apache · vmamidi · Aug 4, 2021 · Jul 19, 2021 · Jul 23, 2021 · Jul 27, 2021
diff --git a/doc/.tx/config b/doc/.tx/config
@@ -752,6 +752,11 @@ file_filter = locale/<lang>/LC_MESSAGES/developer-guide/api/functions/TSHttpConn
 source_file = _build/locale/pot/developer-guide/api/functions/TSHttpConnect.en.pot
 source_lang = en
 
+[apache-traffic-server-6x.developer-guide--api--functions--TSHttpConnectPlugin_en]
+file_filter = locale/<lang>/LC_MESSAGES/developer-guide/api/functions/TSHttpConnectPlugin.en.po
+source_file = _build/locale/pot/developer-guide/api/functions/TSHttpConnectPlugin.en.pot
+source_lang = en
+
 [apache-traffic-server-6x.developer-guide--api--functions--TSHttpConnectWithPluginId_en]
 file_filter = locale/<lang>/LC_MESSAGES/developer-guide/api/functions/TSHttpConnectWithPluginId.en.po
 source_file = _build/locale/pot/developer-guide/api/functions/TSHttpConnectWithPluginId.en.pot
@@ -1342,6 +1347,21 @@ file_filter = locale/<lang>/LC_MESSAGES/developer-guide/api/functions/TSPluginIn
 source_file = _build/locale/pot/developer-guide/api/functions/TSPluginInit.en.pot
 source_lang = en
 
+[apache-traffic-server-6x.developer-guide--api--functions--TSPluginVCIOBufferIndexGet]
+file_filter = locale/<lang>/LC_MESSAGES/developer-guide/api/functions/TSPluginVCIOBufferIndexGet.en.po
+source_file = _build/locale/pot/developer-guide/api/functions/TSPluginVCIOBufferIndexGet.en.pot
+source_lang = en
+
+[apache-traffic-server-6x.developer-guide--api--functions--TSPluginVCIOBufferWaterMarkGet]
+file_filter = locale/<lang>/LC_MESSAGES/developer-guide/api/functions/TSPluginVCIOBufferWaterMarkGet.en.po
+source_file = _build/locale/pot/developer-guide/api/functions/TSPluginVCIOBufferWaterMarkGet.en.pot
+source_lang = en
+
+[apache-traffic-server-6x.developer-guide--api--functions--TSHttpConnectOptionsGet]
+file_filter = locale/<lang>/LC_MESSAGES/developer-guide/api/functions/TSHttpConnectOptionsGet.en.po
+source_file = _build/locale/pot/developer-guide/api/functions/TSHttpConnectOptionsGet.en.pot
+source_lang = e
+
 [apache-traffic-server-6x.developer-guide--api--functions--TSRemap_en]
 file_filter = locale/<lang>/LC_MESSAGES/developer-guide/api/functions/TSRemap.en.po
 source_file = _build/locale/pot/developer-guide/api/functions/TSRemap.en.pot

diff --git a/doc/admin-guide/files/records.config.en.rst b/doc/admin-guide/files/records.config.en.rst
@@ -4350,6 +4350,21 @@ Plug-in Configuration
    Enables (``1``) or disables (``0``) the dynamic reload feature for remap
    plugins (`remap.config`). Global plugins (`plugin.config`) do not have dynamic reload feature yet.
 
+.. ts:cv:: CONFIG proxy.config.plugin.vc.default_buffer_index INT 8
+   :reloadable:
+   :overridable:
+
+   Specifies the buffer index and thus size to use when constructing IO buffers within the PluginVC.
+   Tuning this can impact performance of intercept plugins. Default is 8, which aligns with the
+   default value of ts:cv:`CONFIG proxy.config.http.default_buffer_size`.
+
+.. ts:cv:: CONFIG proxy.config.plugin.vc.default_buffer_water_mark INT 0
+   :reloadable:
+   :overridable:
+
+   Specifies the buffer water mark size in bytes used to control the flow of data through IO buffers
+   within the PluginVC. Default is zero to preserve existing PluginVC water marking behavior.
+
 SOCKS Processor
 ===============
 

