15 KiB
15 KiB
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