Apache Traffic Server

Administrator's Guide
https://trafficserver.readthedocs.org/en/latest/admin/index.en.html

Cache Architecture
https://trafficserver.readthedocs.org/en/latest/arch/cache/cache.en.html


Programmer's Guide
(http://trafficserver.apache.org/docs/trunk/sdk/index.en.html)

Plugins are programs that add services (such as filtering or content transformation) or entire features (such as new protocol support) to Traffic Server.

Traffic Server enables sophisticated caching and processing of web-related
traffic, such as DNS and HTTP requests and responses.Traffic Server itself consists of an event-driven loop that can be simplified
as follows
::::Cfor(;;)
{
 event=get_next_event();
 handle_event(event);
}

The Role of Plugins You compile your plugin source code to create a shared library that Traffic
Server loads when it is started. Your plugin contains callback functions that
are registered for specific Traffic Server events. When Traffic Server needs
to process an event, it invokes any and all call-back functions you've registered
for that event type.

Plugin Process


Plugin Process.jpg



Possible uses for plugins include the following:

HTTP processing: plugins can filter, blacklist, authorize users, transform content
Protocol support: plugins can enable Traffic Server to proxy-cache new
protocol content

Possible Traffic Server Plugins

Possible Traffic Server Plugins.jpg



Plugin Initialization

Each plugin must define an initialization function named TSPluginInit that Traffic Server invokes when the plugin is loaded. The TSPluginInit function is commonly used to read configuration information and register hooks for event notification.

The TSPluginInit function has two arguments:

    - The argc argument represents the number of arguments defined in the plugin.config file for that particular plugin

   -  The argv argument is an array of pointers to the actual arguments defined in the plugin.config file for that plugin


Compile Your Plugin

The process for compiling a shared library varies with the platform used,
so the Traffic Server API provides the tsxs tool which you can use to create shared
libraries on all the supported Traffic Server platforms.

Traffic Server can accommodate multiple plugins. If several plugin functions are triggered by the same event, then Traffic Server invokes each plugin's function in the order each was defined in the plugin.config file.

The Asynchronous Event Model

The asynchronous event mode. This is the design paradigm used throughout Traffic Server; plugins must also follow this design. It includes the callback mechanism for Traffic Server to "wake up" your plugin and put it to work.

Traffic Server is a multi-threaded process. There are two main reasons why a server might use multiple threads:

   1) To take advantage of the concurrency available with multiple CPUs and multiple I/O devices.

   2) To manage concurrency from having many simultaneous client connections. For example, a server could create one thread for each connection, allowing the operating system (OS) to control switching between threads.

Traffic Server uses multiple threads for the first reason. However, Traffic Server does not use a separate OS thread per transaction because it would not be efficient when handling thousands of simultaneous connections.

Instead, Traffic Server provides special event-driven mechanisms for efficiently scheduling work: the event system and continuations. The event system is used to schedule work to be done on threads. A continuation is a passive, event-driven state machine that can do some work until it reaches a waiting point; it then sleeps until it receives notification that conditions are right for doing more work. For example, HTTP state machines (which handle HTTP transactions) are implemented as continuations.

Traffic Server has several processors, such as cache processor and net processor, that consolidate cache or network I/O tasks. Processors talk to the event system and schedule work on threads. An executing thread calls back a continuation by sending it an event. When a continuation receives an event, it wakes up, does some work, and either destroys itself or goes back to sleep & waits for the next event


Traffic Server Internals.jpg


Plugins are typically implemented as continuations.


Traffic Server with Plugins.jpg


a plugin might dynamically create other continuations as needed. Transform plugins are built in this manner: a static parent continuation checks all transactions to see if any are transformable; when a transaction is transformable, the static continuation creates a type of continuation called a vconnection. The vconnection lives as long as it takes to complete the transform and then destroys itself. This design can be seen in all of the sample transform plugins. Plugins that support new protocols also have this architecture: a static continuation listens for incoming client connections and then creates transaction state machines to handle each protocol transaction. When you write plugins, there are several ways to send events to continuations. For HTTP plugins, there is a "hook" mechanism that enables the Traffic Server HTTP state machine to send your plugin wakeup calls when needed. Additionally, several Traffic Server API functions trigger Traffic Server sub-processes to send events to plugins: TSContCall, TSVConnRead, TSCacheWrite, and TSMgmtUpdateRegister, to name a few

Traffic Server HTTP State Machine

Traffic Server performs sophisticated HTTP caching and proxying. Important features include checking for alternates and document freshness, filtering, supporting cache hierarchies, and hosting. Traffic Server handles thousands of client requests at a time and each request is handled by an HTTP state machine.  

These machines follow a complex state diagram that includes all of the states required to support Traffic Server's features. The Traffic Server API provides hooks to a subset of these states, chosen for their relevance to plugins.

The example in this section (below) explains how a plugin typically intervenes and extends Traffic Server's processing of an HTTP transaction

Simplified HTTP Transaction.jpg

  The figure above, Simplified HTTP Transaction, does not show behavior in the event of an error. If there is an error at a any stage, then the HTTP state machine jumps to the "send reply header" state and sends a reply. If the reply is an error, then the transaction closes. If the reply is not an error, then Traffic Server first sends the response content before it closes the transaction.

 API Hooks Corresponding to States.jpeg

You use hooks as triggers to start your plugin. The name of a hook reflects the Traffic Server state that was just completed. For example, the "OS DNS lookup" hook wakes up a plugin right after the origin server DNS lookup. For a plugin that requires the IP address of the requested origin server, this hook is the right one to use. 

Blacklist Plugin.jpg

Traffic Server calls the Blacklist plugin right after the origin server DNS lookup. The plugin checks the requested host against a list of blacklisted servers; if the request is allowed, then the transaction proceeds. If the host is forbidden, then the Blacklist plugin sends the transaction into an error state. When the HTTP state machine gets to the "send reply header" state, it then calls the Blacklist plugin to provide the error message that's sent to the client.

Types of Hooks

Plugins do have hooks invoked for plugin's states handled. Header manipulation plugins, such as filtering, basic authorization, or redirects, usually have a global hook to the DNS lookup or the read request header states. If specific actions need to be done to the transaction further on, then the plugin adds itself to a transaction hook.

  The plugin's hook to the "send reply header" state is a transaction hook, meaning that this hook is only invoked for specified transactions.

 Determine where your plugin needs to hook on to Traffic Server's HTTP processing (view the HTTP Transaction State Diagram )