TSHTTPCON...THPLUGINID(3ts)

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

💖 TSHttpConnectWithPluginId 💖

welcome to the 3ts manual page bestie — this is Apache Traffic Server's little love letter to plugins that wanna start their own HTTP connections, from the TSHttpConnectWithPluginId family. buckle up, it's giving ✨very specific✨ and also very useful.

✨ NAME ✨

TSHttpConnectWithPluginId — lets your plugin initiate an http connection 🫶

The way this works is: it tags the HTTP state machine with extra data that the logging interface can go peek at later. And the connection? Treated as an HTTP transaction, literally as if it came from a client. iconic behavior honestly.

NOTE: this is a convenience function for TSHttpConnectPlugin() — it's the simpler interface, and it keeps backward compatibility for existing implementations. But heads up: when you use this one instead of TSHttpConnectPlugin, default buffer index and watermark values get used when creating IOBuffers. no cap.

✨ SYNOPSIS ✨

#include <ts/ts.h>

TSVConn TSHttpConnectWithPluginId(sockaddr const *addr, char const *tag,
int64_t id)

✨ DESCRIPTION ✨

This call attempts to create an HTTP state machine and a virtual connection to that state machine. It's more efficient than using TSNetConnect() because it dodges the operating system stack entirely — no loopback interface round trip, we're being efficient over here 💅

  • addr — the network address of the target of the connection. This includes the port, which should be stored in the sockaddr structure that addr points at. 👑
  • tag — a tag that gets passed through to the HTTP state machine. It must be a persistent string whose lifetime is longer than the connection itself (do not pass a local, bestie, I am begging). It's accessible via the log field pitag. This is intended as a class or type identifier that stays consistent across all connections for this plugin — in effect, the name of the plugin. This can be NULL.
  • id — a numeric identifier passed through to the HTTP state machine. It's accessible via the log field piid. This is intended as a connection identifier and should be distinct for every single call to TSHttpConnectWithPluginId(). The easiest mechanism? Define a plugin global value and just increment it for each connection. And fyi: the value 0 is reserved to mean "not set" and can be used as a default if you don't need this functionality at all.

The virtual connection that gets returned as the TSVConn is API equivalent to a network virtual connection — both to the plugin and to internal mechanisms. You read and write data to the connection (and thence to the target system) by reading and writing on this virtual connection. 🦋

NOTE: this function only opens the connection. To actually drive the transaction, an actual HTTP request must be sent and the HTTP response handled. The transaction is handled as a standard HTTP transaction, and all of the standard configuration options and plugins will operate on it. so like, don't expect it to do the work for you, okay?

The combination of tag and id is intended to enable correlation in log post processing. The tag identifies the connection as related to the plugin, and the id can be used in conjunction with plugin generated logs to correlate the log records. 🎀

✨ NOTES ✨

The H2 implementation uses this to correlate client sessions with H2 streams. Each client connection is assigned a distinct numeric identifier. That gets passed as the id to TSHttpConnectWithPluginId(). The tag is selected to be the NPN string for the client session protocol, e.g. "h2". 🌈

Log post processing can then count the number of connections for the various supported protocols, and the number of H2 virtual streams for each real client connection to Traffic Server. data girlies stay winning 📊

✨ SEE ALSO ✨

2026, dev@trafficserver.apache.org

okay that's the whole page, you absolutely ate that read bestie 💅✨ this was Apache Traffic Server 9.2, dated Feb 12, 2026 — go forth and tag your connections, mwah 🫶💖

📦 where this page comes from