Home /Modules/http-3.0/http3_pipeline.h

http3_pipeline.h

http-3.0/http3_pipeline.h · 181 line(s) · c

/* ==========================================================================
 * 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 <stddef.h>
#include <stdint.h>

#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 */