api-ape 1.1.0 → 2.1.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
@@ -77,6 +89,7 @@ Include the bundled client and start calling:
 * **Real-time broadcasts** — Built-in `broadcast()` and `broadcastOthers()` methods for pushing to clients
 * **Promise-based calls** — Chainable paths like `ape.users.list()` map to `api/users/list.js`
 * **Automatic reconnection** — Client auto-reconnects on disconnect with exponential backoff
+* **HTTP streaming fallback** — Automatically falls back to long polling when WebSockets are blocked
 * **JJS Encoding** — Extended JSON supporting Date, RegExp, Error, Set, Map, undefined, and circular refs
 * **Connection lifecycle hooks** — Customize behavior on connect, receive, send, error, and disconnect
 
@@ -86,12 +99,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)) |
 
@@ -139,6 +153,53 @@ ape.on('notification', ({ data, err, type }) => {
 })
 ```
 
+#### `ape.configure(options)`
+
+Configure client connection options.
+
+```js
+// Configure transport mode
+ape.configure({ transport: 'auto' })      // Auto-detect (default)
+ape.configure({ transport: 'websocket' }) // Force WebSocket only
+ape.configure({ transport: 'polling' })   // Force HTTP streaming
+
+// Configure connection details
+ape.configure({ 
+  port: 9010,
+  host: 'example.com',
+  transport: 'auto'
+})
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `port` | `number` | Server port (default: auto-detect) |
+| `host` | `string` | Server hostname (default: auto-detect) |
+| `transport` | `string` | Transport mode: `'auto'`, `'websocket'`, or `'polling'` |
+
+#### `ape.getTransport()`
+
+Get the currently active transport type.
+
+```js
+const transport = ape.getTransport()
+console.log(transport) // 'websocket' | 'polling' | null
+```
+
+#### `ape.onConnectionChange(handler)`
+
+Listen for connection state changes.
+
+```js
+const unsubscribe = ape.onConnectionChange((state) => {
+  console.log('Connection state:', state)
+  // 'disconnected' | 'connecting' | 'connected'
+})
+
+// Later: stop listening
+unsubscribe()
+```
+
 ---
 
 ## Configuration
@@ -146,7 +207,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 +218,7 @@ ape(app, {
 Customize behavior per connection:
 
 ```js
-ape(app, {
+ape(server, {
   where: 'api',
   onConnent(socket, req, hostId) {
     return {
@@ -282,6 +343,48 @@ This is automatic — send a Date, receive a Date. No configuration needed.
 
 ---
 
+## HTTP Streaming Fallback
+
+api-ape automatically falls back to HTTP streaming when WebSockets are unavailable or blocked by firewalls/proxies.
+
+### How It Works
+
+1. **WebSocket First**: Client attempts WebSocket connection (4 second timeout)
+2. **Auto-Fallback**: On failure, switches to HTTP streaming transport
+3. **Background Retry**: Keeps attempting WebSocket reconnection every 30 seconds
+4. **Auto-Upgrade**: Switches back to WebSocket when available
+
+### Streaming Transport
+
+When in polling mode:
+- **GET `/api/ape/poll`**: Long-lived connection, server streams JSON messages
+- **POST `/api/ape/poll`**: Client sends messages
+- Cookie-based session (`apeHostId`) for authentication
+- Heartbeat every 20 seconds to prevent proxy timeout
+
+### Force Transport Mode
+
+```js
+// Force HTTP streaming (useful for testing)
+ape.configure({ transport: 'polling' })
+
+// Force WebSocket only (fail if unavailable)
+ape.configure({ transport: 'websocket' })
+
+// Auto-detect (default)
+ape.configure({ transport: 'auto' })
+```
+
+### Check Active Transport
+
+```js
+if (ape.getTransport() === 'polling') {
+  console.log('Using HTTP streaming fallback')
+}
+```
+
+---
+
 ## Examples & Demos
 
 The repository contains working examples:
@@ -328,7 +431,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
 
@@ -460,7 +563,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/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, getTransport } = connectSocket()
 connectSocket.autoReconnect()
 
 // Global API - use defineProperty to bypass Proxy interception
@@ -15,3 +15,21 @@ Object.defineProperty(window.ape, 'on', {
     enumerable: false,
     configurable: false
 })
+Object.defineProperty(window.ape, 'onConnectionChange', {
+    value: onConnectionChange,
+    writable: false,
+    enumerable: false,
+    configurable: false
+})
+Object.defineProperty(window.ape, 'configure', {
+    value: connectSocket.configure,
+    writable: false,
+    enumerable: false,
+    configurable: false
+})
+Object.defineProperty(window.ape, 'getTransport', {
+    value: getTransport,
+    writable: false,
+    enumerable: false,
+    configurable: false
+})