yinzerflow 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [0.8.0] - 2026-04-24
+
+### Features
+
+- **WebSocket RFC 6455 frame protocol implementation** — Added complete frame protocol support with constants and type definitions for RFC 6455 compliance (4237a80)
+- **WebSocket handshake validation and connection class** — Implemented handshake validation logic and connection management class for WebSocket clients (6b4ca03)
+- **WebSocket framework integration with hooks and configuration** — Integrated WebSocket support into YinzerFlow with lifecycle hooks and configurable options (d344156)
+- **WebSocket channel pub/sub with encode-once broadcast** — Added publish/subscribe messaging system for WebSocket channels with efficient broadcast encoding (97de59a)
+- **WebSocket security controls and integration tests** — Implemented security controls and comprehensive integration test suite (3e6a2f5)
+- **WebSocket exports, documentation and verification** — Added public API exports, documentation, and verification sweep across the WebSocket implementation (3bbfb6a)
+
+### Bug Fixes
+
+- **Fix strict TypeScript build errors with exactOptionalPropertyTypes** — Resolved strict TypeScript compilation errors related to optional property types in WebSocket implementation (0e43ea7)
+- **Security hardening and naming convention improvements** — Applied security hardening measures, refactored test helpers to follow DRY principles, and improved naming conventions for consistency (bbe71b8)
+
+### Internal
+
+- **Format WebSocket exports for readability** — Improved code formatting and organization of WebSocket exports (ebfe6d3)
+- **Improve YinzerFlow code formatting** — Enhanced overall code formatting and consistency across the framework (1bcd868)
+- **Format WebSocket code consistently** — Applied consistent code formatting standards to WebSocket implementation (3e76ffc)
+
 ## [0.7.0] - 2026-02-20
 
 ### Bug Fixes

package/docs/core/websockets.md

