Architecture Overview

Architecture Overview

Apache Traffic Server is a high-performance HTTP/HTTPS caching proxy server written in C++20. It uses an event-driven, multi-threaded architecture with a plugin system for extensibility.

Overview

ATS processes web traffic using a non-blocking, event-driven model built around Continuations — callback objects that handle asynchronous events. This design allows a small number of threads to handle tens of thousands of concurrent connections without blocking.

Key capabilities:

• HTTP/1.1, HTTP/2, and HTTP/3 (QUIC) support
• TLS termination
• Disk and RAM caching
• Extensible via C/C++ plugins

Event-Driven Model

Continuations

The Continuation class is the core abstraction for asynchronous programming in ATS. A Continuation is a callback object with a handler function that processes events:

class MyContinuation : public Continuation {
  int
  handle_event(int event, void *data)
  {
    switch (event) {
    case EVENT_SUCCESS:
      return EVENT_DONE;
    case EVENT_ERROR:
      return EVENT_ERROR;
    }
    return EVENT_CONT;
  }
};

Key rules:

• Never block in event handlers — use async I/O or schedule deferred work
• Return EVENT_DONE when complete, EVENT_CONT to continue, or EVENT_ERROR on failure
• Use EThread::schedule() for deferred work

Event Loop

Each event thread runs an event loop that processes Continuations. Work is scheduled onto threads, and the thread's loop dispatches events to the appropriate Continuation handlers. This is similar to Node.js or Nginx's event model, but implemented in C++.

Threading Model

ATS uses several specialized thread pools:

Event Threads (ET_NET)

The primary worker threads. These handle:

• Network I/O (accept, read, write)
• HTTP state machine processing
• Plugin hook execution
• Timer-based scheduling

Critical rule: Never block in event threads. Any blocking operation (sleep, synchronous I/O, mutex contention) stalls all connections on that thread.

DNS Threads

A dedicated thread pool for DNS resolution. DNS lookups are handed off to these threads so event threads aren't blocked waiting for DNS responses.

Disk I/O Threads

Handle cache disk operations. Disk reads and writes are dispatched to these threads and results are delivered back to event threads via Continuation callbacks.

Task Threads (ET_TASK)

For CPU-intensive work that shouldn't run on event threads (e.g., heavy computation, blocking plugin operations).

HTTP State Machine

The HttpSM class (src/proxy/http/HttpSM.cc) is the central component that orchestrates HTTP request processing. It's the single most important file in the codebase.

Request Processing Flow

1. Accept — Connection accepted by an event thread
2. Read Request — Parse client request headers
3. Remap — Apply URL remapping rules (remap.config)
4. Cache Lookup — Check if the response is cached
5. DNS Lookup — Resolve origin server (if cache miss)
6. Origin Connect — Connect to origin server
7. Read Response — Read origin response headers
8. Cache Write — Store response in cache (if cacheable)
9. Send Response — Send response to client

Plugins can hook into any stage of this flow.

Plugin Hooks

Plugins register for specific hook points to intercept and modify request/response processing:

Hook	When It Fires
TS_HTTP_READ_REQUEST_HDR_HOOK	After reading client request headers
TS_HTTP_SEND_REQUEST_HDR_HOOK	Before sending request to origin
TS_HTTP_READ_RESPONSE_HDR_HOOK	After reading origin response headers
TS_HTTP_SEND_RESPONSE_HDR_HOOK	Before sending response to client
TS_HTTP_TXN_START_HOOK	At the start of a transaction
TS_HTTP_TXN_CLOSE_HOOK	At the end of a transaction

Plugin System

ATS supports two types of plugins:

• Global plugins — Loaded at startup via plugin.config, affect all traffic
• Remap plugins — Attached to specific remap rules via @plugin= in remap.config

Plugins use the C API defined in include/ts/ts.h. A C++ wrapper is available in src/tscpp/.

Plugin Examples

• example/plugins/ — Simple reference implementations
• plugins/ — Production-quality stable plugins
• plugins/experimental/ — Newer experimental plugins

Key Source Files

File	Purpose
include/iocore/eventsystem/Continuation.h	Core async callback pattern
src/proxy/http/HttpSM.cc	HTTP state machine (most important file)
src/iocore/cache/Cache.cc	Cache implementation
include/ts/ts.h	Plugin C API (most stable interface)
include/tscore/ink_memory.h	Memory allocation functions
src/iocore/net/	Network I/O layer
src/proxy/http2/	HTTP/2 implementation
src/proxy/http3/	HTTP/3 implementation

Repository Structure

trafficserver/
├── ci/                    Quality assurance and CI tools
├── cmake/                 CMake build system files
├── configs/               Default configuration files
├── doc/                   Sphinx documentation (admin + developer guides)
├── example/               Example plugins
├── ext/                   External dependencies
├── include/               Header files
│   ├── ts/                Public plugin API (ts.h)
│   ├── tscpp/             C++ plugin API
│   └── iocore/            Internal headers
├── lib/                   Third-party libraries (Catch2, swoc, yamlcpp, ...)
├── plugins/               Stable core plugins
│   └── experimental/      Experimental plugins
├── src/                   Source code
│   ├── api/               C Plugin API implementation
│   ├── cripts/            Cripts scripting framework
│   ├── iocore/            I/O subsystem
│   │   ├── cache/         Disk and RAM cache
│   │   ├── dns/           DNS resolution
│   │   ├── eventsystem/   Event-driven engine
│   │   ├── hostdb/        Internal DNS cache
│   │   └── net/           Network I/O (incl. QUIC)
│   ├── proxy/             HTTP proxy logic
│   │   ├── http/          HTTP/1.x (HttpSM.cc is central)
│   │   ├── http2/         HTTP/2
│   │   ├── http3/         HTTP/3
│   │   ├── hdrs/          Header parsing
│   │   └── logging/       Flexible logging
│   ├── tscore/            Core utilities
│   └── tsutil/            Utilities (metrics, debugging, regex)
├── tests/                 Tests (AuTest, unit tests)
└── tools/                 Utility scripts and tools

See Also

• HTTP 3 Documentation — HTTP/3 and QUIC design and build instructions
• Getting Started — Building and running ATS
• Developer's Guide — Full developer documentation