trafficserver-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jpe...@apache.org
Subject [18/51] trafficserver git commit: Documentation reorganization
Date Tue, 03 Nov 2015 06:09:54 GMT
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`
+


Mime
View raw message