alknet/tasks/endpoint/crate-init.md

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

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

Description

Phase 2, Task 1 of the crate extraction (per docs/research/alknet-crate-extraction/findings.md). Initialize the alknet-endpoint crate from scratch. This crate provides the server-side multi-transport accept-loop runner — AlknetEndpoint, HandlerRegistry, and the transport-specific accept loops (quinn, iroh, TCP+TLS).

The endpoint takes pre-built transports via builder methods (with_quinn, with_iroh, with_tcp_tls) — it does not build transports and does not depend on alknet-tls. The assembly layer builds transports from alknet-tls's TlsServerConfig and hands them to the endpoint. See docs/architecture/crates/endpoint/README.md for the full spec.

Crate setup

Create crates/alknet-endpoint/ with:

• Cargo.toml — package metadata, dependencies, feature flags
• src/lib.rs — crate root with module declarations and re-exports
• Module skeleton files for:
  • src/registry.rs — HandlerRegistry (extracted from endpoint.rs lines 66-116)
  • src/endpoint.rs — AlknetEndpoint struct, new, builder methods, run, shutdown (built fresh against ADR-083 shape)
  • src/dispatch.rs — dispatch (public), build_auth_context, ACME guard (extracted from endpoint.rs lines 330-490)
  • src/accept/mod.rs — accept module declarations
  • src/accept/quinn.rs — dispatch_quinn, run_quinn_accept_loop, extract_quinn_alpn, extract_quinn_client_fingerprint (extracted from endpoint.rs lines 287-388)
  • src/accept/iroh.rs — dispatch_iroh, run_iroh_accept_loop, extract_iroh_client_fingerprint (extracted from endpoint.rs lines 390-472)
  • src/accept/tcp_tls.rs — dispatch_tcp_tls, run_tcp_tls_accept_loop, extract_tcp_tls_alpn, extract_tcp_tls_client_fingerprint (new code, not in current endpoint.rs)

Dependencies

Per the findings (Phase 2) and the architecture spec:

Crate	Purpose
alknet-core	Connection, ProtocolHandler, AuthContext, IdentityProvider, DynamicConfig (workspace path)
quinn 0.11	QUIC transport (optional, feature-gated)
iroh 0.28	Iroh transport (optional, feature-gated)
tokio-rustls 0.26	TCP+TLS transport (optional, feature-gated)
tokio 1 (full)	Async runtime, spawn, watch, TcpListener
arc-swap 1	DynamicConfig
tracing 0.1	Structured logging

The endpoint does not depend on alknet-tls — it takes pre-built transports. TLS config construction stays at the assembly layer.

Feature flags

[features]
default = []
quinn = ["dep:quinn", "alknet-core/quinn"]      # with_quinn — quinn accept loop
iroh = ["dep:iroh", "alknet-core/iroh"]          # with_iroh — iroh accept loop
tcp = ["dep:tokio-rustls"]                       # with_tcp_tls — TCP+TLS accept loop

The quinn/iroh features pull the corresponding features on alknet-core (for Connection::from_quinn / from_iroh — the constructors stay in core). A deployment enables the features for the transports it runs.

Workspace Cargo.toml

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

Module skeleton

// src/lib.rs
//! alknet-endpoint: Server-side multi-transport accept-loop runner.
//!
//! `AlknetEndpoint` takes pre-built transports (quinn, iroh, TCP+TLS) via
//! builder methods, runs their accept loops inside `run()`, and dispatches
//! each accepted connection to the registered `ProtocolHandler` by ALPN.
//!
//! The endpoint does not build transports and does not depend on
//! `alknet-tls` — transport construction is the assembly layer's concern.

pub mod accept;
pub mod dispatch;
pub mod endpoint;
pub mod registry;

// Re-exports (filled in by subsequent tasks)

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

Acceptance Criteria

• crates/alknet-endpoint/Cargo.toml exists with all dependencies and feature flags
• crates/alknet-endpoint/src/lib.rs exists with module declarations
• Module skeleton files exist: registry.rs, endpoint.rs, dispatch.rs, accept/mod.rs, accept/quinn.rs, accept/iroh.rs, accept/tcp_tls.rs
• Root Cargo.toml members list includes crates/alknet-endpoint
• cargo check -p alknet-endpoint succeeds
• cargo clippy -p alknet-endpoint succeeds with no warnings
• Dual licensing: MIT OR Apache-2.0 (workspace-inherited)
• alknet-core dependency uses workspace path (path = "../alknet-core")
• No dependency on alknet-tls (endpoint takes pre-built transports)
• Feature flags: quinn, iroh, tcp (all optional, default off)

References

• docs/research/alknet-crate-extraction/findings.md — Phase 2
• docs/architecture/crates/endpoint/README.md — full architecture spec
• docs/architecture/decisions/083-endpoint-as-accept-loop-runner.md — ADR-083
• crates/alknet-core/Cargo.toml — reference for dep versions
• crates/alknet-tls/Cargo.toml — reference for feature flag pattern

Notes

This is the foundational setup task for alknet-endpoint. All subsequent endpoint/* tasks depend on this one. The crate has no alknet dependencies beyond core. The endpoint does NOT depend on alknet-tls — it takes pre-built transports via builder methods. The quinn/iroh features pull the corresponding features on alknet-core for Connection::from_quinn / from_iroh constructors.

Summary

To be filled on completion