svn commit: r1844401 - /httpd/httpd/trunk/docs/manual/mod/mod_headers.xml

[el...@apache.org]

Author: elukey
Date: Sat Oct 20 09:21:47 2018
New Revision: 1844401

URL: http://svn.apache.org/viewvc?rev=1844401&view=rev
Log:
mod_headers.xml: clarify the difference between
                 onsuccess vs always

In PR 62380 a user was confused why Header set always
was not overriding a header set by a HTTP backend managed
via mod_proxy_http. The difference between 'onsuccess'
and 'always' is really subtle, even if somebody is familiar
with r->headers_out and r->err_headers_out and the httpd's
internals.

As Stefan mentioned over email, the absence of a "normalized"
headers list in the response should be explained, so I tried to
do so in this commit.




Modified:
    httpd/httpd/trunk/docs/manual/mod/mod_headers.xml

Modified: httpd/httpd/trunk/docs/manual/mod/mod_headers.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/mod/mod_headers.xml?rev=1844401&r1=1844400&r2=1844401&view=diff
==============================================================================
--- httpd/httpd/trunk/docs/manual/mod/mod_headers.xml (original)
+++ httpd/httpd/trunk/docs/manual/mod/mod_headers.xml Sat Oct 20 09:21:47 2018
@@ -328,16 +328,12 @@ available in 2.4.10 and later</compatibi
     modified.</p>
 
     <p> The optional <var>condition</var> argument determines which internal
-    table of responses headers this directive will operate against. Despite the
-    name, the default value of <code>onsuccess</code> does <em>not</em> limit
-    an <var>action</var> to responses with a 2xx status code.  Headers set under
-    this condition are still used when, for example, a request is <em>successfully</em>
-    proxied or generated by CGI, even when they have generated a failing status code.</p>
-
-    <p>When your action is a function of an existing header, you may need to specify
-    a condition of <code>always</code>, depending on which internal table the
-    original header was set in.  The table that corresponds to <code>always</code> is
-    used for locally generated error responses as well as successful responses.
+    table of responses headers this directive will operate against:
+    <code>onsuccess</code> (default, can be omitted) or <code>always</code>.
+    The difference between the two lists is that the headers contained in the
+    latter are added to the response even on error, and persisted across
+    internal redirects (for example, ErrorDocument handlers).
+
     Note also that repeating this directive with both conditions makes sense in
     some scenarios because <code>always</code> is not a superset of
     <code>onsuccess</code> with respect to existing headers:</p>
@@ -346,14 +342,42 @@ available in 2.4.10 and later</compatibi
        <li> You're adding a header to a locally generated non-success (non-2xx) response, such
             as a redirect, in which case only the table corresponding to
             <code>always</code> is used in the ultimate response.</li>
-       <li> You're modifying or removing a header generated by a CGI script,
-            in which case the CGI scripts are in the table corresponding to
+       <li> You're modifying or removing a header generated by a CGI script
+            or by <module>mod_proxy_fcgi</module>,
+            in which case the CGI scripts' headers are in the table corresponding to
             <code>always</code> and not in the default table.</li>
        <li> You're modifying or removing a header generated by some piece of
             the server but that header is not being found by the default
             <code>onsuccess</code> condition.</li>
     </ul>
 
+    <p>This difference between <code>onsuccess</code> and <code>always</code> is
+    a feature that resulted as a consequence of how httpd internally stores
+    headers for a HTTP response, since it does not offer any "normalized" single
+    list of headers. The main problem that can arise if the following concept
+    is not kept in mind while writing the configuration is that some HTTP responses
+    might end up with the same header duplicated (confusing users or sometimes even
+    HTTP clients). For example, suppose that you have a simple PHP proxy setup with
+    <module>mod_proxy_fcgi</module> and your backend PHP scripts adds the
+    <code>X-Foo: bar</code> header to each HTTP response. As described above,
+    <module>mod_proxy_fcgi</module> uses the <code>always</code> table to store
+    headers, so a configuration like the following ends up in the wrong result, namely
+    having the header duplicated with both values:</p>
+
+    <highlight language="config">
+# X-Foo's value is set in the 'onsuccess' headers table
+Header set X-Foo: baz
+    </highlight>    
+
+    <p>To circumvent this limitation, there are some known configuration
+    patterns that can help, like the following:</p>
+
+        <highlight language="config">
+# 'onsuccess' can be omitted since it is the default
+Header onsuccess unset X-Foo
+Header always set X-Foo "baz"
+        </highlight>
+
     <p>Separately from the <var>condition</var> parameter described above, you
     can limit an action based on HTTP status codes for e.g. proxied or CGI
     requests. See the example that uses %{REQUEST_STATUS} in the section above.</p>
@@ -362,6 +386,14 @@ available in 2.4.10 and later</compatibi
     argument (second argument if a <var>condition</var> is specified).
     This can be one of the following values:</p>
 
+    <note type="warning"><title>Warning</title>
+        <p>Please read the difference between <code>always</code>
+        and <code>onsuccess</code> headers list described above
+        before start reading the actions list, since that important
+        concept still applies. Each action, in fact, works as described
+        but only on the target headers list.</p>
+    </note>
+
     <dl>
     <dt><code>add</code></dt>
     <dd>The response header is added to the existing set of headers,