You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by sj...@apache.org on 2010/03/30 20:21:40 UTC
svn commit: r929212 - in /incubator/trafficserver/site/trunk/docs/v2/sdk:
RemapAPI_Example.html ch03.html ch03s02.html js/tocnodes.js
Author: sjiang
Date: Tue Mar 30 18:21:40 2010
New Revision: 929212
URL: http://svn.apache.org/viewvc?rev=929212&view=rev
Log:
TS-270: Added some more remap plugin documentation and an example
Added:
incubator/trafficserver/site/trunk/docs/v2/sdk/RemapAPI_Example.html (with props)
Modified:
incubator/trafficserver/site/trunk/docs/v2/sdk/ch03.html
incubator/trafficserver/site/trunk/docs/v2/sdk/ch03s02.html
incubator/trafficserver/site/trunk/docs/v2/sdk/js/tocnodes.js
Added: incubator/trafficserver/site/trunk/docs/v2/sdk/RemapAPI_Example.html
URL: http://svn.apache.org/viewvc/incubator/trafficserver/site/trunk/docs/v2/sdk/RemapAPI_Example.html?rev=929212&view=auto
==============================================================================
--- incubator/trafficserver/site/trunk/docs/v2/sdk/RemapAPI_Example.html (added)
+++ incubator/trafficserver/site/trunk/docs/v2/sdk/RemapAPI_Example.html Tue Mar 30 18:21:40 2010
@@ -0,0 +1,135 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Remap Plugin Example</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="ch03.html">Prev</a> â Chapter 3. Remap Plugin: Getting Started</div>
+<div class="navnext">Remap Plugin Function Reference <a accesskey="n" href="ch03s02.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div>
+ <h2 class="title" style="clear: both">
+<a name="ExampleQueryRemap">Example: Query Remap Plugin</a></h2>
+</div>
+
+<p>The sample remap plugin, <code class="filename">query_remap.c</code>, 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.</p>
+
+<h3 class="title">Configuration of query_remap</h3>
+<p>The query remap plugin will allow the query parameter name to be specified, along with the hostnames of the servers to hash across. Sample <code class="filename">remap.config</code> rules using <code class="code">query_remap</code> will look like: <p>
+
+<pre class="programlisting">
+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
+</pre>
+
+<p>The first <code class="code">@pparam</code> specifies the query param key for which the value will be hashed. The remaining parameters list the hostnames of the servers. A request for <code class="code">http://www.example.com/search?q=apache</code> will match the first rule. The plugin will look for the <code class="code"><em class="replaceable">q</em></code> parameter and hash the value '<code class="code">apache</code>' to pick from among <code class="code">srch<em class="replaceable">[1-3]</em>.example.com</code> to send the request.</p>
+
+<p>If the request does not include a <code class="code"><em class="replaceable">q</em></code> query parameter and the plugin decides not to modify the request, the default toURL '<code class="code">http://srch1.example.com/search</code>' will be used by TS.</p>
+
+<p>The parameters are passed to the plugin's <code class="code">tsremap_new_instance</code> function. In <code class="code">query_remap</code>, <code class="code">tsremap_new_instance</code> creates a plugin-defined <code class="code">query_remap_info</code> 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 <code class="code">tsremap_remap</code> function when it is triggered for a request.</p>
+
+<pre class="programlisting">
+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 < 4) {
+ INKError("Missing parameters for " PLUGIN_NAME);
+ return -1;
+ }
+
+ //initialize the struct to store info about this remap instance
+ // the argv parameters are:
+ // 0: fromURL
+ // 1: toURL
+ // 2: query param to hash
+ // 3,4,... : server hostnames
+ query_remap_info *qri = (query_remap_info*) malloc(sizeof(query_remap_info));
+
+ qri->param_name = strdup(argv[2]);
+ qri->param_len = strlen(qri->param_name);
+ qri->num_hosts = argc - 3;
+ qri->hosts = (char**) malloc(qri->num_hosts*sizeof(char*));
+
+ for (i=0; i < qri->num_hosts; ++i) {
+ qri->hosts[i] = strdup(argv[i+3]);
+ }
+
+ *ih = (ihandle)qri;
+ return 0;
+}
+</pre>
+
+<p>Another way remap plugins may want handle more complex configuration is to specify a configuration filename as a <code class="code">pparam</code> and parse the specified file during instance initialization.</p>
+
+
+<h3 class="title">Performing the Remap</h3>
+<p>The plugin implements the <code class="code">tsremap_remap</code> 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 <code class="code">TSRemapRequestInfo</code> struct contains input and output members for the remap operation. </p>
+
+<p><code class="code">tsremap_remap</code> uses the configuration information passed via the <code class="code">ihandle</code> and checks the <code class="code">request_query</code> for the configured query parameter. If the parameter is found, the plugin sets a <code class="code">new_host</code> to modify the request host:</p>
+
+<pre class="programlisting">
+int tsremap_remap(ihandle ih, rhandle rh, TSRemapRequestInfo *rri)
+{
+ int hostidx = -1;
+ query_remap_info *qri = (query_remap_info*)ih;
+
+ if (!qri) {
+ INKError("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*) malloc(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)) % (u_int32_t)qri->num_hosts;
+ break;
+ }
+ }
+
+ free(q);
+
+ if (hostidx >= 0) {
+ rri->new_host_size = strlen(qri->hosts[hostidx]);
+ if (rri->new_host_size <= TSREMAP_RRI_MAX_HOST_SIZE) {
+ //copy the chosen host into rri
+ memcpy(rri->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;
+}
+</pre>
+
+</div>
+</body>
+</html>
Propchange: incubator/trafficserver/site/trunk/docs/v2/sdk/RemapAPI_Example.html
------------------------------------------------------------------------------
svn:executable = *
Modified: incubator/trafficserver/site/trunk/docs/v2/sdk/ch03.html
URL: http://svn.apache.org/viewvc/incubator/trafficserver/site/trunk/docs/v2/sdk/ch03.html?rev=929212&r1=929211&r2=929212&view=diff
==============================================================================
--- incubator/trafficserver/site/trunk/docs/v2/sdk/ch03.html (original)
+++ incubator/trafficserver/site/trunk/docs/v2/sdk/ch03.html Tue Mar 30 18:21:40 2010
@@ -6,7 +6,7 @@
<div class="navheader">
<div class="navprev">
<a accesskey="p" href="Roadmap_CreatingPlugins.html">Prev</a> â Roadmap for Creating Plugins</div>
-<div class="navnext">API Function Reference â <a accesskey="n" href="ch03s02.html">Next</a>
+<div class="navnext">Example: Query Remap Plugin â <a accesskey="n" href="RemapAPI_Example.html">Next</a>
</div>
</div>
<div id="toc"></div>
@@ -21,6 +21,7 @@
<li><a href="ch03.html#RequiredFunctions">Required Functions </a></li>
<li><a href="ch03.html#Configuration">Configuration </a></li>
</ul>
+<li><span class="section"><a href="RemapAPI_Example.html">Example: Query Remap</a></span></li>
<li><span class="section"><a href="ch03s02.html">API Function Reference</a></span></li>
</ul>
<div></div>
@@ -49,7 +50,7 @@
</ul> </p>
<h3><a name="Configuration">Configuration </a></h3>
- <p>To associate a remap plugin with a remap rule, use the <code>@pplugin</code> parameter. See the Admin Guide section (?TBD?) for details on configuring remap plugins</p>
+ <p>To associate a remap plugin with a remap rule, use the <code>@plugin</code> parameter. See the Admin Guide section (?TBD?) for details on configuring remap plugins</p>
</div>
Modified: incubator/trafficserver/site/trunk/docs/v2/sdk/ch03s02.html
URL: http://svn.apache.org/viewvc/incubator/trafficserver/site/trunk/docs/v2/sdk/ch03s02.html?rev=929212&r1=929211&r2=929212&view=diff
==============================================================================
--- incubator/trafficserver/site/trunk/docs/v2/sdk/ch03s02.html (original)
+++ incubator/trafficserver/site/trunk/docs/v2/sdk/ch03s02.html Tue Mar 30 18:21:40 2010
@@ -1,25 +1,25 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<title>Remap.API.h</title>
+<title>Remap Plugin Function Reference</title>
<!--#include file="top.html" -->
<div class="navheader">
<div class="navprev">
-<a accesskey="p" href="ch03.html">Prev</a> â Chapter 3. Remap Plugin: Getting Started</div>
-<div class="navnext">Chapter 4: Header-Based Plugin Examplesâ <a accesskey="n" href="HeaderBasedPluginEx.html">Next</a>
+<a accesskey="p" href="RemapAPI_Example.html">Prev</a> â Example: Query Remap Plugin</div>
+<div class="navnext">Chapter 4: Header-Based Plugin Examples â <a accesskey="n" href="HeaderBasedPluginEx.html">Next</a>
</div>
</div>
<div id="toc"></div>
<div class="section" lang="en">
<div class="titlepage"><div><div>
<h2 class="title" style="clear: both">
-<a name="id372670"></a>API Function Reference </h2>
+<a name="id372670"></a>Remap Plugin Function Reference </h2>
<ul>
- <li><a href=ch03s02.html#tsremap_init>tsremap_init </a> </li>
- <li><a href=ch03s02.html#tsremap_new_instance>tsremap_new_instance </a> </li>
- <li><a href=ch03s02.html#tsremap_remap>tsremap_remap </a> </li>
- <li><a href=ch03s02.html#tsremap_delete_instance>tsremap_delete_instance </a> </li>
- <li><a href=ch03s02.html#tsremap_os_response>tsremap_os_response </a> </li>
+ <li><a href="#tsremap_init">tsremap_init </a> </li>
+ <li><a href="#tsremap_new_instance">tsremap_new_instance </a> </li>
+ <li><a href="#tsremap_remap">tsremap_remap </a> </li>
+ <li><a href="#tsremap_delete_instance">tsremap_delete_instance </a> </li>
+ <li><a href="#tsremap_os_response">tsremap_os_response </a> </li>
</ul>
<p></p>
</div></div></div>
@@ -62,7 +62,7 @@
</dd>
<dt><span class="term"><b>Description</b></span></dt>
<dd>
- <p>Traffic Server calls this initialization routine once per remap instance for which the plugin is configured (i.e. once per rule in <code>remap.config</code> that has <code class="code">@pplugin=</code>). All remap plugins are required to implement this function.</p>
+ <p>Traffic Server calls this initialization routine once per remap instance for which the plugin is configured (i.e. once per rule in <code>remap.config</code> that has <code class="code">@plugin=</code>). All remap plugins are required to implement this function.</p>
</dd>
<dt><span class="term"><b>Returns</b></span></dt>
<dd>
@@ -84,9 +84,69 @@
<p><code class="code"><em class="replaceable">rh </em></code> is the <code>INKHttpTxn</code> for the request. This allows remap plugins to use APIs from<code> ts.h</code>.</p>
<p><code class="code"><em class="replaceable">rri </em></code> is the <code>TSRemapRequestInfo</code> struct contains input and output parameters for the remap operation for a single request. The struct members are as follows:</p>
<h5 class="title">Input (read-only) members</h5>
- <pre class="programlisting"> unsigned long size; /* sizeof(TSRemapRequestInfo) */ int request_port; /* request port number */ int remap_from_port; /* fromURL port number (from remap rule string) */ int remap_to_port; /* toURL port number (from remap rule string) */ const char *orig_url; /* request URL (not NULL terminated) */ int orig_url_size; /* request URL size */ const char *request_host; /* request host string (not NULL terminated) */ int request_host_size; /* request host string size */ const char *remap_from_host; /* fromURL host (from remap rule string) */ int remap_from_host_size; /* fromURL host size */ const char *remap_to_host; /* toURL host (from remap rule string) */ int remap_to_host_size; /* toURL host size */ const char *request_path; /* request path (not NULL terminated) */ int request_path_size; /* request pa
th size */ const char *remap_from_path; /* fromURL path (from remap rule string) */ int remap_from_path_size; /* fromURL path size */ const char *remap_to_path; /* toURL path (from remap rule string) */ int remap_to_path_size; /* toURL path size */ const char *request_cookie; /* request cookie string (not NULL terminated) */ int request_cookie_size; /* request cookie string size */ const char *request_query; /* request query string (not NULL terminated) */ int request_query_size; /* request query string size. */ const char *request_matrix; /* request matrix string (not NULL terminated) */ int request_matrix_size; /* request matrix string size. */ const char *from_scheme; /* The "from" scheme (e.g. http) */ int from_scheme_len; /* The len of the "from" scheme */ const char *to_scheme; /* The "to" scheme (e.g. http) */ int to_scheme_len; /* The len of the "to" sche
me */ unsigned int client_ip; /* The client IP is an unsigned network order (big-endian) 32-bit number. */ </pre>
+ <pre class="programlisting">
+ unsigned long size; /* sizeof(TSRemapRequestInfo) */
+
+ int request_port; /* request port number */
+ int remap_from_port; /* fromURL port number (from remap rule) */
+ int remap_to_port; /* toURL port number (from remap rule) */
+
+ const char *orig_url; /* request URL */
+ int orig_url_size; /* request URL size */
+
+ const char *request_host; /* request host string (not NULL terminated) */
+ int request_host_size; /* request host string size */
+
+ const char *remap_from_host; /* fromURL host (from remap rule, not NULL terminated) */
+ int remap_from_host_size; /* fromURL host size */
+
+ const char *remap_to_host; /* toURL host (from remap rule, not NULL terminated) */
+ int remap_to_host_size; /* toURL host size */
+
+ const char *request_path; /* request path (from client, not NULL terminated) */
+ int request_path_size; /* request path size */
+
+ const char *remap_from_path; /* fromURL path (from remap rule, not NULL terminated) */
+ int remap_from_path_size; /* fromURL path size */
+
+ const char *remap_to_path; /* toURL path (from remap rule, not NULL terminated) */
+ int remap_to_path_size; /* toURL path size */
+
+ const char *request_cookie; /* request 'Cookie:' value string (from client, not NULL terminated) */
+ int request_cookie_size; /* request cookie header size */
+
+ const char *request_query; /* request query string (from client, not NULL terminated) */
+ int request_query_size; /* request query string size. */
+
+ const char *request_matrix; /* request matrix string (from client, not NULL terminated) */
+ int request_matrix_size; /* request matrix string size. */
+
+ const char *from_scheme; /* The "from" scheme (e.g. http) */
+ int from_scheme_len; /* The len of the "from" scheme */
+
+ const char *to_scheme; /* The "to" scheme (e.g. http) */
+ int to_scheme_len; /* The len of the "to" scheme */
+
+ unsigned int client_ip; /* The client IP is an unsigned 32-bit network byte order (big-endian) value */
+</pre>
<h5 class="title">Output members</h5>
- <pre class="programlisting"> char new_host[TSREMAP_RRI_MAX_HOST_SIZE]; /* new host string */ int new_host_size; /* new host string size (if 0 - do not change request host) */ int new_port; /* new port number (0 - do not change request port) */ char new_path[TSREMAP_RRI_MAX_PATH_SIZE]; /* new path string */ int new_path_size; /* new path string size (0 - do not change request path) */ char new_query[TSREMAP_RRI_MAX_PATH_SIZE]; /* new query string */ int new_query_size; /* new query string size (0 - do not change request query) */ char new_matrix[TSREMAP_RRI_MAX_PATH_SIZE]; /* new matrix parameter string */ int new_matrix_size; /* new matrix parameter string size (0 - do not change matrix parameters) */ char redirect_url[TSREMAP_RRI_MAX_REDIRECT_URL]; /* redirect url (to redirect/reject request) */
int redirect_url_size; /* redirect url size (0 - empty redirect url string) */ int require_ssl; /* Require the toScheme to become SSL (e.g. HTTPS). */ /* 0 -> Disable SSL if toScheme is SSL */ /* 1 -> Enable SSL if toScheme is not SSL */ /* -1 (default) -> Don't modify scheme */ </pre>
+ <pre class="programlisting">
+ char new_host[TSREMAP_RRI_MAX_HOST_SIZE]; /* new host string */
+ int new_host_size; /* new host string size (if 0 - do not change request host) */
+ int new_port; /* new port number (0 - do not change request port) */
+ char new_path[TSREMAP_RRI_MAX_PATH_SIZE]; /* new path string */
+ int new_path_size; /* new path string size (0 - do not change request path) */
+ char new_query[TSREMAP_RRI_MAX_PATH_SIZE]; /* new query string */
+ int new_query_size; /* new query string size (0 - do not change request query) */
+ char new_matrix[TSREMAP_RRI_MAX_PATH_SIZE]; /* new matrix parameter string */
+ int new_matrix_size; /* new matrix parameter string size (0 - do not change matrix parameters) */
+ char redirect_url[TSREMAP_RRI_MAX_REDIRECT_URL]; /* redirect url (to redirect/reject request) */
+ int redirect_url_size; /* redirect url size (0 - empty redirect url string) */
+ int require_ssl; /* Require the toScheme to become SSL (e.g. HTTPS). */
+ /* 0 -> Disable SSL if toScheme is SSL */
+ /* 1 -> Enable SSL if toScheme is not SSL */
+ /* -1 (default) -> Don't modify scheme */
+</pre>
</dd>
<dt><span class="term"><b>Returns</b></span></dt>
<dd>
@@ -94,7 +154,8 @@
</dd>
<dt><span class="term"><b>Description</b></span></dt>
<dd>
- <p>This is the main remap function in which the plugin can modify the client request based on the <code class="replaceable">rri </code> input members. The function is called for client requests matching the remap rule associated with the plugin (based on <code class="code">fromURL</code>). If multiple rules match the client request, then Traffic Server uses the first match. In relation to Traffic Server's HTTP transaction APIs, <code class="code">tsremap_remap</code> is invoked before <code class="code">INK_HTTP_READ_REQUEST_HDR_HOOK</code> and before a cache lookup. Thus, the cache lookup key is altered if the plugin modifies the request.</p>
+ <p>This is the main remap function in which the plugin can modify the client request based on the <code class="replaceable">rri</code> input members. The function must be reentrant, as TS may call the remap function concurrently from multiple threads.</p>
+ <p>The function is called for client requests matching the remap rule associated with the plugin (based on <code class="code">fromURL</code>). If multiple rules match the client request, then Traffic Server uses the first match. In relation to Traffic Server's HTTP transaction APIs, <code class="code">tsremap_remap</code> is invoked before <code class="code">INK_HTTP_READ_REQUEST_HDR_HOOK</code> and before a cache lookup. Thus, the cache lookup key is altered if the plugin modifies the request.</p>
</dd>
</dl>
</div>
Modified: incubator/trafficserver/site/trunk/docs/v2/sdk/js/tocnodes.js
URL: http://svn.apache.org/viewvc/incubator/trafficserver/site/trunk/docs/v2/sdk/js/tocnodes.js?rev=929212&r1=929211&r2=929212&view=diff
==============================================================================
--- incubator/trafficserver/site/trunk/docs/v2/sdk/js/tocnodes.js (original)
+++ incubator/trafficserver/site/trunk/docs/v2/sdk/js/tocnodes.js Tue Mar 30 18:21:40 2010
@@ -42,9 +42,12 @@ var n27 = new YAHOO.widget.TextNode({ la
// var n28 = new YAHOO.widget.TextNode({ label: "Index", href: "CreatingTSPlugins.html#id372630" }, n22, false);
var n29 = new YAHOO.widget.TextNode({ label: "3. Remap Plugin", href: "ch03.html" }, root, false);
//var n30 = new YAHOO.widget.TextNode({ label: "Why Use a Remap Plugin?", href: "ch03.html#id372652" }, n29, false);
-var n31 = new YAHOO.widget.TextNode({ label: "Remap.API.h", href: "ch03s02.html" }, n29, false);
+var n30 = new YAHOO.widget.TextNode({ label: "Example: Query Remap", href: "RemapAPI_Example.html" }, n29, false);
+var n31 = new YAHOO.widget.TextNode({ label: "Function Reference", href: "ch03s02.html" }, n29, false);
+/*
var n32 = new YAHOO.widget.TextNode({ label: "Functions You Need to Implement", href: "ch03s03.html" }, n29, false);
var n33 = new YAHOO.widget.TextNode({ label: "Examples", href: "ch03s04.html" }, n29, false);
+*/
var n34 = new YAHOO.widget.TextNode({ label: "4. Header-Based Plugin Examples", href: "HeaderBasedPluginEx.html" }, root, false);
//var n35 = new YAHOO.widget.TextNode({ label: "Overview", href: "HeaderBasedPluginEx.html#HeaderBasedEx_Overview" }, n34, false);
var n36 = new YAHOO.widget.TextNode({ label: "The Blacklist Plugin", href: "BlacklistPlugin.html" }, n34, false);