api-ape 2.0.0 → 2.2.2

package/server/lib/ws/server.js

@@ -0,0 +1,109 @@
+/**
+ * WebSocketServer class
+ * Handles HTTP upgrade requests and creates WebSocket connections
+ */
+
+const { EventEmitter } = require('events')
+const { generateAcceptKey } = require('./frames')
+const { WebSocket } = require('./socket')
+
+class WebSocketServer extends EventEmitter {
+    /**
+     * Create WebSocket server
+     * @param {{ noServer?: boolean }} options
+     */
+    constructor(options = {}) {
+        super()
+        this._noServer = options.noServer || false
+        this._clients = new Set()
+    }
+
+    /**
+     * Get all connected clients
+     * @returns {Set<WebSocket>}
+     */
+    get clients() {
+        return this._clients
+    }
+
+    /**
+     * Handle HTTP upgrade request
+     * @param {http.IncomingMessage} req - HTTP request
+     * @param {net.Socket} socket - TCP socket
+     * @param {Buffer} head - First packet of upgraded stream
+     * @param {function} callback - Called with WebSocket instance
+     */
+    handleUpgrade(req, socket, head, callback) {
+        // Validate WebSocket upgrade request
+        const upgrade = req.headers['upgrade']
+        if (!upgrade || upgrade.toLowerCase() !== 'websocket') {
+            socket.destroy()
+            return
+        }
+
+        const key = req.headers['sec-websocket-key']
+        if (!key) {
+            socket.destroy()
+            return
+        }
+
+        // Validate key is valid base64 (16 bytes = 24 chars base64)
+        if (!/^[A-Za-z0-9+/]{22}==$/.test(key)) {
+            socket.destroy()
+            return
+        }
+
+        // Generate accept key
+        const acceptKey = generateAcceptKey(key)
+
+        // Build HTTP 101 response
+        const headers = [
+            'HTTP/1.1 101 Switching Protocols',
+            'Upgrade: websocket',
+            'Connection: Upgrade',
+            `Sec-WebSocket-Accept: ${acceptKey}`,
+            '', ''  // Empty line to end headers
+        ].join('\r\n')
+
+        // Send handshake response
+        socket.write(headers)
+
+        // If there's buffered data after upgrade, process it
+        // The 'head' contains any data received after the upgrade request
+        // We'll handle this in the WebSocket's buffer
+
+        // Create WebSocket wrapper
+        const ws = new WebSocket(socket)
+        this._clients.add(ws)
+
+        // Remove from clients on close
+        ws.on('close', () => {
+            this._clients.delete(ws)
+        })
+
+        // Handle any buffered data
+        if (head && head.length > 0) {
+            socket.unshift(head)
+        }
+
+        // Call callback with the WebSocket
+        if (callback) {
+            callback(ws)
+        }
+    }
+
+    /**
+     * Close server and all connections
+     */
+    close(callback) {
+        for (const client of this._clients) {
+            client.close(1001, 'Server shutting down')
+        }
+        this._clients.clear()
+        if (callback) {
+            callback()
+        }
+    }
+}
+
+module.exports = { WebSocketServer }

package/server/lib/ws/socket.js

