This stage of the helper reply protocol adds kv-pair support to the
url_rewrite_helper interfacefor URL redirect and rewrite operations.
It uses the new Notes objects and kv-pair field added by the stage 2
helper protocol instead of parsing the 'other' field. Although,
the 'other' field is still parsed when *no* result field is received
for backward compatibility with older helpers.
The response syntax for URL helpers becomes:
[channel-ID SP] result [SP kv-pair ...] [SP other] EOL
NP: 'other' field is now deprecated and will be ignored/discarded on any
response containing a result code field.
When result code "OK" is presented by the helper several kv-pairs are
reserved to control Squid actions:
* "rewrite-url=" is added to return a re-written URL.
- When this key is presented the URL is re-written to the new one by
Squid without client interaction.
- The 'url' keys presence will override this key.
* "url=" is added to return the redirected-to URL.
- When this key name is presented an HTTP redirect response is generated
for the client.
- This keys presence overrides the 'rewrite-url' key actions.
* "status=" is added to hold the HTTP status code for use in redirect
operations.
- This field is optional and status is no longer required for marking
redirect actions.
- If no redirect status is provided Squid will assign one (currently the
default is 302, that may change in the future).
- This key is only relevant when 'url' key is also presented. In all
other uses it is currently ignored.
When result codes BH or ERR are presented by the helper no redirect or
rewrite action is performed and no kv-pair key names are reserved for use
at this time.
Any other keys MAY be sent on any response. The URL helper interface
makes no other use of them, but this patch does pass them on to the ALE
object for logging as transaction Notes. All kv-pairs returned by the
helper (including the url, stauts rewrite-url keys) are available for
logging via the %{...}note log format option.
As with changes to other helpers interfaces in earlier updates, only
the first value presented for any of the reserved kv-pairs is used.
Multiple values are accepted as notes, but otherwise ignored by Squid and
do not affect the transaction outcome.
Additionally, when the BH result code is received from the helper a
simple recovery is attempted. The lookup request will be re-scheduled (up
to once) in an attempt to find a better responding helper.
NOTE: Helper notes are *not* passed to adaptation interfaces.
- REQMOD adaptation happens before URL helpers are used.
- REPMOD adaptation may at some point receive them, but that change is
not done by this update.
This update was sponsored by Edgewave.