59 lines
2.7 KiB
Markdown
59 lines
2.7 KiB
Markdown
## Context
|
|
|
|
Run has typed clients for control/job/log/artifact channels and local spool packages, but its executable behavior is still a smoke summary plus bounded lifecycle executor that immediately returns success metadata. Platform-side job leasing is already available, so the missing piece is a persistent run worker that consumes jobs safely.
|
|
|
|
## Goals / Non-Goals
|
|
|
|
**Goals:**
|
|
|
|
- Add hello/heartbeat and job polling loops.
|
|
- Execute install/start/stop lifecycle jobs using scoped process supervision.
|
|
- Emit progress and terminal results through the job channel.
|
|
- Connect stdout/stderr to log spool and lifecycle artifacts to artifact queue hooks.
|
|
- Enforce path, credential, command, and socket safety.
|
|
|
|
**Non-Goals:**
|
|
|
|
- No arbitrary plugin code execution or unbounded shell access.
|
|
- No game client bridge implementation.
|
|
- No cloud host provisioning or billing.
|
|
- No external artifact/log storage backend implementation.
|
|
|
|
## Decisions
|
|
|
|
### Decision 1: Worker owns channel scheduling
|
|
|
|
The run worker keeps control heartbeat high priority, job claim/result next, logs durable/batched, and artifacts lower priority. Long transfers must not block heartbeat or job result submission.
|
|
|
|
### Decision 2: Lifecycle actions use scoped command templates
|
|
|
|
Plugin lifecycle action references resolve to bounded command templates under a configured server workspace. Absolute paths, parent traversal, raw credentials, and socket exposure are rejected.
|
|
|
|
### Decision 3: Process supervisor is an abstraction
|
|
|
|
Process management sits behind a supervisor interface so tests can use fake processes and later game-specific process handling can be added without rewriting the worker loop.
|
|
|
|
### Decision 4: Smoke mode remains
|
|
|
|
Smoke mode stays available for local diagnostics. Worker mode is enabled through explicit config.
|
|
|
|
## Risks / Trade-offs
|
|
|
|
- [Risk] Real process orchestration can hang. Mitigation: bounded timeouts, cancellation, progress heartbeat, and supervisor tests.
|
|
- [Risk] Command templates can become unsafe. Mitigation: validation rejects shell metacharacter abuse, absolute paths, direct sockets, and secret env leaks.
|
|
- [Risk] Worker loops can starve logs/artifacts. Mitigation: separate scheduling and priority rules.
|
|
|
|
## Migration Plan
|
|
|
|
1. Add worker config and session state.
|
|
2. Implement control heartbeat and job loop.
|
|
3. Add process supervisor and lifecycle executor.
|
|
4. Wire logs/artifacts to existing queues.
|
|
5. Update command entrypoint and docs.
|
|
6. Add unit and integration-style tests.
|
|
|
|
## Open Questions
|
|
|
|
- Whether future plugin action runtimes should interpret JSON action schemas directly or compile them into lifecycle command templates.
|
|
- Whether server process state should be persisted in a journal file or a small local database.
|