How to write a MODULE_FIRST.

Caudium 1.0, 1.2, 1.3

A MODULE_FIRST is handed control before any other module except another MODULE_FIRST with a lower priority. In the case where there are multiple MODULE_FIRSTs, the order is not predictable.

This MODULE_FIRST skims a percentage of traffic based on a RegExp that is supplied in the Configuration Interface. There is an Include and an Exclude RegExp that is loaded as a global variable, and therefore is only read upon a reload of the module after the corresponding RegExps in the Config Interface are saved.

A Status is maintained in a global variable of the number of pages that have been passed without being redirected and the number that were redirected.

A MODULE_FIRST should return a 0 after it is done processing. The module 123session.pike, a method to keep session information on a per surfer basis, is a sophisticated MODULE_FIRST.

The premise of the attached MODULE_FIRST is to redirect a percentage of people that are hitting .html pages to another URL. If you redirect someone to a file within the current filesystem, it is possible to have multiple redirects. As a result, you might want to send the traffic to a host that is not running the MODULE_FIRST. We used it to redirect 50% of the incoming traffic of a marketing site to another location to test a new design.

In the Config Interface, you can click on the Status and Debug section of the module definition and see how many people were redirected and how many people were not redirected. This is accomplished with a global variable called count that is defined in the module outside of any of the subroutines, and count is incremented in the last_resort section of the module.

// cd34, v0.1, 2002-02-05
// http://daviesinc.com/modules/
//
int thread_safe=1;
#include <module.h>

inherit "module";
inherit "caudiumlib";

constant module_type = MODULE_FIRST;
constant module_name = "Skimmer Module";
constant module_doc  = "";
constant module_unique = 1;

object incl=0,excl=0;
int redirected=0,passed=0;

void create() {
  defvar("skim", 5, "Skim %", TYPE_INT,
         "This will take x% of the incoming requests for an .html doc and redirect them to a different URL");
  defvar("topdir", 0, "Skim Top Directory?", TYPE_FLAG,
         "Do you want to skim traffic from the top directory?");
  defvar("redirecturl", "NONE/", "Where are we sending the traffic?", TYPE_STRING,
         "");
  defvar("regexpinclude", "\.(htm|html|shtml|rxml)$|/$",
         "Regexp Include Specification", TYPE_STRING,
         "An expression here will include processing for anything that matches this Pike Syntax Regexp<br>"
         "For Example:<br>.*<br>will include processing for all files.  id->not_query is automatically "
         "lowercased."
         "<br>"
         "\\.(htm|html|shtml|rxml)$|/$");
  defvar("regexpexclude", "\.(jpg|jpeg|gif|png)$|^/_internal",
         "Regexp Exclude Specification", TYPE_STRING,
         "An expression here will exclude processing for anything that matches this Pike Syntax Regexp<br>"
         "For Example:<br>\\.(jpg|jpeg|gif|png)$|^/_internal <br>will exclude processing for jpg, gif and png files "
         "id->not_query is automatically lowercased");
}

void start(int num, object conf) {
  catch {
    if (strlen(query("regexpinclude")))
      incl = Regexp(query("regexpinclude"));
    if (strlen(query("regexpexclude")))
      excl = Regexp(query("regexpexclude"));
  };
}


string status() {
  return (sprintf("%d redirected, %d passed. %3.2f%% of the traffic is being redirected",
                  redirected,passed,(passed>0)?(float)redirected/((float)passed+(float)redirected)*100.0:0.0));
}

mapping first_try(object id) {

  if (QUERY(topdir)==0 && String.count(id->not_query,"/")<2)
    return 0;

//perror("match: "+id->not_query+" "+incl->match(lower_case(id->not_query))+"\n");
//perror("exclude: "+excl->match(lower_case(id->not_query))+"\n");
  if (id->not_query && (incl && !incl->match(lower_case(id->not_query))) ||
      (excl &&  excl->match(lower_case(id->not_query))))
    return(0);

  if (random(100) < QUERY(skim)) {
    redirected++;
    return http_redirect(QUERY(redirecturl));
  }

  passed++;
  return 0;
}