glm-5.3-flash
82653c31b6
- new ADR-017: GitSession is a real typed client in v1 (ls_refs/fetch/ push), grounded in the two deployment use cases — the p2p replicator is the named downstream and needs the client protocol layer; the thin-wrapper reading is superseded - fetch client reuses gix-protocol (async-client) over a custom alkcall gix_transport::client::Transport impl (handshake writes the ADR-016 request line on the direct path; the channels open-op params carry it otherwise); push hand-rolled to ADR-013's shapes (gitoxide has no send-pack client) - storage-agnostic: packs stream both ways to caller-owned consumers; no in-session credentials (alkcall transport authenticates); client sessions carry ADR-009 Limits (client is also internet-facing) - manifest: gix-protocol/gix-transport gain async-client features (verified against published tree, MSRV 1.88) - amend ADR-010 (consumer-half bullet) and ADR-012 §4 (the deferred gix-protocol call — resolved; rider superseded); backend/transport/ overview/doors wording; review 001 A-5 marked resolved verification: cargo check (default, --all-features, --no-default-features, --features sha256), cargo +1.88 check, cargo test, clippy -D warnings, fmt --check — clean across the matrix
114 lines
6.0 KiB
Markdown
114 lines
6.0 KiB
Markdown
# ADR-010: Pure protocol crate — alkgit follows the alktty/alktunnels template
|
|
|
|
## Status
|
|
Accepted (supersedes ADR-001, ADR-006)
|
|
|
|
## Context
|
|
|
|
OQ-09 captured a structural correction to how alkgit was initially framed.
|
|
The monorepo + binary setup (`alkgit-core`/`alkgit-transport`/`alkgit-http`/
|
|
`alkgit-ssh`/`alkgitd`) came from the repo-initialization agent's rendering
|
|
of loosely-scoped use-case discussions — not a deliberate architecture
|
|
decision. It diverged from the established family pattern: the alk
|
|
protocol crates (alktty, alktunnels, alksocks in progress) are single
|
|
published crates implementing a service as a producer/consumer protocol on
|
|
top of alkcall channels, with doors (http, ssh, net) owned by separate
|
|
family crates that downstream consumers assemble.
|
|
|
|
The git service fits that pattern exactly:
|
|
|
|
- **Producer half** = POC-1's substrate verbatim: an adapter implementing
|
|
alkcall `ProtocolHandler` for the `alk/git` ALPN → `accept_bi()` →
|
|
duplex V2 session, plus a `register_openable` helper so a git session is
|
|
openable through the `alk/channels` multiplexer (alktty ADR-007/009
|
|
pattern: the channels open-op carries the negotiation — here, the
|
|
`{repo, service}` params (ADR-016), which is also the natural ACL
|
|
enforcement point).
|
|
- **Consumer half** = a typed `GitSession` client (alktty's `TtySession`
|
|
analog) driving fetch/push against a remote alkgit service — the
|
|
alkcall-native primitive for replication/mirroring in the alknet
|
|
rewrite.
|
|
- **Backend seam** = traits for registry, ref listing, pack generation,
|
|
and pack ingestion; the gix implementation ships behind a feature flag
|
|
(alktty's `local`-feature analog). Unlike alktunnels (no backend trait,
|
|
their ADR-004), git needs the storage seam — pack generation/ingestion
|
|
is too heavy to hard-wire — and unlike alktty, wasm-cleanliness is NOT a
|
|
goal: it falls out of the wire layer being gix-free, but nothing targets
|
|
wasm.
|
|
- **Smart-http** = the stateless substrate (ADR-005) stays in the protocol
|
|
crate; the http *mounting* (routes, content types,
|
|
`HttpAdapter::with_extra_routes` wiring) becomes an alkhttp `git`
|
|
feature — published after alkgit (see doors.md). POC-3 proved that
|
|
mapping is thin (its route layer was a thin wrapper over the stateless
|
|
substrate).
|
|
- **git-over-ssh** = alkssh's job when that crate exists (after alksocks).
|
|
The temporary russh-in-alkgitd decision (ssh.md) is dropped, not
|
|
shipped. The requirement alkgit places on alkssh is small and recorded
|
|
in doors.md.
|
|
|
|
Why now: nothing is implemented (the crates/ tree is an empty skeleton),
|
|
so the entire migration is documentation and manifest surgery. POC work
|
|
maps 1:1 onto the new shape, so no validation is lost.
|
|
|
|
## Decision
|
|
|
|
**alkgit is a single protocol crate** following the alktty/alktunnels
|
|
template:
|
|
|
|
- One crate, one repo (no cargo workspace, no sub-crates). Published to
|
|
crates.io as `alkgit`.
|
|
- **Producer half**: `GitAdapter` (direct `alk/git` ALPN via
|
|
`ProtocolHandler`) + channels `register_openable` (open-op params carry
|
|
`{repo, service}` — ADR-016's schema; the negotiation, the service
|
|
selector, and the ACL enforcement point; the service at open time is
|
|
what lets the gate run the correct `authorize` action per ADR-011/015).
|
|
- **Consumer half**: `GitSession` typed client with `connect_direct` and
|
|
`open_via_channels` constructors — both send the ADR-016 preamble
|
|
(request line / open-op params) including the service. Specified by
|
|
ADR-017: real typed client in v1 (`ls_refs`/`fetch`/`push`; fetch via
|
|
gitoxide's client machinery over a custom alkcall transport, push
|
|
hand-rolled to ADR-013's shapes, storage-agnostic).
|
|
- **Backend traits** (registry, refs, pack-gen, pack-ingest) in-crate;
|
|
`gix` implementation behind the default-on `gix` feature (disable it to
|
|
embed your own storage).
|
|
- **Substrate layer in-crate**: duplex session (ADR-002 boundary) +
|
|
stateless request/response substrate (ADR-005) — the stateless side is
|
|
IO-abstract (request-reader/response-writer), so alkhttp's feature maps
|
|
routes onto it without alkgit knowing http exists.
|
|
- **No binary. No front doors.** Assembly is downstream's job (the
|
|
platform deployment, or a future tiny assembly crate once alkssh/alknet
|
|
exist to assemble against).
|
|
- ALPN: `alk/git` (matches `alk/tty`, `alk/tunnel`, `alk/socks5`).
|
|
- Session tuple, security invariants (ADR-007/008/009), V2-first protocol
|
|
(ADR-003), pack pipeline (ADR-004), substrate types (ADR-005) all carry
|
|
over unchanged — they are pattern-independent.
|
|
|
|
## Consequences
|
|
|
|
- Positive: the embedder seam is *stronger* than ADR-001's shape (backend
|
|
traits let a downstream use its own storage instead of dragging gix
|
|
in); release surface shrinks to one crate; git becomes the first
|
|
payload service proven across three doors (alkhttp, alkssh, alknet)
|
|
with one protocol core; auth semantics collapse to "the door's auth"
|
|
(OQ-08 narrows sharply); POC-validated shapes are preserved verbatim.
|
|
- Negative: `vision.md`'s "single-binary git server" framing is amended —
|
|
the binary was never the user's intent (OQ-09 context); git-over-http
|
|
now ships on alkhttp's release cadence (feature lands in alkhttp 0.6
|
|
after `alkgit` is published); git-over-ssh waits for alkssh (no ssh
|
|
path in the interim unless a downstream adds its own wire-ssh
|
|
termination via the duplex session — that is a legitimate embedder
|
|
path, not alkgit scope).
|
|
- Neutral: crate granularity sub-decision resolved as "merge" (the
|
|
storage-only embedder concern is served by feature-gating, not
|
|
splitting: `default-features = false` gives the wire/protocol layer
|
|
without gix).
|
|
- ADR-001 (crate decomposition) and ADR-006 (http router factory) are
|
|
superseded; ssh.md/http.md/alkgitd.md are replaced by doors.md.
|
|
|
|
## References
|
|
- OQ-09 (the discussion this resolves), OQ-01 (subsumed), OQ-03 (narrowed)
|
|
- alktty docs/architecture (template), alktunnels docs/architecture (the
|
|
no-binary, feature-gated `local` precedent)
|
|
- POC-1/2/3 findings (the 1:1 mapping evidence)
|
|
- ADR-002 (unchanged, load-bearing), ADR-003/004/005/007/008/009
|
|
(carry over), doors.md, backend.md, overview.md |