WsServer

A generic, schema-driven realtime WebSocket server in Elixir/Phoenix for Godot clients. The server is configured per game through a JSON manifest (schemas, channels, routing, persistence) rather than being reprogrammed; it speaks the Phoenix Channels protocol over wss and runs as a container. There is no GUI.

Documentation

• docs/USAGE.md — start here: install → start → configure → connect → use, end to end
• docs/MANIFEST.md — the manifest format (schemas/channels/ routing/persistence/auth)
• docs/PROTOCOL.md — the wss wire protocol the Godot client speaks (framing, routing, presence, state sync, rate limiting)
• docs/AUTHORING_ADDON.md — building the Godot editor addon that authors the manifest and configures the server
• docs/DEPLOYMENT.md — container deployment & environment variables
• docs/IMPLEMENTATION_KICKOFF.md — the full architecture & phase plan

Status

All phases of the kickoff plan are complete ✅

• Phase 0 — project & toolchain setup
• Phase 1 — foundation: HTTPS/wss from the start, Postgres, container & compose, .env config, health endpoint
• Phase 2 — config layer: JSON manifest loaded into ETS via the config registry, admin-secret–guarded push/reload API — see docs/MANIFEST.md
• Phase 3 — schema registry & validation: ex_json_schema payload validation against named schemas, x-secret field handling (Argon2 hashing / redaction, never echoed)
• Phase 4 — generic manifest-driven channel & routing (broadcast_all / broadcast_others / direct / filtered)
• Phase 5 — player auth: accounts (Argon2), Phoenix.Token, connect-time token verification, requires_auth enforcement
• Phase 6 — state & persistence: ETS hot-cache + throttled Postgres flush, join-time state sync, crash recovery
• Phase 7 — hardening & extension hooks: Phoenix.Presence, per-connection rate limiting, pluggable routing filter stage, binary-serializer seam

TLS / wss from the start

The server exposes an HTTPS-only listener (no plain HTTP) — Godot clients connect exclusively over wss and the health check is served over https too. Listener port and certificate paths are configurable via the HTTPS_PORT, TLS_CERT_PATH and TLS_KEY_PATH environment variables, so the self-signed dev certificate can be swapped for a real one in production without a rebuild.

Local development

Prerequisites: Elixir/OTP and a reachable PostgreSQL (e.g. the db service from compose.yaml, or a local container).

cp .env.example .env          # then edit secrets (SECRET_KEY_BASE, ADMIN_SECRET)
mix setup                     # deps, dev TLS cert (mix cert.setup), DB create/migrate
mix phx.server                # serves https/wss on https://localhost:4001
curl -k https://localhost:4001/health

mix setup generates a self-signed development certificate via mix cert.setup (a wrapper around mix phx.gen.cert). Certificates and .env are git-ignored.

Running with containers

cp .env.example .env          # set SECRET_KEY_BASE and ADMIN_SECRET
podman compose up --build     # or: docker compose up --build

The entrypoint provisions a self-signed certificate (if none is mounted), runs database migrations, then starts the release. See docs/DEPLOYMENT.md.

Tests & quality gates

A running PostgreSQL is required. Each phase must pass all gates:

mix format --check-formatted
mix credo --strict
mix test                      # includes wss end-to-end tests via slipstream
# or all at once:
mix precommit

End-to-end tests use slipstream to drive simulated Godot clients over real wss connections (WsServer.TestClient).