@@ -0,0 +1,343 @@
+# 📖 WebSockets
+
+YinzerFlow includes production-level WebSocket support built on raw RFC 6455 — the same TCP-level approach as the HTTP server. No external dependencies.
+
+- **Channel-based pub/sub** with encode-once broadcast (frame encoded once, raw bytes to all subscribers)
+- **Per-socket typed data** — generics flow through all handlers
+- **Backpressure handling** — `'buffer'` (safe default) or `'drop'` (for real-time data like trading quotes)
+- **Hook integration** — `wsBeforeMessage` / `wsAfterMessage` for cross-cutting concerns
+- **Security** — origin validation, per-IP connection limits
+- **Zero overhead** when no `app.ws()` routes registered
+
+```typescript
+import { YinzerFlow } from 'yinzerflow';
+
+const app = new YinzerFlow({ port: 3000 });
+
+app.ws('/chat', {
+  open(ws) {
+    ws.subscribe('general');
+  },
+  message(ws, data) {
+    ws.publish('general', data as string);
+  },
+});
+
+await app.listen();
+```
+
+# ⚙️ Usage
+
+## 🎛️ Settings
+
+### websocket.maxPayloadLength — @default <span style="color: #2ecc71">`16777216`</span> (16MB)
+
+Maximum incoming message payload in bytes. Frames exceeding this limit trigger a close with code 1009.
+
+```typescript
+const app = new YinzerFlow({
+  websocket: {
+    maxPayloadLength: 1_048_576, // 1MB
+  },
+});
+```
+
+### websocket.idleTimeout — @default <span style="color: #2ecc71">`120`</span> (seconds)
+
+Seconds of inactivity before closing the connection. Set to `0` to disable.
+
+<span style="color: #f39c12">**⚡ Performance:**</span> For high-frequency data streams (trading quotes), the idle timeout resets on every received frame — frequent data prevents timeout.
+
+### websocket.maxConnectionsPerIp — @default <span style="color: #2ecc71">`50`</span>
+
+Maximum concurrent WebSocket connections from a single IP address.
+
+### websocket.allowedOrigins — @default <span style="color: #2ecc71">`[]`</span> (allow all)
+
+List of allowed origins for upgrade requests. Empty array allows all origins (including missing origin headers from non-browser clients).
+
+```typescript
+const app = new YinzerFlow({
+  websocket: {
+    allowedOrigins: ['https://app.example.com', 'https://admin.example.com'],
+  },
+});
+```
+
+### websocket.backpressure.strategy — @default <span style="color: #2ecc71">`'buffer'`</span>
+
+How to handle outgoing data when the client can't keep up:
+
+<aside>
+
+Options: `'buffer' | 'drop'`
+
+- `'buffer'`: Queue messages up to `limit` bytes, then close the connection. Safe default — no data loss unless the client is overwhelmed.
+- `'drop'`: Silently discard messages. Ideal for real-time data streams (trading quotes, live telemetry) where stale data is worse than gaps.
+</aside>
+
+```typescript
+// Trading data — drop stale quotes rather than buffering
+const app = new YinzerFlow({
+  websocket: {
+    backpressure: {
+      strategy: 'drop',
+    },
+  },
+});
+```
+
+### websocket.backpressure.limit — @default <span style="color: #2ecc71">`1048576`</span> (1MB)
+
+Maximum bytes to queue before closing the connection (only applies to `'buffer'` strategy).
+
+## 🔧 Route Registration
+
+### app.ws(path, handlers, options?)
+
+Register a WebSocket route. Supports parameterized paths (`:param`) just like HTTP routes.
+
+```typescript
+// Simple echo server
+app.ws('/echo', {
+  message(ws, data) {
+    ws.send(data);
+  },
+});
+
+// Parameterized path
+app.ws('/chat/:room', {
+  upgrade(req) {
+    return { room: req.params.room };
+  },
+  open(ws) {
+    ws.subscribe(`room:${ws.data.room}`);
+  },
+  message(ws, data) {
+    ws.publish(`room:${ws.data.room}`, data as string);
+  },
+});
+```
+
+### Handler Lifecycle
+
+| Handler | When | Use for |
+|---------|------|---------|
+| `upgrade(req)` | Before handshake | Auth, attach per-socket data, reject with `false` |
+| `open(ws)` | After handshake | Subscribe to channels, send welcome message |
+| `message(ws, data, isBinary)` | On each message | Business logic, pub/sub |
+| `close(ws, code, reason)` | On disconnect | Cleanup (unsubscribe is automatic) |
+| `error(ws, error)` | On socket error | Logging, alerting |
+| `drain(ws)` | When backpressure clears | Resume sending |
+
+### Per-Socket Typed Data
+
+The `upgrade` handler's return value becomes `ws.data` — fully typed via generics:
+
+```typescript
+app.ws<{ userId: string; role: string }>('/api/ws', {
+  upgrade(req) {
+    const token = req.headers.authorization;
+    const user = validateToken(token);
+    if (!user) return false; // 403 rejection
+    return { userId: user.id, role: user.role };
+  },
+  message(ws) {
+    console.log(ws.data.userId); // ✅ typed as string
+    console.log(ws.data.role);   // ✅ typed as string
+  },
+});
+```
+
+## 🔔 Pub/Sub
+
+### Channel Subscriptions
+
+```typescript
+ws.subscribe('channel-name');    // Join a channel
+ws.unsubscribe('channel-name');  // Leave a channel
+ws.isSubscribed('channel-name'); // Check membership
+```
+
+### Broadcasting
+
+```typescript
+// From inside a WS handler — excludes the sender
+ws.publish('quotes', JSON.stringify({ symbol: 'AAPL', price: 178.50 }));
+
+// From outside WS context (HTTP routes, timers, background jobs)
+app.publish('quotes', JSON.stringify({ symbol: 'AAPL', price: 178.50 }));
+
+// Check subscriber count
+const count = app.subscriberCount('quotes');
+```
+
+<span style="color: #3498db">**💡 Tip:**</span> `ws.publish()` excludes the sender automatically. `app.publish()` sends to all subscribers (no sender context).
+
+### Encode-Once Broadcast
+
+When publishing to a channel, the WebSocket frame is encoded **once** into raw bytes, then the same `Buffer` is written to every subscriber. This is O(messageSize + N×write) instead of O(N×messageSize) — critical for high-throughput scenarios like trading quote distribution.
+
+## 🪝 Hooks
+
+### WS Message Hooks
+
+Global hooks that run before/after every WebSocket message handler:
+
+```typescript
+app.wsBeforeMessage([
+  async (ws, data, isBinary) => {
+    console.log(`[WS] ${ws.remoteAddress}: ${String(data)}`);
+  },
+]);
+
+app.wsAfterMessage([
+  async (ws, data, isBinary) => {
+    // Metrics, logging, etc.
+  },
+]);
+```
+
+## 📡 The `ws` Object
+
+Available in all handlers:
+
+| Property/Method | Type | Description |
+|----------------|------|-------------|
+| `ws.send(data)` | `(string \| Buffer) => void` | Send a message |
+| `ws.close(code?, reason?)` | `(number?, string?) => void` | Close connection |
+| `ws.ping(data?)` | `(Buffer?) => void` | Send ping |
+| `ws.subscribe(channel)` | `(string) => void` | Join channel |
+| `ws.unsubscribe(channel)` | `(string) => void` | Leave channel |
+| `ws.publish(channel, data)` | `(string, string \| Buffer) => number` | Broadcast (excludes self) |
+| `ws.isSubscribed(channel)` | `(string) => boolean` | Check membership |
+| `ws.data` | `T` (readonly) | Per-socket data from upgrade |
+| `ws.readyState` | `number` (readonly) | Connection state |
+| `ws.remoteAddress` | `string` (readonly) | Client IP |
+| `ws.bufferedAmount` | `number` (readonly) | Queued bytes |
+
+# ✨ Best Practices
+
+- **Authenticate in `upgrade`** — reject unauthorized connections before the handshake completes, not after
+- **Use channels for grouping** — `ws.subscribe('user:123')` rather than manual connection tracking
+- **Set `strategy: 'drop'` for real-time data** — stale trading quotes are worse than gaps
+- **Keep message handlers fast** — expensive work should be dispatched to background jobs
+- **Clean up in `close`** — though channel unsubscription is automatic
+
+# 💻 Examples
+
+### Production API — Real-Time Trading Data
+
+**Use Case:** Push market quotes to subscribed clients with minimal latency
+
+**Description:** HTTP endpoints ingest quote data and publish to WebSocket subscribers. Backpressure uses `'drop'` strategy — stale quotes are discarded if a client can't keep up.
+
+```typescript
+import { YinzerFlow } from 'yinzerflow';
+
+const app = new YinzerFlow({
+  port: 3000,
+  websocket: {
+    maxPayloadLength: 65_536,
+    idleTimeout: 300,
+    allowedOrigins: ['https://trading.example.com'],
+    backpressure: { strategy: 'drop' },
+  },
+});
+
+// WebSocket: clients subscribe to symbol channels
+app.ws<{ symbols: Array<string> }>('/quotes', {
+  upgrade(req) {
+    const token = req.headers.authorization;
+    const user = validateToken(token);
+    if (!user) return false;
+    const symbols = req.query.symbols?.split(',') ?? [];
+    return { symbols };
+  },
+  open(ws) {
+    for (const symbol of ws.data.symbols) {
+      ws.subscribe(`quote:${symbol}`);
+    }
+    ws.send(JSON.stringify({ type: 'subscribed', symbols: ws.data.symbols }));
+  },
+  message(ws, data) {
+    const msg = JSON.parse(data as string);
+    if (msg.type === 'subscribe') {
+      ws.subscribe(`quote:${msg.symbol}`);
+    }
+  },
+});
+
+// HTTP: ingest quotes and broadcast to subscribers
+app.post('/api/quotes', (ctx) => {
+  const { symbol, price, volume } = ctx.request.body;
+  const count = app.publish(
+    `quote:${symbol}`,
+    JSON.stringify({ type: 'quote', symbol, price, volume, ts: Date.now() }),
+  );
+  return { broadcast: count };
+});
+
+await app.listen();
+```
+
+### Dev API — Echo Server
+
+**Use Case:** Development and testing
+
+**Description:** Simple echo server with logging for debugging WebSocket connections.
+
+```typescript
+import { YinzerFlow } from 'yinzerflow';
+
+const app = new YinzerFlow({
+  port: 3000,
+  logging: { level: 'debug' },
+});
+
+app.ws('/echo', {
+  open(ws) {
+    ws.send('Connected to echo server');
+  },
+  message(ws, data, isBinary) {
+    ws.send(data);
+  },
+  close(ws, code, reason) {
+    console.log(`Disconnected: ${code} ${reason}`);
+  },
+});
+
+await app.listen();
+```
+
+## 🚀 Performance Notes
+
+- **Encode-once broadcast**: Publishing to N subscribers encodes the frame once. 1000 subscribers = 1 encode + 1000 writes, not 1000 encodes.
+- **In-place XOR unmasking**: Client frames are unmasked by mutating the buffer directly — zero allocation.
+- **`Buffer.allocUnsafe`** for outgoing frames — skips zero-fill since the entire buffer is written before use.
+- **Zero overhead** when no `app.ws()` routes: no upgrade detection, no Sets allocated, no security instances created.
+- **Idle timeout** resets on every received frame — high-frequency data streams won't trigger timeout.
+
+## 🔒 Security Notes
+
+### 🛡️ Origin Validation
+- **Problem**: Unauthorized origins connecting to WebSocket endpoints
+- **YinzerFlow Solution**: `websocket.allowedOrigins` validates the Origin header during upgrade. Case-insensitive matching. Empty list = allow all (for server-to-server or development).
+
+### 🛡️ Connection Limits
+- **Problem**: Connection exhaustion from a single IP
+- **YinzerFlow Solution**: `websocket.maxConnectionsPerIp` limits concurrent connections. Returns 429 when exceeded. Counter automatically decrements on disconnect.
+
+### 🛡️ Payload Size Limits
+- **Problem**: Memory exhaustion from oversized messages
+- **YinzerFlow Solution**: `websocket.maxPayloadLength` checked on frame header before buffering. Exceeding triggers close with code 1009 (Too Large).
+
+## 🔧 Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| 403 on upgrade | Origin not in `allowedOrigins` | Add origin or set `allowedOrigins: []` |
+| 429 on upgrade | Too many connections from IP | Increase `maxConnectionsPerIp` |
+| Connection drops silently | Idle timeout | Increase `idleTimeout` or send periodic pings |
+| Messages not received | Client backpressured with `'drop'` | Switch to `'buffer'` or increase client throughput |
+| `ws.data` is `undefined` | No `upgrade` handler | Add `upgrade(req) { return { ... } }` |