api-ape 1.0.2 → 2.0.0

package/example/Vite/src/style.css

@@ -0,0 +1,200 @@
+* {
+    box-sizing: border-box;
+    margin: 0;
+    padding: 0;
+}
+
+.container {
+    min-height: 100vh;
+    background: linear-gradient(135deg, #1a1a2e 0%, #16213e 50%, #0f3460 100%);
+    color: #fff;
+    font-family: -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif;
+}
+
+.main {
+    max-width: 600px;
+    margin: 0 auto;
+    padding: 2rem;
+    width: 100%;
+}
+
+.title {
+    font-size: 2.5rem;
+    text-align: center;
+    margin-bottom: 0.5rem;
+}
+
+.gradient {
+    background: linear-gradient(90deg, #00d2ff, #3a7bd5);
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent;
+    background-clip: text;
+}
+
+.subtitle {
+    text-align: center;
+    color: #0f0;
+    margin-bottom: 2rem;
+    font-weight: bold;
+}
+
+.join-form {
+    display: flex;
+    gap: 1rem;
+    justify-content: center;
+}
+
+.input {
+    padding: 1rem 1.5rem;
+    font-size: 1rem;
+    border: none;
+    border-radius: 50px;
+    background: rgba(255, 255, 255, 0.1);
+    color: #fff;
+    outline: none;
+    width: 250px;
+}
+
+.input::placeholder {
+    color: rgba(255, 255, 255, 0.5);
+}
+
+.button {
+    padding: 1rem 2rem;
+    font-size: 1rem;
+    border: none;
+    border-radius: 50px;
+    background: linear-gradient(90deg, #00d2ff, #3a7bd5);
+    color: #fff;
+    cursor: pointer;
+    font-weight: bold;
+    transition: opacity 0.2s;
+}
+
+.button:hover {
+    opacity: 0.9;
+}
+
+.button:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+}
+
+.chat-container {
+    background: rgba(255, 255, 255, 0.05);
+    border-radius: 20px;
+    overflow: hidden;
+    box-shadow: 0 20px 60px rgba(0, 0, 0, 0.3);
+}
+
+.header {
+    display: flex;
+    justify-content: space-between;
+    padding: 1rem 1.5rem;
+    background: rgba(255, 255, 255, 0.1);
+    font-weight: bold;
+}
+
+.user-count {
+    font-size: 0.85rem;
+    color: #0f0;
+}
+
+.messages {
+    height: 350px;
+    overflow-y: auto;
+    padding: 1rem;
+}
+
+.messages::-webkit-scrollbar {
+    width: 6px;
+}
+
+.messages::-webkit-scrollbar-track {
+    background: rgba(255, 255, 255, 0.05);
+}
+
+.messages::-webkit-scrollbar-thumb {
+    background: rgba(255, 255, 255, 0.2);
+    border-radius: 3px;
+}
+
+.empty-state {
+    text-align: center;
+    color: #666;
+    margin-top: 140px;
+}
+
+.message {
+    display: flex;
+    flex-direction: column;
+    gap: 0.25rem;
+    padding: 0.75rem 1rem;
+    margin-bottom: 0.5rem;
+    background: rgba(255, 255, 255, 0.05);
+    border-radius: 12px;
+    border-left: 3px solid #3a7bd5;
+}
+
+.my-message {
+    background: rgba(0, 210, 255, 0.15);
+    border-left-color: #00d2ff;
+}
+
+.message .username {
+    color: #00d2ff;
+    font-size: 0.85rem;
+}
+
+.message .time {
+    color: #666;
+    font-size: 0.7rem;
+}
+
+.input-form {
+    display: flex;
+    gap: 0.5rem;
+    padding: 1rem;
+    border-top: 1px solid rgba(255, 255, 255, 0.1);
+}
+
+.message-input {
+    flex: 1;
+    padding: 0.75rem 1rem;
+    font-size: 1rem;
+    border: none;
+    border-radius: 50px;
+    background: rgba(255, 255, 255, 0.1);
+    color: #fff;
+    outline: none;
+    transition: background 0.2s;
+}
+
+.message-input::placeholder {
+    color: rgba(255, 255, 255, 0.5);
+}
+
+.message-input:focus {
+    background: rgba(255, 255, 255, 0.15);
+}
+
+.send-button {
+    padding: 0.75rem 1.5rem;
+    font-size: 1rem;
+    border: none;
+    border-radius: 50px;
+    background: #3a7bd5;
+    color: #fff;
+    cursor: pointer;
+    font-weight: bold;
+    transition: opacity 0.2s;
+}
+
+.send-button:hover {
+    opacity: 0.9;
+}
+
+.send-button:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+}

package/example/Vite/src/vite-env.d.ts

@@ -0,0 +1,7 @@
+/// <reference types="vite/client" />
+
+declare module '*.vue' {
+    import type { DefineComponent } from 'vue'
+    const component: DefineComponent<{}, {}, any>
+    export default component
+}

package/example/Vite/vite.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+
+export default defineConfig({
+    plugins: [vue()],
+    server: {
+        port: 5173,
+        proxy: {
+            '/api': {
+                target: 'http://localhost:3000',
+                ws: true,
+                changeOrigin: true
+            }
+        }
+    },
+    build: {
+        outDir: 'dist',
+        emptyOutDir: true
+    }
+})

package/index.d.ts

@@ -1,7 +1,7 @@
 // Type definitions for api-ape
 // Project: https://github.com/codemeasandwich/api-ape
 
-import { Application } from 'express'
+import { Server as HttpServer } from 'http'
 import { WebSocket } from 'ws'
 import { IncomingMessage } from 'http'
 
@@ -94,9 +94,18 @@ export interface ApeServerOptions {
 }
 
 /**
- * Initialize api-ape on an Express app
+ * Initialize api-ape on a Node.js HTTP/HTTPS server
  */
-declare function ape(app: Application, options: ApeServerOptions): void
+declare function ape(server: HttpServer, options: ApeServerOptions): void
+
+declare namespace ape {
+    /** Broadcast to all connected clients */
+    export function broadcast(type: string, data: any, excludeHostId?: string): void
+    /** Get count of connected clients */
+    export function online(): number
+    /** Get all connected client hostIds */
+    export function getClients(): string[]
+}
 
 export default ape
 
@@ -104,6 +113,21 @@ export default ape
 // CLIENT TYPES
 // =============================================================================
 
+/**
+ * Connection state enum values
+ */
+export type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'closing'
+
+/**
+ * Connection state enum object
+ */
+export declare const ConnectionState: {
+    Disconnected: 'disconnected'
+    Connecting: 'connecting'
+    Connected: 'connected'
+    Closing: 'closing'
+}
+
 /**
  * Message received from server
  */
@@ -140,6 +164,8 @@ export type SetOnReceiver = {
 export interface ApeClient {
     sender: ApeSender
     setOnReciver: SetOnReceiver
+    /** Subscribe to connection state changes. Returns unsubscribe function. */
+    onConnectionChange: (handler: (state: ConnectionState) => void) => () => void
 }
 
 /**
@@ -161,6 +187,8 @@ export interface ConnectSocket {
     configure(options: ApeClientConfig): void
     /** Enable auto-reconnection on disconnect */
     autoReconnect(): void
+    /** Connection state enum */
+    ConnectionState: typeof ConnectionState
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api-ape",
-  "version": "1.0.2",
+  "version": "2.0.0",
   "description": "Remote procedure events",
   "main": "index.js",
   "types": "index.d.ts",
@@ -27,7 +27,6 @@
   },
   "homepage": "https://github.com/codemeasandwich/api-ape#readme",
   "dependencies": {
-    "express-ws": "^5.0.2",
     "jest": "^29.3.1",
     "ua-parser-js": "^1.0.37",
     "ws": "^8.14.0"
@@ -35,4 +34,4 @@
   "devDependencies": {
     "esbuild": "^0.27.2"
   }
-}
+}

