api-ape 1.0.2 → 2.0.0

package/server/lib/main.js

@@ -1,23 +1,186 @@
 const loader = require('./loader')
 const wiring = require('./wiring')
-const expressWs = require('express-ws');
-const path = require('path');
+const { WebSocketServer } = require('ws')
+const path = require('path')
+const fs = require('fs')
+const { getFileTransferManager } = require('./fileTransfer')
+const { parse: parseUrl } = require('url')
 
 let created = false
 
-module.exports = function (app, { where, onConnent }) {
+/**
+ * Parse URL path parameters like /api/ape/data/:hash
+ * Returns null if pattern doesn't match, or object with params if it does
+ */
+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
+ */
+function sendJson(res, statusCode, data) {
+    res.writeHead(statusCode, { 'Content-Type': 'application/json' })
+    res.end(JSON.stringify(data))
+}
+
+/**
+ * Get cookie value from request
+ */
+function getCookie(req, name) {
+    const cookies = req.headers.cookie
+    if (!cookies) return null
+    const match = cookies.match(new RegExp(`(?:^|;\\s*)${name}=([^;]*)`))
+    return match ? match[1] : null
+}
+
+/**
+ * Check if request is from localhost
+ */
+function isLocalhost(req) {
+    const host = req.headers.host?.split(':')[0] || ''
+    return ['localhost', '127.0.0.1', '[::1]'].includes(host)
+}
+
+/**
+ * Check if connection is secure (HTTPS)
+ */
+function isSecure(req) {
+    return req.socket?.encrypted || req.headers['x-forwarded-proto'] === 'https'
+}
+
+module.exports = function (server, { where, onConnent, fileTransferOptions }) {
 
     if (created) {
         throw new Error("Api-Ape already started")
     }
-    created = true;
-    expressWs(app)
+    created = true
+
     const controllers = loader(where)
+    const fileTransfer = getFileTransferManager(fileTransferOptions)
+
+    // Create WebSocket server attached to the HTTP server
+    const wss = new WebSocketServer({ noServer: true })
+
+    // Handle WebSocket connections
+    const wsPath = `/${where}/ape`
+    const wiringHandler = wiring(controllers, onConnent, fileTransfer)
 
-    // Serve bundled client at /ape.js
-    app.get('/api/ape.js', (req, res) => {
-        res.sendFile(path.join(__dirname, '../../dist/ape.js'))
+    wss.on('connection', wiringHandler)
+
+    // Handle HTTP upgrade requests for WebSocket
+    server.on('upgrade', (req, socket, head) => {
+        const { pathname } = parseUrl(req.url)
+
+        if (pathname === wsPath) {
+            wss.handleUpgrade(req, socket, head, (ws) => {
+                wss.emit('connection', ws, req)
+            })
+        } else {
+            socket.destroy()
+        }
     })
 
-    app.ws('/api/ape', wiring(controllers, onConnent))
+    // 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 at /api/ape.js (or /{where}/ape.js)
+        if (pathname === `/${where}/ape.js`) {
+            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
+        }
+
+        // File download endpoint - GET /api/ape/data/:hash
+        const downloadMatch = matchRoute(pathname, `/${where}/ape/data/:hash`)
+        if (req.method === 'GET' && downloadMatch) {
+            const { hash } = downloadMatch
+            const hostId = getCookie(req, 'apeHostId') || req.headers['x-ape-host-id']
+
+            if (!hostId) {
+                return sendJson(res, 401, { error: 'Missing session identifier' })
+            }
+
+            if (!isLocalhost(req) && !isSecure(req)) {
+                return sendJson(res, 403, { error: 'HTTPS required for file transfers' })
+            }
+
+            const result = fileTransfer.getDownload(hash, hostId)
+
+            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 endpoint - PUT /api/ape/data/:queryId/:pathHash
+        const uploadMatch = matchRoute(pathname, `/${where}/ape/data/:queryId/:pathHash`)
+        if (req.method === 'PUT' && uploadMatch) {
+            const { queryId, pathHash } = uploadMatch
+            const hostId = getCookie(req, 'apeHostId') || req.headers['x-ape-host-id']
+
+            if (!hostId) {
+                return sendJson(res, 401, { error: 'Missing session identifier' })
+            }
+
+            if (!isLocalhost(req) && !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)
+                const success = fileTransfer.receiveUpload(queryId, pathHash, data, hostId)
+
+                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)
+        }
+    })
 }

package/server/lib/wiring.js

@@ -26,7 +26,7 @@ function defaultEvents(events = {}) {
 //============================================== wiring
 //=====================================================
 
-module.exports = function wiring(controllers, onConnent) {
+module.exports = function wiring(controllers, onConnent, fileTransfer) {
     onConnent = onConnent || (() => { });
     return function webSocketHandler(socket, req) {
 
@@ -70,7 +70,8 @@ module.exports = function wiring(controllers, onConnent) {
                     events: { onReceive, onSend, onError, onDisconnent },
                     controllers,
                     sharedValues,
-                    embedValues: embed
+                    embedValues: embed,
+                    fileTransfer  // Pass file transfer manager
                 }// END ape
                 send = socketSend(ape)
                 ape.send = send
@@ -92,3 +93,4 @@ module.exports = function wiring(controllers, onConnent) {
 
     } // END webSocketHandler
 } // END wiring
+

package/server/socket/receive.js

@@ -2,8 +2,95 @@ const messageHash = require('../../utils/messageHash')
 const { broadcast, online, getClients } = require('../lib/broadcast')
 const jss = require('../../utils/jss')
 
+/**
+ * Find B/A tagged properties in data (indicating pending uploads)
+ * Returns array of { path, hash, tag }
+ */
+function findUploadTags(obj, path = '') {
+    const uploads = []
+
+    if (obj === null || obj === undefined || typeof obj !== 'object') {
+        return uploads
+    }
+
+    if (Array.isArray(obj)) {
+        for (let i = 0; i < obj.length; i++) {
+            uploads.push(...findUploadTags(obj[i], path ? `${path}.${i}` : String(i)))
+        }
+        return uploads
+    }
+
+    for (const key of Object.keys(obj)) {
+        // Check for B or A tag (binary upload markers)
+        const bMatch = key.match(/^(.+)<!B>$/)
+        const aMatch = key.match(/^(.+)<!A>$/)
+
+        if (bMatch) {
+            uploads.push({
+                path: path ? `${path}.${bMatch[1]}` : bMatch[1],
+                hash: obj[key],
+                tag: 'B',
+                originalKey: key
+            })
+        } else if (aMatch) {
+            uploads.push({
+                path: path ? `${path}.${aMatch[1]}` : aMatch[1],
+                hash: obj[key],
+                tag: 'A',
+                originalKey: key
+            })
+        } else {
+            uploads.push(...findUploadTags(obj[key], path ? `${path}.${key}` : key))
+        }
+    }
+
+    return uploads
+}
+
+/**
+ * Clean upload tags from data (rename key<!B> to key)
+ */
+function cleanUploadTags(obj) {
+    if (obj === null || obj === undefined || typeof obj !== 'object') {
+        return obj
+    }
+
+    if (Array.isArray(obj)) {
+        return obj.map(cleanUploadTags)
+    }
+
+    const cleaned = {}
+    for (const key of Object.keys(obj)) {
+        const bMatch = key.match(/^(.+)<!B>$/)
+        const aMatch = key.match(/^(.+)<!A>$/)
+
+        if (bMatch) {
+            cleaned[bMatch[1]] = obj[key] // Will be replaced with actual data
+        } else if (aMatch) {
+            cleaned[aMatch[1]] = obj[key] // Will be replaced with actual data
+        } else {
+            cleaned[key] = cleanUploadTags(obj[key])
+        }
+    }
+    return cleaned
+}
+
+/**
+ * Set value at nested path
+ */
+function setValueAtPath(obj, path, value) {
+    const parts = path.split('.')
+    let current = obj
+
+    for (let i = 0; i < parts.length - 1; i++) {
+        current = current[parts[i]]
+    }
+
+    current[parts[parts.length - 1]] = value
+}
+
 module.exports = function receiveHandler(ape) {
-    const { send, checkReply, events, controllers, sharedValues, hostId, embedValues } = ape
+    const { send, checkReply, events, controllers, sharedValues, hostId, embedValues, fileTransfer } = ape
 
     // Build `this` context for controllers
     // Includes: client metadata + api-ape utilities
@@ -18,7 +105,7 @@ module.exports = function receiveHandler(ape) {
         hostId
     }
 
-    return function onReceive(msg) {
+    return async function onReceive(msg) {
         // Convert Buffer to string - WebSocket messages may arrive as binary
         const msgString = typeof msg === 'string' ? msg : msg.toString('utf8');
         const queryId = messageHash(msgString);
@@ -31,6 +118,34 @@ module.exports = function receiveHandler(ape) {
             // Call onReceive hook - it should return a finish callback
             const onFinish = events.onReceive(queryId, data, type) || (() => { })
 
+            // Check for pending uploads (B/A tags)
+            let processedData = data
+            if (fileTransfer && data) {
+                const uploadTags = findUploadTags(data)
+
+                if (uploadTags.length > 0) {
+                    console.log(`📤 Waiting for ${uploadTags.length} upload(s) for ${type}`)
+
+                    // Clean the data object
+                    processedData = cleanUploadTags(data)
+
+                    // Wait for all uploads
+                    try {
+                        await Promise.all(uploadTags.map(async ({ path, hash }) => {
+                            const uploadData = await fileTransfer.registerUpload(queryId, hash, hostId)
+                            setValueAtPath(processedData, path, uploadData)
+                        }))
+                    } catch (uploadErr) {
+                        console.error(`📤 Upload wait failed:`, uploadErr)
+                        send(queryId, false, false, uploadErr)
+                        if (typeof onFinish === 'function') {
+                            onFinish(uploadErr, true)
+                        }
+                        return
+                    }
+                }
+            }
+
             const result = new Promise((resolve, reject) => {
                 try {
                     const controller = controllers[type]
@@ -38,7 +153,7 @@ module.exports = function receiveHandler(ape) {
                         throw `TypeError: "${type}" was not found`
                     }
                     checkReply(queryId, createdAt)
-                    resolve(controller.call(that, data))
+                    resolve(controller.call(that, processedData))
                 } catch (err) {
                     reject(err)
                 }

package/server/socket/send.js

@@ -1,4 +1,5 @@
 const jss = require('../../utils/jss')
+const { FileTransferManager } = require('../lib/fileTransfer')
 
 function checkSocketState(socket) {
   if (socket.readyState !== socket.OPEN) {
@@ -17,7 +18,88 @@ function checkSocketState(socket) {
   } // END if
 } // END checkSocketState
 
-module.exports = function sendHandler({ socket, events, hostId }) {
+/**
+ * Check if value is binary data (Buffer, ArrayBuffer, or typed array)
+ */
+function isBinaryData(value) {
+  if (value === null || value === undefined) return false
+  return Buffer.isBuffer(value) ||
+    value instanceof ArrayBuffer ||
+    ArrayBuffer.isView(value)
+}
+
+/**
+ * Detect content type from binary data
+ */
+function detectContentType(data) {
+  // Could be enhanced with magic number detection
+  return 'application/octet-stream'
+}
+
+/**
+ * Process data object, replacing binary values with L-tagged hashes
+ * Returns { processedData, binaryEntries }
+ */
+function processBinaryData(data, queryId, fileTransfer, hostId, path = '') {
+  if (data === null || data === undefined) {
+    return { processedData: data, binaryEntries: [] }
+  }
+
+  if (isBinaryData(data)) {
+    // 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)
+
+    return {
+      processedData: { [`__ape_link__`]: hash },
+      binaryEntries: [{ path, hash }]
+    }
+  }
+
+  if (Array.isArray(data)) {
+    const processedArray = []
+    const allBinaryEntries = []
+
+    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
+      )
+      processedArray.push(processedData)
+      allBinaryEntries.push(...binaryEntries)
+    }
+
+    return { processedData: processedArray, binaryEntries: allBinaryEntries }
+  }
+
+  if (typeof data === 'object') {
+    const processedObj = {}
+    const allBinaryEntries = []
+
+    for (const key of Object.keys(data)) {
+      const itemPath = path ? `${path}.${key}` : key
+      const { processedData, binaryEntries } = processBinaryData(
+        data[key], queryId, fileTransfer, hostId, itemPath
+      )
+
+      // If this was binary data, mark the key with <!L> tag
+      if (binaryEntries.length > 0 && processedData?.__ape_link__) {
+        processedObj[`${key}<!L>`] = processedData.__ape_link__
+      } else {
+        processedObj[key] = processedData
+      }
+      allBinaryEntries.push(...binaryEntries)
+    }
+
+    return { processedData: processedObj, binaryEntries: allBinaryEntries }
+  }
+
+  // Primitive value - return as-is
+  return { processedData: data, binaryEntries: [] }
+}
+
+module.exports = function sendHandler({ socket, events, hostId, fileTransfer }) {
 
   return function send(queryId, type, data, err) {
     if (!type && !queryId) {
@@ -43,11 +125,24 @@ module.exports = function sendHandler({ socket, events, hostId }) {
       }
       return;
     }
+
+    // Process binary data if fileTransfer is available
+    let processedData = data
+    if (fileTransfer && data && !err) {
+      const { processedData: processed, binaryEntries } = processBinaryData(
+        data, queryId || type, fileTransfer, hostId
+      )
+      processedData = processed
+      if (binaryEntries.length > 0) {
+        console.log(`📦 Registered ${binaryEntries.length} binary download(s) for ${queryId || type}`)
+      }
+    }
+
     if (err) {
       socket.send(jss.stringify({ err: err.message || err, type, queryId }))
       if (typeof onFinish === 'function') onFinish(err, true)
     } else {
-      socket.send(jss.stringify({ data, type, queryId }))
+      socket.send(jss.stringify({ data: processedData, type, queryId }))
       if (typeof onFinish === 'function') onFinish(false, data)
     }