glm-5.3-flash
8f73da5d12
Architecture documentation structure per sdd_process phase 1: - README index (doc table, ADR table, lifecycle), overview with crate map, dependency rules, and security invariants - Component specs: storage, transport, http, ssh, alkgitd (all draft) - ADRs 001-009: crate decomposition, front-door-blind core, V2-first protocol, pack pipeline (data::output generation / data::input ingestion), session substrate types, http adapter composition (proposed, OQ-01), ACL-before-advertisement, registry-resolved repo identity, bounded-resources budgets - open-questions.md: OQ-01..08 with two deferred(scope), one deferred(unclear), door-type definitions, blocker tracker tasks in tasks/architecture/ - v1 ssh-door decision recorded: russh terminates wire SSH in alkgitd; alkcall channels stay the internal substrate (OQ-03 partially resolved) Two review rounds (fresh-context subagent): 4 critical + 17 warnings fixed in round one; zero critical + 4 warnings + 5 suggestions fixed in round two. All ADR/OQ cross-references verified resolving.
96 lines
4.0 KiB
Markdown
96 lines
4.0 KiB
Markdown
---
|
|
status: draft
|
|
last_updated: 2026-09-21
|
|
---
|
|
|
|
# alkgitd: Server Binary
|
|
|
|
## What it is
|
|
|
|
The assembly point: config parsing, listener setup (TLS/ACME), vault
|
|
wiring, the admin surface, and the glue that turns config into running
|
|
adapters. The only crate that knows the whole graph (ADR-001). No business
|
|
logic lives here.
|
|
|
|
## Assembly shape
|
|
|
|
For each listener (http and/or ssh), the binary:
|
|
|
|
1. Builds the identity provider (per-door; **OQ-08** decides mechanics).
|
|
2. Builds the registry (core trait + chosen backing; **OQ-06** decides
|
|
backing) and the storage roots from config.
|
|
3. Builds the transport hooks + `Limits` from config (ADR-009 defaults +
|
|
overrides).
|
|
4. http door: constructs the alkgit-http router factory (ADR-006) and
|
|
merges via `HttpAdapter::with_extra_routes`; wraps in alktls per
|
|
config; `Arc<HttpAdapter>` per accept task (POC-3 usage note).
|
|
5. ssh door: russh listener terminates SSH; alkgit-ssh dispatches the
|
|
exec requests (ssh.md §client compatibility).
|
|
6. Vault (alkvault) wired for any credential material; metadata/config
|
|
hold vault references only (convention 4/5).
|
|
|
|
## Config schema (v1 shape)
|
|
|
|
Server-facing values (registry backing location, storage roots, per-door
|
|
listeners/ports, TLS/ACME, limits overrides, vault path). The schema's
|
|
final shape depends on **OQ-06** (backing) and **OQ-08** (identity
|
|
config); the skeleton above is the stable frame.
|
|
|
|
Feature flags (convention 10): `sha256` (passthrough), `acme` (alktls
|
|
wiring). Base binary compiles lean; both feature sets verified in CI
|
|
(AGENTS.md verification commands).
|
|
|
|
## Admin API (scope: OQ-07)
|
|
|
|
- alkcall ops with `Visibility::Internal`, served over an admin-only
|
|
listener — never on the git traffic surface (alk-stack.md §gitea
|
|
lesson; vision threat-model notes).
|
|
- Candidate v1 op set (repo create/delete, visibility, ACL grant/revoke)
|
|
and its exact shapes: **OQ-07** — a dedicated session once the identity
|
|
model (OQ-08) exists, since op shapes depend on what identities mean.
|
|
- A downstream app may replace this surface entirely (vision
|
|
composability): the ops are alkcall ops, not embedded web endpoints.
|
|
|
|
## TLS/ACME
|
|
|
|
- alktls composition: `Connection::from_bidi(TlsStream, alpn)` — the
|
|
POC-1/3-validated alkcall entry shape. The http door rides TLS with
|
|
ALPN `http/1.1`/`h2`. The ssh door is a plain TCP listener
|
|
(stock `git clone ssh://` clients do not do TLS) — russh terminates SSH
|
|
directly on it (ssh.md); alkcall `Connection::from_stream` wraps the
|
|
post-auth stream when the adapter needs alkcall types.
|
|
- `acme` feature: alktls ACME state machine wired to config for the http
|
|
listener (alk-stack.md lists this as "likely trivial"; risk note: if the
|
|
wiring surprises, that becomes a research task before alkgitd
|
|
implementation — not silently absorbed).
|
|
|
|
## Serving loops
|
|
|
|
- Per-connection accept → `ProtocolHandler::handle` (alkcall ADR-002)
|
|
→ adapter dispatch → transport session.
|
|
- Server-wide blocking-pool budget for pack generation (ADR-009):
|
|
accepted/rejected at assembly time.
|
|
- Graceful shutdown: listener stop + session drain bounded by the
|
|
session wall clock (ADR-009).
|
|
|
|
## Design Decisions
|
|
|
|
| ADR | Decision | Summary |
|
|
|---|---|---|
|
|
| [001](decisions/001-crate-decomposition.md) | Crate decomposition | alkgitd = assembly only |
|
|
| [006](decisions/006-http-adapter-composition.md) | Router factory | alkgitd consumes the factory like any embedder |
|
|
| [008](decisions/008-registry-resolved-repo-identity.md) | Repo identity | storage roots configured server-side here |
|
|
| [009](decisions/009-bounded-resources-budget.md) | Budgets | limits overrides live in config |
|
|
|
|
## Open Questions
|
|
|
|
- **OQ-06**: registry backing (deferred(scope)).
|
|
- **OQ-07**: admin op set (open — after OQ-08).
|
|
- **OQ-08**: identity providers per door (open).
|
|
|
|
## References
|
|
|
|
- `docs/research/alk-stack.md` (integration surface, version pins)
|
|
- `docs/research/poc3-findings.md` (HttpAdapter usage, extra-routes behavior)
|
|
- alkcall ADRs: 002 (ProtocolHandler), 010 (capability injection), 017
|
|
(privilege model) |