Skip to content

Commit 8e8de03

Browse files
author
DavidQ
committed
define docker runtime for authoritative server hosting — PLAN_PR_LEVEL_12_5_SERVER_HOSTING_DOCKER_RUNTIME
1 parent 8549a2c commit 8e8de03

7 files changed

Lines changed: 163 additions & 10 deletions

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
MODEL: GPT-5.3-codex
2-
REASONING: low
2+
REASONING: high
33
COMMAND:
4-
Finalize APPLY_PR_LEVEL_12_4_PLAYABLE_MULTIPLAYER_VALIDATION.
5-
Update docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md markers only.
6-
Do not modify wording or structure.
4+
Prepare implementation-ready Docker runtime plan for authoritative server.
5+
Keep scope minimal (single-node).
6+
Update roadmap markers only.

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
apply playable multiplayer validation and verify — APPLY_PR_LEVEL_12_4_PLAYABLE_MULTIPLAYER_VALIDATION
1+
define docker runtime for authoritative server hosting — PLAN_PR_LEVEL_12_5_SERVER_HOSTING_DOCKER_RUNTIME

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
- apply complete
2-
- validation passed
3-
- replication verified
4-
- roadmap updated
1+
- docker runtime defined
2+
- startup lifecycle defined
3+
- connection path defined
4+
- roadmap rule enforced

‎docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -611,7 +611,7 @@
611611
- [x] authoritative live server runtime
612612
- [x] replication/client application
613613
- [x] playable real multiplayer validation
614-
- [ ] server hosting + Docker containerization
614+
- [.] server hosting + Docker containerization
615615
- [ ] promotion/readiness gate
616616
- [x] include samples for phase 13
617617

‎docs/pr/BUILD_PR_LEVEL_12_5_SERVER_HOSTING_DOCKER_RUNTIME.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# BUILD_PR_LEVEL_12_5_SERVER_HOSTING_DOCKER_RUNTIME
2+
3+
## Purpose
4+
Implement a minimal single-node Docker runtime for the authoritative multiplayer server path with repeatable startup/shutdown validation.
5+
6+
## Scope
7+
Primary target files:
8+
- `samples/phase-13/1316/server/authoritativeMultiplayerServer.mjs`
9+
- `samples/phase-13/1316/server/Dockerfile`
10+
- `samples/phase-13/1316/server/docker-compose.yml`
11+
- `samples/phase-13/1316/server/README.md`
12+
- `docs/pr/LEVEL_12_5_SERVER_HOSTING_DOCKER_RUNTIME_CHECKLIST.md`
13+
- `docs/pr/APPLY_PR_LEVEL_12_5_SERVER_HOSTING_DOCKER_RUNTIME.md`
14+
15+
Allowed nearby reads:
16+
- `src/engine/network/AuthoritativeServerRuntime.js`
17+
- `src/engine/network/ClientReplicationApplicationLayer.js`
18+
- `tests/final/MultiplayerNetworkingStack.test.mjs`
19+
- `samples/phase-13/1316/server/networkSampleADashboardServer.mjs`
20+
21+
## Required implementation
22+
- Add one Node server entrypoint that hosts the authoritative runtime in single-node mode.
23+
- Keep Docker runtime single-node only:
24+
- one container
25+
- one exposed service port
26+
- no orchestration, no horizontal scaling
27+
- Define env-driven runtime configuration for:
28+
- bind host
29+
- service port
30+
- session id
31+
- tick rate
32+
- optional admin/health key contract (if required by existing server pattern)
33+
- Provide startup/shutdown lifecycle behavior:
34+
- startup initializes authoritative runtime and begins accepting client/session interaction
35+
- shutdown stops runtime cleanly and exits without residual state
36+
- Provide container health/readiness endpoint and document commands.
37+
38+
## Acceptance criteria
39+
- Containerized server starts in single-node mode.
40+
- Client can connect to containerized server session path.
41+
- Session lifecycle is valid through startup, active session, and shutdown.
42+
- Startup/run/stop instructions are documented and repeatable.
43+
- Scope remains minimal; no scaling/orchestration features added.
44+
45+
## Validation
46+
Run only:
47+
- `node --check samples/phase-13/1316/server/authoritativeMultiplayerServer.mjs`
48+
- `docker build -f samples/phase-13/1316/server/Dockerfile samples/phase-13/1316 -t authoritative-server-single-node`
49+
- `docker run --rm -p 4310:4310 authoritative-server-single-node`
50+
- `docker compose -f samples/phase-13/1316/server/docker-compose.yml up --build`
51+
- `node --input-type=module -e "import('./tests/final/MultiplayerNetworkingStack.test.mjs').then(async ({ run }) => { await run(); console.log('PASS MultiplayerNetworkingStack'); })"`
52+
53+
## Non-goals
54+
- no cloud deployment expansion
55+
- no Kubernetes/orchestration layer
56+
- no horizontal scaling
57+
- no gameplay expansion
58+
- no 3D work
59+
- no broad debug/tool expansion
60+
61+
## Working tree rule
62+
If the tree is already dirty, ignore unrelated files and modify only the scoped files for this PR purpose.