package/server/README.md

@@ -11,6 +11,7 @@ server/
 │   ├── main.js       # Express integration & setup
 │   ├── loader.js     # Auto-loads controller files from folder
 │   ├── broadcast.js  # Client tracking & broadcast utilities
+│   ├── fileTransfer.js # Binary file transfer manager
 │   └── wiring.js     # WebSocket handler setup
 ├── socket/
 │   ├── receive.js    # Incoming message handler
@@ -52,6 +53,19 @@ app.listen(3000)
 |--------|------|-------------|
 | `where` | `string` | Directory containing controller files |
 | `onConnent` | `function` | Connection lifecycle hook |
+| `fileTransferOptions` | `object` | Binary transfer settings (see below) |
+
+### File Transfer Options
+
+```js
+ape(app, {
+  where: 'api',
+  fileTransferOptions: {
+    startTimeout: 60000,    // Time to wait for transfer start (ms)
+    completeTimeout: 60000  // Time after start before cleanup (ms)
+  }
+})
+```
 
 ### Controller Context (`this`)
 
@@ -91,3 +105,33 @@ api/
 │   ├── list.js   → ape.users.list(data)
 │   └── create.js → ape.users.create(data)
 ```
+
+## File Transfers
+
+Controllers can return `Buffer` data directly. The framework handles conversion:
+
+```js
+// api/files/download.js
+const fs = require('fs')
+
+module.exports = function(filename) {
+  return {
+    name: filename,
+    data: fs.readFileSync(`./uploads/${filename}`)
+  }
+}
+```
+
+For uploads, the controller receives `Buffer` data:
+
+```js
+// api/files/upload.js
+module.exports = function({ name, data }) {
+  // data is a Buffer
+  fs.writeFileSync(`./uploads/${name}`, data)
+  return { success: true }
+}
+```
+
+Binary data is transferred via `/api/ape/data/:hash` with session verification and HTTPS enforcement (localhost exempt).
+

package/server/index.js

@@ -1,6 +1,14 @@
 /**
  * api-ape server entry point
- * Exports the main ape function
+ * Exports the main ape function and broadcast utilities
  */
 
-module.exports = require('./lib/main')
+const ape = require('./lib/main')
+const { broadcast, online, getClients } = require('./lib/broadcast')
+
+// Attach broadcast utilities to the main function for clean exports
+ape.broadcast = broadcast
+ape.online = online
+ape.getClients = getClients
+
+module.exports = ape

package/server/lib/fileTransfer.js

@@ -0,0 +1,247 @@
+/**
+ * FileTransferManager - Handles temporary binary data endpoints
+ * 
+ * For downloads (server → client):
+ * - Registers binary data with a hash
+ * - Creates temporary endpoint at GET /api/ape/data/:hash
+ * - Verifies session before allowing download
+ * - Auto-cleanup after timeout
+ * 
+ * For uploads (client → server):
+ * - Registers upload expectation with queryId + pathHash
+ * - Receives data via PUT /api/ape/data/:queryId/:pathHash
+ * - Waits for matching WS message before processing
+ */
+
+// Default timeouts (configurable)
+const DEFAULT_START_TIMEOUT = 60 * 1000  // 1 minute to start download
+const DEFAULT_COMPLETE_TIMEOUT = 60 * 1000  // 1 minute after download starts
+
+class FileTransferManager {
+    constructor(options = {}) {
+        this.startTimeout = options.startTimeout || DEFAULT_START_TIMEOUT
+        this.completeTimeout = options.completeTimeout || DEFAULT_COMPLETE_TIMEOUT
+
+        // Map<hash, { data, contentType, sessionHostId, createdAt, downloadStarted, timer }>
+        this.pendingDownloads = new Map()
+
+        // Map<`${queryId}/${pathHash}`, { sessionHostId, createdAt, resolver, rejector, timer, data }>
+        this.pendingUploads = new Map()
+
+        // Cleanup interval
+        this._cleanupInterval = setInterval(() => this._cleanup(), 30000)
+    }
+
+    /**
+     * Register a binary download
+     * @param {string} hash - Unique hash for this download
+     * @param {Buffer|ArrayBuffer} data - Binary data to serve
+     * @param {string} contentType - MIME type (e.g., 'application/octet-stream')
+     * @param {string} sessionHostId - Host ID of the client session
+     * @returns {string} The hash (for confirmation)
+     */
+    registerDownload(hash, data, contentType, sessionHostId) {
+        // Clear any existing entry with same hash
+        if (this.pendingDownloads.has(hash)) {
+            const existing = this.pendingDownloads.get(hash)
+            if (existing.timer) clearTimeout(existing.timer)
+        }
+
+        const entry = {
+            data,
+            contentType: contentType || 'application/octet-stream',
+            sessionHostId,
+            createdAt: Date.now(),
+            downloadStarted: false,
+            timer: setTimeout(() => {
+                // Auto-remove if download never started
+                if (!this.pendingDownloads.get(hash)?.downloadStarted) {
+                    this.pendingDownloads.delete(hash)
+                    console.log(`📦 Download expired (never started): ${hash}`)
+                }
+            }, this.startTimeout)
+        }
+
+        this.pendingDownloads.set(hash, entry)
+        console.log(`📦 Registered download: ${hash} for session ${sessionHostId}`)
+        return hash
+    }
+
+    /**
+     * Get download data (called by HTTP handler)
+     * @param {string} hash - Download hash
+     * @param {string} requestingHostId - Host ID of requester (from session/cookie)
+     * @returns {{ data: Buffer, contentType: string } | null}
+     */
+    getDownload(hash, requestingHostId) {
+        const entry = this.pendingDownloads.get(hash)
+
+        if (!entry) {
+            console.warn(`📦 Download not found: ${hash}`)
+            return null
+        }
+
+        // Session verification
+        if (entry.sessionHostId !== requestingHostId) {
+            console.warn(`📦 Session mismatch for ${hash}: expected ${entry.sessionHostId}, got ${requestingHostId}`)
+            return null
+        }
+
+        // Mark download as started
+        if (!entry.downloadStarted) {
+            entry.downloadStarted = true
+            clearTimeout(entry.timer)
+
+            // Set new timer for cleanup after completion
+            entry.timer = setTimeout(() => {
+                this.pendingDownloads.delete(hash)
+                console.log(`📦 Download cleaned up: ${hash}`)
+            }, this.completeTimeout)
+        }
+
+        return {
+            data: entry.data,
+            contentType: entry.contentType
+        }
+    }
+
+    /**
+     * Register an expected upload
+     * @param {string} queryId - Query ID from WS message
+     * @param {string} pathHash - Hash of property path
+     * @param {string} sessionHostId - Host ID of the client session
+     * @returns {Promise<Buffer>} Resolves when upload is received
+     */
+    registerUpload(queryId, pathHash, sessionHostId) {
+        const key = `${queryId}/${pathHash}`
+
+        return new Promise((resolve, reject) => {
+            const entry = {
+                sessionHostId,
+                createdAt: Date.now(),
+                resolver: resolve,
+                rejector: reject,
+                data: null,
+                timer: setTimeout(() => {
+                    this.pendingUploads.delete(key)
+                    reject(new Error(`Upload timeout: ${key}`))
+                }, this.startTimeout)
+            }
+
+            this.pendingUploads.set(key, entry)
+            console.log(`📤 Registered upload expectation: ${key} for session ${sessionHostId}`)
+        })
+    }
+
+    /**
+     * Receive upload data (called by HTTP handler)
+     * @param {string} queryId - Query ID from URL
+     * @param {string} pathHash - Path hash from URL
+     * @param {Buffer} data - Uploaded binary data
+     * @param {string} requestingHostId - Host ID of uploader
+     * @returns {boolean} True if accepted
+     */
+    receiveUpload(queryId, pathHash, data, requestingHostId) {
+        const key = `${queryId}/${pathHash}`
+        const entry = this.pendingUploads.get(key)
+
+        if (!entry) {
+            console.warn(`📤 Upload not expected: ${key}`)
+            return false
+        }
+
+        // Session verification
+        if (entry.sessionHostId !== requestingHostId) {
+            console.warn(`📤 Session mismatch for upload ${key}: expected ${entry.sessionHostId}, got ${requestingHostId}`)
+            return false
+        }
+
+        // Clear timeout and resolve
+        clearTimeout(entry.timer)
+        entry.resolver(data)
+        this.pendingUploads.delete(key)
+        console.log(`📤 Upload received: ${key}`)
+
+        return true
+    }
+
+    /**
+     * Generate hash for download from queryId and property path
+     * @param {string} queryId - The query ID
+     * @param {string} propertyPath - The property path (e.g., 'files.0.data')
+     * @returns {string} Combined hash
+     */
+    static generateHash(queryId, propertyPath) {
+        // Simple hash combining queryId and path
+        // In production, could use crypto.createHash
+        const combined = `${queryId}:${propertyPath}`
+        let hash = 0
+        for (let i = 0; i < combined.length; i++) {
+            const char = combined.charCodeAt(i)
+            hash = ((hash << 5) - hash) + char
+            hash = hash & hash // Convert to 32bit integer
+        }
+        return Math.abs(hash).toString(36)
+    }
+
+    /**
+     * Cleanup expired entries
+     * @private
+     */
+    _cleanup() {
+        const now = Date.now()
+        const maxAge = this.startTimeout + this.completeTimeout
+
+        // Cleanup downloads
+        for (const [hash, entry] of this.pendingDownloads) {
+            if (now - entry.createdAt > maxAge) {
+                clearTimeout(entry.timer)
+                this.pendingDownloads.delete(hash)
+                console.log(`📦 Cleanup stale download: ${hash}`)
+            }
+        }
+
+        // Cleanup uploads
+        for (const [key, entry] of this.pendingUploads) {
+            if (now - entry.createdAt > maxAge) {
+                clearTimeout(entry.timer)
+                entry.rejector(new Error(`Upload expired: ${key}`))
+                this.pendingUploads.delete(key)
+                console.log(`📤 Cleanup stale upload: ${key}`)
+            }
+        }
+    }
+
+    /**
+     * Shutdown cleanup
+     */
+    destroy() {
+        clearInterval(this._cleanupInterval)
+
+        // Clear all timers
+        for (const entry of this.pendingDownloads.values()) {
+            clearTimeout(entry.timer)
+        }
+        for (const entry of this.pendingUploads.values()) {
+            clearTimeout(entry.timer)
+        }
+
+        this.pendingDownloads.clear()
+        this.pendingUploads.clear()
+    }
+}
+
+// Singleton instance
+let instance = null
+
+function getFileTransferManager(options) {
+    if (!instance) {
+        instance = new FileTransferManager(options)
+    }
+    return instance
+}
+
+module.exports = {
+    FileTransferManager,
+    getFileTransferManager
+}