@@ -0,0 +1,222 @@
+/**
+ * WebSocket connection class
+ * Wraps a TCP socket and handles WebSocket frame protocol
+ */
+
+const { EventEmitter } = require('events')
+const {
+    OPCODES,
+    parseFrame,
+    buildFrame,
+    buildCloseFrame,
+    buildPongFrame,
+    parseClosePayload
+} = require('./frames')
+
+// WebSocket ready states (matching ws library)
+const READY_STATES = {
+    CONNECTING: 0,
+    OPEN: 1,
+    CLOSING: 2,
+    CLOSED: 3
+}
+
+class WebSocket extends EventEmitter {
+    constructor(socket) {
+        super()
+        this._socket = socket
+        this._readyState = READY_STATES.OPEN
+        this._buffer = Buffer.alloc(0)
+        this._fragments = []
+        this._fragmentOpcode = null
+
+        // Define constants on instance (matching ws library API)
+        this.CONNECTING = READY_STATES.CONNECTING
+        this.OPEN = READY_STATES.OPEN
+        this.CLOSING = READY_STATES.CLOSING
+        this.CLOSED = READY_STATES.CLOSED
+
+        this._setupSocketListeners()
+    }
+
+    get readyState() {
+        return this._readyState
+    }
+
+    /**
+     * Send data to the client
+     * @param {string|Buffer} data - Data to send
+     */
+    send(data) {
+        if (this._readyState !== READY_STATES.OPEN) {
+            throw new Error('WebSocket is not open')
+        }
+
+        const opcode = Buffer.isBuffer(data) ? OPCODES.BINARY : OPCODES.TEXT
+        const frame = buildFrame(data, opcode)
+        this._socket.write(frame)
+    }
+
+    /**
+     * Close the WebSocket connection
+     * @param {number} code - Status code
+     * @param {string} reason - Close reason
+     */
+    close(code = 1000, reason = '') {
+        if (this._readyState === READY_STATES.CLOSING ||
+            this._readyState === READY_STATES.CLOSED) {
+            return
+        }
+
+        this._readyState = READY_STATES.CLOSING
+        const frame = buildCloseFrame(code, reason)
+        this._socket.write(frame)
+
+        // Give time for close frame to send, then destroy
+        setTimeout(() => {
+            if (this._readyState !== READY_STATES.CLOSED) {
+                this._socket.destroy()
+            }
+        }, 100)
+    }
+
+    /**
+     * Set up TCP socket event handlers
+     */
+    _setupSocketListeners() {
+        this._socket.on('data', (data) => {
+            this._handleData(data)
+        })
+
+        this._socket.on('close', () => {
+            this._readyState = READY_STATES.CLOSED
+            this.emit('close')
+        })
+
+        this._socket.on('error', (err) => {
+            this.emit('error', err)
+        })
+    }
+
+    /**
+     * Handle incoming data, parse frames
+     * @param {Buffer} data - Incoming data chunk
+     */
+    _handleData(data) {
+        // Append to buffer
+        this._buffer = Buffer.concat([this._buffer, data])
+
+        // Process all complete frames in buffer
+        while (this._buffer.length > 0) {
+            const result = parseFrame(this._buffer)
+            if (!result) break // Incomplete frame
+
+            const { frame, bytesConsumed } = result
+            this._buffer = this._buffer.slice(bytesConsumed)
+
+            this._handleFrame(frame)
+        }
+    }
+
+    /**
+     * Handle a parsed frame
+     * @param {{ fin: boolean, opcode: number, payload: Buffer }} frame
+     */
+    _handleFrame(frame) {
+        const { fin, opcode, payload } = frame
+
+        switch (opcode) {
+            case OPCODES.CONTINUATION:
+                this._handleContinuation(fin, payload)
+                break
+
+            case OPCODES.TEXT:
+            case OPCODES.BINARY:
+                if (fin) {
+                    // Complete message
+                    this._emitMessage(opcode, payload)
+                } else {
+                    // Start of fragmented message
+                    this._fragments = [payload]
+                    this._fragmentOpcode = opcode
+                }
+                break
+
+            case OPCODES.CLOSE:
+                this._handleClose(payload)
+                break
+
+            case OPCODES.PING:
+                this._handlePing(payload)
+                break
+
+            case OPCODES.PONG:
+                // Pong received, could emit event if needed
+                break
+
+            default:
+                // Unknown opcode, close connection
+                this.close(1002, 'Unknown opcode')
+        }
+    }
+
+    /**
+     * Handle continuation frame for fragmented messages
+     */
+    _handleContinuation(fin, payload) {
+        if (!this._fragmentOpcode) {
+            this.close(1002, 'Unexpected continuation frame')
+            return
+        }
+
+        this._fragments.push(payload)
+
+        if (fin) {
+            const completePayload = Buffer.concat(this._fragments)
+            this._emitMessage(this._fragmentOpcode, completePayload)
+            this._fragments = []
+            this._fragmentOpcode = null
+        }
+    }
+
+    /**
+     * Emit message event
+     */
+    _emitMessage(opcode, payload) {
+        // For text, convert to string; for binary, keep as Buffer
+        // But ws library emits Buffer by default, so we match that
+        this.emit('message', payload)
+    }
+
+    /**
+     * Handle close frame
+     */
+    _handleClose(payload) {
+        const { code, reason } = parseClosePayload(payload)
+
+        if (this._readyState === READY_STATES.OPEN) {
+            // Send close frame back
+            this._readyState = READY_STATES.CLOSING
+            const frame = buildCloseFrame(code)
+            this._socket.write(frame, () => {
+                this._socket.destroy()
+            })
+        } else {
+            this._socket.destroy()
+        }
+
+        this._readyState = READY_STATES.CLOSED
+    }
+
+    /**
+     * Handle ping frame - respond with pong
+     */
+    _handlePing(payload) {
+        if (this._readyState === READY_STATES.OPEN) {
+            const pong = buildPongFrame(payload)
+            this._socket.write(pong)
+        }
+    }
+}
+
+module.exports = { WebSocket, READY_STATES }

