Files
aevolution/docs/networking/DEV_SESSION_OPERATIONS.md
T
dingoandClaude Opus 5.5 c588be237c Fix M9.4-M9.7 review findings in the dev session stack
- TLS: replace send() with a bounded queue/flush; an interrupted record is
  retried with identical arguments and later frames wait behind it, so no
  queued frame is lost or reordered; close() flushes first.
- Carriers: server-issued 'I','N' | 48-bit epoch | 64-bit ordinal ids
  replace the aliasing low-32-bit packing; client sequences are kept
  separately for replies; out-of-range epochs are refused, never truncated.
- Grants: a durable, fsynced, fail-closed consumed-grant ledger
  (--session-grant-ledger, /objects/dev-session-grants.v1 in dev) keeps
  single-use grants consumed across process and pod restarts.
- Liveness: protocol v1 (undeployed) gains Heartbeat and the timeout close
  reason; both sides heartbeat when idle and treat 5 s of silence as dead.
- Client sends are bounded and unresolved tracking starts at send time.
- ci-client configures with an explicit C compiler.

Each finding has a regression test; ADR-0083, the schema, operations doc
and VALIDATION record the corrections.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-02 05:44:44 -04:00

3.4 KiB

Dev session operations (M9.7)

Decision: ADR-0083; protocol: DEV_SESSION_PROTOCOL. evolution-dev only. Stage and World0 have no session Secret, and evo-server refuses any environment but dev.

1. Build the tools

cmake -P tools/prepare-mbedtls.cmake
cmake --preset network && cmake --build --preset network   # evo-dev-session
# Desktop client with remote mode (also needs SDL prepared):
cmake --preset client-network && cmake --build --preset client-network

The server image (deploy/docker/Dockerfile, server-runtime) is built with EVO_BUILD_NETWORK=ON; a new image digest must be pinned in the dev overlay as usual (ADR-0071) before the session flags exist in the cluster.

2. Create credentials on the operator machine (once)

evo-dev-session credentials --environment dev \
  --server-name dev-region.evolution.test --out ~/aevolution-dev-session

Writes dev-ca.pem (public; give to dev clients), server.pem (public), server.key and grant.key (secrets, owner-only, never overwritten). Keep the directory private. Never commit these files; the policy check rejects Secrets in Git.

3. Provision the Secret (cluster administrator, out of band)

kubectl -n evolution-dev create secret generic evolution-dev-session \
  --from-file=server.pem=$HOME/aevolution-dev-session/server.pem \
  --from-file=server.key=$HOME/aevolution-dev-session/server.key \
  --from-file=grant.key=$HOME/aevolution-dev-session/grant.key

The Deployment mounts it optionally (0440). Consumed grants are recorded in /objects/dev-session-grants.v1 on the region's persistent volume (fsynced before each Welcome), so a restarted pod refuses grants its predecessor used. Corrupt or unwritable ledgers fail closed (error session-grant-ledger, or sessions refused).

Rotation: create new credentials, replace the Secret, restart evo-region and redistribute dev-ca.pem. Old grants stop verifying with the new key.

4. Session drill (enables sessions temporarily, then restores Git values)

EVO_DEV_SESSION=./build/network/evo-dev-session \
  tools/ops/session-drill.sh ~/aevolution-dev-session [--context <name>]

Expected: probe durable ... before and after the forced pod deletion, a second probe welcome with a higher epoch, PASS session drill. Record the output in engineering/VALIDATION.md. Exit 1 on any missing observation; Git values are restored on every exit path.

5. Interactive engineering session

While a drill-style override is active (REGION_INPUTS=development-v1, REGION_SESSION=dev; revert afterwards: kubectl -n evolution-dev set env deployment/evo-region REGION_INPUTS= REGION_SESSION=):

evo-dev-session grants --environment dev --key ~/aevolution-dev-session/grant.key \
  --world 100 --frame 9 --region 1 --subject 7 --count 16 --out grants.bin
kubectl -n evolution-dev port-forward deploy/evo-region 17400:7400 &
evo-client --connect 127.0.0.1:17400 --server-name dev-region.evolution.test \
  --ca ~/aevolution-dev-session/dev-ca.pem --grants grants.bin

The listener binds the pod's loopback, so only port-forward reaches it; nothing is exposed through a Service, NodePort or Ingress. A grant bundle lasts at most one hour and each connection consumes one grant. WASD sends intentions; the small chip under the intention dot turns white (admitted), green (durable, no effect) or red/grey (rejected or outcome unknown). Console lines report every session event.