Script control header
GreasySpoon scripts behavior is managed through a specific header which must be inserted at the begining of each script. All of the header's lines must be commented (as it is not part of the script code by itself), and the header is characterized by:
  • A starting tag ==ServerScript==
  • A closing tag  ==/ServerScript==
When creating a new script through the web interface, a default control header is automatically generated. An example of such header is provided hereafter (with Java/JavaScript comment tag, for Ruby '//' would be replaced by '#'):
//==ServerScript== Header start tag
//@name scriptsample Script unique name
//@status off Script status (here the script is desactivated)
//@order 0 Requested order: here the script should be applied first
//@timeout 2000 Execution threshold: script will be aborted if processing exceeds 2 seconds (2000 ms)
//@description  script header example Script description
//@include    .* Applies per default on any URL
//@exclude   http://.*\.mydomain\..{2,3}/.* Except on sites in mydomain (.fr, .com, …) domains
//@exclude   http://.*\.mydomain2\.com/.* And except on sites in mydomain2.com
//@responsecode   301 302 Proceed only servers responses with 301/302 HTTP response code
//==/ServerScript== Header end tag
Headers types and roles
Script control header supports following tags (default values are in bold):
  • @name <String> : mandatory header, unique name used to characterize script
  • @status <on|off> : mandatory header, allows to enable/disable script. Note that enabling/disabling the script can also be done using scripts list page available through the web interface.
  • @timeout <integer>: optional header, allows to configure processing threshold (in ms) after which script will be aborted. This value cannot exceed GreasySpoon overall processing time threshold, which is set globally by the administrator.
  • @order <integer> : optional header allowing to sort scripts between them. Script with lower values are executed first. Note that if two scripts are configured with the same order value, they will be sorted randomly.
  • @description <String> : optional string used to provide a short description of what the script does
  • @include <regular expression> : mandatory header, compared to server URLs to see on which sites (URLs) the script will applied. Regular expressions must follow PERL syntax. Several @include tags can be inserted in the header.
  • @exclude <regular expression> : optional header, compared to server URLs to see on which sites (URLs) the script will NOT applied. Several @exclude tags can be inserted in the header. Note that exclude regexes are evaluated before @include regexes.
  • @responsecode <integer(s)> : optional header, only for scripts on responses (default value: 200). Allows to select the HTTP server responses to be processed by the script, based on their HTTP response code. For example, using "@responsecode 301 302" will make script applicable only on redirection responses (see list of possible response codes).
    Note: special values "0" or "*" can be used to indicate that ALL responses will be processed whatever their responses code.
Note about @include and @exclude tags
@include and @exclude tags are used to define URLs for which script will apply.
For GreasySpoon releases before 0.5.4, @include and @exclude do not take URL parameters (i.e ?param=value) into account.
Since version 0.5.4, URL parameters are also processed, so users migrating from 0.5.x to 0.5.4 should check that a trailing ".*" is present at the end of their regexes.

Warning: in order to easier trafic selection, requested URL is converted to lowercase before being compared to include and exclude tags. Tags should therefore only use lowercase characters.
 
These parameters allow to optimize performances by interupting trafic processing on GS for content that will not be modified.
If no include or exclude tag is defined, script will apply to everything per default.
 
If you encounter issues with @include and @exclude tags, ensure that URL was turned to lowercase and that special chars ( . * ? | () {} ...) are correctly escaped.
Note about timeout thresholds
Timeout is used to define the maximum processing time in milliseconds allocated for traffic processing. There are two timeout thresholds defined in GreasySpoon:
  • An overall timeout, defined in greasyspoon.ini
  • Optional script timeouts defined in script headers
When modification time exceeds timeout, GreasySpoon interupts current script and continues processing with the last modified version of the content. For example, considering 3 scripts running in response mode with a @timeout defined in script2:
  • If overall timeout is reached while processing script 3, GreasySpoon will return the result of script2 to the client
  • If script2 @timeout is reached while processing it, GreasySpoon will abort script2 and call script3 with the result of script1
The two thresholds can be deactivated if desired. However, it is recommended to keep at least a high overall threshold to avoid potential infinite loop or dead-locks in scripts. Also, GreasySpoon behaviour can be configured whe reaching overall threshold:
  • Either by replying with an error
  • Or by bypassing all the processing and returning the original unmodified content