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

1. 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**).
2. `GET info/refs`: emit advertisement (via transport stateless
   substrate); ACL checked before the smart prefix line.
3. `POST git-upload-pack`: build `StatelessRequest` (ADR-005) — the
   substrate handles capability-dump skipping, delim-aware parsing,
   flush-only responses, probe handling.
4. `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](decisions/002-front-door-blind-core.md) | Session boundary | stateless substrate per POST |
| [005](decisions/005-session-substrate-types.md) | Substrate types | http framing rules live in transport |
| [006](decisions/006-http-adapter-composition.md) | Router factory | **proposed** — OQ-01 open |
| [007](decisions/007-acl-before-advertisement.md) | ACL first | explicit wiring, not inherited |
| [008](decisions/008-registry-resolved-repo-identity.md) | Repo identity | path segment = registry ID |
| [009](decisions/009-bounded-resources-budget.md) | 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"