feat(deploy): version-coherence — WS-анонс версии сервера + guarded reload устаревших вкладок (#481)

SPA — долгоживущий клиент: вкладку держат часами, сервер за это время
передеплоивают. Старый index.html ссылается на content-hashed чанки, которых в
новом образе нет → ленивый import() → catch-all отдаёт index.html как text/html →
WebKit «not a valid JavaScript MIME type» (наблюдали в проде). Реактивный
предохранитель (chunk-error-boundary) ловит УЖЕ случившуюся ошибку. Делаем сигнал
ПРОАКТИВНЫМ: сервер сообщает версию по существующему WS, клиент сравнивает и
делает guarded reload ДО битого чанка. closes #481

- Единый источник версии: vite.config.ts вычисляет resolveAppVersion РОВНО раз →
  и в define.APP_VERSION, и в плагине, пишущем dist/version.json. Бандл и файл
  тождественны by construction. Сервер читает client/dist/version.json при старте
  (client-version.ts: resolveClientDistPath вынесен из static.module — единый
  источник пути; readClientBuildVersion → версия или '' на любой ошибке,
  fail-safe). НИКАКИХ Docker/ENV-изменений.
- WS: отдельное событие app-version {version} (НЕ в message/WebSocketEvent —
  член без operation сломал бы union). ws.gateway читает версию в onModuleInit +
  boot-лог ACTIVE/DISABLED; emit в handleConnection (success-ветка, после join).
  ТОЛЬКО per-connect анонс, БЕЗ broadcast (broadcast в кластере → thundering-herd
  reload флота; естественный реконнект покрывает и single-container, и кластер).
- Клиент: listener навешан СИНХРОННО в том же useEffect, что создаёт сокет (до
  connect — иначе гонка с немедленным emit сервера). Чистая decideVersionAction
  (reload|banner|noop; пустая версия → noop fail-safe). Грязная оболочка
  triggerGuardedReload: модульный latch, hidden→немедленный reload, visible→баннер
  + reload-on-hidden {once}, фикс-id закрываемый баннер с кнопкой «Обновить».
- Общий one-shot флаг: reload-guard.ts (hasAutoReloaded/markAutoReloaded над
  существующим chunk-reload-attempted); chunk-load-error-boundary переведён на
  него. Проактивный + реактивный reload делят ОДИН счётчик → максимум одна
  авто-перезагрузка за сессию суммарно; permanent skew / oscillation / disabled
  storage → после первого reload только баннер, петли нет (проверено трассировкой).

Проверка: server jest client-version 7/7; client vitest version-coherence+
reload-guard+guarded-reload 16/16 (coverage 97.9%). Build-proof единого источника:
APP_VERSION=test-A → dist/version.json {"version":"test-A"} + вшито в бандл.
Полный staging-приём (docker build-arg, WS-кадры в DevTools, мульти-таб) — вне
автостенда, шаги приёмки #481 (крит.1-4) на ручную проверку.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

apps/server/src/common/helpers/client-version.spec.ts

@@ -0,0 +1,52 @@
+import { join } from 'path';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import { readClientBuildVersion } from './client-version';
+
+describe('readClientBuildVersion', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(join(os.tmpdir(), 'client-version-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  const writeVersionJson = (content: string) =>
+    fs.writeFileSync(join(dir, 'version.json'), content);
+
+  it('returns the version from a valid version.json', () => {
+    writeVersionJson(JSON.stringify({ version: 'test-A' }));
+    expect(readClientBuildVersion(dir)).toBe('test-A');
+  });
+
+  it('trims surrounding whitespace in the version', () => {
+    writeVersionJson(JSON.stringify({ version: '  v1.2.3  ' }));
+    expect(readClientBuildVersion(dir)).toBe('v1.2.3');
+  });
+
+  it('returns "" when version.json is missing', () => {
+    expect(readClientBuildVersion(dir)).toBe('');
+  });
+
+  it('returns "" on malformed JSON', () => {
+    writeVersionJson('{ not json');
+    expect(readClientBuildVersion(dir)).toBe('');
+  });
+
+  it('returns "" when the version field is absent', () => {
+    writeVersionJson(JSON.stringify({ notVersion: 'x' }));
+    expect(readClientBuildVersion(dir)).toBe('');
+  });
+
+  it('returns "" when the version field is not a string', () => {
+    writeVersionJson(JSON.stringify({ version: 123 }));
+    expect(readClientBuildVersion(dir)).toBe('');
+  });
+
+  it('returns "" when the path does not exist at all', () => {
+    expect(readClientBuildVersion(join(dir, 'nope'))).toBe('');
+  });
+});

apps/server/src/common/helpers/client-version.ts

@@ -0,0 +1,36 @@
+import { join } from 'path';
+import * as fs from 'node:fs';
+
+/**
+ * Resolve the absolute path to the built client bundle directory
+ * (`apps/client/dist`) shipped into the runtime image.
+ *
+ * The `../` depth is anchored on THIS module's compiled location
+ * (`dist/common/helpers`). `integrations/static` sits at the same depth under
+ * the compiled root, so both callers (StaticModule and readClientBuildVersion)
+ * MUST share this single helper rather than duplicating the depth — a copy in a
+ * module at a different depth would silently resolve to the wrong directory.
+ */
+export function resolveClientDistPath(): string {
+  return join(__dirname, '..', '..', '..', '..', 'client/dist');
+}
+
+/**
+ * Read the build version the client bundle was compiled with, from
+ * `<clientDistPath>/version.json` (written by the Vite build — the single
+ * source of truth shared by the baked-in `APP_VERSION` global and this file).
+ *
+ * Fail-safe: any error (missing file, unreadable, bad JSON, non-string
+ * version) yields `''`. The caller treats an empty version as "unknown" and
+ * the whole version-coherence feature stays silently inert — existing deploys
+ * without the file keep working unchanged.
+ */
+export function readClientBuildVersion(clientDistPath: string): string {
+  try {
+    const raw = fs.readFileSync(join(clientDistPath, 'version.json'), 'utf8');
+    const version = (JSON.parse(raw) as { version?: unknown }).version;
+    return typeof version === 'string' ? version.trim() : '';
+  } catch {
+    return '';
+  }
+}

apps/server/src/common/helpers/index.ts

@@ -3,3 +3,4 @@ export * from './nanoid.utils';
 export * from './file.helper';
 export * from './constants';
 export * from './security-headers';
+export * from './client-version';

apps/server/src/integrations/static/static.module.ts

@@ -4,6 +4,7 @@ import { join } from 'path';
 import * as fs from 'node:fs';
 import fastifyStatic from '@fastify/static';
 import { EnvironmentService } from '../environment/environment.service';
+import { resolveClientDistPath } from '../../common/helpers/client-version';
 
 /**
  * Resolve the response headers for a statically served client asset.
@@ -56,14 +57,7 @@ export class StaticModule implements OnModuleInit {
     const httpAdapter = this.httpAdapterHost.httpAdapter;
     const app = httpAdapter.getInstance();
 
-    const clientDistPath = join(
-      __dirname,
-      '..',
-      '..',
-      '..',
-      '..',
-      'client/dist',
-    );
+    const clientDistPath = resolveClientDistPath();
 
     const indexFilePath = join(clientDistPath, 'index.html');
 

apps/server/src/ws/ws.gateway.ts

@@ -9,10 +9,14 @@ import {
 import { Server, Socket } from 'socket.io';
 import { TokenService } from '../core/auth/services/token.service';
 import { JwtPayload, JwtType } from '../core/auth/dto/jwt-payload';
-import { OnModuleDestroy } from '@nestjs/common';
+import { Logger, OnModuleDestroy, OnModuleInit } from '@nestjs/common';
 import { SpaceMemberRepo } from '@docmost/db/repos/space/space-member.repo';
 import { WsService } from './ws.service';
 import { getSpaceRoomName, getUserRoomName } from './ws.utils';
+import {
+  readClientBuildVersion,
+  resolveClientDistPath,
+} from '../common/helpers/client-version';
 import * as cookie from 'cookie';
 
 @WebSocketGateway({
@@ -20,17 +24,40 @@ import * as cookie from 'cookie';
   transports: ['websocket'],
 })
 export class WsGateway
-  implements OnGatewayConnection, OnGatewayInit, OnModuleDestroy
+  implements
+    OnGatewayConnection,
+    OnGatewayInit,
+    OnModuleInit,
+    OnModuleDestroy
 {
   @WebSocketServer()
   server: Server;
 
+  private readonly logger = new Logger(WsGateway.name);
+
+  // The build version of the client bundle shipped in this image, read once at
+  // startup from client/dist/version.json (single source of truth, same value
+  // baked into the client's APP_VERSION). Empty string => version.json missing
+  // or empty => the proactive version-coherence reload feature stays inert.
+  private appVersion = '';
+
   constructor(
     private tokenService: TokenService,
     private spaceMemberRepo: SpaceMemberRepo,
     private wsService: WsService,
   ) {}
 
+  onModuleInit(): void {
+    this.appVersion = readClientBuildVersion(resolveClientDistPath());
+    if (this.appVersion) {
+      this.logger.log(`app-version reload: ACTIVE (v=${this.appVersion})`);
+    } else {
+      this.logger.log(
+        'app-version reload: DISABLED (version.json missing/empty)',
+      );
+    }
+  }
+
   afterInit(server: Server): void {
     this.wsService.setServer(server);
   }
@@ -55,6 +82,14 @@ export class WsGateway
       const spaceRooms = userSpaceIds.map((id) => getSpaceRoomName(id));
 
       client.join([userRoom, workspaceRoom, ...spaceRooms]);
+
+      // Announce this container's client build version to the freshly
+      // authenticated socket. On a redeploy the client reconnects to the new
+      // container and receives the new version here, letting it guard-reload
+      // before it hits a stale lazy chunk. Per-connect only (no broadcast):
+      // natural reconnect covers both single-container and cluster without a
+      // thundering-herd fleet reload.
+      client.emit('app-version', { version: this.appVersion });
     } catch (err) {
       client.emit('Unauthorized');
       client.disconnect();