‎docs/pr/LEVEL_12_5_SERVER_HOSTING_DOCKER_RUNTIME_PREP.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# LEVEL_12_5_SERVER_HOSTING_DOCKER_RUNTIME_PREP
2+
3+
## Goal
4+
Prepare an implementation-ready, minimal single-node Docker runtime plan for the authoritative server lane.
5+
6+
## Single-Node Runtime Model
7+
8+
- One container process hosts one authoritative server runtime instance.
9+
- One service port is exposed (default: `4310`).
10+
- One active session id is configured at startup (default: `session-authoritative`).
11+
- No multi-node clustering, no service discovery, no orchestration dependencies.
12+
13+
## Server Lifecycle Contract
14+
15+
Startup:
16+
- parse env config
17+
- initialize authoritative runtime
18+
- bind HTTP/WebSocket service endpoint(s)
19+
- expose readiness endpoint once runtime is active
20+
21+
Shutdown:
22+
- stop accepting new connections
23+
- flush/close active session state cleanly
24+
- stop runtime loop
25+
- close server process with deterministic exit
26+
27+
## Environment Contract (Minimal)
28+
29+
- `AUTHORITATIVE_SERVER_HOST` (default `0.0.0.0`)
30+
- `AUTHORITATIVE_SERVER_PORT` (default `4310`)
31+
- `AUTHORITATIVE_SESSION_ID` (default `session-authoritative`)
32+
- `AUTHORITATIVE_TICK_RATE_HZ` (default `20`)
33+
- `AUTHORITATIVE_LOG_LEVEL` (default `info`)
34+
35+
## Docker Contract (Minimal)
36+
37+
- Dockerfile uses Node runtime image with explicit working directory.
38+
- Container exposes `4310`.
39+
- Healthcheck targets `/health` (or existing compatible health route if retained).
40+
- Compose file defines one service only and maps host port to container port.
41+
42+
## Validation Checklist Targets
43+
44+
- container build succeeds
45+
- runtime starts in container and binds configured host/port
46+
- readiness/health endpoint returns success
47+
- client can connect to running container server
48+
- runtime stops cleanly on shutdown
49+
50+
## Failure Modes To Cover
51+
52+
- invalid env config blocks startup with clear error
53+
- port bind conflict fails fast with explicit log
54+
- health endpoint not ready while runtime uninitialized
55+
- abrupt shutdown leaves active runtime state (must be prevented)
56+
57+
## Scope Guardrails
58+
59+
- single-node only
60+
- no scaling/orchestration
61+
- no gameplay expansion
62+
- no 3D work

‎docs/pr/PLAN_PR_LEVEL_12_5_SERVER_HOSTING_DOCKER_RUNTIME.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# PLAN_PR_LEVEL_12_5_SERVER_HOSTING_DOCKER_RUNTIME
2+
3+
## Purpose
4+
Define containerized server runtime for authoritative multiplayer hosting.
5+
6+
## Scope
7+
- Define Docker-based server runtime model
8+
- Define environment configuration (ports, sessions, scaling assumptions)
9+
- Define startup/shutdown lifecycle
10+
- Define minimal deployment validation
11+
12+
## In Scope
13+
- Single-node Docker runtime
14+
- Local + LAN deployment validation
15+
- Config-driven startup
16+
17+
## Out of Scope
18+
- No cloud scaling yet
19+
- No orchestration (K8s, etc.)
20+
- No gameplay expansion
21+
22+
## Acceptance Criteria
23+
- Server runs in Docker
24+
- Client connects to containerized server
25+
- Session lifecycle validated
26+
- Repeatable startup instructions documented
27+
28+
## Roadmap Rule
29+
Update markers only [ ] [.] [x] — no wording/structure changes

0 commit comments

Comments
 (0)