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.3 KiB

Raw Blame History

status, last_updated

status	last_updated
draft	2026-09-21

alkgit-http: HTTP Front Door

What it is

The smart-http adapter: git's http protocol served over alkhttp. Owns the smart-http endpoints, the http-framing composition (streaming both ways), and the ACL wiring that alkhttp's extra-routes surface does not provide by default. Shape partially pending OQ-01/ADR-006 (router factory vs alkhttp feature).

Routes (POC-3-validated shapes)

Route	Service	Notes
`GET /{repo}/info/refs?service=git-{upload,receive}-pack`	advertisement	smart prefix + capability dump + flush; `application/x-git-*-pack-advertisement`; no-cache
`GET /{repo}/info/refs?service=git-upload-archive`	—	not served — honest refusal (404/403 class), same rule as ssh (ADR-003)
`POST /{repo}/git-upload-pack`	V2 fetch commands	one command per POST
`POST /{repo}/git-receive-pack`	push	streaming ingestion, budgeted body (OQ-04)

{repo} is the registry ID (ADR-008) — path segment → registry lookup, never a path.
Reserved-path collision checks stay with alkhttp (HttpAdapter::with_extra_routes verifies; POC-3 confirmed passing).

Session flow (per request)

Extract repo ID from the path; resolve + authorize before any response bytes (ADR-007/008). Unknown == unauthorized (no existence oracle). Identity comes from the downstream auth model (OQ-08).
GET info/refs: emit advertisement (via transport stateless substrate); ACL checked before the smart prefix line.
POST git-upload-pack: build StatelessRequest (ADR-005) — the substrate handles capability-dump skipping, delim-aware parsing, flush-only responses, probe handling.
POST git-receive-pack: streaming body → transport receive-pack; body budgeted (ADR-009; alkhttp extra routes are unbounded by default — the budget is ours, POC-3 follow-up 3).

Streaming composition (POC-3-proven)

Request bodies: axum BodyDataStream → chunk-at-a-time reader → packetline parser; no accumulation (dribble-probe verified). The futures-io reader adapter lives in transport (ADR-005).
Responses: sideband/protocol output → bounded mpsc (8 slots) → Body::from_stream; back pressure parks the blocking-side generator; first chunk leaves in milliseconds; RSS flat under slow readers.
One sideband chunk = one HTTP chunk (65000-byte chunks carry over).

Composition seam (ADR-006 — proposed, OQ-01)

The crate exposes the adapter as a factory (shape per ADR-006): dependencies in (identity extractor, registry, transport hooks, limits), an axum Router out, ready for HttpAdapter::with_extra_routes. alkgitd is the first consumer; a downstream alkhttp deployment is the second. If adopted, this section becomes the seam spec.

HttpAdapter is not Clone (POC-3): assembly holds Arc<HttpAdapter> per accept task — the intended usage.

Auth

The gateway bearer layer does not cover extra routes' handlers unless registered before it (POC-3): ACL wiring here is explicit, not inherited.
Identity extraction mechanics (bearer/basic/…) are OQ-08; the factory seam takes it as a callback so downstream apps plug theirs in.
Anonymous fetch: per-repo opt-in; push always authenticated (ADR-007).

Design Decisions

ADR	Decision	Summary
002	Session boundary	stateless substrate per POST
005	Substrate types	http framing rules live in transport
006	Router factory	proposed — OQ-01 open
007	ACL first	explicit wiring, not inherited
008	Repo identity	path segment = registry ID
009	Budgets	request-body cap on POSTs

Open Questions

OQ-01: adapter home/composability (partially resolved — ADR-006 proposed).
OQ-08: identity sources (open — blocks the auth section).
OQ-04: receive-pack over http (deferred(unclear)).

References

docs/research/poc3-findings.md (route shapes, framing facts, streaming measurements — normative)
docs/research/alk-stack.md §"Interfaces in alkcall terms"

4.3 KiB Raw Blame History