56 lines
5.9 KiB
Markdown
56 lines
5.9 KiB
Markdown
## Context
|
|
|
|
Platform stores a deployment definition on the server instance and serializes it into a leased lifecycle assignment. The currently checked-out independent Run implementation has no matching `deployment` member in its protocol, so Go silently discards the incoming JSON field. Existing Platform dispatch evidence proves only that Platform queued a snapshot.
|
|
|
|
Raw host directories and command text are normally protected. The operator has explicitly authorized local Run startup diagnostics containing those values, but the repository's channel rules still prohibit sending them through Platform, plugins, artifacts, job results, audits, or browser logs.
|
|
|
|
## Goals / Non-Goals
|
|
|
|
**Goals:**
|
|
|
|
- Execute the same typed, frozen deployment revision that Platform dispatches.
|
|
- Provide an authenticated, non-sensitive execution receipt that ties a Run result to the deployment revision.
|
|
- Load authorized saved execution values directly into the edit dialog and make clearing optional values explicit.
|
|
- Emit approved raw diagnostics only to Run's local process logger for a start operation.
|
|
|
|
**Non-Goals:**
|
|
|
|
- No host browsing, direct Platform-to-host access, plugin access to execution inputs, credential logging, or raw values in any remotely transmitted channel.
|
|
- No re-addition of Run source to this repository.
|
|
- No implicit conversion of arbitrary command strings into shell execution; selected shell policy remains enforced by Run.
|
|
|
|
## Decisions
|
|
|
|
1. **Use a typed deployment envelope shared by copied contracts, with a required protocol version and definition revision.** Platform sends the immutable definition already stored with the job; Run rejects unsupported versions or invalid action/mode combinations. This is preferred to a separate mutable lookup because it preserves the job's execution fence.
|
|
|
|
2. **Add a compact execution receipt to the terminal result.** It contains only protocol version, deployment revision, lifecycle action, deployment mode, configured/effective-working-directory state, shell kind, and outcome. Platform validates receipt equality with the leased snapshot before projecting `Run confirmed rN`. A hash of raw values is deliberately excluded because low-entropy commands and paths are susceptible to guessing.
|
|
|
|
3. **Keep raw diagnostics local and opt-in.** A new Run configuration flag enables startup diagnostics. When enabled, the Run process logger prints server root, effective working directory, selected shell, and the exact command immediately before launch. This writer is distinct from the process log sink and cannot be passed into Run's log batch uploader. Credentials, runtime bindings, install/stop/status commands, and environment values remain excluded.
|
|
|
|
4. **Use explicit update operations for protected optional fields.** The deployment update DTO gains a `clearFields` list, while omitted values preserve the saved field and supplied non-empty values replace it. Shell is represented as an optional value so omission preserves it and an explicit empty shell selects direct argv mode. This prevents a normal edit from silently resetting shell configuration.
|
|
|
|
5. **Auto-reveal only within the authorized editor route.** The editor calls the existing owner-scoped reveal endpoint when opened, stores values only in component state, signals that protected values are visible, and clears state on close. Ordinary deployment reads remain redacted.
|
|
|
|
6. **SCUM guided installation is a typed template, not a custom command.** The first-party SCUM template is the authority for SteamCMD App `3792580`, SCUM file/config markers, Microsoft Visual C++ prerequisites, DirectX runtime, and verification. Run receives the frozen template plus the protected root and game fields, creates a controlled SteamCMD argument vector including `+force_install_dir`, and never interprets an operator or plugin supplied shell snippet for the guided path. Microsoft prerequisite artifacts use official Microsoft endpoints and silent switches under a fixed Run catalog; an internal mirror is not selected unless it is explicitly checksum-equivalent to that catalog. Run checks runtime markers before each install and verifies the marker again afterward.
|
|
|
|
7. **Keep transport identifiers internal and present safe operation text.** `process.install` remains the Run capability because it is part of the leased job protocol. The Platform Web task card derives its title from the frozen plugin/action and deployment phase (for example, `安装 SCUM 服务端`), rather than rendering the protocol capability as user-facing copy.
|
|
|
|
## Risks / Trade-offs
|
|
|
|
- [Raw local diagnostics can be copied from the host console] → Diagnostics are opt-in, local-only, action-scoped, and clearly warn operators; no credentials or environment are included.
|
|
- [Mixed Platform/Run releases can lose execution confirmation] → Version/capability negotiation rejects deployment-aware jobs until the Run supports the protocol, rather than silently ignoring input.
|
|
- [An editor request can reveal operational values to an authorized browser] → It remains owner-authorized, uses no shared cache, and clears on dialog close.
|
|
- [Existing clients cannot express clearing] → The additive `clearFields` field preserves existing requests while enabling explicit removal.
|
|
- [A download mirror may be stale or tampered with] → Prefer the official Microsoft catalog and a fixed checksum/signature policy. Mirrors are acceleration only after equivalence verification; they are never the trust root.
|
|
|
|
## Migration Plan
|
|
|
|
1. Release Run support and advertise a new deployment-execution capability.
|
|
2. Release Platform support, requiring that capability before it dispatches a typed deployment job.
|
|
3. Enable local diagnostics only on Runs where the operator sets the explicit configuration flag.
|
|
4. Roll back by disabling the flag and stopping Platform dispatch to the new capability; saved deployment definitions remain intact.
|
|
|
|
## Open Questions
|
|
|
|
- None. The raw diagnostic allowance is constrained to the local Run process logger by the operator's instruction.
|