diff --git a/doc/admin-guide/logging/formatting.en.rst b/doc/admin-guide/logging/formatting.en.rst
@@ -539,10 +539,12 @@ Field Source           Description
 ===== ================ ============================================================
 piid  Proxy Plugin     Plugin ID for the current transaction. This is set for
                        plugin driven transactions via
-                       :c:func:`TSHttpConnectWithPluginId`.
+                       :c:func:`TSHttpConnectWithPluginId`. or
+                       :c:func:`TSHttpConnectPlugin`.
 pitag Proxy Plugin     Plugin tag for the current transaction. This is set for
                        plugin driven transactions via
-                       :c:func:`TSHttpConnectWithPluginId`.
+                       :c:func:`TSHttpConnectWithPluginId`. or
+                       :c:func:`TSHttpConnectPlugin`.
 cqint Client Request   If a request was generated internally (via a plugin), then
                        this has a value of ``1``, otherwise ``0``. This can be
                        useful when tracking internal only requests, such as those

diff --git a/doc/developer-guide/api/functions/TSHttpConnectOptionsGet.en.rst b/doc/developer-guide/api/functions/TSHttpConnectOptionsGet.en.rst
@@ -0,0 +1,37 @@
+.. 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:: c
+
+TSHttpConnectOptionsGet
+***********************
+
+Synopsis
+========
+
+.. code-block:: cpp
+
+    #include <ts/ts.h>
+
+.. function:: TSHttpConnectOptions TSHttpConnectOptionsGet(TSConnectType connect_type)
+
+Description
+===========
+
+Convenience function to obtain a :type:`TSHttpConnectOptions` struct of the given
+:type:`TSConnectType` provided in :arg:`connect_type` with default values.
diff --git a/doc/developer-guide/api/functions/TSHttpConnectPlugin.en.rst b/doc/developer-guide/api/functions/TSHttpConnectPlugin.en.rst
@@ -0,0 +1,89 @@
+.. 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:: c
+
+TSHttpConnectPlugin
+*************************
+
+Allows the plugin to initiate an http connection. This will tag the
+HTTP state machine with extra data that can be accessed by the
+logging interface. Additional arguments provide buffer settings that
+are used when constructing IOBuffers. The connection is treated as
+an HTTP transaction as if it came from a client.
+
+Synopsis
+========
+
+.. code-block:: cpp
+
+    #include <ts/ts.h>
+
+.. function:: TSVConn TSHttpConnectPlugin(TSHttpConnectOptions * options);
+
+Description
+===========
+
+This call attempts to create an HTTP state machine and a virtual
+connection to that state machine. This is more efficient than using
+:c:func:`TSNetConnect` because it avoids using the operating system
+stack via the loopback interface.
+
+:arg:`options`
+   A :c:type:`TSHttpConnectOptions` structure that contains fields
+   that provide the network address of the target, a tag that can be
+   passed through to the HTTP state machine, a plugin ID, a buffer
+   index and buffer water mark.
+
+The virtual connection returned as the :c:type:`TSVConn` is API
+equivalent to a network virtual connection both to the plugin and
+to internal mechanisms. Data is read and written to the connection
+(and thence to the target system) by reading and writing on this
+virtual connection.
+
+.. note::
+
+   This function only opens the connection. To drive the transaction an actual
+   HTTP request must be sent and the HTTP response handled. The transaction is
+   handled as a standard HTTP transaction and all of the standard configuration
+   options and plugins will operate on it.
+
+The combination of :arg:`tag` and :arg:`id` is intended to enable correlation
+in log post processing. The :arg:`tag` identifies the connection as related
+to the plugin and the :arg:`id` can be used in conjunction with plugin
+generated logs to correlate the log records.
+
+Notes
+=====
+
+The H2 implementation uses this to correlate client sessions
+with H2 streams. Each client connection is assigned a distinct
+numeric identifier. This is passed in the options structure via
+the member variable `id` to the :c:func:`TSHttpConnectPlugin` function.
+The :arg:`tag` is selected to be the NPN string for the client session
+protocol, e.g. "h2". Log post processing can then count the number of
+connections for the various supported protocols and the number of H2
+virtual streams for each real client connection to Traffic Server.
+
+See Also
+========
+
+:manpage:`TSHttpConnectWithPluginId(3ts)`,
+:manpage:`TSHttpConnect(3ts)`,
+:manpage:`TSNetConnect(3ts)`,
+:manpage:`TSAPI(3ts)`
diff --git a/doc/developer-guide/api/functions/TSHttpConnectWithPluginId.en.rst b/doc/developer-guide/api/functions/TSHttpConnectWithPluginId.en.rst
@@ -26,6 +26,13 @@ HTTP state machine with extra data that can be accessed by the
 logging interface. The connection is treated as an HTTP transaction
 as if it came from a client.
 
