api-ape 2.0.0 → 2.2.2

package/package.json

@@ -1,24 +1,62 @@
 {
   "name": "api-ape",
-  "version": "2.0.0",
-  "description": "Remote procedure events",
+  "version": "2.2.2",
+  "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",
   "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "browser": "./client/index.js",
+      "default": "./index.js"
+    },
+    "./client": "./client/index.js",
+    "./client/*": "./client/*",
+    "./server": "./server/index.js",
+    "./server/*": "./server/*"
+  },
+  "files": [
+    "dist/",
+    "client/",
+    "server/",
+    "utils/",
+    "index.js",
+    "index.d.ts",
+    "!**/*.test.js"
+  ],
   "scripts": {
-    "test": "jest --no-cache ",
-    "test:go": "npm test -- --watch --coverage",
-    "test:update": "npm test -- --updateSnapshot",
-    "test:cover": "npm test -- --coverage --no-cache --detectOpenHandles",
-    "test:watch": "npm test -- --watch --runInBand"
+    "prepare": "cp .hooks/* .git/hooks/ 2>/dev/null && chmod +x .git/hooks/* || true",
+    "test": "jest --no-cache",
+    "test:watch": "jest --watch --runInBand",
+    "test:cover": "jest --coverage --no-cache --detectOpenHandles",
+    "demo:express": "cd example/ExpressJs && npm install && npm start",
+    "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"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/codemeasandwich/api-ape.git"
   },
   "keywords": [
-    "rpc",
+    "websocket",
+    "realtime",
+    "CSRF",
     "api",
-    "ape"
+    "remote-procedure-call",
+    "real-time",
+    "broadcast",
+    "socket",
+    "event-driven",
+    "http-streaming",
+    "long-polling",
+    "client-server",
+    "auto-reconnect",
+    "jjs",
+    "rpe",
+    "nodejs",
+    "library"
   ],
   "author": "brian shannon",
   "license": "MIT",
@@ -26,12 +64,9 @@
     "url": "https://github.com/codemeasandwich/api-ape/issues"
   },
   "homepage": "https://github.com/codemeasandwich/api-ape#readme",
-  "dependencies": {
-    "jest": "^29.3.1",
-    "ua-parser-js": "^1.0.37",
-    "ws": "^8.14.0"
-  },
+  "dependencies": {},
   "devDependencies": {
-    "esbuild": "^0.27.2"
+    "esbuild": "^0.27.2",
+    "jest": "^29.3.1"
   }
 }

package/server/README.md

@@ -8,15 +8,26 @@ Express.js integration for WebSocket-based Remote Procedure Events (RPE).
 server/
 ├── index.js          # Entry point (exports lib/main)
 ├── lib/
-│   ├── main.js       # Express integration & setup
+│   ├── main.js       # HTTP server integration & setup
 │   ├── loader.js     # Auto-loads controller files from folder
 │   ├── broadcast.js  # Client tracking & broadcast utilities
 │   ├── fileTransfer.js # Binary file transfer manager
-│   └── wiring.js     # WebSocket handler setup
+│   ├── longPolling.js  # HTTP streaming fallback handler
+│   ├── wiring.js     # WebSocket handler setup
+│   ├── wsProvider.js # Runtime detection (Node 24+ native / polyfill)
+│   └── ws/           # RFC 6455 WebSocket polyfill (zero dependencies)
+│       ├── index.js  # Module entry point
+│       ├── frames.js # Frame encoding/decoding
+│       ├── socket.js # WebSocket connection class
+│       ├── server.js # WebSocketServer class
+│       └── adapters/ # Runtime-specific adapters
+│           ├── bun.js  # Bun native WebSocket
+│           └── deno.js # Deno native WebSocket
 ├── socket/
 │   ├── receive.js    # Incoming message handler
 │   └── send.js       # Outgoing message handler
 ├── security/
+│   ├── origin.js     # Origin verification (works with Express & raw Node.js)
 │   └── reply.js      # Duplicate request protection
 └── utils/
     └── ...           # Server utilities
@@ -29,12 +40,12 @@ npm i api-ape
 ```
 
 ```js
-const express = require('express')
+const { createServer } = require('http')
 const ape = require('api-ape')
 
-const app = express()
+const server = createServer()
 
