154 lines
15 KiB
Markdown
154 lines
15 KiB
Markdown
## ADDED Requirements
|
|
|
|
### Requirement: Plugins declare bounded client-manager lifecycle contracts
|
|
Game plugins SHALL declare client-manager version/revision metadata, supported targets, deployment mode, required Run and component capabilities, relative executable contract, bounded lifecycle actions, health contract, compatibility constraints, and update policy before Platform enables lifecycle operations.
|
|
|
|
#### Scenario: Valid lifecycle profile is installed
|
|
- **WHEN** a plugin declares a client-manager profile with a supported target, pinned or policy-approved revision, fixed build adapter, safe relative executable, bounded start/stop/restart and health settings, and known capability names
|
|
- **THEN** plugin and Platform validation MUST preserve the declaration and Platform MUST derive lifecycle availability from the installed declaration, runtime binding, server ownership, and assigned endpoint capabilities
|
|
|
|
#### Scenario: Unsafe lifecycle profile is submitted
|
|
- **WHEN** a plugin declaration contains arbitrary shell, an absolute or traversing path, raw credentials, secret or token values, direct sockets, host endpoints, environment secrets, unknown capabilities, or an unbounded health/control action
|
|
- **THEN** plugin and Platform validation MUST reject it before registration or lifecycle dispatch
|
|
|
|
### Requirement: Platform gates every lifecycle action against current ownership and capability state
|
|
Platform SHALL authorize client-manager build, deploy, register, control, update, rollback, revoke, retry, and uninstall independently using the current actor, server visibility, installed plugin declaration, runtime binding, assigned Run endpoint, artifact ownership, target, revision, component key generation, and lifecycle state.
|
|
|
|
#### Scenario: Authorized owner deploys an available build
|
|
- **WHEN** a server owner or authorized administrator selects an available current-generation distribution for the same server, profile, target, and approved revision while the assigned Run endpoint is online and declares client-manager deployment capability
|
|
- **THEN** Platform MUST create or reuse one typed deployment intent and job and MUST expose its real state and progress
|
|
|
|
#### Scenario: Mismatched lifecycle input is requested
|
|
- **WHEN** an actor supplies another owner's server, another server or component artifact, another Run endpoint, a mismatched target or revision, an expired or revoked distribution, or a stale component-key generation
|
|
- **THEN** Platform MUST deny the operation before job creation, MUST record a redacted denial audit, and MUST NOT reveal whether an inaccessible resource exists
|
|
|
|
#### Scenario: Service or component credential calls an operator endpoint
|
|
- **WHEN** a Run service credential or Client Manager component session calls an operator lifecycle endpoint without the required operator role
|
|
- **THEN** Platform MUST return an authorization failure and MUST NOT broaden that credential into an operator session
|
|
|
|
### Requirement: Platform persists and reconciles a real lifecycle state machine
|
|
Platform SHALL durably persist desired state, active and previous deployment references, component-key and deployment generations, job linkage, health summary, failure detail, and lifecycle timestamps for each server/profile installation.
|
|
|
|
#### Scenario: Lifecycle advances through real evidence
|
|
- **WHEN** build, deployment, registration, control, update, rollback, or uninstall work changes phase
|
|
- **THEN** Platform MUST transition only through valid requested, building, available, deploying, installed, registering, online, degraded, offline, updating, rolling_back, stopping, uninstalled, or failed states using durable job results, Run reports, or authenticated component heartbeats rather than local UI timers
|
|
|
|
#### Scenario: Platform restarts with in-flight work
|
|
- **WHEN** Platform restarts while a lifecycle job or component session is in progress
|
|
- **THEN** reconciliation MUST restore the persisted intent, project the durable job/session state idempotently, reject stale attempts, and either resume, retry, roll back, or fail safely without creating a duplicate activation
|
|
|
|
#### Scenario: Duplicate lifecycle request is retried
|
|
- **WHEN** the same actor repeats a request with the same idempotency key and immutable inputs
|
|
- **THEN** Platform MUST return the original installation/job result, while the same idempotency key with different immutable inputs MUST be rejected
|
|
|
|
### Requirement: Run deploys client managers through a checksummed controlled workspace
|
|
Run SHALL execute client-manager deployment only through the typed job contract and SHALL download, resume, verify, stage, and atomically activate an authorized distribution inside its configured client-manager workspace.
|
|
|
|
#### Scenario: Deployment completes after an interrupted transfer
|
|
- **WHEN** a current leased deployment downloads an available artifact in chunks and the transfer is interrupted
|
|
- **THEN** Run MUST persist offset and checksum state, resume without re-downloading acknowledged bytes, verify the final checksum and safe package layout, activate the staged slot, and report installed only after real activation succeeds
|
|
|
|
#### Scenario: Deployment payload or package is unsafe
|
|
- **WHEN** a deployment contains arbitrary commands, raw host paths, sockets, credentials, a stale attempt/deployment/key generation, a mismatched artifact/target/component, a checksum failure, traversal, symlink, device file, or unexpected executable layout
|
|
- **THEN** Run MUST reject or fail the job without changing the active slot and MUST return only bounded redacted diagnostics
|
|
|
|
#### Scenario: Deployment is cancelled or retried
|
|
- **WHEN** cancellation arrives between chunks or activation phases, a lease expires, or a retry uses the same idempotency and deployment generation
|
|
- **THEN** Run MUST honor the current fence, retain only safe resumable staging state, never let a stale attempt replace a newer activation, and converge on one recorded outcome
|
|
|
|
### Requirement: Client Manager authenticates as an independent component
|
|
Client Manager SHALL register with Platform using its own current component key and generation and SHALL receive a short-lived component session that is separate from Run control registration, job leases, credentials, and channels.
|
|
|
|
#### Scenario: Installed component registers successfully
|
|
- **WHEN** a deployed Client Manager signs a canonical registration request with a fresh timestamp and nonce and reports the active installation, artifact, version/revision, deployment generation, and declared capabilities
|
|
- **THEN** Platform MUST verify the same server/profile ownership, current component-key generation, active deployment, target/revision, signature, nonce, and capabilities, persist only a hash of a new expiring component session, return the token only to the component, and move the installation toward online health
|
|
|
|
#### Scenario: Registration signature is stale, replayed, revoked, or mismatched
|
|
- **WHEN** registration uses an expired timestamp, repeated nonce, revoked or previous-generation key, another server/component identity, inactive artifact, stale deployment generation, or undeclared capabilities
|
|
- **THEN** Platform MUST reject registration, record a safe denial audit, and MUST NOT create or reveal a component session
|
|
|
|
#### Scenario: Run identity is presented as Client Manager identity
|
|
- **WHEN** a caller presents a Run key, Run bearer session, Run job lease, or Run endpoint identity to the Client Manager registration or heartbeat contract
|
|
- **THEN** Platform MUST reject it and MUST NOT reuse Run authentication state
|
|
|
|
### Requirement: Component heartbeats drive safe health projection
|
|
Platform SHALL accept bounded heartbeat and capability reports only from a valid component session and SHALL project logical health and last-seen state without exposing local process details.
|
|
|
|
#### Scenario: Healthy component heartbeat arrives
|
|
- **WHEN** an unexpired, unrevoked session bound to the active installation reports a monotonic heartbeat with declared capabilities and a safe health code
|
|
- **THEN** Platform MUST update last seen and logical health idempotently and MUST expose only version, status, health code/reason, capabilities, and timestamps to authorized operators
|
|
|
|
#### Scenario: Heartbeat expires
|
|
- **WHEN** a component misses its declared heartbeat grace and offline thresholds
|
|
- **THEN** reconciliation MUST transition the installation from online to degraded and then offline using safe reasons while preserving the last successful deployment and audit history
|
|
|
|
#### Scenario: Session heartbeat is replayed or fenced
|
|
- **WHEN** a heartbeat sequence repeats, the session is expired/revoked, or its key, deployment, endpoint ownership, or artifact fence is no longer current
|
|
- **THEN** Platform MUST reject it without mutating health and require a new valid registration
|
|
|
|
### Requirement: Run performs bounded client-manager process control
|
|
Run SHALL start, stop, restart, and inspect a deployed Client Manager only through the plugin-declared executable and health contract and the typed lifecycle job.
|
|
|
|
#### Scenario: Operator starts or restarts a deployed component
|
|
- **WHEN** Platform dispatches an authorized current-generation control job whose action is declared by the profile
|
|
- **THEN** Run MUST supervise the fixed relative executable from the active slot, use bounded timeouts, persist the logical process state, and report progress and outcome without returning a PID, host path, environment secret, or socket
|
|
|
|
#### Scenario: Unsupported or stale control is requested
|
|
- **WHEN** a control action is undeclared, the installation is uninstalled, the attempt or deployment generation is stale, or another process already owns the active fence
|
|
- **THEN** Run MUST reject the operation idempotently without executing a command or disrupting the newer process
|
|
|
|
### Requirement: Updates are staged, health-checked, and rollback-safe
|
|
Platform and Run SHALL treat a Client Manager update as a same-installation transaction with explicit approval, compatible current-generation artifact selection, staged activation, bounded health confirmation, and a retained previous deployment.
|
|
|
|
#### Scenario: Compatible update becomes healthy
|
|
- **WHEN** an authorized operator approves a newer compatible artifact for the same server/profile/target and Run verifies, stages, activates, starts, and observes required health
|
|
- **THEN** Platform MUST set the new artifact/version as active, retain the prior deployment as rollback candidate, revoke the superseded component session, require new registration, and record real update progress and audit evidence
|
|
|
|
#### Scenario: Candidate update fails health
|
|
- **WHEN** download, checksum, activation, startup, registration, or health confirmation fails after an update begins
|
|
- **THEN** Run MUST preserve or restore the previous slot, Platform MUST project rolling_back and the real rollback result, and success MUST NOT be reported unless the restored deployment is active and healthy
|
|
|
|
#### Scenario: Invalid update or rollback is requested
|
|
- **WHEN** an artifact is revoked, from another server/profile/target, has a stale key generation, violates compatibility/version policy, or the previous slot no longer exists
|
|
- **THEN** Platform and Run MUST reject the request before activation and preserve the current deployment
|
|
|
|
### Requirement: Revocation and uninstall are safe and idempotent
|
|
Platform SHALL support session revocation and Run SHALL stop and uninstall a Client Manager without deleting server or shared files, while retaining Platform lifecycle and audit history.
|
|
|
|
#### Scenario: Key or session is revoked
|
|
- **WHEN** an authorized operator resets the component key, explicitly revokes the component session, reassigns ownership/endpoint, activates an update/rollback, or begins uninstall
|
|
- **THEN** Platform MUST revoke matching sessions, reject subsequent heartbeats, fence old artifacts/deployments as applicable, and show that rebuild/redeploy or registration is required
|
|
|
|
#### Scenario: Installed component is uninstalled
|
|
- **WHEN** an authorized operator confirms uninstall and Run completes the typed job
|
|
- **THEN** Run MUST stop the supervised process, remove only controlled active/previous/staging slots and local session/journal material for that installation, Platform MUST mark it uninstalled, and build/distribution/audit history MUST remain available
|
|
|
|
#### Scenario: Uninstall is repeated or interrupted
|
|
- **WHEN** uninstall is retried after partial cleanup, cancellation, lease expiry, or an already-uninstalled result
|
|
- **THEN** Run and Platform MUST converge idempotently without following links, escaping the configured workspace, or deleting game server/shared data
|
|
|
|
### Requirement: Lifecycle operations are durably audited and redacted
|
|
Platform SHALL record durable success, failure, and denial audits for build, deploy, register, start, stop, restart, update, rollback, revoke, retry, and uninstall using safe identifiers and bounded reasons.
|
|
|
|
#### Scenario: Lifecycle result is audited
|
|
- **WHEN** an operator, Run endpoint, or Client Manager performs or is denied a sensitive lifecycle action
|
|
- **THEN** the audit MUST include actor type and safe actor ID, server/profile/component, installation, job or artifact ID where applicable, operation, result, and redacted reason without raw keys, tokens, secret refs/values, credentials, paths, PIDs, sockets, endpoint addresses, DSNs, RCON passwords, or large output
|
|
|
|
### Requirement: Client Manager traffic remains isolated from Run channels
|
|
Client-manager registration, heartbeat, deployment transfer, process control, and optional game-client traffic SHALL remain separated from Run control heartbeat, job acknowledgement/result/cancel, log ingest, and artifact upload scheduling.
|
|
|
|
#### Scenario: Client-manager artifact transfer stalls
|
|
- **WHEN** a large or stalled client-manager download or component traffic stream is active
|
|
- **THEN** Run heartbeat, job ack/result/cancel polling, log spool upload, and unrelated artifact progress MUST continue independently within their bounded queues
|
|
|
|
### Requirement: Platform web provides a complete safe Client Manager workspace
|
|
platform_web SHALL provide authorized operators a Client Manager management workspace that reflects real backend state and preserves the existing black-mecha and magical-girl crystal-moonlight game-operations visual system.
|
|
|
|
#### Scenario: Operator manages the complete lifecycle
|
|
- **WHEN** an authorized operator opens Server Detail for a declared Client Manager
|
|
- **THEN** the UI MUST show safe profile/target/version/revision, build and artifact state, deployment/registration/online health, last seen, active/previous deployment, current job progress, permitted start/stop/restart, update/rollback, retry/redeploy after key reset, session revoke, and confirmed uninstall actions using real API projections
|
|
|
|
#### Scenario: Action is unavailable or destructive
|
|
- **WHEN** an action lacks permission, declaration, binding, online endpoint, capability, compatible artifact, current key generation, allowed lifecycle state, or confirmation
|
|
- **THEN** the UI MUST disable or hide it with a safe reason, require explicit confirmation for key reset/revoke/rollback/uninstall, preserve 401/403 handling, and MUST NOT fabricate progress or expose raw secrets, sessions, paths, PIDs, sockets, credentials, or endpoint addresses
|