package/server/lib/wsProvider.js

@@ -0,0 +1,135 @@
+/**
+ * WebSocket Provider
+ * Detects runtime capabilities and provides appropriate WebSocket implementation
+ * 
+ * Priority:
+ * 1. Deno native WebSocket (Deno.upgradeWebSocket)
+ * 2. Bun native WebSocket (Bun.serve websocket)
+ * 3. Node.js 24+ stable native WebSocketServer (node:ws module)
+ * 4. Custom polyfill (RFC 6455 compliant)
+ */
+
+/**
+ * Check if running in Deno runtime
+ * @returns {boolean}
+ */
+function isDeno() {
+    return typeof Deno !== 'undefined' && typeof Deno.upgradeWebSocket === 'function'
+}
+
+/**
+ * Check if running in Bun runtime
+ * Uses process.versions.bun which is the recommended detection method
+ * @returns {boolean}
+ */
+function isBun() {
+    return typeof process !== 'undefined' && !!process.versions?.bun
+}
+
+/**
+ * Check if Node.js version is 24+ stable (not pre-release)
+ * @returns {boolean}
+ */
+function isNode24Stable() {
+    if (typeof process === 'undefined' || !process.versions || !process.versions.node) {
+        return false
+    }
+
+    // Skip if this is actually Bun (Bun also has process.versions.node)
+    if (isBun()) {
+        return false
+    }
+
+    const versionStr = process.versions.node
+    const majorVersion = parseInt(versionStr.split('.')[0], 10)
+
+    // Must be Node 24+
+    if (majorVersion < 24) {
+        return false
+    }
+
+    // Check if this is a stable release (not RC, alpha, beta)
+    // Pre-release versions contain hyphens like "24.0.0-rc.1"
+    if (versionStr.includes('-')) {
+        return false
+    }
+
+    return true
+}
+
+/**
+ * Get the detected runtime type
+ * @returns {'deno' | 'bun' | 'node' | 'unknown'}
+ */
+function getRuntime() {
+    if (isDeno()) return 'deno'
+    if (isBun()) return 'bun'
+    if (typeof process !== 'undefined' && process.versions?.node) return 'node'
+    return 'unknown'
+}
+
+/**
+ * Get WebSocket provider based on runtime capabilities
+ * @returns {{ type: string, WebSocketServer: typeof import('./ws').WebSocketServer, runtime: string }}
+ */
+function getWebSocketProvider() {
+    const runtime = getRuntime()
+
+    // 1. Check for Deno runtime
+    if (runtime === 'deno') {
+        try {
+            const { DenoWebSocketServer } = require('./ws/adapters/deno')
+            return { type: 'deno-native', WebSocketServer: DenoWebSocketServer, runtime }
+        } catch {
+            // Adapter not available, fall through to polyfill
+        }
+    }
+
+    // 2. Check for Bun runtime
+    if (runtime === 'bun') {
+        try {
+            const { BunWebSocketServer } = require('./ws/adapters/bun')
+            return { type: 'bun-native', WebSocketServer: BunWebSocketServer, runtime }
+        } catch {
+            // Adapter not available, fall through to polyfill
+        }
+    }
+
+    // 3. Try Node.js 24+ native WebSocketServer
+    if (isNode24Stable()) {
+        try {
+            const { WebSocketServer } = require('node:ws')
+            if (WebSocketServer) {
+                return { type: 'node-native', WebSocketServer, runtime }
+            }
+        } catch {
+            // node:ws not available, fall through
+        }
+    }
+
+    // 4. Fall back to our polyfill
+    const { WebSocketServer } = require('./ws/index')
+    return { type: 'polyfill', WebSocketServer, runtime }
+}
+
+// Cache the provider for consistent usage
+let cachedProvider = null
+
+/**
+ * Get cached WebSocket provider
+ * @returns {{ type: string, WebSocketServer: typeof import('./ws').WebSocketServer, runtime: string }}
+ */
+function getCachedProvider() {
+    if (!cachedProvider) {
+        cachedProvider = getWebSocketProvider()
+    }
+    return cachedProvider
+}
+
+module.exports = {
+    getWebSocketProvider: getCachedProvider,
+    getRuntime,
+    isDeno,
+    isBun,
+    isNode24Stable
+}

