browser/openspec/specs/platform-side-distribution-builds/spec.md

platform-side-distribution-builds Specification

Purpose

TBD - created by archiving change platform-side-docker-distribution-builds. Update Purpose after archive.

Requirements

Requirement: Server creation requires only plugin type and server name

The system SHALL require only the game plugin type and the server name to create a server instance, and SHALL NOT require a deployment target, run endpoint, or runtime profile at creation time.

Scenario: Creation form field set

• WHEN an owner opens the server creation workflow
• THEN the form requires plugin type and server name only, and presents no deployment target or run endpoint selector as a creation prerequisite

Scenario: Creation without any registered endpoint

• WHEN an owner creates a server instance while no run endpoint is registered for that instance
• THEN creation succeeds and the instance is created without a deployment target binding

Scenario: Binding established by run registration

• WHEN a generated run for that instance registers itself with the platform
• THEN the platform binds the instance to that run endpoint without the owner having pre-selected it

Scenario: Target selection remains available after creation

• WHEN an owner opens an already-created instance
• THEN deployment target and runtime profile selection remain available as optional actions on that instance

Requirement: Distribution builds execute in a platform-owned Docker builder

The platform SHALL execute distribution.build work in a platform-owned Docker builder and SHALL NOT dispatch distribution build jobs to machine-side run endpoints.

Scenario: Run distribution build execution

• WHEN an owner requests run generation for a server instance
• THEN the platform builds the package in its own Docker builder and records the resulting artifact against the build job

Scenario: Client-manager distribution build execution

• WHEN an owner requests client-manager generation for a server instance
• THEN the platform builds the package in its own Docker builder and records the resulting artifact against the build job

Scenario: Build failure reporting

• WHEN a platform Docker build fails
• THEN the distribution status becomes failed, the build job reports a failure, and the failure reason excludes host paths and secret values

Requirement: Build availability is independent of run endpoint capabilities

The system SHALL determine generate-run and generate-client-manager availability from plugin declarations, runtime bindings, and platform builder readiness, and SHALL NOT require any run endpoint to advertise distribution.build.

Scenario: Instance bound only to its own generated run

• WHEN a server instance's only run endpoint is its own generated run, which holds no distribution-build authority
• THEN generate-run remains available and a new run distribution can be generated

Scenario: No privileged worker endpoint registered

• WHEN no run endpoint advertising distribution.build is registered or online
• THEN run generation still succeeds through the platform Docker builder

Scenario: Builder unavailable

• WHEN the platform Docker builder is unavailable
• THEN the unavailable reason names the platform builder rather than a run endpoint capability

Requirement: Generated runs hold no distribution-build authority

The system SHALL continue to deny distribution-build work to component-authenticated generated runs. This restriction is a security boundary and SHALL NOT be relaxed to unblock building.

Scenario: Generated run claims a build

• WHEN a component-authenticated generated run claims work advertising distribution.build
• THEN the platform does not assign distribution build work to that run

Requirement: Platform builds do not expose plaintext component auth keys over the job channel

The system SHALL keep component auth keys inside the platform when builds are executed by the platform Docker builder, and SHALL NOT return plaintext auth keys to machine-side run endpoints for distribution builds.

Scenario: Build input secret handling

• WHEN the platform builder assembles a package requiring a component auth key
• THEN the key is resolved inside the platform and is not transmitted to any machine-side run endpoint

Scenario: Generated package still authenticates

• WHEN a package built by the platform builder registers with the platform
• THEN its embedded credential and key generation are accepted as before