Document that hosts are matched in order while policies are matched by precedence rules

Ref: 0c54b6bf

README.rst

@@ -345,6 +345,10 @@ be used to specify any subdomain of ``example.com``.
 Host names are case-insensitive; that is, ``.policy()`` will match
 a host name successfully regardless of case.
 
+Policies must be added in the order for which the host name lookup is
+to be carried out later. This is particularly important when the
+asterisk is used and more specific entries exist.
+
 The string in ``policy`` MUST be identical to the object name (VCL
 symbol) for a ``policy`` object previously defined in ``vcl_init``.
 If no such policy object exists, then the VCL load will fail with an
@@ -401,6 +405,9 @@ patterns as Akamai:
 If ``path`` violates any of these restrictions, then the VCL load will
 fail with an error message.
 
+Note that, while hosts are matched in order, paths are not. See
+:ref:`func_hosts.policy` for details.
+
 If a policy is assigned to a ``host`` and a ``path`` pattern, then
 subsequent invocations of ``.add()`` may assign policies to the same
 host and different patterns. A later invocation of ``.add()`` MAY NOT
@@ -464,10 +471,10 @@ This method MAY NOT be called in ``vcl_init``. If it is, then the VCL
 load fails.
 
 The method searches for host names added by the ``.add()`` method that
-match ``host``, possibly matching the suffix if the host name in
-``.add()`` began with an asterisk. If it finds a host for which a
-policy was assigned globally (without a path pattern), then it returns
-the type for that policy.
+match ``host`` in order of addition, possibly matching the suffix if
+the host name in ``.add()`` began with an asterisk. If it finds a host
+for which a policy was assigned globally (without a path pattern),
+then it returns the type for that policy.
 
 If it finds a host for which path patterns were defined, it attempts
 to match ``path``, respecting the use of ``*`` or ``...`` in the
@@ -497,6 +504,11 @@ Formally, the "more specific" relation is defined as:
 
   * else if A precedes B lexigraphically
 
+Note that, in contrast to hosts, for paths the order in which they
+were added with the ``.add()`` method is irrelevant. The rules for
+path matching should be identical to those of the Akamai SecureHD
+Policy Editor.
+
 Subsequent calls to the ``.token()``, ``.secret()`` or ``.explain()``
 methods refer to the most recent invocation of ``.policy()`` in the
 same task scope, that is in the same client or backend transaction.

src/vmod_hoailona.vcc

@@ -302,6 +302,10 @@ be used to specify any subdomain of ``example.com``.
 Host names are case-insensitive; that is, ``.policy()`` will match
 a host name successfully regardless of case.
 
+Policies must be added in the order for which the host name lookup is
+to be carried out later. This is particularly important when the
+asterisk is used and more specific entries exist.
+
 The string in ``policy`` MUST be identical to the object name (VCL
 symbol) for a ``policy`` object previously defined in ``vcl_init``.
 If no such policy object exists, then the VCL load will fail with an
@@ -358,6 +362,9 @@ patterns as Akamai:
 If ``path`` violates any of these restrictions, then the VCL load will
 fail with an error message.
 
+Note that, while hosts are matched in order, paths are not. See
+:ref:`func_hosts.policy` for details.
+
 If a policy is assigned to a ``host`` and a ``path`` pattern, then
 subsequent invocations of ``.add()`` may assign policies to the same
 host and different patterns. A later invocation of ``.add()`` MAY NOT
@@ -414,10 +421,10 @@ This method MAY NOT be called in ``vcl_init``. If it is, then the VCL
 load fails.
 
 The method searches for host names added by the ``.add()`` method that
-match ``host``, possibly matching the suffix if the host name in
-``.add()`` began with an asterisk. If it finds a host for which a
-policy was assigned globally (without a path pattern), then it returns
-the type for that policy.
+match ``host`` in order of addition, possibly matching the suffix if
+the host name in ``.add()`` began with an asterisk. If it finds a host
+for which a policy was assigned globally (without a path pattern),
+then it returns the type for that policy.
 
 If it finds a host for which path patterns were defined, it attempts
 to match ``path``, respecting the use of ``*`` or ``...`` in the
@@ -447,6 +454,11 @@ Formally, the "more specific" relation is defined as:
 
   * else if A precedes B lexigraphically
 
+Note that, in contrast to hosts, for paths the order in which they
+were added with the ``.add()`` method is irrelevant. The rules for
+path matching should be identical to those of the Akamai SecureHD
+Policy Editor.
+
 Subsequent calls to the ``.token()``, ``.secret()`` or ``.explain()``
 methods refer to the most recent invocation of ``.policy()`` in the
 same task scope, that is in the same client or backend transaction.