You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by jp...@apache.org on 2015/11/03 07:09:54 UTC
[18/51] trafficserver git commit: Documentation reorganization
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/developer-guide/plugins/example-plugins/blacklist/source-code.en.rst
----------------------------------------------------------------------
diff --git a/doc/developer-guide/plugins/example-plugins/blacklist/source-code.en.rst b/doc/developer-guide/plugins/example-plugins/blacklist/source-code.en.rst
new file mode 100644
index 0000000..402c54f
--- /dev/null
+++ b/doc/developer-guide/plugins/example-plugins/blacklist/source-code.en.rst
@@ -0,0 +1,305 @@
+.. 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
+
+.. _developer-plugins-examples-blacklist-code:
+
+Sample Source Code
+******************
+
+.. _blacklist-1.c:
+
+blacklist-1.c
+-------------
+
+The sample blacklisting plugin included in the Traffic Server SDK is
+``blacklist-1.c``. This plugin checks every incoming HTTP client request
+against a list of blacklisted web sites. If the client requests a
+blacklisted site, then the plugin returns an ``Access forbidden``
+message to the client.
+
+This plugin illustrates:
+
+- An HTTP transaction extension
+
+- How to examine HTTP request headers
+
+- How to use the logging interface
+
+- How to use the plugin configuration management interface
+
+.. code-block:: c
+
+ /* blacklist-1.c: An example program that denies client access
+ * to blacklisted sites. This plugin illustrates
+ * how to use configuration information from the
+ * blacklist.txt configuration file.
+ *
+ * Usage:
+ * (Solaris) : blacklist-1.so
+ *
+ *
+ */
+
+ #include <stdio.h>
+ #include <string.h>
+ #include <ts/ts.h>
+
+ #define MAX_NSITES 500
+
+ static char* sites[MAX_NSITES];
+ static int nsites;
+ static TSMutex sites_mutex;
+ static TSTextLogObject log;
+
+ static void
+ handle_dns (TSHttpTxn txnp, TSCont contp)
+ {
+ TSMBuffer bufp;
+ TSMLoc hdr_loc;
+ TSMLoc url_loc;
+ const char *host;
+ int i;
+ int host_length;
+
+ if (!TSHttpTxnClientReqGet (txnp, &bufp, &hdr_loc)) {
+ TSError ("[blacklist-1] Couldn't retrieve client request header");
+ goto done;
+ }
+
+ url_loc = TSHttpHdrUrlGet (bufp, hdr_loc);
+ if (!url_loc) {
+ TSError ("[blacklist-1] Couldn't retrieve request url");
+ TSHandleMLocRelease (bufp, TS_NULL_MLOC, hdr_loc);
+ goto done;
+ }
+
+ host = TSUrlHostGet (bufp, url_loc, &host_length);
+ if (!host) {
+ TSError ("[blacklist-1] Couldn't retrieve request hostname");
+ TSHandleMLocRelease (bufp, hdr_loc, url_loc);
+ TSHandleMLocRelease (bufp, TS_NULL_MLOC, hdr_loc);
+ goto done;
+ }
+
+ TSMutexLock(sites_mutex);
+
+ for (i = 0; i < nsites; i++) {
+ if (strncmp (host, sites[i], host_length) == 0) {
+ if (log) {
+ TSTextLogObjectWrite(log, "blacklisting site: %s", sites[i]);
+ } else {
+ printf ("blacklisting site: %s\n", sites[i]);
+ }
+ TSHttpTxnHookAdd (txnp, TS_HTTP_SEND_RESPONSE_HDR_HOOK, contp);
+ TSHandleMLocRelease (bufp, hdr_loc, url_loc);
+ TSHandleMLocRelease (bufp, TS_NULL_MLOC, hdr_loc);
+ TSHttpTxnReenable (txnp, TS_EVENT_HTTP_ERROR);
+ TSMutexUnlock(sites_mutex);
+ return;
+ }
+ }
+
+ TSMutexUnlock(sites_mutex);
+ TSHandleMLocRelease (bufp, hdr_loc, url_loc);
+ TSHandleMLocRelease (bufp, TS_NULL_MLOC, hdr_loc);
+
+ done:
+ TSHttpTxnReenable (txnp, TS_EVENT_HTTP_CONTINUE);
+ }
+
+ static void
+ handle_response (TSHttpTxn txnp)
+ {
+ TSMBuffer bufp;
+ TSMLoc hdr_loc;
+ TSMLoc url_loc;
+ char *url_str;
+ char *buf;
+ int url_length;
+
+ if (!TSHttpTxnClientRespGet (txnp, &bufp, &hdr_loc)) {
+ TSError ("[blacklist-1] Couldn't retrieve client response header");
+ goto done;
+ }
+
+ TSHttpHdrStatusSet (bufp, hdr_loc, TS_HTTP_STATUS_FORBIDDEN);
+ TSHttpHdrReasonSet (bufp, hdr_loc,
+ TSHttpHdrReasonLookup (TS_HTTP_STATUS_FORBIDDEN),
+ strlen (TSHttpHdrReasonLookup (TS_HTTP_STATUS_FORBIDDEN)) );
+
+ if (!TSHttpTxnClientReqGet (txnp, &bufp, &hdr_loc)) {
+ TSError ("[blacklist-1] Couldn't retrieve client request header");
+ TSHandleMLocRelease (bufp, TS_NULL_MLOC, hdr_loc);
+ goto done;
+ }
+
+ url_loc = TSHttpHdrUrlGet (bufp, hdr_loc);
+ if (!url_loc) {
+ TSError ("[blacklist-1] Couldn't retrieve request url");
+ TSHandleMLocRelease (bufp, TS_NULL_MLOC, hdr_loc);
+ goto done;
+ }
+
+ buf = (char *)TSmalloc (4096);
+
+ url_str = TSUrlStringGet (bufp, url_loc, &url_length);
+ sprintf (buf, "You are forbidden from accessing \"%s\"\n", url_str);
+ TSfree (url_str);
+ TSHandleMLocRelease (bufp, hdr_loc, url_loc);
+ TSHandleMLocRelease (bufp, TS_NULL_MLOC, hdr_loc);
+
+ TSHttpTxnErrorBodySet (txnp, buf, strlen (buf), NULL);
+
+ done:
+ TSHttpTxnReenable (txnp, TS_EVENT_HTTP_CONTINUE);
+ }
+
+ static void
+ read_blacklist (void)
+ {
+ char blacklist_file[1024];
+ TSFile file;
+
+ sprintf (blacklist_file, "%s/blacklist.txt", TSPluginDirGet());
+ file = TSfopen(blacklist_file, "r");
+
+ TSMutexLock (sites_mutex);
+ nsites = 0;
+
+ if (file != NULL) {
+ char buffer[1024];
+
+ while (TSfgets (file, buffer, sizeof(buffer)-1) != NULL && nsites < MAX_NSITES) {
+ char* eol;
+ if ((eol = strstr(buffer, "\r\n")) != NULL) {
+ /* To handle newlines on Windows */
+ *eol = '\0';
+ } else if ((eol = strchr(buffer, '\n')) != NULL) {
+ *eol = '\0';
+ } else {
+ /* Not a valid line, skip it */
+ continue;
+ }
+ if (sites[nsites] != NULL) {
+ TSfree (sites[nsites]);
+ }
+ sites[nsites] = TSstrdup (buffer);
+ nsites++;
+ }
+
+ TSfclose (file);
+ } else {
+ TSError ("[blacklist-1] Unable to open %s", blacklist_file);
+ TSError ("[blacklist-1] All sites will be allowed", blacklist_file);
+ }
+
+ TSMutexUnlock (sites_mutex);
+ }
+
+ static int
+ blacklist_plugin (TSCont contp, TSEvent event, void *edata)
+ {
+ TSHttpTxn txnp = (TSHttpTxn) edata;
+
+ switch (event) {
+ case TS_EVENT_HTTP_OS_DNS:
+ handle_dns (txnp, contp);
+ return 0;
+ case TS_EVENT_HTTP_SEND_RESPONSE_HDR:
+ handle_response (txnp);
+ return 0;
+ case TS_EVENT_MGMT_UPDATE:
+ read_blacklist ();
+ return 0;
+ default:
+ break;
+ }
+ return 0;
+ }
+
+ int
+ check_ts_version()
+ {
+
+ const char *ts_version = TSTrafficServerVersionGet();
+ int result = 0;
+
+ if (ts_version) {
+ int major_ts_version = 0;
+ int minor_ts_version = 0;
+ int patch_ts_version = 0;
+
+ if (sscanf(ts_version, "%d.%d.%d", &major_ts_version, &minor_ts_version, &patch_ts_version) != 3) {
+ return 0;
+ }
+
+ /* Need at least TS 2.0 */
+ if (major_ts_version >= 2) {
+ result = 1;
+ }
+
+ }
+
+ return result;
+ }
+
+ void
+ TSPluginInit (int argc, const char *argv[])
+ {
+ int i;
+ TSCont contp;
+ TSPluginRegistrationInfo info;
+
+ info.plugin_name = "blacklist-1";
+ info.vendor_name = "DsCompany";
+ info.support_email = "ts-api-support@DsCompany.com";
+
+ if (!TSPluginRegister(&info)) {
+ TSError ("[blacklist-1] Plugin registration failed.");
+ }
+
+ if (!check_ts_version()) {
+ TSError ("[blacklist-1] Plugin requires Traffic Server 2.0 or later");
+ return;
+ }
+
+ /* create an TSTextLogObject to log blacklisted requests to */
+ TSReturnCode error = TSTextLogObjectCreate("blacklist", TS_LOG_MODE_ADD_TIMESTAMP,
+ &log);
+ if (error != TS_SUCCESS) {
+ printf("Blacklist plugin: error %d while creating log\n", error);
+ }
+
+ sites_mutex = TSMutexCreate ();
+
+ nsites = 0;
+ for (i = 0; i < MAX_NSITES; i++) {
+ sites[i] = NULL;
+ }
+
+ read_blacklist ();
+
+ contp = TSContCreate (blacklist_plugin, NULL);
+
+ TSHttpHookAdd (TS_HTTP_OS_DNS_HOOK, contp);
+
+ TSMgmtUpdateRegister (contp, "Super Blacklist Plugin", "blacklist.cgi");
+ }
+
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/developer-guide/plugins/example-plugins/blacklist/working-with-http-header-functions.en.rst
----------------------------------------------------------------------
diff --git a/doc/developer-guide/plugins/example-plugins/blacklist/working-with-http-header-functions.en.rst b/doc/developer-guide/plugins/example-plugins/blacklist/working-with-http-header-functions.en.rst
new file mode 100644
index 0000000..f437d93
--- /dev/null
+++ b/doc/developer-guide/plugins/example-plugins/blacklist/working-with-http-header-functions.en.rst
@@ -0,0 +1,64 @@
+.. 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
+
+.. _developer-plugins-examples-blacklist-http-header-functions:
+
+Working with HTTP Header Functions
+**********************************
+
+The Blacklist plugin examines the host header in every client
+transaction. This is done in the ``handle_dns`` routine, using
+``TSHttpTxnClientReqGet``, ``TSHttpHdrUrlGet``, and ``TSUrlHostGet``.
+
+.. code-block:: c
+
+ static void
+ handle_dns (TSHttpTxn txnp, TSCont contp)
+ {
+ TSMBuffer bufp;
+ TSMLoc hdr_loc;
+ TSMLoc url_loc;
+ const char *host;
+ int i;
+ int host_length;
+
+ if (TSHttpTxnClientReqGet(txnp, &bufp, &hdr_loc) != TS_SUCCESS) {
+ TSError("[blacklist] Couldn't retrieve client request header");
+ goto done;
+ }
+
+ if (TSHttpHdrUrlGet(bufp, hdr_loc, &url_loc) != TS_SUCCESS) {
+ TSError("[blacklist] Couldn't retrieve request url");
+ TSHandleMLocRelease(bufp, TS_NULL_MLOC, hdr_loc);
+ goto done;
+ }
+
+ host = TSUrlHostGet(bufp, url_loc, &host_length);
+ if (!host) {
+ TSError("[blacklist] couldn't retrieve request hostname");
+ TSHandleMLocRelease(bufp, hdr_loc, url_loc);
+ TSHandleMLocRelease(bufp, TS_NULL_MLOC, hdr_loc);
+ goto done;
+ }
+
+To access the host header, the plugin must first get the client request,
+retrieve the URL portion, and then obtain the host header. See
+:ref:`developer-plugins-http-headers` for more information about these calls.
+See :ref:`developer-plugins-http-headers-marshal-buffers`
+for guidelines on using ``TSHandleMLocRelease``.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/developer-guide/plugins/example-plugins/index.en.rst
----------------------------------------------------------------------
diff --git a/doc/developer-guide/plugins/example-plugins/index.en.rst b/doc/developer-guide/plugins/example-plugins/index.en.rst
new file mode 100644
index 0000000..4e120c4
--- /dev/null
+++ b/doc/developer-guide/plugins/example-plugins/index.en.rst
@@ -0,0 +1,78 @@
+.. 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
+
+.. _developer-plugins-examples:
+
+Example Plugins
+***************
+
+.. toctree::
+ :maxdepth: 2
+
+ basic-authorization/index.en
+ blacklist/index.en
+ query-remap/index.en
+
+.. _developer-plugins-header-based-examples:
+
+Header-Based Plugin Examples
+============================
+
+Header-based plugins read or modify the headers of HTTP messages that
+Traffic Server sends and receives. Reading this chapter will help you to
+understand the following topics:
+
+- Creating continuations for your plugins
+
+- Adding global hooks
+
+- Adding transaction hooks
+
+- Working with HTTP header functions
+
+The two sample plugins discussed in this chapter are ``blacklist-1.c``
+and ``basic-auth.c``.
+
+Overview
+--------
+
+Header-based plugins take actions based on the contents of HTTP request
+or response headers. Examples include filtering (on the basis of
+requested URL, source IP address, or other request header), user
+authentication, or user redirection. Header-based plugins have the
+following common elements:
+
+- The plugin has a static parent continuation that scans all Traffic
+ Server headers (either request headers, response headers, or both).
+
+- The plugin has a global hook. This enables the plugin to check all
+ transactions to determine if the plugin needs to do something.
+
+- The plugin gets a handle to the transaction being processed through
+ the global hook.
+
+- If the plugin needs to do something to transactions in specific
+ cases, then it sets up a transaction hook for a particular event.
+
+- The plugin obtains client header information and does something based
+ on that information.
+
+This chapter demonstrates how these components are implemented in SDK
+sample code.
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/developer-guide/plugins/example-plugins/query-remap/example-query-remap.en.rst
----------------------------------------------------------------------
diff --git a/doc/developer-guide/plugins/example-plugins/query-remap/example-query-remap.en.rst b/doc/developer-guide/plugins/example-plugins/query-remap/example-query-remap.en.rst
new file mode 100644
index 0000000..5d6ed9b
--- /dev/null
+++ b/doc/developer-guide/plugins/example-plugins/query-remap/example-query-remap.en.rst
@@ -0,0 +1,152 @@
+.. 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
+
+Example: Query Remap Plugin
+***************************
+
+The sample remap plugin, ``query_remap.c``, maps client requests to a
+number of servers based on a hash of the request's URL query parameter.
+This can be useful for spreading load for a given type of request among
+backend servers, while still maintaining "stickiness" to a single server
+for similar requests. For example, a search engine may want to send
+repeated queries for the same keywords to a server that has likely
+cached the result from a prior query.
+
+Configuration of query\_remap
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The query remap plugin will allow the query parameter name to be
+specified, along with the hostnames of the servers to hash across.
+Sample ``remap.config`` rules using ``query_remap`` will look like:
+
+::
+
+ map http://www.example.com/search http://srch1.example.com/search @plugin=query_remap.so @pparam=q @pparam=srch1.example.com @pparam=srch2.example.com @pparam=srch3.example.com
+ map http://www.example.com/profiles http://prof1.example.com/profiles @plugin=query_remap.so @pparam=user_id @pparam=prof1.example.com @pparam=prof2.example.com
+
+The first ``@pparam`` specifies the query param key for which the value
+will be hashed. The remaining parameters list the hostnames of the
+servers. A request for ``http://www.example.com/search?q=apache`` will
+match the first rule. The plugin will look for the *``q``* parameter and
+hash the value '``apache``\ ' to pick from among
+``srch_[1-3]_.example.com`` to send the request.
+
+If the request does not include a *``q``* query parameter and the plugin
+decides not to modify the request, the default toURL
+'``http://srch1.example.com/search``\ ' will be used by TS.
+
+The parameters are passed to the plugin's ``tsremap_new_instance``
+function. In ``query_remap``, ``tsremap_new_instance`` creates a
+plugin-defined ``query_remap_info`` struct to store its configuration
+parameters. The ihandle, an opaque pointer that can be used to pass
+per-instance data, is set to this struct pointer and will be passed to
+the ``tsremap_remap`` function when it is triggered for a request.
+
+.. code-block:: c
+
+ typedef struct _query_remap_info {
+ char *param_name;
+ size_t param_len;
+ char **hosts;
+ int num_hosts;
+ } query_remap_info;
+
+
+ int tsremap_new_instance(int argc,char *argv[],ihandle *ih,char *errbuf,int errbuf_size)
+ {
+ int i;
+
+ if (argc param_name = strdup(argv[2]);
+ qri->param_len = strlen(qri->param_name);
+ qri->num_hosts = argc - 3;
+ qri->hosts = (char**) TSmalloc(qri->num_hosts*sizeof(char*));
+
+ for (i=0; i num_hosts; ++i) {
+ qri->hosts[i] = strdup(argv[i+3]);
+ }
+
+ *ih = (ihandle)qri;
+ return 0;
+ }
+
+Another way remap plugins may want handle more complex configuration is
+to specify a configuration filename as a ``pparam`` and parse the
+specified file during instance initialization.
+
+Performing the Remap
+~~~~~~~~~~~~~~~~~~~~
+
+The plugin implements the ``tsremap_remap`` function, which is called
+when TS has read the client HTTP request headers and matched the request
+to a remap rule configured for the plugin. The ``TSRemapRequestInfo``
+struct contains input and output members for the remap operation.
+
+``tsremap_remap`` uses the configuration information passed via the
+``ihandle`` and checks the ``request_query`` for the configured query
+parameter. If the parameter is found, the plugin sets a ``new_host`` to
+modify the request host:
+
+.. code-block:: c
+
+ int tsremap_remap(ihandle ih, rhandle rh, TSRemapRequestInfo *rri)
+ {
+ int hostidx = -1;
+ query_remap_info *qri = (query_remap_info*)ih;
+
+ if (!qri) {
+ TSError("[remap] NULL ihandle");
+ return 0;
+ }
+
+ if (rri && rri->request_query && rri->request_query_size > 0) {
+ char *q, *s, *key;
+
+ //make a copy of the query, as it is read only
+ q = (char*) TSmalloc(rri->request_query_size+1);
+ strncpy(q, rri->request_query, rri->request_query_size);
+ q[rri->request_query_size] = '\0';
+
+ s = q;
+ //parse query parameters
+ for (key = strsep(&s, "&"); key != NULL; key = strsep(&s, "&")) {
+ char *val = strchr(key, '=');
+ if (val && (size_t)(val-key) == qri->param_len &&
+ !strncmp(key, qri->param_name, qri->param_len)) {
+ ++val;
+ //the param key matched the configured param_name
+ //hash the param value to pick a host
+ hostidx = hash_fnv32(val, strlen(val)) % (uint32_t)qri->num_hosts;
+ break;
+ }
+ }
+
+ TSfree(q);
+
+ if (hostidx >= 0) {
+ rri->new_host_size = strlen(qri->hosts[hostidx]);
+ if (rri->new_host_size new_host, qri->hosts[hostidx], rri->new_host_size);
+ return 1; //host has been modified
+ }
+ }
+ }
+
+ //the request was not modified, TS will use the toURL from the remap rule
+ return 0;
+ }
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/developer-guide/plugins/example-plugins/query-remap/index.en.rst
----------------------------------------------------------------------
diff --git a/doc/developer-guide/plugins/example-plugins/query-remap/index.en.rst b/doc/developer-guide/plugins/example-plugins/query-remap/index.en.rst
new file mode 100644
index 0000000..4c8a3e2
--- /dev/null
+++ b/doc/developer-guide/plugins/example-plugins/query-remap/index.en.rst
@@ -0,0 +1,75 @@
+.. 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
+
+.. _developer-plugins-examples-query-remap:
+
+Query Remap Plugin
+******************
+
+.. toctree::
+ :maxdepth: 2
+
+ example-query-remap.en
+
+The Remap plugin provides a more flexible, dynamic way of specifying
+remap rules. It is not built on top of the Traffic Server APIs and
+exists solely for the purpose of URL remapping. The remap plugin is not
+global --it is configured on a per-remap rule basis, which enables you
+to customize how URLs are redirected based on individual rules in the
+``remap.config`` file.
+
+The Traffic Server Remap API enables a plugin to dynamically map a
+client request to a target URL. Each plugin is associated with one or
+more remap rules in ``remap.config`` (an "instance"). If a request URL
+matches a remap rule's "fromURL", then Traffic Server calls the
+plugin-defined remap function for that request.
+
+((Editor's note: additional text TBD; text in this chapter is still
+under development))
+
+Remap Header File
+=================
+
+The ``remap.h`` header file contains the Traffic Server remap API. By
+default, the header file location is: ``/usr/local/include/ts/remap.h``
+
+Required Functions
+==================
+
+A remap plugin is required to implement the following functions:
+
+- `TSRemapInit <http://people.apache.org/~amc/ats/doc/html/remap_8h.html#af7e9b1eee1c38c6f8dcc67a65ba02c24>`_:
+ the remap initialization function, called once when the plugin is
+ loaded
+
+- `TSRemapNewInstance <http://people.apache.org/~amc/ats/doc/html/remap_8h.html#a963de3eeed2ed7a2da483acf77dc42ca>`_:
+ a new instance is created for each rule associated with the plugin.
+ Called each time the plugin used in a remap rule (this function is
+ what processes the pparam values)
+
+- `TSRemapDoRemap <http://people.apache.org/~amc/ats/doc/html/remap_8h.html#acf73f0355c591e145398211b3c0596fe>`_:
+ the entry point used by Traffic Server to find the new URL to which
+ it remaps; called every time a request comes in
+
+Configuration
+~~~~~~~~~~~~~
+
+To associate a remap plugin with a remap rule, use the ``@plugin``
+parameter. See the Admin Guide section (?TBD?) for details on
+configuring remap plugins
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/developer-guide/plugins/getting-started/a-simple-plugin.en.rst
----------------------------------------------------------------------
diff --git a/doc/developer-guide/plugins/getting-started/a-simple-plugin.en.rst b/doc/developer-guide/plugins/getting-started/a-simple-plugin.en.rst
new file mode 100644
index 0000000..64bed89
--- /dev/null
+++ b/doc/developer-guide/plugins/getting-started/a-simple-plugin.en.rst
@@ -0,0 +1,126 @@
+.. 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
+
+.. _developer-plugins-getting-started-simple-plugin:
+
+A Simple Plugin
+***************
+
+This section describes how to write, compile, configure, and run a
+simple Traffic Server plugin. You'll follow the steps below:
+
+1. Make sure that your plugin source code contains an ``TSPluginInit``
+ initialization function.
+
+2. Compile your plugin source code, creating a shared library.
+
+3. Add an entry to your plugin's ``plugin.config`` file.
+
+4. Add the path to your plugin shared library into the
+ :file:`records.config` file.
+
+5. Restart Traffic Server.
+
+Compile Your Plugin
+~~~~~~~~~~~~~~~~~~~
+
+The process for compiling a shared library varies with the platform
+used, so the Traffic Server API provides the tsxs tool which you can use
+to create shared libraries on all the supported Traffic Server
+platforms.
+
+Example
+^^^^^^^
+
+Assuming the sample program is stored in the file ``hello-world.c``, you
+could use the following commands to build a shared library
+
+::
+
+ tsxs -o hello-world.so -c hello-world.c
+
+tsxs can be found in ``trafficserver-dev`` package.
+
+This shared library will be your plugin. In order to install it, run
+
+::
+
+ sudo tsxs -o hello-world.so -i
+
+or the equivalent to ``sudo`` on your platform.
+
+Update the ``plugin.config`` File
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Your next step is to tell Traffic Server about the plugin by adding the
+following line to the ``plugin.config`` file. Since our simple plugin
+does not require any arguments, the following ``plugin.config`` will
+work:
+
+::
+
+ # a simple plugin.config for hello-world
+ hello-world.so
+
+Traffic Server can accommodate multiple plugins. If several plugin
+functions are triggered by the same event, then Traffic Server invokes
+each plugin's function in the order each was defined in the
+``plugin.config`` file.
+
+.. _specify-the-plugins-location:
+
+Specify the Plugin's Location
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+All plugins must be located in the directory specified by the
+configuration variable ``proxy.config.plugin.plugin_dir``, which is
+located in the :file:`records.config` file. The directory can be specified
+as an absolute or relative path.
+
+If a relative path is used, then the starting directory will be the
+Traffic Server installation directory as specified in
+``/etc/traffic_server``. The default value is ``libexec/trafficserver``,
+but this can vary based on how the software was configured and built. It
+is common to use the default directory. Be sure to place the shared
+library ``hello-world.so`` inside the directory you've configured.
+
+Restart Traffic Server
+~~~~~~~~~~~~~~~~~~~~~~
+
+The last step is to start/restart Traffic Server. Shown below is the
+output displayed after you've created and loaded your ``hello-world``
+plugin.
+
+::
+
+ # ls libexec/trafficserver
+ hello-world.so*
+ # bin/traffic_server
+ [Mar 27 19:06:31.669] NOTE: updated diags config
+ [Mar 27 19:06:31.680] NOTE: loading plugin 'libexec/trafficserver/hello-world.so'
+ hello world
+ [Mar 27 19:06:32.046] NOTE: cache disabled (initializing)
+ [Mar 27 19:06:32.053] NOTE: cache enabled
+ [Mar 27 19:06:32.526] NOTE: Traffic Server running
+
+**Note:** in the example above, Traffic Server notes are directed to the
+console by specifying ``E`` for ``proxy.config.diags.output.note`` in
+:file:`records.config`. The second note shows Traffic Server attempting to
+load the ``hello-world`` plugin. The third line of Traffic Server output
+is from your plugin.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/developer-guide/plugins/getting-started/index.en.rst
----------------------------------------------------------------------
diff --git a/doc/developer-guide/plugins/getting-started/index.en.rst b/doc/developer-guide/plugins/getting-started/index.en.rst
new file mode 100644
index 0000000..2ded690
--- /dev/null
+++ b/doc/developer-guide/plugins/getting-started/index.en.rst
@@ -0,0 +1,246 @@
+.. 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
+
+.. _developer-plugins-getting-started:
+
+Getting Started
+***************
+
+.. toctree::
+ :maxdepth: 2
+
+ a-simple-plugin.en
+ plugin-registration-and-version-checking.en
+ naming-conventions.en
+
+The Traffic Server API enables you to create plugins, using the C
+programming language, that customize the behavior of your Traffic Server
+installation. This chapter contains the following sections:
+
+- `Understanding Traffic Server Plugins`_ -- a brief introduction to plugins.
+
+- :ref:`developer-plugins-getting-started-simple-plugin` -- walks through
+ compiling and loading an example ``hello world`` plugin.
+
+- :ref:`developer-plugins-getting-started-registration` -- shows
+ you how to register your plugin and make sure it's compatible with the
+ version of Traffic Server you're using.
+
+- :ref:`developer-plugins-getting-started-naming` -- outlines Traffic
+ Server API naming conventions. For guidelines on creating plugin
+ source code, see :ref:`developer-plugins-introduction`.
+
+Understanding Traffic Server Plugins
+====================================
+
+Traffic Server enables sophisticated caching and processing of
+web-related traffic, such as DNS and HTTP requests and responses.
+
+Traffic Server itself consists of an event-driven loop that can be
+simplified as follows:
+
+.. code-block:: c
+
+ for (;;) {
+ event = get_next_event();
+ handle_event (event);
+ }
+
+The Role of Plugins
+-------------------
+
+You compile your plugin source code to create a shared library that
+Traffic Server loads when it is started. Your plugin contains callback
+functions that are registered for specific Traffic Server events. When
+Traffic Server needs to process an event, it invokes any and all
+call-back functions you've registered for that event type.
+
+.. caution::
+
+ Since plugins add object code to Traffic Server, programming errors in a
+ plugin can have serious implications. Bugs in your plugin, such as an
+ out-of-range pointer, can cause Traffic Server processes to crash and
+ may ultimately result in unpredictable behavior.
+
+**Plugin Process**
+
+.. _PluginProcess:
+
+.. figure:: /static/images/sdk/plugin_process.jpg
+ :align: center
+ :alt: Plugin Process
+
+ Plugin Process
+
+Possible Uses for Plugins
+-------------------------
+
+Possible uses for plugins include the following:
+
+- HTTP processing: plugins can filter, blacklist, authorize users,
+ transform content
+
+- Protocol support: plugins can enable Traffic Server to proxy-cache
+ new protocol content
+
+Some examples of plugins include:
+
+- **Blacklisting plugin**: denies attempts to access web sites that are
+ off-limits.
+
+- **Append transform plugin**: adds text to HTTP response content.
+
+- **Image conversion plugin**: transforms JPEG images to GIF images.
+
+- **Compression plugin**: sends response content to a compression
+ server that compresses the data (alternatively, a compression library
+ local to the Traffic Server host machine could do the compression).
+
+- **Authorization plugin**: checks a user's permissions to access
+ particular web sites. The plugin could consult a local authorization
+ program or send queries to an authorization server.
+
+- **A plugin that gathers client information** from request headers and
+ enters this information in a database.
+
+- **Protocol plugin**: listens for specific protocol requests on a
+ designated port and then uses Traffic Server's proxy server & cache
+ to serve client requests.
+
+The figure below, :ref:`possibleTSplugins`, illustrates several types of plugins.
+
+**Possible Traffic Server Plugins**
+
+.. _possibleTSplugins:
+
+.. figure:: /static/images/sdk/Uses.jpg
+ :align: center
+ :alt: Possible Traffic Server Plugins
+
+ Possible Traffic Server Plugins
+
+You can find basic examples for many plugins in the SDK sample code:
+
+- ``append-transform.c`` adds text from a specified file to HTTP/text
+ responses. This plugin is explained in
+ :ref:`developer-plugins-http-transformations-append`
+
+- The compression plugin in the figure communicates with the server
+ that actually does the compression. The ``server-transform.c`` plugin
+ shows how to open a connection to a transformation server, have the
+ server do the transformation, and send transformed data back to the
+ client. Although the transformation is null in
+ ``server-transform.c``, a compression or image translation plugin
+ could be implemented in a similar way.
+
+- ``basic-auth.c`` performs basic HTTP proxy authorization.
+
+- ``blacklist-1.c`` reads blacklisted servers from a configuration file
+ and denies client access to these servers. This plugin is explained
+ in :ref:`developer-plugins-examples-blacklist`.
+
+Plugin Loading
+--------------
+
+When Traffic Server is first started, it consults the ``plugin.config``
+file to determine the names of all shared plugin libraries that need to
+be loaded. The ``plugin.config`` file also defines arguments that are to
+be passed to each plugin's initialization function, ``TSPluginInit``.
+The :file:`records.config` file defines the path to each plugin shared
+library, as described in :ref:`specify-the-plugins-location`.
+
+.. note:: The path for each of these files is *<root_dir>*\ ``/config/``, where *<root_dir>* is where you installed Traffic Server.
+
+Plugin Configuration
+--------------------
+
+The sample ``plugin.config`` file below contains a comment line, a blank
+line, and two plugin configurations:
+
+::
+
+ # This is a comment line.
+
+ my-plugin.so junk.example.com trash.example.org garbage.example.edu
+ some-plugin.so arg1 arg2 $proxy.config.http.cache.on
+
+Each plugin configuration in the ``plugin.config`` file resembles a UNIX
+or DOS shell command; each line in ``plugin.config`` cannot exceed 1023
+characters.
+
+The first plugin configuration is for a plugin named ``my-plugin.so``.
+It contains three arguments that are to be passed to that plugin's
+initialization routine. The second configuration is for a plugin named
+``some-plugin.so``; it contains three arguments. The last argument,
+*``$proxy.config.http.cache.on``*, is actually a configuration variable.
+Traffic Server will look up the specified configuration variable and
+substitute its value.
+
+Plugins with global variables should not appear more than once in
+``plugin.config``. For example, if you enter:
+
+::
+
+ add-header.so header1
+ add-header.so header2
+
+then the second global variable, ``header2``, will be used for both
+instances. A simple workaround is to give different names to different
+instances of the same plugin. For example:
+
+::
+
+ cp add-header.so add-header1.so
+ cp add-header.so add-header2.so
+
+These entries will produce the desired result below:
+
+::
+
+ add-header1.so header1
+ add-header2.so header2
+
+Configuration File Rules
+------------------------
+
+- Comment lines begin with **#** and continue to the end of the line.
+
+- Blank lines are ignored.
+
+- Plugins are loaded and initialized by Traffic Server in the order
+ they appear in the ``plugin.config`` file.
+
+Plugin Initialization
+---------------------
+
+Each plugin must define an initialization function named
+``TSPluginInit`` that Traffic Server invokes when the plugin is loaded.
+The ``TSPluginInit`` function is commonly used to read configuration
+information and register hooks for event notification.
+
+The ``TSPluginInit`` function has two arguments:
+
+- The ``argc`` argument represents the number of arguments defined in
+ the ``plugin.config`` file for that particular plugin
+
+- The ``argv`` argument is an array of pointers to the actual arguments
+ defined in the ``plugin.config`` file for that plugin
+
+See :c:func:`TSPluginInit` for details about ``TSPluginInit``.
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/developer-guide/plugins/getting-started/naming-conventions.en.rst
----------------------------------------------------------------------
diff --git a/doc/developer-guide/plugins/getting-started/naming-conventions.en.rst b/doc/developer-guide/plugins/getting-started/naming-conventions.en.rst
new file mode 100644
index 0000000..8824977
--- /dev/null
+++ b/doc/developer-guide/plugins/getting-started/naming-conventions.en.rst
@@ -0,0 +1,55 @@
+.. 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
+
+.. _developer-plugins-getting-started-naming:
+
+Naming Conventions
+******************
+
+The Traffic Server API adheres to the following naming conventions:
+
+- The ``TS`` prefix is used for all function and variable names defined
+ in the Traffic Server API. **Examples**:
+ ``TS_EVENT_NONE``,\ ``TSMutex``, and ``TSContCreate``
+
+- Enumerated values are always written in all uppercase letters.
+ **Examples**: ``TS_EVENT_NONE`` and ``TS_VC_CLOSE_ABORT``
+
+- Constant values are all uppercase; enumerated values can be seen as a
+ subset of constants. **Examples**: ``TS_URL_SCHEME_FILE`` and
+ ``TS_MIME_FIELD_ACCEPT``
+
+- The names of defined types are mixed-case. **Examples**:
+ ``TSHttpSsn`` and ``TSHttpTxn``
+
+- Function names are mixed-case. **Examples**: ``TSUrlCreate`` and
+ ``TSContDestroy``
+
+- Function names use the following subject-verb naming style:
+ ``TS-<subject>-<verb>``, where ``<subject>`` goes from general to
+ specific. This makes it easier to determine what a function does by
+ reading its name. **For** **example**: the function to retrieve the
+ password field (the specific subject) from a URL (the general
+ subject) is ``TSUrlPasswordGet``.
+
+- Common verbs like ``Create``, ``Destroy``, ``Get``, ``Set``,
+ ``Copy``, ``Find``, ``Retrieve``, ``Insert``, ``Remove``, and
+ ``Delete`` are used only when appropriate.
+
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/developer-guide/plugins/getting-started/plugin-registration-and-version-checking.en.rst
----------------------------------------------------------------------
diff --git a/doc/developer-guide/plugins/getting-started/plugin-registration-and-version-checking.en.rst b/doc/developer-guide/plugins/getting-started/plugin-registration-and-version-checking.en.rst
new file mode 100644
index 0000000..dd4c287
--- /dev/null
+++ b/doc/developer-guide/plugins/getting-started/plugin-registration-and-version-checking.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
+
+.. _developer-plugins-getting-started-registration:
+
+Plugin Registration and Version Checking
+****************************************
+
+Make sure that the functions in your plugin are supported in your
+version of Traffic Server.
+
+Use the following interfaces:
+
+- `TSPluginRegister <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a6d7f514e70abaf097c4a3f1ba01f6df8>`_
+- `TSTrafficServerVersionGet <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a3ef91e01612ffdce6dd040f836db08e8>`_
+
+The following version of ``hello-world`` registers the plugin and
+ensures it's running with a compatible version of Traffic Server.
+
+.. code-block:: c
+
+ #include <stdio.h>
+ #include <ts/ts.h>
+ int
+ check_ts_version()
+ {
+
+ const char *ts_version = TSTrafficServerVersionGet();
+ int result = 0;
+
+ if (ts_version) {
+ int major_ts_version = 0;
+ int minor_ts_version = 0;
+ int patch_ts_version = 0;
+
+ if (sscanf(ts_version, "%d.%d.%d", &major_ts_version,
+ &minor_ts_version, &patch_ts_version) != 3) {
+ return 0;
+ }
+
+ /* We need at least Traffic Server 2.0 */
+
+ if (major_ts_version >= 2) {
+ result = 1;
+ }
+
+ }
+
+ return result;
+ }
+
+ void
+ TSPluginInit (int argc, const char *argv[])
+ {
+
+ TSPluginRegistrationInfo info;
+
+ info.plugin_name = "hello-world";
+ info.vendor_name = "MyCompany";
+ info.support_email = "ts-api-support@MyCompany.com";
+
+ if (!TSPluginRegister(&info)) {
+ TSError ("[plugin_name] Plugin registration failed.");
+ }
+
+ if (!check_ts_version()) {
+ TSError ("[plugin_name] Plugin requires Traffic Server 2.0 or later");
+ return;
+ }
+
+ TSDebug ("debug-hello", "Hello World!\n");
+ }
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/developer-guide/plugins/hooks-and-transactions/adding-hooks.en.rst
----------------------------------------------------------------------
diff --git a/doc/developer-guide/plugins/hooks-and-transactions/adding-hooks.en.rst b/doc/developer-guide/plugins/hooks-and-transactions/adding-hooks.en.rst
new file mode 100644
index 0000000..3b6e004
--- /dev/null
+++ b/doc/developer-guide/plugins/hooks-and-transactions/adding-hooks.en.rst
@@ -0,0 +1,155 @@
+.. 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
+
+.. _developer-plugins-hooks-adding:
+
+Adding Hooks
+************
+
+There are several ways to add hooks to your plugin.
+
+- **Global HTTP hooks** HTTP transaction hooks are set on a global
+ basis using the function ``TSHttpHookAdd``. This means that the
+ continuation specified as the parameter to ``TSHttpHookAdd`` is
+ called for every transaction. ``TSHttpHookAdd`` must be used in
+ ``TSPluginInit``.
+
+- **Transaction hooks** Transaction hooks can be used to call plugins
+ back for a specific HTTP transaction. You cannot add transaction
+ hooks in ``TSPluginInit``; you first need a handle to a transaction.
+ See :ref:`developer-plugins-blacklist-access-process-txn`.
+
+- **Transformation hooks** Transformation hooks are a special case of
+ transaction hooks. See
+ :c:func:`TSVConnCacheObjectSizeGet`
+ for more information about transformation hooks. You add a
+ transformation hook using ``TSHttpTxnHookAdd``, as described in
+ :ref:`developer-plugins-hooks-http-transactions`.
+
+- **Session hooks** An HTTP session starts when a client opens a
+ connection to Traffic Server and ends when the connection closes. A
+ session can consist of several transactions. Session hooks enable you
+ to hook your plugin to a particular point in every transaction within
+ a specified session (see :doc:`HTTP Sessions <http-sessions.en>`).
+ Session hooks are added in a manner similar to transaction hooks (ie,
+ you first need a handle to an HTTP session).
+
+- **HTTP select alternate hook** Alternate selection hooks enable you
+ to hook on to the alternate selection state. These hooks must be
+ added globally, since Traffic Server does not have a handle to a
+ transaction or session when alternate selection is taking place. See
+ :doc:`HTTP Alternate Selection <http-alternate-selection.en>` for
+ information on the alternate selection mechanism.
+
+All of the hook addition functions
+(:c:func:`TSHttpHookAdd`,
+:c:func:`TSHttpSsnHookAdd`,
+:c:func:`TSHttpSsnReenable`)
+take ``TSHttpHookID`` (identifies the hook to add on to) and ``TSCont``
+(the basic callback mechanism in Traffic Server). A single ``TSCont``
+can be added to any number of hooks at a time.
+
+An HTTP hook is identified by the enumerated type ``TSHttpHookID``. The
+values for ``TSHttpHookID`` are:
+
+**Values for TSHttpHookID**
+
+``TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK``
+ Called after the HTTP state machine has completed the cache lookup
+ for the document requested in the ongoing transaction. Register this
+ hook via ``TSHttpTxnHookAdd`` or ``TSHttpHookAdd``. Corresponds to
+ the event ``TS_EVENT_HTTP_CACHE_LOOKUP_COMPLETE``.
+
+``TS_HTTP_OS_DNS_HOOK``
+ Called immediately after the HTTP state machine has completed a DNS
+ lookup of the origin server. The HTTP state machine will know the
+ origin server's IP address at this point, which is useful for
+ performing both authentication and blacklisting. Corresponds to the
+ event ``TS_EVENT_HTTP_OS_DNS``.
+
+``TS_HTTP_POST_REMAP_HOOK``
+ Called immediately after remapping occurs, before cache lookup.
+ Corresponds to the event ``TS_EVENT_HTTP_POST_REMAP``.
+
+``TS_HTTP_PRE_REMAP_HOOK``
+ Called after the request header is read from the client, before any
+ remapping of the headers occurs. Corresponds to the event
+ ``TS_EVENT_HTTP_PRE_REMAP``.
+
+``TS_HTTP_READ_CACHE_HDR_HOOK``
+ Called immediately after the request and response header of a
+ previously-cached object is read from cache. This hook is only
+ called if the document is being served from cache. Corresponds to
+ the event ``TS_EVENT_HTTP_READ_CACHE_HDR``.
+
+``TS_HTTP_READ_RESPONSE_HDR_HOOK``
+ Called immediately after the response header is read from the origin
+ server or parent proxy. Corresponds to the event
+ ``TS_EVENT_HTTP_READ_RESPONSE_HDR``.
+
+``TS_HTTP_RESPONSE_TRANSFORM_HOOK``
+ See :ref:`"Transformations" <transformations>`
+ for information about transformation hooks.
+
+``TS_HTTP_READ_REQUEST_HDR_HOOK``
+ Called immediately after the request header is read from the client.
+ Corresponds to the event ``TS_EVENT_HTTP_READ_REQUEST_HDR``.
+
+``TS_HTTP_REQUEST_TRANSFORM_HOOK``
+ See :ref:`"Transformations" <transformations>`
+ for information about transformation hooks.
+
+``TS_HTTP_SELECT_ALT_HOOK``
+ See :doc:`"HTTP Alternate Selection" <http-alternate-selection.en>` for
+ information about the alternate selection mechanism.
+
+``TS_HTTP_SEND_RESPONSE_HDR_HOOK``
+ Called immediately before the proxy's response header is written to
+ the client; this hook is usually used for modifying the response
+ header. Corresponds to the event
+ ``TS_EVENT_HTTP_SEND_RESPONSE_HDR``.
+
+``TS_HTTP_SEND_REQUEST_HDR_HOOK``
+ Called immediately before the proxy's request header is sent to the
+ origin server or the parent proxy. This hook is not called if the
+ document is being served from cache. This hook is usually used for
+ modifying the proxy's request header before it is sent to the origin
+ server or parent proxy.
+
+``TS_HTTP_SSN_CLOSE_HOOK``
+ Called when an HTTP session ends. A session ends when the client
+ connection is closed. You can only add this hook as a global hook
+
+``TS_HTTP_SSN_START_HOOK``
+ Called when an HTTP session is started. A session starts when a
+ client connects to Traffic Server. You can only add this hook as a
+ global hook.
+
+``TS_HTTP_TXN_CLOSE_HOOK``
+ Called when an HTTP transaction ends.
+
+``TS_HTTP_TXN_START_HOOK``
+ Called when an HTTP transaction is started. A transaction starts
+ when either a client connects to Traffic Server and data is
+ available on the connection, or a previous client connection that
+ was left open for keep alive has new data available.
+
+The function you use to add a global HTTP hook is
+:c:func:`TSHttpHookAdd`.
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/developer-guide/plugins/hooks-and-transactions/http-alternate-selection.en.rst
----------------------------------------------------------------------
diff --git a/doc/developer-guide/plugins/hooks-and-transactions/http-alternate-selection.en.rst b/doc/developer-guide/plugins/hooks-and-transactions/http-alternate-selection.en.rst
new file mode 100644
index 0000000..6358e74
--- /dev/null
+++ b/doc/developer-guide/plugins/hooks-and-transactions/http-alternate-selection.en.rst
@@ -0,0 +1,193 @@
+.. 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
+
+.. _developer-plugins-hooks-alternate-selection:
+
+HTTP Alternate Selection
+************************
+
+The HTTP alternate selection functions provide a mechanism for hooking
+into Traffic Server's alternate selection mechanism and augmenting it
+with additional information. **HTTP alternate selection** refers to the
+process of choosing between several alternate versions of a document for
+a specific URL. Alternates arise because the HTTP 1.1 specification
+allows different documents to be sent back for the same URL (depending
+on the clients request). For example, a server might send back a GIF
+image to a client that only accepts GIF images, and might send back a
+JPEG image to a client that only accepts JPEG images.
+
+The alternate selection mechanism is invoked when Traffic Server looks
+up a URL in its cache. For each URL, Traffic Server stores a vector of
+alternates. For each alternate in this vector, Traffic Server computes a
+quality value between 0 and 1 that represents how "good" the alternate
+is. A quality value of 0 means that the alternate is unacceptable; a
+value of 1 means that the alternate is a perfect match.
+
+If a plugin hooks onto the ``TS_HTTP_SELECT_ALT_HOOK``, then it will be
+called back when Traffic Server performs alternate selection. You cannot
+register locally to the hook ``TS_HTTP_SELECT_ALT_HOOK`` by using
+``TSHttpTxnHookAdd`` - you can only do so by using only
+``TSHttpHookAdd``. Since Traffic Server does not actually have an HTTP
+transaction or an HTTP session on hand when alternate selection is
+performed, it is only valid to hook onto the global list of
+``TS_HTTP_SELECT_ALT_HOOK``. Traffic Server calls each of the select
+alternate hooks with the ``TS_EVENT_HTTP_SELECT_ALT`` event. The
+``void *edata`` argument that is passed to the continuation is a pointer
+to an ``TSHttpAltInfo`` structure. It can be used later to call the HTTP
+alternate selection functions listed at the end of this section. Unlike
+other hooks, this alternate selection callout is non-blocking; the
+expectation is that the quality value for the alternate will be changed
+by a call to ``TSHttpAltInfoQualitySet``.
+
+.. note::
+
+ HTTP SM does not have to be reenabled using ``TSHttpTxnReenable`` or any
+ other APIs; just return from the function.
+
+The sample code below shows how to call the alternate APIs.
+
+.. code-block:: c
+
+ static void handle_select_alt(TSHttpAltInfo infop)
+ {
+ TSMBuffer client_req_buf, cache_resp_buf;
+ TSMLoc client_req_hdr, cache_resp_hdr;
+
+ TSMLoc accept_transform_field;
+ TSMLoc content_transform_field;
+
+ int accept_transform_len = -1, content_transform_len = -1;
+ const char* accept_transform_value = NULL;
+ const char* content_transform_value = NULL;
+ int content_plugin, accept_plugin;
+
+ float quality;
+
+ /* get client request, cached request and cached response */
+ TSHttpAltInfoClientReqGet (infop, &client_req_buf, &client_req_hdr);
+ TSHttpAltInfoCachedRespGet(infop, &cache_resp_buf, &cache_resp_hdr);
+
+ /* get the Accept-Transform field value from the client request */
+ accept_transform_field = TSMimeHdrFieldFind(client_req_buf,
+ client_req_hdr, "Accept-Transform", -1);
+ if (accept_transform_field) {
+ TSMimeHdrFieldValueStringGet(client_req_buf, client_req_hdr,
+ accept_transform_field, 0, &accept_transform_value, &accept_transform_len);
+ TSDebug(DBG_TAG, "Accept-Transform = |%s|",
+ accept_transform_value);
+ }
+
+ /* get the Content-Transform field value from cached server response */
+ content_transform_field = TSMimeHdrFieldFind(cache_resp_buf,
+ cache_resp_hdr, "Content-Transform", -1);
+ if (content_transform_field) {
+ TSMimeHdrFieldValueStringGet(cache_resp_buf, cache_resp_hdr,
+ content_transform_field, 0, &content_transform_value, &content_transform_len);
+ TSDebug(DBG_TAG, "Content-Transform = |%s|",
+ content_transform_value);
+ }
+
+ /* compute quality */
+ accept_plugin = (accept_transform_value && (accept_transform_len > 0) &&
+ (strncmp(accept_transform_value, "plugin",
+ accept_transform_len) == 0));
+
+ content_plugin = (content_transform_value && (content_transform_len >0) &&
+ (strncmp(content_transform_value, "plugin",
+ content_transform_len) == 0));
+
+ if (accept_plugin) {
+ quality = content_plugin ? 1.0 : 0.0;
+ } else {
+ quality = content_plugin ? 0.0 : 0.5;
+ }
+
+ TSDebug(DBG_TAG, "Setting quality to %3.1f", quality);
+
+ /* set quality for this alternate */
+ TSHttpAltInfoQualitySet(infop, quality);
+
+ /* cleanup */
+ if (accept_transform_field)
+ TSHandleMLocRelease(client_req_buf, client_req_hdr,
+ accept_transform_field);
+ TSHandleMLocRelease(client_req_buf, TS_NULL_MLOC, client_req_hdr);
+
+ if (content_transform_field)
+ TSHandleMLocRelease(cache_resp_buf, cache_resp_hdr,
+ content_transform_field);
+ TSHandleMLocRelease(cache_resp_buf, TS_NULL_MLOC, cache_resp_hdr);
+ }
+
+ static int alt_plugin(TSCont contp, TSEvent event, void *edata)
+ {
+ TSHttpAltInfo infop;
+
+ switch (event) {
+ case TS_EVENT_HTTP_SELECT_ALT:
+ infop = (TSHttpAltInfo)edata;
+ handle_select_alt(infop);
+ break;
+
+ default:
+ break;
+ }
+
+ return 0;
+ }
+
+ void TSPluginInit (int argc, const char *argv[])
+ {
+ TSHttpHookAdd(TS_HTTP_SELECT_ALT_HOOK, TSContCreate (alt_plugin,
+ NULL));
+ }
+
+Traffic Server augments the alternate selection through these callouts
+using the following algorithm:
+
+1. Traffic Server computes its own quality value for the alternate,
+ taking into account the quality of the accept match, the encoding
+ match, and the language match.
+
+2. Traffic Server then calls out each of the continuations on the global
+ ``TS_HTTP_SELECT_ALT_HOOK``'s list.
+
+3. It multiplies its quality value with the value returned by each
+ callout. Since all of the values are clamped to be between 0 and 1,
+ the final value will be between 0 and 1 as well.
+
+4. This algorithm also ensures that a single callout can block the usage
+ of a given alternate by specifying a quality value of 0.
+
+A common usage for the alternate selection mechanism is when a plugin
+transforms a document for some clients and not for others, but wants to
+store both the transformed and unchanged document. The client's request
+will specify whether it accepted the transformed document. The plugin
+will then determine if the alternate matches this specification and then
+set the appropriate quality level for the alternate.
+
+The HTTP alternate selection functions are:
+
+- `TSHttpAltInfoCachedReqGet <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#af4f3a56716e3e97afd582c7fdb14bcb7>`_
+
+- `TSHttpAltInfoCachedRespGet <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#aff5861ae4a4a7a6ce7b2d669c113b3bb>`_
+
+- `TSHttpAltInfoClientReqGet <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a74d494c6442b6012d8385e92f0e14dee>`_
+
+- `TSHttpAltInfoQualitySet <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a978b7160a048491d5698e0f4c0c79aad>`_
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/developer-guide/plugins/hooks-and-transactions/http-sessions.en.rst
----------------------------------------------------------------------
diff --git a/doc/developer-guide/plugins/hooks-and-transactions/http-sessions.en.rst b/doc/developer-guide/plugins/hooks-and-transactions/http-sessions.en.rst
new file mode 100644
index 0000000..26da265
--- /dev/null
+++ b/doc/developer-guide/plugins/hooks-and-transactions/http-sessions.en.rst
@@ -0,0 +1,56 @@
+.. 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
+
+.. _developer-plugins-hooks-http-sessions:
+
+HTTP Sessions
+*************
+
+An **HTTP session** is an object that is defined for the lifetime of a
+client's TCP session. The Traffic Server API enables you to add a global
+hook to the start or end of an HTTP session, as well as add session
+hooks that call back your plugin for every transaction within a given
+session. When a client connects to Traffic Server, it opens up a TCP
+connection and sends one or more HTTP requests. An individual request
+and its response comprise the HTTP transaction. The **HTTP session**
+begins when the client opens the connection and ends when the connection
+closes.
+
+The HTTP session hooks are:
+
+- ``TS_HTTP_SSN_START_HOOK`` Called when an HTTP session is started (a
+ session starts when a client connects to Traffic Server). This hook
+ must be added as a global hook.
+
+- ``TS_HTTP_SSN_CLOSE_HOOK`` Called when an HTTP session ends (a
+ session ends when the client connection is closed). This hook must be
+ added as a global hook.
+
+Use the session hooks to get a handle to a session (an ``TSHttpSsn``
+object). If you want your plugin to be called back for each transaction
+within the session, then use ``TSHttpSsnHookAdd``.
+
+**Note:** you must reenable the session with ``TSHttpSsnReenable`` after
+processing a session hook.
+
+The session hook functions are listed below:
+
+- :c:func:`TSHttpSsnHookAdd`
+- :c:func:`TSHttpSsnReenable`
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/developer-guide/plugins/hooks-and-transactions/http-transactions.en.rst
----------------------------------------------------------------------
diff --git a/doc/developer-guide/plugins/hooks-and-transactions/http-transactions.en.rst b/doc/developer-guide/plugins/hooks-and-transactions/http-transactions.en.rst
new file mode 100644
index 0000000..28a7f9e
--- /dev/null
+++ b/doc/developer-guide/plugins/hooks-and-transactions/http-transactions.en.rst
@@ -0,0 +1,200 @@
+.. 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
+
+.. _developer-plugins-hooks-http-transactions:
+
+HTTP Transactions
+*****************
+
+The HTTP transaction functions enable you to set up plugin callbacks to
+HTTP transactions and obtain/modify information about particular HTTP
+transactions.
+
+As described in the section on HTTP sessions, an **HTTP transaction** is
+an object defined for the lifetime of a single request from a client and
+the corresponding response from Traffic Server. The **``TSHttpTxn``**
+structure is the main handle given to a plugin for manipulating a
+transaction's internal state. Additionally, an HTTP transaction has a
+reference back to the HTTP session that created it.
+
+The sample code below illustrates how to register locally to a
+transaction and associate data to the transaction.
+
+.. code-block:: c
+
+ /*
+ * Simple plugin that illustrates:
+ * - how to register locally to a transaction
+ * - how to deal with data that's associated with a tranaction
+ *
+ * Note: for readability, error checking is omitted
+ */
+
+ #include <ts/ts.h>
+
+ #define DBG_TAG "txn"
+
+ /* Structure to be associated to txns */
+ typedef struct {
+ int i;
+ float f;
+ char *s;
+ } TxnData;
+
+ /* Allocate memory and init a TxnData structure */
+ TxnData *
+ txn_data_alloc()
+ {
+ TxnData *data;
+ data = TSmalloc(sizeof(TxnData));
+
+ data->i = 1;
+ data->f = 0.5;
+ data->s = "Constant String";
+ return data;
+ }
+
+ /* Free up a TxnData structure */
+ void
+ txn_data_free(TxnData *data)
+ {
+ TSfree(data);
+ }
+
+ /* Handler for event READ_REQUEST and TXN_CLOSE */
+ static int
+ local_hook_handler (TSCont contp, TSEvent event, void *edata)
+ {
+ TSHttpTxn txnp = (TSHttpTxn) edata;
+ TxnData *txn_data = TSContDataGet(contp);
+ switch (event) {
+ case TS_EVENT_HTTP_READ_REQUEST_HDR:
+ /* Modify values of txn data */
+ txn_data->i = 2;
+ txn_data->f = 3.5;
+ txn_data->s = "Constant String 2";
+ break;
+
+ case TS_EVENT_HTTP_TXN_CLOSE:
+ /* Print txn data values */
+ TSDebug(DBG_TAG, "Txn data i=%d f=%f s=%s", txn_data->i, txn_data->f, txn_data->s);
+
+ /* Then destroy the txn cont and its data */
+ txn_data_free(txn_data);
+ TSContDestroy(contp);
+ break;
+
+ default:
+ TSAssert(!"Unexpected event");
+ break;
+ }
+
+ TSHttpTxnReenable(txnp, TS_EVENT_HTTP_CONTINUE);
+ return 1;
+ }
+
+ /* Handler for event TXN_START */
+ static int
+ global_hook_handler (TSCont contp, TSEvent event, void *edata)
+ {
+ TSHttpTxn txnp = (TSHttpTxn) edata;
+ TSCont txn_contp;
+ TxnData *txn_data;
+
+ switch (event) {
+ case TS_EVENT_HTTP_TXN_START:
+ /* Create a new continuation for this txn and associate data to it */
+ txn_contp = TSContCreate(local_hook_handler, TSMutexCreate());
+ txn_data = txn_data_alloc();
+ TSContDataSet(txn_contp, txn_data);
+
+ /* Registers locally to hook READ_REQUEST and TXN_CLOSE */
+ TSHttpTxnHookAdd(txnp, TS_HTTP_READ_REQUEST_HDR_HOOK, txn_contp);
+ TSHttpTxnHookAdd(txnp, TS_HTTP_TXN_CLOSE_HOOK, txn_contp);
+ break;
+
+ default:
+ TSAssert(!"Unexpected event");
+ break;
+ }
+
+ TSHttpTxnReenable(txnp, TS_EVENT_HTTP_CONTINUE);
+ return 1;
+ }
+
+
+ void
+ TSPluginInit (int argc, const char *argv[])
+ {
+ TSCont contp;
+
+ /* Note that we do not need a mutex for this txn since it registers globally
+ and doesn't have any data associated with it */
+ contp = TSContCreate(global_hook_handler, NULL);
+
+ /* Register gloabally */
+ TSHttpHookAdd(TS_HTTP_TXN_START_HOOK, contp);
+ }
+
+See :ref:`developer-plugins-hooks-adding` for background on HTTP transactions
+and HTTP hooks, as well as :ref:`developer-plugins-hooks-and-transactions`. See
+also the :ref:`HTTP Transaction State Diagram <http-txn-state-diagram>` for an
+illustration of the steps involved in a typical HTTP transaction.
+
+The HTTP transaction functions are:
+
+- :c:func:`TSHttpTxnCacheLookupStatusGet`
+
+- :c:func:`TSHttpTxnCachedReqGet`
+ - Note that it is an error to modify cached headers.
+
+- :c:func:`TSHttpTxnCachedRespGet`
+ - Note that it is an error to modify cached headers.
+
+- :c:func:`TSHttpTxnClientReqGet`
+ - Plugins that must read client request headers use this call to
+ retrieve the HTTP header.
+
+- :c:func:`TSHttpTxnClientRespGet`
+
+- :c:func:`TSHttpTxnErrorBodySet`
+
+- :c:func:`TSHttpTxnHookAdd`
+
+- :c:func:`TSHttpTxnNextHopAddrGet`
+
+- :c:func:`TSHttpTxnParentProxySet`
+
+- :c:func:`TSHttpTxnReenable`
+
+- :c:func:`TSHttpTxnServerAddrGet`
+
+- :c:func:`TSHttpTxnServerReqGet`
+
+- :c:func:`TSHttpTxnServerRespGet`
+
+- :c:func:`TSHttpTxnSsnGet`
+
+- :c:func:`TSHttpTxnTransformedRespCache`
+
+- :c:func:`TSHttpTxnTransformRespGet`
+
+- :c:func:`TSHttpTxnUntransformedRespCache`
+
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/developer-guide/plugins/hooks-and-transactions/index.en.rst
----------------------------------------------------------------------
diff --git a/doc/developer-guide/plugins/hooks-and-transactions/index.en.rst b/doc/developer-guide/plugins/hooks-and-transactions/index.en.rst
new file mode 100644
index 0000000..89e2d7f
--- /dev/null
+++ b/doc/developer-guide/plugins/hooks-and-transactions/index.en.rst
@@ -0,0 +1,161 @@
+.. 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
+
+.. _developer-plugins-hooks-and-transactions:
+
+Hooks and Transactions
+**********************
+
+Hooks are points in Traffic Server transaction processing where plugins
+can step in and do some work. Registering a plugin function for callback
+amounts to "adding" the function to a hook. You can register your plugin
+to be called back for every single transaction or only for specific
+transactions.
+
+This chapter contains the following sections:
+
+.. toctree::
+ :maxdepth: 2
+
+ adding-hooks.en
+ http-sessions.en
+ http-transactions.en
+ intercepting-http-transactions.en
+ initiate-http-connection.en
+ http-alternate-selection.en
+
+.. _developer-plugins-hooks:
+
+Hooks
+=====
+
+To understand hooks and transactions, you should be familiar with the
+following terminology:
+
+HTTP Transaction
+----------------
+
+A **transaction** consists of a single HTTP request from a client and
+the response Traffic Server sends to that client. Thus, a transaction
+begins when Traffic Server receives a request and ends when Traffic
+Server sends the response.
+
+Traffic Server uses **HTTP state machines** to process transactions. The
+state machines follow a complex set of states involved in sophisticated
+caching and document retrieval (taking into account, for example,
+alternate selection, freshness criteria, and hierarchical caching). The
+Traffic Server API provides hooks to a subset of these states, as
+illustrated in the :ref:`http-txn-state-diagram` below.
+
+Transform Hooks
+---------------
+
+The two **transform hooks**, ``TS_HTTP_REQUEST_TRANSFORM_HOOK`` and
+``TS_HTTP_RESPONSE_TRANSFORM_HOOK``, are called in the course of an HTTP
+transform. To see where in the HTTP transaction they are called, look
+for the "set up transform" ovals in the :ref:`http-txn-state-diagram` below.
+
+HTTP Session
+------------
+
+A **session** consists of a single client connection to Traffic Server;
+it may consist of a single transaction or several transactions in
+succession. The session starts when the client connection opens and ends
+when the connection closes.
+
+.. _http-txn-state-diagram:
+
+HTTP Transaction State Diagram
+------------------------------
+
+.. graphviz::
+ :alt: HTTP Transaction State Diagram
+
+ digraph http_txn_state_diagram{
+ accept -> TS_HTTP_TXN_START_HOOK;
+ TS_HTTP_TXN_START_HOOK -> "read req hdrs";
+ "read req hdrs" -> TS_HTTP_READ_REQUEST_HDR_HOOK;
+ TS_HTTP_READ_REQUEST_HDR_HOOK -> TS_HTTP_PRE_REMAP_HOOK;
+ TS_HTTP_PRE_REMAP_HOOK -> "remap request";
+ "remap request" -> TS_HTTP_POST_REMAP_HOOK;
+ TS_HTTP_POST_REMAP_HOOK -> "cache lookup";
+ "cache lookup" -> DNS [label = "miss"];
+ DNS -> TS_HTTP_OS_DNS_HOOK;
+ TS_HTTP_OS_DNS_HOOK -> TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK;
+ "cache lookup" -> TS_HTTP_SELECT_ALT_HOOK [label = "hit"];
+ TS_HTTP_SELECT_ALT_HOOK -> "cache match";
+ "cache match" -> TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK [label="no match"];
+ "cache match" -> TS_HTTP_READ_CACHE_HDR_HOOK [label = "cache fresh"];
+ TS_HTTP_READ_CACHE_HDR_HOOK -> "cache fresh";
+ "cache fresh" -> TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK;
+ TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK -> "lock URL in cache" [label = "miss"];
+ TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK -> "lock URL in cache" [label = "no match "];
+ TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK -> "lock URL in cache" [label = "stale"];
+ TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK -> "send cached hdrs" [label = "fresh"];
+ "send cached hdrs" -> "set up transform";
+ "lock URL in cache" -> "pick address";
+ "pick address" -> "try connect" [label = " "];
+ "try connect" -> "pick address" [label = "fail"];
+ "try connect" -> TS_HTTP_SEND_REQUEST_HDR_HOOK [label = "success"];
+ TS_HTTP_SEND_REQUEST_HDR_HOOK -> "send req hdrs";
+ "send req hdrs" -> "set up POST/PUT read" [label = "POST/PUT"];
+ "send req hdrs" -> "read reply hdrs" [label = "GET"];
+ "set up POST/PUT read" -> "set up req transform";
+ "set up req transform" -> "tunnel req body";
+ "tunnel req body" -> "read reply hdrs";
+ "read reply hdrs" -> TS_HTTP_READ_RESPONSE_HDR_HOOK;
+ TS_HTTP_READ_RESPONSE_HDR_HOOK -> "check valid";
+ "check valid" -> "setup server read" [label = "yes"];
+ "check valid" -> "pick address" [label = "no"];
+ "setup server read" -> "set up cache write" [label = "cacheable"];
+ "setup server read" -> "set up transform" [label = "uncacheable"];
+ "set up cache write" -> "set up transform";
+ "set up transform" -> TS_HTTP_SEND_RESPONSE_HDR_HOOK;
+ TS_HTTP_SEND_RESPONSE_HDR_HOOK -> "send reply hdrs";
+ "send reply hdrs" -> "tunnel response";
+ "tunnel response" -> TS_HTTP_TXN_CLOSE_HOOK;
+ TS_HTTP_TXN_CLOSE_HOOK -> accept;
+
+ TS_HTTP_TXN_START_HOOK [shape=box];
+ TS_HTTP_READ_REQUEST_HDR_HOOK [shape = box];
+ TS_HTTP_PRE_REMAP_HOOK [shape = box];
+ TS_HTTP_POST_REMAP_HOOK [shape = box];
+ TS_HTTP_OS_DNS_HOOK [shape = box];
+ TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK[shape = box];
+ TS_HTTP_SELECT_ALT_HOOK [shape = box];
+ TS_HTTP_READ_CACHE_HDR_HOOK [shape = box];
+ TS_HTTP_SEND_REQUEST_HDR_HOOK [shape = box];
+ "set up req transform" [tooltip = "req transform takes place here"];
+ TS_HTTP_READ_RESPONSE_HDR_HOOK [shape = box];
+ "set up transform" [tooltip = "response transform takes place here"];
+ TS_HTTP_SEND_RESPONSE_HDR_HOOK [shape = box];
+ TS_HTTP_TXN_CLOSE_HOOK [shape = box];
+ }
+
+HTTP Transacation Timers
+------------------------
+
+For an overview of HTTP transaction timers, refer to the transaction timer diagram
+below.
+
+.. toctree::
+ :maxdepth: 1
+
+ Transaction Timers: Trafficserver Timers at different states <trafficserver-timers.en>
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/developer-guide/plugins/hooks-and-transactions/initiate-http-connection.en.rst
----------------------------------------------------------------------
diff --git a/doc/developer-guide/plugins/hooks-and-transactions/initiate-http-connection.en.rst b/doc/developer-guide/plugins/hooks-and-transactions/initiate-http-connection.en.rst
new file mode 100644
index 0000000..a732b96
--- /dev/null
+++ b/doc/developer-guide/plugins/hooks-and-transactions/initiate-http-connection.en.rst
@@ -0,0 +1,29 @@
+.. 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
+
+.. _developer-pluings-hooks-initiate-http:
+
+Initiate HTTP Connection
+************************
+
+This function enables plugins to initiate HTTP transactions. The
+initiate HTTP connection function is:
+
+- :c:func:`TSHttpConnect`
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/developer-guide/plugins/hooks-and-transactions/intercepting-http-transactions.en.rst
----------------------------------------------------------------------
diff --git a/doc/developer-guide/plugins/hooks-and-transactions/intercepting-http-transactions.en.rst b/doc/developer-guide/plugins/hooks-and-transactions/intercepting-http-transactions.en.rst
new file mode 100644
index 0000000..1412183
--- /dev/null
+++ b/doc/developer-guide/plugins/hooks-and-transactions/intercepting-http-transactions.en.rst
@@ -0,0 +1,34 @@
+.. 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
+
+.. _developer-plugins-hooks-intercepting:
+
+Intercepting HTTP Transactions
+******************************
+
+The intercepting HTTP transaction functions enable plugins to intercept
+transactions either after the request is received or upon contact with
+the origin server. The plugin then acts as the origin server using the
+``TSVConn`` interface. The intercepting HTTP transaction function allow
+for reading ``POST`` bodies in plugins as well as using alternative
+transports to the origin server.The intercepting HTTP transaction
+functions are:
+
+- :c:func:`TSHttpTxnIntercept`
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/developer-guide/plugins/http-headers/header-functions.en.rst
----------------------------------------------------------------------
diff --git a/doc/developer-guide/plugins/http-headers/header-functions.en.rst b/doc/developer-guide/plugins/http-headers/header-functions.en.rst
new file mode 100644
index 0000000..151487a
--- /dev/null
+++ b/doc/developer-guide/plugins/http-headers/header-functions.en.rst
@@ -0,0 +1,179 @@
+.. 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
+
+.. _developer-plugins-http-headers-functions:
+
+Header Functions
+****************
+
+The Traffic Server API HTTP header functions enable you to work with
+HTTP header data stored in marshal buffers.
+
+The HTTP header data structure is a parsed version of the HTTP header
+defined in the HTTP protocol specification. An HTTP header is composed
+of a request or response line followed by zero or more MIME fields. In
+fact, an HTTP header is a subclass of a MIME header; all of the MIME
+header routines operate on HTTP headers.
+
+An HTTP **request line** is composed of a method, a URL, and version. A
+**response line** is composed of a version, status code, and reason
+phrase. See `About HTTP Headers <../http-headers#AboutHTTPHeaders>`__
+for additional details and examples.
+
+To facilitate fast comparisons and reduce storage size, Traffic Server
+defines several pre-allocated method names. These names correspond to
+the methods defined in the HTTP 1.1 specification
+
+``TS_HTTP_METHOD_CONNECT``
+ "CONNECT"
+
+``TS_HTTP_METHOD_DELETE``
+ "DELETE"
+
+``TS_HTTP_METHOD_GE``
+ "GET"
+
+``TS_HTTP_METHOD_HEAD``
+ "HEAD"
+
+``TS_HTTP_METHOD_ICP_QUERY``
+ "ICP\_QUERY"
+
+``TS_HTTP_METHOD_OPTIONS``
+ "OPTIONS"
+
+``TS_HTTP_METHOD_POST``
+ "POST"
+
+``TS_HTTP_METHOD_PURGE``
+ "PURGE"
+
+``TS_HTTP_METHOD_PUT``
+ "PUT"
+
+``TS_HTTP_METHOD_TRACE``
+ "TRACE"
+
+``TS_HTTP_METHOD_PUSH``
+ "PUSH"
+
+Traffic Server also defines several common values that appear in HTTP
+headers.
+
+``TS_HTTP_VALUE_BYTES``
+ "bytes"
+
+``TS_HTTP_VALUE_CHUNKED``
+ "chunked"
+
+``TS_HTTP_VALUE_CLOSE``
+ "close"
+
+``TS_HTTP_VALUE_COMPRESS``
+ "compress"
+
+``TS_HTTP_VALUE_DEFLATE``
+ "deflate"
+
+``TS_HTTP_VALUE_GZIP``
+ "gzip"
+
+``TS_HTTP_VALUE_IDENTITY``
+ "identity"
+
+``TS_HTTP_VALUE_KEEP_ALIVE``
+ "keep-alive"
+
+``TS_HTTP_VALUE_MAX_AGE``
+ "max-age"
+
+``TS_HTTP_VALUE_MAX_STALE``
+ "max-stale"
+
+``TS_HTTP_VALUE_MIN_FRESH``
+ "min-fresh"
+
+``TS_HTTP_VALUE_MUST_REVALIDATE``
+ "must-revalidate"
+
+``TS_HTTP_VALUE_NONE``
+ "none"
+
+``TS_HTTP_VALUE_NO_CACHE``
+ "no-cache"
+
+``TS_HTTP_VALUE_NO_STORE``
+ "no-store"
+
+``TS_HTTP_VALUE_NO_TRANSFORM``
+ "no-transform"
+
+``TS_HTTP_VALUE_ONLY_IF_CACHED``
+ "only-if-cached"
+
+``TS_HTTP_VALUE_PRIVATE``
+ "private"
+
+``TS_HTTP_VALUE_PROXY_REVALIDATE``
+ "proxy-revalidate"
+
+``TS_HTTP_VALUE_PUBLIC``
+ "public"
+
+``TS_HTTP_VALUE_S_MAX_AGE``
+ "s-maxage"
+
+The method names and header values above are defined in ``ts.h`` as
+``const char*`` strings. When Traffic Server sets a method or a header
+value, it checks to make sure that the new value is one of the known
+values. If it is, then it stores a pointer into a global table (instead
+of storing the known value in the marshal buffer). The method names and
+header values listed above are also pointers into this table. This
+allows simple pointer comparison of the value returned from
+``TSHttpMethodGet`` with one of the values listed above. It is also
+recommended that you use the above values when referring to one of the
+known schemes, since this removes the possibility of a spelling error.
+
+The **HTTP Header Functions** are listed below:
+
+- :c:func:`TSHttpHdrClone`
+- :c:func:`TSHttpHdrCopy`
+- :c:func:`TSHttpHdrCreate`
+- :c:func:`TSHttpHdrDestroy`
+- :c:func:`TSHttpHdrLengthGet`
+- :c:func:`TSHttpHdrMethodGet`
+- :c:func:`TSHttpHdrMethodSet`
+- :c:func:`TSHttpHdrPrint`
+- :c:func:`TSHttpHdrReasonGet`
+- :c:func:`TSHttpHdrReasonLookup`
+- :c:func:`TSHttpHdrReasonSet`
+- :c:func:`TSHttpHdrStatusGet`
+- :c:func:`TSHttpHdrStatusSet`
+- :c:func:`TSHttpHdrTypeGet`
+- :c:func:`TSHttpHdrTypeSet`
+- :c:func:`TSHttpHdrUrlGet`
+- :c:func:`TSHttpHdrUrlSet`
+- :c:func:`TSHttpHdrVersionGet`
+- :c:func:`TSHttpHdrVersionSet`
+- :c:func:`TSHttpParserClear`
+- :c:func:`TSHttpParserCreate`
+- :c:func:`TSHttpParserDestroy`
+- :c:func:`TSHttpHdrParseReq`
+- :c:func:`TSHttpHdrParseResp`
+