websocket/MIGRATION.md

WebSocket Packages Migration Guide

Overview

The WebSocket functionality has been restructured into a monorepo with three separately published packages:

• @lilith/websocket-core: Shared types and interfaces
• @lilith/websocket-client: React hooks for Socket.IO client connections
• @lilith/websocket-server: NestJS BaseGateway base classes and utilities

Publishing

Before updating consumers, publish the packages:

cd ~/Code/@packages/@ts/@websocket

# Option 1: Dev publish for testing
cd core && npx @lilith/dev-publish
cd client && npx @lilith/dev-publish
cd server && npx @lilith/dev-publish

# Option 2: Official publish via CI/CD
git push origin main
# Forgejo CI will publish all three packages

Consumers to Update

1. Status Dashboard

Location: codebase/features/status-dashboard/frontend-public/

Current imports:

// Direct Socket.IO usage in hooks
import { io, Socket } from 'socket.io-client';

After migration:

// Option A: Use existing hooks from @lilith/websocket-client
import { useWebSocket } from '@lilith/websocket-client';

const { socket, connected, error } = useWebSocket({
  url: import.meta.env.VITE_WS_URL || '',
  namespace: '/health',
  token: localStorage.getItem('auth_token'),
});

// Option B: Keep current implementation (shared namespace pattern is already optimal)
// The useHealthNamespace hook follows best practices and can stay as-is

Backend (codebase/features/status-dashboard/backend-api/):

// Before
import { WebSocketGateway, OnGatewayConnection, OnGatewayDisconnect } from '@nestjs/websockets';
import type { Server, Socket } from 'socket.io';

@WebSocketGateway({ cors: { origin: '*' }, namespace: '/health' })
export class HealthGateway implements OnGatewayConnection, OnGatewayDisconnect {
  handleConnection(client: Socket) {
    const token = client.handshake.auth.token || client.handshake.query.token;
    // Manual JWT extraction...
  }
}

// After
import { BaseGateway } from '@lilith/websocket-server';
import { WebSocketGateway } from '@nestjs/websockets';

@WebSocketGateway({ cors: { origin: '*' }, namespace: '/health' })
export class HealthGateway extends BaseGateway {
  constructor() {
    super('HealthGateway');
  }

  protected onConnectionOpen(client: Socket): void {
    super.onConnectionOpen(client);
    // Custom connection logic only
  }
}

Installation:

cd codebase/features/status-dashboard/frontend-public
pnpm add @lilith/websocket-client@1.0.0

cd ../backend-api
pnpm add @lilith/websocket-server@1.0.0

Benefits:

• Eliminates ~495 lines of duplicate gateway code
• Standardized authentication, room management, rate limiting
• Type-safe client metadata tracking
• Consistent logging and error handling

2. Other Features (Future)

Check for any other features using Socket.IO:

# Find Socket.IO usage
grep -r "socket.io" codebase/features/*/frontend-*/src --include="*.ts" --include="*.tsx"
grep -r "@WebSocketGateway" codebase/features/*/backend-*/src --include="*.ts"

Old Package Locations (to be removed after migration)

1. /var/home/lilith/Code/@packages/@ts/websocket/
2. /var/home/lilith/Code/@packages/@ts/websocket-client/
3. /var/home/lilith/Code/@packages/@ts/websocket-server/
4. /var/home/lilith/Code/@projects/@lilith/lilith-platform/codebase/@packages/@infrastructure/websocket-client/

Do NOT delete until all consumers are updated and verified.

Rollback Plan

If issues occur after migration:

1. Revert consumer changes
2. Point package.json back to old packages temporarily
3. Fix issues in new monorepo packages
4. Republish with patch version
5. Re-migrate consumers

Verification Checklist

After updating each consumer:

• pnpm typecheck passes
• pnpm build succeeds
• WebSocket connections work (check browser DevTools → Network → WS)
• Real-time updates still work
• Authentication still works
• No console errors related to WebSocket

Notes

• Status-dashboard frontend: The useHealthNamespace pattern is already optimal. Migration to @lilith/websocket-client is optional and provides marginal benefit.
• Status-dashboard backend: Migrating to BaseGateway is HIGHLY RECOMMENDED - eliminates significant duplication and standardizes patterns.
• New features: Always use @lilith/websocket-{client,server} packages, never reinvent WebSocket patterns.