Release Notes: initial details for Store-ID and Annotations

diff --git a/doc/release-notes/release-3.4.sgml b/doc/release-notes/release-3.4.sgml
index 2c48e82490d031bf3848a304c2cf0f59799d742a..bc464dbdbf8cfe2f11f845fe0b6e55af590c6932 100644 (file)
--- a/doc/release-notes/release-3.4.sgml
+++ b/doc/release-notes/release-3.4.sgml
@@ -40,7 +40,9 @@ The 3.4 change history can be <url url="http://www.squid-cache.org/Versions/v3/3
 <itemize>
        <item>Helper protocol extensions
        <item>SSL Server Certificate Validator
+       <item>Store-ID
        <item>TPROXY Support for OpenBSD 5.1+ and FreeBSD 9+
+       <item>Transaction Annotations
 </itemize>
 
 Most user-facing changes are reflected in squid.conf (see below).
@@ -94,6 +96,31 @@ Most user-facing changes are reflected in squid.conf (see below).
    <em>ssl_crtd</em> related options. 
 
 
+<sect1>Store-ID
+<p>Details at <url url="http://wiki.squid-cache.org/Features/StoreID">.
+
+<p>This feature is a redesigned equivalent to the Squid-2.7 feature known as StoreURL-rewrite.
+
+<p><em>Notice</em> that this is not a direct portage of the Squid-2.7 feature so behaviour
+  differences do exist. Although the new feature works in similar enough ways that the old
+  helper scripts used for Squid-2.7 are expected to work in this and later versions of Squid.
+
+<p>Squid traditionally uses the requested URL as an index key ID to locate objects in cache.
+   It is not the only key possible and the Store-ID feature exposes an API for external
+   helpers to provide Squid with an alternative key name for any URL.
+
+<p>When any client request is received which requires a cache lookup the URL is passed to
+   a helper specified with the <em>store_id_rewrite_program</em> directive to check for
+   an alternative Store ID. This allows the helper to identify URLs which refer to duplicate
+   resources and de-duplicate the cache content. <em>store_id_access</em> is provided to
+   allow ACL-based tuning of which traffic gets sent to the helper and reduce overheads.
+
+<p>Once subtle and noteworthy difference between Squid-2 and Squid-3 which is highlighted by
+   this feature is that <em>refresh_pattern</em> applies its regex argument against the Store
+   ID key and not the transaction URL. So using the Store-ID feature to alter the value
+   affects which <em>refresh_pattern</em> directive will be matched.
+
+
 <sect1>TPROXY Support for OpenBSD 5.1+ and FreeBSD 9+
 <p>Details at <url url="http://wiki.squid-cache.org/ConfigExamples/Intercept/OpenBsdPf">.
 
@@ -114,6 +141,34 @@ Most user-facing changes are reflected in squid.conf (see below).
    which do not yet support the getsockname() API.
    These systems require <em>--with-nat-devpf</em> to enable /dev/pf support when using PF firewall.
 
+<sect1>Transaction Annotations
+<p>Previously the only annotation methods available were ICAP/eCAP HTTP header insertions
+   or external ACL <em>tag=</em> result code. Each of which had only limited possibilities
+   for use and little or no correlation.
+
+<p>It is now possible to add annotations to a client transaction from several sources:
+<itemize>
+       <item>  Directly from squid.conf using the <em>note</em> directive with
+               ACL-based selection of which annotation is linked to any
+               particular transaction.
+
+       <item>  By configured helper processes returning a key=value pair.
+               The key name becomes the annotation name.
+</itemize>
+
+<p>Annotations on the transaction can be passed to ICAP services or eCAP modules using the
+   <em>adaptation_meta</em> directive to send them as headers.
+   They can also be logged using the <em>%note</em> log format code in custom logs. With
+   the new helper response syntax changes this means all helper response key=value details
+   such as URL-rewrite or store-id changes, external ACL tag etc. are now able to be logged.
+
+<p>Annotations which are already assigned to a transaction can be checked using an ACL test
+   of the new <em>note</em> ACL type. This can match a particular note by name and value,
+   of for any notes with a given name.
+
+<p>NOTE: not all helper interfaces are yet enabled to convert key=value into annotations
+        and the external ACL interface does not yet send annotations to the helper.
+
 
 <sect>Changes to squid.conf since Squid-3.3
 <p>
@@ -150,9 +205,24 @@ This section gives a thorough account of those changes in three categories:
 <sect1>Changes to existing tags<label id="modifiedtags">
 <p>
 <descrip>
+       <tag>access_log</tag>
+       <p>Configuration syntax extended to support name=value options.
+         <em>New Syntax:</em> access_log module:place [option ...] [acl ...]
+       <p>New option <em>logformat=</em> to specify the logging format name.
+       <p>New option <em>buffer-size=</em> to specify how large the log buffer
+          for this log is to be when <em>buffered_logs</em> is enabled.
+       <p>New option <em>on-error=</em> to specify what handling is to be done
+          if the logging module encounters a non-recoverable error writing logs.
+          With the value <em>die</em> (the default) Squid halts operation.
+          With the value <em>drop</em> Squid drops log lines and continue running.
+
        <tag>acl</tag>
        <p>New test type <em>server_cert_fingerprint</em> to match against 
           server SSL certificate fingerprint.
+       <p>New test type <em>note</em> to match against transaction annotations
+          by name and value, or just by name.
+       <p>New test type <em>any-of</em> to match if any one of a set of named ACLs.
+       <p>New test type <em>all-of</em> to match against all of a set of named ACLs.
 
        <tag>auth_param</tag>
        <p>New result code <em>BH</em> to signal helper internal errors