api-ape 2.2.2 → 2.3.0

package/index.d.ts

@@ -50,7 +50,7 @@ export interface ControllerContext {
         os: { name?: string; version?: string }
         device: { type?: string; vendor?: string; model?: string }
     }
-    /** Custom embedded values from onConnent */
+    /** Custom embedded values from onConnect */
     [key: string]: any
 }
 
@@ -63,7 +63,7 @@ export type ControllerFunction<T = any, R = any> = (
 ) => R | Promise<R>
 
 /**
- * Send function provided to onConnent
+ * Send function provided to onConnect
  */
 export type SendFunction = {
     (type: string, data: any): void
@@ -76,7 +76,7 @@ export type SendFunction = {
 export type AfterHook = (err: Error | null, result: any) => void
 
 /**
- * Connection lifecycle hooks returned from onConnent
+ * Connection lifecycle hooks returned from onConnect
  */
 export interface ConnectionHandlers {
     /** Values to embed into controller context */
@@ -88,11 +88,11 @@ export interface ConnectionHandlers {
     /** Called on error */
     onError?: (errorString: string) => void
     /** Called when client disconnects */
-    onDisconnent?: () => void
+    onDisconnect?: () => void
 }
 
 /**
- * onConnent callback signature
+ * onConnect callback signature
  */
 export type OnConnectCallback = (
     socket: ApeWebSocket,
@@ -107,7 +107,114 @@ export interface ApeServerOptions {
     /** Directory containing controller files */
     where: string
     /** Connection lifecycle hook */
-    onConnent?: OnConnectCallback
+    onConnect?: OnConnectCallback
+}
+
+// =============================================================================
+// 🌲 FOREST - DISTRIBUTED MESH TYPES
+// =============================================================================
+
+/**
+ * Supported database client types for Forest adapters
+ */
+export type ForestDatabaseClient =
+    | RedisClient
+    | MongoClient
+    | PostgresPool
+    | SupabaseClient
+    | FirebaseDatabase
+    | ForestCustomAdapter
+
+/** Redis client (node-redis or ioredis) */
+export interface RedisClient {
+    duplicate(): RedisClient
+    publish(channel: string, message: string): Promise<number>
+    subscribe(channel: string): Promise<void>
+    on(event: string, handler: (...args: any[]) => void): void
+}
+
+/** MongoDB client */
+export interface MongoClient {
+    db(name?: string): any
+}
+
+/** PostgreSQL pool (pg) */
+export interface PostgresPool {
+    query(text: string, values?: any[]): Promise<any>
+    connect(): Promise<any>
+}
+
+/** Supabase client */
+export interface SupabaseClient {
+    from(table: string): any
+    channel(name: string): any
+    removeChannel(channel: any): Promise<void>
+}
+
+/** Firebase Realtime Database */
+export interface FirebaseDatabase {
+    ref(path: string): any
+    goOnline?(): void
+    app?: any
+}
+
+/**
+ * Forest adapter instance interface
+ */
+export interface ForestAdapterInstance {
+    /** This server's unique ID */
+    readonly serverId: string
+
+    /** Join the distributed mesh */
+    join(serverId?: string): Promise<void>
+
+    /** Leave the mesh and cleanup */
+    leave(): Promise<void>
+
+    /** Client-to-server lookup operations */
+    lookup: {
+        /** Register a client on this server */
+        add(clientId: string): Promise<void>
+        /** Find which server owns a client */
+        read(clientId: string): Promise<string | null>
+        /** Remove a client mapping (must own it) */
+        remove(clientId: string): Promise<void>
+    }
+
+    /** Inter-server channel operations */
+    channels: {
+        /** Push message to a server's channel (empty string = broadcast) */
+        push(serverId: string, message: any): Promise<void>
+        /** Subscribe to a server's channel, returns unsubscribe function */
+        pull(serverId: string, handler: (message: any, senderServerId: string) => void): Promise<() => Promise<void>>
+    }
+}
+
+/**
+ * Custom adapter interface for implementing your own Forest adapter
+ */
+export interface ForestCustomAdapter {
+    join(serverId: string): Promise<void>
+    leave(): Promise<void>
+    lookup: {
+        add(clientId: string): Promise<void>
+        read(clientId: string): Promise<string | null>
+        remove(clientId: string): Promise<void>
+    }
+    channels: {
+        push(serverId: string, message: any): Promise<void>
+        pull(serverId: string, handler: (message: any, senderServerId: string) => void): Promise<() => Promise<void>>
+    }
+}
+
+/**
+ * Options for joinVia()
+ */
+export interface ForestOptions {
+    /** Prefix for keys/tables (default: 'ape') */
+    namespace?: string
+    /** Custom server ID (default: auto-generated) */
+    serverId?: string
 }
 
 /**
@@ -118,18 +225,56 @@ declare function ape(server: HttpServer, options: ApeServerOptions): void
 declare namespace ape {
     /** Broadcast to all connected clients */
     export function broadcast(type: string, data: any, excludeClientId?: string): void
-    /** Get count of connected clients */
-    export function online(): number
-    /** Get all connected client clientIds */
-    export function getClients(): string[]
+
+    /**
+     * Read-only Map of connected clients
+     * Each ClientWrapper provides: clientId, sessionId, embed, agent, sendTo(type, data)
+     */
+    export const clients: ReadonlyMap<string, ClientWrapper>
+
+    // =========================================================================
+    // 🌲 FOREST - DISTRIBUTED MESH
+    // =========================================================================
+
+    /**
+     * Join the distributed mesh for multi-server coordination.
+     * Pass any supported database client - APE auto-detects the type.
+     * 
+     * @example
+     * // Redis
+     * ape.joinVia(redisClient);
+     * 
+     * // With options
+     * ape.joinVia(mongoClient, { namespace: 'myapp', serverId: 'srv-1' });
+     * 
+     * // Custom adapter
+     * ape.joinVia({ join, leave, lookup, channels });
+     */
+    export function joinVia(client: ForestDatabaseClient, options?: ForestOptions): Promise<ForestAdapterInstance>
+
+    /**
+     * Leave the distributed mesh gracefully.
+     * Removes all client mappings and unsubscribes from channels.
+     */
+    export function leaveCluster(): Promise<void>
+
+    /**
+     * Current Forest adapter instance (null if not joined)
+     */
+    export const cluster: ForestAdapterInstance | null
+
+    /**
+     * This server's ID in the cluster (null if not joined)
+     */
+    export const serverId: string | null
 
     // Browser client methods (available when imported in browser context)
     /** Subscribe to broadcasts from the server */
     export function on<T = any>(type: string, handler: (message: { err?: Error; type: string; data: T }) => void): void
     /** Subscribe to connection state changes. Returns unsubscribe function. */
     export function onConnectionChange(handler: (state: 'offline' | 'walled' | 'disconnected' | 'connecting' | 'connected') => void): () => void
-    /** Get current transport type */
-    export function getTransport(): 'websocket' | 'polling' | null
+    /** Current transport type (read-only) */
+    export const transport: 'websocket' | 'polling' | null
 
     /** Call any server function dynamically (browser only) */
     export function message<T = any, R = any>(data?: T): Promise<R>
@@ -161,8 +306,8 @@ export interface ApeBrowserClient extends ApeSender {
     /** Subscribe to connection state changes. Returns unsubscribe function. */
     onConnectionChange(handler: (state: ConnectionState) => void): () => void
 
-    /** Get current transport type ('websocket' | 'polling' | null) */
-    getTransport(): TransportType | null
+    /** Current transport type (read-only) */
+    readonly transport: TransportType | null
 }
 
 // =============================================================================
@@ -221,11 +366,11 @@ export type SetOnReceiver = {
  */
 export interface ApeClient {
     sender: ApeSender
-    setOnReciver: SetOnReceiver
+    setOnReceiver: SetOnReceiver
     /** Subscribe to connection state changes. Returns unsubscribe function. */
     onConnectionChange: (handler: (state: ConnectionState) => void) => () => void
-    /** Get current transport type ('websocket' | 'polling' | null) */
-    getTransport: () => TransportType | null
+    /** Current transport type (read-only) */
+    readonly transport: TransportType | null
 }
 
 /**
@@ -256,5 +401,24 @@ export { connectSocket }
 // =============================================================================
 
 export declare const broadcast: (type: string, data: any) => void
-export declare const online: () => number
-export declare const getClients: () => string[]
+export declare const clients: ReadonlyMap<string, ClientWrapper>
+
+/**
+ * Client wrapper providing client info and sendTo function
+ */
+export interface ClientWrapper {
+    /** Unique client identifier */
+    readonly clientId: string
+    /** Session ID from cookie (set by outer framework) */
+    readonly sessionId: string | null
+    /** Embedded values from onConnect */
+    readonly embed: Record<string, any>
+    /** Parsed user-agent info */
+    readonly agent: {
+        browser: { name?: string; version?: string }
+        os: { name?: string; version?: string }
+        device: { type?: string; vendor?: string; model?: string }
+    }
+    /** Send a message to this specific client */
+    sendTo(type: string, data: any): void
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api-ape",
-  "version": "2.2.2",
+  "version": "2.3.0",
   "description": "Remote Procedure Events (RPE) - A lightweight WebSocket framework for building real-time APIs. Call server functions from the browser like local methods with automatic reconnection, HTTP streaming fallback, and extended JSON encoding.",
   "main": "index.js",
   "browser": "./client/index.js",
@@ -33,7 +33,7 @@
     "demo:nextjs": "cd example/NextJs && docker-compose up --build",
     "demo:vite": "cd example/Vite && npm install && npm run dev",
     "demo:bun": "cd example/Bun && npm install && npm start",
-    "publish": "bash scripts/publish.sh"
+    "release": "bash scripts/publish.sh"
   },
   "repository": {
     "type": "git",

package/server/README.md

@@ -23,6 +23,14 @@ server/
 │       └── adapters/ # Runtime-specific adapters
 │           ├── bun.js  # Bun native WebSocket
 │           └── deno.js # Deno native WebSocket
+├── adapters/         # 🌲 Forest - Distributed mesh adapters
+│   ├── index.js      # Auto-detection & factory
+│   ├── redis.js      # Redis PUB/SUB adapter
+│   ├── mongo.js      # MongoDB Change Streams adapter
+│   ├── postgres.js   # PostgreSQL LISTEN/NOTIFY adapter
+│   ├── supabase.js   # Supabase Realtime adapter
+│   ├── firebase.js   # Firebase RTDB adapter
+│   └── README.md     # Adapter documentation
 ├── socket/
 │   ├── receive.js    # Incoming message handler
 │   └── send.js       # Outgoing message handler
@@ -47,9 +55,9 @@ const server = createServer()
 
 ape(server, {
   where: 'api',        // Controller directory
-  onConnent: (socket, req, send) => ({
+  onConnect: (socket, req, send) => ({
     embed: { userId: req.session?.userId },
-    onDisconnent: () => console.log('Client left')
+    onDisconnect: () => console.log('Client left')
   })
 })
 
@@ -63,7 +71,7 @@ server.listen(3000)
 | Option | Type | Description |
 |--------|------|-------------|
 | `where` | `string` | Directory containing controller files |
-| `onConnent` | `function` | Connection lifecycle hook |
+| `onConnect` | `function` | Connection lifecycle hook |
 | `fileTransferOptions` | `object` | Binary transfer settings (see below) |
 
 ### File Transfer Options
@@ -95,13 +103,13 @@ ape(app, {
 ### Connection Lifecycle Hooks
 
 ```js
-onConnent(socket, req, send) {
+onConnect(socket, req, send) {
   return {
     embed: { ... },          // Values available as this.* in controllers
     onReceive: (queryId, data, type) => afterFn,
     onSend: (data, type) => afterFn,
     onError: (errStr) => { ... },
-    onDisconnent: () => { ... }
+    onDisconnect: () => { ... }
   }
 }
 ```
@@ -159,6 +167,40 @@ module.exports = function({ name, data }) {
 
 Binary data is transferred via `/api/ape/data/:hash` with session verification and HTTPS enforcement (localhost exempt).
 
+### Client-to-Client File Streaming (`<!F>`)
+
+For sharing files between clients (broadcasts), use the `<!F>` marker. Messages route immediately; file data transfers asynchronously with true streaming support.
+
+```
+Client A → Server: { msg: "here's a file", file<!F>: "hash123" }  + HTTP upload
+Server → Client B: { msg: "here's a file", file<!F>: "hash123" }  (immediate)
+Client B → Server: GET /api/ape/data/hash123                       (streams available bytes)
+```
+
+**Key differences from regular file transfer (`<!A>`/`<!B>`):**
+
+| Feature | Regular (`<!A>`/`<!B>`) | Shared (`<!F>`) |
+|---------|------------------------|-----------------|
+| **Session check** | Required | Skipped |
+| **Blocking** | Waits for upload | Non-blocking |
+| **Partial download** | No | Yes (stream what's uploaded) |
+| **Use case** | Client → Server | Client → Client via broadcast |
+
+**Server-side flow:**
+
+1. Message with `<!F>` received → streaming file registered
+2. Controller invoked immediately (non-blocking)
+3. When broadcast, `<!F>` tags pass through unchanged
+4. HTTP upload completes streaming file
+5. Other clients fetch from `/api/ape/data/:hash` (no session check)
+
+**Response headers:**
+
+| Header | Description |
+|--------|-------------|
+| `X-Ape-Complete` | `1` if upload finished, `0` if still streaming |
+| `X-Ape-Total-Received` | Bytes received so far |
+
 ---
 
 ## HTTP Streaming Endpoints
@@ -221,3 +263,267 @@ The built-in polyfill implements:
 - Ping/pong heartbeats
 - Proper close handshake
 - Masking (client→server)
+
+---
+
+## 🌲 Forest: Distributed Mesh
+
+**Forest** is api-ape's distributed coordination system for horizontal scaling. It routes messages between servers via a shared database, enabling you to run multiple api-ape instances behind a load balancer.
+
+### Quick Start
+
+```js
+const ape = require('api-ape');
+const { createClient } = require('redis');
+
+const redis = createClient();
+await redis.connect();
+
+// Join the mesh — pass any supported database client
+ape.joinVia(redis);
+
+// Graceful shutdown
+process.on('SIGINT', async () => {
+  await ape.leaveCluster();
+  process.exit(0);
+});
+```
+
+### The Problem Forest Solves
+
+Without coordination, each server only knows about its own connected clients:
+
+```
+              Load Balancer
+                   │
+      ┌────────────┼────────────┐
+      │            │            │
+   Server A     Server B     Server C
+   client-1     client-2     client-3
+```
+
+If Server A wants to send a message to `client-2`, it doesn't know where `client-2` is connected.
+
+**Naive solutions:**
+- **Broadcast to all servers** — O(n) messages, doesn't scale
+- **Sticky sessions** — Complex LB config, no failover
+
+**Forest's solution:**
+- **Direct routing** — Lookup `clientId → serverId`, push only to that server. O(1).
+
+### How It Works
+
+Forest uses two database primitives:
+
+| Primitive | Purpose | Example |
+|-----------|---------|---------|
+| **Lookup Table** | Maps `clientId → serverId` | Redis key, Postgres row |
+| **Channels** | Real-time message push | Redis PUB/SUB, Postgres NOTIFY |
+
+#### Message Flow
+
+```
+Server A: "Send message to client-2"
+    │
+    ▼
+1. Check local clients → not found
+    │
+    ▼
+2. lookup.read("client-2") → "srv-B"
+    │
+    ▼
+3. channels.push("srv-B", { destClientId: "client-2", ... })
+    │
+    ▼
+   Database (Redis/Postgres/Mongo/etc)
+    │
+    ▼
+Server B: Receives message, delivers to client-2
+```
+
+### Supported Backends
+
+| Backend | How to Connect | Channels | Lookup | Ideal For |
+|---------|---------------|----------|--------|-----------|
+| **Redis** | `createClient()` | PUB/SUB | Key-value | Most deployments; fastest |
+| **MongoDB** | `new MongoClient()` | Change Streams | Collection | Mongo-native stacks |
+| **PostgreSQL** | `new pg.Pool()` | LISTEN/NOTIFY | Table | SQL shops |
+| **Supabase** | `createClient()` | Realtime | Table | Supabase users |
+| **Firebase** | `getDatabase()` | Native push | JSON tree | Serverless/edge |
+
+### API Reference
+
+#### `ape.joinVia(client, options?)`
+
+Join the distributed mesh.
+
+```js
+ape.joinVia(redis);
+ape.joinVia(redis, { 
+  namespace: 'myapp',     // Key/table prefix (default: 'ape')
+  serverId: 'srv-west-1'  // Custom server ID (default: auto-generated)
+});
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `namespace` | `string` | `'ape'` | Prefix for all keys/tables |
+| `serverId` | `string` | Auto-generated | Unique ID for this server instance |
+
+#### `ape.leaveCluster()`
+
+Gracefully leave the mesh. Removes client mappings and unsubscribes from channels.
+
+```js
+await ape.leaveCluster();
+```
+
+### Namespacing
+
+Forest creates its own database objects with your namespace prefix:
+
+| Backend | Created Objects |
+|---------|----------------|
+| **Redis** | `ape:client:{id}`, `ape:channel:{serverId}`, `ape:channel:ALL` |
+| **MongoDB** | Database: `ape_cluster`, Collections: `clients`, `events` |
+| **PostgreSQL** | Tables: `ape_clients`, Channel: `ape_events` |
+| **Supabase** | Table: `ape_clients` (must create), Realtime channels |
+| **Firebase** | Paths: `/ape/clients/*`, `/ape/channels/*` |
+
+### Custom Adapters
+
+For unsupported databases or testing, implement the adapter interface:
+
+```js
+ape.joinVia({
+  async join(serverId) {
+    // Subscribe to channels, register this server
+  },
+  
+  async leave() {
+    // Unsubscribe, cleanup client mappings
+  },
+  
+  lookup: {
+    async add(clientId) {
+      // Map clientId → this server
+    },
+    async read(clientId) {
+      // Return serverId or null
+    },
+    async remove(clientId) {
+      // Delete mapping (must own it)
+    }
+  },
+  
+  channels: {
+    async push(serverId, message) {
+      // Send to server's channel ("" = broadcast)
+    },
+    async pull(serverId, handler) {
+      // Subscribe to channel
+      // handler(message, senderServerId)
+      return async () => { /* unsubscribe */ };
+    }
+  }
+});
+```
+
+### Lifecycle
+
+| Event | What Happens |
+|-------|-------------|
+| **Server joins** | `join(serverId)` — subscribe to channels |
+| **Client connects** | `lookup.add(clientId)` — register mapping |
+| **Message to remote client** | `lookup.read()` → `channels.push()` |
+| **Broadcast** | `channels.push('')` — to ALL channel |
+| **Client disconnects** | `lookup.remove(clientId)` |
+| **Server shuts down** | `leave()` — cleanup everything |
+
+### Crash Recovery
+
+`clientId` is ephemeral — generated fresh on each connection. If a server crashes:
+
+1. Orphaned client mappings remain (stale)
+2. Clients reconnect with new `clientId` to another server
+3. New mappings are created; old ones are harmless
+4. Optional: Use Redis `EXPIRE` or DB TTL indexes for cleanup
+
+### Example: Multi-Server Chat
+
+**Server A (port 3001):**
+```js
+const ape = require('api-ape');
+const redis = createClient();
+await redis.connect();
+
+ape(server, { where: 'api' });
+ape.joinVia(redis, { serverId: 'srv-a' });
+
+server.listen(3001);
+```
+
+**Server B (port 3002):**
+```js
+const ape = require('api-ape');
+const redis = createClient();
+await redis.connect();
+
+ape(server, { where: 'api' });
+ape.joinVia(redis, { serverId: 'srv-b' });
+
+server.listen(3002);
+```
+
+**Controller (`api/chat.js`):**
+```js
+module.exports = function(message) {
+  // Broadcasts across ALL servers automatically
+  this.broadcastOthers('chat', { 
+    from: this.clientId, 
+    message 
+  });
+  return { sent: true };
+};
+```
+
+Now clients connected to different servers can chat with each other seamlessly.
+
+### Performance Considerations
+
+| Concern | Recommendation |
+|---------|---------------|
+| **Lookup latency** | Use Redis for sub-ms lookups |
+| **Message throughput** | Redis PUB/SUB handles millions/sec |
+| **Stale mappings** | Set TTL/EXPIRE on client keys |
+| **Large payloads** | Postgres NOTIFY has 8KB limit |
+| **Change Stream lag** | MongoDB may have slight delay |
+
+### Debugging
+
+Forest logs key operations:
+
+```
+🔌 APE: Detected redis adapter (serverId: X7K9MWPA)
+✅ Redis adapter: joined as X7K9MWPA
+📍 Redis adapter: registered client abc123 -> X7K9MWPA
+📤 Redis adapter: pushed to server Y8M2ZPQR
+📢 Redis adapter: broadcast to all servers
+🔴 Redis adapter: leaving, cleaning up 3 clients
+```
+
+---
+
+## Adapter Files
+
+See detailed adapter implementations in [`server/adapters/`](adapters/):
+
+| File | Description |
+|------|-------------|
+| `index.js` | Auto-detects database type, creates adapter |
+| `redis.js` | Redis PUB/SUB adapter |
+| `mongo.js` | MongoDB Change Streams adapter |
+| `postgres.js` | PostgreSQL LISTEN/NOTIFY adapter |
+| `supabase.js` | Supabase Realtime adapter |
+| `firebase.js` | Firebase RTDB adapter |
+| `README.md` | Quick reference for all adapters |