Skip to content

Kinetic

KinetiC is a high-performance, cross-platform HTTP/1.1 server written in C. It was conceived not as a continuation of CServe, but as a complete response to its design flaws. While CServe was built on ad-hoc feature implementations under product constraints, KinetiC was designed from the ground up to follow strict RFC 9110 / 9112 compliance and invariant-based state machines.

Here is the story of how KinetiC was built, following the actual commit history, functions, structures, and developmental steps of the project.

timeline
    title KinetiC Architectural Milestones
    Genesis : Core Allocators & String Helpers : Arena allocator (ktc_arena) & zero-copy slices (ktc_str)
    Event Loop : libuv & YAML Parsing : Non-blocking connection management & Cloud-Native YAML config
    Request Parsing : Strict RFC State Machine : Invariant-based parsing of Request Line and Headers
    Framing & Bodies : Content-Length & Chunked Transfer : Handling request bodies and dynamic streaming

Phase 1: Genesis and Memory Safety (Commits 49e4aec - ee531f9)

The project began with a deliberate choice: no raw string manipulation or garbage-prone heap allocations on the hot path. To achieve this, the very first commits set up the core utilities:

  • ktc_str: A non-owning octet slice { const uint8_t *ptr; size_t len; }. Pointing directly to client read buffers, it avoids memory copies and expensive strlen calls. Since HTTP specifies octet-based wire data, uint8_t is used to prevent Unicode validation overhead. String operations include byte-for-byte equality checking (ktc_str_eq), case-insensitive checks for headers (ktc_str_eq_case_insensitive), and lexicographic sorting (ktc_str_cmp).
  • ktc_arena: A fast, zero-deallocation bump allocator represented by ktc_arena_t. It manages regional memory blocks. Connection blocks are allocated via ktc_arena_alloc() and initialized via ktc_arena_calloc(). When a persistent connection completes a request, ktc_arena_reset() rewinds the bump pointer to the first block and frees any overflow regions, completely eliminating heap fragmentation.

Phase 2: Event-Loop Integration & Configuration (Commits 09cb106 - 777d68f)

With the memory foundations laid, the next phase introduced asynchronous network I/O and configuration handling:

  • Asynchronous I/O via libuv: Instead of raw socket management or direct epoll calls, KinetiC adopted libuv for cross-platform event loops. It sets up one loop (uv_loop_t) per worker. Sockets are initialized as TCP handles (uv_tcp_t), and connections are registered using non-blocking read (uv_read_start) and write (uv_write) flows.
  • YAML Configuration (parseyml.c): Settings are parsed via libyaml from configurations like test_config.yaml.
  • Integration Testing: Added Python-based integration tests and signal handlers (uv_signal_t) to test graceful shutdowns.

Phase 3: Invariant-Based Parsing (Commits 2b9f276 - d0f62e9)

Rather than relying on destructive string-modifying functions like strtok (which fail on partial TCP packet streams), KinetiC implemented a strict character-by-character state machine:

  • Request Line Parser (ktc_req_line_parser_t): An incremental parser driven by ktc_req_line_parser_feed(). It processes bytes through states:
    • KTC_REQ_LINE_STATE_IDLE
    • KTC_REQ_LINE_STATE_SKIP_EMPTY (skipping leading CRLFs)
    • KTC_REQ_LINE_STATE_METHOD
    • KTC_REQ_LINE_STATE_TARGET
    • KTC_REQ_LINE_STATE_VERSION
    • KTC_REQ_LINE_STATE_CRLF
    • KTC_REQ_LINE_STATE_COMPLETE
    • Errors are caught early: KTC_REQ_LINE_ERR_BAD_SYNTAX for spacing anomalies, KTC_REQ_LINE_ERR_URI_TOO_LONG for buffer boundaries, and KTC_REQ_LINE_ERR_VERSION_NOT_SUPPORTED. Once parsed, ktc_req_line_parser_resolve() resolves target views against the main buffer.
  • Header Parsing State Machine (ktc_header_parser_t): Driven by ktc_header_parser_feed(), it parses headers into name-value pairs up to KTC_MAX_HEADERS (64). The states track names (KTC_HEADER_STATE_NAME), values (KTC_HEADER_STATE_VALUE), and end of sections (KTC_HEADER_STATE_DOUBLE_CRLF). It enforces strict Host header presence and duplicate rejection (KTC_HEADER_ERR_DUPLICATE_HOST / KTC_HEADER_ERR_MISSING_HOST).

Phase 4: Dynamic Request Framing (Commit 89fb402 - 5b1f249)

The latest major addition completed the parsing engine by introducing request body handling:

  • Framing Resolution: ktc_body_resolve_framing() examines headers to select KTC_BODY_FRAMING_LENGTH or KTC_BODY_FRAMING_CHUNKED based on RFC 9112 section 6.3 precedence rules.
  • Chunked Transfer Parser (ktc_chunk_parser_t): Implements an incremental chunk parsing state machine:
    • Parses hex chunk sizes (KTC_CHUNK_STATE_SIZE).
    • Skips extensions (KTC_CHUNK_STATE_EXTENSION).
    • Copies chunk data (KTC_CHUNK_STATE_DATA).
    • Decodes trailer headers (KTC_CHUNK_STATE_TRAILERS_DATA).
    • Completes at KTC_CHUNK_STATE_COMPLETE.

Core Architecture Summary

Layer Component Implementation
Networking Asynchronous I/O libuv Event Loop (uv_loop_t)
Allocation Memory Management ktc_arena (Per-connection bump allocator)
Parsing Wire Protocol Character-by-character FSM (RFC 9110 / 9112)
Config Server Settings YAML Loader

To Be Continued...

KinetiC is under active development. Upcoming phases include persistent session expiry timers (uv_timer_t), pipelining response queues, multi-process master/worker socket sharing (SO_REUSEPORT), and an interactive performance dashboard.