Reject version-mismatched joins and prompt refresh on homepage after deploys

package.json

@@ -13,6 +13,7 @@
     "docs:map-generator": "cd map-generator && go doc -cmd -u -all",
     "tunnel": "npm run build-prod && npm run start:server",
     "test": "vitest run && vitest run tests/server",
+    "test:e2e": "cross-env E2E=1 vitest run tests/e2e",
     "test:matchmaking": "node tests/matchmaking/contained.mjs",
     "test:matchmaking:e2e": "node tests/matchmaking/e2e.mjs",
     "perf": "npx tsx tests/perf/run-all.ts",

resources/lang/en.json

@@ -1504,6 +1504,9 @@
     "sam_launcher": "SAM Launcher",
     "warship": "Warship"
   },
+  "update_available": {
+    "message": "A new version of OpenFront is available. The page will now refresh to update."
+  },
   "user_setting": {
     "alert_frame_desc": "Toggle the alert frame. When enabled, the frame will be displayed when you are betrayed or attacked over land.",
     "alert_frame_label": "Alert Frame",

src/client/ClientGameRunner.ts

@@ -229,6 +229,12 @@ export function joinLobby(
             }),
           );
         });
+      } else if (message.error === "version_mismatch") {
+        // The server runs a newer build than this bundle (tab left open
+        // across a deploy). Reload to pick up the new version.
+        showInGameAlert(translateText("update_available.message")).then(() => {
+          window.location.reload();
+        });
       } else {
         showErrorModal(
           message.error,

src/client/GameModeSelector.ts

@@ -12,6 +12,7 @@ import {
 import { PublicGameInfo, PublicGames } from "../core/Schemas";
 import "./components/IOSAddToHomeScreenBanner";
 import { HostLobbyModal } from "./HostLobbyModal";
+import { showInGameAlert } from "./InGameModal";
 import { JoinLobbyModal } from "./JoinLobbyModal";
 import { PublicLobbySocket } from "./LobbySocket";
 import { JoinLobbyEvent } from "./Main";
@@ -37,10 +38,19 @@ export class GameModeSelector extends LitElement {
   private serverTimeOffset: number = 0;
   private defaultLobbyTime: number = 0;
 
-  private lobbySocket = new PublicLobbySocket((lobbies) =>
-    this.handleLobbiesUpdate(lobbies),
+  private lobbySocket = new PublicLobbySocket(
+    (lobbies) => this.handleLobbiesUpdate(lobbies),
+    // This socket only runs while the player is on the homepage (Main.ts
+    // stops it when a game is joined), so it's always safe to reload here.
+    { onUpdateAvailable: () => this.handleUpdateAvailable() },
   );
 
+  private handleUpdateAvailable() {
+    showInGameAlert(translateText("update_available.message")).then(() => {
+      window.location.reload();
+    });
+  }
+
   createRenderRoot() {
     return this;
   }

src/client/LobbySocket.ts

@@ -5,6 +5,9 @@ interface LobbySocketOptions {
   reconnectDelay?: number;
   maxWsAttempts?: number;
   pollIntervalMs?: number;
+  // Fired at most once, when the server advertises a different build commit
+  // than this bundle — i.e. a new version deployed while this tab was open.
+  onUpdateAvailable?: () => void;
 }
 
 function getRandomWorkerPath(numWorkers: number): string {
@@ -24,13 +27,16 @@ export class PublicLobbySocket {
 
   private readonly reconnectDelay: number;
   private readonly maxWsAttempts: number;
+  private readonly onUpdateAvailable?: () => void;
+  private updateAvailableFired = false;
 
   constructor(
     private onLobbiesUpdate: (data: PublicGames) => void,
     options?: LobbySocketOptions,
   ) {
     this.reconnectDelay = options?.reconnectDelay ?? 3000;
     this.maxWsAttempts = options?.maxWsAttempts ?? 3;
+    this.onUpdateAvailable = options?.onUpdateAvailable;
   }
 
   async start() {
@@ -88,6 +94,7 @@ export class PublicLobbySocket {
         JSON.parse(event.data as string),
       );
       if (message.type === "full") {
+        this.checkServerCommit(message.gitCommit);
         this.lastFull = {
           serverTime: message.serverTime,
           games: message.games,
@@ -134,6 +141,17 @@ export class PublicLobbySocket {
     }
   }
 
+  private checkServerCommit(serverCommit: string | undefined) {
+    if (this.updateAvailableFired || this.onUpdateAvailable === undefined) {
+      return;
+    }
+    if (serverCommit === undefined) return;
+    const ownCommit = ClientEnv.gitCommit();
+    if (ownCommit === "DEV" || serverCommit === ownCommit) return;
+    this.updateAvailableFired = true;
+    this.onUpdateAvailable();
+  }
+
   private handleClose() {
     if (this.stopped) return;
     console.log("WebSocket disconnected, attempting to reconnect...");

src/client/Transport.ts

@@ -427,6 +427,7 @@ export class Transport {
       cosmetics: this.lobbyConfig.cosmetics,
       turnstileToken: this.lobbyConfig.turnstileToken,
       token: await getPlayToken(),
+      gitCommit: ClientEnv.gitCommit(),
     } satisfies ClientJoinMessage);
   }
 
@@ -437,6 +438,7 @@ export class Transport {
       // Note: clientID is not sent - server looks it up from persistentID in token
       lastTurn: lastTurn,
       token: await getPlayToken(),
+      gitCommit: ClientEnv.gitCommit(),
     } satisfies ClientRejoinMessage);
   }
 

src/core/Schemas.ts

@@ -250,6 +250,10 @@ export const PublicLobbyFullSchema = z.object({
   type: z.literal("full"),
   serverTime: z.number(),
   games: z.partialRecord(PublicGameTypeSchema, z.array(PublicGameInfoSchema)),
+  // Build commit of the serving deployment. Clients on the homepage compare
+  // it to their own bundle's commit to detect that a new version deployed
+  // and prompt a refresh. Optional so clients tolerate older servers.
+  gitCommit: z.string().max(64).optional(),
 });
 
 export const PublicLobbyCountsSchema = z.object({
@@ -879,6 +883,11 @@ export const ClientJoinMessageSchema = z.object({
   // Server replaces the refs with the actual cosmetic data.
   cosmetics: PlayerCosmeticRefsSchema.optional(),
   turnstileToken: z.string().nullable(),
+  // Build commit of the client bundle. The sim only stays deterministic when
+  // every client in a game runs identical code, so the server rejects joins
+  // whose commit doesn't match its own (missing counts as a mismatch —
+  // pre-feature bundles are by definition stale).
+  gitCommit: z.string().max(64).optional(),
 });
 
 export const ClientRejoinMessageSchema = z.object({
@@ -887,6 +896,8 @@ export const ClientRejoinMessageSchema = z.object({
   // Note: clientID is NOT sent - server looks it up from persistentID in token
   lastTurn: z.number(),
   token: TokenSchema,
+  // See ClientJoinMessageSchema.gitCommit.
+  gitCommit: z.string().max(64).optional(),
 });
 
 export const ClientMessageSchema = z.discriminatedUnion("type", [

src/server/Worker.ts

@@ -451,6 +451,26 @@ export async function startWorker() {
           return;
         }
 
+        // The sim is deterministic only when every client in a game runs
+        // identical code, so a client built from a different commit (e.g. a
+        // tab left open across a deploy) would desync the game. Reject it
+        // with a typed error the client answers by refreshing. A missing
+        // commit means a pre-feature bundle, which is stale by definition.
+        if (clientMsg.gitCommit !== ServerEnv.gitCommit()) {
+          log.info("rejecting version-mismatched client", {
+            gameID: clientMsg.gameID,
+            clientCommit: clientMsg.gitCommit,
+          });
+          ws.send(
+            JSON.stringify({
+              type: "error",
+              error: "version_mismatch",
+            } satisfies ServerErrorMessage),
+          );
+          ws.close(1002, "Version mismatch");
+          return;
+        }
+
         // Verify token signature
         const result = await verifyClientToken(clientMsg.token);
         if (result.type === "error") {

src/server/WorkerLobbyService.ts

@@ -15,6 +15,7 @@ import {
   WorkerReady,
 } from "./IPCBridgeSchema";
 import { logger } from "./Logger";
+import { ServerEnv } from "./ServerEnv";
 
 // The game config advertised for a listed private lobby: everything the
 // host configured minus host-only fields. The server already rejects
@@ -256,6 +257,7 @@ export class WorkerLobbyService {
           type: "full",
           serverTime: this.lastPublicGames.serverTime,
           games: this.sanitizeGames(this.lastPublicGames.games),
+          gitCommit: ServerEnv.gitCommit(),
         } satisfies PublicLobbyMessage);
         ws.send(fullJson);
       }
@@ -307,6 +309,7 @@ export class WorkerLobbyService {
         type: "full",
         serverTime: publicGames.serverTime,
         games: sanitizedGames,
+        gitCommit: ServerEnv.gitCommit(),
       };
       this.lastFullGameIds = fingerprint;
     } else {

tests/ClientVersionSchemas.test.ts

@@ -0,0 +1,71 @@
+import {
+  ClientJoinMessageSchema,
+  ClientRejoinMessageSchema,
+  PublicLobbyMessageSchema,
+} from "../src/core/Schemas";
+
+const COMMIT = "a".repeat(40);
+
+const baseJoin = {
+  type: "join",
+  token: "123e4567-e89b-12d3-a456-426614174000",
+  gameID: "abcd1234",
+  username: "TestPlayer",
+  clanTag: null,
+  turnstileToken: null,
+};
+
+const baseRejoin = {
+  type: "rejoin",
+  gameID: "abcd1234",
+  lastTurn: 10,
+  token: "123e4567-e89b-12d3-a456-426614174000",
+};
+
+describe("gitCommit on join/rejoin messages", () => {
+  test("join parses with gitCommit", () => {
+    const result = ClientJoinMessageSchema.safeParse({
+      ...baseJoin,
+      gitCommit: COMMIT,
+    });
+    expect(result.success).toBe(true);
+    expect(result.data?.gitCommit).toBe(COMMIT);
+  });
+
+  test("join parses without gitCommit (pre-feature clients)", () => {
+    const result = ClientJoinMessageSchema.safeParse(baseJoin);
+    expect(result.success).toBe(true);
+    expect(result.data?.gitCommit).toBeUndefined();
+  });
+
+  test("join rejects an oversized gitCommit", () => {
+    const result = ClientJoinMessageSchema.safeParse({
+      ...baseJoin,
+      gitCommit: "a".repeat(65),
+    });
+    expect(result.success).toBe(false);
+  });
+
+  test("rejoin parses with and without gitCommit", () => {
+    expect(
+      ClientRejoinMessageSchema.safeParse({ ...baseRejoin, gitCommit: COMMIT })
+        .success,
+    ).toBe(true);
+    expect(ClientRejoinMessageSchema.safeParse(baseRejoin).success).toBe(true);
+  });
+});
+
+describe("gitCommit on the public lobby feed", () => {
+  test("full message parses with and without gitCommit", () => {
+    const full = { type: "full", serverTime: 123, games: {} };
+    expect(PublicLobbyMessageSchema.safeParse(full).success).toBe(true);
+    const withCommit = PublicLobbyMessageSchema.safeParse({
+      ...full,
+      gitCommit: COMMIT,
+    });
+    expect(withCommit.success).toBe(true);
+    if (withCommit.success && withCommit.data.type === "full") {
+      expect(withCommit.data.gitCommit).toBe(COMMIT);
+    }
+  });
+});