docs(architecture): ADR-016 — native session preamble (review 001 A-3)
- new ADR-016: channels open-op params pinned as {repo, service}
(channels/git/sub, additionalProperties: false); direct-ALPN GitAdapter
parses the git-daemon request line (POC-1-verbatim grammar, capture-
backed); session tuple gains the service dimension on both substrates;
GitSession mirrors the shapes; version deliberately stays out of the
preamble (service fully determines the state machine)
- amend ADR-002/005/010 (tuple, substrate inputs, open-op params pin) and
transport.md/doors.md/overview.md/backend.md accordingly
- add the ADR-016 wire shapes to OQ-03's freeze inventory; note in
AGENTS.md convention 9 that the alkgit-specific framing now exists and
is pinned
- review 001: A-3 marked resolved
verification: cargo test, clippy -D warnings, fmt --check, doc — clean
This commit is contained in:
1 parent
201c7a1fce
commit
41b0894740
12 files changed
+294
-52
No files matched your search
@@ -22,16 +22,25 @@ full decision (what each substrate owns and why); the surface is:
|
||||
|
||||
- **Duplex session** (the `alk/git` ALPN producer, channels-opened git
|
||||
sessions, embedder stream doors) — input: (peer identity, resolved repo
|
||||
id, authorized-repo marker, duplex stream, `Limits`). The marker is a
|
||||
type the door/adapter constructs only after the ADR-007 check passes
|
||||
(skipping the check is a type error — ADR-007; D-3). Encapsulates the
|
||||
split/compat/packetline
|
||||
bridge, the request reader (delim-aware parsing, `reset()` discipline,
|
||||
break-on-error), and the sideband writer.
|
||||
id, service, authorized-repo marker, duplex stream, `Limits`). The
|
||||
marker is a type the door/adapter constructs only after the ADR-007
|
||||
check passes (skipping the check is a type error — ADR-007; D-3). The
|
||||
service is selected at establishment on every native path (ADR-016:
|
||||
the channels open-op params `{repo, service}`, or the in-band
|
||||
git-daemon request line the direct-ALPN `GitAdapter` parses,
|
||||
POC-1-verbatim), and selects the state machine: the V2 capability
|
||||
advertisement for fetch, the V0 ref advertisement for push — both are
|
||||
server-emitted firsts, so the service must precede the stream.
|
||||
Encapsulates the split/compat/packetline bridge, the request reader
|
||||
(delim-aware parsing, `reset()` discipline, break-on-error), and the
|
||||
sideband writer.
|
||||
- **Stateless session** (smart-http doors, e.g. alkhttp's future `git`
|
||||
feature) — input: (peer identity, resolved repo id, authorized-repo
|
||||
marker, request-reader, response-writer, `Limits`) per http POST; adds
|
||||
the http-framing rules
|
||||
feature) — input: (peer identity, resolved repo id, service,
|
||||
authorized-repo marker, request-reader, response-writer, `Limits`) per
|
||||
http POST. The door's route still selects the service (doors.md), but
|
||||
the substrate input carries it explicitly — nothing in a POST body
|
||||
distinguishes an upload-pack POST from a receive-pack POST before
|
||||
parsing (ADR-016). Adds the http-framing rules
|
||||
(capability-dump skip, flush-only responses, probe handling). IO-abstract:
|
||||
the door supplies reader/writer; see [doors.md](doors.md) for the
|
||||
mounting.
|
||||
@@ -145,7 +154,8 @@ a partial ref list is the worst failure mode an advertisement can have
|
||||
|
||||
Crate-root re-exports (alktty pattern; the full list in
|
||||
[backend.md](backend.md) §public API): `GitAdapter` + `register_openable`,
|
||||
`GitSession`, substrate types, `Limits`, the backend traits (ADR-010's
|
||||
`GitSession`, substrate types (including the service selector and the
|
||||
authorized-repo marker), `Limits`, the backend traits (ADR-010's
|
||||
seam), protocol error enums; gix-feature types under the feature.
|
||||
Publish-freeze point: **OQ-03**.
|
||||
|
||||
@@ -161,11 +171,13 @@ Publish-freeze point: **OQ-03**.
|
||||
| [010](decisions/010-pure-protocol-crate.md) | Pure protocol crate | wire layer is backend-trait-only |
|
||||
| [013](decisions/013-receive-pack-state-machine.md) | receive-pack | V0-framed push machine, thin-pack acceptance, unpack-first CAS |
|
||||
| [014](decisions/014-v2-negotiation-ack-loop.md) | Negotiation | ack loop, no `ready`, wait-for-done stays |
|
||||
| [016](decisions/016-native-session-preamble.md) | Native session preamble | `{repo, service}` open-op params, request-line preamble, service in the tuple |
|
||||
|
||||
## Open Questions
|
||||
|
||||
- **OQ-03**: publish/API freeze (partially resolved — single-crate shape
|
||||
settled by ADR-010).
|
||||
settled by ADR-010; the native-path preamble shapes entered the freeze
|
||||
inventory via ADR-016).
|
||||
- **OQ-05**: sha256 policy (deferred(scope)).
|
||||
- OQ-02 resolved (ADR-014 — ack loop design).
|
||||
- OQ-04 resolved (ADR-013 — receive-pack state machine).
|
||||
@@ -176,7 +188,7 @@ Publish-freeze point: **OQ-03**.
|
||||
`docs/research/poc3-findings.md` (the normative wire behavior —
|
||||
observed against real git, not docs' grammar)
|
||||
- `docs/research/push-captures.md` (the push-path normative record —
|
||||
ADR-013's basis)
|
||||
ADR-013's basis; the git:// request-line framing ADR-016 adopts)
|
||||
- `docs/research/negotiation-captures.md` (the negotiation normative
|
||||
record — ADR-014's basis)
|
||||
- `docs/research/git-protocol.md` (inventory + observed corrections)
|
||||
|
||||
Reference in new issue
Block a user