Skip to content

Getting started

This section takes you from a checkout to a running server, then points to the next guide for each common task.

Prerequisites

aeronet requires a C++23 compiler and CMake 3.28 or newer. Linux is the primary platform; macOS and Windows are also supported through the same public API. Only 64-bit targets are supported. The complete toolchain matrix and package-manager instructions are in Installation and build.

Choose the features you need

The core build is intentionally modular. Enable optional capabilities at CMake configure time:

  • AERONET_ENABLE_OPENSSL for TLS and HTTPS.
  • AERONET_ENABLE_HTTP2 for HTTP/2, including ALPN and h2c.
  • AERONET_ENABLE_WEBSOCKET for RFC 6455 endpoints.
  • AERONET_ENABLE_ASYNC_HANDLERS for coroutine handlers.
  • AERONET_ENABLE_HTTP_CLIENT for the synchronous client and connection pool.
  • AERONET_ENABLE_HTTP_SERVER for the HttpServer
  • AERONET_ENABLE_OPENTELEMETRY for traces/metrics, AERONET_ENABLE_GLAZE for JSON/YAML configuration, and AERONET_ENABLE_JWT for JWT/JWKS. JWT is available only when both OpenSSL and Glaze are enabled.

Set AERONET_ENABLE_HTTP_CLIENTto OFF if you need only the server, or AERONET_ENABLE_HTTP_SERVER to OFF if you need only the client to minimize the code to be compiled.

Note that it is not possible to exclude both.

The build configuration reference explains every feature gate and dependency. The server and client references cover runtime controls.

Feature overview

What is implemented, what is optional (flag: enabled by a CMake option), and where each feature is documented.

Area What you get Read more
HTTP/1.1 parsing Request line, headers, chunked bodies, pipelining, deterministic and security-minded duplicate header policy, incoming request trailers Requests, HTTP/1.1 conformance
Routing Exact paths, path parameters and wildcards, method allow-lists, streaming and fixed handlers coexisting on one path (for instance streaming GET, fixed POST), heterogeneous path lookups (std::string, std::string_view, const char*) Routing
Connections and limits Keep-alive, maximum header and body sizes, maximum requests per connection, idle timeout Servers and lifecycle, Server configuration
Middleware Global and per-route request / response hooks (streaming-aware), rate limiting, CORS Middleware, CORS
Compression gzip, deflate, zstd and brotli; q-value negotiation, size threshold, per-response opt-out, direct compression Compression
Inbound decompression Multi-layer codings, safety guards, header removal, streaming inflaters once Content-Length exceeds a configured threshold Compression
Streaming and files Chunked responses, outgoing trailers, sendfile for plain sockets, range and conditional requests Streaming responses, Static files
Async handlers Coroutine handlers and background work off the event loop Async handlers
TLS (flag) ALPN, mTLS, SNI, session tickets, cached OCSP stapling, CRL and revocation hooks, debug key logs, kTLS, metrics TLS
HTTP/2 (flag) RFC 9113, HPACK, ALPN h2, h2c prior knowledge, stream multiplexing, incoming trailers HTTP/2
WebSocket (flag) RFC 6455, text / binary frames, ping / pong, close handshake WebSocket
HTTP client (flag) Synchronous HTTP/1.1 and HTTP/2, keep-alive pool, redirects, automatic (de)compression, HTTPS, streamed response bodies HTTP client
JWT (flag) RFC 7519 sign / verify, HS / RS / ES / PS / EdDSA, JWK / JWKS by kid, rejects alg: none JWT
Observability Logging (spdlog optional, ISO 8601 UTC timestamps), per-request metrics callback (alpha), OpenTelemetry traces and metrics (experimental, flag), outbound statistics (bytes queued, immediate vs flush writes, high-water marks) Observability, Performance
Event loop Edge-triggered epoll loop, one thread per SingleHttpServer, writev scatter-gather for header and body Performance and tuning
Scaling SO_REUSEPORT multi-reactor scaling, MultiHttpServer orchestrating N reactors on N threads Servers and lifecycle
Lifecycle RAII construction (listening after the constructor, ephemeral port resolved immediately), blocking run(), non-blocking start() and startDetached() (returns an AsyncHandle), restarts, move semantics, runtime configuration and router updates Servers and lifecycle
Graceful shutdown beginDrain(maxWait) stops accepting, closes keep-alive connections after the current responses, and can force-close stragglers; optional built-in SIGINT / SIGTERM handler Servers and lifecycle
Configuration Fluent HttpServerConfig setters (withPort(), ...), JSON / YAML files Server configuration, JSON and config files
Kubernetes Built-in liveness, readiness and startup probes Health probes, Kubernetes

The tests behind these features are summarized in the test coverage matrix. The exhaustive matrix of HTTP/1.1 behavior is the HTTP/1.1 conformance reference.

  1. Follow Your first server to run a route on port 8080.
  2. Read Routing and requests to add paths, parameters, and request handling.
  3. Read Requests and Responses, then Middleware, Streaming responses, or Static files as needed, and Async handlers when handlers make blocking calls.
  4. Add a protocol or module when needed: TLS, HTTP/2, WebSocket, the HTTP client, or JWT.

Tip

The repository's examples directory is the best source for complete, buildable programs. The guides focus on how the pieces fit together and link to those executable examples.