recker 1.0.83 → 1.0.84-next.ca0ad49

package/README.md

@@ -4,7 +4,7 @@
 
 ### Multi-Protocol SDK for the AI Era
 
-Nine protocols unified: HTTP, WebSocket, DNS, WHOIS, RDAP, FTP, SFTP, Telnet, HLS.
+Ten protocols unified: HTTP, WebSocket, DNS, WHOIS, RDAP, FTP, SFTP, Telnet, HLS, Raffel.
 <br>
 AI-native: OpenAI, Anthropic, Google, Ollama + MCP server with 70 tools.
 <br>
@@ -108,13 +108,14 @@ await recker.whois('github.com');      // WHOIS
 await recker.dns('google.com');        // DNS
 await recker.ai.chat('Hello!');        // AI
 recker.ws('wss://example.com/socket'); // WebSocket
+recker.raffel('ws://game:9999');       // Raffel
 ```
 
 ## What's Inside
 
 | Category | Features |
 |:---------|:---------|
-| **Protocols** | HTTP/2, WebSocket, DNS, WHOIS, RDAP, FTP, SFTP, Telnet, HLS |
+| **Protocols** | HTTP/2, WebSocket, DNS, WHOIS, RDAP, FTP, SFTP, Telnet, HLS, Raffel |
 | **AI** | OpenAI, Anthropic, Google, Ollama, Groq, Mistral + streaming |
 | **Resilience** | Retry, circuit breaker, rate limiting, request deduplication |
 | **Auth** | Basic, Bearer, OAuth2, AWS SigV4, Digest, API Key + 15 providers |
@@ -197,6 +198,23 @@ await spider.crawl('https://protected-site.com');
 
 [📖 Anti-blocking docs](https://forattini-dev.github.io/recker/#/scraping/06-anti-blocking)
 
+### Raffel Protocol
+
+```typescript
+import { createRaffelClient } from 'recker';
+
+const client = createRaffelClient('ws://api:3000', { reconnect: true });
+await client.connect();
+
+const user = await client.call<User>('users.get', { id: 42 });
+client.subscribe('notifications', (event, data) => console.log(event, data));
+client.notify('analytics.track', { event: 'page_view' });
+```
+
+Recker connects. Raffel serves. One protocol, zero glue.
+
+[→ Raffel Documentation](https://forattini-dev.github.io/recker/#/protocols/10-raffel)
+
 ### 48 API Presets
 
 Pre-configured clients for popular services:

package/dist/mcp/resources/index.js

@@ -161,6 +161,17 @@ export class ResourceRegistry {
                 mimeType: 'text/markdown',
                 text: this.getBenchmarkSummary(),
             }]);
+        this.registerResource({
+            uri: 'recker://docs/raffel',
+            name: 'Raffel Protocol Client',
+            description: 'Connect to Raffel servers: RPC calls, channels, events, error handling',
+            mimeType: 'text/markdown',
+        }, () => [{
+                type: 'resource',
+                uri: 'recker://docs/raffel',
+                mimeType: 'text/markdown',
+                text: RAFFEL_DOCS,
+            }]);
         this.registerResource({
             uri: 'recker://seo/checklist',
             name: 'SEO Technical Checklist',
@@ -1091,3 +1102,122 @@ function getErrorMessage(error) {
         return String(error);
     }
 }
+const RAFFEL_DOCS = `# Raffel Protocol Client
+
+Connect to Raffel servers with type-safe RPC, channels, and events over WebSocket.
+
+## Setup
+
+\`\`\`typescript
+import { createRaffelClient, RaffelError } from 'recker';
+// or: import { RaffelClient } from 'recker';
+// or: recker.raffel(url, options)
+\`\`\`
+
+## Connect & Close
+
+\`\`\`typescript
+// Transport auto-detected from URL: ws://, http://, tcp://, udp://, http://host/rpc
+const client = createRaffelClient('ws://localhost:3000', {
+  defaultTimeout: 10000,
+  channels: ['lobby'],
+  ws: {                               // WebSocket-specific options
+    reconnect: true,
+    reconnectDelay: 1000,
+    maxReconnectAttempts: 5,
+    heartbeatInterval: 30000,
+    headers: { Authorization: 'Bearer token' },
+  },
+});
+// HTTP: createRaffelClient('http://api:3000', { http: { timeout: 10000 } })
+// TCP:  createRaffelClient('tcp://svc:9000', { tcp: { reconnect: true } })
+// UDP:  createRaffelClient('udp://svc:9000')
+// JSON-RPC: createRaffelClient('http://api:3000/rpc')
+await client.connect();
+client.close();
+\`\`\`
+
+## RPC Calls
+
+\`\`\`typescript
+const user = await client.call<User>('users.get', { id: 42 });
+const data = await client.call('slow.op', payload, { timeout: 60000 });
+const res  = await client.call('search', query, { signal: abortController.signal });
+client.cancel('req-3');  // Cancel in-flight call
+\`\`\`
+
+## Fire-and-Forget
+
+\`\`\`typescript
+client.notify('analytics.track', { event: 'click' });
+\`\`\`
+
+## Channels
+
+\`\`\`typescript
+client.subscribe('chat', (event, data) => console.log(event, data));
+client.publish('chat', 'message', { text: 'Hello' });
+client.unsubscribe('chat');
+\`\`\`
+
+## Events
+
+| Event | Args | Description |
+|---|---|---|
+| raffel:connected | — | Connected |
+| raffel:disconnected | — | Disconnected |
+| raffel:event | (procedure, payload) | Server event |
+| raffel:channel:subscribed | (channel, members?) | Joined channel |
+| raffel:channel:unsubscribed | (channel) | Left channel |
+| raffel:channel:event | (channel, event, data) | Channel event |
+| ws:reconnecting | (attempt, delay) | Reconnecting |
+| ws:error | (error) | WebSocket error |
+
+## Error Handling
+
+\`\`\`typescript
+try {
+  await client.call('users.get', { id: 999 });
+} catch (err) {
+  if (err instanceof RaffelError) {
+    err.code;       // "NOT_FOUND"
+    err.status;     // 404
+    err.procedure;  // "users.get"
+    err.details;    // optional server details
+  }
+}
+\`\`\`
+
+## Properties
+
+- \`client.isConnected\` — boolean
+- \`client.raw\` — underlying RaffelTransport
+- \`client.rawWs\` — underlying ReckerWebSocket (null for non-WS transports)
+
+## Capability Matrix
+
+| Method | WS | HTTP | TCP | UDP | JSON-RPC |
+|---|:---:|:---:|:---:|:---:|:---:|
+| call() | ✅ | ✅ | ✅ | ✅ | ✅ |
+| callStream() | ✅ | ✅ (SSE) | ✅ | ❌ | ❌ |
+| notify() | ✅ | ✅ | ✅ | ✅ | ✅ |
+| subscribe() | ✅ | ❌ | ✅ | ❌ | ❌ |
+| publish() | ✅ | ❌ | ✅ | ❌ | ❌ |
+| cancel() | ✅ | ❌ | ✅ | ❌ | ❌ |
+
+## Example
+
+\`\`\`typescript
+const api = createRaffelClient('ws://api:3000', {
+  channels: ['notifications'],
+  channelHandlers: {
+    notifications: (event, data) => showToast(data),
+  },
+  ws: { reconnect: true },
+});
+await api.connect();
+
+const user = await api.call('auth.verify', { token });
+api.notify('presence.online', { userId: user.id });
+\`\`\`
+`;

