67 lines
3.1 KiB
Markdown
67 lines
3.1 KiB
Markdown
# run
|
|
|
|
Machine-side executor for scoped server operations.
|
|
|
|
## Responsibilities
|
|
|
|
- Register with platform and report heartbeat, version, capabilities, and capacity.
|
|
- Claim and execute jobs for server lifecycle, file/config work, backups, updates, and bounded database or command work.
|
|
- Collect server logs into local spool and upload acknowledged batches.
|
|
- Transfer artifacts with chunking, checksums, resume, throttling, and low priority.
|
|
- Optionally coordinate with a game client bridge when a specific game requires in-game commands or snapshots.
|
|
|
|
## Required Directory Plan
|
|
|
|
Implementation should use dedicated directories for:
|
|
|
|
- `api/`: platform-facing HTTP/gRPC client adapters.
|
|
- `protocol/`: control, job, log, artifact, and game-client bridge DTOs.
|
|
- `domain/`: executor domain types.
|
|
- `runtime/`: local execution and server process orchestration.
|
|
- `spool/`: local durable log/job/artifact queues.
|
|
- `artifact/`: chunk transfer implementation.
|
|
- `logingest/`: log collectors and uploaders.
|
|
- `config/`: configuration structures and loading.
|
|
- `shared/`: small shared helpers.
|
|
|
|
Logs and artifacts must have separate queues and priority controls.
|
|
|
|
## Development Baseline
|
|
|
|
Tooling:
|
|
|
|
- Go 1.25.1.
|
|
- Module: `browser.local/run`.
|
|
|
|
Commands:
|
|
|
|
```bash
|
|
go test ./...
|
|
go run ./cmd/run
|
|
```
|
|
|
|
Runtime configuration:
|
|
|
|
- `RUN_MODE`: local mode, default `smoke`.
|
|
- `RUN_PLATFORM_URL`: platform base URL, default `http://127.0.0.1:8080`.
|
|
- `RUN_ENDPOINT_ID`, `RUN_DISPLAY_NAME`, `RUN_VERSION`, `RUN_REGISTRATION_TOKEN`: worker identity and registration metadata.
|
|
- `RUN_WORKSPACE_ROOT`, `RUN_SPOOL_ROOT`: scoped local server workspace and separate local log/artifact queues.
|
|
- `RUN_MAX_JOBS`, `RUN_HEARTBEAT_INTERVAL_MS`, `RUN_POLL_INTERVAL_MS`, `RUN_RETRY_BACKOFF_MS`: worker capacity and scheduling controls.
|
|
|
|
For local direct debugging, copy `run/.env.example` to `run/.env`, edit the values, and run:
|
|
|
|
```bash
|
|
set -a
|
|
source .env
|
|
set +a
|
|
go run ./cmd/run
|
|
```
|
|
|
|
Use `RUN_MODE=worker` when you want the executor to register, heartbeat, claim jobs, and execute lifecycle templates. Use `RUN_MODE=smoke` for a one-shot config summary.
|
|
|
|
In Docker, `RUN_PLATFORM_URL` must be `http://platform:8080` because `platform` is the compose service name. Locally, keep it as `http://127.0.0.1:8080`.
|
|
|
|
Current executable behavior includes smoke mode plus worker mode. Worker mode registers with platform, sends lightweight heartbeat metadata, claims lifecycle jobs, acknowledges leases, reports bounded progress, executes scoped `process.install`, `process.start`, and `process.stop` command templates inside per-server workspaces, polls cancellation, submits terminal results, and reconciles active jobs.
|
|
|
|
Lifecycle templates are JSON files addressed by logical keys under the server workspace. They resolve to direct executable/argument vectors, not shell strings. Absolute paths, parent traversal, raw credentials, direct sockets, shell launchers, unsafe environment keys, and unsafe output are rejected or redacted. Process stdout/stderr is written to the log spool, and lifecycle result metadata is queued through artifact hooks so control heartbeat and job result submission stay independent from log and artifact work.
|