You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by zw...@apache.org on 2019/02/28 00:38:18 UTC
[trafficserver] branch 8.0.x updated: Doc: Add documentation for
experimental plugin "multiplexer".
This is an automated email from the ASF dual-hosted git repository.
zwoop pushed a commit to branch 8.0.x
in repository https://gitbox.apache.org/repos/asf/trafficserver.git
The following commit(s) were added to refs/heads/8.0.x by this push:
new af775f0 Doc: Add documentation for experimental plugin "multiplexer".
af775f0 is described below
commit af775f0609935cba79e274f88b2df138be339bc3
Author: Alan M. Carroll <am...@apache.org>
AuthorDate: Thu Aug 9 09:32:23 2018 -0500
Doc: Add documentation for experimental plugin "multiplexer".
(cherry picked from commit 180822ba81908705a238079ebfd0080164ae4f00)
---
doc/admin-guide/plugins/index.en.rst | 7 ++
doc/admin-guide/plugins/multiplexer.en.rst | 118 +++++++++++++++++++++++++++++
2 files changed, 125 insertions(+)
diff --git a/doc/admin-guide/plugins/index.en.rst b/doc/admin-guide/plugins/index.en.rst
index 7df48de..0647264 100644
--- a/doc/admin-guide/plugins/index.en.rst
+++ b/doc/admin-guide/plugins/index.en.rst
@@ -155,6 +155,7 @@ directory of the |TS| source tree. Experimental plugins can be compiled by passi
Metalink <metalink.en>
Money Trace <money_trace.en>
MP4 <mp4.en>
+ Multiplexer <multiplexer.en>
MySQL Remap <mysql_remap.en>
Signed URLs <url_sig.en>
SSL Headers <sslheaders.en>
@@ -204,6 +205,12 @@ directory of the |TS| source tree. Experimental plugins can be compiled by passi
:doc:`MP4 <mp4.en>`
MP4 streaming media.
+:doc:`Multiplexer <multiplexer.en>`
+ Multiplex inbound requests to multiple upstream destinations. This is useful for requests that
+ are beacons or other metric gathering requests, to report to multiple upstreams. Alternatively
+ this can be used to do A/B testing by sending a duplicated slice of inbound production traffic to
+ experimental upstreams.
+
:doc:`MySQL Remap <mysql_remap.en>`
Allows dynamic remaps from a MySQL database.
diff --git a/doc/admin-guide/plugins/multiplexer.en.rst b/doc/admin-guide/plugins/multiplexer.en.rst
new file mode 100644
index 0000000..f0f86a5
--- /dev/null
+++ b/doc/admin-guide/plugins/multiplexer.en.rst
@@ -0,0 +1,118 @@
+.. 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
+
+.. highlight:: cpp
+.. default-domain:: cpp
+.. |Name| replace:: Multiplexer
+
+|Name|
+**********
+
+|Name| is a remap plug-in that allows a request to be multiplexed one or more times and sent to
+different remap entries. Both headers and body (in case of POST or PUT methods, only) are copied
+into the new requests.
+
+Description
+===========
+
+Actions:
+
+#. Adds ``X-Multiplexer: original`` header into client's request.
+#. Copies client's request (bodies are copied by transforming the request)
+#. Changes ``Host`` header of the copy according to ``pparam`` from the remap rule.
+#. Changes ``X-Multiplexer header`` to "copy".
+#. Sends the copied request with :code:`TSHttpConnect`.
+
+|Name| dispatches the request in background without blocking the original request. Multiplexed
+responses are drained and discarded.
+
+A global timeout can be overwritten through ``multiplexer__timeout`` environment variable representing how many nanoseconds to wait. A default 1s timeout is hard-coded.
+
+Please use ``multiplexer`` tag for debugging purposes. While debugging, multiplexed requests and
+responses are printed into the logs.
+
+Multiplexer produces the following statistics consumed with ``traffic_ctl``:
+
+* failures: number of failed multiplexed requests
+* hits: number of successful multiplexed requests
+* requests: total number of multiplexed requests
+* time(avg): average time taken between multiplexed requests and their responses
+* timeouts: number of multiplexed requests which timed-out
+* size(avg): average size of multiplexed responses
+
+Example remap.config::
+
+ map http://www.example.com/a http://www.example.com/ @plugin=multiplexer.so @pparam=host1.example.com
+ map http://www.example.com/b http://www.example.com/ @plugin=multiplexer.so @pparam=host2.example.com
+ map http://www.example.com/c http://www.example.com/ @plugin=multiplexer.so @pparam=host1.example.com @pparam=host2.example.com
+
+
+Implementation
+==============
+
+Parsing Chunk Encoded Data
+--------------------------
+
+|Name| parses chunked data with its own home brew parser. In the parser :code:`size_` is the size of
+a chunk to be consumed. The local variable / parameter :code:`size` is raw input size as read from an
+:code:`TSIOBufferBlock`. The "size states" are marked blue.
+
+.. uml::
+ :align: center
+
+ @startuml
+
+ skinparam state {
+ backgroundColor<<SIZE_STATE>> SkyBlue
+ }
+
+ state kSize <<SIZE_STATE>>
+ kSize : Accumulate size_\nfrom hex input.
+ [*] --> kSize
+ kSize --> kSize : hex digit
+ kSize --> kDataN : CR,size_ > 0
+ kSize --> kEndN : CR, size_ == 0
+ kSize --> kInvalid : *
+
+ state kDataN <<SIZE_STATE>>
+ kDataN --> kData : LF
+ kDataN --> kInvalid : *
+ kDataN : ASSERT(size_ > 0)
+
+ state kEndN <<SIZE_STATE>>
+ kEndN --> kEnd : LF
+ kEndN --> kInvalid : *
+
+ kData : Consume size_\nbytes of input.
+ kData --> kSizeR : Input consumed
+
+ state kSizeR <<SIZE_STATE>>
+ kSizeR --> kSizeN : CR
+ kSizeR --> kInvalid : *
+
+ state kSizeN <<SIZE_STATE>>
+ kSizeN --> kSize : LF
+ kSizeN --> kInvalid : *
+
+ kInvalid --> [*]
+ kEnd --> [*]
+ @enduml
+
+Notes
+=====
+
+.. note:: This should be moved to the |TS| documentation.