smcloud

Overview ¶

smcloud is the SM Cloud backup/restore service (ADR 0040 / docs/v2-design/sm-cloud-p1.md): a small HTTP API (internal/cloud/server) over a Postgres store (internal/cloud/store) that the daemon's smcloud forwarder pushes QSOs to and the restore command pulls from.

Configuration is flag + environment (a 12-factor service on a VPS under systemd, not a workstation app — no config.json):

-listen / SMCLOUD_LISTEN       listen address (default 127.0.0.1:8091 —
                               loopback; a LAN/proxy posture opts into a
                               wider bind explicitly)
-callsign / SMCLOUD_CALLSIGN   tenant 1's callsign (required)
-max-concurrent /
SMCLOUD_MAX_CONCURRENT         in-flight request cap (default 16, ~3× the
                               DB pool; over-limit → 503 + Retry-After;
                               the accept-time connection cap is 4× this)
SMCLOUD_DSN                    Postgres DSN (env ONLY — the DSN carries the
                               DB password, and argv is world-readable via
                               ps; required)
SMCLOUD_TOKEN                  tenant 1's bearer token (env ONLY, same
                               reason; required, ≥32 chars, placeholder
                               rejected)
SMCLOUD_CALLSIGN_N /
SMCLOUD_TOKEN_N                additional tenants, N in [2, 32] (milestone
                               1, ADR 0052 — hand-provisioned multi-
                               tenancy). Fail-loud: orphaned halves,
                               unparseable indices, duplicate tokens and
                               duplicate callsigns all refuse boot; see
                               collectTenantPairs.

Boot: open + ping Postgres, apply the embedded migrations (store.Migrate — same files + tracking table as `task migrate:cloud:up`), ensure every provisioned tenant, serve. TLS is the reverse proxy's job (S6 hosting); this listener is plain HTTP. Tenant isolation is structural in the store (uuid uniqueness is scoped per tenant, migration 0004); rotating one tenant's token is an env-file edit + restart, touching no other tenant's credentials.

Request limiting is two layers with distinct jobs (decided 2026-07-18): per-IP rate limiting lives at the reverse proxy, which sees real client IPs (deploy/smcloud/Caddyfile.example); THIS binary carries a two-level in-process bound so it stays safe even run without the proxy — an accept-time connection cap (netutil.LimitListener, 4× the request cap; net/http spawns a goroutine per accepted connection BEFORE any handler runs, so a handler-level limiter alone cannot bound a connection flood) plus the in-handler request semaphore (internal/cloud/server/limit.go). The DB pool protects Postgres; these protect the process. The remaining pre-Phase-2 gate is the ADR 0040 security assessment (docs/backlog.md, "smcloud hardening — pre-Phase-2 gate").