api-ape 3.0.1 → 4.1.0

package/server/lib/bun.js

@@ -1,122 +1,338 @@
 /**
- * Bun-specific api-ape integration
- * Returns handlers for use with Bun.serve()
- * 
- * Usage:
- * ```ts
+ * @fileoverview Bun-Specific api-ape Integration
+ *
+ * This module provides Bun-native integration for api-ape servers.
+ * It returns handlers that can be directly used with `Bun.serve()`,
+ * taking advantage of Bun's high-performance WebSocket implementation.
+ *
+ * Bun has a unique server API compared to Node.js:
+ * - WebSocket upgrades are handled via `server.upgrade()` in the fetch handler
+ * - WebSocket events are handled via a separate `websocket` object
+ * - The `fetch` function handles all HTTP requests
+ *
+ * This module provides a seamless integration that:
+ * - Handles WebSocket upgrades for the api-ape endpoint
+ * - Serves the client JavaScript bundle
+ * - Wraps Bun's native WebSocket in a ws-compatible interface
+ *
+ * @module server/lib/bun
+ * @see {@link module:server/lib/runtimes/bun} - Runtime-specific initialization
+ * @see {@link module:server/lib/ws/adapters/bun} - Bun WebSocket adapter
+ *
+ * @example
+ * // Basic usage with Bun.serve()
  * import { apeBun } from 'api-ape/bun'
- * 
- * const ape = apeBun({ where: 'api', onConnect: ... })
- * 
+ *
+ * const ape = apeBun({
+ *     where: 'api',
+ *     onConnect: (socket, req, send) => {
+ *         console.log('Client connected')
+ *         return {
+ *             onDisconnect: () => console.log('Client disconnected'),
+ *             embed: { userId: 'user-123' }
+ *         }
+ *     }
+ * })
+ *
+ * Bun.serve({
+ *     port: 3000,
+ *     fetch: ape.fetch,
+ *     websocket: ape.websocket
+ * })
+ *
+ * @example
+ * // Combined with custom routes
  * Bun.serve({
- *   port: 3000,
- *   fetch: ape.fetch,
- *   websocket: ape.websocket
+ *     port: 3000,
+ *     fetch(req, server) {
+ *         // Try api-ape routes first
+ *         const apeResponse = ape.fetch(req, server)
+ *         if (apeResponse !== null) return apeResponse
+ *
+ *         // Custom routes
+ *         const url = new URL(req.url)
+ *         if (url.pathname === '/health') {
+ *             return new Response('OK')
+ *         }
+ *
+ *         return new Response('Not Found', { status: 404 })
+ *     },
+ *     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')
+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");
+
+/**
+ * @typedef {Object} ApeBunOptions
+ * Configuration options for the Bun api-ape integration.
+ *
+ * @property {string} where - Directory containing controller files (relative to cwd).
+ *     Controllers in this directory become API endpoints.
+ *     Example: 'api' means controllers in './api/' folder.
+ * @property {Function} [onConnect] - Callback when a client connects.
+ *     Receives (socket, req, send) and can return { onDisconnect, embed }.
+ * @property {Object} [fileTransferOptions] - Options for the file transfer manager.
+ */
+
+/**
+ * @typedef {Object} ApeBunResult
+ * The result object containing handlers for Bun.serve().
+ *
+ * @property {Function} fetch - HTTP request handler for Bun.serve().
+ *     Returns Response for api-ape routes, null for non-matching routes.
+ * @property {Object} websocket - WebSocket event handlers for Bun.serve().
+ * @property {BunWebSocketServer} wss - The WebSocket server instance.
+ */
 
 /**
- * Create api-ape handlers for Bun.serve()
- * @param {{ where: string, onConnect?: Function, fileTransferOptions?: Object }} options
+ * @typedef {Object} BunWebSocketHandlers
+ * WebSocket event handlers for Bun.serve().
+ *
+ * @property {Function} open - Called when a WebSocket connection opens
+ * @property {Function} message - Called when a message is received
+ * @property {Function} close - Called when a connection closes
+ * @property {Function} error - Called when an error occurs
+ */
+
+/**
+ * Creates api-ape handlers for use with Bun.serve().
+ *
+ * This function sets up everything needed to run api-ape on Bun:
+ * - Loads controllers from the specified directory
+ * - Creates a WebSocket server with Bun-native adapter
+ * - Returns fetch and websocket handlers for Bun.serve()
+ *
+ * The returned `fetch` handler:
+ * - Handles WebSocket upgrades at `/{where}/ape`
+ * - Serves the client bundle at `/{where}/ape.js`
+ * - Returns `null` for non-matching routes (allows fallthrough)
+ *
+ * The returned `websocket` handler:
+ * - Wraps Bun's native WebSocket in ws-compatible interface
+ * - Routes messages through api-ape's wiring layer
+ * - Handles connection lifecycle (open, message, close, error)
+ *
+ * @function apeBun
+ * @param {ApeBunOptions} options - Configuration options
+ * @param {string} options.where - Controller directory name
+ * @param {Function} [options.onConnect] - Connection callback
+ * @param {Object} [options.fileTransferOptions] - File transfer options
+ * @returns {ApeBunResult} Object with fetch, websocket, and wss properties
+ *
+ * @example
+ * // Minimal setup
+ * const ape = apeBun({ where: 'api' })
+ *
+ * Bun.serve({
+ *     port: 3000,
+ *     fetch: ape.fetch,
+ *     websocket: ape.websocket
+ * })
+ *
+ * @example
+ * // With connection handler
+ * const ape = apeBun({
+ *     where: 'api',
+ *     onConnect: async (socket, req, send) => {
+ *         // Authenticate user from cookies/headers
+ *         const token = req.headers.get('authorization')
+ *         const user = await verifyToken(token)
+ *
+ *         return {
+ *             embed: { userId: user.id, role: user.role },
+ *             onDisconnect: () => {
+ *                 console.log(`User ${user.id} disconnected`)
+ *             }
+ *         }
+ *     }
+ * })
+ *
+ * @example
+ * // With file transfer options
+ * const ape = apeBun({
+ *     where: 'api',
+ *     fileTransferOptions: {
+ *         startTimeout: 30000,
+ *         completeTimeout: 60000
+ *     }
+ * })
  */
 function apeBun({ where, onConnect, fileTransferOptions }) {
-    const controllers = loader(where)
-    const fileTransfer = getFileTransferManager(fileTransferOptions)
-    const wss = new BunWebSocketServer({ noServer: true })
+  /**
+   * Load controllers from the specified directory.
+   * @type {Object<string, Function>}
+   */
+  const controllers = loader(where);
 
-    const wsPath = `/${where}/ape`
-    const wiringHandler = wiring(controllers, onConnect, fileTransfer)
+  /**
+   * File transfer manager for handling binary uploads/downloads.
+   * @type {import('./fileTransfer').FileTransferManager}
+   */
+  const fileTransfer = getFileTransferManager(fileTransferOptions);
 
-    // Handle connections
-    wss.on('connection', wiringHandler)
+  /**
+   * WebSocket server instance with Bun adapter.
+   * @type {BunWebSocketServer}
+   */
+  const wss = new BunWebSocketServer({ noServer: true });
 
-    /**
-     * 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 })
-            }
-        }
+  /**
+   * WebSocket path for api-ape connections.
+   * @type {string}
+   */
+  const wsPath = `/${where}/ape`;
 
-        // 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 })
-            }
+  /**
+   * Wiring handler that processes WebSocket connections and messages.
+   * @type {Function}
+   */
+  const wiringHandler = wiring(controllers, onConnect, fileTransfer);
+
+  // Handle WebSocket connections through the wiring layer
+  wss.on("connection", wiringHandler);
+
+  /**
+   * Bun fetch handler for HTTP requests and WebSocket upgrades.
+   *
+   * Routes handled:
+   * - `/{where}/ape` - WebSocket upgrade endpoint
+   * - `/{where}/ape.js` - Client JavaScript bundle
+   *
+   * @function fetch
+   * @param {Request} req - Bun Request object
+   * @param {Object} server - Bun server instance with upgrade() method
+   * @returns {Response|null|undefined} Response for handled routes, null/undefined for others
+   *
+   * @example
+   * // In Bun.serve()
+   * fetch(req, server) {
+   *     const apeResponse = ape.fetch(req, server)
+   *     if (apeResponse !== null) return apeResponse
+   *     // ... handle other routes
+   * }
+   */
+  function fetch(req, server) {
+    const url = new URL(req.url);
+    const pathname = url.pathname;
+
+    // Handle WebSocket upgrade requests
+    if (pathname === wsPath) {
+      const upgrade = req.headers.get("upgrade");
+      if (upgrade?.toLowerCase() === "websocket") {
+        // Use Bun's native upgrade mechanism
+        // Store request in data for access in websocket.open
+        const success = server.upgrade(req, {
+          data: { req },
+        });
+        if (success) {
+          // Return undefined to signal Bun handles the response
+          return undefined;
         }
+        return new Response("WebSocket upgrade failed", { status: 500 });
+      }
+    }
 
-        // Not an api-ape route
-        return null
+    // Serve the client JavaScript 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 to allow fallthrough
+    return null;
+  }
+
+  /**
+   * Bun WebSocket event handlers.
+   *
+   * These handlers are passed directly to Bun.serve() and handle
+   * the WebSocket lifecycle events. Each handler wraps Bun's native
+   * WebSocket in a ws-compatible BunWebSocket adapter.
+   *
+   * @type {BunWebSocketHandlers}
+   */
+  const websocket = {
     /**
-     * Bun websocket handlers
+     * Called when a WebSocket connection is opened.
+     * Creates a BunWebSocket wrapper and passes to the wiring handler.
+     *
+     * @param {Object} ws - Bun's native WebSocket instance
      */
-    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)
-            }
-        }
-    }
+    open(ws) {
+      // Create ws-compatible wrapper around Bun's WebSocket
+      const wrapper = new BunWebSocket(ws);
+      wss._clients.set(ws, wrapper);
 
-    return {
-        fetch,
-        websocket,
-        wss
-    }
+      // Get the original request from upgrade data
+      const { req } = ws.data || {};
+
+      // Pass to wiring handler for api-ape processing
+      wiringHandler(wrapper, req);
+    },
+
+    /**
+     * Called when a message is received on the WebSocket.
+     * Routes the message through the wrapper's event system.
+     *
+     * @param {Object} ws - Bun's native WebSocket instance
+     * @param {string|Buffer} message - The received message
+     */
+    message(ws, message) {
+      const wrapper = wss._clients.get(ws);
+      if (wrapper) {
+        wrapper._onMessage(message);
+      }
+    },
+
+    /**
+     * Called when a WebSocket connection is closed.
+     * Triggers close event and cleans up the wrapper.
+     *
+     * @param {Object} ws - Bun's native WebSocket instance
+     * @param {number} code - Close status code
+     * @param {string} reason - Close reason
+     */
+    close(ws, code, reason) {
+      const wrapper = wss._clients.get(ws);
+      if (wrapper) {
+        wrapper._onClose(code, reason);
+        wss._clients.delete(ws);
+      }
+    },
+
+    /**
+     * Called when an error occurs on the WebSocket.
+     * Routes the error through the wrapper's event system.
+     *
+     * @param {Object} ws - Bun's native WebSocket instance
+     * @param {Error} error - The error that occurred
+     */
+    error(ws, error) {
+      const wrapper = wss._clients.get(ws);
+      if (wrapper) {
+        wrapper._onError(error);
+      }
+    },
+  };
+
+  return {
+    fetch,
+    websocket,
+    wss,
+  };
 }
 
-module.exports = { apeBun }
+module.exports = { apeBun };

package/server/lib/fileTransfer/README.md

@@ -0,0 +1,63 @@
+# File Transfer Module
+
+## Overview
+
+The fileTransfer module handles binary data transfers between clients and the server. It enables api-ape to seamlessly transmit files, images, and other binary content alongside JSON messages through a tag-based system that automatically coordinates HTTP uploads and downloads.
+
+**Key capabilities:**
+
+- **Tagged binary fields** — Mark message fields with `<!B>` or `<!A>` to indicate pending binary uploads
+- **Streaming transfers** — Client-to-client file streaming without storing complete files in memory
+- **Download links** — Server can return `<!L>` tags that clients automatically fetch
+- **Session verification** — All transfers are authenticated against the client's session
+- **Timeout management** — Configurable timeouts for upload start and completion
+- **Progress tracking** — Track streaming transfer progress with partial reads
+
+The module works transparently—controllers receive and return regular Buffers while the framework handles the HTTP upload/download coordination behind the scenes.
+
+> **Contributing?** See [`files.md`](./files.md) for directory structure and file descriptions.
+
+## Tag System
+
+Messages can include special tags to handle binary data:
+
+| Tag | Direction | Description |
+|-----|-----------|-------------|
+| `<!B>` | Client → Server | Client will upload a Buffer via HTTP PUT |
+| `<!A>` | Client → Server | Client will upload an ArrayBuffer via HTTP PUT |
+| `<!F>` | Client → Server | Client-to-client streaming file transfer |
+| `<!L>` | Server → Client | Server returns download link for client to fetch |
+
+## How It Works
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                    Binary Upload Flow                            │
+├──────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  1. Client sends: { "image<!B>": "hash123", name: "photo.jpg" }  │
+│  2. Server holds message, waits for binary upload                │
+│  3. Client uploads binary via PUT /api/ape/data/qid/hash123      │
+│  4. Server injects Buffer into message: { image: <Buffer>, ... } │
+│  5. Controller receives complete message with binary data        │
+│                                                                  │
+└──────────────────────────────────────────────────────────────────┘
+
+┌──────────────────────────────────────────────────────────────────┐
+│                   Binary Download Flow                           │
+├──────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  1. Controller returns: { image: <Buffer>, name: "photo.jpg" }   │
+│  2. Server replaces Buffer with link: { "image<!L>": "hash456" } │
+│  3. Client receives message, detects <!L> tag                    │
+│  4. Client fetches binary via GET /api/ape/data/hash456          │
+│  5. Client receives: { image: <ArrayBuffer>, name: "photo.jpg" } │
+│                                                                  │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+## See Also
+
+- [`../fileTransfer.js`](../fileTransfer.js) — Main file transfer manager
+- [`../../socket/tagUtils.js`](../../socket/tagUtils.js) — Tag parsing utilities
+- [`../../socket/receive.js`](../../socket/receive.js) — Message handler with upload coordination

