alkdev/alkgit

0 Fork 0

Files

T

glm-5.3-flash 82653c31b6 docs(architecture): ADR-017 — consumer half, GitSession as typed client (review 001 A-5)

- 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

2026-09-29 09:24:47 +00:00

6.0 KiB

Raw Blame History

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

6.0 KiB Raw Blame History