/* ========================================================================== * http3_pipeline.h -- SLeeLa HTTP 3.0 reference processing pipeline (spec §19) * with idempotency/retry classes (spec §9). * * The pipeline is the DATA FLOW that drives an HTTP 3.0 exchange. It makes the * spec's §19 hot path explicit and traceable: * * receive -> minimal parse -> service-id lookup -> operation-id lookup * -> compact unpack -> SLeeLa dispatch -> business logic * -> compact result pack -> response * * A registered service exposes operations; each operation declares a retry * class (§9) and a handler. Dispatch is keyed on the compact SERVICE-ID/OP-ID * from the envelope (§4/§5), never on a re-parsed name in the hot path. * ========================================================================== */ #ifndef HTTP3_PIPELINE_H #define HTTP3_PIPELINE_H #include #include #include "http3_envelope.h" #include "http3_naming.h" #include "http3_timing.h" #ifdef __cplusplus extern "C" { #endif /* Retry classes (§9). Declared per operation so a client/connector can decide * whether an uncertain transport failure may be safely repeated. */ typedef enum { HTTP3_RETRY_READ = 0, /* safe to retry when semantics permit */ HTTP3_RETRY_IDEMPOTENT = 1, /* repeat produces the same intended state */ HTTP3_RETRY_MUTATING = 2, /* retry needs explicit policy/idempotency key*/ HTTP3_RETRY_STREAM = 3 /* retry semantics are operation-specific */ } http3_retry_class_t; /* * Business-logic handler for one operation. It receives the request payload * and writes a result payload plus an application status (§7). The handler is * pure application logic; the pipeline owns parse/dispatch/pack around it. */ typedef http3_status_t (*http3_op_handler_t)(const uint8_t *payload, size_t payload_len, uint8_t *result, size_t result_cap, size_t *result_len, void *service_ctx); typedef struct { uint32_t op_id; http3_retry_class_t retry_class; http3_op_handler_t handler; } http3_op_binding_t; typedef struct { uint32_t service_id; void *ctx; /* opaque per-service state passed to handlers */ http3_op_binding_t ops[HTTP3_MAX_OPS_PER_SVC]; size_t op_count; } http3_service_binding_t; /* The pipeline: the naming dictionary plus the dispatch table. One instance * per connection/service host embodies the reusable state the §19 hot path * relies on. */ typedef struct { http3_naming_t naming; http3_service_binding_t services[HTTP3_MAX_SERVICES]; size_t service_count; uint64_t requests_handled; /* observability (§17) */ uint16_t intactx_threshold;/* INTACTX variance tamper limit */ uint64_t digest_rejects; /* packets dropped: bad DIGEST */ uint64_t tamper_resets; /* packets reset: INTACTX tamper */ uint64_t replays_rejected; /* packets dropped: stale NONCE */ uint8_t mac_key[HTTP3_MAC_KEY_BYTES]; /* per-conn MAC key */ uint64_t nonce_high_water; /* highest accepted NONCE so far */ /* Connection-level timing (advisory; no wire change). */ http3_timing_t timing; /* max-speed/on-time/balance state */ uint64_t late_packets; /* observed: missed deadline */ uint64_t over_rate_packets;/* observed: faster than max speed */ uint64_t unbalanced_packets;/* observed: jitter out of band */ } http3_pipeline_t; /* Initialize an empty pipeline. The INTACTX tamper threshold defaults to * HTTP3_INTACTX_TAMPER_THRESHOLD. The per-connection MAC key starts all-zero; * set the real key (from key agreement) with http3_pipeline_set_mac_key before * handling wire packets, so the DIGEST is verified against a shared secret. */ void http3_pipeline_init(http3_pipeline_t *pipe); /* Set the INTACTX variance threshold above which an inbound packet is treated * as coming from a tampered host and RESET. Pass 0 to restore the default. */ void http3_pipeline_set_intactx_threshold(http3_pipeline_t *pipe, uint16_t threshold); /* Install the 16-byte per-connection MAC key used to verify each packet's * keyed-MAC DIGEST. In a deployment this is the secret from the crypto * substrate's key agreement; peers that share it can authenticate each other's * packets, and a forger without it cannot produce a valid DIGEST. */ void http3_pipeline_set_mac_key(http3_pipeline_t *pipe, const uint8_t key[HTTP3_MAC_KEY_BYTES]); /* Reset the replay window (NONCE high-water mark) to `start`. The next packet * accepted must carry a NONCE strictly greater than `start`. Use when a new * connection/session begins; a real multi-sender deployment keys the window per * sender identity, but the single-connection reference keeps one monotonic * high-water mark. */ void http3_pipeline_reset_replay_window(http3_pipeline_t *pipe, uint64_t start); /* Configure connection-level timing bounds (max speed / on-time grace / balance * band), in nanoseconds. Pass 0 for any field to keep its current value. */ void http3_pipeline_set_timing(http3_pipeline_t *pipe, uint64_t min_gap_ns, uint64_t lateness_ns, uint64_t balance_ns); /* * Observe a received packet's timing: `arrival_ns` is when it arrived and * `deadline_ns` (0 if none) is when it was due. ADVISORY only -- it never * rejects a packet; it updates the running carrier-certainty estimate and the * late/over-rate/unbalanced counters. Returns the advisory flags for this * packet (see http3_timing_flag_t). Call it alongside http3_pipeline_handle_wire * for each packet whose arrival time you have. */ unsigned http3_pipeline_observe_timing(http3_pipeline_t *pipe, uint64_t arrival_ns, uint64_t deadline_ns); /* Current carrier-certainty estimate in [0,1] (how dependable the path looks). */ double http3_pipeline_carrier_certainty(const http3_pipeline_t *pipe); /* * Register a service by name, returning its compact SERVICE-ID (§4). ctx is * handed to every handler of this service. */ uint32_t http3_pipeline_register_service(http3_pipeline_t *pipe, const char *service_name, void *ctx); /* * Register an operation by name under a service. Returns the compact OP-ID. * The retry class (§9) and handler are recorded for dispatch. */ uint32_t http3_pipeline_register_op(http3_pipeline_t *pipe, const char *service_name, const char *op_name, http3_retry_class_t retry_class, http3_op_handler_t handler); /* Query the retry class of an operation (§9). Returns -1 if unknown. */ int http3_pipeline_retry_class(const http3_pipeline_t *pipe, uint32_t service_id, uint32_t op_id); /* * The §19 hot path over an already-parsed envelope: service-id lookup -> * op-id lookup -> dispatch -> business logic -> result pack into `resp`. * Returns 0 if a response was produced (even an error response), -1 only on a * NULL argument. The response status distinguishes app failure from transport. */ int http3_pipeline_dispatch(http3_pipeline_t *pipe, const http3_envelope_t *env, http3_response_t *resp); /* * Full receive path (§19 from "HTTP receive"): takes a wire buffer (textual or * binary, auto-detected), performs minimal parse + unpack, then an integrity * gate (per-packet DIGEST verify, then INTACTX tamper check), then dispatch. * A packet whose DIGEST fails is rejected (BAD_DIGEST); a packet whose INTACTX * variance exceeds the threshold is RESET (TAMPERED, response carries * HTTP3_FLAG_RESET) and never dispatched. Writes a packed textual response into * out/out_cap. Returns 0 on success. */ int http3_pipeline_handle_wire(http3_pipeline_t *pipe, const uint8_t *wire, size_t wire_len, char *out, size_t out_cap, size_t *written); #ifdef __cplusplus } #endif #endif /* HTTP3_PIPELINE_H */