package/dist/raffel/client.d.ts

@@ -1,5 +1,6 @@
 import { ReckerWebSocket } from '../websocket/client.js';
 import type { RaffelClientOptions, RaffelCallOptions, ChannelEventHandler } from './types.js';
+import type { RaffelTransport } from './transport.js';
 type Listener = (...args: any[]) => void;
 declare class SimpleEmitter {
     private listeners;
@@ -9,30 +10,37 @@ declare class SimpleEmitter {
     emit(event: string, ...args: any[]): boolean;
 }
 export declare class RaffelClient extends SimpleEmitter {
-    private ws;
+    private transport;
     private pendingCalls;
     private subscribedChannels;
     private idCounter;
     private defaultTimeout;
     private onEvent?;
+    private url;
+    private options;
     constructor(url: string, options?: RaffelClientOptions);
+    private ensureTransport;
+    _setTransport(transport: RaffelTransport): void;
+    private wireTransportEvents;
     connect(): Promise<void>;
     close(code?: number, reason?: string): void;
     get isConnected(): boolean;
-    get raw(): ReckerWebSocket;
+    get raw(): RaffelTransport;
+    get rawWs(): ReckerWebSocket | null;
     call<T = unknown>(procedure: string, payload?: unknown, options?: RaffelCallOptions): Promise<T>;
+    callStream<T = unknown>(procedure: string, payload?: unknown): AsyncIterable<T>;
     notify(procedure: string, payload?: unknown): void;
     subscribe(channel: string, handler?: ChannelEventHandler): void;
     unsubscribe(channel: string): void;
     publish(channel: string, event: string, data?: unknown): void;
     cancel(id: string): void;
-    private handleMessage;
+    private executeWithTimeout;
+    private handleIncoming;
     private handleEnvelope;
     private handleChannelMessage;
     private nextId;
     private extractBaseId;
     private sendChannelSubscribe;
-    private sendRaw;
 }
 export declare function createRaffelClient(url: string, options?: RaffelClientOptions): RaffelClient;
 export {};

package/dist/raffel/client.js

@@ -1,5 +1,8 @@
-import { ReckerWebSocket } from '../websocket/client.js';
+import { UnsupportedError } from '../core/errors.js';
 import { RaffelError } from './types.js';
+import { TransportCapability, hasExecute, hasCapability } from './transport.js';
+import { WsTransport } from './transport-ws.js';
+import { createTransport, detectTransportType } from './transport-factory.js';
 class SimpleEmitter {
     listeners = new Map();
     on(event, listener) {
@@ -35,38 +38,52 @@ class SimpleEmitter {
     }
 }
 export class RaffelClient extends SimpleEmitter {
-    ws;
+    transport;
     pendingCalls = new Map();
     subscribedChannels = new Map();
     idCounter = 0;
     defaultTimeout;
     onEvent;
+    url;
+    options;
     constructor(url, options = {}) {
         super();
-        const { channels, channelHandlers, onEvent, defaultTimeout, ...wsOptions } = options;
-        this.defaultTimeout = defaultTimeout ?? 30_000;
-        this.onEvent = onEvent;
-        this.ws = new ReckerWebSocket(url, wsOptions);
-        if (channels) {
-            for (const ch of channels) {
-                this.subscribedChannels.set(ch, channelHandlers?.[ch] ?? null);
+        this.url = url;
+        this.options = options;
+        this.defaultTimeout = options.defaultTimeout ?? 30_000;
+        this.onEvent = options.onEvent;
+        if (options.channels) {
+            for (const ch of options.channels) {
+                this.subscribedChannels.set(ch, options.channelHandlers?.[ch] ?? null);
             }
         }
-        if (channelHandlers) {
-            for (const [ch, handler] of Object.entries(channelHandlers)) {
+        if (options.channelHandlers) {
+            for (const [ch, handler] of Object.entries(options.channelHandlers)) {
                 if (!this.subscribedChannels.has(ch)) {
                     this.subscribedChannels.set(ch, handler);
                 }
             }
         }
-        this.ws.on('message', (msg) => this.handleMessage(msg));
-        this.ws.on('open', () => {
+    }
+    async ensureTransport() {
+        if (this.transport)
+            return;
+        this.transport = await createTransport(this.url, this.options);
+        this.wireTransportEvents();
+    }
+    _setTransport(transport) {
+        this.transport = transport;
+        this.wireTransportEvents();
+    }
+    wireTransportEvents() {
+        this.transport.on('message', (data) => this.handleIncoming(data));
+        this.transport.on('connected', () => {
             this.emit('raffel:connected');
             for (const [channel] of this.subscribedChannels) {
                 this.sendChannelSubscribe(channel);
             }
         });
-        this.ws.on('close', (_code, _reason) => {
+        this.transport.on('disconnected', () => {
             this.emit('raffel:disconnected');
             for (const [id, pending] of this.pendingCalls) {
                 if (pending.timer)
@@ -75,15 +92,16 @@ export class RaffelClient extends SimpleEmitter {
             }
             this.pendingCalls.clear();
         });
-        this.ws.on('reconnecting', (attempt, delay) => {
+        this.transport.on('reconnecting', (attempt, delay) => {
             this.emit('ws:reconnecting', attempt, delay);
         });
-        this.ws.on('error', (err) => {
+        this.transport.on('error', (err) => {
             this.emit('ws:error', err);
         });
     }
     async connect() {
-        return this.ws.connect();
+        await this.ensureTransport();
+        return this.transport.connect();
     }
     close(code, reason) {
         for (const [id, pending] of this.pendingCalls) {
@@ -92,13 +110,18 @@ export class RaffelClient extends SimpleEmitter {
             pending.reject(new Error(`Connection closed while waiting for response to ${id}`));
         }
         this.pendingCalls.clear();
-        this.ws.close(code, reason);
+        if (this.transport) {
+            this.transport.close(code, reason);
+        }
     }
     get isConnected() {
-        return this.ws.isConnected;
+        return this.transport?.isConnected ?? false;
     }
     get raw() {
-        return this.ws;
+        return this.transport;
+    }
+    get rawWs() {
+        return this.transport instanceof WsTransport ? this.transport.socket : null;
     }
     async call(procedure, payload, options) {
         const id = this.nextId();
@@ -110,6 +133,9 @@ export class RaffelClient extends SimpleEmitter {
             payload: payload ?? {},
             metadata: {},
         };
+        if (hasExecute(this.transport)) {
+            return this.executeWithTimeout(this.transport, envelope, timeout, procedure, options?.signal);
+        }
         return new Promise((resolve, reject) => {
             let timer = null;
             const cleanup = () => {
@@ -122,7 +148,7 @@ export class RaffelClient extends SimpleEmitter {
             };
             const onAbort = () => {
                 cleanup();
-                this.sendRaw({ id, type: 'cancel' });
+                this.transport.send({ id, type: 'cancel' });
                 reject(new Error(`Call to ${procedure} was aborted`));
             };
             if (timeout > 0) {
@@ -139,9 +165,75 @@ export class RaffelClient extends SimpleEmitter {
                 options.signal.addEventListener('abort', onAbort, { once: true });
             }
             this.pendingCalls.set(id, { resolve, reject, timer });
-            this.ws.sendJSON(envelope);
+            this.transport.send(envelope);
         });
     }
+    async *callStream(procedure, payload) {
+        if (!hasCapability(this.transport, TransportCapability.STREAM)) {
+            throw new UnsupportedError(`callStream() not supported over ${detectTransportType(this.url, this.options)}. Use WebSocket, HTTP, or TCP.`);
+        }
+        if (hasExecute(this.transport) && this.transport.executeStream) {
+            const envelope = {
+                id: this.nextId(),
+                procedure,
+                type: 'stream:start',
+                payload: payload ?? {},
+                metadata: {},
+            };
+            yield* this.transport.executeStream(envelope);
+            return;
+        }
+        const id = this.nextId();
+        const envelope = {
+            id,
+            procedure,
+            type: 'stream:start',
+            payload: payload ?? {},
+            metadata: {},
+        };
+        const queue = [];
+        let resolve = null;
+        const push = (item) => {
+            queue.push(item);
+            if (resolve) {
+                resolve();
+                resolve = null;
+            }
+        };
+        const streamHandler = (data) => {
+            if (!data.id || !data.id.startsWith(id))
+                return;
+            if (data.type === 'stream:data') {
+                push({ value: data.payload });
+            }
+            else if (data.type === 'stream:end') {
+                push({ done: true });
+                this.transport.off('message', streamHandler);
+            }
+            else if (data.type === 'error') {
+                push({ error: new RaffelError(data.payload, procedure) });
+                this.transport.off('message', streamHandler);
+            }
+        };
+        this.transport.on('message', streamHandler);
+        this.transport.send(envelope);
+        try {
+            while (true) {
+                if (queue.length === 0) {
+                    await new Promise((r) => { resolve = r; });
+                }
+                const item = queue.shift();
+                if (item.done)
+                    return;
+                if (item.error)
+                    throw item.error;
+                yield item.value;
+            }
+        }
+        finally {
+            this.transport.off('message', streamHandler);
+        }
+    }
     notify(procedure, payload) {
         const envelope = {
             id: this.nextId(),
@@ -150,26 +242,43 @@ export class RaffelClient extends SimpleEmitter {
             payload: payload ?? {},
             metadata: {},
         };
-        this.ws.sendJSON(envelope);
+        if (hasExecute(this.transport)) {
+            this.transport.execute({
+                ...envelope,
+                type: 'notify',
+            }).catch(() => { });
+        }
+        else {
+            this.transport.send(envelope);
+        }
     }
     subscribe(channel, handler) {
+        if (!hasCapability(this.transport, TransportCapability.SUBSCRIBE)) {
+            throw new UnsupportedError(`subscribe() not supported over ${detectTransportType(this.url, this.options)}. Use WebSocket or TCP.`);
+        }
         this.subscribedChannels.set(channel, handler ?? null);
-        if (this.ws.isConnected) {
+        if (this.transport.isConnected) {
             this.sendChannelSubscribe(channel);
         }
     }
     unsubscribe(channel) {
+        if (!hasCapability(this.transport, TransportCapability.SUBSCRIBE)) {
+            throw new UnsupportedError(`unsubscribe() not supported over ${detectTransportType(this.url, this.options)}. Use WebSocket or TCP.`);
+        }
         this.subscribedChannels.delete(channel);
-        if (this.ws.isConnected) {
+        if (this.transport.isConnected) {
             const msg = {
                 id: this.nextId(),
                 type: 'unsubscribe',
                 channel,
             };
-            this.ws.sendJSON(msg);
+            this.transport.send(msg);
         }
     }
     publish(channel, event, data) {
+        if (!hasCapability(this.transport, TransportCapability.PUBLISH)) {
+            throw new UnsupportedError(`publish() not supported over ${detectTransportType(this.url, this.options)}. Use WebSocket or TCP.`);
+        }
         const msg = {
             id: this.nextId(),
             type: 'publish',
@@ -177,9 +286,12 @@ export class RaffelClient extends SimpleEmitter {
             event,
             data,
         };
-        this.ws.sendJSON(msg);
+        this.transport.send(msg);
     }
     cancel(id) {
+        if (!hasCapability(this.transport, TransportCapability.CANCEL)) {
+            throw new UnsupportedError(`cancel() not supported over ${detectTransportType(this.url, this.options)}. Use WebSocket or TCP.`);
+        }
         const pending = this.pendingCalls.get(id);
         if (pending) {
             if (pending.timer)
@@ -187,26 +299,36 @@ export class RaffelClient extends SimpleEmitter {
             pending.reject(new Error(`Call ${id} was cancelled`));
             this.pendingCalls.delete(id);
         }
-        this.sendRaw({ id, type: 'cancel' });
+        this.transport.send({ id, type: 'cancel' });
     }
-    handleMessage(msg) {
-        if (typeof msg.data !== 'string')
-            return;
-        let parsed;
-        try {
-            parsed = JSON.parse(msg.data);
+    async executeWithTimeout(transport, envelope, timeout, procedure, signal) {
+        if (signal?.aborted) {
+            throw new Error(`Call to ${procedure} was aborted`);
         }
-        catch {
-            return;
+        const promises = [
+            transport.execute(envelope),
+        ];
+        if (timeout > 0) {
+            promises.push(new Promise((_, reject) => {
+                setTimeout(() => reject(new Error(`Call to ${procedure} timed out after ${timeout}ms`)), timeout);
+            }));
         }
-        if (parsed.channel) {
-            this.handleChannelMessage(parsed);
+        if (signal) {
+            promises.push(new Promise((_, reject) => {
+                signal.addEventListener('abort', () => reject(new Error(`Call to ${procedure} was aborted`)), { once: true });
+            }));
         }
-        else if (parsed.procedure || parsed.type === 'cancel') {
-            this.handleEnvelope(parsed);
+        return Promise.race(promises);
+    }
+    handleIncoming(data) {
+        if (data.channel) {
+            this.handleChannelMessage(data);
+        }
+        else if (data.procedure || data.type === 'cancel') {
+            this.handleEnvelope(data);
         }
         else {
-            this.emit('raffel:unknown', parsed);
+            this.emit('raffel:unknown', data);
         }
     }
     handleEnvelope(envelope) {
@@ -271,10 +393,7 @@ export class RaffelClient extends SimpleEmitter {
             type: 'subscribe',
             channel,
         };
-        this.ws.sendJSON(msg);
-    }
-    sendRaw(data) {
-        this.ws.sendJSON(data);
+        this.transport.send(msg);
     }
 }
 export function createRaffelClient(url, options) {

package/dist/raffel/index.d.ts

@@ -1,2 +1,9 @@
 export * from './client.js';
 export * from './types.js';
+export * from './transport.js';
+export * from './transport-ws.js';
+export * from './transport-http.js';
+export * from './transport-tcp.js';
+export * from './transport-udp.js';
+export * from './transport-jsonrpc.js';
+export { detectTransportType, createTransport } from './transport-factory.js';

package/dist/raffel/index.js

@@ -1,2 +1,9 @@
 export * from './client.js';
 export * from './types.js';
+export * from './transport.js';
+export * from './transport-ws.js';
+export * from './transport-http.js';
+export * from './transport-tcp.js';
+export * from './transport-udp.js';
+export * from './transport-jsonrpc.js';
+export { detectTransportType, createTransport } from './transport-factory.js';

package/dist/raffel/transport-factory.d.ts

@@ -0,0 +1,4 @@
+import type { RaffelTransport } from './transport.js';
+import type { RaffelClientOptions, RaffelTransportType } from './types.js';
+export declare function detectTransportType(url: string, options?: RaffelClientOptions): RaffelTransportType;
+export declare function createTransport(url: string, options?: RaffelClientOptions): Promise<RaffelTransport>;

package/dist/raffel/transport-factory.js

@@ -0,0 +1,52 @@
+import { WsTransport } from './transport-ws.js';
+export function detectTransportType(url, options) {
+    if (options?.transport)
+        return options.transport;
+    const lower = url.toLowerCase();
+    if (lower.startsWith('ws://') || lower.startsWith('wss://')) {
+        return 'websocket';
+    }
+    if (lower.startsWith('tcp://')) {
+        return 'tcp';
+    }
+    if (lower.startsWith('udp://')) {
+        return 'udp';
+    }
+    if (lower.startsWith('http://') || lower.startsWith('https://')) {
+        try {
+            const parsed = new URL(url);
+            if (parsed.pathname === '/rpc' || parsed.pathname.endsWith('/rpc')) {
+                return 'jsonrpc';
+            }
+        }
+        catch {
+        }
+        return 'http';
+    }
+    return 'websocket';
+}
+export async function createTransport(url, options = {}) {
+    const type = detectTransportType(url, options);
+    switch (type) {
+        case 'websocket':
+            return new WsTransport(url, options.ws);
+        case 'http': {
+            const { HttpTransport } = await import('./transport-http.js');
+            return new HttpTransport(url, options.http);
+        }
+        case 'tcp': {
+            const { TcpTransport } = await import('./transport-tcp.js');
+            return new TcpTransport(url, options.tcp);
+        }
+        case 'udp': {
+            const { UdpTransport } = await import('./transport-udp.js');
+            return new UdpTransport(url, options.udp);
+        }
+        case 'jsonrpc': {
+            const { JsonRpcTransport } = await import('./transport-jsonrpc.js');
+            return new JsonRpcTransport(url, options.jsonrpc);
+        }
+        default:
+            throw new Error(`Unknown transport type: ${type}`);
+    }
+}

package/dist/raffel/transport-http.d.ts

@@ -0,0 +1,25 @@
+import type { RaffelExecutableTransport, RaffelTransportEvent } from './transport.js';
+import type { RaffelEnvelope, RaffelHttpOptions } from './types.js';
+type Listener = (...args: any[]) => void;
+export declare class HttpTransport implements RaffelExecutableTransport {
+    readonly capabilities: number;
+    private client;
+    private connected;
+    private listeners;
+    private baseUrl;
+    constructor(url: string, options?: RaffelHttpOptions);
+    get isConnected(): boolean;
+    connect(): Promise<void>;
+    close(): void;
+    send(_data: unknown): void;
+    execute(envelope: RaffelEnvelope): Promise<unknown>;
+    executeStream(envelope: RaffelEnvelope): AsyncIterable<unknown>;
+    private parseSSE;
+    private getReader;
+    private parseBody;
+    on(event: RaffelTransportEvent, listener: Listener): void;
+    off(event: RaffelTransportEvent, listener: Listener): void;
+    once(event: RaffelTransportEvent, listener: Listener): void;
+    private emit;
+}
+export {};