Module http_facade 

Transport-agnostic REST + SSE facade types (WEFT-122 / Cognitum gaps #6–#8).

Bound by clawft-services axum handlers; not a standalone server. HTTP REST facade with SSE streaming for WeftOS.

Closes Cognitum Seed gaps #6, #7, #8:

• Gap #6: GET /events SSE delta stream from KernelEventLog.
• Gap #7: POST /custody/witness external chain-event injection.
• Gap #8: REST API facade wrapping kernel Unix-socket RPC methods.

Architecture

This module is transport-agnostic: it defines typed request/response structs, an SSE event formatter, and a dispatch layer that maps HTTP routes to kernel operations. The actual HTTP server binding (axum, hyper, etc.) is left to the binary crate or clawft-services.

Feature Gate

Gated behind http-api. Not included in the default feature set.

Structs

FacadeResponse

HTTP status code + JSON body returned by the facade.

SseMessage

A single SSE message ready for wire formatting.

WitnessRequest

Request body for POST /custody/witness.

WitnessResponse

Response body for POST /custody/witness.

Enums

FacadeRoute

A matched facade route with its target RPC method.

HttpMethod

HTTP method for route matching.

RpcParam

Extracted route parameters (e.g., :pid from /api/agents/:pid).

SseEventType

Known SSE event types streamed on GET /events.

Constants

CONTENT_TYPE_JSON

Content-Type for JSON responses.

CONTENT_TYPE_SSE

Content-Type for SSE responses.

SSE_HEARTBEAT_COMMENT

SSE heartbeat comment frame (:heartbeat\n\n).

SSE_HEARTBEAT_INTERVAL_SECS

Default heartbeat interval in seconds.

Functions

build_rpc_params

Build RPC params JSON from the HTTP request body and route params.

classify_boot_event

Classify a kernel boot event into an SSE event type.

match_facade_route

Match an HTTP method + path to a facade route.

poll_events

Snapshot the event log and produce SSE messages for any new events since the given cursor position.

sse_response_headers

Required SSE response headers as (name, value) pairs.

verify_witness_signature

Validate a hex-encoded Ed25519 signature.