api-ape 2.2.2 → 2.3.0

package/server/adapters/mongo.js

@@ -0,0 +1,161 @@
+/**
+ * MongoDB Adapter for APE Cluster
+ * 
+ * Uses MongoDB Change Streams for real-time inter-server messaging.
+ * Requires replica set for change stream support.
+ */
+
+/**
+ * Create MongoDB adapter
+ * @param {MongoClient} mongoClient - MongoDB client
+ * @param {object} opts
+ * @param {string} opts.serverId - This server's unique ID
+ * @param {string} [opts.namespace='ape'] - Database/collection prefix
+ * @returns {Promise<AdapterInstance>}
+ */
+async function createMongoAdapter(mongoClient, { serverId, namespace = 'ape' }) {
+    if (!serverId) throw new Error('serverId required');
+
+    // State machine: INIT -> JOINED -> LEFT
+    let state = 'INIT';
+    const ownedClients = new Set();
+    const handlers = new Map();
+    let changeStream = null;
+
+    // Use dedicated database for APE cluster
+    const db = mongoClient.db(`${namespace}_cluster`);
+    const clientsCol = db.collection('clients');
+    const eventsCol = db.collection('events');
+
+    // Ensure indexes
+    async function ensureIndexes() {
+        await clientsCol.createIndex({ clientId: 1 }, { unique: true });
+        await clientsCol.createIndex({ serverId: 1 });
+        // Events TTL - auto-delete after 1 hour
+        await eventsCol.createIndex({ createdAt: 1 }, { expireAfterSeconds: 3600 });
+        await eventsCol.createIndex({ targetServerId: 1, createdAt: 1 });
+    }
+
+    const adapter = {
+        get serverId() { return serverId; },
+
+        async join(id) {
+            const sid = id || serverId;
+            if (!sid?.trim()) throw new Error('serverId required');
+            if (state === 'JOINED') throw new Error('already joined');
+            if (state === 'LEFT') throw new Error('cannot rejoin after leave');
+
+            await ensureIndexes();
+
+            // Watch for events targeted to this server or broadcast
+            try {
+                changeStream = eventsCol.watch([
+                    {
+                        $match: {
+                            'fullDocument.targetServerId': { $in: [sid, ''] },
+                            operationType: 'insert'
+                        }
+                    }
+                ], { fullDocument: 'updateLookup' });
+
+                changeStream.on('change', (change) => {
+                    if (change.operationType === 'insert') {
+                        const doc = change.fullDocument;
+                        const handler = handlers.get(doc.targetServerId) || handlers.get('');
+                        if (handler) {
+                            handler(doc.message, doc.senderServerId);
+                        }
+                    }
+                });
+
+                changeStream.on('error', (err) => {
+                    console.error('📛 Mongo adapter: change stream error', err.message);
+                });
+
+            } catch (e) {
+                console.warn('⚠️ Mongo adapter: Change streams not available (requires replica set). Falling back to polling.');
+                // Could implement polling fallback here
+            }
+
+            state = 'JOINED';
+            console.log(`✅ Mongo adapter: joined as ${sid}`);
+        },
+
+        async leave() {
+            if (state !== 'JOINED') return;
+            state = 'LEFT';
+
+            console.log(`🔴 Mongo adapter: leaving, cleaning up ${ownedClients.size} clients`);
+
+            // Close change stream
+            if (changeStream) {
+                await changeStream.close();
+                changeStream = null;
+            }
+
+            // Remove all owned client mappings
+            if (ownedClients.size > 0) {
+                await clientsCol.deleteMany({
+                    clientId: { $in: Array.from(ownedClients) }
+                });
+            }
+            ownedClients.clear();
+        },
+
+        lookup: {
+            async add(clientId) {
+                await clientsCol.updateOne(
+                    { clientId },
+                    { $set: { clientId, serverId, updatedAt: new Date() } },
+                    { upsert: true }
+                );
+                ownedClients.add(clientId);
+                console.log(`📍 Mongo adapter: registered client ${clientId} -> ${serverId}`);
+            },
+
+            async read(clientId) {
+                const doc = await clientsCol.findOne({ clientId });
+                return doc?.serverId || null;
+            },
+
+            async remove(clientId) {
+                if (!ownedClients.has(clientId)) {
+                    throw new Error(`not owner: cannot remove client ${clientId}`);
+                }
+                await clientsCol.deleteOne({ clientId });
+                ownedClients.delete(clientId);
+                console.log(`🗑️ Mongo adapter: removed client ${clientId}`);
+            }
+        },
+
+        channels: {
+            async push(targetServerId, message) {
+                await eventsCol.insertOne({
+                    targetServerId: targetServerId || '',
+                    senderServerId: serverId,
+                    message,
+                    createdAt: new Date()
+                });
+
+                if (targetServerId) {
+                    console.log(`📤 Mongo adapter: pushed to server ${targetServerId}`);
+                } else {
+                    console.log(`📢 Mongo adapter: broadcast to all servers`);
+                }
+            },
+
+            async pull(targetServerId, handler) {
+                handlers.set(targetServerId || '', handler);
+
+                // Return unsubscribe function
+                return async () => {
+                    handlers.delete(targetServerId || '');
+                };
+            }
+        }
+    };
+
+    return adapter;
+}
+
+module.exports = { createMongoAdapter };