+.. note::
+
+   This is a convenience function for :c:func:`TSHttpConnectPlugin` to provide
+   a simpler interface and backward compatibility for existing implementations.
+   When this function is used instead of `TSHttpConnectPlugin`, default buffer
+   index and watermark values will be used when creating IOBuffers.
+
 Synopsis
 ========
 
@@ -99,6 +106,7 @@ real client connection to Traffic Server.
 See Also
 ========
 
+:manpage:`TSHttpConnectPlugin(3ts)`,
 :manpage:`TSHttpConnect(3ts)`,
 :manpage:`TSNetConnect(3ts)`,
 :manpage:`TSAPI(3ts)`
diff --git a/doc/developer-guide/api/functions/TSHttpOverridableConfig.en.rst b/doc/developer-guide/api/functions/TSHttpOverridableConfig.en.rst
@@ -183,6 +183,8 @@ TSOverridableConfigKey Value                                              Config
 :c:enumerator:`TS_CONFIG_SSL_CLIENT_PRIVATE_KEY_FILENAME`                 :ts:cv:`proxy.config.ssl.client.private_key.filename`
 :c:enumerator:`TS_CONFIG_SSL_CLIENT_CA_CERT_FILENAME`                     :ts:cv:`proxy.config.ssl.client.CA.cert.filename`
 :c:enumerator:`TS_CONFIG_HTTP_HOST_RESOLUTION_PREFERENCE`                 :ts:cv:`proxy.config.hostdb.ip_resolve`
+:c:enumerator:`TS_CONFIG_PLUGIN_VC_DEFAULT_BUFFER_INDEX`                  :ts:cv:`proxy.config.plugin.vc.default_buffer_index`
+:c:enumerator:`TS_CONFIG_PLUGIN_VC_DEFAULT_BUFFER_WATER_MARK`             :ts:cv:`proxy.config.plugin.vc.default_buffer_water_mark`
 ========================================================================  ====================================================================
 
 Examples

diff --git a/doc/developer-guide/api/functions/TSHttpTxnPluginTagGet.en.rst b/doc/developer-guide/api/functions/TSHttpTxnPluginTagGet.en.rst
@@ -38,5 +38,6 @@ tag is set by the plugin that created the transaction.
 
 See also
 ========
+:manpage:`TSHttpConnectPlugin(3ts)`,
 :manpage:`TSHttpConnectWithPluginId(3ts)`,
 :manpage:`TSAPI(3ts)`
