first commit

2026-07-11 14:56:10 +08:00
commit 7e05d0a4e7
660 changed files with 78119 additions and 0 deletions
@@ -0,0 +1,66 @@
+# 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.