api-ape 2.0.0 → 2.2.2

package/server/lib/ws/adapters/bun.js

@@ -0,0 +1,225 @@
+/**
+ * Bun Native WebSocket Adapter
+ * Wraps Bun's ServerWebSocket to be compatible with the ws library API
+ * 
+ * Bun uses a different pattern:
+ * - Bun.serve({ websocket: { open, message, close, ... } })
+ * - server.upgrade(req) to upgrade connections
+ * 
+ * This adapter provides a ws-compatible WebSocketServer that works
+ * with the existing api-ape code.
+ */
+
+const { EventEmitter } = require('events')
+
+// WebSocket ready states (matching ws library)
+const READY_STATES = {
+    CONNECTING: 0,
+    OPEN: 1,
+    CLOSING: 2,
+    CLOSED: 3
+}
+
+/**
+ * Wrapper around Bun's ServerWebSocket to provide ws-compatible API
+ */
+class BunWebSocket extends EventEmitter {
+    constructor(bunSocket) {
+        super()
+        this._socket = bunSocket
+        this._readyState = READY_STATES.OPEN
+
+        // 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
+    }
+
+    get readyState() {
+        return this._readyState
+    }
+
+    /**
+     * Send data to the client
+     * @param {string|Buffer|ArrayBuffer} data - Data to send
+     */
+    send(data) {
+        if (this._readyState !== READY_STATES.OPEN) {
+            throw new Error('WebSocket is not open')
+        }
+        this._socket.send(data)
+    }
+
+    /**
+     * 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
+        this._socket.close(code, reason)
+    }
+
+    /**
+     * Called by BunWebSocketServer when message received
+     * @internal
+     */
+    _onMessage(data) {
+        // Convert to Buffer for consistency with ws library
+        const buffer = Buffer.isBuffer(data) ? data : Buffer.from(data)
+        this.emit('message', buffer)
+    }
+
+    /**
+     * Called by BunWebSocketServer when connection closed
+     * @internal
+     */
+    _onClose(code, reason) {
+        this._readyState = READY_STATES.CLOSED
+        this.emit('close', code, reason)
+    }
+
+    /**
+     * Called by BunWebSocketServer on error
+     * @internal
+     */
+    _onError(error) {
+        this.emit('error', error)
+    }
+}
+
+/**
+ * WebSocketServer compatible with Bun's server.upgrade() pattern
+ * 
+ * Usage in main.js:
+ * - Create BunWebSocketServer
+ * - It provides the websocket handlers for Bun.serve()
+ * - Call handleUpgrade() when upgrade request received
+ */
+class BunWebSocketServer extends EventEmitter {
+    constructor(options = {}) {
+        super()
+        this._noServer = options.noServer || false
+        this._clients = new Map() // Map socket -> BunWebSocket wrapper
+
+        // Bun websocket handler configuration
+        // This will be used by the integration in main.js
+        this.websocketHandlers = {
+            open: (ws) => this._handleOpen(ws),
+            message: (ws, message) => this._handleMessage(ws, message),
+            close: (ws, code, reason) => this._handleClose(ws, code, reason),
+            error: (ws, error) => this._handleError(ws, error)
+        }
+    }
+
+    /**
+     * Get all connected clients
+     * @returns {Set<BunWebSocket>}
+     */
+    get clients() {
+        return new Set(this._clients.values())
+    }
+
+    /**
+     * Handle upgrade request - called from main.js
+     * For Bun, we need to return info for the upgrade
+     * @param {Request} req - Bun Request object
+     * @param {*} server - Bun server instance
+     * @param {*} head - Not used in Bun
+     * @param {function} callback - Called with wrapped WebSocket
+     */
+    handleUpgrade(req, server, head, callback) {
+        // In Bun, we store the callback and req info
+        // The actual upgrade happens via server.upgrade()
+        // The callback will be called in _handleOpen when Bun calls our open handler
+
+        // Store pending upgrade info keyed by some identifier
+        // Bun's server.upgrade() succeeds/fails synchronously
+        const upgraded = server.upgrade(req, {
+            data: { callback, req }
+        })
+
+        if (!upgraded) {
+            // Upgrade failed
+            return false
+        }
+
+        return true
+    }
+
+    /**
+     * Handle Bun websocket open event
+     * @internal
+     */
+    _handleOpen(bunSocket) {
+        const wrapper = new BunWebSocket(bunSocket)
+        this._clients.set(bunSocket, wrapper)
+
+        // Get the callback from upgrade data
+        const { callback, req } = bunSocket.data || {}
+
+        if (callback) {
+            callback(wrapper)
+        }
+
+        // Emit connection event
+        this.emit('connection', wrapper, req)
+    }
+
+    /**
+     * Handle Bun websocket message event
+     * @internal
+     */
+    _handleMessage(bunSocket, message) {
+        const wrapper = this._clients.get(bunSocket)
+        if (wrapper) {
+            wrapper._onMessage(message)
+        }
+    }
+
+    /**
+     * Handle Bun websocket close event
+     * @internal
+     */
+    _handleClose(bunSocket, code, reason) {
+        const wrapper = this._clients.get(bunSocket)
+        if (wrapper) {
+            wrapper._onClose(code, reason)
+            this._clients.delete(bunSocket)
+        }
+    }
+
+    /**
+     * Handle Bun websocket error event
+     * @internal
+     */
+    _handleError(bunSocket, error) {
+        const wrapper = this._clients.get(bunSocket)
+        if (wrapper) {
+            wrapper._onError(error)
+        }
+    }
+
+    /**
+     * Close server and all connections
+     */
+    close(callback) {
+        for (const [bunSocket, wrapper] of this._clients) {
+            wrapper.close(1001, 'Server shutting down')
+        }
+        this._clients.clear()
+        if (callback) {
+            callback()
+        }
+    }
+}
+
+module.exports = {
+    BunWebSocket,
+    BunWebSocketServer
+}

