[GitHub] flimzy commented on a change in pull request #237: "Rewrite" section cleanup

[GitBox <gi...@apache.org>]

flimzy commented on a change in pull request #237: "Rewrite" section cleanup
URL: https://github.com/apache/couchdb-documentation/pull/237#discussion_r173620698
 
 

 ##########
 File path: src/api/ddoc/rewrites.rst
 ##########
 @@ -91,51 +98,58 @@ Rewrite section a is stringified function
           return reply;
         }
 
-      The req2 object rewrites is called with is a slightly truncated version
-      of req object, provided for list and update functions. Fields *info*,
-      *uuid*, *id* and *form* are removed to speed up request processing.
-      All other fields of the req object are in place.
+Using an array of rules for ``rewrites``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Rewrite section is an array
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+    When the ``rewrites`` field is an array of rule objects, the server will
+    rewrite the request based on the first matching rule in the array.
 
-    Each rule is an *object* with next structure:
+    Each rule in the array is an *object* with the following fields:
 
-    - **from** (*string*): The path rule used to bind current URI to the rule.
-      It uses pattern matching for that.
-    - **to** (*string*): Rule to rewrite a URL. It can contain variables
-      depending on  binding variables discovered during pattern matching and
-      query args (URL args and from the query member)
     - **method** (*string*): HTTP request method to bind the request method to
-      the rule. Default is ``"*"``
-    - **query** (*object*): Query args you want to define they can contain
-      dynamic variable by binding the key
-
-    The ``to``and ``from`` paths may contains string patterns with leading
-    ``:`` or ``*`` characters.
-
-    For example: ``/somepath/:var/*``
-
-    - This path is converted in Erlang list by splitting ``/``
-    - Each ``var`` are converted in atom
-    - ``""`` are converted to ``''`` atom
-    - The pattern matching is done by splitting ``/`` in request URL in a list
-      of token
-    - A string pattern will match equal token
-    - The star atom (``'*'`` in single quotes) will match any number of tokens,
-      but may only be present as the last `pathterm` in a `pathspec`
-    - If all tokens are matched and all `pathterms` are used, then the
-      `pathspec` matches
-
-    The pattern matching is done by first matching the HTTP request method to a
-    rule. ``method`` is equal to ``"*"`` by default, and will match any HTTP
-    method. It will then try to match the path to one rule. If no rule matches,
-    then a :statuscode:`404` response returned.
-
-    Once a rule is found we rewrite the request URL using the ``to`` and
-    ``query`` fields. The identified token are matched to the rule and will
-    replace var. If ``'*'`` is found in the rule it will contain the remaining
-    part if it exists.
+      the rule. If omitted, uses ``"*"``, which matches all methods.
+    - **from** (*string*): The pattern used to compare against the URL and
+      define dynamic variables.
+    - **to** (*string*): The path to rewrite the URL to. It can contain
+      variables depending on binding variables discovered during pattern
+      matching and query args (URL args and from the query member).
+    - **query** (*object*): Query args passed to the rewritten URL. They may
+      contain dynamic variables.
+
+    The ``to`` and ``from`` paths may contains string patterns with leading
+    ``:`` or ``*`` characters to define dynamic variables in the match.
+
+    The first rule in the ``rewrites`` array that matches the incoming request
+    is used to define the rewrite. To match the incoming request, the
+    rule's ``method`` must match the request's HTTP method and the rule's
+    ``from`` must match the request's path using the following pattern matching
+    logic.
+
+    - The *from* pattern and URL are first split on ``/`` to get a list of
+      tokens. For example, if *from* field is ``/somepath/:var/*`` and the URL
+      is ``/somepath/a/b/c``, the tokens are ``somepath``, ``:var``, and
+      ``*`` for the *from* pattern and ``somepath``, ``a``, ``b``, and
+      ``c`` for the URL.
+    - Each token starting with ``:`` in the pattern will match the
+      corresponding token in the URL and define a new dynamic variable whose
+      name is the remaining string after the ``:`` and value is the token from
+      the URL. In this example, the ``:var`` token will match ``b``
+      and set ``var`` = ``a``.
 
 Review comment:
   This part confuses me. `:var` will match `b`, and set `var` = `a`? Is there a typo here, or is it just confusing logic?  Or is my brain just mush?

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services