api-ape 2.2.2 → 2.3.0

package/server/adapters/README.md

@@ -0,0 +1,275 @@
+# APE Cluster Adapters
+
+Connect multiple api-ape server instances via a shared database for horizontal scaling.
+
+## Quick Start
+
+```js
+import ape from 'api-ape/server';
+import { createClient } from 'redis';
+
+// Connect to your database
+const redis = createClient();
+await redis.connect();
+
+// Join the cluster — APE creates its own namespace
+ape.joinVia(redis);
+```
+
+That's it. APE will:
+- Detect the database type (Redis, MongoDB, PostgreSQL)
+- Create namespaced keys/tables (`ape:*` or `ape_*`)
+- Route messages between servers automatically
+
+---
+
+## How It Works
+
+```
+┌─────────────┐                    ┌─────────────┐
+│  Server A   │                    │  Server B   │
+│  client-1   │                    │  client-2   │
+└──────┬──────┘                    └──────▲──────┘
+       │                                  │
+       │ 1. sendTo("client-2")            │
+       │    → lookup.read("client-2")     │
+       │    → returns "srv-B"             │
+       │                                  │
+       │ 2. channels.push("srv-B", msg)   │
+       └──────────┬───────────────────────┘
+                  │
+           ┌──────▼──────┐
+           │   Database  │
+           │  (message   │
+           │    bus)     │
+           └─────────────┘
+```
+
+Messages are routed **directly** to the server hosting the client. No broadcast spam.
+
+---
+
+## Adapter Interface
+
+All adapters implement this interface:
+
+```ts
+interface AdapterInstance {
+  // Lifecycle
+  join(serverId: string): Promise<void>;
+  leave(): Promise<void>;
+  
+  // Client → Server mapping
+  lookup: {
+    add(clientId: string): Promise<void>;
+    read(clientId: string): Promise<string | null>;
+    remove(clientId: string): Promise<void>;
+  };
+  
+  // Inter-server messaging
+  channels: {
+    push(serverId: string, message: object): Promise<void>;
+    pull(serverId: string, handler: (msg, senderServerId) => void): Promise<() => void>;
+  };
+}
+```
+
+---
+
+## Supported Databases
+
+### Redis (Recommended)
+
+Best performance. Uses PUB/SUB for real-time messaging.
+
+```js
+import { createClient } from 'redis';
+
+const redis = createClient({ url: 'redis://localhost:6379' });
+await redis.connect();
+
+ape.joinVia(redis);
+```
+
+**Keys created:**
+- `ape:client:{clientId}` — client→server mapping
+- `ape:channel:{serverId}` — PUB/SUB channel
+- `ape:channel:ALL` — broadcast channel
+
+---
+
+### MongoDB
+
+Uses Change Streams for real-time push (requires replica set).
+
+```js
+import { MongoClient } from 'mongodb';
+
+const mongo = new MongoClient('mongodb://localhost:27017');
+await mongo.connect();
+
+ape.joinVia(mongo);
+```
+
+**Database/Collections created:**
+- Database: `ape_cluster`
+- Collection: `clients` — client→server mapping
+- Collection: `events` — message bus (change streams)
+
+---
+
+### PostgreSQL
+
+Uses LISTEN/NOTIFY for real-time messaging.
+
+```js
+import pg from 'pg';
+
+const pool = new pg.Pool({ connectionString: 'postgres://localhost/mydb' });
+
+ape.joinVia(pool);
+```
+
+**Database/Tables created:**
+- Database: `ape_cluster` (or uses existing)
+- Table: `clients` — client→server mapping
+- Channel: `ape_events` — LISTEN/NOTIFY channel
+
+---
+
+### Supabase
+
+Uses Supabase Realtime for push messaging. Simple setup if you're already using Supabase.
+
+```js
+import { createClient } from '@supabase/supabase-js';
+
+const supabase = createClient(SUPABASE_URL, SUPABASE_KEY);
+
+ape.joinVia(supabase);
+```
+
+**Requirements:**
+- Create table: `ape_clients (client_id TEXT PRIMARY KEY, server_id TEXT, updated_at TIMESTAMP)`
+- Enable Realtime on your project
+
+---
+
+### Firebase Realtime Database
+
+Native real-time push. Perfect for serverless and edge deployments.
+
+```js
+import { initializeApp } from 'firebase-admin/app';
+import { getDatabase } from 'firebase-admin/database';
+
+const app = initializeApp();
+const database = getDatabase(app);
+
+ape.joinVia(database);
+```
+
+**Paths created:**
+- `/ape/clients/{clientId}` — client→server mapping
+- `/ape/channels/{serverId}` — message channels
+- `/ape/channels/ALL` — broadcast channel
+
+---
+
+## Custom Adapters
+
+For other databases or testing, pass your own adapter:
+
+```js
+ape.joinVia({
+  async join(serverId) {
+    // Subscribe to channels, register server
+  },
+  
+  async leave() {
+    // Cleanup subscriptions, remove client mappings
+  },
+  
+  lookup: {
+    async add(clientId) {
+      // Map clientId → this serverId
+    },
+    async read(clientId) {
+      // Return serverId or null
+    },
+    async remove(clientId) {
+      // Delete mapping (only if we own it)
+    }
+  },
+  
+  channels: {
+    async push(serverId, message) {
+      // Send to serverId's channel ("" = broadcast)
+    },
+    async pull(serverId, handler) {
+      // Subscribe to serverId's channel
+      // handler(message, senderServerId)
+      return async () => { /* unsubscribe */ };
+    }
+  }
+});
+```
+
+---
+
+## Options
+
+```js
+ape.joinVia(redis, {
+  namespace: 'myapp',     // Default: 'ape'
+  serverId: 'srv-custom'  // Default: auto-generated UUID
+});
+```
+
+---
+
+## Lifecycle
+
+| Event | Adapter Action |
+|-------|---------------|
+| Server starts | `join(serverId)` — subscribe to channels |
+| Client connects | `lookup.add(clientId)` — register mapping |
+| Client disconnects | `lookup.remove(clientId)` — delete mapping |
+| Server shutdown | `leave()` — cleanup all owned mappings |
+
+### Graceful Shutdown
+
+```js
+process.on('SIGINT', async () => {
+  await ape.leaveCluster();
+  process.exit(0);
+});
+```
+
+---
+
+## Message Format
+
+Messages sent via `channels.push`:
+
+```js
+// Direct message
+{
+  destClientId: 'user-123',
+  type: 'chat',
+  data: { text: 'Hello!' }
+}
+
+// Broadcast
+{
+  type: 'system',
+  data: { notice: 'Maintenance in 5 min' }
+}
+
+// Broadcast excluding sender
+{
+  type: 'chat',
+  data: { text: 'Hello everyone!' },
+  excludeClientId: 'user-456'
+}
+```

