NOTE: This plugin is deprecated as of ATS v7.x. Instead, look at the new
``collapsed_forwardin'' plugin instead!


ATS (Apache Traffic Server) Collapsed Connection Handling Plugin
------------------------------------------------------------------------------

This plugin collapses connections with identical CacheUrl/EffectiveUrl.

If an entry was created for a given CacheUrl/EffectiveUrl in our global hashTable,
successive GET requests with identical CacheUrl/EffectiveUrl will be blocked in 
POST_REMAP hook until the hash entry was removed.  (POST_REMAP hook is the last 
hook before 'cache lookup')

For requests going into 'cache lookup' stage,
  if CacheLookupStatus is HIT_FRESH,
    hash entry will be removed at earliest possible time.

For requests going into 'read server response header' stage,
  if response is not 200 OK,
    hash entry will be removed at earliest possible time.
  if response is public cacheable, (by checking 'Expires' header and 'Cache-Control' header with 'public' & 'max-age=...' values),
    if proxy.config.cache.enable_read_while_writer is enabled,
      hash entry will be removed at earliest possible time.
    else
      hash entry will be removed in TXN_CLOSE hook. 
  if response is not public cacheable,
    we will update hash entry with a special value to let successive requests pass collapsed check,
    this special hash entry will be removed in TXN_CLOSE hook if value of keep_pass_record_time is 0,
    else it will be added into a list with timeout and removed by later collapsed requests.

To view full state diagram, please view state.png


CONFIGURATION

To have trafficserver use this plugin, add a line for 'collapsed_connection.so' in the 'plugin.config' file.
The plugin can be configured with only 1 argument, which is location of its configuration file.

Example plugin.config:
    collapsed_connection.so conf/collapsed_connection/check_X_CC_header.config

This plugin can be added in remap.config as well.
Thus, it can have different configurations or only be enabled/disabled for specific remap rules.
If the only argument for this plugin is "0" or "1", it means just "disable" or "enable" this plugin with default config value.

Example remap.config:
    map http://no-collapse1.www.example.com/ http://www.example.com/ @plugin=connection_collapsing.so @pparam=0
    map http://no-collapse2.www.example.com/ http://www.example.com/ @plugin=connection_collapsing.so @pparam=conf/collapsed_connection/disable.config

Its configuration file can have 5 configurable options:
    CONFIG proxy.config.http.collapsed_connection.enabled INT 1
    CONFIG proxy.config.http.collapsed_connection.required_header STRING NULL
    CONFIG proxy.config.http.collapsed_connection.insert_lock_retry_time INT 10
    CONFIG proxy.config.http.collapsed_connection.max_lock_retry_timeout INT 2000
    CONFIG proxy.config.http.collapsed_connection.keep_pass_record_time INT 5000

Meaning of these configurable options:
    enabled
        enable collapsing or not, useful in remap rules if we want to disable/enable specific remap rules.
    required_header
        only collapse requests with 'required_header' http header present.
    insert_lock_retry_time
        if hash entry was locked, retry to get lock after insert_lock_retry_time millisecond.
    max_lock_retry_timeout
        if request was unable to get lock more than max_lock_retry_timeout millisecond, it will be unblocked anyway.
    keep_pass_record_time
        if response is not public cacheable,
        the pass sentinel will be kept in hash table for at least keep_pass_record_time millisecond before be removed.


3rd party open source code
----------------------------------------------------------------------------------
MurmurHash3 by Austin Appleby, https://code.google.com/p/smhasher/wiki/MurmurHash3
   * Calculate hash key for CacheUrl
