cd42a8c294
- MIGRATION.md: step-by-step consumer update guide - CLEANUP.md: cleanup process for old package locations - cleanup-old-locations.sh: automated cleanup script Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
146 lines
4.4 KiB
Markdown
146 lines
4.4 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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**:
|
|
```typescript
|
|
// Direct Socket.IO usage in hooks
|
|
import { io, Socket } from 'socket.io-client';
|
|
```
|
|
|
|
**After migration**:
|
|
```typescript
|
|
// 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/`):
|
|
|
|
```typescript
|
|
// 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**:
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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.
|