2.9 KiB
2.9 KiB
The Pipelines server — working map
Read this before touching internal/server/, internal/stage/, internal/pipeline/ or
internal/protocol/. The generic half — how a Go service is built, tested and reviewed — belongs to
the pipeline that started you.
Build and test
go build ./... && go vet ./...
go test ./internal/server # ~10-15 s
go test ./internal/stage ./internal/pipeline ./internal/protocol
go test ./... # ~1 min for everything; `gofmt -l .` must print nothing
Where things are
internal/server/websocket.go— the/connecttransport and the request dispatch. Envelope validation lives here; every command returns its own typed reply.internal/server/runner.go— run execution: the stage loop, stage outcomes, budgets, retries, ownership and settlement. This is where a run's state changes.internal/server/runevents.go— the push hub: subscriptions scoped per workspace, per-run frames, coalescing. Live clients fold these instead of polling.internal/server/chat_*.go— the chat broker:chat_sessions, claims, the stream, permissions, session registry.internal/stage/— one client per harness and stage type:opencode.go(native sessions),pi.go(RPC),model.go,agent.go,human.go(decision stages),ntfy.go(notifications),result_repair.go(the strict-envelope repair ladder),budget.go(usage accounting).internal/pipeline/— the store: definitions and immutable versions, runs and steps, the operator-session registry, retention, search.internal/protocol/— every wire shape. A new command means a message field here, documentation indocs/cli.md, and tests both sides.cmd/pipelines-server/main.go— flags and wiring, including which OpenCode endpoint chat brokers from (-opencode-endpoint,PIPELINES_OPENCODE_ENDPOINT, or the recorded choice).
Checking behaviour without disturbing the live server
scripts/run-local-server.sh starts a scratch server, and the binary takes -addr and -db, so a
live check runs against a scratch database and a free loopback port. The operator's deployment is
~/.local/share/pipelines with the service on 0.0.0.0:8080 and ntfy on 8090.
Hard rules
- Never restart, rebuild or redeploy the deployed server, ntfy or a running run to test a change: a restart kills every run in flight. Deploying is the operator's step.
- Commit locally only, never push.
- One run per workspace at a time — the server refuses a second one rather than sharing a tree.
- The service is durable: sessions, runs and definitions live in SQLite, so a migration must open an
existing database cleanly (see the
migrateRun*/addColumnIfMissingpattern). - Artifacts are inventoried with bounds (
internal/server/artifacts.go: file count, per-file and total size); a large file is served by direct URL, not by growing the inventory.