feat(control-plane): UserIdDirectory + ServerIdDirectory, e2e stability fixes

[gmliao]

Summary

Part 1 — Matchmaking stability fixes (pre-existing commits)

• ticketId now UUID; assignment TTL set correctly
• Deferred env reads to avoid startup-time failures
• REDIS_DB=1 isolation for split-role e2e
• BullMQ/Redis connection stability in e2e (globalSetup, beforeAll)

Part 2 — ClusterDirectory → UserIdDirectory + ServerIdDirectory refactor

Refactors the in-memory ServerRegistryService into a Redis-backed ServerIdDirectory, making game server registrations visible across all control-plane nodes.

Architecture change:

• UserIdDirectory (USER_ID_DIRECTORY) — userId→nodeId with TTL lease; used by Realtime and Matchmaking (rename of ClusterDirectory)
• ServerIdDirectory (SERVER_ID_DIRECTORY) — serverId→ServerEntry; Redis-backed, cross-node; used by Provisioning and Admin
• ClusterDirectory token and ServerRegistryService removed

Files changed:

• infra/cluster-directory/ — new UserIdDirectory, ServerIdDirectory interfaces + Redis impls
• infra/contracts/server-entry.dto.ts — ServerEntry extracted to shared location
• ProvisioningController, InMemoryProvisioningClient — inject SERVER_ID_DIRECTORY
• AdminController — inject SERVER_ID_DIRECTORY, getServers() now async
• UserSessionRegistryService, MatchmakingService — inject USER_ID_DIRECTORY
• All unit tests and e2e tests updated

E2E Redis isolation:

• e2e-global-setup.ts and e2e-helpers.flushServerKeys() flush cd:server:* keys between suites to prevent cross-test pollution

Test plan

• npm run build — PASS
• npm test — 11 suites / 49 tests PASS
• npm run test:e2e -- --runInBand — 6 suites / 18 passed + 1 skipped PASS

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

swift-state-tree/Packages/control-plane/src/modules/realtime/realtime.module.ts

Line 13 in 450f71e

RealtimeGateway,

Gate RealtimeGateway to API-enabled roles

The gateway is always registered, so MATCHMAKING_ROLE=queue-worker instances still accept /realtime connections even though this role disables channel subscriptions (isApiEnabled(...) short-circuits in both Redis channel services). In that state, clients can enqueue but will never receive match.assigned, so requests routed to a worker node appear to hang indefinitely; this breaks the split-role deployment model whenever a worker is reachable (LB misroute, direct access, or config drift).

---

swift-state-tree/Packages/control-plane/src/modules/realtime/realtime.gateway.ts

Lines 123 to 126 in 450f71e

	const m = msg as { action?: string };
	if (m?.action === 'enqueue') {
	this.handleEnqueue(client, m as WsEnqueueMessage);
	return;

Validate WebSocket enqueue payload before queuing

WebSocket messages are only JSON-parsed and then cast to WsEnqueueMessage without runtime validation, so malformed enqueue payloads (for example missing groupSize or members) are still forwarded to matchmakingService.enqueue. This can create invalid queued tickets that never become matchable and can pollute queue state, whereas the HTTP path is protected by DTO validation.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[gmliao]

Both comments addressed in commit 585610e:

P1 — Gate RealtimeGateway to API-enabled roles

Added an early-return in handleConnection:

if (!isApiEnabled(getMatchmakingRole())) {
  client.close(4403, 'This node does not serve WebSocket connections (queue-worker role)');
  return;
}

queue-worker nodes now immediately close any incoming /realtime connection with code 4403, preventing the silent-hang scenario described.

P2 — Validate WebSocket enqueue payload via class-validator

Added WsEnqueueMessageDto class to ws-envelope.dto.ts with the same validators as the HTTP EnqueueRequest DTO (@IsNotEmpty, @IsString, @IsArray, @IsInt, @Min(1), @IsOptional). In setupMessageHandler, before calling handleEnqueue, the payload is now validated:

const dto = plainToInstance(WsEnqueueMessageDto, m);
const errors = await validate(dto);
if (errors.length > 0) {
  this.sendError(client, `Invalid enqueue payload: ${detail}`);
  return;
}

Malformed payloads (missing queueKey, wrong groupSize type, etc.) are now rejected with a descriptive error message before reaching the queue. Both class-validator and class-transformer were already in package.json.

All tests pass: build ✅ / unit 49/49 ✅ / e2e 18/19 ✅ (1 pre-existing skip)