Add docs and examples for req-disposition.

Closes #24

docs/ref-match-flags.md

+# ``match-flags`` -- configuring match operations
+
+This is the authoritative reference for the ``match-flags`` field,
+which is used in a number of places in the custom resource
+configurations where string comparisons are specified. For example in
+the [``rewrites`` configuration](/docs/ref-varnish-cfg.md) for header
+and URL rewriting, and in the [``req-disposition``
+configuration](/docs/ref-req-disposition.md) to specify the
+disposition of client requests.
+
+Three types of string comparison are used by this Ingress
+implementation:
+
+* regular expression matching: strings are matched against patterns
+  with the syntax and semantics of [RE2 regular
+  expressions](https://github.com/google/re2/wiki/Syntax)
+
+* fixed string matches: strings are tested for equality with literal
+  string values. Characters such as wildcards or regular expression
+  metacharacters have no special meaning.
+
+* prefix matches: strings are tested as to whether they begin with any
+  one of a set of strings. These are also literal matches against the
+  prefixes, in the sense that no character in the prefix has a special
+  meaning.
+
+The string comparisons are typically configured for an array of
+possible string values. The comparisons are evaluated as true if they
+are true for any one of the strings in the array. In other words, the
+string array represents a boolean OR of comparisons.
+
+The ``match-flags`` object is used to configure and control the
+comparison operations. ``match-flags`` is optional in every context in
+which it may be specified -- if it is left out, then comparisons are
+executed with default options.
+
+Only the ``case-sensitive`` field may be set for fixed string and
+prefix matches, typically configured with the string enum values
+``equal`` and ``prefix``, respectively.  All of the other fields are
+permitted only for regular expression matches, typically configured as
+``match``. In other words, case insensitivity can be specified for all
+comparison operations, but the other fields apply only to regex
+matching.
+
+The ``match-flag`` fields are adapted from the
+[RE2](https://github.com/google/re2/) library (via [VMOD
+re2](https://code.uplex.de/uplex-varnish/libvmod-re2)).  The fields
+are:
+
+* ``case-sensitive`` (default ``true``): if ``false``, then
+  comparisons (regex, fixed string or prefix) are case insensitive.
+
+* ``anchor`` (default ``none``): sets anchoring at start-of-string or
+  end-of-string for every pattern to be matched; equivalent to using
+  the ``^`` and ``$`` for start- and end-of-string in the notation for
+  each pattern. Possible values are:
+
+    * ``start``: each pattern is anchored at the start
+
+    * ``both``: each pattern is anchored at both start and end.
+
+    * ``none`` (default): no implicit anchoring (but ``^`` and/or
+      ``$`` may be used in individual patterns)
+
+* ``literal`` (default ``false``): if ``true``, then the strings to to
+  be matched are matched literally, with no special meaning for regex
+  metacharacters (despite the use of regex matching).
+
+* ``never-capture`` (default ``false``): if ``true``, then substring
+  capturing is not executed for regex matches. Capturing
+  backreferences is necessary for some applications, such as header
+  and URL rewrites.  But consider setting ``never-capture`` to
+  ``true`` if your patterns have round parentheses ``()`` for grouping
+  only, and backreferences are not needed, since regex matches are
+  faster without the captures.
+
+* ``utf8`` (default ``false``): if ``true``, then characters in each
+  pattern match UTF8 code points; otherwise, the patterns and the
+  strings to be matched are interpreted as Latin-1 (ISO-8859-1). Note
+  that characters in header values and URL paths almost always fall in
+  the ASCII range, so the default is usually sufficient. Note also that
+  this differs from the default in the RE2 library.
+
+* ``longest-match`` (default ``false``): if ``true``, then the matcher
+  searches for the longest possible match where alternatives are
+  possible. For example with the pattern ``a(b|bb)`` and the string
+  ``abb``, ``abb`` matches when ``longest-match`` is ``true``, and
+  backref 1 is ``bb``. Otherwise, ``ab`` matches, and backref 1 is
+  ``b``.
+
+* ``posix-syntax`` (default ``false``): if ``true``, then patterns are
+  restricted to POSIX (egrep) syntax. Otherwise, the full range of
+  [RE2](https://github.com/google/re2/wiki/Syntax) is available.
+
+    The next two flags (``perl-classes`` and ``word-boundary``) are
+    only consulted when ``posix-syntax`` is ``true``.
+
+* ``perl-classes`` (default ``false``): if ``true`` and
+  ``posix-syntax`` is also ``true``, then the perl character classes
+  ``\d``, ``\s``, ``\w``, ``\D``, ``\S`` and ``\W`` are permitted in a
+  pattern. When ``posix-syntax`` is ``false``, the perl classes are
+  always permitted.
+
+* ``word-boundary`` (default ``false``): if ``true`` and
+  ``posix-syntax`` is also ``true``, then the perl assertions ``\b``
+  and ``\B`` (word boundary and not a word boundary) are permitted in
+  a pattern. When ``posix-syntax`` is ``false``, the word boundary
+  assertions are always permitted.
+
+* ``max-mem`` (integer, default 8MB): an upper bound (in bytes) for
+  the size of the compiled pattern. If ``max-mem`` is too small, the
+  matcher may fall back to less efficient algorithms, or the pattern
+  may fail to compile.
+
+    This field very rarely needs to be set; the default is the RE2
+    default, and is sufficient for typical patterns. Increasing
+    ``max-mem`` is usually only necessary if VCL loads fail due to
+    failed regex compiles, and the error message (shown in Event
+    notifications and the controller log) indicates that the pattern
+    is too large.
+
+See the [``examples/``](/examples/) folder, particular the examples
+for [rewriting](/examples/rewrite) and [client request
+disposition](/examples/req-disposition/), for working examples in
+which the ``match-flags`` object is used.

docs/ref-req-disposition.md

+# ``req-disposition`` -- disposition of client requests
+
+This is the authoritative reference for the ``spec.req-disposition``
+field of the [``VarnishConfig`` Custom
+Resource](/docs/ref-varnish-cfg.md), which defines how client requests
+are processed further after the request headers have been received.
+
+The configuration in ``req-disposition`` causes the definition of [VCL
+subroutine
+``vcl_recv``](https://varnish-cache.org/docs/6.1/users-guide/vcl-built-in-subs.html#vcl-recv)
+in
+[``builtin.vcl``](https://github.com/varnishcache/varnish-cache/blob/6.1/bin/varnishd/builtin.vcl)
+to be overridden. ``builtin.vcl`` acts as "default VCL"; after a
+subroutine in the VCL generated by the controller has been executed,
+if it does not use ``return`` to branch to another [processing
+state](https://varnish-cache.org/docs/6.1/reference/states.html), then
+the subroutine in ``builtin.vcl`` is executed. Built-in ``vcl_recv``
+establishes default policies for client requests such as:
+
+* which requests proceed to cache lookup, and hence may potentially be
+  cache hits.
+
+* which requests bypass cache lookup, and hence are never cache hits
+  (and avoid the effects of [request
+  coalescing](https://varnish-cache.org/docs/6.1/users-guide/increasing-your-hitrate.html#cache-misses)).
+
+* how to handle requests with non-standard request methods.
+
+A common use case for overriding built-in ``vcl_recv`` is to allow
+caching for requests that use cookies or basic authentication. The
+default policy in ``builtin.vcl`` takes a cautious approach by
+bypassing cache lookup for such requests, since their responses may be
+personalized. But especially since cookies are ubiquitous, it is often
+necessary to override the default.
+
+Note that if you override any part of built-in ``vcl_recv`` -- that is
+if you configure ``req-disposition`` at all -- you must override all
+of it. That is, you will have to consider policies for everything that
+builtin-in ``vcl_recv`` implements in your configuration for
+``req-disposition``, because no part of built-in ``vcl_recv`` will be
+executed. You can, of course, make decisions that differ from those in
+built-in ``vcl_recv``.
+
+See the [``examples/`` folder](/examples/req-disposition) for working
+examples of configurations for ``req-disposition``. Among these are:
+
+* A reconstruction in YAML for everything that built-in ``vcl_recv``
+  does, to illustrate how the same policies can be configured for
+  Kubernetes.
+
+* An alternative configuration for built-in ``vcl_recv``, to allow
+  cache lookup for requests using cookies or basic authentication,
+  and to make different decisions about some other policies.
+
+* Bypassing cache lookup when the Cookie header contains a session
+  token, but otherwise allowing cache lookup for requests with
+  cookies.
+
+* Bypassing cache lookup for certain URL path patterns, and explicitly
+  invoking cache lookup for other URL patterns.
+
+* URL white- and blacklisting -- immediately rejecting requests whose
+  URL path does or does not match groups of patterns.
+
+## Configuration
+
+The configuration in ``req-disposition`` determines the next
+[state](https://varnish-cache.org/docs/6.1/reference/states.html) in
+the processing of a client request. The implementation of
+``req-disposition`` is executed after everything else that runs in
+``vcl_recv``, and bypasses built-in ``vcl_recv`` as discussed above.
+
+``req-disposition`` is a non-empty array of objects with these two
+fields, both of which are required:
+
+* ``conditions``: a set of conditions against which a client request
+  is matched
+
+* ``disposition``: the next processing state for a client request
+  that matches the ``conditions``
+
+The ``conditions`` are evaluated for a client request in the order in
+which they appear in the array. For the first object whose ``conditions``
+match the client request, the request is processed further according to
+the corresponding ``disposition``. If none of the ``conditions`` match,
+then the request proceeds to cache lookup (``return(hash)``).
+
+``disposition`` is an object with these two fields:
+
+* ``action`` (required): one of the following strings, corresponnding
+  to a [``return()`` keyword for
+  ``vcl_recv``](https://varnish-cache.org/docs/6.1/users-guide/vcl-built-in-subs.html#vcl-recv);
+
+    * ``hash``: cache lookup
+
+    * ``pass``: bypass cache lookup
+
+    * ``synth``: return a synthetic response
+
+    * ``pipe``: Varnish acts as a
+      [tunnel](https://varnish-cache.org/docs/6.1/users-guide/vcl-built-in-subs.html#vcl-pipe)
+      between client and backend
+
+    * ``restart``:
+      [restart](https://varnish-cache.org/docs/6.1/users-guide/vcl-built-in-subs.html#restart)
+      request processing
+
+    * ``purge``: evict the cache object that corresponds to the
+      request
+
+    * ``fail``: invoke [VCL
+      failure](https://varnish-cache.org/docs/6.1/users-guide/vcl-built-in-subs.html#fail)
+
+* ``status``: the HTTP status of the synthetic response when
+  ``action`` is ``synth``. Required for ``synth``, and ignored for
+  other values of ``action``. ``status`` MUST be in the range 200 to
+  599, inclusive.
+
+It is not possible to use ``action`` to specify branching to a VCL label.
+
+``conditions`` is an array of objects with the following fields,
+describing all of the conditions that a client request that must
+fulfill to invoke the corresponding ``disposition``:
+
+* ``comparand`` (required): the "thing to be compared" -- one of the
+  following
+  (cf. [vcl(7)](https://varnish-cache.org/docs/6.1/reference/vcl.html#req-and-req-top)):
+
+    * ``req.url``: URL path
+
+    * ``req.http.$HEADER``. where ``$HEADER`` is a client request
+      header.  For example, ``req.http.Cookie`` specifies the Cookie
+      header.
+
+    * ``req.method``: request method
+
+    * ``req.proto``: HTTP protocol (such as "HTTP/1.1" or "HTTP/2")
+
+    * ``req.esi_level``: the current depth of ESI
+      includes. ``req.esi_level`` is 0 for requests that are not
+      included.
+
+    * ``req.restarts``: the number of times the request has been
+      restarted.  ``req.restarts`` is 0 if the request has not been
+      restarted.
+
+* ``compare``: the operation by which the ``comparand`` is evaluated,
+  possibly in relation to the strings in the ``values`` field, or the
+  number in the ``count`` field, as documented further down. One of:
+
+    * ``equal`` (default), ``not-equal``: test for equality or
+      inequality with ``values`` or ``count``.
+
+    * ``match``, ``not-match``: test if the ``comparand`` does or does
+      not match any of the regular expressions in ``values``.
+
+    * ``prefix``, ``not-prefix``: test if the ``comparand`` does or
+      does not have a prefix that is specified in the ``values``
+      array.
+
+    * ``exists``, ``not-exists``: test if the header specified in the
+      ``comparand`` as ``req.http.$HEADER`` is or is not present in
+      the client request.
+
+    * ``greater``, ``greater-equal``, ``less``, ``less-equal``: test
+      the ``comparand`` against ``count`` with the numeric
+      relation >, >=, < or <=, respectively.
+
+    * When ``compare`` is ``exists`` or ``not-exists``, the
+      ``comparand`` MUST be of the form ``req.http.$HEADER`` to
+      specify a client request header. The ``values`` and ``count``
+      fields are ignored.
+
+    * When ``compare`` is any of ``match``, ``not-match``, ``prefix``
+      or ``not-prefix``:
+
+        * the ``values`` array MUST be specified.
+
+        * the ``count`` field MAY NOT be specified.
+
+        * ``comparand`` MUST be one of ``req.url``,
+          ``req.http.$HEADER``, ``req.method`` or ``req.proto``. In
+          other words, the ``comparand`` MUST designate a string
+          value.
+    
+    * When ``compare`` is any of ``greater``, ``greater-equal``,
+      ``less`` or ``less-equal``:
+
+        * the ``count`` field MUST be specified.
+
+        * the ``values`` array MAY NOT be specified.
+
+        * ``comparand`` MUST be one of ``req.esi_level`` or
+          ``req.restarts``.  That is, the ``comparand`` MUST designate
+          a numeric value.
+    
+* ``values``: if present, a non-empty array of strings to which the
+  ``comparand`` is compared, according to the relation specified by
+  ``compare``. If ``values`` is specified, then:
+
+    * ``count`` MAY NOT be specified.
+
+    * ``compare`` MUST be one of ``equal``, ``not-equal``, ``match``,
+      ``not-match``, ``prefix`` or ``not-prefix``.
+
+    * ``comparand`` MUST be one of ``req.url``, ``req.http.$HEADER``,
+      ``req.method`` or ``req.proto``.
+
+    * When ``compare`` is ``match`` or ``not-match``, the strings in
+      ``values`` have the syntax and semantics of [RE2 regular
+      expressions](https://github.com/google/re2).
+
+    * When ``compare`` is ``equal``, ``not-equal``, ``prefix`` or
+      ``not-prefix`` the strings in ``values`` are fixed strings or
+      prefixes. Characters such as regular expression metacharacters
+      or wildcards have no special meaning.
+
+* ``count``: if present, a number to which the ``comparand`` is
+  compared according to ``compare``. If ``count`` is specfied:
+
+    * ``values`` MAY NOT be specified.
+
+    * ``compare`` MUST be one of ``equal``, ``not-equal``,
+      ``greater``, ``greater-equal``, ``less`` or ``less-equal``.
+
+    * ``comparand`` MUST be one of ``req.esi_level`` or
+      ``req.restarts``.
+
+* ``match-flags``: if present, an object with configuration to
+  control string comparison operations. If ``match-flags`` is absent,
+  then comparisons are executed with default options. See the
+  [``match-flags`` specification](/docs/ref-match-flags.md) for
+  details. ``match-flags`` is ignored for numeric comparisons
+  (when ``count`` is specified).
+
+When more than one string is specified in ``values``, the condition
+evaluates as true if the ``compare`` relation with ``comparand`` holds
+for any one of the strings. In other words, the array represents a
+boolean OR of comparisons. For example, this condition evaluates as
+true if the client request header ``Foo`` has either of the values
+``bar`` or ``baz``:
+
+```
+  - comparand: req.http.Foo
+    compare: equal
+    values:
+      - bar
+      - baz
+```
+
+The complete set of ``conditions`` is evaluated as true, and hence the
+corresponding ``disposition`` is invoked, if each condition in the
+array evaluates as true. In other words, the ``conditions`` array
+represents a boolean AND of conditions.
+
+## Example
+
+This configuration reconstructs one of the rules in built-in
+``vcl_recv`` as a ``req-disposition`` configuration -- a client
+request is rejected as an error if it does not have a ``Host`` header,
+when HTTP/1.1 is in use (since the HTTP standard requires it):
+
+```
+spec:
+  req-disposition:
+    - conditions:
+      - comparand: req.http.Host
+        compare: not-exists
+      - comparand: req.esi_level
+        count: 0
+      - comparand: req.proto
+        compare: prefix
+        values:
+          - HTTP/1.1
+        match-flags:
+          case-insensitive: true
+      disposition:
+        action: synth
+        status: 400
+```
+
+The conditions in the ``conditions`` array specify a client request for which
+all of the following are true:
+
+* The ``Host`` header is not present in the request (``not-exists``).
+
+* The request is not ESI-included -- ``req.esi_level`` == 0. We do not
+  require this check for ESI-included requests. Notice that the
+  ``compare`` field was left out, so the default comparison ``equals``
+  is assumed.
+
+* The protocol is specified as HTTP/1.1. This is considered true if
+  ``req.proto`` begins with `"HTTP/1.1"`` (``compare: prefix``), and
+  the match with the string is case-insensitive.
+
+If all of these conditions are true, then the ``disposition`` is
+executed. In this case, a synthetic "400 Bad Request" response is
+generated.
+
+See the [``examples/`` folder](/examples/req-disposition) for more
+examples of the use of ``req-disposition``.
\ No newline at end of file

docs/ref-varnish-cfg.md

@@ -779,87 +779,10 @@ Elements of the ``rewrites`` array may have these fields, of which
     that a synthetic response with status 503 and the reason "VCL
     failed" is returned for the request.
 
-* ``match-flags`` is an object with configuration to control comparison
-  operations. If ``match-flags`` is absent, then comparisons are executed
-  with default options.
-
-    Only the ``case-sensitive`` field may be set if ``compare`` is
-    ``equal`` or ``prefix``; all of the other fields are permitted
-    only if ``compare`` is ``match``. In other words, case
-    insensitivity can be specified for all comparison operations, but
-    the other fields apply only to regex matching. The fields are:
-
-    * ``case-sensitive`` (default ``true``): if ``false``, then regex
-      and fixed-string comparisons are case insensitive.
-
-    * ``anchor`` (default ``none``): sets anchoring at start-of-string
-      or end-of-string for every pattern in the ``rules`` array;
-      equivalent to using the ``^`` and ``$`` for start- and
-      end-of-string in the notation for each pattern. Possible values
-      are:
-
-        * ``start``: each pattern is anchored at the start
-
-        * ``both``: each pattern is anchored at both start and end.
-
-        * ``none`` (default): no implicit anchoring (but ``^`` and/or
-          ``$`` may be used in individual patterns)
-
-    * ``literal`` (default ``false``): if ``true``, then the strings
-      in the ``value`` fields of the ``rules`` are matched literally,
-      with no special meaning for regex metacharacters.
-
-    * ``never-capture`` (default ``false``): if ``true``, then
-      substring capturing is not executed for regex matches. Consider
-      setting ``never-capture`` to ``true`` if your patterns have
-      round parentheses ``()`` for grouping only, and backreferences
-      are not used in rewrite strings, since regex matches are faster
-      without the captures.
-
-    * ``utf8`` (default ``false``): if ``true``, then characters in
-      each pattern match UTF8 code points; otherwise, the patterns and
-      the strings to be matched are interpreted as Latin-1
-      (ISO-8859-1). Note that characters in header values and URL
-      paths almost always fall in the ASCII range, so the default is
-      usually sufficient.
-
-    * ``longest-match`` (default ``false``): if ``true``, then the
-      matcher searches for the longest possible match where
-      alternatives are possible. For example with the pattern
-      ``a(b|bb)`` and the string ``abb``, ``abb`` matches when
-      ``longest-match`` is ``true``, and backref 1 is
-      ``bb``. Otherwise, ``ab`` matches, and backref 1 is ``b``.
-
-    * ``posix-syntax`` (default ``false``): if ``true``, then patterns
-      are restricted to POSIX (egrep) syntax. Otherwise, the full
-      range of [RE2](https://github.com/google/re2/wiki/Syntax) is
-      available. The next two flags (``perl-classes`` and
-      ``word-boundary``) are only consulted when ``posix-syntax`` is
-      ``true``.
-
-    * ``perl-classes`` (default ``false``): if ``true`` and
-      ``posix-syntax`` is also ``true``, then the perl character
-      classes ``\d``, ``\s``, ``\w``, ``\D``, ``\S`` and ``\W`` are
-      permitted in a pattern. When ``posix-syntax`` is ``false``, the
-      perl classes are always permitted.
-
-    * ``word-boundary`` (default ``false``): if ``true`` and
-      ``posix-syntax`` is also ``true``, then the perl assertions
-      ``\b`` and ``\B`` (word boundary and not a word boundary) are
-      permitted in a pattern. When ``posix-syntax`` is ``false``, the
-      word boundary assertions are always permitted.
-
-    * ``max-mem`` (integer, default 8MB): an upper bound (in bytes)
-      for the size of the compiled pattern. If ``max-mem`` is too
-      small, the matcher may fall back to less efficient algorithms,
-      or the pattern may fail to compile.
-
-        This field very rarely needs to be set; the default is the RE2
-        default, and is sufficient for typical patterns. Increasing
-        ``max-mem`` is usually only necessary if VCL loads fail due to
-        failed regex compiles, and the error message (shown in Event
-        notifications and the controller log) indicates that the
-        pattern is too large.
+* ``match-flags`` is an object with configuration to control
+  comparison operations. If ``match-flags`` is absent, then
+  comparisons are executed with default options. See the
+  [``match-flags`` reference](/docs/ref-match-flags.md) for details.
 
 * ``vcl-sub`` is an enum indicating the
   [VCL subroutine](https://varnish-cache.org/docs/6.1/reference/states.html)
@@ -914,3 +837,11 @@ Elements of the ``rewrites`` array may have these fields, of which
     If more than one rewrite in the ``rewrites`` array specifies the
     same VCL subroutine, then they are executed in that subroutine in
     the order in which they appear in the array.
+
+## ``spec.req-disposition``
+
+The ``req-disposition`` is optional, and if present contains a
+configuration of the disposition of client requests -- how client
+requests are processed further after request headers have been
+received. See the [``req-disposition``
+reference](/docs/ref-req-disposition.md) for details.

examples/README.md

@@ -29,6 +29,19 @@ requirements.
 * Specifying [rewrite rules](/examples/rewrite) for request headers,
   response headers, and URL paths.
 
+* Specifying the [disposition of client requests](/example/req-disposition).
+  This can enable a number of features, such as:
+
+    * allowing caching for requests that use cookies or basic
+      authentication.
+
+    * defining cacheability based on properties of the client request,
+      such as URL path patterns.
+
+    * defining white- and blacklists for requests.
+
+    * defining the means to purge cache entries via a request.
+
 * The [BackendConfig](/examples/backend-config) Custom Resource, to
   configure properties such as timeouts, health probes and
   load-balancing for Services to which requests are routed according

examples/req-disposition/README.md

+# Disposition of client requests
+
+The sample manifests in this folder configures the disposition of
+client requests -- how client requests are further processed after
+request headers have been received. The ``req-disposition`` field of
+the [``VarnishConfig`` custom resource](/docs/ref-varnish-cfg.md)
+determines the next [processing
+state](https://varnish-cache.org/docs/6.1/reference/states.html) for a
+request, subject to properties of the request.  It overrides the
+implementation of ``vcl_recv`` in
+[``builtin.vcl``](https://github.com/varnishcache/varnish-cache/blob/6.1/bin/varnishd/builtin.vcl).
+
+A common use case for ``req-disposition`` is to allow caching for
+requests that use cookies or basic authentication, since the Varnish
+default, implemented in ``builtin.vcl``, is to bypass the cache for
+such requests. The default is the cautious approach, since the
+responses to requests with cookies or basic auth may be
+personalized. You may use ``req-disposition`` to relax the default,
+but make sure that personalized responses are not cached as a result.
+
+A variety of other features can be implemented with
+``req-disposition``, such as:
+
+* specifically invoking cache lookup or bypass based on properites of
+  the client request, such as URL path patterns. In other words,
+  defining cacheability based on properties of the client request.
+
+* white- and blacklisting requests
+
+* defining a means to use the
+  [purge](https://varnish-cache.org/docs/6.1/users-guide/purging.html)
+  facility via client requets, for example by defining a ``PURGE``
+  request method.
+
+Examples for such configurations are discussed below.
+
+See the [docs](/docs/ref-req-disposition.md) for the technical reference
+for the configuration of client request dispositions.
+
+The examples apply to the Ingress and Services defined in the
+["cafe" example](/examples/hello).
+
+## Reconstructing built-in ``vcl_recv`` in YAML
+
+The first example re-implements the implementation of ``vcl_recv`` in
+``builtin.vcl`` as a ``req-disposition`` configuration. Of course it
+doesn't make sense to deploy this configuration unchanged in your
+cluster; since it does exactly what built-in ``vcl_recv`` does, you
+might as well leave it out and let Varnish execute the built-in
+version. But the YAML is presented here as an illustration of the
+configuration, and to show which parts of the default policies you
+might want to change.
+
+Apply the configuration with:
+
+```
+$ kubectl apply -f builtin.yaml
+```
+
+``req-disposition`` is an array of objects with the fields
+``conditions`` and ``disposition``. Each object is evaluated against a
+client request in the order of the array; for the first one for which
+the ``conditions`` evaluate as true, the corresponding ``disposition``
+determines further processing of the request. If none of the
+``conditions`` evaluate as true, the request proceeds to cache lookup.
+
+The first element of ``req-disposition`` says that if the request
+method is ``PRI`` (tested with case-sensitive string equality), then
+send a synthetic response with status ``405 Method Not Allowed``:
+
+```
+    - conditions:
+      - comparand: req.method
+        compare: equal
+        values:
+          - PRI
+      disposition:
+        action: synth
+        status: 405
+```
+
+The ``PRI`` method is part of the HTTP/2 connection preface, see
+[RFC7540](https://tools.ietf.org/html/rfc7540#section-3.5).
+
+The next element enforces the requirement of HTTP/1.1 that the
+``Host`` header must be present in a request:
+
+```
+    - conditions:
+      - comparand: req.http.Host
+        compare: not-exists
+      - comparand: req.esi_level
+        count: 0
+      - comparand: req.proto
+        compare: prefix
+        values:
+          - HTTP/1.1
+        match-flags:
+          case-sensitive: false
+      disposition:
+        action: synth
+        status: 400
+```
+
+These ``conditions`` are true if each of the following are true:
+
+* The ``Host`` header is not present in the request
+  (``compare:not.exists``).
+
+* The request is not ESI-included -- ``req.esi_level`` is 0. Notice
+  that the ``compare`` field is not specified in the second clause, so
+  the default comparison ``equals`` is assumed.
+
+* The protocol begins with the strings ``HTTP/1.1``. The third clause
+  specifies a case-insensitive prefix match.
+
+If all three clauses are true, then the ``disposition`` specifies a
+synthetic response with status ``400 Bad Request`` -- an HTTP/1.1
+request without a ``Host`` header is illegal.
+
+The next element specifies that the request is processed in [pipe
+mode](https://varnish-cache.org/docs/6.1/users-guide/vcl-built-in-subs.html#vcl-pipe)
+for request method ``CONNECT``, or any non-standard request method:
+
+```
+    - conditions:
+      - comparand: req.method
+        compare: not-equal
+        values:
+          - GET
+          - HEAD
+          - PUT
+          - POST
+          - TRACE
+          - OPTIONS
+          - DELETE
+          - PATCH
+      disposition:
+        action: pipe
+```
+
+Tnis configuration uses the ``not-equal`` comparison against an array
+of strings, which evaluates to true if the ``equal`` comparison does
+not evaluate to true against the array. It evaluates to true if the
+request method (``req.method``) is equal to any string in the
+array. If the ``not-equal`` comparison is true (hence the method is
+either ``CONNECT`` or a method not specified by the HTTP standard),
+then the ``disposition`` specifies ``pipe``. In pipe mode, Varnish
+acts as a tunnel between the client and backend. This may be an
+appropriate choice for a WebSockets client, for example.
+
+The next element specifies that cache lookup is bypassed if the
+request method is neither of ``GET`` or ``HEAD`` -- ``POST``
+requests, for example, bypass cache lookup:
+
+```
+    - conditions:
+      - comparand: req.method
+        compare: not-equal
+        values:
+          - GET
+          - HEAD
+      disposition:
+        action: pass
+```
+
+Setting the ``disposition`` to ``pass`` for requests whose responses
+are known to be uncacheable can be advantageous, because potential
+waiting due to [request
+coalescing](https://varnish-cache.org/docs/6.1/users-guide/increasing-your-hitrate.html#passing-client-requests)
+is avoided.
+
+The next two elements are the ones that most commonly require an override
+of the defaults: if a request has a ``Cookie`` or ``Authorization`` header,
+then cache lookup is bypassed:
+
+```
+    - conditions:
+      - comparand: req.http.Cookie
+        compare: exists
+      disposition:
+        action: pass
+
+    - conditions:
+      - comparand: req.http.Authorization
+        compare: exists
+      disposition:
+        action: pass
+```
+
+Both of the ``conditions`` use ``compare:exists``, which is true if
+the header is present in the request. ``exists`` and ``not-exists``
+may only be used when the ``comparand`` specifies a header.
+
+To verify the configuration, as with other examples we use curl with
+the ``-x`` (or ``--proxy``) option set to ``$IP:$PORT``, where ``$IP``
+is the public address of the cluster, and ``$PORT`` is the port at
+which it receives requests that are directed to the Ingress:
+
+```
+# The usual requests routed by the Ingress get the expected responses,
+# as for built-in vcl_recv:
+$ curl -x $IP:$PORT -v http://cafe.example.com/coffee
+[...]
+> GET http://cafe.example.com/coffee HTTP/1.1
+> Host: cafe.example.com
+[...]
+> 
+< HTTP/1.1 200 OK
+[...]
+< 
+[...]
+Server name: coffee-6c47b9cb9c-mrddp
+[...]
+URI: /coffee
+
+$ curl -x $IP:$PORT -v http://cafe.example.com/tea
+[...]
+> GET http://cafe.example.com/tea HTTP/1.1
+> Host: cafe.example.com
+[...]
+> 
+< HTTP/1.1 200 OK
+[...]
+< 
+[...]
+Server name: tea-58d4697745-4vd7g
+[...]
+URI: /tea
+
+$ curl -x $IP:$PORT -v http://cafe.example.com/beer
+[...]
+> GET http://cafe.example.com/beer HTTP/1.1
+> Host: cafe.example.com
+[...]
+> 
+< HTTP/1.1 404 Not Found
+[...]
+
+# Requests using the PRI method get the response 405 Method Not
+# Allowed.
+$ curl -x $IP:$PORT -X PRI -v http://cafe.example.com/coffee
+[...]
+> PRI http://cafe.example.com/coffee HTTP/1.1
+> Host: cafe.example.com
+[...]
+> 
+< HTTP/1.1 405 Method Not Allowed
+[...]
+
+# To construct a request without a Host header using curl, we do
+# not use the -x option, but set -H 'Host:' to remove the header.
+# The response is 400 Bad Request as configured above.
+curl -H 'Host:' -v http://$IP:$PORT/coffee
+$ curl -x $IP:$PORT -v http://cafe.example.com/coffee
+> GET /coffee HTTP/1.1
+> User-Agent: curl/7.52.1
+> Accept: */*
+> 
+< HTTP/1.1 400 Bad Request
+[...]
+
+# To verify the pipe and pass dispositions, we view the Varnish log on
+# one of the Pods on which Varnish is deployed, using kubetcl exec:
+$ kubectl exec -it varnish-98498798b-qp5m6 -- varnishlog -n /var/run/varnish-home
+
+# Requests with the CONNECT method are diverted to pipe mode:
+$ curl -x $IP:$PORT -X CONNECT -v http://cafe.example.com/coffee
+[...]
+> CONNECT http://cafe.example.com/coffee HTTP/1.1
+> Host: cafe.example.com
+[...]
+
+# In the Varnish log:
+*   << Request  >> 32853     
+[...]
+-   ReqMethod      CONNECT
+-   ReqURL         /coffee
+[...]
+-   VCL_call       RECV
+-   VCL_return     pipe
+[...]
+
+# Requests whose method is neither GET nor HEAD are set to pass,
+# bypassing cache lookup:
+$ curl -x $IP:$PORT -X PUT -v http://cafe.example.com/coffee
+[...]
+> PUT http://cafe.example.com/coffee HTTP/1.1
+> Host: cafe.example.com
+[...]
+
+*   << Request  >> 32852     
+[...]
+-   ReqMethod      PUT
+-   ReqURL         /coffee
+[...]
+-   VCL_call       RECV
+-   VCL_return     pass
+[...]
+
+# Requests with either of the Cookie or Authorization headers are set
+# to pass.
+$ curl -x $IP:$PORT -H 'Cookie: foo=bar' -v http://cafe.example.com/coffee
+[...]
+> GET http://cafe.example.com/coffee HTTP/1.1
+> Host: cafe.example.com
+[...]
+> Cookie: foo=bar
+[...]
+
+*   << Request  >> 32879     
+[...]
+-   ReqMethod      GET
+-   ReqURL         /coffee
+[...]
+-   ReqHeader      Cookie: foo=bar
+[...]
+-   VCL_call       RECV
+-   VCL_return     pass
+[...]
+
+```
+
+## An alternative configuration
+
+The next example demonstrates different choices about the disposition of
+client requests. The main differences are:
+
+* Cache lookups are permitted for requests that use cookies or basic
+  authentication.
+
+* Non-standard request methods are handled a bit differently.
+
+Apply the configuration:
+
+```
+$ kubectl apply -f alt-builtin.yaml
+```
+
+Recall that if the ``req-disposition`` configuration is used at all,
+everything in built-in ``vcl_recv`` is overridden; so the
+configuration must include any features we wish to preserve. In
+``alt-builtin.yaml``, two elements are included that are the same as
+in ``builtin.yaml``, and bring about the same logic as in built-in
+``vcl_recv``:
+
+* Requests for the HTTP/1.1 protocol without a ``Host`` header get a
+  synthetic 400 Bad Request response.
+
+* Cache lookup is bypassed for requests whose method is neither of GET
+  or HEAD.
+
+The differences are:
+
+* The stanzas in ``builtin.yaml`` that set the ``disposition`` to
+  ``pass`` when ``Cookie`` or ``Authorization`` headers are present
+  are left out.  Since processing proceeds to cache lookup if none of
+  the ``conditions`` in ``req-disposition`` match the request, caching
+  becomes possible for such requests.
+
+* The only request method that invokes pipe mode is ``CONNECT``. This
+  may be useful if you have client and backend applications that use a
+  technique such as WebSockets, needing the "tunneling" feature of pipe
+  mode.
+
+* For all other non-standard request methods (including ``PRI``), a
+  synthetic 405 Method Not Allowed response is generated.
+
+This stanza invokes pipe mode for request method ``CONNECT``:
+
+```
+    - conditions:
+      - comparand: req.method
+        compare: equal
+        values:
+          - CONNECT
+      disposition:
+        action: pipe
+```
+
+The stanza for handling non-standard request methods is rewritten as:
+
+```
+    - conditions:
+      - comparand: req.method
+        compare: not-equal
+        values:
+          - GET
+          - HEAD
+          - PUT
+          - POST
+          - TRACE
+          - OPTIONS
+          - DELETE
+          - PATCH
+      disposition:
+        action: synth
+        status: 405
+```
+
+If your site does not have any application such WebSockets that
+requires pipe mode, just leave out the stanza concerning ``CONNECT``,
+and include ``CONNECT`` in the array of method names in the second
+stanza.
+
+You may use a configuration like this to limit the permitted request
+methods more narrowly. For example, if none of your backend
+applications support any method besides ``GET``, ``HEAD`` and
+``POST``, then only include those method names in the ``values``
+array.
+
+Verification:
+
+```
+# Cache lookup is permitted for a request with a Cookie header.
+# We verify this by checking the log.
+$ curl -x $IP:$PORT -H 'Cookie: foo=bar' -v http://cafe.example.com/coffee
+[...]
+> GET http://cafe.example.com/coffee HTTP/1.1
+> Host: cafe.example.com
+[...]
+> Cookie: foo=bar
+[...]
+
+# VCL_return:hash in the log indicates that processing proceeds to
+# cache lookup:
+*   << Request  >> 33142     
+[...]
+-   ReqMethod      GET
+-   ReqURL         /coffee
+[...]
+-   ReqHeader      Cookie: foo=bar
+[...]
+-   VCL_call       RECV
+-   VCL_return     hash
+[...]
+
+# Requests with the CONNECT method go to pipe mode:
+$ curl -x $IP:$PORT -X CONNECT -v http://cafe.example.com/coffee
+[...]
+> CONNECT http://cafe.example.com/coffee HTTP/1.1
+> Host: cafe.example.com
+[...]
+
+*   << Request  >> 33171     
+[...]
+-   ReqMethod      CONNECT
+-   ReqURL         /coffee
+[...]
+-   VCL_call       RECV
+-   VCL_return     pipe
+[...]
+
+# Requests with any non-standard method get a 405 Method Not Allowed
+# response.
+$ curl -x $IP:$PORT -X HACK -v http://cafe.example.com/coffee
+[...]
+> HACK http://cafe.example.com/coffee HTTP/1.1
+> Host: cafe.example.com
+[...]
+> 
+< HTTP/1.1 405 Method Not Allowed
+[...]
+```
+
+## Bypassing cache lookup for specific cookies
+
+The next example illustrates a more fine-grained solution to permitting
+cache lookups for requests with cookies. If the Cookie header contains
+specific cookie names, with their values constrained to specific forms,
+then cache lookup is bypassed, otherwise permitted. This may be used to
+ensure that personalized responses are not cached, for example if the
+request uses a cookie with a session or login token. But if the request
+uses other cookies, then the response may be cacheable.
+
+To apply the configuration:
+
+```
+$ kubectl apply -f pass-on-session-cookie.yaml
+```
+
+The configuration contains this stanza for request with cookies:
+
+```
+    - conditions:
+      - comparand: req.http.Cookie
+        compare: match
+        values:
+          - \bSESSIONID\s*=\s*[[:xdigit:]]{32}\b
+          - \bLOGIN\s*=\s*\w+\b
+      disposition:
+        action: pass
+```
+
+The condition in this stanza uses ``compare:match``, indicating a
+regex match with any of the patterns in ``values``, which are
+interpreted as [RE2](https://github.com/google/re2/wiki/Syntax)
+regular expressions.  The cookies in question are ``SESSIONID``, whose
+value may be a 32 digit hex string; and ``LOGIN``, whose value may be
+any string of word characters.  Cache lookup is bypassed if the Cookie
+header's value matches either of the two patterns; otherwise cache
+lookup is permitted for a request with cookies.
+
+Remember that the ``req-disposition`` configuration also includes
+other features we wish to preserve (such as status 400 for HTTP/1.1
+requests with no Host header, or status 405 for non-standard request
+methods).
+
+Verification:
+```
+# The Varnish log shows pass for requests with cookies that match
+# either of the two patterns:
+$ curl -x $IP:$PORT -H 'Cookie: SESSIONID=0123456789abcdef0123456789abcdef' -v http://cafe.example.com/coffee
+[...]
+> GET http://cafe.example.com/coffee HTTP/1.1
+> Host: cafe.example.com
+[...]
+> Cookie: SESSIONID=0123456789abcdef0123456789abcdef
+[...]
+
+*   << Request  >> 33011     
+[...]
+-   ReqMethod      GET
+-   ReqURL         /coffee
+[...]
+-   ReqHeader      Cookie: SESSIONID=0123456789abcdef0123456789abcdef
+[...]
+-   VCL_call       RECV
+-   VCL_return     pass
+[...]
+
+$ curl -x $IP:$PORT -H 'Cookie: LOGIN=foobar' -v http://cafe.example.com/coffee
+[...]
+> GET http://cafe.example.com/coffee HTTP/1.1
+> Host: cafe.example.com
+[...]
+> Cookie: LOGIN=foobar
+[...]
+
+*   << Request  >> 252       
+[...]
+-   ReqMethod      GET
+-   ReqURL         /coffee
+[...]
+-   ReqHeader      Cookie: LOGIN=foobar
+[...]
+-   VCL_call       RECV
+-   VCL_return     pass
+[...]
+
+# Cache lookup proceeds if the Cookie header does not match either pattern:
+$ curl -x $IP:$PORT -H 'Cookie: foo=bar' -v http://cafe.example.com/coffee
+[...]
+> GET http://cafe.example.com/coffee HTTP/1.1
+> Host: cafe.example.com
+[...]
+> Cookie: foo=bar
+[...]
+
+*   << Request  >> 269       
+[...]
+-   ReqMethod      GET
+-   ReqURL         /coffee
+[...]
+-   ReqHeader      Cookie: foo=bar
+[...]
+-   VCL_call       RECV
+-   VCL_return     hash
+[...]
+```
+
+## Defining cacheability for URL path patterns
+
+The next example shows a different kind of feature that may be
+implemented with ``req-disposition`` -- defining requests as cacheable
+or not cacheable based on URL path patterns.
+
+Applying the configuration:
+
+```
+$ kubectl apply -f cacheability.yaml
+```
+
+The stanzas of interest in this configuration specify ``disposition``
+as ``hash`` or ``pass`` based on whether the URL path matches sets of
+patterns:
+
+```
+    - conditions:
+      - comparand: req.url
+        compare: match
+        values:
+          - \.png$
+          - \.jpe?g$
+          - \.css$
+          - \.js$
+      disposition:
+        action: hash
+
+    - conditions:
+      - comparand: req.url
+        compare: prefix
+        values:
+          - /interactive/
+          - /basket/
+          - /personal/
+          - /dynamic/
+      disposition:
+        action: pass
+```
+
+The first stanza uses ``compare.match`` to specify matching the URL against
+the regular expressions in ``values``, all of which describe file endings
+(for typically cacheable content). If the URL matches any one of them, then
+proceed to cache lookup (``action:hash``).
+
+The second stanza uses ``compare:prefix``, to determine if the URL has a
+prefix that is listed as one of the ``values``. If so, then cache lookup
+is bypassed.
+
+Verification:
+
+```
+# URLs that match the patterns for cacheability:
+$ curl -x $IP:$PORT -v http://cafe.example.com/coffee/black.js
+[...]
+> GET http://cafe.example.com/coffee/black.js HTTP/1.1
+> Host: cafe.example.com
+[...]
+
+# In the Varnish log:
+*   << Request  >> 688       
+[...]
+-   ReqMethod      GET
+-   ReqURL         /coffee/black.js
+[...]
+-   VCL_call       RECV
+-   VCL_return     hash
+[...]
+
+$ curl -x $IP:$PORT -v http://cafe.example.com/tea/sugar.css
+[...]
+> GET http://cafe.example.com/tea/sugar.css HTTP/1.1
+> Host: cafe.example.com
+[...]
+
+*   << Request  >> 33416     
+[...]
+-   ReqMethod      GET
+-   ReqURL         /tea/sugar.css
+[...]
+-   VCL_call       RECV
+-   VCL_return     hash
+[...]
+
+# URLs with prefixes classified as non-cacheable
+$ curl -x $IP:$PORT -v http://cafe.example.com/interactive/foo/bar
+[...]
+> GET http://cafe.example.com/interactive/foo/bar HTTP/1.1
+> Host: cafe.example.com
+[...]
+
+# The log shows that we go to pass:
+*   << Request  >> 719       
+[...]
+-   ReqMethod      GET
+-   ReqURL         /interactive/foo/bar
+[...]
+-   VCL_call       RECV
+-   VCL_return     pass
+[...]
+
+$ curl -x $IP:$PORT -v http://cafe.example.com/dynamic/baz/quux
+[...]
+> GET http://cafe.example.com/dynamic/baz/quux HTTP/1.1
+> Host: cafe.example.com
+[...]
+
+*   << Request  >> 33455     
+[...]
+-   ReqMethod      GET
+-   ReqURL         /dynamic/baz/quux
+[...]
+-   VCL_call       RECV
+-   VCL_return     pass
+[...]
+```
+
+## Request white- and blacklisting
+
+White- and blacklisting requests, based on properties of the client
+request, are additional features made possible by ``req-disposition``,
+demonstrated in the next example.
+
+Applying the configuration:
+
+```
+$ kubectl apply -f url-whitelist.yaml
+```
+
+The URL whitelist is defined in this stanza:
+
+```
+    - conditions:
+      - comparand: req.url
+        compare: not-prefix
+        values:
+          - /tea/sugar/
+          - /coffee/sugar/
+      disposition:
+        action: synth
+        status: 403
+```
+
+This means that a synthetic 403 Forbidden response is sent for every
+request whose URL path does not begin with one of the prefixes in
+``values``.
+
+The blacklist is defined with:
+
+```
+    - conditions:
+      - comparand: req.url
+        compare: prefix
+        values:
+          - /tea/sugar/black/
+          - /coffee/sugar/black/
+      disposition:
+        action: synth
+        status: 403
+```
+
+In this case, the synthetic 403 Forbidden response is generated for
+requests whose URL path does begin with one of the prefixes in
+``values``.  The combined effect is that requests are only permitted
+for URLs in the whitelist, but not for URLs in the blacklist.
+
+Of course your configuration can characterize the requests by other
+means available in ``conditions``, for example by specifying regex
+matching in ``compare``, and/or other properties of the request, such
+as headers, in ``comparand``.
+
+Verification:
+
+```
+# Requests matching the whitelist are permitted:
+$ curl -x $IP:$PORT -v http://cafe.example.com/coffee/sugar/bar
+[...]
+> GET http://cafe.example.com/coffee/sugar/foo HTTP/1.1
+> Host: cafe.example.com
+[...]
+> 
+< HTTP/1.1 200 OK
+[...]
+
+$ curl -x $IP:$PORT -v http://cafe.example.com/tea/sugar/bar
+[...]
+> GET http://cafe.example.com/tea/sugar/foo HTTP/1.1
+> Host: cafe.example.com
+[...]
+> 
+< HTTP/1.1 200 OK
+[...]
+
+# Requests not matching the whitelist are forbidden:
+$ curl -x $IP:$PORT -v http://cafe.example.com/coffee/baz
+[...]
+> GET http://cafe.example.com/coffee/baz HTTP/1.1
+> Host: cafe.example.com
+[...]
+> 
+< HTTP/1.1 403 Forbidden
+[...]
+
+$ curl -x $IP:$PORT -v http://cafe.example.com/tea/quux
+[...]
+> GET http://cafe.example.com/tea/quux HTTP/1.1
+> Host: cafe.example.com
+[...]
+> 
+< HTTP/1.1 403 Forbidden
+[...]
+
+# Requests matching the blacklist are also forbidden:
+$ curl -x $IP:$PORT -v http://cafe.example.com/coffee/sugar/black/foo
+[...]
+> GET http://cafe.example.com/coffee/sugar/black/foo HTTP/1.1
+> Host: cafe.example.com
+[...]
+> 
+< HTTP/1.1 403 Forbidden
+[...]
+
+$ curl -x $IP:$PORT -v http://cafe.example.com/tea/sugar/black/foo
+[...]
+> GET http://cafe.example.com/tea/sugar/black/foo HTTP/1.1
+> Host: cafe.example.com
+[...]
+> 
+< HTTP/1.1 403 Forbidden
+[...]
+
+```
+
+## Defining a PURGE method
+
+The final example demonstrates a way to make the Varnish
+[purge](https://varnish-cache.org/docs/6.1/users-guide/purging.html)
+facility available via a ``PURGE`` request method. When the processing
+state is set to ``purge``, and the request is a cache hit, the cached
+object and all of its variants are invlaidated, and Varnish send a
+synthetic "200 Purged" response.
+
+Applying the configuration:
+
+```
+$ kubectl apply -f purge-method.yaml
+```
+
+The ``PURGE`` method is defined with:
+
+```
+    - conditions:
+      - comparand: req.method
+        compare: equal
+        values:
+          - PURGE
+      disposition:
+        action: purge
+```
+
+This simply diverts to ``action:purge`` whenever the request method is
+``PURGE``. You will almost certainly want to also define authorization
+for use of purging via request, for example with an
+[ACL](/examples/acl) or [basic
+authentication](/examples/authentication), so that only trusted users
+are able to purge cache entries.
+
+Verification:
+
+```
+$ curl -X PURGE -x $IP:$PORT -v http://cafe.example.com/coffee
+[...]
+> PURGE http://cafe.example.com/coffee HTTP/1.1
+> Host: cafe.example.com
+[...]
+> 
+< HTTP/1.1 200 Purged
+[...]
+
+```

examples/req-disposition/alt-builtin.yaml

@@ -13,8 +13,11 @@ spec:
   services:
     - varnish-ingress
 
+  # Configure the disposition of client requests.
   req-disposition:
 
+    # Requests for HTTP/1.1. without a Host header are rejected with
+    # 400 Bad Request, as in builtin.yaml and built-in vcl_recv.
     - conditions:
       - comparand: req.http.Host
         compare: not-exists
@@ -30,6 +33,10 @@ spec:
         action: synth
         status: 400
 
+    # Requests with the CONNECT method invoke pipe mode. This may be
+    # appropriate for a WebSockets application. If you don't need pipe
+    # mode for any purpose, just include CONNECT in the array of
+    # request method names in the next stanza.
     - conditions:
       - comparand: req.method
         compare: equal
@@ -38,6 +45,8 @@ spec:
       disposition:
         action: pipe
 
+    # Requests with any non-standard method get a synthetic 405 Method
+    # Not Allowed response.
     - conditions:
       - comparand: req.method
         compare: not-equal
@@ -54,6 +63,8 @@ spec:
         action: synth
         status: 405
 
+    # Cache lookup is bypassed for requests whose method is neither of
+    # GET or HEAD.
     - conditions:
       - comparand: req.method
         compare: not-equal

examples/req-disposition/builtin.yaml

@@ -12,8 +12,26 @@ spec:
   services:
     - varnish-ingress
 
+  # req-disposition configures the disposition of client requests, as
+  # an array of objects with the conditions and disposition fields. If
+  # all of the conditions for such an object are true for a request,
+  # then the request is processed further as specified in the
+  # corresponding disposition field. The disposition specifies the
+  # next state of request processing, see:
+  # https://varnish-cache.org/docs/6.1/reference/states.html
+  #
+  # The conditions are evaluated in order, and the first set of
+  # conditions that evaluate to true invoke the corresponding
+  # disposition. If none of the conditions match, the request
+  # proceeds to cache lookup -- return(hash) from vcl_recv.
+  #
+  # This configuration reconstructs vcl_recv from builtin.vcl,
+  # see:
+  # https://github.com/varnishcache/varnish-cache/blob/6.1/bin/varnishd/builtin.vcl
   req-disposition:
 
+    # If the request method is "PRI", then send a synthetic "405
+    # Method Not Allowed" response.
     - conditions:
       - comparand: req.method
         compare: equal
@@ -23,6 +41,8 @@ spec:
         action: synth
         status: 405
 
+    # Reject an HTTP/1.1 request with a synthetic "400 Bad Request"
+    # response if it doesn't have a Host header.
     - conditions:
       - comparand: req.http.Host
         compare: not-exists
@@ -38,6 +58,8 @@ spec:
         action: synth
         status: 400
 
+    # Go to pipe mode for any request whose method is CONNECT, or a
+    # non-standard method.
     - conditions:
       - comparand: req.method
         compare: not-equal
@@ -53,6 +75,10 @@ spec:
       disposition:
         action: pipe
 
+    # Bypass cache lookup if the request method is neither of GET or
+    # HEAD.  Note that we only get here if the previous conditions did
+    # not evaluate to true, so the method must be one of PUT, POST,
+    # TRACE, OPTIONS, DELETE or PATCH.
     - conditions:
       - comparand: req.method
         compare: not-equal
@@ -62,14 +88,21 @@ spec:
       disposition:
         action: pass
 
+    # Bypass cache lookup if the request has a Cookie header.
     - conditions:
       - comparand: req.http.Cookie
         compare: exists
       disposition:
         action: pass
 
+    # Bypass cache lookup if the request has an Authorization header;
+    # that is, if it is sending credentials for basic or proxy
+    # authentication.
     - conditions:
       - comparand: req.http.Authorization
         compare: exists
       disposition:
         action: pass
+
+# If none of the conditions evaluate to true, then the request
+# proceeds to cache lookup.

examples/req-disposition/cacheability.yaml

@@ -14,8 +14,11 @@ spec:
   services:
     - varnish-ingress
 
+  # Configure the disposition of client requests.
   req-disposition:
 
+    # Requests for HTTP/1.1. without a Host header are rejected with
+    # 400 Bad Request, as in builtin.yaml and built-in vcl_recv.
     - conditions:
       - comparand: req.http.Host
         compare: not-exists
@@ -31,6 +34,8 @@ spec:
         action: synth
         status: 400
 
+    # Requests with any non-standard method get a synthetic 405 Method
+    # Not Allowed response.
     - conditions:
       - comparand: req.method
         compare: not-equal
@@ -47,6 +52,8 @@ spec:
         action: synth
         status: 405
 
+    # Cache lookup is bypassed for requests whose method is neither of
+    # GET or HEAD.
     - conditions:
       - comparand: req.method
         compare: not-equal
@@ -56,6 +63,8 @@ spec:
       disposition:
         action: pass
 
+    # Go to cache lookup (hash) if the URL ends in any of the patterns
+    # listed in values.
     - conditions:
       - comparand: req.url
         compare: match
@@ -67,6 +76,8 @@ spec:
       disposition:
         action: hash
 
+    # Bypass cache lookup (pass) if the URL begins with any of the
+    # prefixes listed in values.
     - conditions:
       - comparand: req.url
         compare: prefix

examples/req-disposition/pass-on-session-cookie.yaml

+# Configuration for disposition of client requests that illustrates
+# bypassing cache lookups for specific cookies.
+
+apiVersion: "ingress.varnish-cache.org/v1alpha1"
+kind: VarnishConfig
+metadata:
+  name: pass-on-session-cookie-cfg
+spec:
+  # The services array is required and must have at least one element.
+  # Lists the Service names of Varnish services in the same namespace
+  # to which this config is to be applied.
+  services:
+    - varnish-ingress
+
+  # Configure the disposition of client requests.
+  req-disposition:
+
+    # Requests for HTTP/1.1. without a Host header are rejected with
+    # 400 Bad Request, as in builtin.yaml and built-in vcl_recv.
+    - conditions:
+      - comparand: req.http.Host
+        compare: not-exists
+      - comparand: req.esi_level
+        count: 0
+      - comparand: req.proto
+        compare: prefix
+        values:
+          - HTTP/1.1
+        match-flags:
+          case-insensitive: true
+      disposition:
+        action: synth
+        status: 400
+
+    # Requests with any non-standard method get a synthetic 405 Method
+    # Not Allowed response.
+    - conditions:
+      - comparand: req.method
+        compare: not-equal
+        values:
+          - GET
+          - HEAD
+          - PUT
+          - POST
+          - TRACE
+          - OPTIONS
+          - DELETE
+          - PATCH
+          - CONNECT
+      disposition:
+        action: synth
+        status: 405
+
+    # Cache lookup is bypassed if the Cookie header includes either of
+    # the SESSION or LOGINID cookies, with their values constrained to
+    # specific forms. Cache lookup is permitted otherwise.
+    - conditions:
+      - comparand: req.http.Cookie
+        compare: match
+        values:
+          - \bSESSIONID\s*=\s*[[:xdigit:]]{32}\b
+          - \bLOGIN\s*=\s*\w+\b
+      disposition:
+        action: pass
+
+    # Cache lookup is bypassed for requests whose method is neither of
+    # GET or HEAD.
+    - conditions:
+      - comparand: req.method
+        compare: not-equal
+        values:
+          - GET
+          - HEAD
+      disposition:
+        action: pass

examples/req-disposition/purge-method.yaml

@@ -13,8 +13,11 @@ spec:
   services:
     - varnish-ingress
 
+  # Configure the disposition of client requests.
   req-disposition:
 
+    # Requests for HTTP/1.1. without a Host header are rejected with
+    # 400 Bad Request, as in builtin.yaml and built-in vcl_recv.
     - conditions:
       - comparand: req.http.Host
         compare: not-exists
@@ -30,6 +33,8 @@ spec:
         action: synth
         status: 400
 
+    # Divert to purge when the request method is PURGE.
+    # See: https://varnish-cache.org/docs/6.1/users-guide/purging.html
     - conditions:
       - comparand: req.method
         compare: equal
@@ -38,6 +43,8 @@ spec:
       disposition:
         action: purge
 
+    # Requests with any non-standard method get a synthetic 405 Method
+    # Not Allowed response.
     - conditions:
       - comparand: req.method
         compare: not-equal
@@ -50,10 +57,13 @@ spec:
           - OPTIONS
           - DELETE
           - PATCH
+          - CONNECT
       disposition:
         action: synth
         status: 405
 
+    # Cache lookup is bypassed for requests whose method is neither of
+    # GET or HEAD.
     - conditions:
       - comparand: req.method
         compare: not-equal

examples/req-disposition/url-whitelist.yaml

 # Configuration for disposition of client requests that permits cache
 # lookups for requests with Cookie or Authorization headers, and
-# defines a whitelist for requests based on URL path prefixes.
+# defines white- and blacklists for requests based on URL path prefixes.
 
 apiVersion: "ingress.varnish-cache.org/v1alpha1"
 kind: VarnishConfig
@@ -13,8 +13,11 @@ spec:
   services:
     - varnish-ingress
 
+  # Configure the disposition of client requests.
   req-disposition:
 
+    # Requests for HTTP/1.1. without a Host header are rejected with
+    # 400 Bad Request, as in builtin.yaml and built-in vcl_recv.
     - conditions:
       - comparand: req.http.Host
         compare: not-exists
@@ -30,6 +33,8 @@ spec:
         action: synth
         status: 400
 
+    # Requests with any non-standard method get a synthetic 405 Method
+    # Not Allowed response.
     - conditions:
       - comparand: req.method
         compare: not-equal
@@ -42,25 +47,42 @@ spec:
           - OPTIONS
           - DELETE
           - PATCH
+          - CONNECT
       disposition:
         action: synth
         status: 405
 
+    # A URL whitelist. Requests for URLs that do not have these
+    # prefixes get a synthetic 403 Forbidden response.
     - conditions:
-      - comparand: req.method
-        compare: not-equal
+      - comparand: req.url
+        compare: not-prefix
         values:
-          - GET
-          - HEAD
+          - /tea/sugar/
+          - /coffee/sugar/
       disposition:
-        action: pass
+        action: synth
+        status: 403
 
+    # A URL blacklist. Requests for URLs with these prefixes get a
+    # synthetic 403 Forbidden response.
     - conditions:
       - comparand: req.url
-        compare: not-prefix
+        compare: prefix
         values:
-          - /tea/
-          - /coffee/
+          - /tea/sugar/black/
+          - /coffee/sugar/black/
       disposition:
         action: synth
         status: 403
+
+    # Cache lookup is bypassed for requests whose method is neither of
+    # GET or HEAD.
+    - conditions:
+      - comparand: req.method
+        compare: not-equal
+        values:
+          - GET
+          - HEAD
+      disposition:
+        action: pass