docs(architecture): spec alknet-core with per-crate subdocs, ADR-010/011
Add alknet-core architecture specs in docs/architecture/crates/core/ with focused subdocuments for core types, endpoint, auth, and config. Write ADR-010 (ALPN Router and Endpoint) defining AlknetEndpoint, HandlerRegistry, accept loop, and graceful shutdown. Write ADR-011 (AuthContext Structure) defining AuthContext fields, immutability in handle(), and IdentityProvider injection pattern. Resolve OQ-04 (static registration), OQ-12 (file paths only for v1). Add OQ-11 (auth observability). Fix remaining alknet-secret references to alknet-vault across ADRs 003/004/005/009.
This commit is contained in:
@@ -1,15 +1,15 @@
|
||||
---
|
||||
status: draft
|
||||
last_updated: 2026-06-16
|
||||
last_updated: 2026-06-17
|
||||
---
|
||||
|
||||
# Alknet Architecture
|
||||
|
||||
## Current State
|
||||
|
||||
**Pre-implementation.** The project has completed a pivot from a three-layer model to an ALPN-as-service model. The greenfield workspace contains only `alknet-vault` (stable) and research/reference material. Foundational ADRs (001–009) are in place, including the BiStream type definition (ADR-007), vault integration (ADR-008), and the one-way door decision framework (ADR-009). Architecture specs are ready for Phase 1 implementation planning.
|
||||
**Pre-implementation.** The project has completed a pivot from a three-layer model to an ALPN-as-service model. The greenfield workspace contains only `alknet-vault` (stable) and research/reference material. Foundational ADRs (001–011) are in place, including the BiStream type definition (ADR-007), vault integration (ADR-008), ALPN router/endpoint (ADR-010), and AuthContext structure (ADR-011). The alknet-core crate spec is in draft.
|
||||
|
||||
**Next step**: Resolve remaining two-way-door questions during implementation. Start with alknet-core (ProtocolHandler trait, Connection, endpoint, router, auth types, config).
|
||||
**Next step**: Review alknet-core spec documents, then begin implementation. Two-way-door questions (OQ-05, OQ-07, OQ-11, OQ-12) will be resolved during implementation.
|
||||
|
||||
## Architecture Documents
|
||||
|
||||
@@ -17,8 +17,13 @@ last_updated: 2026-06-16
|
||||
|----------|--------|-------------|
|
||||
| [overview.md](overview.md) | draft | Workspace-level overview, crate graph, shared types, design principles |
|
||||
| [open-questions.md](open-questions.md) | draft | Centralized OQ tracker with door-type classifications |
|
||||
| [crates/core/README.md](crates/core/README.md) | draft | alknet-core crate index |
|
||||
| [crates/core/core-types.md](crates/core/core-types.md) | draft | ProtocolHandler, HandlerError, Connection, BiStream, StreamError |
|
||||
| [crates/core/endpoint.md](crates/core/endpoint.md) | draft | ALPN router, HandlerRegistry, accept loop, shutdown |
|
||||
| [crates/core/auth.md](crates/core/auth.md) | draft | AuthContext, Identity, IdentityProvider, AuthToken, resolution flow |
|
||||
| [crates/core/config.md](crates/core/config.md) | draft | StaticConfig, DynamicConfig, ArcSwap, ConfigReloadHandle |
|
||||
|
||||
Crate-specific specs will be created when each crate is ready for Phase 1 architecture work, not in advance.
|
||||
Crate-specific specs for alknet-call, alknet-ssh, etc. will be created when each crate is ready for Phase 1 architecture work.
|
||||
|
||||
## ADR Table
|
||||
|
||||
@@ -33,6 +38,8 @@ Crate-specific specs will be created when each crate is ready for Phase 1 archit
|
||||
| [007](decisions/007-bistream-type-definition.md) | BiStream Type Definition | Accepted |
|
||||
| [008](decisions/008-secret-service-integration.md) | Vault Integration Point | Accepted |
|
||||
| [009](decisions/009-one-way-door-decision-framework.md) | One-Way Door Decision Framework | Accepted |
|
||||
| [010](decisions/010-alpn-router-and-endpoint.md) | ALPN Router and Endpoint | Proposed |
|
||||
| [011](decisions/011-authcontext-structure.md) | AuthContext Structure and Resolution Flow | Proposed |
|
||||
|
||||
## Open Questions
|
||||
|
||||
@@ -45,10 +52,15 @@ See [open-questions.md](open-questions.md) for the full tracker.
|
||||
- **OQ-06**: ALPN per connection, not per stream (ADR-006)
|
||||
- **OQ-08**: Vault integration — CLI-embedded via call protocol (ADR-008)
|
||||
|
||||
**Two-way doors (deferred to implementation):**
|
||||
- **OQ-04**: Dynamic handler registration — start static, add ArcSwap later
|
||||
**Resolved two-way doors:**
|
||||
- **OQ-04**: Dynamic handler registration — static at startup (ADR-010)
|
||||
- **OQ-12**: TLS certificate provisioning — file paths in StaticConfig, ACME later
|
||||
|
||||
**Two-way doors (resolved or deferred to implementation):**
|
||||
- **OQ-04**: Dynamic handler registration — resolved: static at startup (ADR-010)
|
||||
- **OQ-05**: Multi-transport endpoint — start with quinn, add transport trait later
|
||||
- **OQ-07**: Call protocol scope — start with one stream per operation
|
||||
- **OQ-11**: Handler-level auth resolution observability — decide during implementation
|
||||
|
||||
**Deferred (not active):**
|
||||
- **OQ-09**: WASM target boundaries — design constraint, not deliverable
|
||||
|
||||
Reference in New Issue
Block a user