api-ape 3.0.2 → 4.1.0

package/server/lib/main.js

@@ -1,561 +1,398 @@
-const loader = require('./loader')
-const wiring = require('./wiring')
-const { getWebSocketProvider, isBun, isDeno, getRuntime } = require('./wsProvider')
-const path = require('path')
-const fs = require('fs')
-const { getFileTransferManager } = require('./fileTransfer')
-const { createLongPollingHandler } = require('./longPolling')
-const { parse: parseUrl } = require('url')
-
-let created = false
-
 /**
- * Parse URL path parameters like /api/ape/data/:hash
- * Returns null if pattern doesn't match, or object with params if it does
+ * @fileoverview Main api-ape Server Entry Point
+ *
+ * This module provides the unified entry point for initializing api-ape on any
+ * supported server platform. It handles runtime detection, WebSocket setup,
+ * controller loading, and HTTP endpoint configuration.
+ *
+ * ## Supported Runtimes
+ *
+ * | Runtime   | WebSocket Provider        | Notes                        |
+ * |-----------|---------------------------|------------------------------|
+ * | Node.js   | Polyfill or native (v24+) | Full feature support         |
+ * | Bun       | Native Bun WebSocket      | High performance             |
+ * | Deno      | Native Deno WebSocket     | Via adapter                  |
+ *
+ * ## Initialization Flow
+ *
+ * ```
+ * ape(server, options)
+ *       │
+ *       ▼
+ * ┌─────────────────────────────────────────────────────┐
+ * │  createApeCore(options)                             │
+ * │  ├── Load controllers from 'where' directory       │
+ * │  ├── Initialize file transfer manager              │
+ * │  ├── Create WebSocket wiring handler               │
+ * │  └── Create HTTP long-polling handlers             │
+ * └─────────────────────────────────────────────────────┘
+ *       │
+ *       ▼
+ * ┌─────────────────────────────────────────────────────┐
+ * │  Detect Server Type                                │
+ * │  ├── Bun.serve() server → initBunServerWithReload  │
+ * │  └── Node.js http.Server → initNodeServer          │
+ * └─────────────────────────────────────────────────────┘
+ *       │
+ *       ▼
+ * ┌─────────────────────────────────────────────────────┐
+ * │  Server Running                                    │
+ * │  ├── WebSocket: /api/ape (or custom path)          │
+ * │  ├── Long-poll: /api/ape/poll                      │
+ * │  ├── Ping: /api/ape/ping                           │
+ * │  ├── Client bundle: /api/ape.js                    │
+ * │  └── File transfer: /api/ape/data/:hash            │
+ * └─────────────────────────────────────────────────────┘
+ * ```
+ *
+ * ## HTTP Endpoints Created
+ *
+ * | Endpoint                    | Method | Description                    |
+ * |-----------------------------|--------|--------------------------------|
+ * | `/{where}/ape`              | WS     | WebSocket connection endpoint  |
+ * | `/{where}/ape/poll`         | GET    | HTTP streaming (long-poll)     |
+ * | `/{where}/ape/poll`         | POST   | Send message via HTTP          |
+ * | `/{where}/ape/ping`         | GET    | Connection health check        |
+ * | `/{where}/ape.js`           | GET    | Client JavaScript bundle       |
+ * | `/{where}/ape.js.map`       | GET    | Source map for debugging       |
+ * | `/{where}/ape/data/:hash`   | GET    | Download binary data           |
+ * | `/{where}/ape/data/:qid/:h` | PUT    | Upload binary data             |
+ *
+ * @module server/lib/main
+ * @see {@link module:server/lib/wiring} for WebSocket connection handling
+ * @see {@link module:server/lib/loader} for controller loading
+ * @see {@link module:server/lib/longPolling} for HTTP fallback
+ *
+ * @example <caption>Basic Node.js Setup</caption>
+ * const http = require('http')
+ * const ape = require('api-ape/server/lib/main')
+ *
+ * const server = http.createServer()
+ *
+ * ape(server, {
+ *   where: 'api',  // Load controllers from ./api directory
+ *   onConnect: (socket, req, send) => ({
+ *     embed: { userId: getUserFromRequest(req) }
+ *   })
+ * })
+ *
+ * server.listen(3000)
+ *
+ * @example <caption>Express Integration</caption>
+ * const express = require('express')
+ * const ape = require('api-ape/server/lib/main')
+ *
+ * const app = express()
+ * const server = app.listen(3000)
+ *
+ * ape(server, {
+ *   where: 'api',
+ *   onConnect: async (socket, req, send) => {
+ *     const session = await validateSession(req)
+ *     return {
+ *       embed: { user: session.user, permissions: session.permissions },
+ *       onDisconnect: () => logDisconnect(session.user)
+ *     }
+ *   }
+ * })
+ *
+ * @example <caption>Bun Server</caption>
+ * const ape = require('api-ape/server/lib/main')
+ *
+ * const server = Bun.serve({
+ *   port: 3000,
+ *   fetch(req) { return new Response('Hello') },
+ *   websocket: { message() {} }  // Required for api-ape
+ * })
+ *
+ * ape(server, { where: 'api' })
  */