package/server/adapters/firebase.js

@@ -0,0 +1,172 @@
+/**
+ * Firebase Realtime Database Adapter for APE Cluster
+ * 
+ * Uses Firebase RTDB for real-time inter-server messaging.
+ * Perfect for serverless and edge deployments.
+ * 
+ * Firebase provides native real-time push via onValue/onChildAdded listeners.
+ */
+
+/**
+ * Create Firebase RTDB adapter
+ * @param {Database} database - Firebase Realtime Database instance from firebase-admin or firebase
+ * @param {object} opts
+ * @param {string} opts.serverId - This server's unique ID
+ * @param {string} [opts.namespace='ape'] - Path prefix
+ * @returns {Promise<AdapterInstance>}
+ */
+async function createFirebaseAdapter(database, { 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();
+    const unsubscribers = [];
+
+    // Firebase path helpers
+    const paths = {
+        clients: () => `${namespace}/clients`,
+        client: (id) => `${namespace}/clients/${id}`,
+        channel: (sid) => `${namespace}/channels/${sid || 'ALL'}`,
+    };
+
+    // Get ref helper (works with both firebase-admin and firebase client SDK)
+    const ref = (path) => {
+        // firebase-admin style
+        if (typeof database.ref === 'function') {
+            return database.ref(path);
+        }
+        // firebase client SDK style (modular)
+        if (typeof database === 'object' && database._checkNotDeleted) {
+            const { ref: getRef } = require('firebase/database');
+            return getRef(database, path);
+        }
+        throw new Error('Unsupported Firebase Database instance');
+    };
+
+    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');
+
+            // Listen to this server's channel
+            const serverChannelRef = ref(paths.channel(sid));
+            const serverListener = serverChannelRef.on('child_added', (snapshot) => {
+                const data = snapshot.val();
+                if (data && data.senderServerId !== sid) {
+                    const handler = handlers.get(sid) || handlers.get('');
+                    if (handler) {
+                        handler(data.message, data.senderServerId);
+                    }
+                }
+                // Clean up processed message
+                snapshot.ref.remove();
+            });
+            unsubscribers.push(() => serverChannelRef.off('child_added', serverListener));
+
+            // Listen to broadcast channel
+            const broadcastRef = ref(paths.channel(''));
+            const broadcastListener = broadcastRef.on('child_added', (snapshot) => {
+                const data = snapshot.val();
+                if (data && data.senderServerId !== sid) {
+                    const handler = handlers.get('');
+                    if (handler) {
+                        handler(data.message, data.senderServerId);
+                    }
+                }
+                // Clean up processed message after short delay (let other servers read it)
+                setTimeout(() => snapshot.ref.remove(), 5000);
+            });
+            unsubscribers.push(() => broadcastRef.off('child_added', broadcastListener));
+
+            state = 'JOINED';
+            console.log(`✅ Firebase adapter: joined as ${sid}`);
+        },
+
+        async leave() {
+            if (state !== 'JOINED') return;
+            state = 'LEFT';
+
+            console.log(`🔴 Firebase adapter: leaving, cleaning up ${ownedClients.size} clients`);
+
+            // Unsubscribe all listeners
+            for (const unsub of unsubscribers) {
+                unsub();
+            }
+            unsubscribers.length = 0;
+
+            // Remove all owned client mappings
+            for (const clientId of ownedClients) {
+                try {
+                    await ref(paths.client(clientId)).remove();
+                } catch (e) {
+                    console.error(`Firebase: failed to remove client ${clientId}`, e.message);
+                }
+            }
+            ownedClients.clear();
+        },
+
+        lookup: {
+            async add(clientId) {
+                await ref(paths.client(clientId)).set({
+                    serverId,
+                    updatedAt: Date.now()
+                });
+                ownedClients.add(clientId);
+                console.log(`📍 Firebase adapter: registered client ${clientId} -> ${serverId}`);
+            },
+
+            async read(clientId) {
+                const snapshot = await ref(paths.client(clientId)).once('value');
+                const data = snapshot.val();
+                return data?.serverId || null;
+            },
+
+            async remove(clientId) {
+                if (!ownedClients.has(clientId)) {
+                    throw new Error(`not owner: cannot remove client ${clientId}`);
+                }
+                await ref(paths.client(clientId)).remove();
+                ownedClients.delete(clientId);
+                console.log(`🗑️ Firebase adapter: removed client ${clientId}`);
+            }
+        },
+
+        channels: {
+            async push(targetServerId, message) {
+                const channelRef = ref(paths.channel(targetServerId));
+
+                await channelRef.push({
+                    targetServerId: targetServerId || '',
+                    senderServerId: serverId,
+                    message,
+                    timestamp: Date.now()
+                });
+
+                if (targetServerId) {
+                    console.log(`📤 Firebase adapter: pushed to server ${targetServerId}`);
+                } else {
+                    console.log(`📢 Firebase 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 = { createFirebaseAdapter };

package/server/adapters/index.js

@@ -0,0 +1,144 @@
+/**
+ * APE Cluster Adapters
+ * 
+ * Detect database type and create appropriate adapter for multi-server coordination.
+ * 
+ * Usage:
+ *   const adapter = await createAdapter(redisClient);
+ *   const adapter = await createAdapter(mongoClient);
+ *   const adapter = await createAdapter(pgPool);
+ *   const adapter = await createAdapter(supabaseClient);
+ *   const adapter = await createAdapter(firebaseDatabase);
+ *   const adapter = await createAdapter(customAdapter);
+ */
+
+const { randomBytes } = require('crypto');
+
+// Generate short unique server ID
+const B = b => [...b].map(v => '0123456789ABCDEFGHJKMNPQRSTVWXYZ'[v & 31]).join('');
+const uuid = () => B(randomBytes(8));
+
+/**
+ * Detect database type from client object
+ * @param {object} client - Database client
+ * @returns {'redis'|'mongo'|'postgres'|'supabase'|'firebase'|'custom'|null}
+ */
+function detectClientType(client) {
+    if (!client) return null;
+
+    // Custom adapter - has our interface methods
+    if (typeof client.join === 'function' &&
+        typeof client.leave === 'function' &&
+        client.lookup && client.channels) {
+        return 'custom';
+    }
+
+    // Redis (node-redis or ioredis)
+    if (typeof client.duplicate === 'function' &&
+        (typeof client.publish === 'function' || typeof client.PUBLISH === 'function')) {
+        return 'redis';
+    }
+
+    // MongoDB
+    if (typeof client.db === 'function' && client.constructor?.name === 'MongoClient') {
+        return 'mongo';
+    }
+
+    // PostgreSQL (pg.Pool)
+    if (typeof client.query === 'function' && typeof client.connect === 'function') {
+        return 'postgres';
+    }
+
+    // Supabase (has .from() for tables and .channel() for realtime)
+    if (typeof client.from === 'function' && typeof client.channel === 'function') {
+        return 'supabase';
+    }
+
+    // Firebase Realtime Database (has .ref() method)
+    if (typeof client.ref === 'function' &&
+        (typeof client.goOnline === 'function' || client.app)) {
+        return 'firebase';
+    }
+
+    return null;
+}
+
+/**
+ * Create adapter from database client
+ * @param {object} client - Database client or custom adapter
+ * @param {object} opts - Options
+ * @param {string} [opts.namespace='ape'] - Key/table prefix
+ * @param {string} [opts.serverId] - Server ID (auto-generated if not provided)
+ * @returns {Promise<AdapterInstance>}
+ */
+async function createAdapter(client, opts = {}) {
+    const type = detectClientType(client);
+    const serverId = opts.serverId || uuid();
+    const namespace = opts.namespace || 'ape';
+
+    if (!type) {
+        throw new Error(
+            'Unable to detect database type. Supported: Redis, MongoDB, PostgreSQL, Supabase, Firebase, or custom adapter.'
+        );
+    }
+
+    console.log(`🔌 APE: Detected ${type} adapter (serverId: ${serverId})`);
+
+    switch (type) {
+        case 'custom':
+            return wrapCustomAdapter(client, serverId);
+
+        case 'redis':
+            const { createRedisAdapter } = require('./redis');
+            return createRedisAdapter(client, { serverId, namespace });
+
+        case 'mongo':
+            const { createMongoAdapter } = require('./mongo');
+            return createMongoAdapter(client, { serverId, namespace });
+
+        case 'postgres':
+            const { createPostgresAdapter } = require('./postgres');
+            return createPostgresAdapter(client, { serverId, namespace });
+
+        case 'supabase':
+            const { createSupabaseAdapter } = require('./supabase');
+            return createSupabaseAdapter(client, { serverId, namespace });
+
+        case 'firebase':
+            const { createFirebaseAdapter } = require('./firebase');
+            return createFirebaseAdapter(client, { serverId, namespace });
+
+        default:
+            throw new Error(`Unknown adapter type: ${type}`);
+    }
+}
+
+/**
+ * Attach serverId to custom adapter
+ * @param {object} adapter - Custom adapter object  
+ * @param {string} serverId - Server ID
+ * @returns {AdapterInstance}
+ */
+function wrapCustomAdapter(adapter, serverId) {
+    // Wrap to ensure consistent interface and default serverId
+    return {
+        get serverId() { return serverId; },
+        join: (id) => adapter.join(id || serverId),
+        leave: () => adapter.leave(),
+        lookup: {
+            add: (clientId) => adapter.lookup.add(clientId),
+            read: (clientId) => adapter.lookup.read(clientId),
+            remove: (clientId) => adapter.lookup.remove(clientId)
+        },
+        channels: {
+            push: (targetServerId, message) => adapter.channels.push(targetServerId, message),
+            pull: (targetServerId, handler) => adapter.channels.pull(targetServerId, handler)
+        }
+    };
+}
+
+module.exports = {
+    createAdapter,
+    detectClientType,
+    uuid
+};