HTTP Transactions

The HTTP transaction functions enable you to set up plugin callbacks to HTTP transactions and obtain/modify information about particular HTTP transactions.

As described in HTTP sessions, an HTTP transaction is an object defined for the lifetime of a single request from a client and the corresponding response from Traffic Server. The TSHttpTxn structure is the main handle given to a plugin for manipulating a transaction's internal state. Additionally, an HTTP transaction has a reference back to the HTTP session that created it.

The sample code below illustrates how to register locally to a transaction and associate data to the transaction.

/*
* Simple plugin that illustrates:
* - how to register locally to a transaction
* - how to deal with data that's associated with a transaction
*
* Note: for readability, error checking is omitted
*/

#include <ts/ts.h>

namespace
{
DbgCtl dbg_ctl{"txn"};
}

/* Structure to be associated to txns */
struct TxnData {
   int i;
   float f;
   char const *s;
};

/* Allocate memory and init a TxnData structure */
TxnData *
txn_data_alloc()
{
   auto data{new TxnData};

   data->i = 1;
   data->f = 0.5;
   data->s = "Constant String";
   return data;
}

/* Handler for event READ_REQUEST and TXN_CLOSE */
static int
local_hook_handler (TSCont contp, TSEvent event, void *edata)
{
   TSHttpTxn txnp = (TSHttpTxn) edata;
   auto txn_data = static_cast<TxnData *>(TSContDataGet(contp));
   switch (event) {
   case TS_EVENT_HTTP_READ_REQUEST_HDR:
      /* Modify values of txn data */
      txn_data->i = 2;
      txn_data->f = 3.5;
      txn_data->s = "Constant String 2";
      break;

   case TS_EVENT_HTTP_TXN_CLOSE:
      /* Print txn data values */
      Dbg(dbg_ctl, "Txn data i=%d f=%f s=%s", txn_data->i, txn_data->f, txn_data->s);

      /* Then destroy the txn cont and its data */
      delete txn_data;
      TSContDestroy(contp);
      break;

   default:
       TSAssert(!"Unexpected event");
       break;
   }

   TSHttpTxnReenable(txnp, TS_EVENT_HTTP_CONTINUE);
   return 1;
}

/* Handler for event TXN_START */
static int
global_hook_handler (TSCont contp, TSEvent event, void *edata)
{
   auto txnp = static_cast<TSHttpTxn>(edata);
   TSCont txn_contp;
   TxnData *txn_data;

   switch (event) {
   case TS_EVENT_HTTP_TXN_START:
      /* Create a new continuation for this txn and associate data to it */
      txn_contp = TSContCreate(local_hook_handler, TSMutexCreate());
      txn_data = txn_data_alloc();
      TSContDataSet(txn_contp, txn_data);

      /* Registers locally to hook READ_REQUEST and TXN_CLOSE */
      TSHttpTxnHookAdd(txnp, TS_HTTP_READ_REQUEST_HDR_HOOK, txn_contp);
      TSHttpTxnHookAdd(txnp, TS_HTTP_TXN_CLOSE_HOOK, txn_contp);
      break;

   default:
      TSAssert(!"Unexpected event");
      break;
   }

   TSHttpTxnReenable(txnp, TS_EVENT_HTTP_CONTINUE);
   return 1;
}


void
TSPluginInit (int argc, const char *argv[])
{
   /* Note that we do not need a mutex for this txn since it registers globally
      and doesn't have any data associated with it */
   TSCont contp = TSContCreate(global_hook_handler, nullptr);

   /* Register globally */
   TSHttpHookAdd(TS_HTTP_TXN_START_HOOK, contp);
}

See Adding Hooks for background on HTTP transactions and HTTP hooks, as well as Hooks and Transactions. See also the HTTP Transaction State Diagram for an illustration of the steps involved in a typical HTTP transaction.

The HTTP transaction functions are: