api-ape 2.2.2 → 2.3.0

package/server/index.js

@@ -4,11 +4,11 @@
  */
 
 const ape = require('./lib/main')
-const { broadcast, online, getClients } = require('./lib/broadcast')
+const { broadcast, clients } = require('./lib/broadcast')
 
 // Attach broadcast utilities to the main function for clean exports
 ape.broadcast = broadcast
-ape.online = online
-ape.getClients = getClients
+ape.clients = clients
 
 module.exports = ape
+

package/server/lib/broadcast.js

@@ -1,40 +1,120 @@
 /**
- * Broadcast utilities for api-ape
- * Tracks connected clients and provides broadcast functions
+ * Client tracking and broadcast utilities for api-ape
+ * Provides a Map of connected clients with sendTo functionality
  */
 
-// Track all connected clients for broadcast
-const connectedClients = new Set()
+// Internal Map of connected clients: clientId -> ClientWrapper
+const _clients = new Map()
 
 /**
- * Add a client to the connected set
+ * Create a ClientWrapper that exposes client info and sendTo function
+ * @param {object} clientInfo - Raw client info from wiring/longPolling
+ */
+function createClientWrapper(clientInfo) {
+    return {
+        get clientId() { return clientInfo.clientId },
+        get sessionId() { return clientInfo.sessionId || null },
+        get embed() { return clientInfo.embed || {} },
+        get agent() { return clientInfo.agent || {} },
+        /**
+         * Send a message to this specific client
+         * @param {string} type - Message type
+         * @param {any} data - Data to send
+         */
+        sendTo(type, data) {
+            if (clientInfo.send) {
+                try {
+                    clientInfo.send(false, type, data, false)
+                } catch (e) {
+                    console.error(`📢 sendTo failed for ${clientInfo.clientId}:`, e.message)
+                }
+            }
+        }
+    }
+}
+
+/**
+ * Read-only proxy for the clients Map
+ * Allows: get, has, keys, values, entries, forEach, size, iteration
+ * Prevents: set, delete, clear (throws error if attempted)
+ */
+const clients = new Proxy(_clients, {
+    get(target, prop) {
+        // Prevent mutation methods
+        if (prop === 'set' || prop === 'delete' || prop === 'clear') {
+            return () => {
+                throw new Error(`ape.clients.${prop}() is not allowed. Clients are managed internally by api-ape.`)
+            }
+        }
+
+        // Allow size property
+        if (prop === 'size') {
+            return target.size
+        }
+
+        // Bind methods to target
+        const value = target[prop]
+        if (typeof value === 'function') {
+            return value.bind(target)
+        }
+
+        return value
+    }
+})
+
+/**
+ * Add a client to the connected map (internal use only)
+ * @param {object} clientInfo - { clientId, sessionId, agent, embed, send }
  */
 function addClient(clientInfo) {
-    connectedClients.add(clientInfo)
-    console.log(`🟢 Client added: ${clientInfo.clientId} (total: ${connectedClients.size})`)
+    const wrapper = createClientWrapper(clientInfo)
+    _clients.set(clientInfo.clientId, wrapper)
+
+    // Store reference to raw info so we can update embed later if needed
+    wrapper._raw = clientInfo
+
+    console.log(`🟢 Client added: ${clientInfo.clientId} (total: ${_clients.size})`)
 }
 
 /**
- * Remove a client from the connected set
- * Accepts either the client object or { clientId } for lookup
+ * Remove a client from the connected map (internal use only)
+ * @param {string|object} clientIdOrInfo - clientId string or { clientId } object
  */
-function removeClient(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
+function removeClient(clientIdOrInfo) {
+    const clientId = typeof clientIdOrInfo === 'string'
+        ? clientIdOrInfo
+        : clientIdOrInfo.clientId
+
+    if (_clients.has(clientId)) {
+        _clients.delete(clientId)
+        console.log(`🔴 Client removed: ${clientId} (total: ${_clients.size})`)
+    } else {
+        console.log(`⚠️ Client not found for removal: ${clientId} (total: ${_clients.size})`)
     }
-    // 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
-        }
+}
+
+/**
+ * Update a client's embed values after onConnect resolves (internal use only)
+ * @param {string} clientId 
+ * @param {object} embed 
+ */
+function updateClientEmbed(clientId, embed) {
+    const wrapper = _clients.get(clientId)
+    if (wrapper && wrapper._raw) {
+        wrapper._raw.embed = embed
+    }
+}
+
+/**
+ * Update a client's send function after it's ready (internal use only)
+ * @param {string} clientId 
+ * @param {function} send 
+ */
+function updateClientSend(clientId, send) {
+    const wrapper = _clients.get(clientId)
+    if (wrapper && wrapper._raw) {
+        wrapper._raw.send = send
     }
-    console.log(`⚠️ Client not found for removal: ${clientInfo.clientId} (total: ${connectedClients.size})`)
 }
 
 /**
@@ -44,37 +124,23 @@ function removeClient(clientInfo) {
  * @param {string} [excludeClientId] - Optional clientId to exclude (e.g., sender)
  */
 function broadcast(type, data, excludeClientId) {
-    console.log(`📢 Broadcasting "${type}" to ${connectedClients.size} clients`, excludeClientId ? `(excluding ${excludeClientId})` : '')
-    connectedClients.forEach(client => {
-        if (excludeClientId && client.clientId === excludeClientId) {
+    console.log(`📢 Broadcasting "${type}" to ${_clients.size} clients`, excludeClientId ? `(excluding ${excludeClientId})` : '')
+    _clients.forEach((wrapper, clientId) => {
+        if (excludeClientId && clientId === excludeClientId) {
             return // Skip excluded client
         }
-        try {
-            client.send(false, type, data, false)
-        } catch (e) {
-            console.error(`📢 Broadcast failed to ${client.clientId}:`, e.message)
-        }
+        wrapper.sendTo(type, data)
     })
 }
 
-/**
- * Get count of online clients
- */
-function online() {
-    return connectedClients.size
-}
-
-/**
- * Get all connected client clientIds
- */
-function getClients() {
-    return Array.from(connectedClients).map(c => c.clientId)
-}
-
 module.exports = {
+    // Public: read-only clients Map
+    clients,
+    // Public: broadcast function
+    broadcast,
+    // Internal: client management (used by wiring.js and longPolling.js)
     addClient,
     removeClient,
-    broadcast,
-    online,
-    getClients
+    updateClientEmbed,
+    updateClientSend
 }

package/server/lib/bun.js

@@ -6,7 +6,7 @@
  * ```ts
  * import { apeBun } from 'api-ape/bun'
  * 
- * const ape = apeBun({ where: 'api', onConnent: ... })
+ * const ape = apeBun({ where: 'api', onConnect: ... })
  * 
  * Bun.serve({
  *   port: 3000,
@@ -25,15 +25,15 @@ const { BunWebSocket, BunWebSocketServer } = require('./ws/adapters/bun')
 
 /**
  * Create api-ape handlers for Bun.serve()
- * @param {{ where: string, onConnent?: Function, fileTransferOptions?: Object }} options
+ * @param {{ where: string, onConnect?: Function, fileTransferOptions?: Object }} options
  */
-function apeBun({ where, onConnent, fileTransferOptions }) {
+function apeBun({ where, onConnect, 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)
+    const wiringHandler = wiring(controllers, onConnect, fileTransfer)
 
     // Handle connections
     wss.on('connection', wiringHandler)

package/server/lib/fileTransfer.js

@@ -28,10 +28,124 @@ class FileTransferManager {
         // Map<`${queryId}/${pathHash}`, { sessionHostId, createdAt, resolver, rejector, timer, data }>
         this.pendingUploads = new Map()
 
+        // Map<fileId, StreamingFileEntry> - for client-to-client streaming
+        // StreamingFileEntry: { uploaderId, chunks[], totalReceived, isComplete, createdAt, timer }
+        this.streamingFiles = new Map()
+
         // Cleanup interval
         this._cleanupInterval = setInterval(() => this._cleanup(), 30000)
     }
 
+    /**
+     * Register a streaming file (client-to-client transfer)
+     * Called when <!F> tag is detected in incoming message
+     * @param {string} fileId - Unique file identifier
+     * @param {string} uploaderId - Client ID of uploader
+     * @returns {string} The fileId
+     */
+    registerStreamingFile(fileId, uploaderId) {
+        // Clear existing entry if any
+        if (this.streamingFiles.has(fileId)) {
+            const existing = this.streamingFiles.get(fileId)
+            if (existing.timer) clearTimeout(existing.timer)
+        }
+
+        const entry = {
+            uploaderId,
+            chunks: [],
+            totalReceived: 0,
+            isComplete: false,
+            createdAt: Date.now(),
+            timer: setTimeout(() => {
+                this.streamingFiles.delete(fileId)
+                console.log(`📦 Streaming file expired: ${fileId}`)
+            }, this.startTimeout + this.completeTimeout)
+        }
+
+        this.streamingFiles.set(fileId, entry)
+        console.log(`📦 Registered streaming file: ${fileId} from ${uploaderId}`)
+        return fileId
+    }
+
+    /**
+     * Append a chunk to a streaming file
+     * @param {string} fileId - File identifier
+     * @param {Buffer} chunk - Data chunk
+     * @returns {boolean} True if accepted
+     */
+    appendChunk(fileId, chunk) {
+        const entry = this.streamingFiles.get(fileId)
+        if (!entry) {
+            console.warn(`📦 Streaming file not found: ${fileId}`)
+            return false
+        }
+
+        entry.chunks.push(chunk)
+        entry.totalReceived += chunk.length
+        return true
+    }
+
+    /**
+     * Mark streaming file as complete
+     * @param {string} fileId - File identifier
+     * @param {Buffer} data - Complete file data (if not chunked)
+     * @returns {boolean} True if successful
+     */
+    completeStreamingUpload(fileId, data) {
+        const entry = this.streamingFiles.get(fileId)
+        if (!entry) {
+            console.warn(`📦 Streaming file not found for completion: ${fileId}`)
+            return false
+        }
+
+        if (data) {
+            entry.chunks = [data]
+            entry.totalReceived = data.length
+        }
+        entry.isComplete = true
+
+        // Reset timer for cleanup after completion
+        clearTimeout(entry.timer)
+        entry.timer = setTimeout(() => {
+            this.streamingFiles.delete(fileId)
+            console.log(`📦 Streaming file cleaned up: ${fileId}`)
+        }, this.completeTimeout)
+
+        console.log(`📦 Streaming upload complete: ${fileId} (${entry.totalReceived} bytes)`)
+        return true
+    }
+
+    /**
+     * Get streaming file data (available bytes so far)
+     * @param {string} fileId - File identifier
+     * @param {number} offset - Byte offset to start from (for resumable downloads)
+     * @returns {{ data: Buffer, isComplete: boolean, totalReceived: number } | null}
+     */
+    getStreamingFile(fileId, offset = 0) {
+        const entry = this.streamingFiles.get(fileId)
+        if (!entry) {
+            return null
+        }
+
+        // Concatenate chunks
+        const data = Buffer.concat(entry.chunks)
+
+        return {
+            data: offset > 0 ? data.slice(offset) : data,
+            isComplete: entry.isComplete,
+            totalReceived: entry.totalReceived
+        }
+    }
+
+    /**
+     * Check if a file ID is a streaming file
+     * @param {string} fileId - File identifier
+     * @returns {boolean}
+     */
+    isStreamingFile(fileId) {
+        return this.streamingFiles.has(fileId)
+    }
+
     /**
      * Register a binary download
      * @param {string} hash - Unique hash for this download
@@ -210,6 +324,15 @@ class FileTransferManager {
                 console.log(`📤 Cleanup stale upload: ${key}`)
             }
         }
+
+        // Cleanup streaming files
+        for (const [fileId, entry] of this.streamingFiles) {
+            if (now - entry.createdAt > maxAge) {
+                clearTimeout(entry.timer)
+                this.streamingFiles.delete(fileId)
+                console.log(`📦 Cleanup stale streaming file: ${fileId}`)
+            }
+        }
     }
 
     /**
@@ -228,6 +351,12 @@ class FileTransferManager {
 
         this.pendingDownloads.clear()
         this.pendingUploads.clear()
+
+        // Clear streaming file timers
+        for (const entry of this.streamingFiles.values()) {
+            clearTimeout(entry.timer)
+        }
+        this.streamingFiles.clear()
     }
 }
 

package/server/lib/longPolling.js

@@ -1,6 +1,7 @@
-const { addClient, removeClient, broadcast } = require('./broadcast')
+const { addClient, removeClient, broadcast, clients, updateClientEmbed } = require('./broadcast')
 const makeid = require('../utils/genId')
 const jss = require('../../utils/jss')
+const parseUserAgent = require('../utils/parseUserAgent')
 
 // Active streaming connections: clientId -> { res, messageQueue, heartbeatTimer }
 const streamClients = new Map()
@@ -45,7 +46,7 @@ function sendJson(res, statusCode, data) {
 /**
  * Create long polling handler
  */
-function createLongPollingHandler(controllers, onConnent, fileTransfer) {
+function createLongPollingHandler(controllers, onConnect, fileTransfer) {
 
     /**
      * Handle GET /api/ape/poll - Streaming receive
@@ -116,26 +117,33 @@ function createLongPollingHandler(controllers, onConnent, fileTransfer) {
             }
         }, 20000)
 
-        // Register client for broadcasts
-        const clientInfo = { clientId, send }
-        addClient(clientInfo)
+        // Extract sessionId from cookies
+        const sessionIdMatch = (req.headers.cookie || '').match(/(?:^|;\s*)sessionId=([^;]*)/)
+        const sessionId = sessionIdMatch ? sessionIdMatch[1] : null
+
+        // Parse user agent
+        const agent = parseUserAgent(req.headers['user-agent'])
+
+        // Register client for broadcasts with full metadata
+        addClient({ clientId, sessionId, agent, send, embed: null })
         streamClients.set(clientId, clientState)
 
-        // Call onConnent hook if provided
-        if (onConnent) {
-            Promise.resolve(onConnent(null, req, send))
+        // Call onConnect hook if provided
+        if (onConnect) {
+            Promise.resolve(onConnect(null, req, send))
                 .then(handlers => {
                     if (handlers) {
-                        if (handlers.onDisconnent) {
-                            clientState.onDisconnect = handlers.onDisconnent
+                        if (handlers.onDisconnect) {
+                            clientState.onDisconnect = handlers.onDisconnect
                         }
                         if (handlers.embed) {
                             clientState.embed = handlers.embed
+                            updateClientEmbed(clientId, handlers.embed)
                         }
                     }
                 })
                 .catch(err => {
-                    console.error('onConnent error:', err)
+                    console.error('onConnect error:', err)
                 })
         }
 
@@ -193,8 +201,9 @@ function createLongPollingHandler(controllers, onConnent, fileTransfer) {
                     req,
                     broadcast: (t, d) => broadcast(t, d),
                     broadcastOthers: (t, d) => broadcast(t, d, clientId),
-                    online: () => streamClients.size,
-                    getClients: () => Array.from(streamClients.keys())
+                    // Use clients Map for count and list
+                    online: () => clients.size,
+                    getClients: () => Array.from(clients.keys())
                 }
 
                 // Execute controller

package/server/lib/main.js

@@ -73,11 +73,11 @@ function isSecure(req) {
 /**
  * Create core api-ape handlers (shared between runtimes)
  */
-function createApeCore({ where, onConnent, fileTransferOptions }) {
+function createApeCore({ where, onConnect, fileTransferOptions }) {
     const controllers = loader(where)
     const fileTransfer = getFileTransferManager(fileTransferOptions)
-    const wiringHandler = wiring(controllers, onConnent, fileTransfer)
-    const { handleStreamGet, handleStreamPost } = createLongPollingHandler(controllers, onConnent, fileTransfer)
+    const wiringHandler = wiring(controllers, onConnect, fileTransfer)
+    const { handleStreamGet, handleStreamPost } = createLongPollingHandler(controllers, onConnect, fileTransfer)
 
     const wsPath = `/${where}/ape`
     const pollPath = `/${where}/ape/poll`
@@ -185,6 +185,26 @@ function initNodeServer(server, options) {
         const downloadMatch = matchRoute(pathname, core.downloadPattern)
         if (req.method === 'GET' && downloadMatch) {
             const { hash } = downloadMatch
+
+            // Check for streaming file first (client-to-client sharing, no session check)
+            const streamingFile = core.fileTransfer.getStreamingFile(hash)
+            if (streamingFile) {
+                if (!isLocalhost(req.headers.host) && !isSecure(req)) {
+                    return sendJson(res, 403, { error: 'HTTPS required for file transfers' })
+                }
+
+                // Return available data (may be partial if upload still in progress)
+                res.writeHead(200, {
+                    'Content-Type': 'application/octet-stream',
+                    'Content-Length': streamingFile.data.length,
+                    'X-Ape-Complete': streamingFile.isComplete ? '1' : '0',
+                    'X-Ape-Total-Received': String(streamingFile.totalReceived)
+                })
+                res.end(streamingFile.data)
+                return
+            }
+
+            // Session-bound download (original behavior)
             const clientId = getCookie(req.headers, 'apeClientId') || req.headers['x-ape-client-id']
 
             if (!clientId) {
@@ -213,11 +233,6 @@ function initNodeServer(server, options) {
         const uploadMatch = matchRoute(pathname, core.uploadPattern)
         if (req.method === 'PUT' && uploadMatch) {
             const { queryId, pathHash } = uploadMatch
-            const clientId = getCookie(req.headers, 'apeClientId') || req.headers['x-ape-client-id']
-
-            if (!clientId) {
-                return sendJson(res, 401, { error: 'Missing session identifier' })
-            }
 
             if (!isLocalhost(req.headers.host) && !isSecure(req)) {
                 return sendJson(res, 403, { error: 'HTTPS required for file transfers' })
@@ -227,6 +242,23 @@ function initNodeServer(server, options) {
             req.on('data', chunk => chunks.push(chunk))
             req.on('end', () => {
                 const data = Buffer.concat(chunks)
+
+                // Check if this is a streaming file upload (client-to-client)
+                // For streaming files, queryId might be the fileId directly
+                if (core.fileTransfer.isStreamingFile(pathHash)) {
+                    const success = core.fileTransfer.completeStreamingUpload(pathHash, data)
+                    if (success) {
+                        return sendJson(res, 200, { success: true, streaming: true })
+                    }
+                    return sendJson(res, 404, { error: 'Streaming file not found' })
+                }
+
+                // Regular upload (session-bound)
+                const clientId = getCookie(req.headers, 'apeClientId') || req.headers['x-ape-client-id']
+                if (!clientId) {
+                    return sendJson(res, 401, { error: 'Missing session identifier' })
+                }
+
                 const success = core.fileTransfer.receiveUpload(queryId, pathHash, data, clientId)
 
                 if (success) {

package/server/lib/wiring.js

@@ -4,9 +4,9 @@ const socketReceive = require('../socket/receive')
 const socketSend = require('../socket/send')
 const makeid = require('../utils/genId')
 const parseUserAgent = require('../utils/parseUserAgent');
-const { addClient, removeClient } = require('./broadcast')
+const { addClient, removeClient, updateClientEmbed, updateClientSend } = require('./broadcast')
 
-// connent, beforeSend, beforeReceive, error, afterSend, afterReceive, disconnent
+// connect, beforeSend, beforeReceive, error, afterSend, afterReceive, disconnect
 
 
 function defaultEvents(events = {}) {
@@ -15,7 +15,7 @@ function defaultEvents(events = {}) {
         onReceive: () => { },
         onSend: () => { },
         onError: (errSt) => console.error(errSt),
-        onDisconnent: () => { },
+        onDisconnect: () => { },
     } // END fallBackEvents
     return Object.assign({}, fallBackEvents, events)
 } // END defaultEvents
@@ -24,8 +24,8 @@ function defaultEvents(events = {}) {
 //============================================== wiring
 //=====================================================
 
-module.exports = function wiring(controllers, onConnent, fileTransfer) {
-    onConnent = onConnent || (() => { });
+module.exports = function wiring(controllers, onConnect, fileTransfer) {
+    onConnect = onConnect || (() => { });
     return function webSocketHandler(socket, req) {
 
         let send;
@@ -40,31 +40,35 @@ module.exports = function wiring(controllers, onConnent, fileTransfer) {
 
         const clientId = makeid(20)
         const agent = parseUserAgent(req.headers['user-agent'])
+
+        // Extract sessionId from cookies (set by outer framework)
+        const sessionIdMatch = (req.headers.cookie || '').match(/(?:^|;\s*)sessionId=([^;]*)/)
+        const sessionId = sessionIdMatch ? sessionIdMatch[1] : null
+
         const sharedValues = {
             socket, req, agent, send: (type, data, err) => sentBufferFn(false, type, data, err)
         }
         sharedValues.send.toString = () => clientId
 
-        // Track this client for broadcast BEFORE calling onConnent
-        // This ensures ape.online() returns the correct count when sending init
-        const clientInfo = { clientId, send: null, embed: null }
-        addClient(clientInfo)
+        // Track this client for broadcast BEFORE calling onConnect
+        // This ensures ape.clients.size returns the correct count when sending init
+        addClient({ clientId, sessionId, agent, send: null, embed: null })
 
         // Remove client on disconnect (set up early, will work once send is assigned)
         socket.on('close', () => {
-            removeClient(clientInfo)
+            removeClient(clientId)
         })
 
-        let result = onConnent(socket, req, sharedValues.send)
+        let result = onConnect(socket, req, sharedValues.send)
         if (!result || !result.then) {
             result = Promise.resolve(result)
         }
         result.then(defaultEvents)
-            .then(({ embed, onReceive, onSend, onError, onDisconnent }) => {
+            .then(({ embed, onReceive, onSend, onError, onDisconnect }) => {
                 const isOk = socketOpen(socket, req, onError)
 
                 if (!isOk) {
-                    removeClient(clientInfo) // Clean up if connection fails
+                    removeClient(clientId) // Clean up if connection fails
                     return;
                 }
 
@@ -75,7 +79,7 @@ module.exports = function wiring(controllers, onConnent, fileTransfer) {
                     req,
                     clientId,
                     checkReply,
-                    events: { onReceive, onSend, onError, onDisconnent },
+                    events: { onReceive, onSend, onError, onDisconnect },
                     controllers,
                     sharedValues,
                     embedValues: embed,
@@ -84,13 +88,13 @@ module.exports = function wiring(controllers, onConnent, fileTransfer) {
                 send = socketSend(ape)
                 ape.send = send
 
-                // Update clientInfo with real send function and embed
-                clientInfo.send = send
-                clientInfo.embed = embed
+                // Update client with real send function and embed values
+                updateClientSend(clientId, send)
+                updateClientEmbed(clientId, embed)
 
-                // Call onDisconnent when socket closes
+                // Call onDisconnect when socket closes
                 socket.on('close', () => {
-                    onDisconnent()
+                    onDisconnect()
                 })
 
                 sentBufferAr.forEach(args => send(...args))