api-ape 0.0.0 → 1.0.1

package/index.d.ts

@@ -0,0 +1,179 @@
+// Type definitions for api-ape
+// Project: https://github.com/codemeasandwich/api-ape
+
+import { Application } from 'express'
+import { WebSocket } from 'ws'
+import { IncomingMessage } from 'http'
+
+// =============================================================================
+// SERVER TYPES
+// =============================================================================
+
+/**
+ * Controller context available as `this` inside controller functions
+ */
+export interface ControllerContext {
+    /** Send to ALL connected clients */
+    broadcast(type: string, data: any): void
+    /** Send to all clients EXCEPT the caller */
+    broadcastOthers(type: string, data: any): void
+    /** Get count of connected clients */
+    online(): number
+    /** Get array of connected hostIds */
+    getClients(): string[]
+    /** Unique ID of the calling client */
+    hostId: string
+    /** Original HTTP request */
+    req: IncomingMessage
+    /** WebSocket instance */
+    socket: WebSocket
+    /** Parsed user-agent info */
+    agent: {
+        browser: { name?: string; version?: string }
+        os: { name?: string; version?: string }
+        device: { type?: string; vendor?: string; model?: string }
+    }
+    /** Custom embedded values from onConnent */
+    [key: string]: any
+}
+
+/**
+ * Controller function type
+ */
+export type ControllerFunction<T = any, R = any> = (
+    this: ControllerContext,
+    data: T
+) => R | Promise<R>
+
+/**
+ * Send function provided to onConnent
+ */
+export type SendFunction = {
+    (type: string, data: any): void
+    toString(): string
+}
+
+/**
+ * After hook returned from onReceive/onSend
+ */
+export type AfterHook = (err: Error | null, result: any) => void
+
+/**
+ * Connection lifecycle hooks returned from onConnent
+ */
+export interface ConnectionHandlers {
+    /** Values to embed into controller context */
+    embed?: Record<string, any>
+    /** Called before processing incoming message, return after hook */
+    onReceive?: (queryId: string, data: any, type: string) => AfterHook | void
+    /** Called before sending message, return after hook */
+    onSend?: (data: any, type: string) => AfterHook | void
+    /** Called on error */
+    onError?: (errorString: string) => void
+    /** Called when client disconnects */
+    onDisconnent?: () => void
+}
+
+/**
+ * onConnent callback signature
+ */
+export type OnConnectCallback = (
+    socket: WebSocket,
+    req: IncomingMessage,
+    send: SendFunction
+) => ConnectionHandlers | void
+
+/**
+ * Server options for ape()
+ */
+export interface ApeServerOptions {
+    /** Directory containing controller files */
+    where: string
+    /** Connection lifecycle hook */
+    onConnent?: OnConnectCallback
+}
+
+/**
+ * Initialize api-ape on an Express app
+ */
+declare function ape(app: Application, options: ApeServerOptions): void
+
+export default ape
+
+// =============================================================================
+// CLIENT TYPES
+// =============================================================================
+
+/**
+ * Message received from server
+ */
+export interface ReceivedMessage<T = any> {
+    err?: Error | string
+    type: string
+    data: T
+}
+
+/**
+ * Message handler callback
+ */
+export type MessageHandler<T = any> = (message: ReceivedMessage<T>) => void
+
+/**
+ * Proxy-based sender - any property access creates a callable path
+ * Example: sender.users.list() calls type="/users/list"
+ */
+export interface ApeSender {
+    [key: string]: ApeSender & (<T = any, R = any>(data?: T) => Promise<R>)
+}
+
+/**
+ * Set receiver for specific message type or all messages
+ */
+export type SetOnReceiver = {
+    (type: string, handler: MessageHandler): void
+    (handler: MessageHandler): void
+}
+
+/**
+ * Connected client interface
+ */
+export interface ApeClient {
+    sender: ApeSender
+    setOnReciver: SetOnReceiver
+}
+
+/**
+ * Configuration options for client
+ */
+export interface ApeClientConfig {
+    /** WebSocket port */
+    port?: number
+    /** WebSocket host */
+    host?: string
+}
+
+/**
+ * Connect socket function with configuration methods
+ */
+export interface ConnectSocket {
+    (): ApeClient
+    /** Configure connection options */
+    configure(options: ApeClientConfig): void
+    /** Enable auto-reconnection on disconnect */
+    autoReconnect(): void
+}
+
+/**
+ * Client module default export
+ */
+declare const connectSocket: ConnectSocket
+
+export { connectSocket }
+
+// =============================================================================
+// BROADCAST MODULE
+// =============================================================================
+
+export declare const broadcast: (type: string, data: any) => void
+export declare const online: () => number
+export declare const getClients: () => string[]

package/index.js