package/server/security/origin.js

@@ -1,12 +1,24 @@
 const extractRootDomain = require('./extractRootDomain')
 
+// Helper to get header that works with both Express and raw Node http
+function getHeader(req, name) {
+  // Express-style
+  if (typeof req.header === 'function') {
+    return req.header(name)
+  }
+  // Raw Node.js http request
+  return req.headers[name.toLowerCase()]
+}
+
 module.exports = function (socket, req, onError) {
   onError = onError || console.error
-  const origin = extractRootDomain(req.header('Origin') || "");
-  const host = extractRootDomain(req.header('Host'));
+  const origin = extractRootDomain(getHeader(req, 'Origin') || "")
+  const host = extractRootDomain(getHeader(req, 'Host'))
   if (origin && origin !== host) {
-    onError("REJECTING socket from " + req.header('Origin') + " miss-match with " + req.header('Host'))
-    socket.destroy()
+    onError("REJECTING socket from " + getHeader(req, 'Origin') + " miss-match with " + getHeader(req, 'Host'))
+    if (socket && socket.destroy) {
+      socket.destroy()
+    }
     return false
   }
   return true

package/server/socket/receive.js

@@ -89,9 +89,21 @@ function setValueAtPath(obj, path, value) {
     current[parts[parts.length - 1]] = value
 }
 
+/**
+ * Extract sessionId cookie from request headers
+ */
+function getSessionId(req) {
+    const cookies = req?.headers?.cookie || ''
+    const match = cookies.match(/(?:^|;\s*)sessionId=([^;]*)/)
+    return match ? match[1] : null
+}
+
 module.exports = function receiveHandler(ape) {
     const { send, checkReply, events, controllers, sharedValues, hostId, embedValues, fileTransfer } = ape
 
+    // Extract sessionId from request cookies (set by outer framework session management)
+    const sessionId = getSessionId(sharedValues.req)
+
     // Build `this` context for controllers
     // Includes: client metadata + api-ape utilities
     const that = {
@@ -102,7 +114,8 @@ module.exports = function receiveHandler(ape) {
         broadcastOthers: (type, data) => broadcast(type, data, hostId), // exclude self
         online,
         getClients,
-        hostId
+        hostId,
+        sessionId  // Session ID from cookie (set by outer framework)
     }
 
     return async function onReceive(msg) {

package/server/socket/send.js

@@ -40,7 +40,7 @@ function detectContentType(data) {
  * Process data object, replacing binary values with L-tagged hashes
  * Returns { processedData, binaryEntries }
  */
-function processBinaryData(data, queryId, fileTransfer, hostId, path = '') {
+function processBinaryData(data, queryId, fileTransfer, clientId, path = '') {
   if (data === null || data === undefined) {
     return { processedData: data, binaryEntries: [] }
   }
@@ -49,7 +49,7 @@ function processBinaryData(data, queryId, fileTransfer, hostId, path = '') {
     // This is binary data - register and return hash
     const hash = FileTransferManager.generateHash(queryId, path || 'root')
     const contentType = detectContentType(data)
-    fileTransfer.registerDownload(hash, data, contentType, hostId)
+    fileTransfer.registerDownload(hash, data, contentType, clientId)
 
     return {
       processedData: { [`__ape_link__`]: hash },
@@ -64,7 +64,7 @@ function processBinaryData(data, queryId, fileTransfer, hostId, path = '') {
     for (let i = 0; i < data.length; i++) {
       const itemPath = path ? `${path}.${i}` : String(i)
       const { processedData, binaryEntries } = processBinaryData(
-        data[i], queryId, fileTransfer, hostId, itemPath
+        data[i], queryId, fileTransfer, clientId, itemPath
       )
       processedArray.push(processedData)
       allBinaryEntries.push(...binaryEntries)
@@ -80,7 +80,7 @@ function processBinaryData(data, queryId, fileTransfer, hostId, path = '') {
     for (const key of Object.keys(data)) {
       const itemPath = path ? `${path}.${key}` : key
       const { processedData, binaryEntries } = processBinaryData(
-        data[key], queryId, fileTransfer, hostId, itemPath
+        data[key], queryId, fileTransfer, clientId, itemPath
       )
 
       // If this was binary data, mark the key with <!L> tag
@@ -99,7 +99,7 @@ function processBinaryData(data, queryId, fileTransfer, hostId, path = '') {
   return { processedData: data, binaryEntries: [] }
 }
 
-module.exports = function sendHandler({ socket, events, hostId, fileTransfer }) {
+module.exports = function sendHandler({ socket, events, clientId, fileTransfer }) {
 
   return function send(queryId, type, data, err) {
     if (!type && !queryId) {
@@ -130,7 +130,7 @@ module.exports = function sendHandler({ socket, events, hostId, fileTransfer })
     let processedData = data
     if (fileTransfer && data && !err) {
       const { processedData: processed, binaryEntries } = processBinaryData(
-        data, queryId || type, fileTransfer, hostId
+        data, queryId || type, fileTransfer, clientId
       )
       processedData = processed
       if (binaryEntries.length > 0) {

package/server/utils/deepRequire.js

@@ -1,4 +1,4 @@
-if(!global.process){//(!!process && typeof process !== 'object'){
+if (!global.process) {//(!!process && typeof process !== 'object'){
   throw new Error("deepRequire need to be run on Node server")
 }
 
@@ -18,7 +18,7 @@ function getFilesFromDir(dir, fileTypes) {
       if (fs.statSync(curFile).isFile() && fileTypes.indexOf(path.extname(curFile)) != -1) {
         filesToReturn.push(curFile.replace(dir, ''));
       } else if (fs.statSync(curFile).isDirectory()) {
-       walkDir(curFile);
+        walkDir(curFile);
       }
     }
   };
@@ -27,19 +27,34 @@ function getFilesFromDir(dir, fileTypes) {
 }
 const re = /(?:\.([^.]+))?$/;
 
-module.exports = function(dirname,selector){
+module.exports = function (dirname, selector) {
   selector = selector || ["js"]
-  return getFilesFromDir(dirname, selector.map(ext=>`.${ext}`)).reduce((packages,file) =>{
+  const endpointSources = {} // Track which file defines each endpoint
 
-    if(file === "/index.js")  return packages
+  return getFilesFromDir(dirname, selector.map(ext => `.${ext}`)).reduce((packages, file) => {
+
+    if (file === "/index.js") return packages
     //if(file[0] !== "/") file = "/"+file;
 
-    const pathParts = file.replace(re.exec(file)[0],"").split("/").slice(1)
-    if(pathParts[pathParts.length-1] === "index")
-    pathParts.pop()
+    const pathParts = file.replace(re.exec(file)[0], "").split("/").slice(1)
+    if (pathParts[pathParts.length - 1] === "index")
+      pathParts.pop()
+
+    const endpoint = pathParts.join("/").toLowerCase()
+
+    // Check for duplicate endpoints
+    if (packages[endpoint] !== undefined) {
+      throw new Error(
+        `🦍 Duplicate endpoint detected: "${endpoint}"\n` +
+        `   - ${endpointSources[endpoint]}\n` +
+        `   - ${file}\n` +
+        `   Remove one of these files to fix this conflict.`
+      )
+    }
 
-    packages[pathParts.join("/").toLowerCase()] = require(dirname+`/${file}`)
+    endpointSources[endpoint] = file
+    packages[endpoint] = require(dirname + `/${file}`)
     return packages;
-  },{});
+  }, {});
 
 }