alknet/tasks/http/crate-init.md

id, name, status, depends_on, scope, risk, impact, level

id	name	status	depends_on	scope	risk	impact	level
http/crate-init	Initialize alknet-http crate with Cargo.toml, dependencies, and module skeleton	completed		moderate	low	project	implementation

Description

Initialize the alknet-http crate from scratch. This crate is the HTTP interface for alknet: it serves inbound HTTP on standard ALPNs (h2, http/1.1, with WebSocket upgrade for browser bidirectional access to the call protocol) and hosts the HTTP-backed call-protocol adapters (from_openapi, to_openapi, from_mcp, to_mcp). HTTP/3 + WebTransport (h3) is deferred per ADR-044 and is not part of this crate's initial release.

The crate has two roles in one (ADR-039): HTTP server (HttpAdapter, a ProtocolHandler for h2/http/1.1 + WS upgrade) and HTTP client host (from_openapi/from_mcp forwarding via reqwest, to_openapi/to_mcp projections via axum). Both directions share the same HTTP dependencies, which is why they live in one crate.

Crate setup

Create crates/alknet-http/ with:

• Cargo.toml — package metadata, dependencies, feature gates
• src/lib.rs — crate root with module declarations and re-exports
• Module skeleton files for:
  • src/server/mod.rs — HttpAdapter, axum-over-QUIC, gateway routes, /healthz, decoy, custom routes
  • src/gateway/mod.rs — shared dispatch spine (GatewayDispatch), error mapping
  • src/client/mod.rs — shared HTTP client (ClientWithMiddleware)
  • src/adapters/mod.rs — from_openapi, to_openapi, from_mcp, to_mcp
  • src/websocket/mod.rs — WS upgrade handler, framing, dispatch handoff

Dependencies

Crate	Purpose	Feature gate
alknet-core	ProtocolHandler, Connection, AuthContext, Capabilities, IdentityProvider, AuthToken, Identity, HandlerError (workspace path)	default
alknet-call	OperationAdapter, AdapterError, OperationSpec, Handler, HandlerRegistration, OperationRegistry, OperationProvenance, OperationContext, ResponseEnvelope, CallError, EventEnvelope, Dispatcher, CallConnection (workspace path)	default
axum	HTTP server — Router, extractors, middleware, WebSocket upgrade	default
hyper	HTTP/1.1 + HTTP/2 framing (axum is built on hyper)	default
reqwest	HTTP client — from_openapi/from_mcp forwarding	default
reqwest-middleware	ClientWithMiddleware wrapper for middleware stack	default
reqwest-retry	RetryTransientMiddleware / ExponentialBackoff	default
tokio 1 (full)	Async runtime	default
serde 1	Serialization	default
serde_json 1	JSON wire format, JSON Schema values	default
async-trait 0.1	Async traits	default
tracing 0.1	Structured logging	default
thiserror 2	Error enums	default
uuid 1	Request ID generation (UUID v4)	default
futures	Stream trait for SSE / subscriptions	default
rmcp	MCP streamable HTTP — from_mcp/to_mcp	mcp feature
openapiv3	OpenAPI document types (or a local type — two-way door)	default

Feature gates

[features]
default = ["h2", "http1"]
mcp = ["dep:rmcp"]
# h3 (HTTP/3 + WebTransport) is deferred per ADR-044 — not in the v1
# feature set. The browser bidirectional path uses WebSocket (native to
# axum, no feature gate). When WebTransport revives, the `h3` feature
# gate returns; see ADR-044 and webtransport.md.

• h2 + http1 (default): the axum + hyper HTTP/1.1 + HTTP/2 server, including WebSocket upgrade for browser bidirectional access (ADR-044).
• mcp: the rmcp dependency with streamable HTTP transport features only (ADR-037 — stdio is excluded). Adds from_mcp/to_mcp.

Workspace Cargo.toml

Add crates/alknet-http to the workspace members list in the root Cargo.toml.

Module skeleton

// src/lib.rs
//! alknet-http: HTTP interface for alknet — serves HTTP/1.1 + HTTP/2 on
//! standard ALPNs (with WebSocket upgrade for browser bidirectional access)
//! and hosts the HTTP-backed call-protocol adapters.
//!
//! Two roles in one crate (ADR-039): HTTP server (HttpAdapter, a
//! ProtocolHandler for h2/http1.1 + WS upgrade) and HTTP client host
//! (from_openapi/from_mcp forwarding, to_openapi/to_mcp projections).

pub mod server;
pub mod gateway;
pub mod client;
pub mod adapters;
pub mod websocket;

Each module file gets a doc comment and // TODO: implement marker.

Acceptance Criteria

• crates/alknet-http/Cargo.toml exists with all dependencies and feature gates
• crates/alknet-http/src/lib.rs exists with module declarations
• All module skeleton files exist (server/, gateway/, client/, adapters/, websocket/)
• Root Cargo.toml members list includes crates/alknet-http
• cargo check -p alknet-http succeeds
• cargo clippy -p alknet-http succeeds with no warnings
• Dual licensing: MIT OR Apache-2.0 (workspace-inherited)
• alknet-core dependency uses workspace path (path = "../alknet-core")
• alknet-call dependency uses workspace path (path = "../alknet-call")
• mcp feature gate pulls in rmcp with streamable HTTP transport features only (no stdio)
• h3/WebTransport dependency is absent (deferred per ADR-044)

References

• docs/architecture/crates/http/README.md — crate index
• docs/architecture/crates/http/overview.md — crate overview, dependencies, feature gates
• docs/architecture/decisions/003-crate-decomposition.md — ADR-003 (Amendment 1: alknet-call is protocol-foundation)
• docs/architecture/decisions/039-http-server-and-client-host-colocated.md — ADR-039 (one crate for server + client host)
• docs/architecture/decisions/044-defer-webtransport-browsers-use-websocket.md — ADR-044 (h3 deferred)
• docs/architecture/decisions/037-mcp-stdio-transport-exclusion.md — ADR-037 (streamable HTTP only)

Notes

alknet-http depends on alknet-core (ProtocolHandler, Connection, IdentityProvider, Capabilities) and alknet-call (OperationAdapter, OperationRegistry, HandlerRegistration, EventEnvelope, Dispatcher). The crate has five subsystems: server (HttpAdapter, axum over QUIC), gateway (shared dispatch spine, error mapping), client (shared HTTP client), adapters (from_openapi/to_openapi/from_mcp/to_mcp), and websocket (WS upgrade, native session). The module structure reflects this split. The mcp feature gate is optional; the default feature set is h2 + http1. The h3/WebTransport dependency is absent (deferred per ADR-044).

Summary

Crate initialized: crates/alknet-http with Cargo.toml, src/lib.rs, and five subsystem module skeletons (server, gateway, client, adapters, websocket). Workspace members list updated. Deps: alknet-core, alknet-call (workspace path), axum, hyper, reqwest stack, openapiv3; rmcp optional behind mcp feature (streamable HTTP only, ADR-037). h3/WebTransport absent (ADR-044). Verified: cargo check, build, clippy -D warnings, test, and --features mcp all pass.