plugins/esi/README.combo

Combohandler
--------------------

NOTE:  THIS FILE IS OBSOLETE, SEE THE TRAFFICSERVER ADMIN GUIDE.

This plugin provides that functionality (and more) with the same
interface but with these differences in configuration:

The arguments in the plugin.config line in order represent

1) The path that should triggers combo handler (defaults to
   "admin/v1/combo")

2) The name of the key used for signature verification (disabled
   by default) [verification not implemented yet]

3) A colon separated list of headers which, if present on at least one
   response, will be added to the combo response.

A "-" can be supplied as a value for any of these arguments to request
default value be applied.

Optional arguments:

  --max-files N

    If present in the plugin.config args, this sets the maximum number of
    files to process in a request to N. This cannot be changed per remap.

Also, just like the original combohandler, this plugin generates URLs
of the form 'http://localhost/<dir>/<file-path>'. <dir> here defaults
to "Host" header unless specified by the file path in the query parameter using
a colon. For example:

http://combo.com/admin/v1/combo?filepath1&dir1:filepath2&filepath3

Will result in these three pages being fetched:

http://localhost/combo.com/filepath1
http://localhost/dir1/filepath2
http://localhost/combo.com/filepath3

Remap rules have to be specified to map the above URLs to desired
content servers.

From 1.1.0, the plugin also supports a prefix parameter. Common parts
of successive file paths can be extracted and specified separately
using a 'p' query parameter. Successive file path parameters are
appended to this prefix to create complete file paths. The prefix will
remain active until changed or cleared (set to an empty string). For
example, the query

"/file1&p=/path1/&file2&file3&p=&/file4&p=/dir:path2/&file5&file6"

results in these file paths being "reconstructed":

/file1
/path1/file2
/path1/file3
/file4
/dir:path2/file5
/dir:path2/file6

Caching
-------
Combohandler follows a few rules for the "Cache-Control" header:

1) All requested documents must have "immutable" for the combo'd
   response to also have "immutable".

2) If one or more requested documents has "private" set, then the combo'd
   response will also have "private". If no requested documents have a
   publicity setting, then the default is "public".

3) The "max-age" value will be set to the smallest of all the requested "max-age"
   values. If no documents has "max-age" set, then the default is 10 years.

Config sample
------
 [plugin.config]
  combo_handler.so admin/v1/combo

 [remap.config]
  map http://combo.com           http://os.combo.com  @plugin=combo_handler.so
  map http://localhost/combo.com http://os.combo.com
  map http://localhost/dir1      http://os1.combo.com

  (note that if pristine_host_hdr is enabled in records.config, the Host header
   of request to your combo origin server is 'localhost')

Version 1.2.0
- ported to ATS-3.3.3
- per-map enabled (disabled for all map by default)
- use full Host header as default bucket
- limit sub-file's max count(30) and querystring's max length(3000)

Version 1.1.2
- Use the Bucket visited(instead of 'l' as the default) as the nickname if nickname is not passed.

Version 1.1.1
-------------
- Using yts_http_fetcher_impl package instead of yts_esi_lib

Version 1.1.0
-------------
- Support for 'p=' prefix parameters

Version 1.0.4
-------------
- Checking vconn before closing (triggered on cache hits)

Version 1.0.3
-------------
- Defaulting to '/l' as the path if no colon prefix path
  is specified

Version 1.0.2
-------------
- Using localhost as content server (relying on remap rules)
  and generalizing the colon prefix paths

Version 1.0.1
-------------
- Using d.yimg.com for "d:" prefixed file paths

Version 1.0.0
-------------
- Initial version