package/server/lib/ws/adapters/deno.js

@@ -0,0 +1,186 @@
+/**
+ * Deno Native WebSocket Adapter
+ * Wraps Deno's native WebSocket to be compatible with the ws library API
+ * 
+ * Deno uses a different pattern:
+ * - Deno.serve() with Deno.upgradeWebSocket(req)
+ * - Returns { socket, response } where socket is a standard WebSocket
+ * 
+ * This adapter provides a ws-compatible WebSocketServer that works
+ * with the existing api-ape code.
+ */
+
+const { EventEmitter } = require('events')
+
+// WebSocket ready states (matching ws library)
+const READY_STATES = {
+    CONNECTING: 0,
+    OPEN: 1,
+    CLOSING: 2,
+    CLOSED: 3
+}
+
+/**
+ * Wrapper around Deno's native WebSocket to provide ws-compatible API
+ * Deno's WebSocket uses onmessage/onclose properties instead of EventEmitter
+ */
+class DenoWebSocket extends EventEmitter {
+    constructor(denoSocket) {
+        super()
+        this._socket = denoSocket
+        this._readyState = READY_STATES.OPEN
+
+        // 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
+
+        // Wire up Deno's event properties to our EventEmitter
+        this._setupDenoEvents()
+    }
+
+    get readyState() {
+        return this._readyState
+    }
+
+    /**
+     * Setup Deno WebSocket event handlers
+     * @internal
+     */
+    _setupDenoEvents() {
+        this._socket.onmessage = (event) => {
+            // Convert to Buffer for consistency with ws library
+            const data = event.data
+            const buffer = typeof data === 'string'
+                ? Buffer.from(data)
+                : Buffer.from(data)
+            this.emit('message', buffer)
+        }
+
+        this._socket.onclose = (event) => {
+            this._readyState = READY_STATES.CLOSED
+            this.emit('close', event.code, event.reason)
+        }
+
+        this._socket.onerror = (event) => {
+            this.emit('error', event)
+        }
+    }
+
+    /**
+     * Send data to the client
+     * @param {string|Buffer|ArrayBuffer} data - Data to send
+     */
+    send(data) {
+        if (this._readyState !== READY_STATES.OPEN) {
+            throw new Error('WebSocket is not open')
+        }
+        // Deno's WebSocket.send() accepts string, ArrayBuffer, or Blob
+        if (Buffer.isBuffer(data)) {
+            this._socket.send(data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength))
+        } else {
+            this._socket.send(data)
+        }
+    }
+
+    /**
+     * 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
+        this._socket.close(code, reason)
+    }
+}
+
+/**
+ * WebSocketServer compatible with Deno's Deno.upgradeWebSocket() pattern
+ * 
+ * Usage in main.js:
+ * - Create DenoWebSocketServer
+ * - Call handleUpgrade() when upgrade request received
+ * - It uses Deno.upgradeWebSocket() internally
+ */
+class DenoWebSocketServer extends EventEmitter {
+    constructor(options = {}) {
+        super()
+        this._noServer = options.noServer || false
+        this._clients = new Set()
+    }
+
+    /**
+     * Get all connected clients
+     * @returns {Set<DenoWebSocket>}
+     */
+    get clients() {
+        return this._clients
+    }
+
+    /**
+     * Handle upgrade request using Deno.upgradeWebSocket
+     * @param {Request} req - Deno Request object
+     * @param {*} _socket - Not used in Deno (placeholder for API compat)
+     * @param {*} _head - Not used in Deno (placeholder for API compat)
+     * @param {function} callback - Called with wrapped WebSocket
+     * @returns {{ response: Response } | null} - Response to return from handler
+     */
+    handleUpgrade(req, _socket, _head, callback) {
+        // Check for upgrade header
+        const upgrade = req.headers.get('upgrade')
+        if (!upgrade || upgrade.toLowerCase() !== 'websocket') {
+            return null
+        }
+
+        try {
+            // Use Deno's built-in upgrade
+            const { socket: denoSocket, response } = Deno.upgradeWebSocket(req)
+
+            // Wrap with our adapter
+            const wrapper = new DenoWebSocket(denoSocket)
+            this._clients.add(wrapper)
+
+            // Remove from clients on close
+            wrapper.on('close', () => {
+                this._clients.delete(wrapper)
+            })
+
+            // Call the callback with wrapped socket
+            if (callback) {
+                callback(wrapper)
+            }
+
+            // Emit connection event
+            this.emit('connection', wrapper, req)
+
+            // Return the response for Deno's handler
+            return { response }
+        } catch (err) {
+            console.error('[api-ape] Deno WebSocket upgrade failed:', err)
+            return null
+        }
+    }
+
+    /**
+     * 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 = {
+    DenoWebSocket,
+    DenoWebSocketServer
+}

package/server/lib/ws/frames.js

@@ -0,0 +1,217 @@
+/**
+ * RFC 6455 WebSocket Frame Encoding/Decoding
+ * 
+ * Frame format:
+ *  0                   1                   2                   3
+ *  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+ * +-+-+-+-+-------+-+-------------+-------------------------------+
+ * |F|R|R|R| opcode|M| Payload len |    Extended payload length    |
+ * |I|S|S|S|  (4)  |A|     (7)     |            (16/64)            |
+ * |N|V|V|V|       |S|             |   (if payload len==126/127)   |
+ * | |1|2|3|       |K|             |                               |
+ * +-+-+-+-+-------+-+-------------+-------------------------------+
+ * |     Extended payload length continued, if payload len == 127  |
+ * +-------------------------------+-------------------------------+
+ * |                               | Masking-key, if MASK set to 1 |
+ * +-------------------------------+-------------------------------+
+ * | Masking-key (continued)       |          Payload Data         |
+ * +-------------------------------+-------------------------------+
+ */
+
+const crypto = require('crypto')
+
+// WebSocket GUID for handshake (RFC 6455 Section 1.3)
+const WS_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'
+
+// Opcodes
+const OPCODES = {
+    CONTINUATION: 0x00,
+    TEXT: 0x01,
+    BINARY: 0x02,
+    CLOSE: 0x08,
+    PING: 0x09,
+    PONG: 0x0A
+}
+
+/**
+ * Generate the Sec-WebSocket-Accept header value from client key
+ * @param {string} clientKey - The Sec-WebSocket-Key from client
+ * @returns {string} Base64 encoded accept key
+ */
+function generateAcceptKey(clientKey) {
+    return crypto
+        .createHash('sha1')
+        .update(clientKey + WS_GUID)
+        .digest('base64')
+}
+
+/**
+ * Unmask payload data (client → server messages are always masked)
+ * @param {Buffer} payload - The masked payload
+ * @param {Buffer} maskKey - 4-byte mask key
+ * @returns {Buffer} Unmasked payload
+ */
+function unmaskPayload(payload, maskKey) {
+    const result = Buffer.alloc(payload.length)
+    for (let i = 0; i < payload.length; i++) {
+        result[i] = payload[i] ^ maskKey[i & 3]
+    }
+    return result
+}
+
+/**
+ * Parse a WebSocket frame from buffer
+ * @param {Buffer} buffer - Raw data buffer
+ * @returns {{ frame: Object, bytesConsumed: number } | null} Parsed frame or null if incomplete
+ */
+function parseFrame(buffer) {
+    if (buffer.length < 2) return null
+
+    let offset = 0
+    const firstByte = buffer[offset++]
+    const secondByte = buffer[offset++]
+
+    const fin = (firstByte & 0x80) !== 0
+    const opcode = firstByte & 0x0F
+    const masked = (secondByte & 0x80) !== 0
+    let payloadLength = secondByte & 0x7F
+
+    // Extended payload length
+    if (payloadLength === 126) {
+        if (buffer.length < offset + 2) return null
+        payloadLength = buffer.readUInt16BE(offset)
+        offset += 2
+    } else if (payloadLength === 127) {
+        if (buffer.length < offset + 8) return null
+        // JavaScript can't handle full 64-bit, use lower 32 bits
+        const high = buffer.readUInt32BE(offset)
+        const low = buffer.readUInt32BE(offset + 4)
+        if (high !== 0) {
+            throw new Error('Payload too large')
+        }
+        payloadLength = low
+        offset += 8
+    }
+
+    // Mask key (4 bytes, only if masked)
+    let maskKey = null
+    if (masked) {
+        if (buffer.length < offset + 4) return null
+        maskKey = buffer.slice(offset, offset + 4)
+        offset += 4
+    }
+
+    // Payload
+    if (buffer.length < offset + payloadLength) return null
+    let payload = buffer.slice(offset, offset + payloadLength)
+    offset += payloadLength
+
+    // Unmask if needed
+    if (masked && maskKey) {
+        payload = unmaskPayload(payload, maskKey)
+    }
+
+    return {
+        frame: { fin, opcode, payload },
+        bytesConsumed: offset
+    }
+}
+
+/**
+ * Build a WebSocket frame
+ * Server → client frames are never masked (per RFC 6455)
+ * @param {Buffer|string} data - Payload data
+ * @param {number} opcode - Frame opcode
+ * @param {boolean} fin - Is this the final frame?
+ * @returns {Buffer} Complete frame buffer
+ */
+function buildFrame(data, opcode = OPCODES.TEXT, fin = true) {
+    const payload = Buffer.isBuffer(data) ? data : Buffer.from(data)
+    const payloadLength = payload.length
+
+    // Calculate header size
+    let headerSize = 2 // First two bytes
+    let extendedLengthSize = 0
+
+    if (payloadLength > 65535) {
+        extendedLengthSize = 8
+    } else if (payloadLength > 125) {
+        extendedLengthSize = 2
+    }
+
+    const frame = Buffer.alloc(headerSize + extendedLengthSize + payloadLength)
+    let offset = 0
+
+    // First byte: FIN + opcode
+    frame[offset++] = (fin ? 0x80 : 0x00) | opcode
+
+    // Second byte: mask bit (0) + payload length
+    if (payloadLength > 65535) {
+        frame[offset++] = 127
+        // Write 64-bit length (high 32 bits = 0)
+        frame.writeUInt32BE(0, offset)
+        offset += 4
+        frame.writeUInt32BE(payloadLength, offset)
+        offset += 4
+    } else if (payloadLength > 125) {
+        frame[offset++] = 126
+        frame.writeUInt16BE(payloadLength, offset)
+        offset += 2
+    } else {
+        frame[offset++] = payloadLength
+    }
+
+    // Payload (no masking for server → client)
+    payload.copy(frame, offset)
+
+    return frame
+}
+
+/**
+ * Build a close frame with optional status code and reason
+ * @param {number} code - Status code (1000 = normal)
+ * @param {string} reason - Close reason
+ * @returns {Buffer} Close frame
+ */
+function buildCloseFrame(code = 1000, reason = '') {
+    const reasonBuffer = Buffer.from(reason)
+    const payload = Buffer.alloc(2 + reasonBuffer.length)
+    payload.writeUInt16BE(code, 0)
+    reasonBuffer.copy(payload, 2)
+    return buildFrame(payload, OPCODES.CLOSE)
+}
+
+/**
+ * Build a pong frame in response to ping
+ * @param {Buffer} data - Ping payload to echo back
+ * @returns {Buffer} Pong frame
+ */
+function buildPongFrame(data) {
+    return buildFrame(data, OPCODES.PONG)
+}
+
+/**
+ * Parse close frame payload
+ * @param {Buffer} payload - Close frame payload
+ * @returns {{ code: number, reason: string }}
+ */
+function parseClosePayload(payload) {
+    if (payload.length >= 2) {
+        return {
+            code: payload.readUInt16BE(0),
+            reason: payload.slice(2).toString('utf8')
+        }
+    }
+    return { code: 1005, reason: '' }
+}
+
+module.exports = {
+    OPCODES,
+    generateAcceptKey,
+    parseFrame,
+    buildFrame,
+    buildCloseFrame,
+    buildPongFrame,
+    parseClosePayload,
+    unmaskPayload
+}

package/server/lib/ws/index.js

@@ -0,0 +1,15 @@
+/**
+ * WebSocket polyfill entry point
+ * Provides WebSocketServer compatible with the ws library API
+ */
+
+const { WebSocketServer } = require('./server')
+const { WebSocket, READY_STATES } = require('./socket')
+const { OPCODES } = require('./frames')
+
+module.exports = {
+    WebSocketServer,
+    WebSocket,
+    READY_STATES,
+    OPCODES
+}