feat(backend): HTTP daemon skeleton (Phase 1a) — #10

[neversettle17-101]

Phase 1a — HTTP server skeleton

First sub-PR of the Go HTTP Daemon lane (#10). Stands up the loopback-only sidecar skeleton; REST routes (1b), Electron integration (1c), SSE, WS and static serving land in later phases on top of this.

Lane model: per the issue, the lane is meant to integrate on feat/go-http-daemon and land on main as one unit. That integration branch doesn't exist yet, so this PR targets main; happy to retarget if the lane branch is created.

What's in 1a

• internal/config — env-driven config (AO_PORT, AO_REQUEST_TIMEOUT, AO_SHUTDOWN_TIMEOUT, AO_RUN_FILE) with zero-config defaults. Host is hardcoded to 127.0.0.1 (deliberately no AO_HOST: this daemon has no auth/CORS/TLS, so a stray AO_HOST=0.0.0.0 would turn it into a public no-auth service). AO_PORT is range-validated; timeouts must be > 0 (rejecting zero/negative durations that would silently break the daemon).
• internal/httpd — chi router with the recoverer → request-id → requestLogger → real-ip middleware stack and /healthz + /readyz probes. The access log is a small slog-backed middleware so REST traffic lands on the same stderr stream and key=value shape as the rest of the daemon. The per-request timeout is carried in config but deliberately not applied globally — it scopes to /api/v1 in Phase 1b so it never throttles the long-lived SSE/WS surfaces or the always-answer health probes (per the decision table).
• internal/runfile — atomic PID + port handshake (running.json) for the Electron supervisor, with a dead-PID stale check: a crashed predecessor's file is treated as stale and overwritten, while a live daemon makes startup fail fast. Cross-platform atomic replace via build-tagged atomicReplace (POSIX rename(2) / Windows MoveFileEx with MOVEFILE_REPLACE_EXISTING); cross-platform PID liveness via build-tagged processAlive (POSIX signal 0 / Windows OpenProcess with PROCESS_QUERY_LIMITED_INFORMATION).
• internal/httpd/server.go — bind-before-publish (port conflict fails fast), graceful shutdown on SIGINT/SIGTERM via signal.NotifyContext with a 10s hard timeout, and run-file cleanup on exit.

Decisions honoured

chi framework · single loopback port 3001 · fail-fast on conflict · PID check on startup · signal.NotifyContext + 10s hard shutdown · middleware order recoverer→request-id→requestLogger→real-ip→(timeout, /api/v1-scoped later) · OS-agnostic (macOS / Linux / Windows) via build tags.

Out of scope (later phases)

Route registration (1b), embed.FS static + Electron spawn/supervise + dev proxy (1c), EventBus/SSE (2), /mux WS (4).

Verification

Static checks + unit tests + end-to-end smoke run, all on 5bca1a2 + 24f57fd:

Check	Result
gofmt -l .	clean
go build ./...	clean
go vet ./...	clean
go test -race ./...	all 7 packages pass (config, httpd, runfile, lifecycle, session, domain, decide)
GET /healthz on the built binary	200 {"status":"ok"}
GET /readyz on the built binary	200 {"status":"ready"}
running.json handshake	written with correct pid / port / startedAt; removed on shutdown
Access log on stderr	structured slog with request id, method, path, status, bytes, duration, remote — confirms the slog-routed requestLogger (no chi stdout writes)
Fail-fast on duplicate start (live daemon)	daemon already running (pid X, port Y); refusing to start → exit 1
Graceful shutdown on SIGTERM	shutdown signal received, draining connections → daemon stopped cleanly; running.json removed

New tests added in this PR cover: config defaults / overrides / validation (including zero/negative timeout rejection), run-file round-trip + overwrite-existing + live/dead PID detection, health probes, the full Run lifecycle (boot → running.json published → serve → SIGTERM → clean shutdown → run-file removed), and port-conflict fail-fast.

Tracking: #10

[neversettle17-101]

Done in 61c5b8a — dropped Env, AO_ENV, and IsProduction(); collapsed the logger to a single path. Tests still green.

[Copilot]

Pull request overview

Introduces the Phase 1a Go HTTP daemon skeleton for the backend, establishing a loopback-bound server lifecycle with health probes, env-driven configuration, and an Electron-oriented running.json handshake file.

Changes:

• Added internal/httpd server/router skeleton with /healthz and /readyz, plus graceful shutdown wiring.
• Added internal/config for env-based configuration with defaults and validation.
• Added internal/runfile for atomic-ish running.json write/read/remove and stale/live PID checks, with accompanying tests and README run instructions.

Reviewed changes

Copilot reviewed 11 out of 12 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
README.md	Documents how to run the new Go daemon, probe health, and configure via env vars.
backend/main.go	Boots config + logger, checks run-file staleness, and runs the HTTP server with SIGINT/SIGTERM shutdown.
backend/internal/config/config.go	Implements env-driven config defaults and parsing/validation for port and timeouts.
backend/internal/config/config_test.go	Adds tests for config defaults, overrides, and invalid inputs.
backend/internal/httpd/router.go	Creates the chi router and mounts health/readiness probes with the chosen middleware ordering.
backend/internal/httpd/json.go	Adds a small helper for writing JSON responses consistently.
backend/internal/httpd/server.go	Implements bind-before-publish, serving loop, graceful shutdown, and run-file cleanup.
backend/internal/httpd/server_test.go	Adds tests for probes, full server lifecycle, and port-conflict fail-fast behavior.
backend/internal/runfile/runfile.go	Implements running.json handshake file write/read/remove and stale/live detection.
backend/internal/runfile/runfile_test.go	Adds run-file round-trip and stale/live PID detection tests.
backend/go.mod	Adds chi dependency for the new HTTP daemon skeleton.
backend/go.sum	Records module checksums for the new dependency.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.