TSHTTPHOOKADD(3ts)

📦
version 9.2.5 · 4 versions
, in ubuntu noble, ubuntu questing

💅 TSHTTPHOOKADD 💅

okay bestie, welcome to TSHTTPHOOKADD(3ts), straight out of the Apache Traffic Server manual — this is the one about hooks, aka the little doorways where your plugin gets to pop in and do stuff. pull up a chair. 🫶

✨ 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 🎀

okay so, hooks are literally just points inside Apache Traffic Server's HTTP transaction processing where plugins can step in and do some work. registering a plugin function for callback = adding that function to a hook. periodt. and the way that you get to choose: you can register your plugin to get called back for every single transaction, or for specific transactions only. main character energy either way 💅

HTTP transaction hooks get set on a global basis using TSHttpHookAdd(). which means the continuation you pass as the parameter to TSHttpHookAdd() gets called for every transaction. and listen — TSHttpHookAdd() must only be called from TSPluginInit() or TSRemapInit(). no cap, that's the rule. 🚨

TSHttpSsnHookAdd() adds contp to the end of the list of HTTP session hooks specified by id. so contp gets called back for every transaction within that session, at the point specified by the hook ID. and since contp is being 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 first. iykyk. 🙈

TSHttpTxnHookAdd() adds contp to the end of the list of HTTP transaction hooks specified by id. since contp is being added to a transaction, it is not possible to call TSHttpTxnHookAdd() from the plugin initialization routine either — only when the plugin has a handle to an HTTP transaction. get you a plugin that has a handle, bestie. 💖

a single continuation can be attached to multiple hooks at the same time. and ngl it is good practice to conserve resources by reusing hooks this way when possible. slay, efficiency. ✨

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. it's giving… pattern matching. iconic. 👑

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. and 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.

🚨 bestie, important: but the continuation function must not unlock it. do not. we do not touch the mutex. hands off. 💀

⭐ RETURN VALUES ⭐

None. adding hooks is always successful. every time. no failures, no drama. obsessed. 💖

🦋 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). go read it, it's so good. 📚✨

🌈 SEE ALSO 🌈

2026, dev@trafficserver.apache.org

okay that's the whole page, bestie, you ate that 🍓 — this was TSHTTPHOOKADD(3ts) from version 9.2, dated Feb 12, 2026. go forth and hook responsibly. mwah 💅🎀💜

📦 where this page comes from