[trafficserver] branch master updated: First pass of documentation for URL rewrite.

[am...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

amc pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficserver.git


The following commit(s) were added to refs/heads/master by this push:
     new f32fc32  First pass of documentation for URL rewrite.
f32fc32 is described below

commit f32fc32c8e14510bdc0adb0054f8d48d7e0c817f
Author: Alan M. Carroll <am...@apache.org>
AuthorDate: Mon May 6 09:37:47 2019 -0500

    First pass of documentation for URL rewrite.
---
 doc/developer-guide/core-architecture/index.en.rst |   1 +
 .../url_rewrite_architecture.en.rst                |  60 +++++++++++++
 doc/uml/url_rewrite.plantuml                       | 100 +++++++++++++++++++++
 3 files changed, 161 insertions(+)

diff --git a/doc/developer-guide/core-architecture/index.en.rst b/doc/developer-guide/core-architecture/index.en.rst
index a1efacb..e88e35f 100644
--- a/doc/developer-guide/core-architecture/index.en.rst
+++ b/doc/developer-guide/core-architecture/index.en.rst
@@ -27,3 +27,4 @@ Core Architecture
 
    heap.en
    rpc.en
+   url_rewrite_architecture.en.rst
diff --git a/doc/developer-guide/core-architecture/url_rewrite_architecture.en.rst b/doc/developer-guide/core-architecture/url_rewrite_architecture.en.rst
new file mode 100644
index 0000000..2e1870d
--- /dev/null
+++ b/doc/developer-guide/core-architecture/url_rewrite_architecture.en.rst
@@ -0,0 +1,60 @@
+.. Licensed to the Apache Software Foundation (ASF) under one or more contributor license
+   agreements.  See the NOTICE file distributed with this work for additional information regarding
+   copyright ownership.  The ASF licenses this file to you under the Apache License, Version 2.0
+   (the "License"); you may not use this file except in compliance with the License.  You may obtain
+   a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software distributed under the License
+   is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+   or implied.  See the License for the specific language governing permissions and limitations
+   under the License.
+
+.. include:: ../../common.defs
+
+.. default-domain:: cpp
+
+.. highlight:: cpp
+
+.. _remap_architecture:
+
+URL Rewrite Architecture
+************************
+
+URL rewrite or "remapping" means changing the URL used in the in the :term:`proxy request`. This is
+initially the same as in the :term:`client request` and remains so if no URL rewriting is done.
+
+Rewriting is configured by an ordered list of rules. Each rule contains _parameters_ and
+_arguments_. Parameters are required and describe the basic rule. On top of the parameters are
+arguments, which are optional and adjust the behavior of the basic rule. These are distinguished by
+a leading '@' character, which marks an argument. Otherwise it is a parameter.
+
+Implementation
+==============
+
+.. class:: acl_filter_rule
+
+   An access check to determine if a rule is enabled for a request. The filter has a set of matching
+   criteria and an action, which is either ``ALLOW`` or ``DENY``. If the filter matches the request
+   the action is used, otherwise the next filter is checked.
+
+.. class:: UrlRewrite
+
+   The top level remapping structure. This is created from a configuration file and then used during
+   a transaction to perform remapping. Data that is shared or needs to persist as long as the
+   configuration is stored in this class. These are
+
+   The rules are stored here in one of several containers. The rule type is implicit in which
+   container contains the rule. It is assumed that all rules in a container have the data needed
+   for the rule type of that container.
+
+   .. class:: RegexMapping
+
+      A container for a regular expression mapping. This contains the base mapping along with the
+      regular expression and a format string. The format string is annotated with the locations of
+      regular expression match group subsitutions so that if the regular expression matches, the
+      results can be efficiently assembled in to the output host name.
+
+.. figure:: /uml/images/url_rewrite.svg
+   :align: center
diff --git a/doc/uml/url_rewrite.plantuml b/doc/uml/url_rewrite.plantuml
new file mode 100644
index 0000000..4f31507
--- /dev/null
+++ b/doc/uml/url_rewrite.plantuml
@@ -0,0 +1,100 @@
+' Licensed under the Apache License, Version 2.0 (the "License");
+' you may not use this file except in compliance with the License.
+' You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+' Unless required by  applicable law or agreed to in writing, software distributed under the License is distributed
+' on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+' See the License for the specific language governing permissions and limitations under the License.
+
+@startuml
+
+hide empty members
+
+class UrlRewrite << RefCountObj >> {
+  forward_mappings
+  reverse_mappings
+  permanent_redirects
+  temporary_redirects
+  forward_mappings_with_recv_port
+}
+
+UrlRewrite --* MappingStore
+
+class MappingStore {
+  Rule collection
+}
+
+MappingStore --* "1" RegexMappingList
+MappingStore --* "1" URLTable
+
+class URLTable <<std::unordered_map>> {
+  key: FQDN
+  value: UrlMappingPathIndex
+}
+
+URLTable --* "*" UrlMappingPathIndex
+
+class acl_filter_rule {
+  Access check
+  ============
+  string name
+  IpMap src_ip
+  IpMap proxy_ip
+  std::vector<RemapArg> argv
+}
+
+acl_filter_rule --* "next" acl_filter_rule
+' acl_filter_rule --* "*" RemapArg
+' acl_filter_rule --* "2" IpMap
+
+class url_mapping {
+  rewrite rule
+  ================
+  URL from
+  URL to
+}
+note right: Mapping type is determined by\nwhich MappingStore owns\nthis mapping.
+
+url_mapping --* "1" acl_filter_rule
+note bottom: Local rule and copies of defined filters
+
+url_mapping --* "1" "std::vector<RemapPluginInfo*>"
+url_mapping --* "1" "std::vector<void*>"
+note bottom: "Plugin instance data"
+url_mapping --* "1" referrer_info
+url_mapping --* "1" redirect_tag_str
+url_mapping --* "2" URL
+
+"std::vector<RemapPluginInfo*>" --o "*" RemapPluginInfo
+
+redirect_tag_str --* "next" redirect_tag_str
+note bottom: Redirect URL format elements
+
+class referrer_info {
+  Host rewrite Referer data
+}
+
+referrer_info --* "next" referrer_info
+
+class UrlMappingPathIndex {
+}
+
+class UrlMappingTrie << Trie >> {
+  key: path
+  value: url_mapping
+}
+
+class UrlMappingGroup << std::map >> {
+  key: { scheme, port }
+  value: UrlMappingTrie
+}
+
+UrlMappingPathIndex --* "1" UrlMappingGroup
+UrlMappingGroup --* "*" UrlMappingTrie
+UrlMappingTrie --* "*" url_mapping
+
+RegexMappingList --* "*" url_mapping
+
+class RegexMappingList << Queue >> {
+}
+
+@enduml