51 lines
2.3 KiB
Markdown
51 lines
2.3 KiB
Markdown
## Context
|
|
|
|
The registered `input.sequenced.v1` flow has a payload bound but no typed
|
|
payload grammar. RC5 also has no provider-to-client envelope for host
|
|
termination, rumble, or HDR feedback. The Data Plane must translate these
|
|
states to the provider without exposing Apollo packet formats or credentials.
|
|
|
|
## Goals / Non-Goals
|
|
|
|
**Goals:**
|
|
|
|
- Define fixed, bounded, endian-explicit gateway payloads for keyboard, mouse,
|
|
UTF-8 text, and controller state.
|
|
- Define a reliable control envelope for provider feedback and termination.
|
|
- Define an explicit release operation for every pressed key/button/controller.
|
|
- Keep provider packet encodings and endpoint details internal to the Data Plane.
|
|
|
|
**Non-Goals:**
|
|
|
|
- Touch, pen, motion, file transfer, binary clipboard, or provider-specific
|
|
packets.
|
|
- Changing RC5, moving an existing tag, or making the Connection Server parse
|
|
streaming input.
|
|
|
|
## Decisions
|
|
|
|
- Define a new binary payload grammar beneath the existing registered flows.
|
|
This avoids changing the authenticated tunnel header while removing the
|
|
untyped `device`/opaque-payload ambiguity. JSON was rejected because input is
|
|
latency-sensitive and fixed binary bounds are simpler to validate before
|
|
allocation.
|
|
- Input events use explicit event kinds and fixed payload lengths except UTF-8
|
|
text, which is limited to one valid Unicode scalar value. This permits exact
|
|
provider translation and deterministic cleanup.
|
|
- Provider feedback and termination use the existing bidirectional reliable
|
|
control channel with a distinct magic, direction, type, and length. A new
|
|
channel was rejected because the existing channel is already authenticated,
|
|
reliable, and versioned.
|
|
- Protocol contents and fixtures are finalized before a new immutable release
|
|
candidate is created. RC5 remains an unchanged dependency for current
|
|
consumers until they explicitly adopt the new revision.
|
|
|
|
## Risks / Trade-offs
|
|
|
|
- [New client adoption is required] -> retain RC5 unchanged and publish an
|
|
explicit capability/version mismatch before any provider allocation.
|
|
- [Provider feedback can be high rate] -> allow only termination, rumble, and
|
|
HDR payload types with fixed maximum sizes; other types reject.
|
|
- [Pressed-state loss during disconnect] -> gateway records accepted presses
|
|
and emits typed releases during cleanup before provider disconnect.
|