Talon/chat_grid
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Split client and server revision tracking

Browse Source
This commit is contained in:
Jage9
2026-03-09 02:31:00 -04:00
parent 0cf660c606
commit 1a8f750aa6
10 changed files with 105 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
docs/protocol-notes.md
View File

@@ -38,6 +38,7 @@ This is a behavior guide for packet semantics beyond raw schemas.
## Server -> Client
- `auth_required`: authentication challenge after websocket connect.
- includes `gridName`, `welcomeMessage`, `serverVersion`, and `expectedClientRevision`.
- `auth_result`: auth success/failure and session/account metadata.
- `auth_permissions`: server-pushed live role/permission refresh for current session.
- `admin_roles_list`: role list response payload.
@@ -96,6 +97,8 @@ This is a behavior guide for packet semantics beyond raw schemas.
- `policy` (`usernameMinLength`, `usernameMaxLength`, `passwordMinLength`, `passwordMaxLength`)
- `auth_required.authPolicy`: server auth limits advertised before login/register submit.
- `auth_required.gridName` / `auth_required.welcomeMessage`: server-owned pre-login branding values.
- `auth_required.serverVersion`: server diagnostics version text shown in connect/reconnect messaging.
- `auth_required.expectedClientRevision`: authoritative browser asset revision required by this server instance.
- `auth_result.authPolicy`: server auth limits echoed on auth success/failure responses.
- `auth_result.sessionToken` is used by the client to call the instance-scoped HTTP endpoint `GET <base_path>auth/session/set` (`Authorization: Bearer <sessionToken>`, `X-Chgrid-Auth-Client: 1`) so the server can issue an instance-scoped `HttpOnly` session cookie.
- `welcome.worldConfig.gridSize`: server-authoritative grid size used by clients for bounds/drawing.
@@ -104,7 +107,9 @@ This is a behavior guide for packet semantics beyond raw schemas.
- `welcome.player`: server-assigned spawn/current self position at connect time.
- `welcome.serverInfo`: server process identity/version metadata:
- `instanceId`: unique id generated at server startup
- `version`: server package version (or `unknown` fallback)
- `releaseVersion`: shared public release version
- `serverVersion`: server diagnostics version text (`release + server revision`)
- `expectedClientRevision`: browser asset revision required by this server instance
- `gridName`: server-owned user-facing grid name
- `welcomeMessage`: server-owned pre-login welcome string
- `welcome.uiDefinitions`: server-provided item UI definitions:
@@ -157,4 +162,5 @@ This is a behavior guide for packet semantics beyond raw schemas.
- After reconnect, if `welcome.serverInfo.instanceId` changed, client announces `Server restarted.`
- Client emits `Connected to server. Version <version>.` on initial `welcome` and
`Reconnected to server. Version <version>.` after reconnect.
- If `welcome.serverInfo.version` differs from running client version, client auto-reloads.
- If `auth_required.expectedClientRevision` or `welcome.serverInfo.expectedClientRevision` differs from the running client revision, client auto-reloads.
- Server-only version changes do not trigger browser reload unless `expectedClientRevision` also changes.

6
docs/runtime-flow.md
View File

@@ -8,6 +8,7 @@
4. Server accepts the socket only on the configured instance websocket path and when the browser `Origin` matches `CHGRID_HOST_ORIGIN`, then attempts cookie-based session resume from the instance-scoped websocket handshake cookie.
5. If resume does not authenticate, server sends `auth_required`.
- includes `gridName` and `welcomeMessage` for pre-login branding.
- includes `serverVersion` and `expectedClientRevision` for stale-client detection before login.
- includes `authPolicy` limits for username/password.
6. Client sends `auth_login` or `auth_register` (or explicit `auth_resume` if provided by caller).
7. Server sends `auth_result`.
@@ -20,8 +21,8 @@
- applies `welcome.worldConfig.movementTickMs` as movement pacing guidance
- applies `welcome.worldConfig.movementMaxStepsPerTick` for movement-rate parity
- uses `welcome.player` as authoritative starting position (restored from server-side account state when available)
- records `welcome.serverInfo` (`instanceId`, `version`, `gridName`, `welcomeMessage`) for restart detection and client branding
- if `welcome.serverInfo.version` differs from running client version, auto-reloads the page
- records `welcome.serverInfo` (`instanceId`, `releaseVersion`, `serverVersion`, `expectedClientRevision`, `gridName`, `welcomeMessage`) for restart detection and client branding
- if `welcome.serverInfo.expectedClientRevision` differs from the running client revision, auto-reloads the page
- applies `welcome.uiDefinitions` for item menus/properties/options, server-backed command metadata, item-management metadata, and admin menu labels/order
- sends initial `update_position` echo from server-assigned starting tile
- sends initial `update_nickname`
@@ -75,6 +76,7 @@ Core incoming message effects:
- Reconnect flow waits 5 seconds and retries up to 3 times.
- If reconnect lands on a different `welcome.serverInfo.instanceId`, client announces server restart.
- Connect/reconnect status message is emitted from `welcome` and includes server version.
- Server-only deploys no longer force browser reloads unless `expectedClientRevision` changes.
## Authorization Runtime