-ape(app, {
+ape(server, {
   where: 'api',        // Controller directory
   onConnent: (socket, req, send) => ({
     embed: { userId: req.session?.userId },
@@ -42,12 +53,12 @@ ape(app, {
   })
 })
 
-app.listen(3000)
+server.listen(3000)
 ```
 
 ## API
 
-### `ape(app, options)`
+### `ape(server, options)`
 
 | Option | Type | Description |
 |--------|------|-------------|
@@ -74,8 +85,9 @@ ape(app, {
 | `this.broadcast(type, data)` | Send to ALL connected clients |
 | `this.broadcastOthers(type, data)` | Send to all EXCEPT the caller |
 | `this.online()` | Get count of connected clients |
-| `this.getClients()` | Get array of connected hostIds |
-| `this.hostId` | Unique ID of the calling client |
+| `this.getClients()` | Get array of connected clientIds |
+| `this.clientId` | Unique ID of the calling client (generated by api-ape) |
+| `this.sessionId` | Session ID from cookie (set by outer framework, may be `null`) |
 | `this.req` | Original HTTP request |
 | `this.socket` | WebSocket instance |
 | `this.agent` | Parsed user-agent |
@@ -100,10 +112,22 @@ Drop JS files in your `where` directory:
 
 ```
 api/
-├── hello.js      → ape.hello(data)
-├── users/
-│   ├── list.js   → ape.users.list(data)
-│   └── create.js → ape.users.create(data)
+├── hello.js      → api.hello(data)
+├── users.js      → api.users(data)
+├── posts/
+│   ├── index.js  → api.posts(data)     # index.js maps to parent folder
+│   ├── list.js   → api.posts.list(data)
+│   └── create.js → api.posts.create(data)
+```
+
+**Note**: Both `api/users.js` and `api/users/index.js` map to the same endpoint `api.users(data)`. Use `index.js` when you want to group related files in a folder.
+
+**⚠️ Duplicate Detection**: If both files exist, api-ape will throw an error on startup:
+```
+🦍 Duplicate endpoint detected: "users"
+   - /users/index.js
+   - /users.js
+   Remove one of these files to fix this conflict.
 ```
 
 ## File Transfers
@@ -135,3 +159,65 @@ module.exports = function({ name, data }) {
 
 Binary data is transferred via `/api/ape/data/:hash` with session verification and HTTPS enforcement (localhost exempt).
 
+---
+
+## HTTP Streaming Endpoints
+
+api-ape automatically provides HTTP streaming endpoints as a fallback when WebSockets are blocked:
+
+### GET `/api/ape/poll`
+
+Long-lived HTTP streaming connection for receiving server messages.
+
+- **Session**: Cookie-based (`apeClientId`)
+- **Response**: Streaming JSON messages
+- **Heartbeat**: Every 20 seconds
+- **Auto-reconnect**: Client reconnects after 25 seconds
+
+### POST `/api/ape/poll`
+
+Send messages to server when using HTTP streaming transport.
+
+- **Session**: Cookie-based (`apeClientId`)
+- **Body**: JJS-encoded message
+- **Response**: JJS-encoded result
+
+### How It Works
+
+1. Client attempts WebSocket connection first
+2. On failure (firewall/proxy blocking), falls back to HTTP streaming
+3. Background WebSocket retry every 30 seconds
+4. Automatically upgrades back to WebSocket when available
+
+The fallback is **completely transparent** to your controllers - they work identically with both transports.
+
+---
+
+## Zero-Dependency WebSocket
+
+api-ape includes its own RFC 6455 WebSocket implementation with **zero npm dependencies**.
+
+### Runtime Detection
+
+The server automatically detects and uses the best available WebSocket implementation:
+
+1. **Deno**: Uses native `Deno.upgradeWebSocket()` API
+2. **Bun**: Uses native `Bun.serve()` WebSocket handlers
+3. **Node.js 24+** (stable): Uses native `node:ws` module
+4. **Earlier Node.js**: Uses built-in RFC 6455 polyfill
+
+```javascript
+// Automatic - no configuration needed
+ape(server, { where: 'api' })
+```
+
+### Polyfill Features
+
+The built-in polyfill implements:
+
+- Full RFC 6455 handshake (SHA-1 + GUID)
+- Text and binary frames
+- Frame fragmentation
+- Ping/pong heartbeats
+- Proper close handshake
+- Masking (client→server)

package/server/lib/broadcast.js

@@ -11,31 +11,48 @@ const connectedClients = new Set()
  */
 function addClient(clientInfo) {
     connectedClients.add(clientInfo)
+    console.log(`🟢 Client added: ${clientInfo.clientId} (total: ${connectedClients.size})`)
 }
 
 /**
  * Remove a client from the connected set
+ * Accepts either the client object or { clientId } for lookup
  */
 function removeClient(clientInfo) {
-    connectedClients.delete(clientInfo)
+    const sizeBefore = connectedClients.size
+    // If exact reference found, delete it
+    if (connectedClients.has(clientInfo)) {
+        connectedClients.delete(clientInfo)
+        console.log(`🔴 Client removed (ref): ${clientInfo.clientId} (total: ${connectedClients.size})`)
+        return
+    }
+    // Otherwise search by clientId (needed for long polling cleanup)
+    for (const client of connectedClients) {
+        if (client.clientId === clientInfo.clientId) {
+            connectedClients.delete(client)
+            console.log(`🔴 Client removed (lookup): ${clientInfo.clientId} (total: ${connectedClients.size})`)
+            return
+        }
+    }
+    console.log(`⚠️ Client not found for removal: ${clientInfo.clientId} (total: ${connectedClients.size})`)
 }
 
 /**
  * Broadcast to all connected clients
  * @param {string} type - Message type
  * @param {any} data - Data to send
- * @param {string} [excludeHostId] - Optional hostId to exclude (e.g., sender)
+ * @param {string} [excludeClientId] - Optional clientId to exclude (e.g., sender)
  */
-function broadcast(type, data, excludeHostId) {
-    console.log(`📢 Broadcasting "${type}" to ${connectedClients.size} clients`, excludeHostId ? `(excluding ${excludeHostId})` : '')
+function broadcast(type, data, excludeClientId) {
+    console.log(`📢 Broadcasting "${type}" to ${connectedClients.size} clients`, excludeClientId ? `(excluding ${excludeClientId})` : '')
     connectedClients.forEach(client => {
-        if (excludeHostId && client.hostId === excludeHostId) {
+        if (excludeClientId && client.clientId === excludeClientId) {
             return // Skip excluded client
         }
         try {
             client.send(false, type, data, false)
         } catch (e) {
-            console.error(`📢 Broadcast failed to ${client.hostId}:`, e.message)
+            console.error(`📢 Broadcast failed to ${client.clientId}:`, e.message)
         }
     })
 }
@@ -48,10 +65,10 @@ function online() {
 }
 
 /**
- * Get all connected client hostIds
+ * Get all connected client clientIds
  */
 function getClients() {
-    return Array.from(connectedClients).map(c => c.hostId)
+    return Array.from(connectedClients).map(c => c.clientId)
 }
 
 module.exports = {

package/server/lib/bun.js

@@ -0,0 +1,122 @@
+/**
+ * Bun-specific api-ape integration
+ * Returns handlers for use with Bun.serve()
+ * 
+ * Usage:
+ * ```ts
+ * import { apeBun } from 'api-ape/bun'
+ * 
+ * const ape = apeBun({ where: 'api', onConnent: ... })
+ * 
+ * Bun.serve({
+ *   port: 3000,
+ *   fetch: ape.fetch,
+ *   websocket: ape.websocket
+ * })
+ * ```
+ */
+
+const loader = require('./loader')
+const wiring = require('./wiring')
+const path = require('path')
+const fs = require('fs')
+const { getFileTransferManager } = require('./fileTransfer')
+const { BunWebSocket, BunWebSocketServer } = require('./ws/adapters/bun')
+
+/**
+ * Create api-ape handlers for Bun.serve()
+ * @param {{ where: string, onConnent?: Function, fileTransferOptions?: Object }} options
+ */
+function apeBun({ where, onConnent, fileTransferOptions }) {
+    const controllers = loader(where)
+    const fileTransfer = getFileTransferManager(fileTransferOptions)
+    const wss = new BunWebSocketServer({ noServer: true })
+
+    const wsPath = `/${where}/ape`
+    const wiringHandler = wiring(controllers, onConnent, fileTransfer)
+
+    // Handle connections
+    wss.on('connection', wiringHandler)
+
+    /**
+     * Bun fetch handler - handles HTTP requests and WebSocket upgrades
+     */
+    function fetch(req, server) {
+        const url = new URL(req.url)
+        const pathname = url.pathname
+
+        // WebSocket upgrade
+        if (pathname === wsPath) {
+            const upgrade = req.headers.get('upgrade')
+            if (upgrade?.toLowerCase() === 'websocket') {
+                // Use Bun's native upgrade
+                const success = server.upgrade(req, {
+                    data: { req }
+                })
+                if (success) {
+                    return undefined // Bun handles the response
+                }
+                return new Response('WebSocket upgrade failed', { status: 500 })
+            }
+        }
+
+        // Serve client bundle
+        if (pathname === `/${where}/ape.js`) {
+            try {
+                const filePath = path.join(__dirname, '../../dist/ape.js')
+                const data = fs.readFileSync(filePath)
+                return new Response(data, {
+                    headers: { 'Content-Type': 'application/javascript' }
+                })
+            } catch {
+                return new Response('Client bundle not found', { status: 500 })
+            }
+        }
+
+        // Not an api-ape route
+        return null
+    }
+
+    /**
+     * Bun websocket handlers
+     */
+    const websocket = {
+        open(ws) {
+            const wrapper = new BunWebSocket(ws)
+            wss._clients.set(ws, wrapper)
+
+            const { req } = ws.data || {}
+            wiringHandler(wrapper, req)
+        },
+
+        message(ws, message) {
+            const wrapper = wss._clients.get(ws)
+            if (wrapper) {
+                wrapper._onMessage(message)
+            }
+        },
+
+        close(ws, code, reason) {
+            const wrapper = wss._clients.get(ws)
+            if (wrapper) {
+                wrapper._onClose(code, reason)
+                wss._clients.delete(ws)
+            }
+        },
+
+        error(ws, error) {
+            const wrapper = wss._clients.get(ws)
+            if (wrapper) {
+                wrapper._onError(error)
+            }
+        }
+    }
+
+    return {
+        fetch,
+        websocket,
+        wss
+    }
+}
+
+module.exports = { apeBun }

package/server/lib/longPolling.js

@@ -0,0 +1,226 @@
+const { addClient, removeClient, broadcast } = require('./broadcast')
+const makeid = require('../utils/genId')
+const jss = require('../../utils/jss')
+
+// Active streaming connections: clientId -> { res, messageQueue, heartbeatTimer }
+const streamClients = new Map()
+
+// Pending message handlers for POST requests: queryId -> { resolve, reject, timer }
+const pendingRequests = new Map()
+
+/**
+ * Set apeClientId cookie if not present
+ */
+function ensureClientId(req, res) {
+    const cookies = req.headers.cookie || ''
+    const match = cookies.match(/(?:^|;\s*)apeClientId=([^;]*)/)
+
+    if (match) {
+        return match[1]
+    }
+
+    // Generate new clientId and set cookie
+    const clientId = makeid(20)
+    res.setHeader('Set-Cookie', `apeClientId=${clientId}; Path=/; HttpOnly; SameSite=Strict`)
+    return clientId
+}
+
+/**
+ * Get clientId from cookie
+ */
+function getClientId(req) {
+    const cookies = req.headers.cookie || ''
+    const match = cookies.match(/(?:^|;\s*)apeClientId=([^;]*)/)
+    return match ? match[1] : null
+}
+
+/**
+ * Send JSON response helper
+ */
+function sendJson(res, statusCode, data) {
+    res.writeHead(statusCode, { 'Content-Type': 'application/json' })
+    res.end(JSON.stringify(data))
+}
+
+/**
+ * Create long polling handler
+ */
+function createLongPollingHandler(controllers, onConnent, fileTransfer) {
+
+    /**
+     * Handle GET /api/ape/poll - Streaming receive
+     * Keeps connection open and writes JSON messages as they arrive
+     */
+    function handleStreamGet(req, res) {
+        const clientId = ensureClientId(req, res)
+
+        // Set up streaming response headers
+        res.writeHead(200, {
+            'Content-Type': 'application/json',
+            'Cache-Control': 'no-cache',
+            'Connection': 'keep-alive',
+            'X-Accel-Buffering': 'no' // Disable nginx buffering
+        })
+
+        // Create message queue for this client
+        const clientState = {
+            res,
+            messageQueue: [],
+            heartbeatTimer: null,
+            isActive: true
+        }
+
+        // Send function for this streaming client
+        const send = (type, data, err) => {
+            if (!clientState.isActive) return
+
+            const message = jss.stringify({ type, data, err: err || undefined })
+            try {
+                res.write(message)
+            } catch (e) {
+                cleanup()
+            }
+        }
+        send.toString = () => clientId
+
+        // Clean up on close
+        const cleanup = () => {
+            if (!clientState.isActive) return
+            clientState.isActive = false
+
+            if (clientState.heartbeatTimer) {
+                clearInterval(clientState.heartbeatTimer)
+            }
+
+            streamClients.delete(clientId)
+            removeClient({ clientId })
+
+            // Notify disconnect handler if registered
+            if (clientState.onDisconnect) {
+                clientState.onDisconnect()
+            }
+        }
+
+        req.on('close', cleanup)
+        req.on('error', cleanup)
+        res.on('error', cleanup)
+
+        // Heartbeat to keep connection alive (every 20s)
+        clientState.heartbeatTimer = setInterval(() => {
+            if (!clientState.isActive) return
+            try {
+                // Send heartbeat as empty comment (client ignores)
+                res.write('{"type":"__heartbeat__"}')
+            } catch (e) {
+                cleanup()
+            }
+        }, 20000)
+
+        // Register client for broadcasts
+        const clientInfo = { clientId, send }
+        addClient(clientInfo)
+        streamClients.set(clientId, clientState)
+
+        // Call onConnent hook if provided
+        if (onConnent) {
+            Promise.resolve(onConnent(null, req, send))
+                .then(handlers => {
+                    if (handlers) {
+                        if (handlers.onDisconnent) {
+                            clientState.onDisconnect = handlers.onDisconnent
+                        }
+                        if (handlers.embed) {
+                            clientState.embed = handlers.embed
+                        }
+                    }
+                })
+                .catch(err => {
+                    console.error('onConnent error:', err)
+                })
+        }
+
+        // Close after 25 seconds (before typical proxy timeout)
+        // Client will immediately reconnect
+        setTimeout(() => {
+            cleanup()
+            try {
+                res.end()
+            } catch (e) { }
+        }, 25000)
+    }
+
+    /**
+     * Handle POST /api/ape/poll - Send messages
+     * Process message through controllers, return response
+     */
+    function handleStreamPost(req, res, controllers) {
+        const clientId = getClientId(req)
+
+        if (!clientId) {
+            return sendJson(res, 401, { error: 'Missing session. GET /api/ape/poll first.' })
+        }
+
+        // Collect body
+        const chunks = []
+        req.on('data', chunk => chunks.push(chunk))
+        req.on('end', async () => {
+            try {
+                const body = Buffer.concat(chunks).toString('utf8')
+                const { type: rawType, data, createdAt } = jss.parse(body)
+
+                // Normalize type
+                const type = rawType.replace(/^\//, '').toLowerCase()
+
+                // Find controller
+                const controller = controllers[type]
+                if (!controller) {
+                    return sendJson(res, 404, { error: `Controller "${type}" not found` })
+                }
+
+                // Get client state for embed values
+                const clientState = streamClients.get(clientId)
+                const embedValues = clientState?.embed || {}
+
+                // Extract sessionId from cookies (set by outer framework)
+                const sessionIdMatch = (req.headers.cookie || '').match(/(?:^|;\s*)sessionId=([^;]*)/)
+                const sessionId = sessionIdMatch ? sessionIdMatch[1] : null
+
+                // Build controller context
+                const context = {
+                    ...embedValues,
+                    clientId,
+                    sessionId,  // Session ID from cookie (set by outer framework)
+                    req,
+                    broadcast: (t, d) => broadcast(t, d),
+                    broadcastOthers: (t, d) => broadcast(t, d, clientId),
+                    online: () => streamClients.size,
+                    getClients: () => Array.from(streamClients.keys())
+                }
+
+                // Execute controller
+                const result = await controller.call(context, data)
+
+                // Send response
+                const responsePayload = { data: result }
+                res.writeHead(200, { 'Content-Type': 'application/json' })
+                res.end(jss.stringify(responsePayload))
+
+            } catch (err) {
+                const errorMessage = err.message || String(err)
+                sendJson(res, 500, { error: errorMessage })
+            }
+        })
+
+        req.on('error', (err) => {
+            sendJson(res, 500, { error: err.message })
+        })
+    }
+
+    return {
+        handleStreamGet,
+        handleStreamPost,
+        getStreamClients: () => streamClients
+    }
+}
+
+module.exports = { createLongPollingHandler, getClientId, ensureClientId }