@@ -0,0 +1,11 @@
+
+let apiApe;
+
+if ('undefined' === typeof window
+  || 'undefined' === typeof window.document) {
+  apiApe = require('./server');
+} else {
+  apiApe = require('./client');
+}
+
+module.exports = apiApe

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "api-ape",
-  "version": "0.0.0",
+  "version": "1.0.1",
   "description": "Remote procedure events",
   "main": "index.js",
-  "scripts": {   
+  "types": "index.d.ts",
+  "scripts": {
     "test": "jest --no-cache ",
     "test:go": "npm test -- --watch --coverage",
     "test:update": "npm test -- --updateSnapshot",
@@ -20,12 +21,18 @@
     "ape"
   ],
   "author": "brian shannon",
-  "license": "ISC",
+  "license": "MIT",
   "bugs": {
     "url": "https://github.com/codemeasandwich/api-ape/issues"
   },
   "homepage": "https://github.com/codemeasandwich/api-ape#readme",
   "dependencies": {
-    "jest": "^29.3.1"
+    "express-ws": "^5.0.2",
+    "jest": "^29.3.1",
+    "ua-parser-js": "^1.0.37",
+    "ws": "^8.14.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.27.2"
   }
 }

package/server/README.md

@@ -0,0 +1,93 @@
+# 🦍 api-ape Server
+
+Express.js integration for WebSocket-based Remote Procedure Events (RPE).
+
+## Directory Structure
+
+```
+server/
+├── index.js          # Entry point (exports lib/main)
+├── lib/
+│   ├── main.js       # Express integration & setup
+│   ├── loader.js     # Auto-loads controller files from folder
+│   ├── broadcast.js  # Client tracking & broadcast utilities
+│   └── wiring.js     # WebSocket handler setup
+├── socket/
+│   ├── receive.js    # Incoming message handler
+│   └── send.js       # Outgoing message handler
+├── security/
+│   └── reply.js      # Duplicate request protection
+└── utils/
+    └── ...           # Server utilities
+```
+
+## Usage
+
+```bash
+npm i api-ape
+```
+
+```js
+const express = require('express')
+const ape = require('api-ape')
+
+const app = express()
+
+ape(app, {
+  where: 'api',        // Controller directory
+  onConnent: (socket, req, send) => ({
+    embed: { userId: req.session?.userId },
+    onDisconnent: () => console.log('Client left')
+  })
+})
+
+app.listen(3000)
+```
+
+## API
+
+### `ape(app, options)`
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `where` | `string` | Directory containing controller files |
+| `onConnent` | `function` | Connection lifecycle hook |
+
+### Controller Context (`this`)
+
+| Property | Description |
+|----------|-------------|
+| `this.broadcast(type, data)` | Send to ALL connected clients |
+| `this.broadcastOthers(type, data)` | Send to all EXCEPT the caller |
+| `this.online()` | Get count of connected clients |
+| `this.getClients()` | Get array of connected hostIds |
+| `this.hostId` | Unique ID of the calling client |
+| `this.req` | Original HTTP request |
+| `this.socket` | WebSocket instance |
+| `this.agent` | Parsed user-agent |
+
+### Connection Lifecycle Hooks
+
+```js
+onConnent(socket, req, send) {
+  return {
+    embed: { ... },          // Values available as this.* in controllers
+    onReceive: (queryId, data, type) => afterFn,
+    onSend: (data, type) => afterFn,
+    onError: (errStr) => { ... },
+    onDisconnent: () => { ... }
+  }
+}
+```
+
+## Auto-Routing
+
+Drop JS files in your `where` directory:
+
+```
+api/
+├── hello.js      → ape.hello(data)
+├── users/
+│   ├── list.js   → ape.users.list(data)
+│   └── create.js → ape.users.create(data)
+```

package/server/index.js

@@ -0,0 +1,6 @@
+/**
+ * api-ape server entry point
+ * Exports the main ape function
+ */
+
+module.exports = require('./lib/main')

package/server/lib/broadcast.js