package/server/adapters/postgres.js

@@ -0,0 +1,177 @@
+/**
+ * PostgreSQL Adapter for APE Cluster
+ * 
+ * Uses PostgreSQL LISTEN/NOTIFY for real-time inter-server messaging.
+ * Client mappings stored in a dedicated table.
+ */
+
+/**
+ * Create PostgreSQL adapter
+ * @param {pg.Pool} pool - PostgreSQL connection pool
+ * @param {object} opts
+ * @param {string} opts.serverId - This server's unique ID
+ * @param {string} [opts.namespace='ape'] - Table prefix
+ * @returns {Promise<AdapterInstance>}
+ */
+async function createPostgresAdapter(pool, { serverId, namespace = 'ape' }) {
+    if (!serverId) throw new Error('serverId required');
+
+    // State machine: INIT -> JOINED -> LEFT
+    let state = 'INIT';
+    const ownedClients = new Set();
+    const handlers = new Map();
+    let listenerClient = null;
+
+    // Table and channel names
+    const clientsTable = `${namespace}_clients`;
+    const eventsChannel = `${namespace}_events`;
+
+    // Ensure schema
+    async function ensureSchema() {
+        await pool.query(`
+      CREATE TABLE IF NOT EXISTS ${clientsTable} (
+        client_id VARCHAR(255) PRIMARY KEY,
+        server_id VARCHAR(255) NOT NULL,
+        updated_at TIMESTAMP DEFAULT NOW()
+      );
+      CREATE INDEX IF NOT EXISTS idx_${clientsTable}_server_id 
+        ON ${clientsTable}(server_id);
+    `);
+    }
+
+    const adapter = {
+        get serverId() { return serverId; },
+
+        async join(id) {
+            const sid = id || serverId;
+            if (!sid?.trim()) throw new Error('serverId required');
+            if (state === 'JOINED') throw new Error('already joined');
+            if (state === 'LEFT') throw new Error('cannot rejoin after leave');
+
+            await ensureSchema();
+
+            // Create dedicated client for LISTEN
+            listenerClient = await pool.connect();
+
+            // Subscribe to NOTIFY events
+            await listenerClient.query(`LISTEN ${eventsChannel}`);
+
+            listenerClient.on('notification', (msg) => {
+                try {
+                    const data = JSON.parse(msg.payload);
+
+                    // Check if message is for us or broadcast
+                    if (data.targetServerId === sid || data.targetServerId === '') {
+                        const handler = handlers.get(data.targetServerId) || handlers.get('');
+                        if (handler) {
+                            handler(data.message, data.senderServerId);
+                        }
+                    }
+                } catch (e) {
+                    console.error('📛 Postgres adapter: failed to parse notification', e.message);
+                }
+            });
+
+            state = 'JOINED';
+            console.log(`✅ Postgres adapter: joined as ${sid}`);
+        },
+
+        async leave() {
+            if (state !== 'JOINED') return;
+            state = 'LEFT';
+
+            console.log(`🔴 Postgres adapter: leaving, cleaning up ${ownedClients.size} clients`);
+
+            // Unlisten and release client
+            if (listenerClient) {
+                try {
+                    await listenerClient.query(`UNLISTEN ${eventsChannel}`);
+                    listenerClient.release();
+                } catch (e) {
+                    // Ignore disconnect errors
+                }
+                listenerClient = null;
+            }
+
+            // Remove all owned client mappings
+            if (ownedClients.size > 0) {
+                const ids = Array.from(ownedClients);
+                const placeholders = ids.map((_, i) => `$${i + 1}`).join(',');
+                await pool.query(
+                    `DELETE FROM ${clientsTable} WHERE client_id IN (${placeholders})`,
+                    ids
+                );
+            }
+            ownedClients.clear();
+        },
+
+        lookup: {
+            async add(clientId) {
+                await pool.query(
+                    `INSERT INTO ${clientsTable} (client_id, server_id, updated_at) 
+           VALUES ($1, $2, NOW())
+           ON CONFLICT (client_id) DO UPDATE SET server_id = $2, updated_at = NOW()`,
+                    [clientId, serverId]
+                );
+                ownedClients.add(clientId);
+                console.log(`📍 Postgres adapter: registered client ${clientId} -> ${serverId}`);
+            },
+
+            async read(clientId) {
+                const result = await pool.query(
+                    `SELECT server_id FROM ${clientsTable} WHERE client_id = $1`,
+                    [clientId]
+                );
+                return result.rows[0]?.server_id || null;
+            },
+
+            async remove(clientId) {
+                if (!ownedClients.has(clientId)) {
+                    throw new Error(`not owner: cannot remove client ${clientId}`);
+                }
+                await pool.query(
+                    `DELETE FROM ${clientsTable} WHERE client_id = $1`,
+                    [clientId]
+                );
+                ownedClients.delete(clientId);
+                console.log(`🗑️ Postgres adapter: removed client ${clientId}`);
+            }
+        },
+
+        channels: {
+            async push(targetServerId, message) {
+                const payload = JSON.stringify({
+                    targetServerId: targetServerId || '',
+                    senderServerId: serverId,
+                    message
+                });
+
+                // NOTIFY has 8000 byte limit - for larger payloads, use table
+                if (payload.length > 7500) {
+                    console.warn('⚠️ Postgres adapter: payload too large for NOTIFY, consider using smaller messages');
+                }
+
+                await pool.query(`SELECT pg_notify($1, $2)`, [eventsChannel, payload]);
+
+                if (targetServerId) {
+                    console.log(`📤 Postgres adapter: pushed to server ${targetServerId}`);
+                } else {
+                    console.log(`📢 Postgres adapter: broadcast to all servers`);
+                }
+            },
+
+            async pull(targetServerId, handler) {
+                handlers.set(targetServerId || '', handler);
+
+                // Return unsubscribe function
+                return async () => {
+                    handlers.delete(targetServerId || '');
+                };
+            }
+        }
+    };
+
+    return adapter;
+}
+
+module.exports = { createPostgresAdapter };

