ai.matey.http 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # ai.matey.http
 
+## 0.3.0
+
+### Minor Changes
+
+- d3fd2e2: Production HTTP endpoints: built-in `/health` + `/health/ready` + `/health/live`, Prometheus
+  `/metrics`, OpenAI-compatible `/v1/embeddings`, per-route rate limits via `RouteConfig.rateLimit`,
+  and a zero-dependency WebSocket streaming subpath (`ai.matey.http/websocket`).
+
+### Patch Changes
+
+- Updated dependencies [dae4d01]
+- Updated dependencies [e7df1d0]
+- Updated dependencies [d3fd2e2]
+- Updated dependencies [f227db2]
+- Updated dependencies [2912b7d]
+- Updated dependencies [aef9f4a]
+- Updated dependencies [78731bb]
+- Updated dependencies [b7e2312]
+  - ai.matey.types@0.3.0
+  - ai.matey.core@0.3.0
+  - ai.matey.http.core@0.3.0
+
 ## 0.2.1
 
 ### Patch Changes

package/dist/cjs/websocket/index.js

@@ -0,0 +1,160 @@
+"use strict";
+/**
+ * WebSocket Streaming
+ *
+ * Transport-agnostic WebSocket handler for real-time AI chat. Zero-dependency
+ * by design: instead of bundling a WebSocket implementation, it accepts any
+ * socket satisfying the structural {@link WebSocketLike} interface — Node
+ * `ws` sockets, `Deno.upgradeWebSocket` sockets, Bun sockets, or browser
+ * WebSockets all qualify.
+ *
+ * Wire protocol (JSON text frames):
+ * - client → server: `{ type: 'chat', id, request }`, `{ type: 'cancel', id }`
+ * - server → client: `{ type: 'start' | 'chunk' | 'done' | 'error', id, ... }`
+ *   plus periodic `{ type: 'ping' }` heartbeats
+ *
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createWebSocketHandler = createWebSocketHandler;
+exports.attachWebSocketServer = attachWebSocketServer;
+/**
+ * Create a per-connection handler streaming chat over a WebSocket.
+ *
+ * @example
+ * ```typescript
+ * import { WebSocketServer } from 'ws';
+ * import { createWebSocketHandler } from 'ai.matey.http/websocket';
+ *
+ * const handleSocket = createWebSocketHandler(bridge);
+ * new WebSocketServer({ port: 8080 }).on('connection', handleSocket);
+ * ```
+ */
+function createWebSocketHandler(bridge, options = {}) {
+    const maxConcurrentStreams = options.maxConcurrentStreams ?? 5;
+    const heartbeatMs = options.heartbeatMs ?? 30000;
+    return (socket) => {
+        const activeStreams = new Map();
+        const sendMessage = (message) => {
+            try {
+                socket.send(JSON.stringify(message));
+            }
+            catch (error) {
+                options.onError?.(error instanceof Error ? error : new Error(String(error)));
+            }
+        };
+        let heartbeat;
+        if (heartbeatMs > 0) {
+            heartbeat = setInterval(() => sendMessage({ type: 'ping' }), heartbeatMs);
+            if (typeof heartbeat === 'object' && 'unref' in heartbeat) {
+                heartbeat.unref();
+            }
+        }
+        const cleanup = () => {
+            if (heartbeat) {
+                clearInterval(heartbeat);
+            }
+            for (const controller of activeStreams.values()) {
+                controller.abort();
+            }
+            activeStreams.clear();
+        };
+        const runChat = async (id, request) => {
+            if (activeStreams.size >= maxConcurrentStreams) {
+                sendMessage({
+                    type: 'error',
+                    id,
+                    error: { message: `Too many concurrent streams (max ${maxConcurrentStreams})` },
+                });
+                return;
+            }
+            const controller = new AbortController();
+            activeStreams.set(id, controller);
+            sendMessage({ type: 'start', id });
+            try {
+                const stream = bridge.chatStream(request, { signal: controller.signal });
+                for await (const chunk of stream) {
+                    if (controller.signal.aborted) {
+                        break;
+                    }
+                    sendMessage({ type: 'chunk', id, chunk });
+                }
+                if (!controller.signal.aborted) {
+                    sendMessage({ type: 'done', id });
+                }
+            }
+            catch (error) {
+                if (!controller.signal.aborted) {
+                    sendMessage({
+                        type: 'error',
+                        id,
+                        error: { message: error instanceof Error ? error.message : String(error) },
+                    });
+                }
+            }
+            finally {
+                activeStreams.delete(id);
+            }
+        };
+        const onMessage = (raw) => {
+            let parsed;
+            try {
+                const text = typeof raw === 'string'
+                    ? raw
+                    : raw instanceof Uint8Array
+                        ? new TextDecoder().decode(raw)
+                        : String(raw);
+                parsed = JSON.parse(text);
+            }
+            catch {
+                sendMessage({ type: 'error', id: null, error: { message: 'Malformed JSON message' } });
+                return;
+            }
+            switch (parsed.type) {
+                case 'chat':
+                    if (!parsed.id || parsed.request === undefined) {
+                        sendMessage({
+                            type: 'error',
+                            id: parsed.id ?? null,
+                            error: { message: "'chat' requires 'id' and 'request'" },
+                        });
+                        return;
+                    }
+                    void runChat(parsed.id, parsed.request);
+                    break;
+                case 'cancel':
+                    activeStreams.get(parsed.id)?.abort();
+                    activeStreams.delete(parsed.id);
+                    break;
+                case 'pong':
+                    break;
+                default:
+                    sendMessage({
+                        type: 'error',
+                        id: null,
+                        error: {
+                            message: `Unknown message type: ${String(parsed.type)}`,
+                        },
+                    });
+            }
+        };
+        // Support both listener styles; extract data from DOM MessageEvent
+        if (socket.on) {
+            socket.on('message', (data) => onMessage(data));
+            socket.on('close', cleanup);
+            socket.on('error', cleanup);
+        }
+        else if (socket.addEventListener) {
+            socket.addEventListener('message', (event) => onMessage(event.data ?? event));
+            socket.addEventListener('close', cleanup);
+            socket.addEventListener('error', cleanup);
+        }
+    };
+}
+/**
+ * Attach the handler to a `ws`-style server's connection event.
+ */
+function attachWebSocketServer(server, bridge, options) {
+    server.on('connection', createWebSocketHandler(bridge, options));
+}
+//# sourceMappingURL=index.js.map

