HTTP Server¶

Namespace: dftracer::utils::server

source

struct HttpRequest¶

Public Functions

int parse(const char *buf, std::size_t len)¶: Parse from receive buffer. Returns bytes consumed on success, -1 on error, -2 if incomplete.

std::string_view header(std::string_view name) const¶: Find a header value by name (case-insensitive).

bool has_header(std::string_view name, std::string_view value) const¶: Check if header matches value (case-insensitive).

Public Members

std::string_view method¶

std::string_view path¶

int minor_version¶

std::vector<std::pair<std::string_view, std::string_view>> headers¶

source

struct HttpResponse¶

Public Types

using StreamGenerator = coro::AsyncGenerator<StreamChunk>¶

Public Functions

inline bool is_streaming() const¶

std::string serialize_headers() const¶: Serialize HTTP response headers to string (CRLF-terminated). Automatically adds Content-Length if body is non-empty and not already set.

std::string serialize() const¶: Full response (headers + body).

Public Members

int status_code¶

std::string status_text¶

std::vector<std::pair<std::string, std::string>> headers¶

std::string body¶

std::unique_ptr<StreamGenerator> stream¶

Public Static Functions

static HttpResponse ok()¶

static HttpResponse ok(const std::string &body, const std::string &content_type = "application/json")¶

static HttpResponse not_found()¶

static HttpResponse bad_request(const std::string &msg)¶

static HttpResponse internal_error(const std::string &msg)¶

static HttpResponse streaming(std::unique_ptr<StreamGenerator> gen, const std::string &content_type = "application/x-ndjson")¶

struct StreamChunk¶

Public Members

std::span<const std::string_view> views¶

source

struct QueryCursor¶

Cursor for paginated trace queries. Encodes the current position in the scan across files and chunks for efficient resumption.

Public Functions

std::string encode() const¶: Base64-encode the cursor for URL-safe transmission.

Public Members

std::size_t file_index¶

std::uint32_t chunk_index¶

std::uint32_t line_offset¶

Public Static Functions

static std::optional<QueryCursor> decode(std::string_view cursor)¶: Decode a cursor from a Base64 string.

source

class QueryParams¶

Simple URL query parameter map.

Public Functions

std::string_view get(std::string_view key, std::string_view default_value = {}) const¶

bool has(std::string_view key) const¶

int get_int(std::string_view key, int default_value = 0) const¶

double get_double(std::string_view key, double default_value = 0) const¶

Public Static Functions

static QueryParams parse(std::string_view query)¶: Parse from a query string (“key=value&key2=value2”).

source

struct Route¶

A registered route plus its docs.

Public Members

std::string method¶

std::string path¶

RouteHandler handler¶

RouteDoc doc¶

source

struct RouteDoc¶

Optional documentation attached to a route. When summary is empty the route is treated as internal and left out of the generated docs.

Public Members

std::string summary¶

std::string tag¶

std::vector<RouteParam> params¶

std::string response_example¶

source

struct RouteParam¶

One query parameter of a route, for the generated API docs / OpenAPI spec.

Public Members

std::string name¶

std::string desc¶

bool required¶

std::string example¶

source

class Router¶

Simple prefix-based HTTP router.

Public Functions

void get(const std::string &path, RouteHandler handler)¶

void get(const std::string &path, RouteHandler handler, RouteDoc doc)¶

void post(const std::string &path, RouteHandler handler)¶

void post(const std::string &path, RouteHandler handler, RouteDoc doc)¶

inline const std::vector<Route> &routes() const¶: Registered routes in registration order (for API-docs generation).

inline void set_auth_token(std::string token)¶: When non-empty, every request must present this token (via a ?token= query param or an “Authorization: Bearer <token>” header) or gets 401.

coro::CoroTask<HttpResponse> handle(const HttpRequest &req)¶: Match request method + path, parse query params, invoke handler. Returns 404 if no route matches.

source

class TcpListener¶

TCP listener that accepts connections and spawns per-connection coroutine handlers using structured concurrency.

Public Types

using ConnectionHandler = std::function<coro::CoroTask<void>(int client_fd, struct sockaddr_in addr)>¶: Accept loop: yields new client fds via coroutine. Runs until stop() is called or the listen socket is closed. Spawns handler(client_fd, addr) for each accepted connection.

Public Functions

TcpListener(const std::string &addr, uint16_t port)¶

~TcpListener()¶

TcpListener(const TcpListener&) = delete¶

TcpListener &operator=(const TcpListener&) = delete¶

bool start(int backlog = 128)¶: Bind and listen. Returns true on success.

coro::CoroTask<void> accept_loop(CoroScope &scope, ConnectionHandler handler)¶

void stop()¶: Request graceful shutdown. The accept loop will break on the next iteration. In-flight handlers drain via CoroScope.

inline int fd() const¶

inline uint16_t port() const¶

source

class TraceIndex¶

Scans a directory for trace files and caches paths to their root-local .dftindex database. Used by API handlers to resolve file paths and check index availability.

Public Types

using BloomCache = dftracer::utils::utilities::composites::dft::indexing::BloomFilterCache ¶

Public Functions

