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:

  1. 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
  2. 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.

  1. typedef struct _query_remap_info {
  2.   char *param_name;
  3.   size_t param_len;
  4.   char **hosts;
  5.   int num_hosts;
  6. } query_remap_info;
  9. int tsremap_new_instance(int argc,char *argv[],ihandle *ih,char *errbuf,int errbuf_size)
  10. {
  11.   int i;
  13.   if (argc param_name = strdup(argv[2]);
  14.   qri->param_len = strlen(qri->param_name);
  15.   qri->num_hosts = argc - 3;
  16.   qri->hosts = (char**) TSmalloc(qri->num_hosts*sizeof(char*));
  18.   for (i=0; i num_hosts; ++i) {
  19.     qri->hosts[i] = strdup(argv[i+3]);
  20.   }
  22.   *ih = (ihandle)qri;
  23.   return 0;
  24. }

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:

  1. int tsremap_remap(ihandle ih, rhandle rh, TSRemapRequestInfo *rri)
  2. {
  3.   int hostidx = -1;
  4.   query_remap_info *qri = (query_remap_info*)ih;
  6.   if (!qri) {
  7.     TSError("[remap] NULL ihandle");
  8.     return 0;
  9.   }
  11.   if (rri && rri->request_query && rri->request_query_size > 0) {
  12.     char *q, *s, *key;
  14.     //make a copy of the query, as it is read only
  15.     q = (char*) TSmalloc(rri->request_query_size+1);
  16.     strncpy(q, rri->request_query, rri->request_query_size);
  17.     q[rri->request_query_size] = '\0';
  19.     s = q;
  20.     //parse query parameters
  21.     for (key = strsep(&s, "&"); key != NULL; key = strsep(&s, "&")) {
  22.       char *val = strchr(key, '=');
  23.       if (val && (size_t)(val-key) == qri->param_len &&
  24.           !strncmp(key, qri->param_name, qri->param_len)) {
  25.         ++val;
  26.         //the param key matched the configured param_name
  27.         //hash the param value to pick a host
  28.         hostidx = hash_fnv32(val, strlen(val)) % (uint32_t)qri->num_hosts;
  29.         break;
  30.       }
  31.     }
  33.     TSfree(q);
  35.     if (hostidx >= 0) {
  36.       rri->new_host_size = strlen(qri->hosts[hostidx]);
  37.       if (rri->new_host_size new_host, qri->hosts[hostidx], rri->new_host_size);
  38.         return 1; //host has been modified
  39.       }
  40.     }
  41.   }
  43.   //the request was not modified, TS will use the toURL from the remap rule
  44.   return 0;
  45. }