[FEATURE] System message for servers with integration enabled

[FEATURE] Real-time Integration Status Notification for WebSockets

Description

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.

Proposed Logic

1. Ingest: Inside the validateRegistry middleware, every 1s poll updates a timestamp for the jobId in a fast-access Map/Cache.
2. Verify: When a WebSocket client emits a join event, the server performs a single lookup against the Registry.
3. Notify: If the jobId has been seen within the last 5 seconds, emit a one-time "Integration Active" system message to that specific socket.

Implementation Details

• Storage: Map<string, number> (JobId -> LastSeenTimestamp) or Redis SETEX.
• TTL: 5 seconds (to allow for slight network jitter while ensuring status expires quickly if the game server closes).
• Efficiency: $O(1)$ lookups ensure no impact on WebSocket performance.

Implementation Example

// 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);
});