api-ape 2.2.3 → 3.0.0

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

package/server/client.js

@@ -0,0 +1,299 @@
+/**
+ * api-ape Node.js client
+ * 
+ * Mirrors the browser client API exactly - same usage on server and browser.
+ * 
+ * Usage (identical to browser):
+ *   import api from 'api-ape'
+ *   
+ *   api.message({ user: 'Bob', text: 'Hello!' })
+ *   api.on('message', (data) => console.log(data))
+ *   api.onConnectionChange((state) => console.log(state))
+ * 
+ * Configuration:
+ *   Set APE_SERVER environment variable to the WebSocket URL:
+ *   APE_SERVER=ws://other-server:3000/api/ape node app.js
+ * 
+ *   Or call api.connect(url) before first use
+ */
+
+const jss = require('../utils/jss')
+const { WebSocket: WsPolyfill } = require('./lib/ws')
+
+// Use native WebSocket if available (Node 22+), otherwise use polyfill
+const WebSocket = globalThis.WebSocket || WsPolyfill
+
+// Connection state enum
+const ConnectionState = {
+    Disconnected: 'disconnected',
+    Connecting: 'connecting',
+    Connected: 'connected',
+    Closing: 'closing'
+}
+
+// Shared state (mirrors browser client)
+let ws = null
+let connectionState = ConnectionState.Disconnected
+const connectionChangeListeners = []
+const waitingOn = {}
+const receiverArray = []
+const ofTypesOb = {}
+let queryCounter = 0
+let bufferedCalls = []
+let bufferedReceivers = []
+let ready = false
+let reconnectEnabled = true
+let reconnectTimer = null
+let serverUrl = process.env.APE_SERVER || null
+
+const joinKey = '/'
+const connectTimeout = 5000
+const totalRequestTimeout = 10000
+
+function notifyConnectionChange(newState) {
+    if (connectionState !== newState) {
+        connectionState = newState
+        connectionChangeListeners.forEach(fn => fn(newState))
+    }
+}
+
+function generateQueryId() {
+    return `q${Date.now().toString(36)}_${(queryCounter++).toString(36)}`
+}
+
+function connect(url) {
+    if (url) serverUrl = url
+
+    if (!serverUrl) {
+        console.warn('🦍 api-ape: No server URL configured. Set APE_SERVER env or call api.connect(url)')
+        return
+    }
+
+    if (ws && ws.readyState !== WebSocket.CLOSED) {
+        return
+    }
+
+    notifyConnectionChange(ConnectionState.Connecting)
+
+    ws = new WebSocket(serverUrl)
+
+    ws.onopen = () => {
+        ready = true
+        notifyConnectionChange(ConnectionState.Connected)
+
+        // Flush buffered receivers
+        bufferedReceivers.forEach(({ type, handler }) => {
+            setOnReceiver(type, handler)
+        })
+        bufferedReceivers = []
+
+        // Flush buffered calls
+        bufferedCalls.forEach(({ type, data, resolve, reject, createdAt, timer }) => {
+            clearTimeout(timer)
+            send(type, data, createdAt).then(resolve).catch(reject)
+        })
+        bufferedCalls = []
+    }
+
+    ws.onmessage = (event) => {
+        const msg = jss.parse(typeof event.data === 'string' ? event.data : event.data.toString())
+        const { err, type, queryId, data } = msg
+
+        // Response to a query
+        if (queryId && waitingOn[queryId]) {
+            waitingOn[queryId](err, data)
+            delete waitingOn[queryId]
+            return
+        }
+
+        // Broadcast message
+        if (ofTypesOb[type]) {
+            ofTypesOb[type].forEach(handler => handler({ err, type, data }))
+        }
+        receiverArray.forEach(handler => handler({ err, type, data }))
+    }
+
+    ws.onerror = (err) => {
+        console.error('🦍 api-ape client error:', err.message || err)
+    }
+
+    ws.onclose = () => {
+        ready = false
+        ws = null
+        notifyConnectionChange(ConnectionState.Disconnected)
+
+        if (reconnectEnabled && serverUrl) {
+            reconnectTimer = setTimeout(() => connect(), 1000)
+        }
+    }
+}
+
+function send(type, data, createdAt = Date.now()) {
+    const queryId = generateQueryId()
+
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            delete waitingOn[queryId]
+            reject(new Error(`Request timeout: ${type}`))
+        }, totalRequestTimeout)
+
+        waitingOn[queryId] = (err, result) => {
+            clearTimeout(timer)
+            if (err) {
+                reject(typeof err === 'string' ? new Error(err) : err)
+            } else {
+                resolve(result)
+            }
+        }
+
+        const message = jss.stringify({ type, data, queryId, createdAt })
+        ws.send(message)
+    })
+}
+
+function queueOrSend(type, data) {
+    if (ready && ws && ws.readyState === WebSocket.OPEN) {
+        return send(type, data)
+    }
+
+    // Queue the message
+    return new Promise((resolve, reject) => {
+        const createdAt = Date.now()
+        const timer = setTimeout(() => {
+            const idx = bufferedCalls.findIndex(m => m.createdAt === createdAt)
+            if (idx > -1) bufferedCalls.splice(idx, 1)
+            reject(new Error(`Connection timeout: ${type}`))
+        }, connectTimeout)
+
+        bufferedCalls.push({ type, data, resolve, reject, createdAt, timer })
+
+        // Ensure we're connecting
+        if (connectionState === ConnectionState.Disconnected && serverUrl) {
+            connect()
+        }
+    })
+}
+
+/**
+ * Subscribe to broadcasts from the server (same as browser api.on)
+ */
+function on(type, handler) {
+    if (typeof type === 'function') {
+        handler = type
+        type = null
+    }
+
+    if (ready) {
+        setOnReceiver(type, handler)
+    } else {
+        bufferedReceivers.push({ type, handler })
+        if (serverUrl) connect()
+    }
+}
+
+function setOnReceiver(type, handler) {
+    if (type === null) {
+        receiverArray.push(handler)
+    } else {
+        if (!ofTypesOb[type]) ofTypesOb[type] = []
+        ofTypesOb[type].push(handler)
+    }
+}
+
+/**
+ * Subscribe to connection state changes (same as browser api.onConnectionChange)
+ */
+function onConnectionChange(handler) {
+    connectionChangeListeners.push(handler)
+    handler(connectionState)
+    return () => {
+        const idx = connectionChangeListeners.indexOf(handler)
+        if (idx > -1) connectionChangeListeners.splice(idx, 1)
+    }
+}
+
+/**
+ * Create the sender proxy (mirrors browser client exactly)
+ */
+const handler = {
+    get(target, prop) {
+        // Reserved properties - same as browser
+        if (prop === 'on') return on
+        if (prop === 'onConnectionChange') return onConnectionChange
+        if (prop === 'transport') return ready ? 'websocket' : null
+        if (prop === 'connect') return connect
+        if (prop === 'close') return close
+        if (prop === 'then' || prop === 'catch') return undefined // Not a Promise
+
+        // Return a function that either calls directly or buffers
+        const wrapperFn = function (a, b) {
+            let path = joinKey + prop, body
+            if (arguments.length === 2) {
+                path += a
+                body = b
+            } else {
+                body = a
+            }
+            return queueOrSend(path, body)
+        }
+        return new Proxy(wrapperFn, handler)
+    }
+}
+
+function close() {
+    reconnectEnabled = false
+    if (reconnectTimer) {
+        clearTimeout(reconnectTimer)
+        reconnectTimer = null
+    }
+    if (ws) {
+        notifyConnectionChange(ConnectionState.Closing)
+        ws.close()
+    }
+}
+
+// Create the proxy (same interface as browser senderProxy)
+const api = new Proxy({}, handler)
+
+// Define properties on the proxy (same as browser)
+Object.defineProperty(api, 'on', {
+    value: on,
+    writable: false,
+    enumerable: false,
+    configurable: false
+})
+
+Object.defineProperty(api, 'onConnectionChange', {
+    value: onConnectionChange,
+    writable: false,
+    enumerable: false,
+    configurable: false
+})
+
+Object.defineProperty(api, 'connect', {
+    value: connect,
+    writable: false,
+    enumerable: false,
+    configurable: false
+})
+
+Object.defineProperty(api, 'close', {
+    value: close,
+    writable: false,
+    enumerable: false,
+    configurable: false
+})
+
+// Auto-connect if APE_SERVER is set
+if (serverUrl) {
+    connect()
+}
+
+// Export the same interface as browser
+module.exports = api
+module.exports.default = api
+module.exports.on = on
+module.exports.onConnectionChange = onConnectionChange
+module.exports.connect = connect
+module.exports.close = close
+module.exports.ConnectionState = ConnectionState