-function matchRoute(pathname, pattern) {
-    const patternParts = pattern.split('/')
-    const pathParts = pathname.split('/')
-
-    if (patternParts.length !== pathParts.length) {
-        return null
-    }
 
-    const params = {}
-    for (let i = 0; i < patternParts.length; i++) {
-        if (patternParts[i].startsWith(':')) {
-            params[patternParts[i].slice(1)] = pathParts[i]
-        } else if (patternParts[i] !== pathParts[i]) {
-            return null
-        }
-    }
-    return params
-}
-
-/**
- * Send JSON response (Node.js style)
- */
-function sendJson(res, statusCode, data) {
-    res.writeHead(statusCode, { 'Content-Type': 'application/json' })
-    res.end(JSON.stringify(data))
-}
-
-/**
- * Get cookie value from request headers
- */
-function getCookie(headers, name) {
-    const cookies = typeof headers.get === 'function'
-        ? headers.get('cookie')
-        : headers.cookie
-    if (!cookies) return null
-    const match = cookies.match(new RegExp(`(?:^|;\\s*)${name}=([^;]*)`))
-    return match ? match[1] : null
-}
+const loader = require("./loader");
+const wiring = require("./wiring");
+const { isBun, isDeno, getRuntime } = require("./wsProvider");
+const { getFileTransferManager } = require("./fileTransfer");
+const { createLongPollingHandler } = require("./longPolling");
+const { initNodeServer } = require("./runtimes/node");
+const { isBunServer, initBunServerWithReload } = require("./runtimes/bun");
 
 /**
- * Check if request is from localhost
+ * Flag to track whether api-ape has been initialized
+ *
+ * Prevents multiple initializations which could cause conflicts
+ * with WebSocket handlers and HTTP routes.
+ *
+ * @type {boolean}
+ * @private
  */
-function isLocalhost(host) {
-    const hostname = host?.split(':')[0] || ''
-    return ['localhost', '127.0.0.1', '[::1]'].includes(hostname)
-}
+let created = false;
 
 /**
- * Check if connection is secure (HTTPS)
+ * Reset the singleton state for testing purposes.
+ * This allows creating multiple server instances in test environments.
+ *
+ * @private
+ * @function _resetForTesting
  */
