2.3 KiB
2.3 KiB
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.