NAME

       TSHttpHookAdd - intercept Traffic Server events

SYNOPSIS

          #include <ts/ts.h>

       void TSHttpHookAdd(TSHttpHookID id, TSCont contp)

       void TSHttpSsnHookAdd(TSHttpSsn ssnp, TSHttpHookID id, TSCont contp)

       void TSHttpTxnHookAdd(TSHttpTxn txnp, TSHttpHookID id, TSCont contp)

DESCRIPTION

       Hooks  are  points  in Apache Traffic Server transaction HTTP 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 for specific transactions only.

       HTTP transaction hooks are set on a global basis using the function TSHttpHookAdd().  This
       means  that  the  continuation specified as the parameter to TSHttpHookAdd() is called for
       every  transaction.  TSHttpHookAdd()  must  only  be   called   from   TSPluginInit()   or
       TSRemapInit().

       TSHttpSsnHookAdd()  adds  contp  to the end of the list of HTTP session hooks specified by
       id.  This means that contp is called back for every transaction within the session, at the
       point  specified  by the hook ID. Since contp is added to a session, it is not possible to
       call TSHttpSsnHookAdd() from the plugin initialization routine; the plugin needs a  handle
       to an HTTP session.

       TSHttpTxnHookAdd()  adds  contp to the end of the list of HTTP transaction hooks specified
       by  id.  Since  contp  is  added  to  a  transaction,  it  is   not   possible   to   call
       TSHttpTxnHookAdd()  from  the plugin initialization routine but only when the plugin has a
       handle to an HTTP transaction.

       A single continuation can be attached to multiple hooks at the  same  time.   It  is  good
       practice to conserve resources by reusing hooks in this way when possible.

       When  a  continuation  on  a  hook  is  triggered,  the  name  of  the event passed to the
       continuation function depends on the name of the hook.  The naming convention is that, for
       hook TS_xxx_HOOK, the event passed to the continuation function will be TS_EVENT_xxx.  For
       example, when a continuation attached to TS_HTTP_READ_REQUEST_HDR_HOOK is  triggered,  the
       event passed to the continuation function will be TS_EVENT_HTTP_READ_REQUEST_HDR.

       When  a  continuation  is triggered by a hook, the actual type of the event data (the void
       pointer passed as the third parameter to the continuation function) is determined by which
       hook  it  is.   For  example, for the hook ID TS_HTTP_TXN_CLOSE_HOOK, the event data is of
       type TSHttpTxn.  This is the case regardless of whether the continuation was added to  the
       hook  using  TSHttpTxnHookAdd(), TSHttpSsnHookAdd() or TSHttpHookAdd().  If the event data
       is of type TSHttpTxn, TSHttpSsn or TSVConn, the continuation function can assume the mutex
       of  the  indicated  event  data object is locked.  (But the continuation function must not
       unlock it.)

RETURN VALUES

       None. Adding hooks is always successful.

EXAMPLES

       The following example demonstrates how to add global, session and transaction hooks:

          #include <ts/ts.h>

          static int
          handler(TSCont contp, TSEvent event, void *edata)
          {
              TSHttpSsn ssnp;
              TSHttpTxn txnp;

              switch (event){
              case TS_EVENT_HTTP_SSN_START:
                  ssnp = (TSHttpSsn) edata;
                  // Add a session hook ...
                  TSHttpSsnHookAdd(ssnp, TS_HTTP_TXN_START_HOOK, contp);
                  TSHttpSsnReenable(ssnp, TS_EVENT_HTTP_CONTINUE);
                  return 0;
              case TS_EVENT_HTTP_TXN_START:
                  txnp = (TSHttpTxn) edata;
                  // Add a transaction hook ...
                  TSHttpTxnHookAdd(txnp, TS_HTTP_READ_REQUEST_HDR_HOOK, contp);
                  TSHttpTxnReenable(txnp, TS_EVENT_HTTP_CONTINUE);
                  return 0;
              case TS_EVENT_HTTP_READ_REQUEST_HDR:
                  txnp = (TSHttpTxn) edata;
                  // ...
                  TSHttpTxnReenable(txnp, TS_EVENT_HTTP_CONTINUE);
                  return 0;
              default:
                   break;
              }

              return 0;
          }

          void
          TSPluginInit (int argc, const char *argv[])
          {
              TSCont contp;
              contp = TSContCreate(handler, NULL);
              TSHttpHookAdd(TS_HTTP_SSN_START_HOOK, contp);
          }

       For more example code using hooks, see the test_hooks plugin in tests/tools/plugins  (used
       by the test_hooks.test.py Gold test).

SEE ALSO

       TSAPI(3ts), TSContCreate(3ts), TSLifecycleHookAdd(3ts)

COPYRIGHT

       2023, dev@trafficserver.apache.org