-function isSecure(req) {
-    if (typeof req.headers?.get === 'function') {
-        return req.headers.get('x-forwarded-proto') === 'https'
-    }
-    return req.socket?.encrypted || req.headers?.['x-forwarded-proto'] === 'https'
+function _resetForTesting() {
+  created = false;
 }
 
 /**
- * Create core api-ape handlers (shared between runtimes)
+ * Create the core api-ape handlers shared between all runtimes
+ *
+ * This function initializes the components needed regardless of the
+ * server runtime (Node.js, Bun, Deno):
+ * - Controller loading from the specified directory
+ * - File transfer manager for binary data
+ * - WebSocket message handler (wiring)
+ * - HTTP long-polling handlers for fallback transport
+ * - URL path patterns for all endpoints
+ *
+ * @param {Object} options - Configuration options
+ * @param {string} options.where - Directory containing API controllers (relative to CWD)
+ * @param {Function} [options.onConnect] - Connection lifecycle callback
+ * @param {Object} [options.fileTransferOptions] - File transfer configuration
+ * @param {number} [options.fileTransferOptions.startTimeout=60000] - Timeout before upload starts
+ * @param {number} [options.fileTransferOptions.completeTimeout=60000] - Timeout for upload completion
+ * @param {Object} [options.longPollingOptions] - Long polling configuration
+ * @param {number} [options.longPollingOptions.heartbeatInterval=20000] - Interval in ms for heartbeat pings
+ * @param {number} [options.longPollingOptions.recycleTimeout=25000] - Timeout in ms before recycling connection
+ * @returns {ApeCore} Core handlers and path patterns
+ *
+ * @typedef {Object} ApeCore
+ * @property {Object} controllers - Loaded controller functions keyed by endpoint path
+ * @property {FileTransferManager} fileTransfer - Binary data transfer manager
+ * @property {Function} wiringHandler - WebSocket connection handler
+ * @property {Function} handleStreamGet - HTTP GET handler for long-polling
+ * @property {Function} handleStreamPost - HTTP POST handler for sending messages
+ * @property {string} wsPath - WebSocket endpoint path (e.g., '/api/ape')
+ * @property {string} pollPath - Long-polling endpoint path
+ * @property {string} pingPath - Health check endpoint path
+ * @property {string} clientPath - Client bundle endpoint path
+ * @property {string} clientMapPath - Source map endpoint path
+ * @property {string} downloadPattern - Binary download URL pattern
+ * @property {string} uploadPattern - Binary upload URL pattern
+ *
+ * @private
+ *
+ * @example
+ * const core = createApeCore({
+ *   where: 'api',
+ *   onConnect: myConnectHandler,
+ *   fileTransferOptions: { startTimeout: 30000 }
+ * })
+ *
+ * // core.controllers = { 'users': [Function], 'chat': [Function], ... }
+ * // core.wsPath = '/api/ape'
  */
-function createApeCore({ where, onConnect, fileTransferOptions }) {
-    const controllers = loader(where)
-    const fileTransfer = getFileTransferManager(fileTransferOptions)
-    const wiringHandler = wiring(controllers, onConnect, fileTransfer)
-    const { handleStreamGet, handleStreamPost } = createLongPollingHandler(controllers, onConnect, fileTransfer)
-
-    const wsPath = `/${where}/ape`
-    const pollPath = `/${where}/ape/poll`
-    const pingPath = `/${where}/ape/ping`
-    const clientPath = `/${where}/ape.js`
-    const clientMapPath = `/${where}/ape.js.map`
-    const downloadPattern = `/${where}/ape/data/:hash`
-    const uploadPattern = `/${where}/ape/data/:queryId/:pathHash`
-
-    return {
-        controllers,
-        fileTransfer,
-        wiringHandler,
-        handleStreamGet,
-        handleStreamPost,
-        wsPath,
-        pollPath,
-        pingPath,
-        clientPath,
-        clientMapPath,
-        downloadPattern,
-        uploadPattern
-    }
+function createApeCore({ where, onConnect, fileTransferOptions, longPollingOptions }) {
+  const controllers = loader(where);
+  const fileTransfer = getFileTransferManager(fileTransferOptions);
+  const wiringHandler = wiring(controllers, onConnect, fileTransfer);
+  const { handleStreamGet, handleStreamPost } = createLongPollingHandler(
+    controllers,
+    onConnect,
+    fileTransfer,
+    longPollingOptions,
+  );
+
+  return {
+    controllers,
+    fileTransfer,
+    wiringHandler,
+    handleStreamGet,
+    handleStreamPost,
+    wsPath: `/${where}/ape`,
+    pollPath: `/${where}/ape/poll`,
+    pingPath: `/${where}/ape/ping`,
+    clientPath: `/${where}/ape.js`,
+    clientMapPath: `/${where}/ape.js.map`,
+    downloadPattern: `/${where}/ape/data/:hash`,
+    uploadPattern: `/${where}/ape/data/:queryId/:pathHash`,
+  };
 }
 
 /**
- * Node.js / Express integration
- * Uses server.on('upgrade') and server.on('request')
+ * Initialize api-ape on an HTTP server
+ *
+ * This is the main entry point for setting up api-ape. It:
+ * 1. Validates that api-ape hasn't already been initialized
+ * 2. Creates core handlers (controllers, WebSocket, HTTP)
+ * 3. Detects the server type (Node.js, Bun)
+ * 4. Initializes the appropriate runtime-specific handlers
+ *
+ * ## Options
+ *
+ * | Option               | Type     | Description                                |
+ * |----------------------|----------|--------------------------------------------|
+ * | `where`              | string   | Directory containing API controllers       |
+ * | `onConnect`          | Function | Called when a client connects              |
+ * | `fileTransferOptions`| Object   | Binary file transfer configuration         |
+ * | `transport`          | string   | Force transport: 'websocket' or 'longpolling' |
+ *
+ * ## onConnect Callback
+ *
+ * The `onConnect` function is called for each new WebSocket connection.
+ * It receives `(socket, req, send)` and should return an options object:
+ *
+ * ```javascript
+ * onConnect: (socket, req, send) => ({
+ *   embed: { userId: '123' },      // Values available in all controllers as `this`
+ *   onReceive: (queryId, data, type) => { },  // Called when message received
+ *   onSend: (data, type) => { },              // Called when message sent
+ *   onError: (errorString) => { },            // Called on errors
+ *   onDisconnect: () => { }                   // Called when client disconnects
+ * })
+ * ```
+ *
+ * @param {http.Server|Object} server - HTTP server instance (Node.js or Bun)
+ * @param {Object} options - Configuration options
+ * @param {string} options.where - Directory containing API controller files
+ * @param {Function} [options.onConnect] - Connection lifecycle callback
+ * @param {Object} [options.fileTransferOptions] - File transfer settings
+ * @param {string} [options.transport] - Force specific transport mode
+ * @returns {Object} Server information including WebSocket server instance
+ * @throws {Error} If api-ape has already been initialized
+ * @throws {Error} If server type is not supported
+ *
+ * @example <caption>Minimal Setup</caption>
+ * const http = require('http')
+ * const ape = require('api-ape/server/lib/main')
+ *
+ * const server = http.createServer()
+ * ape(server, { where: 'api' })
+ * server.listen(3000)
+ *
+ * @example <caption>Full Configuration</caption>
+ * ape(server, {
+ *   where: 'api',
+ *
+ *   onConnect: async (socket, req, send) => {
+ *     // Authenticate user from request
+ *     const token = req.headers.cookie?.match(/token=([^;]+)/)?.[1]
+ *     const user = await verifyToken(token)
+ *
+ *     if (!user) {
+ *       socket.close(4001, 'Unauthorized')
+ *       return null
+ *     }
+ *
+ *     // Send welcome message
+ *     send('welcome', { message: `Hello, ${user.name}!` })
+ *
+ *     return {
+ *       embed: {
+ *         user,
+ *         permissions: user.roles
+ *       },
+ *       onReceive: (queryId, data, type) => {
+ *         console.log(`[${user.name}] ${type}:`, data)
+ *       },
+ *       onDisconnect: () => {
+ *         console.log(`[${user.name}] disconnected`)
+ *       }
+ *     }
+ *   },
+ *
+ *   fileTransferOptions: {
+ *     startTimeout: 30000,
+ *     completeTimeout: 120000
+ *   }
+ * })
+ *
+ * @example <caption>Controller File Structure</caption>
+ * // api/users.js - handles /users endpoint
+ * module.exports = async function(data) {
+ *   // `this` contains embed values from onConnect
+ *   const { user, permissions } = this
+ *
+ *   if (!permissions.includes('users:read')) {
+ *     throw new Error('Permission denied')
+ *   }
+ *
+ *   return await db.users.find(data.query)
+ * }
+ *
+ * // api/users/profile.js - handles /users/profile endpoint
+ * module.exports = async function(data) {
+ *   return await db.users.findById(this.user.id)
+ * }
  */
-function initNodeServer(server, options) {
-    const { WebSocketServer } = getWebSocketProvider()
-    const core = createApeCore(options)
-    const { where } = options
-
-    const wss = new WebSocketServer({ noServer: true })
-    wss.on('connection', core.wiringHandler)
-
-    // Handle HTTP upgrade requests for WebSocket
-    server.on('upgrade', (req, socket, head) => {
-        const { pathname } = parseUrl(req.url)
-
-        if (pathname === core.wsPath) {
-            wss.handleUpgrade(req, socket, head, (ws) => {
-                wss.emit('connection', ws, req)
-            })
-        } else {
-            socket.destroy()
-        }
-    })
-
-    // Store original request listeners to chain after api-ape handlers
-    const originalListeners = server.listeners('request').slice()
-    server.removeAllListeners('request')
-
-    // Handle HTTP requests for api-ape routes
-    server.on('request', (req, res) => {
-        const { pathname } = parseUrl(req.url)
-
-        // Serve bundled client
-        if (pathname === core.clientPath) {
-            const filePath = path.join(__dirname, '../../dist/ape.js')
-            fs.readFile(filePath, (err, data) => {
-                if (err) {
-                    sendJson(res, 500, { error: 'Failed to read client bundle' })
-                    return
-                }
-                res.writeHead(200, { 'Content-Type': 'application/javascript' })
-                res.end(data)
-            })
-            return
-        }
-
-        // Serve source map for debugging
-        if (pathname === core.clientMapPath) {
-            const filePath = path.join(__dirname, '../../dist/ape.js.map')
-            fs.readFile(filePath, (err, data) => {
-                if (err) {
-                    sendJson(res, 404, { error: 'Source map not found' })
-                    return
-                }
-                res.writeHead(200, { 'Content-Type': 'application/json' })
-                res.end(data)
-            })
-            return
-        }
-
-        // Ping endpoint for captive portal detection
-        if (pathname === core.pingPath && req.method === 'GET') {
-            return sendJson(res, 200, { ok: true, ts: Date.now() })
-        }
-
-        // Long polling - GET
-        if (pathname === core.pollPath && req.method === 'GET') {
-            core.handleStreamGet(req, res)
-            return
-        }
-
-        // Long polling - POST
-        if (pathname === core.pollPath && req.method === 'POST') {
-            core.handleStreamPost(req, res, core.controllers)
-            return
-        }
-
-        // File download
-        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) {
-                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' })
-            }
-
-            const result = core.fileTransfer.getDownload(hash, clientId)
-
-            if (!result) {
-                return sendJson(res, 404, { error: 'Download not found or unauthorized' })
-            }
-
-            res.writeHead(200, {
-                'Content-Type': result.contentType,
-                'Content-Length': result.data.length || result.data.byteLength
-            })
-            res.end(result.data)
-            return
-        }
-
-        // File upload
-        const uploadMatch = matchRoute(pathname, core.uploadPattern)
-        if (req.method === 'PUT' && uploadMatch) {
-            const { queryId, pathHash } = uploadMatch
-
-            if (!isLocalhost(req.headers.host) && !isSecure(req)) {
-                return sendJson(res, 403, { error: 'HTTPS required for file transfers' })
-            }
-
-            const chunks = []
-            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) {
-                    sendJson(res, 200, { success: true })
-                } else {
-                    sendJson(res, 404, { error: 'Upload not expected or unauthorized' })
-                }
-            })
-            req.on('error', (err) => {
-                sendJson(res, 500, { error: err.message })
-            })
-            return
-        }
-
-        // Not an api-ape route - pass to original handlers
-        for (const listener of originalListeners) {
-            listener.call(server, req, res)
-        }
-    })
-
-    return { wss, core }
-}
+module.exports = function (server, options) {
+  /* istanbul ignore next 3 - would break test isolation to test "already started" */
+  if (created) {
+    throw new Error("Api-Ape already started");
+  }
+  created = true;
+
+  const core = createApeCore(options);
+
+  // Check for Bun server first
+  /* istanbul ignore next 3 - only reachable in Bun runtime */
+  if (isBunServer(server)) {
+    return initBunServerWithReload(server, options, core);
+  }
+
+  // Check for Node.js http.Server (or Express, Koa, etc.)
+  if (server && typeof server.on === "function") {
+    return initNodeServer(server, options, core);
+  }
+
+  /* istanbul ignore next 3 - requires passing invalid server type */
+  throw new Error(
+    "Unsupported server type. Expected http.Server (Node.js) or Bun.serve() server.",
+  );
+};
 
 /**
- * Bun integration
- * Returns fetch and websocket handlers to spread into Bun.serve()
+ * Check if running in Bun runtime
+ *
+ * Useful for conditional logic based on runtime capabilities.
+ *
+ * @function isBun
+ * @returns {boolean} True if running in Bun
+ *
+ * @example
+ * const { isBun } = require('api-ape/server/lib/main')
+ *
+ * if (isBun()) {
+ *   console.log('Running on Bun - native WebSocket available')
+ * }
  */
