Currently, game servers with integration enabled poll the /api/v1/commands endpoint every 1 second (default). This poll includes the jobId in the headers. We can leverage this frequent heartbeat to maintain a "Registry" of active servers.
When a client (user) joins a WebSocket room, we should check this registry to immediately notify them if the server they are on is officially integrated with our system.
validateRegistry middleware, every 1s poll updates a timestamp for the jobId in a fast-access Map/Cache.join event, the server performs a single lookup against the Registry.jobId has been seen within the last 5 seconds, emit a one-time "Integration Active" system message to that specific socket.Map<string, number> (JobId -> LastSeenTimestamp) or Redis SETEX.// A simple In-Memory Registry to track active integrations
// Format: jobId -> lastSeenTimestamp
const jobRegistry = new Map();
// TTL: How long a jobId stays "valid" after the last poll (e.g., 5 seconds)
const REGISTRY_TTL_MS = 5000;
// ----- Command Mailbox Middleware -----
const validateRegistry = async (req, res, next) => {
const universeId = req.headers['x-universe-id'];
const apiKey = req.headers['x-api-key'];
const jobId = req.headers['x-job-id'];
if (!universeId || !apiKey || !jobId) {
return res.status(401).json({ error: "Missing identity headers." });
}
const isAuthenticated = await authenticateGameServer(universeId, apiKey);
if (!isAuthenticated) {
console.warn(`Unauthorized access attempt: Universe ${universeId}`);
return res.status(403).json({ error: "Invalid credentials." });
}
// --- INTEGRATION TRACKING ---
// Every time they poll (1s), we update their "Last Seen" timestamp.
// This is O(1) and extremely lightweight.
jobRegistry.set(jobId, Date.now());
// Optional: Periodically clean up the Map to prevent memory leaks
// (Or use a TTL cache library like 'lru-cache')
req.jobId = jobId;
next();
};
// --------------------------------
// ----- WebSocket Logic ----------
// --------------------------------
// This runs only ONCE when a client joins a room or connects
io.on('connection', (socket) => {
socket.on('join_job', (data) => {
const { jobId } = data;
// 1. Join the socket room as usual
socket.join(jobId);
// 2. Check if this JobId is currently integrated
const lastSeen = jobRegistry.get(jobId);
const isIntegrated = lastSeen && (Date.now() - lastSeen < REGISTRY_TTL_MS);
if (isIntegrated) {
// 3. Notify the client ONCE that the server is integrated
socket.emit('system_message', {
type: 'INTEGRATION_SUCCESS',
message: 'This server has RCL Integration enabled.',
timestamp: Date.now()
});
}
});
});
// --------------------------------
// ----- The Mailbox Endpoint -----
// --------------------------------
app.get('/api/v1/commands', validateRegistry, (req, res) => {
const { jobId } = req;
const messages = mailboxStore.get(jobId) || [];
const validMessages = messages.filter(msg => msg.expiresAt > Date.now());
mailboxStore.delete(jobId);
const payloads = validMessages.map(m => m.payload);
res.json(payloads);
});