@abloatai/ablo 0.35.0 → 0.37.0

package/dist/source/connector.js

@@ -1,266 +0,0 @@
-/**
- * Opens the connector's side of the Data Source reverse channel. You run this
- * process next to your database; it dials an outbound WebSocket to Ablo and serves
- * the load, list, and commit requests over that socket, so a handler with no
- * public URL never needs to receive inbound webhooks. It is the counterpart to
- * `createPushQueue`, which gives the outbound events feed the same treatment, and
- * it speaks the frames defined in `connectorProtocol.ts`.
- *
- * The connector reimplements none of the handler logic. It wraps the same
- * `(request: Request) => Promise<Response>` your deployed route already uses:
- *
- *   import { dataSource, createSourceConnector } from '@abloatai/ablo';
- *   import { sourceOptions } from './ablo.source'; // shared with route.ts
- *
- *   const connector = createSourceConnector({
- *     apiKey: process.env.ABLO_API_KEY!,
- *     handler: dataSource(sourceOptions),
- *   });
- *   await connector.run(controller.signal);
- *
- * Each incoming `request` frame is replayed into a `Request` that carries the
- * original signature headers, so the handler verifies it through the same
- * `verifyAbloSourceRequest` it uses on the webhook path. The transport changes;
- * the trust model does not.
- */
-import { SOURCE_CONNECTOR_PROTOCOL_VERSION, SOURCE_CONNECTOR_WS_PATH, sourceConnectorSubprotocols, encodeFrame, decodeFrame, ConnectorProtocolError, } from './connectorProtocol.js';
-import { ABLO_HOSTED_HTTP_BASE_URL } from '../transaction/auth/hostedEndpoints.js';
-/**
- * The default Ablo base URL the connector dials, to which it appends
- * `SOURCE_CONNECTOR_WS_PATH`.
- */
-const DEFAULT_BASE_URL = ABLO_HOSTED_HTTP_BASE_URL;
-/**
- * The reconnect backoff, in milliseconds, indexed by the number of consecutive
- * failed connect attempts. A long-lived control socket should recover quickly and
- * then settle at a steady interval, so this is a short curve that caps rather than
- * growing without bound. The final entry repeats for any further attempts, and a
- * connection that reaches `ready` resets the count to zero.
- */
-export const DEFAULT_RECONNECT_SCHEDULE = [
-    0, // immediate first reconnect
-    1_000, // 1s
-    2_000, // 2s
-    5_000, // 5s
-    10_000, // 10s
-    30_000, // 30s (steady state)
-];
-export function createSourceConnector(options) {
-    const baseURL = (options.baseURL ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
-    const url = toWebSocketUrl(baseURL) + SOURCE_CONNECTOR_WS_PATH;
-    const schedule = options.reconnectSchedule ?? DEFAULT_RECONNECT_SCHEDULE;
-    const jitter = options.jitter ?? 0.1;
-    const factory = options.webSocket ?? defaultWebSocketFactory;
-    return {
-        async run(signal) {
-            let attempt = 0;
-            while (!signal.aborted) {
-                const delay = backoffFor(schedule, attempt, jitter);
-                if (delay > 0)
-                    await sleep(delay, signal);
-                if (signal.aborted)
-                    return;
-                options.onStatus?.('connecting');
-                const becameReady = await connectOnce({
-                    url,
-                    apiKey: options.apiKey,
-                    handler: options.handler,
-                    factory,
-                    client: options.client,
-                    onStatus: options.onStatus,
-                    onError: options.onError,
-                    signal,
-                });
-                // A connection that reached `ready` resets the backoff so the next
-                // drop reconnects immediately; one that never readied keeps escalating.
-                attempt = becameReady ? 0 : attempt + 1;
-            }
-        },
-    };
-}
-/**
- * Runs one connection: open the socket, register, then serve requests until the
- * socket closes or `signal` aborts. Resolves to whether the connection reached the
- * `ready` state, which the caller uses to reset the reconnect backoff. It never
- * rejects, because a dropped transport is expected and simply drives a reconnect.
- */
-function connectOnce(params) {
-    return new Promise((resolve) => {
-        let ws;
-        try {
-            ws = params.factory(params.url, sourceConnectorSubprotocols(params.apiKey));
-        }
-        catch (err) {
-            params.onError?.(err);
-            resolve(false);
-            return;
-        }
-        let ready = false;
-        let settled = false;
-        const finish = () => {
-            if (settled)
-                return;
-            settled = true;
-            params.signal.removeEventListener('abort', onAbort);
-            params.onStatus?.('disconnected');
-            resolve(ready);
-        };
-        const onAbort = () => {
-            try {
-                ws.close(1000, 'connector_aborted');
-            }
-            catch {
-                // Already closing/closed.
-            }
-            finish();
-        };
-        params.signal.addEventListener('abort', onAbort, { once: true });
-        ws.addEventListener('open', () => {
-            send(ws, {
-                type: 'register',
-                protocolVersion: SOURCE_CONNECTOR_PROTOCOL_VERSION,
-                ...(params.client ? { client: params.client } : {}),
-            });
-        });
-        ws.addEventListener('message', (event) => {
-            let frame;
-            try {
-                frame = decodeFrame(event.data);
-            }
-            catch (err) {
-                params.onError?.(err instanceof ConnectorProtocolError
-                    ? err
-                    : new ConnectorProtocolError(String(err)));
-                return;
-            }
-            handleFrame(frame);
-        });
-        ws.addEventListener('error', (event) => {
-            params.onError?.(event);
-            // `close` always follows `error`; finish() runs there.
-        });
-        ws.addEventListener('close', () => {
-            finish();
-        });
-        function handleFrame(frame) {
-            switch (frame.type) {
-                case 'ready':
-                    handleReady(frame);
-                    return;
-                case 'request':
-                    // Do not await — serve each request concurrently so a slow handler
-                    // never blocks draining the next frame off the socket.
-                    void serveRequest(frame);
-                    return;
-                case 'error':
-                    params.onError?.(new ConnectorProtocolError(`${frame.code}: ${frame.message}`));
-                    return;
-                // `register`/`response` are connector→server only; ignore if echoed.
-                case 'register':
-                case 'response':
-                    return;
-            }
-        }
-        function handleReady(frame) {
-            if (frame.protocolVersion !== SOURCE_CONNECTOR_PROTOCOL_VERSION) {
-                params.onError?.(new ConnectorProtocolError(`Server protocol version ${frame.protocolVersion} != ${SOURCE_CONNECTOR_PROTOCOL_VERSION}`));
-                try {
-                    ws.close(1002, 'protocol_version_mismatch');
-                }
-                catch {
-                    // closing
-                }
-                return;
-            }
-            ready = true;
-            params.onStatus?.('ready');
-        }
-        async function serveRequest(frame) {
-            const response = await runHandler(frame);
-            // Best-effort: if the socket dropped while the handler ran, the server
-            // times the request out and the SDK retries — same as a webhook timeout.
-            send(ws, response);
-        }
-        async function runHandler(frame) {
-            try {
-                const request = new Request(frame.url, {
-                    method: frame.method,
-                    headers: frame.headers,
-                    body: frame.body,
-                });
-                const result = await params.handler(request);
-                const body = await result.text();
-                return {
-                    type: 'response',
-                    id: frame.id,
-                    status: result.status,
-                    body,
-                };
-            }
-            catch (err) {
-                params.onError?.(err);
-                // Surface this as a 500 so Ablo treats it as a retryable failure, exactly
-                // as it would a webhook endpoint that threw.
-                return {
-                    type: 'response',
-                    id: frame.id,
-                    status: 500,
-                    body: JSON.stringify({
-                        error: 'source_connector_handler_error',
-                        message: err instanceof Error ? err.message : String(err),
-                    }),
-                };
-            }
-        }
-        function send(socket, frame) {
-            try {
-                socket.send(encodeFrame(frame));
-            }
-            catch (err) {
-                params.onError?.(err);
-            }
-        }
-    });
-}
-function defaultWebSocketFactory(url, protocols) {
-    const Ctor = globalThis.WebSocket;
-    if (!Ctor) {
-        throw new Error('No global WebSocket available. Pass `webSocket` (e.g. the `ws` package) to createSourceConnector.');
-    }
-    return new Ctor(url, protocols);
-}
-/** `http(s)://` → `ws(s)://`. Leaves an explicit `ws(s)` scheme untouched. */
-function toWebSocketUrl(baseURL) {
-    if (baseURL.startsWith('https://'))
-        return `wss://${baseURL.slice('https://'.length)}`;
-    if (baseURL.startsWith('http://'))
-        return `ws://${baseURL.slice('http://'.length)}`;
-    return baseURL;
-}
-function backoffFor(schedule, attempt, jitter) {
-    if (attempt <= 0)
-        return 0;
-    const base = schedule[Math.min(attempt, schedule.length - 1)] ?? 0;
-    if (jitter <= 0 || base === 0)
-        return base;
-    const swing = base * jitter;
-    return Math.max(0, base + (Math.random() * 2 - 1) * swing);
-}
-function sleep(ms, signal) {
-    return new Promise((resolve) => {
-        if (signal.aborted) {
-            resolve();
-            return;
-        }
-        const timer = setTimeout(() => {
-            signal.removeEventListener('abort', onAbort);
-            resolve();
-        }, ms);
-        const onAbort = () => {
-            clearTimeout(timer);
-            signal.removeEventListener('abort', onAbort);
-            resolve();
-        };
-        signal.addEventListener('abort', onAbort, { once: true });
-    });
-}

package/dist/source/connectorProtocol.d.ts

@@ -1,154 +0,0 @@
-/**
- * The wire protocol for the Data Source reverse channel — the frames that travel
- * over the WebSocket a connector opens to Ablo.
- *
- * The load, list, and commit leg of a Data Source normally arrives as an inbound
- * webhook that Ablo posts to your HTTPS endpoint. That needs a public URL, so it
- * cannot reach a handler running on localhost or inside a private network with no
- * inbound path. The reverse channel flips the direction: the connector dials out
- * to Ablo over a WebSocket and serves those same requests back over the open
- * socket. This module defines the frames exchanged on that socket.
- *
- * The trust model does not change. A `request` frame carries the same signature
- * headers (`webhook-id`, `webhook-timestamp`, `webhook-signature`) and the same
- * raw body Ablo would have posted, so the connector verifies it through
- * `verifyAbloSourceRequest` exactly as it would a webhook. Only the transport
- * differs.
- *
- * Frames are validated with Zod as they arrive, the same discipline `contract.ts`
- * applies to change sets: a malformed frame is rejected at the boundary, and both
- * sides infer every wire type from one schema so they cannot silently drift.
- */
-import { z } from 'zod';
-/**
- * The wire-protocol version. It increases on any breaking change to a frame's
- * shape, so a connector and server on mismatched versions fail fast during
- * `register` rather than misparsing a frame later in the stream.
- */
-export declare const SOURCE_CONNECTOR_PROTOCOL_VERSION = 1;
-/** The WebSocket path the connector dials, appended to its configured base URL. */
-export declare const SOURCE_CONNECTOR_WS_PATH = "/v1/source/listen";
-/**
- * The WebSocket subprotocol that identifies a reverse-channel source connector,
- * as opposed to the SDK's sync client, which uses `ablo.sync.v1`. During the
- * handshake the server echoes back only this value and never the subprotocol that
- * carries the credential, keeping the API key out of proxy and load-balancer logs.
- */
-export declare const WS_SOURCE_SUBPROTOCOL = "ablo.source.v1";
-/**
- * Builds the `Sec-WebSocket-Protocol` list a connector offers during the
- * handshake: the source subprotocol followed by the bearer credential, encoded as
- * `ablo.bearer.<apiKey>`. A WebSocket handshake cannot carry an `Authorization`
- * header, so the API key rides as a subprotocol instead — the same mechanism the
- * SDK's sync client uses, which the server reads back with `extractBearer`.
- */
-export declare function sourceConnectorSubprotocols(apiKey: string): string[];
-/**
- * The first frame the connector sends, right after the socket opens. The server
- * has already authenticated the connection and resolved which source it serves
- * from the API key in the handshake, so this frame only negotiates the protocol
- * version and carries advisory metadata.
- */
-export declare const registerFrameSchema: z.ZodObject<{
-    type: z.ZodLiteral<"register">;
-    protocolVersion: z.ZodNumber;
-    client: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-export type RegisterFrame = z.infer<typeof registerFrameSchema>;
-/**
- * The server's acknowledgement of a successful `register`. It echoes the resolved
- * source identity so the connector can confirm and log which source it is serving.
- */
-export declare const readyFrameSchema: z.ZodObject<{
-    type: z.ZodLiteral<"ready">;
-    protocolVersion: z.ZodNumber;
-    sourceId: z.ZodOptional<z.ZodString>;
-    organizationId: z.ZodOptional<z.ZodString>;
-    environment: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-export type ReadyFrame = z.infer<typeof readyFrameSchema>;
-/**
- * A single load, list, or commit request the server forwards to the connector.
- * Its `headers` and `body` are byte-for-byte what the inbound webhook path would
- * have sent, so the connector can replay them into a `Request` and let the same
- * handler verify the signature exactly as it would for a webhook.
- */
-export declare const requestFrameSchema: z.ZodObject<{
-    type: z.ZodLiteral<"request">;
-    id: z.ZodString;
-    method: z.ZodLiteral<"POST">;
-    url: z.ZodString;
-    headers: z.ZodRecord<z.ZodString, z.ZodString>;
-    body: z.ZodString;
-}, z.core.$strip>;
-export type RequestFrame = z.infer<typeof requestFrameSchema>;
-/**
- * The handler's response to one `request` frame, sent back by the connector. The
- * server matches it to the pending request by `id` and treats its `status` and
- * `body` as though an HTTP response had returned.
- */
-export declare const responseFrameSchema: z.ZodObject<{
-    type: z.ZodLiteral<"response">;
-    id: z.ZodString;
-    status: z.ZodNumber;
-    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-    body: z.ZodString;
-}, z.core.$strip>;
-export type ResponseFrame = z.infer<typeof responseFrameSchema>;
-/**
- * An error either side can send for a failure that is not a normal request
- * result, such as a rejected credential, an unsupported protocol version, or a
- * malformed frame. When `id` is set the error belongs to that pending request and
- * fails it; without an `id` it is a connection-level error.
- */
-export declare const errorFrameSchema: z.ZodObject<{
-    type: z.ZodLiteral<"error">;
-    id: z.ZodOptional<z.ZodString>;
-    code: z.ZodString;
-    message: z.ZodString;
-}, z.core.$strip>;
-export type ErrorFrame = z.infer<typeof errorFrameSchema>;
-export declare const connectorFrameSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    type: z.ZodLiteral<"register">;
-    protocolVersion: z.ZodNumber;
-    client: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>, z.ZodObject<{
-    type: z.ZodLiteral<"ready">;
-    protocolVersion: z.ZodNumber;
-    sourceId: z.ZodOptional<z.ZodString>;
-    organizationId: z.ZodOptional<z.ZodString>;
-    environment: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>, z.ZodObject<{
-    type: z.ZodLiteral<"request">;
-    id: z.ZodString;
-    method: z.ZodLiteral<"POST">;
-    url: z.ZodString;
-    headers: z.ZodRecord<z.ZodString, z.ZodString>;
-    body: z.ZodString;
-}, z.core.$strip>, z.ZodObject<{
-    type: z.ZodLiteral<"response">;
-    id: z.ZodString;
-    status: z.ZodNumber;
-    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-    body: z.ZodString;
-}, z.core.$strip>, z.ZodObject<{
-    type: z.ZodLiteral<"error">;
-    id: z.ZodOptional<z.ZodString>;
-    code: z.ZodString;
-    message: z.ZodString;
-}, z.core.$strip>], "type">;
-export type ConnectorFrame = z.infer<typeof connectorFrameSchema>;
-/** Thrown when an incoming frame fails to parse or validate. */
-export declare class ConnectorProtocolError extends Error {
-    readonly code = "source_connector_protocol_error";
-    constructor(message: string);
-}
-/** Serialize a frame for transmission. */
-export declare function encodeFrame(frame: ConnectorFrame): string;
-/**
- * Parses and validates one incoming frame. It accepts either the string or the
- * binary payloads a WebSocket `message` event can deliver, and throws
- * {@link ConnectorProtocolError} on any malformed or unrecognized frame so the
- * caller can reject the connection instead of acting on bad data.
- */
-export declare function decodeFrame(raw: string | ArrayBuffer | Uint8Array): ConnectorFrame;

package/dist/source/connectorProtocol.js

@@ -1,163 +0,0 @@
-/**
- * The wire protocol for the Data Source reverse channel — the frames that travel
- * over the WebSocket a connector opens to Ablo.
- *
- * The load, list, and commit leg of a Data Source normally arrives as an inbound
- * webhook that Ablo posts to your HTTPS endpoint. That needs a public URL, so it
- * cannot reach a handler running on localhost or inside a private network with no
- * inbound path. The reverse channel flips the direction: the connector dials out
- * to Ablo over a WebSocket and serves those same requests back over the open
- * socket. This module defines the frames exchanged on that socket.
- *
- * The trust model does not change. A `request` frame carries the same signature
- * headers (`webhook-id`, `webhook-timestamp`, `webhook-signature`) and the same
- * raw body Ablo would have posted, so the connector verifies it through
- * `verifyAbloSourceRequest` exactly as it would a webhook. Only the transport
- * differs.
- *
- * Frames are validated with Zod as they arrive, the same discipline `contract.ts`
- * applies to change sets: a malformed frame is rejected at the boundary, and both
- * sides infer every wire type from one schema so they cannot silently drift.
- */
-import { z } from 'zod';
-import { environmentSchema } from '../transaction/environment.js';
-import { WS_BEARER_SUBPROTOCOL_PREFIX } from '../transaction/auth/credentialSource.js';
-/**
- * The wire-protocol version. It increases on any breaking change to a frame's
- * shape, so a connector and server on mismatched versions fail fast during
- * `register` rather than misparsing a frame later in the stream.
- */
-export const SOURCE_CONNECTOR_PROTOCOL_VERSION = 1;
-/** The WebSocket path the connector dials, appended to its configured base URL. */
-export const SOURCE_CONNECTOR_WS_PATH = '/v1/source/listen';
-/**
- * The WebSocket subprotocol that identifies a reverse-channel source connector,
- * as opposed to the SDK's sync client, which uses `ablo.sync.v1`. During the
- * handshake the server echoes back only this value and never the subprotocol that
- * carries the credential, keeping the API key out of proxy and load-balancer logs.
- */
-export const WS_SOURCE_SUBPROTOCOL = 'ablo.source.v1';
-/**
- * Builds the `Sec-WebSocket-Protocol` list a connector offers during the
- * handshake: the source subprotocol followed by the bearer credential, encoded as
- * `ablo.bearer.<apiKey>`. A WebSocket handshake cannot carry an `Authorization`
- * header, so the API key rides as a subprotocol instead — the same mechanism the
- * SDK's sync client uses, which the server reads back with `extractBearer`.
- */
-export function sourceConnectorSubprotocols(apiKey) {
-    return [WS_SOURCE_SUBPROTOCOL, `${WS_BEARER_SUBPROTOCOL_PREFIX}${apiKey}`];
-}
-const headerRecord = z.record(z.string(), z.string());
-/**
- * The first frame the connector sends, right after the socket opens. The server
- * has already authenticated the connection and resolved which source it serves
- * from the API key in the handshake, so this frame only negotiates the protocol
- * version and carries advisory metadata.
- */
-export const registerFrameSchema = z.object({
-    type: z.literal('register'),
-    protocolVersion: z.number().int(),
-    /**
-     * An optional client identifier, such as `@abloatai/ablo@0.12.0`, recorded in
-     * the server's logs. It is advisory only and never affects a decision.
-     */
-    client: z.string().optional(),
-});
-/**
- * The server's acknowledgement of a successful `register`. It echoes the resolved
- * source identity so the connector can confirm and log which source it is serving.
- */
-export const readyFrameSchema = z.object({
-    type: z.literal('ready'),
-    protocolVersion: z.number().int(),
-    sourceId: z.string().optional(),
-    organizationId: z.string().optional(),
-    environment: environmentSchema.optional(),
-});
-/**
- * A single load, list, or commit request the server forwards to the connector.
- * Its `headers` and `body` are byte-for-byte what the inbound webhook path would
- * have sent, so the connector can replay them into a `Request` and let the same
- * handler verify the signature exactly as it would for a webhook.
- */
-export const requestFrameSchema = z.object({
-    type: z.literal('request'),
-    /** Correlation id; the matching `response` frame carries the same value. */
-    id: z.string().min(1),
-    method: z.literal('POST'),
-    /** Synthetic absolute URL used only to construct the `Request` object. */
-    url: z.string().min(1),
-    /** The signed webhook signature headers, plus `Content-Type`. */
-    headers: headerRecord,
-    /** Raw JSON request body — exactly the bytes that were signed. */
-    body: z.string(),
-});
-/**
- * The handler's response to one `request` frame, sent back by the connector. The
- * server matches it to the pending request by `id` and treats its `status` and
- * `body` as though an HTTP response had returned.
- */
-export const responseFrameSchema = z.object({
-    type: z.literal('response'),
-    id: z.string().min(1),
-    status: z.number().int(),
-    headers: headerRecord.optional(),
-    /** Raw JSON response body. */
-    body: z.string(),
-});
-/**
- * An error either side can send for a failure that is not a normal request
- * result, such as a rejected credential, an unsupported protocol version, or a
- * malformed frame. When `id` is set the error belongs to that pending request and
- * fails it; without an `id` it is a connection-level error.
- */
-export const errorFrameSchema = z.object({
-    type: z.literal('error'),
-    id: z.string().min(1).optional(),
-    code: z.string().min(1),
-    message: z.string(),
-});
-export const connectorFrameSchema = z.discriminatedUnion('type', [
-    registerFrameSchema,
-    readyFrameSchema,
-    requestFrameSchema,
-    responseFrameSchema,
-    errorFrameSchema,
-]);
-/** Thrown when an incoming frame fails to parse or validate. */
-export class ConnectorProtocolError extends Error {
-    code = 'source_connector_protocol_error';
-    constructor(message) {
-        super(message);
-        this.name = 'ConnectorProtocolError';
-    }
-}
-/** Serialize a frame for transmission. */
-export function encodeFrame(frame) {
-    return JSON.stringify(frame);
-}
-/**
- * Parses and validates one incoming frame. It accepts either the string or the
- * binary payloads a WebSocket `message` event can deliver, and throws
- * {@link ConnectorProtocolError} on any malformed or unrecognized frame so the
- * caller can reject the connection instead of acting on bad data.
- */
-export function decodeFrame(raw) {
-    const text = typeof raw === 'string' ? raw : decodeBinary(raw);
-    let parsed;
-    try {
-        parsed = JSON.parse(text);
-    }
-    catch {
-        throw new ConnectorProtocolError('Frame is not valid JSON');
-    }
-    const result = connectorFrameSchema.safeParse(parsed);
-    if (!result.success) {
-        throw new ConnectorProtocolError(`Invalid connector frame: ${result.error.message}`);
-    }
-    return result.data;
-}
-function decodeBinary(raw) {
-    const bytes = raw instanceof Uint8Array ? raw : new Uint8Array(raw);
-    return new TextDecoder().decode(bytes);
-}