package/server/adapters/redis.js

@@ -0,0 +1,154 @@
+/**
+ * Redis Adapter for APE Cluster
+ * 
+ * Uses Redis PUB/SUB for real-time inter-server messaging.
+ * Client mappings stored as simple key-value pairs.
+ */
+
+/**
+ * Create Redis adapter
+ * @param {object} redis - Redis client (node-redis or ioredis)
+ * @param {object} opts
+ * @param {string} opts.serverId - This server's unique ID
+ * @param {string} [opts.namespace='ape'] - Key prefix
+ * @returns {Promise<AdapterInstance>}
+ */
+async function createRedisAdapter(redis, { serverId, namespace = 'ape' }) {
+    if (!serverId) throw new Error('serverId required');
+
+    // State machine: INIT -> JOINED -> LEFT
+    let state = 'INIT';
+    const ownedClients = new Set();
+    const handlers = new Map();
+
+    // Create dedicated pub/sub connections
+    const pub = redis.duplicate();
+    const sub = redis.duplicate();
+
+    // Key helpers
+    const key = {
+        client: (id) => `${namespace}:client:${id}`,
+        channel: (id) => `${namespace}:channel:${id || 'ALL'}`,
+    };
+
+    // Connect pub/sub clients
+    if (typeof pub.connect === 'function' && pub.isOpen === false) {
+        await pub.connect();
+    }
+    if (typeof sub.connect === 'function' && sub.isOpen === false) {
+        await sub.connect();
+    }
+
+    // Handle incoming messages (node-redis v4 style)
+    if (typeof sub.on === 'function') {
+        sub.on('message', (channel, message) => {
+            try {
+                const data = JSON.parse(message);
+                // Find matching handler
+                for (const [pattern, handler] of handlers) {
+                    if (channel === key.channel(pattern) || channel === key.channel('')) {
+                        handler(data, data._senderServerId || serverId);
+                    }
+                }
+            } catch (e) {
+                console.error('📛 Redis adapter: failed to parse message', e.message);
+            }
+        });
+    }
+
+    const adapter = {
+        get serverId() { return serverId; },
+
+        async join(id) {
+            const sid = id || serverId;
+            if (!sid?.trim()) throw new Error('serverId required');
+            if (state === 'JOINED') throw new Error('already joined');
+            if (state === 'LEFT') throw new Error('cannot rejoin after leave');
+
+            // Subscribe to this server's channel + broadcast channel
+            await sub.subscribe(key.channel(sid));
+            await sub.subscribe(key.channel(''));
+
+            state = 'JOINED';
+            console.log(`✅ Redis adapter: joined as ${sid}`);
+        },
+
+        async leave() {
+            if (state !== 'JOINED') return;
+            state = 'LEFT';
+
+            console.log(`🔴 Redis adapter: leaving, cleaning up ${ownedClients.size} clients`);
+
+            // Remove all owned client mappings
+            for (const clientId of ownedClients) {
+                try {
+                    await pub.del(key.client(clientId));
+                } catch (e) {
+                    console.error(`📛 Redis adapter: failed to remove client ${clientId}`, e.message);
+                }
+            }
+            ownedClients.clear();
+
+            // Unsubscribe and disconnect
+            try {
+                await sub.unsubscribe();
+                await pub.quit();
+                await sub.quit();
+            } catch (e) {
+                // Ignore disconnect errors
+            }
+        },
+
+        lookup: {
+            async add(clientId) {
+                await pub.set(key.client(clientId), serverId);
+                ownedClients.add(clientId);
+                console.log(`📍 Redis adapter: registered client ${clientId} -> ${serverId}`);
+            },
+
+            async read(clientId) {
+                const result = await pub.get(key.client(clientId));
+                return result || null;
+            },
+
+            async remove(clientId) {
+                if (!ownedClients.has(clientId)) {
+                    throw new Error(`not owner: cannot remove client ${clientId}`);
+                }
+                await pub.del(key.client(clientId));
+                ownedClients.delete(clientId);
+                console.log(`🗑️ Redis adapter: removed client ${clientId}`);
+            }
+        },
+
+        channels: {
+            async push(targetServerId, message) {
+                const channel = key.channel(targetServerId);
+                const payload = JSON.stringify({
+                    ...message,
+                    _senderServerId: serverId
+                });
+                await pub.publish(channel, payload);
+
+                if (targetServerId) {
+                    console.log(`📤 Redis adapter: pushed to server ${targetServerId}`);
+                } else {
+                    console.log(`📢 Redis adapter: broadcast to all servers`);
+                }
+            },
+
+            async pull(targetServerId, handler) {
+                handlers.set(targetServerId || '', handler);
+
+                // Return unsubscribe function
+                return async () => {
+                    handlers.delete(targetServerId || '');
+                };
+            }
+        }
+    };
+
+    return adapter;
+}
+
+module.exports = { createRedisAdapter };

