@carlos-tzin/tzin 0.1.0

package/dist/server.js

@@ -0,0 +1,296 @@
+import { Value } from './schema.js';
+import { HttpError, isRawResult } from './contract.js';
+import { createMatcher } from './router.js';
+import { Ctx } from './context.js';
+import { compose } from './middleware.js';
+import { handleMcpMessage } from './mcp.js';
+import { renderLlmsTxt, renderLlmsFullTxt } from './llms.js';
+import { generateOpenApi } from './openapi.js';
+function validationError(section, schema, value) {
+    const errors = [...Value.Errors(schema, value)].map((e) => `${e.path || '/'}: ${e.message}`);
+    return new HttpError(400, `Invalid ${section}`, errors);
+}
+/**
+ * Responses tzin builds itself carry their serialized text alongside, so
+ * adapters can write them without draining the undici body stream — the
+ * single most expensive step of the over-network path (~7k req/s marginal).
+ * User-created responses (raw()) simply fall back to res.text().
+ */
+const FAST_TEXT = '__tzin_text';
+export function fastResponseText(res) {
+    return res[FAST_TEXT];
+}
+/**
+ * Responses tzin builds itself also carry their headers as a plain object,
+ * so adapters skip undici's Headers iteration entirely on the hot path.
+ */
+const FAST_HEADERS = '__tzin_headers';
+export function fastResponseHeaders(res) {
+    return res[FAST_HEADERS];
+}
+/** HTTP statuses that MUST NOT carry a body (1xx, 204, 304). */
+function hasBody(status) {
+    return status !== 204 && status !== 304 && !(status >= 100 && status < 200);
+}
+const JSON_HEADERS = { 'content-type': 'application/json' };
+function jsonFast(body, status) {
+    const text = hasBody(status) ? JSON.stringify(body) : undefined;
+    const res = new Response(text ?? null, {
+        status,
+        ...(text === undefined ? {} : { headers: JSON_HEADERS }),
+    });
+    if (text !== undefined) {
+        const duck = res;
+        duck[FAST_TEXT] = text;
+        duck[FAST_HEADERS] = JSON_HEADERS;
+    }
+    return res;
+}
+function check(section, schema, value) {
+    if (!Value.Check(schema, value))
+        throw validationError(section, schema, value);
+}
+/**
+ * URL search params are always strings; declared boolean/number query fields
+ * are coerced before validation so contracts can speak real types.
+ * Unrecognized values are left as-is and fail validation with a clear error.
+ */
+function coerceQuery(schema, raw) {
+    const props = schema.properties;
+    if (!props)
+        return raw;
+    const out = {};
+    for (const [key, value] of Object.entries(raw)) {
+        const types = props[key]?.type;
+        const list = Array.isArray(types) ? types : types ? [types] : [];
+        if (typeof value === 'string' && list.includes('boolean')) {
+            out[key] = value === 'true' ? true : value === 'false' ? false : value;
+        }
+        else if (typeof value === 'string' && (list.includes('number') || list.includes('integer'))) {
+            const n = Number(value);
+            out[key] = Number.isNaN(n) ? value : n;
+        }
+        else {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+/** Unwrap a Response produced through the middleware path into a RawReply. */
+function toRawReply(res) {
+    const fast = fastResponseText(res);
+    if (fast === undefined)
+        return { status: res.status, response: res };
+    // The FAST_HEADERS snapshot predates any header mutations middleware made
+    // after construction (CORS vary/ACAO, rate-limit footers...), so read the
+    // live Headers here. Only apps with middleware pay this iteration; the
+    // middleware-free hot path never enters this function.
+    const headers = {};
+    res.headers.forEach((value, key) => {
+        headers[key] = value;
+    });
+    return { status: res.status, text: fast, headers };
+}
+/**
+ * Adapters may attach a signal factory instead of a real signal so Ctx can
+ * stay lazy; real Request objects carry a plain signal.
+ */
+export function signalSource(req) {
+    const duck = req;
+    return duck.__tzin_signal_factory ?? req.signal;
+}
+/**
+ * Runtime-agnostic app: pure (req) => res over Web Standards.
+ * Testable without a server (app.fetch), adaptable to Node/Bun/Deno/Workers.
+ */
+function pathnameOf(url) {
+    const path = url.slice(url.indexOf('/', url.indexOf('//') + 2));
+    const end = path.search(/[?#]/);
+    return end === -1 ? path : path.slice(0, end);
+}
+export function createApp(routes, options = {}) {
+    const matchRoute = createMatcher(routes.map((r) => ({ method: r.contract.method, path: r.contract.path, route: r })));
+    /** Shared validation + handler invocation. Single source for both exits. */
+    async function runRoute(hit, req, ctx) {
+        const c = hit.route.contract;
+        const input = { ctx };
+        // Params are always injected (handler types derive them from the path
+        // string); validation applies only when a params schema is declared.
+        if ('params' in hit && hit.params !== undefined) {
+            input.params = hit.params;
+            if (c.params)
+                check('path params', c.params, hit.params);
+        }
+        if ('query' in c && c.query) {
+            const qs = req.url.includes('?') ? req.url.slice(req.url.indexOf('?')) : '';
+            const rawQuery = Object.fromEntries(new URLSearchParams(qs));
+            const query = coerceQuery(c.query, rawQuery);
+            check('query', c.query, query);
+            input.query = query;
+        }
+        if ('headers' in c && c.headers) {
+            const raw = {};
+            req.headers.forEach((v, k) => {
+                raw[k] = v;
+            });
+            check('headers', c.headers, raw);
+            input.headers = raw;
+        }
+        if ('cookies' in c && c.cookies) {
+            const rawCookies = {};
+            for (const part of (req.headers.get('cookie') ?? '').split(';')) {
+                const i = part.indexOf('=');
+                if (i > 0)
+                    rawCookies[part.slice(0, i).trim()] = decodeURIComponent(part.slice(i + 1).trim());
+            }
+            check('cookies', c.cookies, rawCookies);
+            input.cookies = rawCookies;
+        }
+        if ('body' in c && c.body) {
+            let json;
+            try {
+                json = await req.json();
+            }
+            catch {
+                throw new HttpError(400, 'Malformed JSON body');
+            }
+            check('body', c.body, json);
+            input.body = json;
+        }
+        const result = await hit.route.handler(input);
+        if (isRawResult(result))
+            return { kind: 'raw', response: result.__tzin_raw };
+        return { kind: 'json', status: result.status, body: result.body };
+    }
+    /**
+     * Route lookup memoized by "METHOD pathname". Real traffic repeats URLs
+     * constantly (keep-alive clients, polls), so the trie walk + path split +
+     * param decode collapse to a Map hit. Bounded: cleared when it exceeds
+     * ROUTE_CACHE_MAX so abusive unique-URL traffic can't grow it unbounded.
+     */
+    const routeCache = new Map();
+    function cachedMatch(method, pathname) {
+        const key = `${method} ${pathname}`;
+        let hit = routeCache.get(key);
+        if (hit === undefined) {
+            hit = matchRoute(method, pathname);
+            if (routeCache.size >= 10_000)
+                routeCache.clear();
+            routeCache.set(key, hit);
+        }
+        return hit;
+    }
+    async function dispatch(req, ctx) {
+        const pathname = pathnameOf(req.url);
+        const hit = cachedMatch(req.method, pathname);
+        if (!hit)
+            throw new HttpError(404, 'Not Found');
+        if (!('route' in hit)) {
+            throw new HttpError(405, 'Method Not Allowed', undefined, { Allow: hit.allow.join(', ') });
+        }
+        const out = await runRoute(hit, req, ctx);
+        return out.kind === 'raw' ? out.response : jsonFast(out.body, out.status);
+    }
+    async function rawDispatch(req, ctx, pathname) {
+        const hit = cachedMatch(req.method, pathname);
+        if (!hit)
+            throw new HttpError(404, 'Not Found');
+        if (!('route' in hit)) {
+            throw new HttpError(405, 'Method Not Allowed', undefined, { Allow: hit.allow.join(', ') });
+        }
+        const out = await runRoute(hit, req, ctx);
+        if (out.kind === 'raw')
+            return { status: out.response.status, response: out.response };
+        if (!hasBody(out.status))
+            return { status: out.status };
+        return { status: out.status, text: JSON.stringify(out.body), headers: JSON_HEADERS };
+    }
+    const middleware = options.middleware ?? [];
+    const handle = middleware.length
+        ? compose(middleware, dispatch)
+        : dispatch;
+    const seed = new Map(options.provides?.map((e) => [e.key, e.value]));
+    const hasSeed = seed.size > 0;
+    async function dispatchRaw(req) {
+        const pathname = pathnameOf(req.url);
+        try {
+            if (options.mcp && pathname === '/mcp') {
+                if (req.method !== 'POST') {
+                    throw new HttpError(405, 'MCP HTTP transport accepts POST only');
+                }
+                let msg;
+                try {
+                    msg = await req.json();
+                }
+                catch {
+                    return {
+                        status: 400,
+                        text: JSON.stringify({
+                            jsonrpc: '2.0',
+                            id: null,
+                            error: { code: -32700, message: 'Parse error' },
+                        }),
+                        headers: JSON_HEADERS,
+                    };
+                }
+                const reply = await handleMcpMessage(app, msg);
+                if (!reply)
+                    return { status: 202 };
+                return { status: 200, text: JSON.stringify(reply), headers: JSON_HEADERS };
+            }
+            if (options.llms && pathname === '/llms.txt') {
+                return {
+                    status: 200,
+                    text: renderLlmsTxt(routes, options.meta),
+                    headers: { 'content-type': 'text/plain; charset=utf-8' },
+                };
+            }
+            if (options.llms && pathname === '/llms-full.txt') {
+                return {
+                    status: 200,
+                    text: renderLlmsFullTxt(routes, options.meta),
+                    headers: { 'content-type': 'text/plain; charset=utf-8' },
+                };
+            }
+            if (options.openapi && pathname === '/openapi.json') {
+                return {
+                    status: 200,
+                    text: JSON.stringify(generateOpenApi(routes, {
+                        title: options.meta?.title ?? 'API',
+                        version: options.meta?.version ?? '0.0.0',
+                    })),
+                    headers: JSON_HEADERS,
+                };
+            }
+            const ctx = new Ctx(signalSource(req), hasSeed ? seed : undefined);
+            if (middleware.length)
+                return toRawReply(await handle(req, ctx));
+            return await rawDispatch(req, ctx, pathname);
+        }
+        catch (err) {
+            if (err instanceof HttpError) {
+                return {
+                    status: err.status,
+                    text: JSON.stringify({ error: err.message, details: err.details }),
+                    headers: err.headers ? { ...JSON_HEADERS, ...err.headers } : JSON_HEADERS,
+                };
+            }
+            console.error(err);
+            return { status: 500, text: JSON.stringify({ error: 'Internal Server Error' }), headers: JSON_HEADERS };
+        }
+    }
+    async function fetch(req) {
+        const r = await dispatchRaw(req);
+        if (r.response)
+            return r.response;
+        const res = new Response(r.text ?? null, { status: r.status, headers: r.headers });
+        if (r.text !== undefined) {
+            const duck = res;
+            duck[FAST_TEXT] = r.text;
+            duck[FAST_HEADERS] = r.headers;
+        }
+        return res;
+    }
+    const app = { routes, fetch, dispatchRaw };
+    return app;
+}

package/dist/sse.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Server-Sent Events helper. Returns a raw Response streaming
+ * `text/event-stream`; closes when the producer finishes or the
+ * client disconnects (request abort signal).
+ */
+import { type RawResult } from './contract.js';
+export interface SseSender {
+    event(name: string, data: unknown): void;
+    comment(text: string): void;
+}
+export declare function sse(produce: (send: SseSender) => Promise<void>, signal?: AbortSignal): RawResult;

package/dist/sse.js

@@ -0,0 +1,48 @@
+/**
+ * Server-Sent Events helper. Returns a raw Response streaming
+ * `text/event-stream`; closes when the producer finishes or the
+ * client disconnects (request abort signal).
+ */
+import { raw } from './contract.js';
+export function sse(produce, signal) {
+    const encoder = new TextEncoder();
+    const stream = new ReadableStream({
+        start(controller) {
+            let closed = false;
+            const write = (chunk) => {
+                if (!closed)
+                    controller.enqueue(encoder.encode(chunk));
+            };
+            const send = {
+                event: (name, data) => write(`event: ${name}\ndata: ${JSON.stringify(data)}\n\n`),
+                comment: (text) => write(`: ${text}\n\n`),
+            };
+            const close = () => {
+                if (closed)
+                    return;
+                closed = true;
+                try {
+                    controller.close();
+                }
+                catch { }
+            };
+            if (signal) {
+                if (signal.aborted) {
+                    close();
+                    return;
+                }
+                signal.addEventListener('abort', close, { once: true });
+            }
+            produce(send)
+                .catch(() => { })
+                .finally(close);
+        },
+    });
+    return raw(new Response(stream, {
+        headers: {
+            'content-type': 'text/event-stream',
+            'cache-control': 'no-cache',
+            connection: 'keep-alive',
+        },
+    }));
+}

package/dist/workers.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Cloudflare Workers adapters.
+ *
+ * - `toWorker(app)`: plain HTTP passthrough. WebSockets work per-connection,
+ *   but workerd ties each socket to its request's I/O context, so one
+ *   connection CANNOT broadcast into another (sends from foreign contexts
+ *   are silently dropped).
+ * - `toDurableWorker(factory)`: the fix — the whole app (one Hub, Presence,
+ *   SSE + WS + POST) lives inside a single Durable Object, so every
+ *   connection shares one context exactly like Node/Bun. Requires declaring
+ *   the DO in your wrangler config:
+ *
+ *     "durable_objects": {
+ *       "bindings": [{ "name": "TZIN_APP", "class_name": "TzinChannels" }]
+ *     },
+ *     "migrations": [{ "tag": "v1", "new_sqlite_classes": ["TzinChannels"] }]
+ */
+import type { App } from './server.js';
+import type { WsRoute } from './ws.js';
+interface DoNamespace {
+    idFromName(name: string): unknown;
+    get(id: unknown): {
+        fetch(req: Request): Promise<Response> | Response;
+    };
+}
+type Fetcher = {
+    fetch(req: Request): Promise<Response> | Response;
+};
+export interface WorkerOptions {
+    /** Native WebSocket endpoints served via WebSocketPair upgrades. */
+    wsRoutes?: WsRoute[];
+}
+export declare function toWorker(app: App, options?: WorkerOptions): {
+    fetch: (req: Request) => Promise<Response> | Response;
+};
+/** Default names; override via toDurableWorker options. */
+export declare const DEFAULT_DO_BINDING = "TZIN_APP";
+export declare const DEFAULT_DO_CLASS = "TzinChannels";
+/**
+ * The whole app runs here — a single I/O context shared by every WebSocket,
+ * SSE stream and HTTP request, so cross-connection broadcast just works.
+ */
+export declare class TzinChannels {
+    fetch(req: Request): Promise<Response>;
+}
+export interface DurableWorkerOptions extends WorkerOptions {
+    /** DO class name exported by this script (default "TzinChannels"). */
+    className?: string;
+    /** Env binding name declared in wrangler config (default "TZIN_APP"). */
+    binding?: string;
+}
+export declare function toDurableWorker(factory: () => Fetcher, options?: DurableWorkerOptions): {
+    fetch: (req: Request, env?: Record<string, DoNamespace>) => Promise<Response> | Response;
+};
+export {};

package/dist/workers.js

@@ -0,0 +1,130 @@
+import { createMatcher } from './router.js';
+/* ------------------------------------------------------------------ */
+/* Direct mode                                                         */
+/* ------------------------------------------------------------------ */
+export function toWorker(app, options = {}) {
+    const matcher = bindMatcher(options.wsRoutes);
+    return {
+        fetch: (req) => {
+            if (isUpgrade(req)) {
+                if (!matcher)
+                    return new Response('No WebSocket routes configured', { status: 404 });
+                return upgrade(req, matcher);
+            }
+            return app.fetch(req);
+        },
+    };
+}
+/* ------------------------------------------------------------------ */
+/* Durable Object mode: one context for every connection               */
+/* ------------------------------------------------------------------ */
+/** Default names; override via toDurableWorker options. */
+export const DEFAULT_DO_BINDING = 'TZIN_APP';
+export const DEFAULT_DO_CLASS = 'TzinChannels';
+/** Factories registered by toDurableWorker(), consumed by the DO class. */
+const factories = new Map();
+const apps = new Map();
+function appFor(className) {
+    let app = apps.get(className);
+    if (!app) {
+        const f = factories.get(className);
+        if (!f)
+            throw new Error(`No app factory registered for DO class "${className}"`);
+        app = f();
+        apps.set(className, app);
+    }
+    return app;
+}
+/**
+ * The whole app runs here — a single I/O context shared by every WebSocket,
+ * SSE stream and HTTP request, so cross-connection broadcast just works.
+ */
+export class TzinChannels {
+    async fetch(req) {
+        return appFor(DEFAULT_DO_CLASS).fetch(req);
+    }
+}
+export function toDurableWorker(factory, options = {}) {
+    const className = options.className ?? DEFAULT_DO_CLASS;
+    const binding = options.binding ?? DEFAULT_DO_BINDING;
+    factories.set(className, factory);
+    return {
+        fetch: (req, env) => {
+            const ns = env?.[binding];
+            if (!ns) {
+                return new Response(`Missing Durable Object binding "${binding}"`, { status: 500 });
+            }
+            // Singleton: every connection lands in the same DO instance/context.
+            return ns.get(ns.idFromName('tzin-app')).fetch(req);
+        },
+    };
+}
+/* ------------------------------------------------------------------ */
+/* Shared internals                                                    */
+/* ------------------------------------------------------------------ */
+function isUpgrade(req) {
+    return req.headers.get('upgrade')?.toLowerCase() === 'websocket';
+}
+function bindMatcher(wsRoutes) {
+    const routes = wsRoutes ?? [];
+    return routes.length
+        ? createMatcher(routes.map((r) => ({ method: 'GET', path: r.path, route: r })))
+        : undefined;
+}
+function pairCtor() {
+    return globalThis.WebSocketPair;
+}
+function upgrade(req, matcher) {
+    const Pair = pairCtor();
+    if (!Pair)
+        return new Response('WebSockets require a Workers-compatible runtime', { status: 500 });
+    let url;
+    try {
+        url = new URL(req.url);
+    }
+    catch {
+        return new Response('Bad request', { status: 400 });
+    }
+    const hit = matcher('GET', url.pathname);
+    if (!hit || !('route' in hit)) {
+        return new Response('WebSocket upgrade failed', { status: 400 });
+    }
+    const route = hit.route;
+    const pair = new Pair();
+    const client = pair[0];
+    const server = pair[1];
+    // accept() must precede any send(); early sends are buffered until the
+    // 101 response reaches the runtime.
+    server.accept();
+    const send = (frame) => {
+        try {
+            server.send(JSON.stringify(frame));
+        }
+        catch { }
+    };
+    let state;
+    try {
+        state = route.open(send, url);
+    }
+    catch {
+        server.close(1011, 'handler error');
+        return new Response('WebSocket handler failed', { status: 500 });
+    }
+    server.addEventListener('message', (ev) => {
+        const text = typeof ev.data === 'string' ? ev.data : String(ev.data);
+        try {
+            route.message(state, text);
+        }
+        catch { }
+    });
+    const closeAll = () => {
+        try {
+            route.close(state);
+        }
+        catch { }
+    };
+    server.addEventListener('close', closeAll);
+    server.addEventListener('error', closeAll);
+    // The response carries the CLIENT side back to the runtime (101 required).
+    return new Response(null, { status: 101, webSocket: client });
+}

package/dist/ws-node.d.ts

@@ -0,0 +1,3 @@
+import type { Server } from 'node:http';
+import type { WsRoute } from './ws.js';
+export declare function attachChannels(httpServer: Server, routes: WsRoute[]): void;

package/dist/ws-node.js

@@ -0,0 +1,36 @@
+/**
+ * Node WebSocket adapter: attaches WsRoutes to an http.Server via the `ws`
+ * package. Route matching reuses the same radix trie as HTTP dispatch.
+ */
+import { WebSocketServer } from 'ws';
+import { createMatcher } from './router.js';
+export function attachChannels(httpServer, routes) {
+    const wss = new WebSocketServer({ noServer: true });
+    const matcher = createMatcher(routes.map((r) => ({ method: 'GET', path: r.path, route: r })));
+    httpServer.on('upgrade', (req, socket, head) => {
+        let url;
+        try {
+            url = new URL(req.url ?? '/', 'http://local');
+        }
+        catch {
+            socket.destroy();
+            return;
+        }
+        const hit = matcher('GET', url.pathname);
+        if (!hit || !('route' in hit)) {
+            socket.destroy();
+            return;
+        }
+        const route = hit.route;
+        wss.handleUpgrade(req, socket, head, (ws) => {
+            const send = (frame) => {
+                if (ws.readyState === ws.OPEN)
+                    ws.send(JSON.stringify(frame));
+            };
+            const state = route.open(send, url);
+            ws.on('message', (data) => route.message(state, data.toString()));
+            ws.on('close', () => route.close(state));
+            ws.on('error', () => ws.close());
+        });
+    });
+}

package/dist/ws.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Runtime-neutral WebSocket routing: one protocol implementation, thin
+ * adapters per platform (src/ws-node.ts with the `ws` package, src/bun.ts
+ * with Bun's native websockets).
+ *
+ * Channel protocol over WS (mirrors channelRoutes' SSE+POST semantics):
+ *   server -> client: { event, data }            broadcasts + presence_state/presence_diff
+ *   client -> server: { type: 'push', event, data?, id? }
+ *                     { type: 'heartbeat', meta? }
+ */
+import type { Hub } from './hub.js';
+import type { Presence } from './presence.js';
+export type WsSend = (frame: unknown) => void;
+export interface WsRoute {
+    /** Path pattern with :params, same syntax as HTTP contracts. */
+    readonly path: string;
+    /** Connection established; return per-connection state. */
+    open(send: WsSend, url: URL): unknown;
+    /** A text frame arrived. */
+    message(state: unknown, text: string): void;
+    /** Connection closed (client disconnect or server shutdown). */
+    close(state: unknown): void;
+}
+export interface WsChannelOptions {
+    presence?: Presence;
+}
+export declare function wsChannels(hub: Hub, options?: WsChannelOptions): WsRoute;

package/dist/ws.js

@@ -0,0 +1,49 @@
+export function wsChannels(hub, options = {}) {
+    const presence = options.presence;
+    return {
+        path: '/channels/:topic',
+        open(send, url) {
+            const topic = decodeURIComponent(url.pathname.split('/')[2] ?? '');
+            const member = url.searchParams.get('member') ?? undefined;
+            const unsub = hub.subscribe(topic, (e) => send({ event: e.event, data: e.data }));
+            if (member && presence)
+                presence.join(topic, member);
+            // Initial full view on connect (parity with the SSE channel routes).
+            if (presence)
+                send({ event: 'presence_state', data: { members: presence.snapshot(topic) } });
+            return { topic, member, unsub, __send: send };
+        },
+        message(state, text) {
+            const s = state;
+            let frame;
+            try {
+                frame = JSON.parse(text);
+            }
+            catch {
+                s.__send({ error: 'invalid JSON frame' });
+                return;
+            }
+            switch (frame.type) {
+                case 'push':
+                    if (!frame.event) {
+                        s.__send({ error: 'push requires event' });
+                        return;
+                    }
+                    hub.publish(s.topic, frame.event, frame.data ?? null);
+                    break;
+                case 'heartbeat':
+                    if (s.member && presence)
+                        presence.heartbeat(s.topic, s.member, frame.meta);
+                    break;
+                default:
+                    s.__send({ error: `unknown frame type: ${String(frame.type)}` });
+            }
+        },
+        close(state) {
+            const s = state;
+            s.unsub();
+            if (s.member && presence)
+                presence.leave(s.topic, s.member);
+        },
+    };
+}