package/server/index.js

@@ -1,14 +1,37 @@
 /**
  * api-ape server entry point
- * Exports the main ape function and broadcast utilities
+ * 
+ * V3 Usage (100% identical on browser and server):
+ *   import api from 'api-ape'
+ *   api.hello('World')  // Works same on browser AND server
+ *   api.on('message', (data) => console.log(data))
+ * 
+ * Server Setup:
+ *   import api, { ape } from 'api-ape'
+ *   ape(server, { where: 'api' })  // Start your server
+ *   
+ *   // Connect to another server (set APE_SERVER env or call api.connect)
+ *   api.connect('ws://other-server:3000/api/ape')
+ *   api.hello('World')
+ * 
+ * Supports both CommonJS and ES Modules
  */
 
 const ape = require('./lib/main')
-const { broadcast, online, getClients } = require('./lib/broadcast')
+const { broadcast, clients } = require('./lib/broadcast')
+const api = require('./client')
 
-// Attach broadcast utilities to the main function for clean exports
+// Attach broadcast utilities to the ape function
 ape.broadcast = broadcast
-ape.online = online
-ape.getClients = getClients
+ape.clients = clients
+
+// Default export: api client (same interface as browser)
+module.exports = api
+
+// Named exports
+module.exports.ape = ape
+module.exports.api = api
+
+
+
 
-module.exports = ape