-function initBunServer(options) {
-    const { BunWebSocket } = require('./ws/adapters/bun')
-    const core = createApeCore(options)
-    const clients = new Map()
-
-    /**
-     * Fetch handler for Bun.serve()
-     * Handles all api-ape routes, returns null for non-ape routes
-     */
-    function fetch(req, server) {
-        const url = new URL(req.url)
-        const pathname = url.pathname
-
-        // WebSocket upgrade
-        if (pathname === core.wsPath) {
-            const upgrade = req.headers.get('upgrade')
-            if (upgrade?.toLowerCase() === 'websocket') {
-                const success = server.upgrade(req, { data: { req } })
-                if (success) return undefined
-                return new Response('WebSocket upgrade failed', { status: 500 })
-            }
-        }
-
-        // Serve client bundle
-        if (pathname === core.clientPath) {
-            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 })
-            }
-        }
-
-        // Serve source map for debugging
-        if (pathname === core.clientMapPath) {
-            try {
-                const filePath = path.join(__dirname, '../../dist/ape.js.map')
-                const data = fs.readFileSync(filePath)
-                return new Response(data, {
-                    headers: { 'Content-Type': 'application/json' }
-                })
-            } catch {
-                return new Response('Source map not found', { status: 404 })
-            }
-        }
-
-        // Ping endpoint for captive portal detection
-        if (pathname === core.pingPath && req.method === 'GET') {
-            return new Response(JSON.stringify({ ok: true, ts: Date.now() }), {
-                headers: { 'Content-Type': 'application/json' }
-            })
-        }
-
-        // Not an api-ape route
-        return null
-    }
-
-    /**
-     * WebSocket handlers for Bun.serve()
-     */
-    const websocket = {
-        open(ws) {
-            const wrapper = new BunWebSocket(ws)
-            clients.set(ws, wrapper)
-            const { req } = ws.data || {}
-            core.wiringHandler(wrapper, req)
-        },
-
-        message(ws, message) {
-            const wrapper = clients.get(ws)
-            if (wrapper) {
-                wrapper._onMessage(message)
-            }
-        },
-
-        close(ws, code, reason) {
-            const wrapper = clients.get(ws)
-            if (wrapper) {
-                wrapper._onClose(code, reason)
-                clients.delete(ws)
-            }
-        },
-
-        error(ws, error) {
-            const wrapper = clients.get(ws)
-            if (wrapper) {
-                wrapper._onError(error)
-            }
-        }
-    }
-
-    return { fetch, websocket, clients, core }
-}
+module.exports.isBun = isBun;
 
 /**
- * Check if server is a Bun server (has reload method and Bun globals)
+ * Reset singleton state (for testing only)
+ * @private
  */
