Concepts

TxnBox is based on the idea that for a given transaction and hook in Traffic Server, the administrator wants to consider some subset of the information in the transaction and, based on that, perform specific actions. There is a further presumption that the common use will be multiple comparisons against the same data, each comparison associated with different actions. This is a generalization of how URL rewriting happens currently in Traffic Server via "remap.config". The difference between this and remapping is the latter considers only a fixed, very small subset of data in the transaction, the set of actions is limited, and there is only one decision point.

To aid further explanation, some terms need to be defined.

Every action in TxnBox is associated with a specific hook. A TxnBox hook is essentially the same as a hook in Traffic Server. In addition to the hooks in Traffic Server, TxnBox has additional hooks specific to TxnBox.

TxnBox has two phases of operation, load time and run time. Load time is the time during which the configuration is being loaded and run time is when processing transactions. Operations during load time are done by associating the action with a hook that triggers during load time.

A feature is data of interest for a transaction. A feature is created by Extraction which is specifed by a feature expression, which is a series of literals and extractors. Each extractor retrieves a specific datum and the combination of those and (optional) literals defines the resulting feature. Features can be one of several types, the most common being a string.

A directive is an action to be performed. Some directives can have an argument which provides additional control of the directive's action.

A comparison is an operation that compares two features.

Selection is using comparisons can to select specific directives to perform. This is the way in which conditional actions are done in TxnBox.

A TxnBox configuration is organized at the top level by hooks, to which are attached the directives that specify what TxnBox should do to manipulate the transaction. These directives can be conditional based on comparisons to extracted features. This yields a very flexible and powerful mechanism for manipulating transactions.

Configuration

TxnBox can be configured as a global plugin or a remap plugin. In both cases it takes a configuration file that is YAML.

For a global configuration, the top level directives must all be when thereby associating every directive with a specific hook. For a remap configuration, all directives are grouped in an implied when: remap and therefore no explicit when is required.

Each directive and extractor has an associated set of hooks in which it is valid, therefore some will be available in a remap configuration and some will not. In particular there are several directives which are specific to remap because they interact with the data passed to a remap plugin which is not available in any other context.

For both global and remap plugins the configuration file must be specified. A specific key in the file is used as the base of the configuration, ignoring any other data. For global configuration this is by default the txn_box key at the top level. For remap it is the top level node in the file (generally the entire file). This can be overridden by a second parameter, which is a path to the root configuration node. This must be a sequence of keys in maps, starting from the top. The path is specified by a dot separated list of these keys. For example, consider a file with this at the top node level.

txn_box: # path - "txn_box"
   example-1: # path - "txn_box.example-1"
      inner-1: # path - "txn_box.examle-1.inner-1"
   example-2: # path "txn_box.example-2"

If "example-1" was to be the root, the path would be "txn_box.example-1". The global default, "txn_box", would select "txn_box"" as the root node. The path could also be "txn_box.example-1.inner-1" to select the inner most node. As a special case, the path "." means "the unnamed top level node". Note this is problematic in the case of keys that contains ".", which should be avoided.

The point of specifying a key is to enable TxnBox configuration to exist inside a file that contains other configuration, or to enable having a single file that provides configuration for multiple instances of TxnBox.

Hooks

The directive key when can be used to specify on which hook directives should be performed. Each when must also have a do key which contains the directives. The value of when is the hook name, which must be one of

Hook	when	Abbreviation	Plugin API Name
Client Request	read-request	ua-req	READ_REQUEST_HDR_HOOK
Proxy Request	send-request	proxy-req	SEND_REQUEST_HDR_HOOK
Upstream Response	read-response	upstream-rsp	READ_RESPONSE_HDR_HOOK
Proxy Response	send-response	proxy-rsp	SEND_RESPONSE_HDR_HOOK
Pre remap	pre-remap		PRE_REMAP_HOOK
Post remap	post-remap		POST_REMAP_HOOK
Transaction Open	txn-open		TXN_START
Load time	post-load

The abbreviations are primarily for consistency between hook tags, extractors, and directives.

For a global plugin, the top level directives must be when. To set the HTTP header field swoc to invoked immediately after the client request has been read, it would be

txn_box:
-  when: ua-req
   do:
   -  ua-req-field<swoc>: "invoked"

For a remap plugin, the directives are wrapped in a notional code:when: remap directive, so no explicit when directive is needed and all top level directives are performed during remap. If when is used the when is exectued during remap, scheduling the contained directives for the future hook on that transaction.

The post-load hook is invoked immediately after the configuration is loaded and parsed. Directives on this hook may return errors which prevents the configuration from successfully loading. It is used to create resources that persist for the entire time the configuration is in use.