@@ -0,0 +1,63 @@
+/**
+ * Broadcast utilities for api-ape
+ * Tracks connected clients and provides broadcast functions
+ */
+
+// Track all connected clients for broadcast
+const connectedClients = new Set()
+
+/**
+ * Add a client to the connected set
+ */
+function addClient(clientInfo) {
+    connectedClients.add(clientInfo)
+}
+
+/**
+ * Remove a client from the connected set
+ */
+function removeClient(clientInfo) {
+    connectedClients.delete(clientInfo)
+}
+
+/**
+ * Broadcast to all connected clients
+ * @param {string} type - Message type
+ * @param {any} data - Data to send
+ * @param {string} [excludeHostId] - Optional hostId to exclude (e.g., sender)
+ */
+function broadcast(type, data, excludeHostId) {
+    console.log(`📢 Broadcasting "${type}" to ${connectedClients.size} clients`, excludeHostId ? `(excluding ${excludeHostId})` : '')
+    connectedClients.forEach(client => {
+        if (excludeHostId && client.hostId === excludeHostId) {
+            return // Skip excluded client
+        }
+        try {
+            client.send(false, type, data, false)
+        } catch (e) {
+            console.error(`📢 Broadcast failed to ${client.hostId}:`, e.message)
+        }
+    })
+}
+
+/**
+ * Get count of online clients
+ */
+function online() {
+    return connectedClients.size
+}
+
+/**
+ * Get all connected client hostIds
+ */
+function getClients() {
+    return Array.from(connectedClients).map(c => c.hostId)
+}
+
+module.exports = {
+    addClient,
+    removeClient,
+    broadcast,
+    online,
+    getClients
+}

package/server/lib/loader.js

@@ -0,0 +1,10 @@
+const deeprequire = require('../utils/deepRequire')
+const path = require('path')
+
+// Use the current working directory (where node was started)
+// This ensures 'where' folder is relative to the calling application
+const currentDir = process.cwd()
+
+module.exports = function (dirname, selector) {
+  return deeprequire(path.join(currentDir, dirname), selector)
+}

package/server/lib/main.js

@@ -0,0 +1,23 @@
+const loader = require('./loader')
+const wiring = require('./wiring')
+const expressWs = require('express-ws');
+const path = require('path');
+
+let created = false
+
+module.exports = function (app, { where, onConnent }) {
+
+    if (created) {
+        throw new Error("Api-Ape already started")
+    }
+    created = true;
+    expressWs(app)
+    const controllers = loader(where)
+
+    // Serve bundled client at /ape.js
+    app.get('/api/ape.js', (req, res) => {
+        res.sendFile(path.join(__dirname, '../../dist/ape.js'))
+    })
+
+    app.ws('/api/ape', wiring(controllers, onConnent))
+}

package/server/lib/wiring.js

@@ -0,0 +1,94 @@
+const replySecurity = require('../security/reply')
+const socketOpen = require('../socket/open')
+const socketReceive = require('../socket/receive')
+const socketSend = require('../socket/send')
+const makeid = require('../utils/genId')
+const UAParser = require('ua-parser-js');
+const { addClient, removeClient } = require('./broadcast')
+
+const parser = new UAParser();
+
+// connent, beforeSend, beforeReceive, error, afterSend, afterReceive, disconnent
+
+
+function defaultEvents(events = {}) {
+    const fallBackEvents = {
+        embed: {},
+        onReceive: () => { },
+        onSend: () => { },
+        onError: (errSt) => console.error(errSt),
+        onDisconnent: () => { },
+    } // END fallBackEvents
+    return Object.assign({}, fallBackEvents, events)
+} // END defaultEvents
+
+//=====================================================
+//============================================== wiring
+//=====================================================
+
+module.exports = function wiring(controllers, onConnent) {
+    onConnent = onConnent || (() => { });
+    return function webSocketHandler(socket, req) {
+
+        let send;
+        let sentBufferAr = []
+        const sentBufferFn = (...args) => {
+            if (send) {
+                send(...args)
+            } else {
+                sentBufferAr.push(args)
+            }
+        } // END sentBufferFn
+
+        const hostId = makeid(20)
+        const agent = parser.setUA(req.headers['user-agent']).getResult()
+        const sharedValues = {
+            socket, req, agent, send: (type, data, err) => sentBufferFn(false, type, data, err)
+        }
+        sharedValues.send.toString = () => hostId
+
+
+        let result = onConnent(socket, req, sharedValues.send)
+        if (!result || !result.then) {
+            result = Promise.resolve(result)
+        }
+        result.then(defaultEvents)
+            .then(({ embed, onReceive, onSend, onError, onDisconnent }) => {
+                const isOk = socketOpen(socket, req, onError)
+
+                if (!isOk) {
+                    return;
+                }
+
+
+                const checkReply = replySecurity()
+                const ape = {
+                    socket,
+                    req,
+                    hostId,
+                    checkReply,
+                    events: { onReceive, onSend, onError, onDisconnent },
+                    controllers,
+                    sharedValues,
+                    embedValues: embed
+                }// END ape
+                send = socketSend(ape)
+                ape.send = send
+
+                // Track this client for broadcast
+                const clientInfo = { hostId, send, embed }
+                addClient(clientInfo)
+
+                // Remove client on disconnect
+                socket.on('close', () => {
+                    removeClient(clientInfo)
+                    onDisconnent()
+                })
+
+                sentBufferAr.forEach(args => send(...args))
+                sentBufferAr = []
+                socket.on('message', socketReceive(ape))
+            }) // END result.then
+
+    } // END webSocketHandler
+} // END wiring