package/server/adapters/supabase.js

@@ -0,0 +1,199 @@
+/**
+ * Supabase Adapter for APE Cluster
+ * 
+ * Uses Supabase Realtime for inter-server messaging.
+ * Client mappings stored in a dedicated table.
+ * 
+ * Supabase is Postgres under the hood with a simpler Realtime API.
+ */
+
+/**
+ * Create Supabase adapter
+ * @param {SupabaseClient} supabase - Supabase client from @supabase/supabase-js
+ * @param {object} opts
+ * @param {string} opts.serverId - This server's unique ID
+ * @param {string} [opts.namespace='ape'] - Table prefix
+ * @returns {Promise<AdapterInstance>}
+ */
+async function createSupabaseAdapter(supabase, { serverId, namespace = 'ape' }) {
+    if (!serverId) throw new Error('serverId required');
+
+    // State machine: INIT -> JOINED -> LEFT
+    let state = 'INIT';
+    const ownedClients = new Set();
+    const handlers = new Map();
+    let realtimeChannel = null;
+
+    // Table names
+    const clientsTable = `${namespace}_clients`;
+    const eventsTable = `${namespace}_events`;
+
+    // Ensure tables exist (Supabase requires pre-created tables via migrations)
+    // This is a validation check, not creation
+    async function validateTables() {
+        const { error: clientsError } = await supabase
+            .from(clientsTable)
+            .select('client_id')
+            .limit(1);
+
+        if (clientsError && clientsError.code === '42P01') {
+            throw new Error(
+                `Table "${clientsTable}" does not exist. ` +
+                `Create it with: CREATE TABLE ${clientsTable} (client_id TEXT PRIMARY KEY, server_id TEXT NOT NULL);`
+            );
+        }
+    }
+
+    const adapter = {
+        get serverId() { return serverId; },
+
+        async join(id) {
+            const sid = id || serverId;
+            if (!sid?.trim()) throw new Error('serverId required');
+            if (state === 'JOINED') throw new Error('already joined');
+            if (state === 'LEFT') throw new Error('cannot rejoin after leave');
+
+            await validateTables();
+
+            // Subscribe to Realtime channel for this server + broadcast
+            realtimeChannel = supabase
+                .channel(`${namespace}:${sid}`)
+                .on('broadcast', { event: 'message' }, ({ payload }) => {
+                    const { targetServerId, message, senderServerId } = payload;
+
+                    // Check if message is for us or broadcast
+                    if (targetServerId === sid || targetServerId === '') {
+                        const handler = handlers.get(targetServerId) || handlers.get('');
+                        if (handler) {
+                            handler(message, senderServerId);
+                        }
+                    }
+                })
+                .subscribe();
+
+            // Also subscribe to broadcast channel
+            supabase
+                .channel(`${namespace}:ALL`)
+                .on('broadcast', { event: 'message' }, ({ payload }) => {
+                    const { message, senderServerId } = payload;
+                    const handler = handlers.get('');
+                    if (handler) {
+                        handler(message, senderServerId);
+                    }
+                })
+                .subscribe();
+
+            state = 'JOINED';
+            console.log(`✅ Supabase adapter: joined as ${sid}`);
+        },
+
+        async leave() {
+            if (state !== 'JOINED') return;
+            state = 'LEFT';
+
+            console.log(`🔴 Supabase adapter: leaving, cleaning up ${ownedClients.size} clients`);
+
+            // Unsubscribe from channels
+            if (realtimeChannel) {
+                await supabase.removeChannel(realtimeChannel);
+                realtimeChannel = null;
+            }
+
+            // Remove all owned client mappings
+            if (ownedClients.size > 0) {
+                const ids = Array.from(ownedClients);
+                await supabase
+                    .from(clientsTable)
+                    .delete()
+                    .in('client_id', ids);
+            }
+            ownedClients.clear();
+        },
+
+        lookup: {
+            async add(clientId) {
+                const { error } = await supabase
+                    .from(clientsTable)
+                    .upsert({
+                        client_id: clientId,
+                        server_id: serverId,
+                        updated_at: new Date().toISOString()
+                    });
+
+                if (error) throw new Error(`Supabase lookup.add failed: ${error.message}`);
+
+                ownedClients.add(clientId);
+                console.log(`📍 Supabase adapter: registered client ${clientId} -> ${serverId}`);
+            },
+
+            async read(clientId) {
+                const { data, error } = await supabase
+                    .from(clientsTable)
+                    .select('server_id')
+                    .eq('client_id', clientId)
+                    .single();
+
+                if (error && error.code !== 'PGRST116') { // PGRST116 = not found
+                    throw new Error(`Supabase lookup.read failed: ${error.message}`);
+                }
+
+                return data?.server_id || null;
+            },
+
+            async remove(clientId) {
+                if (!ownedClients.has(clientId)) {
+                    throw new Error(`not owner: cannot remove client ${clientId}`);
+                }
+
+                const { error } = await supabase
+                    .from(clientsTable)
+                    .delete()
+                    .eq('client_id', clientId);
+
+                if (error) throw new Error(`Supabase lookup.remove failed: ${error.message}`);
+
+                ownedClients.delete(clientId);
+                console.log(`🗑️ Supabase adapter: removed client ${clientId}`);
+            }
+        },
+
+        channels: {
+            async push(targetServerId, message) {
+                const channelName = targetServerId
+                    ? `${namespace}:${targetServerId}`
+                    : `${namespace}:ALL`;
+
+                const channel = supabase.channel(channelName);
+
+                await channel.send({
+                    type: 'broadcast',
+                    event: 'message',
+                    payload: {
+                        targetServerId: targetServerId || '',
+                        senderServerId: serverId,
+                        message
+                    }
+                });
+
+                if (targetServerId) {
+                    console.log(`📤 Supabase adapter: pushed to server ${targetServerId}`);
+                } else {
+                    console.log(`📢 Supabase adapter: broadcast to all servers`);
+                }
+            },
+
+            async pull(targetServerId, handler) {
+                handlers.set(targetServerId || '', handler);
+
+                // Return unsubscribe function
+                return async () => {
+                    handlers.delete(targetServerId || '');
+                };
+            }
+        }
+    };
+
+    return adapter;
+}
+
+module.exports = { createSupabaseAdapter };