Hooks and Transactions

Hooks are points in Traffic Server transaction processing where plugins can step in and do some work. Registering a plugin function for callback amounts to “adding” the function to a hook. You can register your plugin to be called back for every single transaction or only for specific transactions.

This chapter contains the following sections:

• Adding Hooks
• HTTP Sessions
• HTTP Transactions
• Intercepting HTTP Transactions
• Initiate HTTP Connection
• HTTP Alternate Selection
• TLS User Agent Hooks
  • TLS Hooks
  • TS_VCONN_START_HOOK
  • TS_VCONN_CLOSE_HOOK
  • TS_SSL_CLIENT_HELLO_HOOK
  • TS_SSL_SERVERNAME_HOOK
  • TS_SSL_CERT_HOOK
  • TS_SSL_VERIFY_CLIENT_HOOK
  • TS_SSL_VERIFY_SERVER_HOOK
  • TS_VCONN_OUTBOUND_START_HOOK
  • TS_VCONN_OUTBOUND_CLOSE_HOOK
  • TLS Inbound Hook State Diagram
  • TLS Outbound Hook State Diagram
• TLS Session Plugin API
• Utility Functions
• Example Use Case

Hooks

To understand hooks and transactions, you should be familiar with the following terminology:

HTTP Transaction

A transaction consists of a single HTTP request from a client and the response Traffic Server sends to that client. Thus, a transaction begins when Traffic Server receives a request and ends when Traffic Server sends the response.

Traffic Server uses HTTP state machines to process transactions. The state machines follow a complex set of states involved in sophisticated caching and document retrieval (taking into account, for example, alternate selection, freshness criteria, and hierarchical caching). The Traffic Server API provides hooks to a subset of these states, as illustrated in the HTTP Transaction State Diagram below.

Transform Hooks

The two transform hooks, TS_HTTP_REQUEST_TRANSFORM_HOOK and TS_HTTP_RESPONSE_TRANSFORM_HOOK, are called in the course of an HTTP transform. To see where in the HTTP transaction they are called, look for the “set up transform” ovals in the HTTP Transaction State Diagram below.

The transform hooks can also be triggered on bytes passed for a tunneled connection. In that case the TS_HTTP_REQUEST_TRANSFORM_HOOK and the TS_HTTP_RESPONSE_TRANSFORM_HOOK should be set from a plugin triggered on the TS_HTTP_TUNNEL_START_HOOK. The TS_HTTP_REQUEST_TRANFORM_HOOK will cause IO events to trigger for bytes moving from the user agent to the origin server. The TS_HTTP_RESPONSE_TRANSFORM_HOOK will cause IO events to trigger for bytes moving from the origin server to the user agent.

HTTP Session

A session consists of a single client connection to Traffic Server; it may consist of a single transaction or several transactions in succession. The session starts when the client connection opens and ends when the connection closes.

HTTP Transaction State Diagram

HTTP Transaction Timers

For an overview of HTTP transaction timers, refer to the transaction timer diagram below.

• Transaction Timers: Trafficserver Timers at different states