docs(data-plane): archive gateway contract

2026-07-29 07:00:02 +07:00
parent 50ba2d6bf3
commit 61a17ff42b
4 changed files with 0 additions and 0 deletions
@@ -0,0 +1,24 @@
+## Decisions
+
+- Use quic-go v0.61.0 with TLS 1.3, DATAGRAM enabled, bounded stream windows, bounded
+  datagram sizes, and no migration fallback in the application contract.
+- Authenticate a client hello over a reliable stream, consume authority exactly once through
+  an injected admission client, then open lifecycle/control/input streams and media/audio
+  datagrams.
+- Keep management/readiness/lifecycle, channel translation, and encoded relay separate.
+- Use a deterministic fake Apollo provider behind the same adapter interface as the future
+  network client. Fixtures are non-live evidence and carry no host/credential material.
+- On authority loss, close admission, release every pressed input, stop queues, and report
+  cleanup pending if provider termination is not acknowledged.
+
+## Bounds
+
+JSON hello/control is limited to 64 KiB, datagrams to 65,536 bytes with a configurable
+path-MTU payload cap, fragments to 16, queues to fixed capacities, clipboard text to 65,536
+bytes and rate-limited, and each session owns only bounded goroutines/timers.
+
+## Failure behavior
+
+TLS/authentication, identity/protection, version, audience, grant, capability, parser,
+provider, and cleanup failures close the relevant session with stable codes. Media payloads
+are copied only for framing and are asserted byte-identical in tests.
@@ -0,0 +1,23 @@
+## Why
+
+The Data Plane is an empty gateway boundary. Phase 3C-G needs a pure-Go QUIC process that
+admits only Connection Server authority, adapts one Apollo/GameStream provider profile, and
+relays encoded bytes without exposing the provider or decoding media.
+
+## What Changes
+
+- Add bounded QUIC/TLS streams and DATAGRAM framing with authenticated admission.
+- Add a native-Go Apollo profile, deterministic fixtures, a bounded fake provider, lifecycle
+  cleanup, input release, capability intersection, pacing, telemetry, and packaging.
+
+## Provenance
+
+Provider behavior is independently implemented from the exact Apollo pin
+`adc5c5a0bd80831ce495434bb16aee2cd4175fb8` and the Planning Hub's recorded public
+Moonlight/common-C protocol evidence. Only the used source paths are recorded; no source
+tree or proprietary capture is copied.
+
+## Non-goals
+
+No cgo, native sidecar, decoder/encoder/transcoder/render path, direct provider route,
+database credential, provider plugin framework, or live Apollo qualification.
@@ -0,0 +1,46 @@
+## ADDED Requirements
+
+### Requirement: Authenticated bounded gateway transport
+The gateway SHALL require TLS 1.3 client authentication and a valid versioned grant hello
+before allocating provider state. Reliable lifecycle/control/critical-input messages SHALL
+use streams; encoded media/audio and approved sequenced input SHALL use bounded DATAGRAMs.
+
+#### Scenario: Grant replay or wrong audience
+- **WHEN** a client presents a consumed, expired, revoked, or audience-mismatched grant
+- **THEN** the gateway rejects before provider allocation and emits no provider route or
+  credential to the client.
+
+### Requirement: No-transcode encoded relay
+The gateway SHALL relay provider encoded payload bytes through a codec-neutral Verse envelope
+without decode, encode, transcode, render, or codec conversion.
+
+#### Scenario: Payload relay
+- **WHEN** the fake Apollo provider emits an encoded video or audio payload
+- **THEN** the corresponding Verse payload is byte-identical except for the approved transport
+  framing and the gateway records no decoder/encoder operation.
+
+### Requirement: Provider identity and protection
+The Apollo profile SHALL reject changed, malformed, expired, or not-yet-valid pinned identity
+and SHALL never silently retry with weaker protection.
+
+#### Scenario: Identity change
+- **WHEN** the provider identity differs from the enrolled fingerprint or unique ID
+- **THEN** launch fails closed and the session remains unavailable for new media.
+
+### Requirement: Bounded lifecycle and input safety
+Authority loss, tunnel close, drain, provider disconnect, and explicit termination SHALL be
+distinct states; every pressed key/button/controller SHALL be released before session cleanup.
+
+#### Scenario: Authority expiry during input
+- **WHEN** authority expires while input is pressed
+- **THEN** new input is rejected, release-all is sent to the provider, queues stop, and
+  cleanup is reported as pending until termination is acknowledged.
+
+### Requirement: Deterministic fake-provider qualification
+The complete management, launch/readiness, channel, feedback/input, termination, and cleanup
+sequence SHALL pass against a bounded fake provider plus malformed and timeout fixtures.
+
+#### Scenario: Fake provider timeout
+- **WHEN** readiness or termination times out
+- **THEN** the adapter returns a bounded stable error and marks cleanup pending without
+  spawning unbounded retries or goroutines.
@@ -0,0 +1,5 @@
+- [x] Add strict QUIC/TLS transport, reliable stream framing, and bounded datagram parser.
+- [x] Add capability intersection, queues/pacing, input release, telemetry, and lifecycle.
+- [x] Add deterministic Apollo fixtures, provenance, bounded fake provider, and adapter.
+- [x] Add process-level mTLS/QUIC integration, fuzz/race/resource/impairment/scheduler tests.
+- [x] Add gateway command/package smoke checks and archive after candidate evidence matches.