package/dist/cjs/websocket/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/websocket/index.ts"],"names":[],"mappings":"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"}

package/dist/esm/websocket/index.js

@@ -0,0 +1,156 @@
+/**
+ * WebSocket Streaming
+ *
+ * Transport-agnostic WebSocket handler for real-time AI chat. Zero-dependency
+ * by design: instead of bundling a WebSocket implementation, it accepts any
+ * socket satisfying the structural {@link WebSocketLike} interface — Node
+ * `ws` sockets, `Deno.upgradeWebSocket` sockets, Bun sockets, or browser
+ * WebSockets all qualify.
+ *
+ * Wire protocol (JSON text frames):
+ * - client → server: `{ type: 'chat', id, request }`, `{ type: 'cancel', id }`
+ * - server → client: `{ type: 'start' | 'chunk' | 'done' | 'error', id, ... }`
+ *   plus periodic `{ type: 'ping' }` heartbeats
+ *
+ * @module
+ */
+/**
+ * Create a per-connection handler streaming chat over a WebSocket.
+ *
+ * @example
+ * ```typescript
+ * import { WebSocketServer } from 'ws';
+ * import { createWebSocketHandler } from 'ai.matey.http/websocket';
+ *
+ * const handleSocket = createWebSocketHandler(bridge);
+ * new WebSocketServer({ port: 8080 }).on('connection', handleSocket);
+ * ```
+ */
+export function createWebSocketHandler(bridge, options = {}) {
+    const maxConcurrentStreams = options.maxConcurrentStreams ?? 5;
+    const heartbeatMs = options.heartbeatMs ?? 30000;
+    return (socket) => {
+        const activeStreams = new Map();
+        const sendMessage = (message) => {
+            try {
+                socket.send(JSON.stringify(message));
+            }
+            catch (error) {
+                options.onError?.(error instanceof Error ? error : new Error(String(error)));
+            }
+        };
+        let heartbeat;
+        if (heartbeatMs > 0) {
+            heartbeat = setInterval(() => sendMessage({ type: 'ping' }), heartbeatMs);
+            if (typeof heartbeat === 'object' && 'unref' in heartbeat) {
+                heartbeat.unref();
+            }
+        }
+        const cleanup = () => {
+            if (heartbeat) {
+                clearInterval(heartbeat);
+            }
+            for (const controller of activeStreams.values()) {
+                controller.abort();
+            }
+            activeStreams.clear();
+        };
+        const runChat = async (id, request) => {
+            if (activeStreams.size >= maxConcurrentStreams) {
+                sendMessage({
+                    type: 'error',
+                    id,
+                    error: { message: `Too many concurrent streams (max ${maxConcurrentStreams})` },
+                });
+                return;
+            }
+            const controller = new AbortController();
+            activeStreams.set(id, controller);
+            sendMessage({ type: 'start', id });
+            try {
+                const stream = bridge.chatStream(request, { signal: controller.signal });
+                for await (const chunk of stream) {
+                    if (controller.signal.aborted) {
+                        break;
+                    }
+                    sendMessage({ type: 'chunk', id, chunk });
+                }
+                if (!controller.signal.aborted) {
+                    sendMessage({ type: 'done', id });
+                }
+            }
+            catch (error) {
+                if (!controller.signal.aborted) {
+                    sendMessage({
+                        type: 'error',
+                        id,
+                        error: { message: error instanceof Error ? error.message : String(error) },
+                    });
+                }
+            }
+            finally {
+                activeStreams.delete(id);
+            }
+        };
+        const onMessage = (raw) => {
+            let parsed;
+            try {
+                const text = typeof raw === 'string'
+                    ? raw
+                    : raw instanceof Uint8Array
+                        ? new TextDecoder().decode(raw)
+                        : String(raw);
+                parsed = JSON.parse(text);
+            }
+            catch {
+                sendMessage({ type: 'error', id: null, error: { message: 'Malformed JSON message' } });
+                return;
+            }
+            switch (parsed.type) {
+                case 'chat':
+                    if (!parsed.id || parsed.request === undefined) {
+                        sendMessage({
+                            type: 'error',
+                            id: parsed.id ?? null,
+                            error: { message: "'chat' requires 'id' and 'request'" },
+                        });
+                        return;
+                    }
+                    void runChat(parsed.id, parsed.request);
+                    break;
+                case 'cancel':
+                    activeStreams.get(parsed.id)?.abort();
+                    activeStreams.delete(parsed.id);
+                    break;
+                case 'pong':
+                    break;
+                default:
+                    sendMessage({
+                        type: 'error',
+                        id: null,
+                        error: {
+                            message: `Unknown message type: ${String(parsed.type)}`,
+                        },
+                    });
+            }
+        };
+        // Support both listener styles; extract data from DOM MessageEvent
+        if (socket.on) {
+            socket.on('message', (data) => onMessage(data));
+            socket.on('close', cleanup);
+            socket.on('error', cleanup);
+        }
+        else if (socket.addEventListener) {
+            socket.addEventListener('message', (event) => onMessage(event.data ?? event));
+            socket.addEventListener('close', cleanup);
+            socket.addEventListener('error', cleanup);
+        }
+    };
+}
+/**
+ * Attach the handler to a `ws`-style server's connection event.
+ */
+export function attachWebSocketServer(server, bridge, options) {
+    server.on('connection', createWebSocketHandler(bridge, options));
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/websocket/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/websocket/index.ts"],"names":[],"mappings":"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"}

package/dist/types/websocket/index.d.ts

@@ -0,0 +1,95 @@
+/**
+ * WebSocket Streaming
+ *
+ * Transport-agnostic WebSocket handler for real-time AI chat. Zero-dependency
+ * by design: instead of bundling a WebSocket implementation, it accepts any
+ * socket satisfying the structural {@link WebSocketLike} interface — Node
+ * `ws` sockets, `Deno.upgradeWebSocket` sockets, Bun sockets, or browser
+ * WebSockets all qualify.
+ *
+ * Wire protocol (JSON text frames):
+ * - client → server: `{ type: 'chat', id, request }`, `{ type: 'cancel', id }`
+ * - server → client: `{ type: 'start' | 'chunk' | 'done' | 'error', id, ... }`
+ *   plus periodic `{ type: 'ping' }` heartbeats
+ *
+ * @module
+ */
+import type { Bridge } from 'ai.matey.core';
+/**
+ * Structural WebSocket interface (satisfied by ws, Deno, Bun, browsers).
+ */
+export interface WebSocketLike {
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    /** DOM-style listener registration. */
+    addEventListener?(type: 'message' | 'close' | 'error', listener: (event: unknown) => void): void;
+    /** Node ws-style listener registration. */
+    on?(type: 'message' | 'close' | 'error', listener: (...args: unknown[]) => void): void;
+}
+/**
+ * Client → server messages.
+ */
+export type WebSocketClientMessage = {
+    type: 'chat';
+    id: string;
+    request: unknown;
+} | {
+    type: 'cancel';
+    id: string;
+} | {
+    type: 'pong';
+};
+/**
+ * Server → client messages.
+ */
+export type WebSocketServerMessage = {
+    type: 'start';
+    id: string;
+} | {
+    type: 'chunk';
+    id: string;
+    chunk: unknown;
+} | {
+    type: 'done';
+    id: string;
+} | {
+    type: 'error';
+    id: string | null;
+    error: {
+        message: string;
+        code?: string;
+    };
+} | {
+    type: 'ping';
+};
+/**
+ * Options for the WebSocket handler.
+ */
+export interface WebSocketHandlerOptions {
+    /** Maximum concurrent streams per connection. @default 5 */
+    maxConcurrentStreams?: number;
+    /** Heartbeat interval in milliseconds (0 disables). @default 30000 */
+    heartbeatMs?: number;
+    /** Error observability hook. */
+    onError?: (error: Error) => void;
+}
+/**
+ * Create a per-connection handler streaming chat over a WebSocket.
+ *
+ * @example
+ * ```typescript
+ * import { WebSocketServer } from 'ws';
+ * import { createWebSocketHandler } from 'ai.matey.http/websocket';
+ *
+ * const handleSocket = createWebSocketHandler(bridge);
+ * new WebSocketServer({ port: 8080 }).on('connection', handleSocket);
+ * ```
+ */
+export declare function createWebSocketHandler(bridge: Bridge, options?: WebSocketHandlerOptions): (socket: WebSocketLike) => void;
+/**
+ * Attach the handler to a `ws`-style server's connection event.
+ */
+export declare function attachWebSocketServer(server: {
+    on(event: 'connection', listener: (socket: WebSocketLike) => void): void;
+}, bridge: Bridge, options?: WebSocketHandlerOptions): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/websocket/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/websocket/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,uCAAuC;IACvC,gBAAgB,CAAC,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAAC;IACjG,2CAA2C;IAC3C,EAAE,CAAC,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,OAAO,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;CACxF;AAED;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAC9B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAErB;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAC9B;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC7B;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAC7C;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC5B;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAC/E;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAErB;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,4DAA4D;IAC5D,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAE9B,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,gCAAgC;IAChC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,uBAA4B,GACpC,CAAC,MAAM,EAAE,aAAa,KAAK,IAAI,CAmIjC;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE;IAAE,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,IAAI,GAAG,IAAI,CAAA;CAAE,EACpF,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,uBAAuB,GAChC,IAAI,CAEN"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai.matey.http",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "HTTP framework adapters for AI Matey - Universal AI Adapter System",
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -76,6 +76,16 @@
         "types": "./dist/types/deno/index.d.ts",
         "default": "./dist/cjs/deno/index.js"
       }
+    },
+    "./websocket": {
+      "import": {
+        "types": "./dist/types/websocket/index.d.ts",
+        "default": "./dist/esm/websocket/index.js"
+      },
+      "require": {
+        "types": "./dist/types/websocket/index.d.ts",
+        "default": "./dist/cjs/websocket/index.js"
+      }
     }
   },
   "files": [