package/server/security/extractRootDomain.js

@@ -0,0 +1,21 @@
+/**
+ * Extract root domain from a URL
+ * e.g., "https://sub.example.com:3000/path" -> "example.com"
+ */
+module.exports = function extractRootDomain(url) {
+    if (!url) return ''
+    try {
+        // Handle full URLs
+        if (url.includes('://')) {
+            const hostname = new URL(url).hostname
+            const parts = hostname.split('.')
+            return parts.length > 2 ? parts.slice(-2).join('.') : hostname
+        }
+        // Handle hostname:port format
+        const hostname = url.split(':')[0]
+        const parts = hostname.split('.')
+        return parts.length > 2 ? parts.slice(-2).join('.') : hostname
+    } catch {
+        return url.split(':')[0]
+    }
+}

package/server/security/origin.js

@@ -0,0 +1,13 @@
+const extractRootDomain = require('./extractRootDomain')
+
+module.exports = function (socket, req, onError) {
+  onError = onError || console.error
+  const origin = extractRootDomain(req.header('Origin') || "");
+  const host = extractRootDomain(req.header('Host'));
+  if (origin && origin !== host) {
+    onError("REJECTING socket from " + req.header('Origin') + " miss-match with " + req.header('Host'))
+    socket.destroy()
+    return false
+  }
+  return true
+}

package/server/security/reply.js

@@ -0,0 +1,21 @@
+module.exports = function(){
+  let requestCheck = []
+  return (queryId,createdAt)=>{
+    const startTime = Date.now();
+     if (createdAt > startTime) {
+       throw new Error("createdAt ahead of server by `${(createdAt - startTime) / 1000}secs. +${msg}`")
+    }
+    const tenSecAgo = startTime - 10000
+    if(createdAt < tenSecAgo) {
+       throw new Error("request is old by `${(startTime - createdAt) / 1000}secs. +${msg}`")
+    }
+    
+    requestCheck = requestCheck.filter(([passQueryId,createdWhen])=>{
+      if (passQueryId === queryId) {
+        throw new Error(`Reply: ${queryId} ${msg}`)
+      }
+      return createdWhen > tenSecAgo
+    })
+    requestCheck.push([queryId,createdAt])
+  } // END checkReply
+} // END replySecurity

package/server/socket/open.js

@@ -0,0 +1,10 @@
+const originSecurity = require( '../security/origin')
+
+module.exports = function open(socket, req, onError){
+
+    const isSecure = originSecurity(socket, req, onError)
+    if ( ! isSecure) {
+       return false;
+    }
+    return true
+}

package/server/socket/receive.js

@@ -0,0 +1,66 @@
+const messageHash = require('../../utils/messageHash')
+const { broadcast, online, getClients } = require('../lib/broadcast')
+const jss = require('../../utils/jss')
+
+module.exports = function receiveHandler(ape) {
+    const { send, checkReply, events, controllers, sharedValues, hostId, embedValues } = ape
+
+    // Build `this` context for controllers
+    // Includes: client metadata + api-ape utilities
+    const that = {
+        ...sharedValues,
+        ...embedValues,
+        // api-ape utilities available via `this`
+        broadcast: (type, data) => broadcast(type, data),
+        broadcastOthers: (type, data) => broadcast(type, data, hostId), // exclude self
+        online,
+        getClients,
+        hostId
+    }
+
+    return 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);
+        try {
+            const { type: rawType, data, referer, createdAt, requestedAt } = jss.parse(msgString);
+
+            // Normalize type: strip leading slash, lowercase
+            const type = rawType.replace(/^\//, '').toLowerCase()
+
+            // Call onReceive hook - it should return a finish callback
+            const onFinish = events.onReceive(queryId, data, type) || (() => { })
+
+            const result = new Promise((resolve, reject) => {
+                try {
+                    const controller = controllers[type]
+                    if (!controller) {
+                        throw `TypeError: "${type}" was not found`
+                    }
+                    checkReply(queryId, createdAt)
+                    resolve(controller.call(that, data))
+                } catch (err) {
+                    reject(err)
+                }
+            })
+            result.then(val => {
+                if (undefined !== val) {
+                    send(queryId, false, val, false)
+                }
+                if (typeof onFinish === 'function') {
+                    onFinish(false, val)
+                }
+            }).catch(err => {
+                send(queryId, false, false, err)
+                if (typeof onFinish === 'function') {
+                    onFinish(err, true)
+                }
+            })
+
+        } catch (err) {
+            const errMessage = err.message || err
+            events.onError(hostId, queryId, errMessage)
+        } // END catch
+
+    } // END onReceive
+} // END receiveHandler