TraceIndex(const std::string &directory, const std::string &index_dir, std::size_t max_concurrent = 8)¶

coro::CoroTask<void> initialize()¶: Scan directory and populate the file list.

inline std::size_t file_count() const¶

inline const std::vector<FileInfo> &files() const¶

const FileInfo *find_file(const std::string &path) const¶: Find a file by its path. Returns nullptr if not found.

const FileInfo *file_at(std::size_t index) const¶: Find a file by index. Returns nullptr if out of range.

inline const std::string &directory() const¶

inline const std::string &index_dir() const¶

inline std::size_t max_concurrent() const¶

inline BloomCache &bloom_cache()¶

inline std::uint64_t global_min_timestamp_us() const¶

inline std::uint64_t global_max_timestamp_us() const¶

inline const VizSummary *viz_summary() const¶

inline bool try_begin_summary_build()¶

inline void set_viz_summary(std::unique_ptr<VizSummary> summary)¶

struct FileInfo¶

Public Members

std::string path¶

std::string index_path¶

bool has_bloom_data¶

bool has_checkpoint_index¶

std::uint64_t min_timestamp_us¶

std::uint64_t max_timestamp_us¶

std::uint64_t compressed_size¶

std::uint64_t uncompressed_size¶

std::size_t num_checkpoints¶

std::uint64_t checkpoint_size¶

std::uint64_t num_lines¶

double size_mb¶

source

struct VizSummary¶

Public Functions

inline std::int64_t bucket_of(double abs_ts) const¶

Public Members

std::uint64_t t_begin¶

std::uint64_t t_end¶

std::size_t nbuckets¶

double bucket_us¶

std::uint64_t max_dur¶

std::vector<Lane> lanes¶

std::vector<double> read_bytes¶

std::vector<double> write_bytes¶

std::vector<double> ops¶

std::vector<std::string> names¶

std::vector<GroupRow> by_name¶

std::vector<GroupRow> by_cat¶

std::vector<GroupRow> by_pid¶

std::vector<GroupRow> by_fhash¶

std::vector<std::pair<std::string, std::string>> name_cats¶

std::size_t total_files¶

std::size_t io_files¶

std::vector<AppSpan> app_spans¶

std::vector<std::pair<std::uint64_t, std::uint64_t>> idle_gaps¶

Public Static Attributes

static constexpr std::size_t MAX_CELLS¶

static constexpr std::size_t MIN_BUCKETS_PER_LANE¶

static constexpr std::size_t MAX_BUCKETS_PER_LANE¶

struct AppSpan¶

Public Members

std::uint64_t begin¶

std::uint64_t end¶

std::int64_t pid¶

std::int64_t tid¶

std::string json¶

struct Cell¶

Public Members

std::uint32_t count¶

std::uint64_t total¶

std::uint32_t max_dur¶

std::uint32_t name_id¶

struct GroupRow¶

Public Members

std::string key¶

std::uint64_t count¶

double total¶

double min¶

double max¶

struct Lane¶

Public Members

std::int64_t pid¶

std::int64_t tid¶

std::vector<Cell> cells¶

Free Functions¶

source

std::vector<const TraceIndex::FileInfo*> dftracer::utils::server::collect_candidate_files(TraceIndex &index, const QueryParams &params)¶: Collect the candidate files for a streaming query: the explicit ?file= (when present and found in the index) or all indexed files. Callers apply their own timestamp-overlap filter on top of this.

source

coro::CoroTask<void> dftracer::utils::server::handle_connection(int client_fd, struct sockaddr_in addr, Router &router)¶: Handle a single HTTP/1.1 connection: read requests, route them, send responses. Supports keep-alive (HTTP/1.1 default).

source

void dftracer::utils::server::install_signal_handlers()¶: Install SIGINT/SIGTERM handlers that set g_shutdown_requested and shutdown the listen socket to unblock accept().

source

void dftracer::utils::server::register_trace_api(Router &router, TraceIndex &index)¶: Register trace data API endpoints on the router: GET /api/v1/files — list available trace files GET /api/v1/files/info — file metadata (?file=…) GET /api/v1/events — query events with filters GET /api/v1/events/stream — stream events as NDJSON GET /api/v1/stats — aggregated statistics GET /api/v1/info — global time bounds and file summary

source

void dftracer::utils::server::register_viz_api(Router &router, TraceIndex &index)¶: Register visualization API endpoints on the router: GET /api/v1/viz/events — query events for visualization with time-range windowing, lane grouping, and summary aggregation

source

void dftracer::utils::server::register_viz_ui(Router &router)¶: Register the UI + API-docs routes: the SPA at GET / and /index.html, the API explorer page at GET /api, and the OpenAPI spec at GET /api/openapi.json.

source

inline simdjson::builder::string_builder &dftracer::utils::server::scratch_json_builder()¶

source

std::string_view dftracer::utils::server::viz_api_page_html()¶: Return the embedded API explorer page, generated from web/dist/api.html.

source

std::string_view dftracer::utils::server::viz_index_html()¶: Return the embedded single-page trace viewer. The body is generated at build time from web/dist/index.html by cmake/scripts/embed_asset.cmake.