5.9 KiB
ADDED Requirements
Requirement: Run updates use approved target-matched distributions
Platform SHALL dispatch self-update only for an available Run distribution owned by the same server, built for the registered endpoint OS/architecture, and matching the recorded artifact checksum.
Scenario: Authorized update is queued
- WHEN an authorized owner or platform administrator selects an available same-server distribution for the online endpoint
- THEN Platform MUST bind the update record and job to the distribution, artifact, checksum, target, endpoint, and idempotency key and record a queued audit event
Scenario: Artifact is cross-owner or cross-target
- WHEN the artifact belongs to another server/job, is not an available Run distribution, has a different checksum, or targets another OS/architecture
- THEN Platform MUST reject the update before job creation without revealing artifact contents or private ownership metadata
Requirement: Update artifact reads are resumable and fenced
Run SHALL download update artifacts through a signed active-attempt-only chunk contract with bounded offsets, lengths, total size, and checksum metadata.
Scenario: Download resumes after interruption
- WHEN Run restarts or a chunk request fails after a durable offset was recorded
- THEN Run MUST request the next bounded range, verify every returned offset/length and the final checksum, and MUST NOT redownload already verified bytes
Scenario: Stale attempt requests a chunk
- WHEN a cancelled, expired, wrong-endpoint, wrong-session, wrong-lease, or superseded attempt requests update metadata or bytes
- THEN Platform MUST reject it and MUST NOT return artifact bytes, storage paths, browser tokens, secret refs, or fencing hashes
Requirement: Run stages updates safely
Run SHALL safely validate and stage exactly the expected Run executable from the approved distribution while preserving the installed package configuration.
Scenario: Valid package is staged
- WHEN all artifact bytes and the archive checksum are verified
- THEN Run MUST reject archive traversal/links/devices/duplicates, enforce entry and binary size limits, extract the target-matched executable into an owner-only transaction directory, verify its checksum, fsync the journal, and leave the current executable/configuration unchanged
Scenario: Package verification fails
- WHEN checksum, target, format, entry bounds, executable identity, or extraction validation fails
- THEN Run MUST keep the current executable, remove or quarantine invalid partial data, report a bounded failure, and remain able to heartbeat and accept cancellation
Requirement: Activation occurs only after fenced result acceptance
Run SHALL activate a staged update only after Platform accepts the terminal staged result for the current attempt and the local result acknowledgement is durable.
Scenario: Staging result is rejected
- WHEN Platform rejects the result because the session, attempt, lease, cancellation state, or terminal fingerprint is stale
- THEN Run MUST NOT launch the update helper or replace the executable
Scenario: Staging result is accepted
- WHEN Platform accepts the current staged result
- THEN Run MUST persist the post-ack activation request, launch the staged helper, stop the old worker without dropping the accepted result, and project the update as restart-requested/activating until health is confirmed
Requirement: Activation is health-checked and rollback-safe
The update helper SHALL back up, replace, launch, confirm, and finalize an update transaction, and SHALL restore the previous executable if activation fails.
Scenario: New Run becomes healthy
- WHEN the new executable starts, authenticates, registers the same endpoint/server identity, reconciles jobs, and writes the transaction health marker before timeout
- THEN it MUST submit a signed current-session health report fenced to the terminal update job/attempt/lease, the helper MUST mark the transaction succeeded, retain bounded rollback evidence, and Platform MUST confirm the endpoint's new release/checksum in the safe update projection only after accepting that report
Scenario: Replacement or health confirmation fails
- WHEN copy/rename/start fails, the new process exits, identity differs, or health is not confirmed before timeout
- THEN the helper MUST atomically restore the backup where possible, restart the previous executable, mark rolled-back/failed recovery state, and never claim update success
Scenario: Run restarts with an interrupted transaction
- WHEN startup finds a durable downloading, staged, activating, or rollback transaction
- THEN it MUST resume the safe phase, clean invalid state, or roll back deterministically without applying a different artifact or stale attempt
Requirement: Update status and audit projections are safe
Platform_web and plugins SHALL receive only bounded update identity, artifact checksum, target, phase, progress, timestamps, rollback outcome, endpoint version/release, and safe audit summaries.
Scenario: Update status is queried
- WHEN an authorized user opens server runtime status
- THEN the response MUST omit host/executable/staging/backup paths, raw artifact bodies, credentials, Run tokens, session/lease values or hashes, secret refs, helper PIDs, sockets, and private package configuration
Requirement: Update transfer and activation preserve channel deadlines
Slow update downloads and helper preparation SHALL NOT block control heartbeat, job acknowledgement/result, cancellation polling, logs, or unrelated artifact uploads.
Scenario: Update download is slow
- WHEN update chunk transfer is delayed or the artifact is large
- THEN heartbeat, active job lease renewal, cancellation polling, log upload, and unrelated result reporting MUST continue through separate bounded loops