api-ape 1.0.2 → 2.0.0

package/README.md

@@ -24,18 +24,30 @@ yarn add api-ape
 
 ## Quick Start
 
-### Server (Express.js)
+### Server (Node.js)
 
 ```js
-const express = require('express')
+const { createServer } = require('http')
 const ape = require('api-ape')
 
-const app = express()
+const server = createServer()
 
 // Wire up api-ape - loads controllers from ./api folder
-ape(app, { where: 'api' })
+ape(server, { where: 'api' })
 
-app.listen(3000)
+server.listen(3000)
+```
+
+**With Express:**
+```js
+const express = require('express')
+const ape = require('api-ape')
+
+const app = express()
+const server = app.listen(3000)  // Get the HTTP server
+
+// Pass the HTTP server (not the Express app)
+ape(server, { where: 'api' })
 ```
 
 ### Create a Controller
@@ -86,12 +98,13 @@ Include the bundled client and start calling:
 
 ### Server
 
-#### `ape(app, options)`
+#### `ape(server, options)`
 
-Initialize api-ape on an Express app.
+Initialize api-ape on a Node.js HTTP/HTTPS server.
 
 | Option | Type | Description |
 |--------|------|-------------|
+| `server` | `http.Server` | Node.js HTTP or HTTPS server instance |
 | `where` | `string` | Directory containing controller files (default: `'api'`) |
 | `onConnent` | `function` | Connection lifecycle hook (see [Connection Lifecycle](#connection-lifecycle)) |
 
@@ -146,7 +159,7 @@ ape.on('notification', ({ data, err, type }) => {
 ### Default Options
 
 ```js
-ape(app, {
+ape(server, {
   where: 'api',           // Controller directory
   onConnent: undefined    // Lifecycle hook (optional)
 })
@@ -157,7 +170,7 @@ ape(app, {
 Customize behavior per connection:
 
 ```js
-ape(app, {
+ape(server, {
   where: 'api',
   onConnent(socket, req, hostId) {
     return {
@@ -328,7 +341,7 @@ docker-compose up --build
 
 ### CORS Errors in Browser
 
-Ensure your Express server allows WebSocket connections from your origin. api-ape uses `express-ws` which handles CORS automatically, but verify your Express CORS middleware allows WebSocket upgrade requests.
+Ensure your server allows WebSocket connections from your origin. api-ape uses the `ws` library which handles WebSocket upgrades on the HTTP server level.
 
 ### Controller Not Found
 
@@ -343,12 +356,46 @@ The client automatically reconnects with exponential backoff. If connections dro
 * Verify network stability
 * Check server logs for errors
 
-### Binary Data / File Uploads
+### Binary Data / File Transfers
+
+api-ape supports transparent binary file transfers. Simply return `Buffer` data from controllers:
+
+```js
+// api/files/download.js
+module.exports = function(filename) {
+  return {
+    name: filename,
+    data: fs.readFileSync(`./uploads/${filename}`)  // Buffer
+  }
+}
+```
+
+The client receives `ArrayBuffer` automatically:
+
+```js
+const result = await ape.files.download('image.png')
+console.log(result.data)  // ArrayBuffer
+
+// Display as image
+const blob = new Blob([result.data])
+img.src = URL.createObjectURL(blob)
+```
+
+**Uploads work the same way:**
+
+```js
+// Client
+const arrayBuffer = await file.arrayBuffer()
+await ape.files.upload({ name: file.name, data: arrayBuffer })
+
+// Server (api/files/upload.js)
+module.exports = function({ name, data }) {
+  fs.writeFileSync(`./uploads/${name}`, data)  // data is Buffer
+  return { success: true }
+}
+```
 
-JJS encoding supports complex types, but for large binary data, consider:
-* Sending file URLs instead of raw data
-* Using a separate file upload endpoint
-* Chunking large payloads
+Binary data is transferred via temporary HTTP endpoints (`/api/ape/data/:hash`) with session verification and auto-cleanup.
 
 ### TypeScript Support
 
@@ -426,7 +473,7 @@ api-ape/
 │   └── connectSocket.js # WebSocket client with auto-reconnect
 ├── server/
 │   ├── lib/
-│   │   ├── main.js      # Express integration
+│   │   ├── main.js      # HTTP server integration
 │   │   ├── loader.js    # Auto-loads controller files
 │   │   ├── broadcast.js # Client tracking & broadcast
 │   │   └── wiring.js    # WebSocket handler setup

package/client/README.md

@@ -67,3 +67,35 @@ ape.configure({
 Default port detection:
 - Local (`localhost`, `127.0.0.1`): `9010`
 - Remote: Uses current page port or `443`/`80`
+
+## File Transfers
+
+Binary data is automatically handled. The client fetches binary resources and uploads binary data transparently.
+
+### Receiving Binary Data
+
+```js
+// Server returns Buffer, client receives ArrayBuffer
+const result = await ape.files.download('image.png')
+console.log(result.data)  // ArrayBuffer
+
+// Display as image
+const blob = new Blob([result.data])
+img.src = URL.createObjectURL(blob)
+```
+
+### Uploading Binary Data
+
+```js
+const file = input.files[0]
+const arrayBuffer = await file.arrayBuffer()
+
+// Binary data is uploaded automatically
+await ape.files.upload({
+  name: file.name,
+  data: arrayBuffer  // Sent via HTTP PUT
+})
+```
+
+Binary transfers use `/api/ape/data/:hash` endpoints with session verification.
+

package/client/browser.js

@@ -4,7 +4,7 @@ import connectSocket from './connectSocket.js'
 const port = window.location.port || (window.location.protocol === 'https:' ? 443 : 80)
 connectSocket.configure({ port: parseInt(port, 10) })
 
-const { sender, setOnReciver } = connectSocket()
+const { sender, setOnReciver, onConnectionChange } = connectSocket()
 connectSocket.autoReconnect()
 
 // Global API - use defineProperty to bypass Proxy interception
@@ -15,3 +15,9 @@ Object.defineProperty(window.ape, 'on', {
     enumerable: false,
     configurable: false
 })
+Object.defineProperty(window.ape, 'onConnectionChange', {
+    value: onConnectionChange,
+    writable: false,
+    enumerable: false,
+    configurable: false
+})

package/client/connectSocket.js

@@ -1,9 +1,27 @@
 import messageHash from '../utils/messageHash'
 import jss from '../utils/jss'
 
-
 let connect;
 
+// Connection state enum
+const ConnectionState = {
+  Disconnected: 'disconnected',
+  Connecting: 'connecting',
+  Connected: 'connected',
+  Closing: 'closing'
+}
+
+// Connection state tracking
+let connectionState = ConnectionState.Disconnected
+const connectionChangeListeners = []
+
+function notifyConnectionChange(newState) {
+  if (connectionState !== newState) {
+    connectionState = newState
+    connectionChangeListeners.forEach(fn => fn(newState))
+  }
+}
+
 // Configuration
 let configuredPort = null
 let configuredHost = null
@@ -82,11 +100,13 @@ const ofTypesOb = {};
 function connectSocket() {
 
   if (!__socket) {
+    notifyConnectionChange(ConnectionState.Connecting)
     __socket = new WebSocket(getSocketUrl())
 
     __socket.onopen = event => {
       //console.log('socket connected()');
       ready = true;
+      notifyConnectionChange(ConnectionState.Connected)
       aWaitingSend.forEach(({ type, data, next, err, waiting, createdAt, timer }) => {
         clearTimeout(timer)
         //TODO: clear throw of wait for server
@@ -101,14 +121,148 @@ function connectSocket() {
       aWaitingSend = []
     } // END onopen
 
-    __socket.onmessage = function (event) {
+    /**
+     * Find all L-tagged (binary link) properties in data
+     * Returns array of { path, hash }
+     */
+    function findLinkedResources(obj, path = '') {
+      const resources = []
+
+      if (obj === null || obj === undefined || typeof obj !== 'object') {
+        return resources
+      }
+
+      if (Array.isArray(obj)) {
+        for (let i = 0; i < obj.length; i++) {
+          resources.push(...findLinkedResources(obj[i], path ? `${path}.${i}` : String(i)))
+        }
+        return resources
+      }
+
+      for (const key of Object.keys(obj)) {
+        // Check for L-tag in key (from JJS encoding: key<!L>)
+        if (key.endsWith('<!L>')) {
+          const cleanKey = key.slice(0, -4)
+          const hash = obj[key]
+          resources.push({
+            path: path ? `${path}.${cleanKey}` : cleanKey,
+            hash,
+            originalKey: key
+          })
+        } else {
+          resources.push(...findLinkedResources(obj[key], path ? `${path}.${key}` : key))
+        }
+      }
+
+      return resources
+    }
+
+    /**
+     * Set a value at a nested path in an object
+     */
+    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
+    }
+
+    /**
+     * Clean up L-tagged keys (rename key<!L> to key)
+     */
+    function cleanLinkedKeys(obj) {
+      if (obj === null || obj === undefined || typeof obj !== 'object') {
+        return obj
+      }
+
+      if (Array.isArray(obj)) {
+        return obj.map(cleanLinkedKeys)
+      }
+
+      const cleaned = {}
+      for (const key of Object.keys(obj)) {
+        if (key.endsWith('<!L>')) {
+          const cleanKey = key.slice(0, -4)
+          cleaned[cleanKey] = obj[key] // Value will be replaced after fetch
+        } else {
+          cleaned[key] = cleanLinkedKeys(obj[key])
+        }
+      }
+      return cleaned
+    }
+
+    /**
+     * Fetch binary resources and hydrate data object
+     */
+    async function fetchLinkedResources(data, hostId) {
+      const resources = findLinkedResources(data)
+
+      if (resources.length === 0) {
+        return data
+      }
+
+      console.log(`🦍 Fetching ${resources.length} binary resource(s)`)
+
+      // Clean the data first (remove <!L> suffixes from keys)
+      const cleanedData = cleanLinkedKeys(data)
+
+      // Build base URL for fetches
+      const hostname = configuredHost || window.location.hostname
+      const isLocal = ["localhost", "127.0.0.1", "[::1]"].includes(hostname)
+      const isHttps = window.location.protocol === "https:"
+      const defaultPort = isLocal ? 9010 : (window.location.port || (isHttps ? 443 : 80))
+      const port = configuredPort || defaultPort
+      const protocol = isHttps ? "https" : "http"
+      const portSuffix = (isLocal || (port !== 80 && port !== 443)) ? `:${port}` : ""
+      const baseUrl = `${protocol}://${hostname}${portSuffix}`
+
+      // Fetch all resources in parallel
+      await Promise.all(resources.map(async ({ path, hash }) => {
+        try {
+          const response = await fetch(`${baseUrl}/api/ape/data/${hash}`, {
+            credentials: 'include',
+            headers: {
+              'X-Ape-Host-Id': hostId || ''
+            }
+          })
+
+          if (!response.ok) {
+            throw new Error(`Failed to fetch binary resource: ${response.status}`)
+          }
+
+          const arrayBuffer = await response.arrayBuffer()
+          setValueAtPath(cleanedData, path, arrayBuffer)
+        } catch (err) {
+          console.error(`🦍 Failed to fetch binary resource at ${path}:`, err)
+          setValueAtPath(cleanedData, path, null)
+        }
+      }))
+
+      return cleanedData
+    }
+
+    __socket.onmessage = async function (event) {
       //console.log('WebSocket message:', event);
       const { err, type, queryId, data } = jss.parse(event.data)
 
       // Messages with queryId must fulfill matching promise
       if (queryId) {
         if (waitingOn[queryId]) {
-          waitingOn[queryId](err, data)
+          // Check for linked resources and fetch them before resolving
+          if (data && !err) {
+            try {
+              const hydratedData = await fetchLinkedResources(data)
+              waitingOn[queryId](err, hydratedData)
+            } catch (fetchErr) {
+              waitingOn[queryId](fetchErr, null)
+            }
+          } else {
+            waitingOn[queryId](err, data)
+          }
           delete waitingOn[queryId]
         } else {
           // No matching promise - error and ignore
@@ -118,10 +272,20 @@ function connectSocket() {
       }
 
       // Only messages WITHOUT queryId go to setOnReciver
+      // Also hydrate broadcast messages
+      let processedData = data
+      if (data && !err) {
+        try {
+          processedData = await fetchLinkedResources(data)
+        } catch (fetchErr) {
+          console.error(`🦍 Failed to hydrate broadcast data:`, fetchErr)
+        }
+      }
+
       if (ofTypesOb[type]) {
-        ofTypesOb[type].forEach(worker => worker({ err, type, data }))
+        ofTypesOb[type].forEach(worker => worker({ err, type, data: processedData }))
       } // if ofTypesOb[type]
-      reciverOnAr.forEach(worker => worker({ err, type, data }))
+      reciverOnAr.forEach(worker => worker({ err, type, data: processedData }))
 
     } // END onmessage
 
@@ -133,10 +297,138 @@ function connectSocket() {
       console.warn('socket disconnect:', event);
       __socket = false
       ready = false;
+      notifyConnectionChange(ConnectionState.Disconnected)
       setTimeout(() => reconnect && connectSocket(), 500);
     } // END onclose
 
   } // END if ! __socket
+
+  /**
+   * Check if value is binary data (ArrayBuffer, typed array, or Blob)
+   */
+  function isBinaryData(value) {
+    if (value === null || value === undefined) return false
+    return value instanceof ArrayBuffer ||
+      ArrayBuffer.isView(value) ||
+      (typeof Blob !== 'undefined' && value instanceof Blob)
+  }
+
+  /**
+   * Get binary type tag (A for ArrayBuffer, B for Blob)
+   */
+  function getBinaryTag(value) {
+    if (typeof Blob !== 'undefined' && value instanceof Blob) return 'B'
+    return 'A'
+  }
+
+  /**
+   * Generate a simple hash for binary upload
+   */
+  function generateUploadHash(path) {
+    let hash = 0
+    for (let i = 0; i < path.length; i++) {
+      const char = path.charCodeAt(i)
+      hash = ((hash << 5) - hash) + char
+      hash = hash & hash
+    }
+    return Math.abs(hash).toString(36)
+  }
+
+  /**
+   * Find and extract binary data from payload
+   * Returns { processedData, uploads: [{ path, hash, data, tag }] }
+   */
+  function processBinaryForUpload(data, path = '') {
+    if (data === null || data === undefined) {
+      return { processedData: data, uploads: [] }
+    }
+
+    if (isBinaryData(data)) {
+      const tag = getBinaryTag(data)
+      const hash = generateUploadHash(path || 'root')
+      return {
+        processedData: { [`__ape_upload__`]: hash },
+        uploads: [{ path, hash, data, tag }]
+      }
+    }
+
+    if (Array.isArray(data)) {
+      const processedArray = []
+      const allUploads = []
+
+      for (let i = 0; i < data.length; i++) {
+        const itemPath = path ? `${path}.${i}` : String(i)
+        const { processedData, uploads } = processBinaryForUpload(data[i], itemPath)
+        processedArray.push(processedData)
+        allUploads.push(...uploads)
+      }
+
+      return { processedData: processedArray, uploads: allUploads }
+    }
+
+    if (typeof data === 'object') {
+      const processedObj = {}
+      const allUploads = []
+
+      for (const key of Object.keys(data)) {
+        const itemPath = path ? `${path}.${key}` : key
+        const { processedData, uploads } = processBinaryForUpload(data[key], itemPath)
+
+        // If this was binary data, mark the key with <!B> or <!A> tag
+        if (uploads.length > 0 && processedData?.__ape_upload__) {
+          const tag = uploads[uploads.length - 1].tag
+          processedObj[`${key}<!${tag}>`] = processedData.__ape_upload__
+        } else {
+          processedObj[key] = processedData
+        }
+        allUploads.push(...uploads)
+      }
+
+      return { processedData: processedObj, uploads: allUploads }
+    }
+
+    return { processedData: data, uploads: [] }
+  }
+
+  /**
+   * Upload binary data via HTTP PUT
+   */
+  async function uploadBinaryData(queryId, uploads) {
+    if (uploads.length === 0) return
+
+    // Build base URL
+    const hostname = configuredHost || window.location.hostname
+    const isLocal = ["localhost", "127.0.0.1", "[::1]"].includes(hostname)
+    const isHttps = window.location.protocol === "https:"
+    const defaultPort = isLocal ? 9010 : (window.location.port || (isHttps ? 443 : 80))
+    const port = configuredPort || defaultPort
+    const protocol = isHttps ? "https" : "http"
+    const portSuffix = (isLocal || (port !== 80 && port !== 443)) ? `:${port}` : ""
+    const baseUrl = `${protocol}://${hostname}${portSuffix}`
+
+    console.log(`🦍 Uploading ${uploads.length} binary file(s)`)
+
+    await Promise.all(uploads.map(async ({ hash, data }) => {
+      try {
+        const response = await fetch(`${baseUrl}/api/ape/data/${queryId}/${hash}`, {
+          method: 'PUT',
+          credentials: 'include',
+          headers: {
+            'Content-Type': 'application/octet-stream'
+          },
+          body: data
+        })
+
+        if (!response.ok) {
+          throw new Error(`Upload failed: ${response.status}`)
+        }
+      } catch (err) {
+        console.error(`🦍 Failed to upload binary at ${hash}:`, err)
+        throw err
+      }
+    }))
+  }
+
   wsSend = function (type, data, createdAt, dirctCall) {
     let rej, promiseIsLive = false;
     const timeLetForReqToBeMade = (createdAt + totalRequestTimeout) - Date.now()
@@ -146,9 +438,13 @@ function connectSocket() {
         rej(new Error("Request Timedout for :" + type))
       }
     }, timeLetForReqToBeMade);
+
+    // Process binary data for upload
+    const { processedData, uploads } = processBinaryForUpload(data)
+
     const payload = {
       type,
-      data,
+      data: processedData,
       //referer:window.location.href,
       createdAt: new Date(createdAt),
       requestedAt: dirctCall ? undefined
@@ -169,6 +465,14 @@ function connectSocket() {
         }
       }
       __socket.send(message);
+
+      // Upload binary data after sending WS message
+      if (uploads.length > 0) {
+        uploadBinaryData(queryId, uploads).catch(err => {
+          console.error('🦍 Binary upload failed:', err)
+          // The server will timeout waiting for the upload
+        })
+      }
     });
     const next = replyPromise.then;
     replyPromise.then = worker => {
@@ -248,13 +552,24 @@ function connectSocket() {
           reciverOnAr.push(onTypeStFn)
         }
       }
-    } // END setOnReciver
+    }, // END setOnReciver
+    onConnectionChange: (handler) => {
+      connectionChangeListeners.push(handler)
+      // Immediately call with current state
+      handler(connectionState)
+      // Return unsubscribe function
+      return () => {
+        const idx = connectionChangeListeners.indexOf(handler)
+        if (idx > -1) connectionChangeListeners.splice(idx, 1)
+      }
+    }
   } // END return
 } // END connectSocket
 
 connectSocket.autoReconnect = () => reconnect = true
 connectSocket.configure = configure
+connectSocket.ConnectionState = ConnectionState
 connect = connectSocket
 
 export default connect;
-export { configure };
+export { configure, ConnectionState };