package/server/lib/fileTransfer/files.md

@@ -0,0 +1,30 @@
+# File Transfer Module Files
+
+This module handles binary data transfers between clients and the server. It enables api-ape to seamlessly transmit files, images, and other binary content alongside JSON messages through a tag-based system that automatically coordinates HTTP uploads and downloads.
+
+## Guidelines
+
+- **Tag system consistency** — Use the established tags (`<!B>`, `<!A>`, `<!L>`, `<!F>`); don't invent new ones without updating all consumers
+- **Session verification** — All transfers must authenticate against the client's session; never allow unauthenticated binary access
+- **Timeout handling** — Always set timeouts for pending uploads; clean up resources when timeouts expire
+- **Memory management** — Streaming transfers should not load entire files into memory; use chunked processing
+- **Coordinate with socket module** — Binary tag detection happens in `socket/tagUtils.js`; upload injection in `socket/receive.js`
+
+## Directory Structure
+
+```
+fileTransfer/
+└── streaming.js   # Client-to-client file streaming manager
+```
+
+## Files
+
+### `streaming.js`
+
+The `StreamingFileManager` class handles streaming file transfers between clients:
+
+- **Chunked uploads** — Data arrives in pieces and is accumulated in memory
+- **Partial reads** — Downloaders can read data as it arrives (progressive download)
+- **Completion tracking** — Know when the full file has been received
+- **Automatic cleanup** — Files are removed after configurable timeouts
+- **Transfer coordination** — Manages the handoff between uploader and downloader clients