alkdev/alkgit

0 Fork 0

Files

T

glm-5.3-flash 8f73da5d12 docs(architecture): phase 1 bootstrap — specs, 9 ADRs, OQ tracker

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.

2026-09-21 03:55:33 +00:00

4.0 KiB

Raw Blame History

status, last_updated

status	last_updated
draft	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:

Builds the identity provider (per-door; OQ-08 decides mechanics).
Builds the registry (core trait + chosen backing; OQ-06 decides backing) and the storage roots from config.
Builds the transport hooks + Limits from config (ADR-009 defaults + overrides).
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).
ssh door: russh listener terminates SSH; alkgit-ssh dispatches the exec requests (ssh.md §client compatibility).
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	Crate decomposition	alkgitd = assembly only
006	Router factory	alkgitd consumes the factory like any embedder
008	Repo identity	storage roots configured server-side here
009	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)

4.0 KiB Raw Blame History