Aetherin Server Core
Go runtime core for the Aetherin server, built on a microkernel architecture reused from Gatherin. The kernel stays small and stdlib-only; every product feature arrives as a plugin against pkg/pluginsdk.
Purpose
- Kernel: transport, plugin lifecycle, storage, events, config, secrets.
- Ring-0 plugins: kernel-facing plugins (transport, registry, eventbus,
storage, config, secrets).
- Ring-1 plugins: product features (auth, ratelimit, metering, router,
provider-registry) — currently scaffolds with TODO markers.
REST handlers land in Wave 2.
How to run
Fastest loop — run the core on the host (no Docker, needs a local Go toolchain):
make dev-apiStarts the core with APP_ENV=development on :3000.
Development (Docker + hot reload)
Full dev stack (core + postgres + redis) with live reload:
make dev-stack # docker compose -f docker-compose.dev.yml up -d
make dev-logs # follow the core logs (shows each rebuild/restart)
make down # stop the stackThe core service builds from Dockerfile.dev, which keeps the Go toolchain and installs `air`. The repository is bind-mounted at /app and air watches it using `.air.toml` (.air.toml): **save a *.go file and the server rebuilds and restarts on its own** — no docker compose build required. Module/build caches live in named volumes so rebuilds stay fast, and air's artifacts land in ./tmp (gitignored, safe to delete).
Dev ports: core :3000, postgres :5432, redis :6379; :2345 is left free for a delve debugger. The service definition and env var names match aetherin-deploy/docker-compose.dev.yml. Copy .env.development.example to .env.development to override defaults.
The web console lives in a separate repository; run its dev server with make dev-web (bun on :5173, proxying /api and /v1 to :3000).
Quality gates:
make fmt
make vet
make testPerformance and load harness:
make bench # hot-path micro-benchmarks (sanitize + normalize)
make load-smoke # 10s k6 sanity check against a running core
make load-test # k6 ramping arrival-rate to the 100 RPS targetSee `load/README.md` for prerequisites, the mock upstream, and how to read the metrics.
Architecture
internal/kernel/*— trusted core (config, events, httpserver, plugin
registry/host, secrets, storage). Stdlib only.
pkg/pluginsdk— public, semver-stable plugin contract.plugins/ring0/*— kernel plugins.plugins/ring1/*— product feature plugins (scaffolds).
Plugins never import each other; communication is via the event bus.
Env lanes
APP_ENV selects development, staging, or production. Each lane loads .env.<lane> if present, then process env. Strict mode (non-dev) requires explicit capability grants via GATEWAY_GRANT_<PLUGIN_ID>.
Required vars: APP_ENV, PORT, LOG_LEVEL, GATEWAY_SECRET_KEY (or SECRETS_ROOT_KEY), SQL_DSN, REDIS_CONN_STRING. See .env.development.example. Optional: INVITE_BASE_URL, SMTP_HOST/SMTP_PORT/SMTP_USER/ SMTP_PASSWORD/SMTP_FROM for invitation delivery (see example file).