120 lines
6.6 KiB
Markdown
120 lines
6.6 KiB
Markdown
## ADDED Requirements
|
|
|
|
### Requirement: Component sessions authenticate bridge access
|
|
|
|
The Platform SHALL require every Game Client Bridge request from a companion client to use a valid component session issued through the Client Manager registration flow.
|
|
|
|
#### Scenario: Valid component session uses bridge capability
|
|
|
|
- **WHEN** a deployed companion client registers with the current component key generation, deployment generation, and `game-client.bridge` capability
|
|
- **THEN** the Platform accepts bridge requests for the bound server instance, plugin, profile key, artifact, and session expiry window
|
|
|
|
#### Scenario: Stale component session is rejected
|
|
|
|
- **WHEN** a companion client uses a session from a revoked key generation, expired session, old deployment generation, or undeclared bridge capability
|
|
- **THEN** the Platform rejects the bridge request without returning raw key material or internal secret locations
|
|
|
|
### Requirement: Commands are durable and fenced
|
|
|
|
The Platform SHALL persist Game Client Bridge commands with lifecycle state, idempotency key, expiry, priority, declared command type, payload reference or inline bounded payload, target server instance, plugin, requester, approval state, claim lease, fencing token, and audit metadata.
|
|
|
|
#### Scenario: Operator queues declared bridge command
|
|
|
|
- **WHEN** an authorized operator queues a command declared by the active plugin bridge catalog
|
|
- **THEN** the Platform stores the command as pending, records an audit event, and exposes only safe command status to plugin pages
|
|
|
|
#### Scenario: Duplicate idempotency key is reused
|
|
|
|
- **WHEN** the same requester submits the same command type with the same idempotency key for the same server instance
|
|
- **THEN** the Platform returns the existing command instead of creating a duplicate command
|
|
|
|
#### Scenario: Expired command is not claimed
|
|
|
|
- **WHEN** a pending command has passed its expiry time before a companion client claims it
|
|
- **THEN** the Platform marks the command expired and prevents later claim or execution
|
|
|
|
### Requirement: Companion clients claim and complete commands
|
|
|
|
The Platform SHALL let authenticated companion clients claim pending bridge commands in bounded batches and complete them only with the active claim lease and fencing token.
|
|
|
|
#### Scenario: Client claims pending command batch
|
|
|
|
- **WHEN** an online companion client polls for bridge commands for its bound server instance and profile key
|
|
- **THEN** the Platform returns only eligible pending commands, marks them claimed, assigns leases, and includes fencing tokens
|
|
|
|
#### Scenario: Stale claim cannot complete command
|
|
|
|
- **WHEN** a companion client submits an ack or result with an expired lease, stale fencing token, or mismatched component session
|
|
- **THEN** the Platform rejects the update and leaves the current command state protected from stale completion
|
|
|
|
#### Scenario: Command result is recorded
|
|
|
|
- **WHEN** the active claimant completes a command with a success or failure result
|
|
- **THEN** the Platform stores sanitized result metadata, updates command status, records completion time, and emits an audit event
|
|
|
|
### Requirement: Operators can cancel pending or claimed commands
|
|
|
|
The Platform SHALL allow authorized operators to cancel bridge commands that are not already terminal and SHALL prevent cancelled commands from being executed or completed as successful.
|
|
|
|
#### Scenario: Pending command is cancelled
|
|
|
|
- **WHEN** an authorized operator cancels a pending command
|
|
- **THEN** the Platform marks the command cancelled and excludes it from future claim batches
|
|
|
|
#### Scenario: Claimed command is cancelled before completion
|
|
|
|
- **WHEN** an authorized operator cancels a claimed command
|
|
- **THEN** the Platform records the cancellation and rejects later success results from the old claim
|
|
|
|
### Requirement: Snapshots are versioned and typed
|
|
|
|
The Platform SHALL ingest Game Client Bridge snapshots only when their type, schema version, sequence, source component, payload shape, and retention policy match active plugin declarations.
|
|
|
|
#### Scenario: Client uploads declared snapshot
|
|
|
|
- **WHEN** a companion client uploads a snapshot that matches a declared snapshot type and schema version
|
|
- **THEN** the Platform stores it with server instance, plugin, profile key, source session, sequence, observed time, and retention metadata
|
|
|
|
#### Scenario: Snapshot sequence is stale
|
|
|
|
- **WHEN** a companion client uploads a snapshot with a sequence older than or equal to the latest accepted sequence for the same stream
|
|
- **THEN** the Platform rejects or quarantines the stale snapshot according to validation policy and does not replace the current projection
|
|
|
|
#### Scenario: Plugin page queries snapshots
|
|
|
|
- **WHEN** an authorized plugin page requests snapshots for an owned server instance
|
|
- **THEN** the Platform returns bounded safe projections without raw component secrets, host paths, direct sockets, or unbounded raw dumps
|
|
|
|
### Requirement: Bridge traffic is isolated from Run channels
|
|
|
|
The Platform SHALL keep Game Client Bridge command and snapshot traffic separate from Run control heartbeat, job acknowledgement, log ingest, and artifact transfer channels.
|
|
|
|
#### Scenario: Large snapshot ingestion does not block control
|
|
|
|
- **WHEN** a companion client uploads a large but allowed snapshot payload
|
|
- **THEN** Run control heartbeat, job acknowledgement, and log upload remain independently serviceable through their own channels
|
|
|
|
#### Scenario: Bridge unavailable does not disable server lifecycle
|
|
|
|
- **WHEN** the Game Client Bridge service is unavailable or no companion client is online
|
|
- **THEN** existing Run lifecycle actions, log ingest, artifact transfer, and Client Manager lifecycle projections continue to operate
|
|
|
|
### Requirement: Browser-visible bridge DTOs are safe projections
|
|
|
|
The Platform SHALL expose only safe bridge declarations, command statuses, results, snapshots, availability reasons, and audit references to plugin pages.
|
|
|
|
#### Scenario: Plugin page loads bridge state
|
|
|
|
- **WHEN** a plugin page loads bridge state for a server instance
|
|
- **THEN** the response excludes raw credentials, component keys, sessions, DSNs, host paths, direct Run endpoints, sockets, and storage provider credentials
|
|
|
|
### Requirement: Bridge records are retained and audited
|
|
|
|
The Platform SHALL apply bounded retention to bridge commands, results, snapshots, and audit references while preserving enough metadata for operator review and troubleshooting.
|
|
|
|
#### Scenario: Retention job expires old bridge records
|
|
|
|
- **WHEN** bridge records exceed configured retention limits
|
|
- **THEN** the Platform expires or compacts old records without exposing deleted payloads through plugin page APIs
|
|
|