diff --git a/doc/developer-guide/api/functions/TSPluginVCIOBufferIndexGet.en.rst b/doc/developer-guide/api/functions/TSPluginVCIOBufferIndexGet.en.rst
@@ -0,0 +1,41 @@
+.. 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:: c
+
+TSPluginVCIOBufferIndexGet
+**************************
+
+Synopsis
+========
+
+.. code-block:: cpp
+
+    #include <ts/ts.h>
+
+.. function:: TSIOBufferSizeIndex TSPluginVCIOBufferIndexGet(TSHttpTxn txnp)
+
+Description
+===========
+
+Convenience function to obtain the current value of the
+:ts:cv:`proxy.config.plugin.vc.default_buffer_index` parameter from the
+transaction provided in :arg:`txnp`. If no errors are encountered and the
+buffer index on the transaction is greater than or equal to the minimum value,
+and less than or equal to the maximum value, this value is returned. Otherwise
+the default buffer index is returned.
diff --git a/doc/developer-guide/api/functions/TSPluginVCIOBufferWaterMarkGet.en.rst b/doc/developer-guide/api/functions/TSPluginVCIOBufferWaterMarkGet.en.rst
@@ -0,0 +1,40 @@
+.. 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:: c
+
+TSPluginVCIOBufferWaterMarkGet
+******************************
+
+Synopsis
+========
+
+.. code-block:: cpp
+
+    #include <ts/ts.h>
+
+.. function:: TSIOBufferWaterMark TSPluginVCIOBufferWaterMarkGet(TSHttpTxn txnp)
+
+Description
+===========
+
+Convenience function to obtain the current value of the
+:ts:cv:`proxy.config.plugin.vc.default_buffer_water_mark` parameter from the
+transaction provided in :arg:`txnp`. If no errors are encountered and the
+watermark on the transaction is greater than or equal to zero, this value
+is returned. Otherwise the default value is returned.
diff --git a/doc/developer-guide/api/functions/TSTypes.en.rst b/doc/developer-guide/api/functions/TSTypes.en.rst
@@ -78,6 +78,42 @@ more widely. Those are described on this page.
 
    A 64 bit time value, measured in nanoseconds.
 
+.. type:: TSHttpConnectOptions
+
+   A type that encapsulates options passed into the :func:`TSHttpConnectPlugin` function.
+
+   .. member:: TSConnectType connect_type
+
+      The type of data represented in the struct.
+
+   .. member:: sockaddr const *addr
+
+      Network address of the target of the connection.
+
+   .. member:: const char *tag
+
+      Tag that is passed through to the HTTP state machine.
+
+   .. member:: int64_t id
+
+      Numeric identifier passed through to the HTTP state machine.
+
+   .. member:: TSIOBufferSizeIndex buffer_index
+
+      A numeric buffer size index used to derive actual sizes used when constructing
+      IOBuffers; see :type:`TSIOBufferSizeIndex`.
+
+   .. member:: TSIOBufferWaterMark buffer_water_mark
+
+      A numeric value specifying the minimum number of bytes that must be written to
+      an IOBuffer before any continuation is called back to read from the buffer.
+      See the :c:func:`TSIOBufferWaterMarkGet` and :c:func:`TSIOBufferWaterMarkSet`
+      functions for further detail.
+
+.. type:: TSConnectType
+
+   Enumeration that specifies the type of data within a :c:type:`TSHttpConnectOptions` structure.
+
 .. type:: TSHttpParser
 
 .. type:: TSHttpSsn
@@ -96,6 +132,10 @@ more widely. Those are described on this page.
 
 .. type:: TSIOBufferSizeIndex
 
+.. type:: TSIOBufferWaterMark
+
+   An enumeration that contains valid watermark values, currently only defaults.
+
 .. type:: TSLifecycleHookID
 
    An enumeration that identifies a :ref:`life cycle hook <ts-lifecycle-hook-add>`.

diff --git a/doc/developer-guide/api/types/TSOverridableConfigKey.en.rst b/doc/developer-guide/api/types/TSOverridableConfigKey.en.rst
@@ -150,6 +150,8 @@ Enumeration Members
 .. c:enumerator:: TS_CONFIG_SSL_CLIENT_PRIVATE_KEY_FILENAME
 .. c:enumerator:: TS_CONFIG_SSL_CLIENT_CA_CERT_FILENAME
 .. c:enumerator:: TS_CONFIG_HTTP_HOST_RESOLUTION_PREFERENCE
+.. c:enumerator:: TS_CONFIG_PLUGIN_VC_DEFAULT_BUFFER_INDEX
+.. c:enumerator:: TS_CONFIG_PLUGIN_VC_DEFAULT_BUFFER_WATER_MARK
 
 
 Description