-function isBunServer(server) {
-    return isBun() && typeof server?.reload === 'function'
-}
+module.exports._resetForTesting = _resetForTesting;
 
 /**
- * Initialize Bun server using server.reload() to hook in
- * This allows same signature: ape(server, { where: 'api' })
+ * Check if running in Deno runtime
+ *
+ * @function isDeno
+ * @returns {boolean} True if running in Deno
+ *
+ * @example
+ * const { isDeno } = require('api-ape/server/lib/main')
+ *
+ * if (isDeno()) {
+ *   console.log('Running on Deno')
+ * }
  */
-function initBunServerWithReload(server, options) {
-    const { BunWebSocket } = require('./ws/adapters/bun')
-    const core = createApeCore(options)
-    const clients = new Map()
-
-    // Check if WebSocket support is enabled on Bun server
-    // Bun requires websocket handlers to be defined at Bun.serve() creation
-    const hasWebSocketSupport = typeof server.upgrade === 'function'
-
-    if (!hasWebSocketSupport && options.transport !== 'longpolling') {
-        throw new Error(`
-🦍 api-ape: Bun WebSocket support not enabled!
-
-To enable WebSocket support in Bun, add a 'websocket' property when creating your server:
-
-    const server = Bun.serve({
-        port: 3000,
-        fetch(req) { ... },
-        websocket: { message() {} }  // <-- Required for api-ape
-    })
-
-    ape(server, { where: 'api' })
-
-If you only want HTTP long-polling (no WebSocket), pass:
-    ape(server, { where: 'api', transport: 'longpolling' })
-`)
-    }
-
-    // Store original fetch handler
-    const originalFetch = server.fetch
-
-    /**
-     * Wrapped fetch handler that handles api-ape routes first
-     */
-    function wrappedFetch(req, server) {
-        const url = new URL(req.url)
-        const pathname = url.pathname
-
-        // WebSocket upgrade
-        if (pathname === core.wsPath) {
-            const upgrade = req.headers.get('upgrade')
-            if (upgrade?.toLowerCase() === 'websocket') {
-                const success = server.upgrade(req, { data: { req } })
-                if (success) return undefined
-                return new Response('WebSocket upgrade failed', { status: 500 })
-            }
-        }
-
-        // Serve client bundle
-        if (pathname === core.clientPath) {
-            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 })
-            }
-        }
-
-        // Serve source map for debugging
-        if (pathname === core.clientMapPath) {
-            try {
-                const filePath = path.join(__dirname, '../../dist/ape.js.map')
-                const data = fs.readFileSync(filePath)
-                return new Response(data, {
-                    headers: { 'Content-Type': 'application/json' }
-                })
-            } catch {
-                return new Response('Source map not found', { status: 404 })
-            }
-        }
-
-        // Ping endpoint for captive portal detection
-        if (pathname === core.pingPath && req.method === 'GET') {
-            return new Response(JSON.stringify({ ok: true, ts: Date.now() }), {
-                headers: { 'Content-Type': 'application/json' }
-            })
-        }
-
-        // Pass to original fetch handler
-        if (originalFetch) {
-            return originalFetch(req, server)
-        }
-
-        return new Response('Not Found', { status: 404 })
-    }
-
-    /**
-     * WebSocket handlers
-     */
-    const websocket = {
-        open(ws) {
-            const wrapper = new BunWebSocket(ws)
-            clients.set(ws, wrapper)
-            const { req } = ws.data || {}
-            core.wiringHandler(wrapper, req)
-        },
-
-        message(ws, message) {
-            const wrapper = clients.get(ws)
-            if (wrapper) {
-                wrapper._onMessage(message)
-            }
-        },
-
-        close(ws, code, reason) {
-            const wrapper = clients.get(ws)
-            if (wrapper) {
-                wrapper._onClose(code, reason)
-                clients.delete(ws)
-            }
-        },
-
-        error(ws, error) {
-            const wrapper = clients.get(ws)
-            if (wrapper) {
-                wrapper._onError(error)
-            }
-        }
-    }
-
-    // Use server.reload() to hook in our handlers
-    server.reload({
-        fetch: wrappedFetch,
-        websocket
-    })
-
-    return { clients, core }
-}
+module.exports.isDeno = isDeno;
 
 /**
- * Main api-ape entry point
- * Unified signature for all runtimes:
- *   ape(server, { where: 'api' })
- * 
- * Works with:
- * - Node.js http.Server
- * - Express server
- * - Bun.serve() server
+ * Get the detected runtime type
+ *
+ * @function getRuntime
+ * @returns {'deno'|'bun'|'node'|'unknown'} The detected runtime
+ *
+ * @example
+ * const { getRuntime } = require('api-ape/server/lib/main')
+ *
+ * console.log(`Running on: ${getRuntime()}`)
+ * // Output: 'node', 'bun', 'deno', or 'unknown'
  */
-module.exports = function (server, options) {
-    if (created) {
-        throw new Error("Api-Ape already started")
-    }
-    created = true
-
-    // Bun server - use server.reload() to hook in
-    if (isBunServer(server)) {
-        return initBunServerWithReload(server, options)
-    }
-
-    // Node.js / Express - server is an http.Server with .on() method
-    if (server && typeof server.on === 'function') {
-        return initNodeServer(server, options)
-    }
-
-    throw new Error('Unsupported server type. Expected http.Server (Node.js) or Bun.serve() server.')
-}
-
-// Export runtime detection utilities
-module.exports.isBun = isBun
-module.exports.isDeno = isDeno
-module.exports.getRuntime = getRuntime
+module.exports.getRuntime = getRuntime;