ocel 0.0.1-alpha.0 → 0.0.1

package/dist/kv/pattern.js

@@ -0,0 +1,73 @@
+const literalSegment = /^[A-Za-z0-9._-]+$/;
+const parameterSegment = /^:[A-Za-z_][A-Za-z0-9_]*$/;
+export function parsePattern(written) {
+    if (written === "") {
+        throw new Error("the pattern is empty: write one or more segments joined by /, each a literal or a :parameter");
+    }
+    if (/[{}]/.test(written)) {
+        throw new Error(`pattern "${written}" holds { or }, which a store reserves as the hash tag syntax`);
+    }
+    const segments = [];
+    const named = new Set();
+    for (const part of written.split("/")) {
+        if (part === "") {
+            throw new Error(`pattern "${written}" has an empty segment: it neither starts nor ends with /, and no two / are adjacent`);
+        }
+        if (part.startsWith(":")) {
+            if (!parameterSegment.test(part)) {
+                throw new Error(`pattern "${written}" has segment "${part}", which is no parameter: a parameter is : and a name of letters, digits and _ that starts with a letter or _`);
+            }
+            const name = part.slice(1);
+            if (named.has(name)) {
+                throw new Error(`pattern "${written}" names parameter "${name}" twice, so a key could not say which value is which`);
+            }
+            named.add(name);
+            segments.push({ parameter: name });
+            continue;
+        }
+        if (!literalSegment.test(part)) {
+            throw new Error(`pattern "${written}" has segment "${part}", which is no literal: a literal is letters, digits, ., _ and -`);
+        }
+        segments.push({ literal: part });
+    }
+    return { written, segments };
+}
+export function patternsOverlap(a, b) {
+    if (a.segments.length !== b.segments.length)
+        return false;
+    return a.segments.every((mine, i) => {
+        const theirs = b.segments[i];
+        return !("literal" in mine && "literal" in theirs) || mine.literal === theirs.literal;
+    });
+}
+export function hasParameters(pattern) {
+    return pattern.segments.some((segment) => "parameter" in segment);
+}
+const unreserved = /[A-Za-z0-9\-._~]/;
+export function encodeParameter(value) {
+    let encoded = "";
+    for (const byte of new TextEncoder().encode(value)) {
+        const char = String.fromCharCode(byte);
+        encoded +=
+            byte < 0x80 && unreserved.test(char)
+                ? char
+                : `%${byte.toString(16).toUpperCase().padStart(2, "0")}`;
+    }
+    return encoded;
+}
+export function buildKey(pattern, key) {
+    return pattern.segments
+        .map((segment) => {
+        if ("literal" in segment)
+            return segment.literal;
+        const value = key?.[segment.parameter];
+        if (typeof value === "number" && !Number.isSafeInteger(value)) {
+            throw new TypeError(`the key of pattern "${pattern.written}" gives :${segment.parameter} the number ${value}, which is no safe integer: give a string or an integer within ±(2^53 - 1)`);
+        }
+        if (typeof value !== "string" && typeof value !== "number") {
+            throw new TypeError(`the key of pattern "${pattern.written}" has no value for :${segment.parameter}: give a string or an integer`);
+        }
+        return encodeParameter(String(value));
+    })
+        .join("/");
+}

package/dist/kv/ttl.d.ts

@@ -0,0 +1,22 @@
+/** A length of time written with its unit, such as `"500ms"`, `"10s"`, `"5m"`, `"2h"` or `"30d"`. */
+export type KVDuration = `${number}ms` | `${number}s` | `${number}m` | `${number}h` | `${number}d`;
+/**
+ * How long a write leaves its key to live: a duration replaces the TTL, `"keep"` keeps the
+ * one the key has, and `null` clears it so the key lives until it is deleted or evicted.
+ */
+export type WriteTTL = KVDuration | "keep" | null;
+/** How one write treats its key's TTL. */
+export interface WriteOptions {
+    /** The TTL this write sets instead of the entry's own; without it, the entry's own. */
+    ttl?: WriteTTL;
+}
+export type TTL = {
+    kind: "expire";
+    milliseconds: number;
+} | {
+    kind: "keep";
+} | {
+    kind: "clear";
+};
+export declare function parseTTL(duration: unknown): number;
+export declare function resolveTTL(declared: number | undefined, written: WriteTTL | undefined): TTL;

package/dist/kv/ttl.js

@@ -0,0 +1,21 @@
+import { parseDurationMilliseconds } from "../delivery/duration.js";
+export function parseTTL(duration) {
+    if (typeof duration !== "string") {
+        throw new Error(`a ttl is a duration written with its unit, such as "10s", "5m" or "30d", not ${String(duration)}`);
+    }
+    const milliseconds = Math.round(parseDurationMilliseconds(duration));
+    if (milliseconds < 1) {
+        throw new Error(`a ttl is at least 1ms, and "${duration}" is shorter`);
+    }
+    return milliseconds;
+}
+export function resolveTTL(declared, written) {
+    if (written === undefined) {
+        return declared === undefined ? { kind: "clear" } : { kind: "expire", milliseconds: declared };
+    }
+    if (written === null)
+        return { kind: "clear" };
+    if (written === "keep")
+        return { kind: "keep" };
+    return { kind: "expire", milliseconds: parseTTL(written) };
+}

package/dist/postgres/index.d.ts

@@ -1,2 +1,21 @@
-import { Postgres, type PostgresConfig } from "./pg";
-export declare function postgres(id: string, config: PostgresConfig): Postgres;
+import { Pool } from "pg";
+import { type PostgresConfig } from "./pg.js";
+export { UnprovisionedResourceError } from "../binding/unprovisioned.js";
+type PgReturn = Pool & {
+    connectionString: string;
+};
+/**
+ * Declares a postgres database named `id` and returns a `pg` pool connected to it.
+ *
+ * At deploy the database is provisioned in your account, or bound to the record
+ * `bindings` names; the pool connects through the record's url when it has
+ * one, reading its `sslmode` as libpq does, and otherwise through its host, port,
+ * database, username and password, encrypted as its tls mode asks.
+ * `connectionString` is the same connection as a URL, for tools that take one.
+ */
+export declare function postgres(id: string, config?: PostgresConfig): PgReturn;
+/**
+ * Renders a postgres connection URL from its parts, percent-encoding the
+ * username and password so any character in either survives.
+ */
+export declare function connectionStringFor(host: string, port: number, database: string, username: string, password: string): string;

package/dist/postgres/index.js

@@ -1,4 +1,75 @@
-import { Postgres } from "./pg";
+import { Pool } from "pg";
+import { unprovisionedPhase, unprovisionedProxy } from "../binding/unprovisioned.js";
+import { PostgresTlsMode, } from "../gen/proto/common/bindings/v1/bindings_pb.js";
+import { Postgres } from "./pg.js";
+export { UnprovisionedResourceError } from "../binding/unprovisioned.js";
+/**
+ * Declares a postgres database named `id` and returns a `pg` pool connected to it.
+ *
+ * At deploy the database is provisioned in your account, or bound to the record
+ * `bindings` names; the pool connects through the record's url when it has
+ * one, reading its `sslmode` as libpq does, and otherwise through its host, port,
+ * database, username and password, encrypted as its tls mode asks.
+ * `connectionString` is the same connection as a URL, for tools that take one.
+ */
 export function postgres(id, config) {
-    return new Postgres(id, config);
+    const pg = new Postgres(id, config);
+    if (unprovisionedPhase()) {
+        return unprovisionedProxy(`postgres("${id}")`);
+    }
+    const properties = pg.__config();
+    const client = new Pool(poolConfig(properties));
+    return Object.assign(client, { connectionString: connectionStringOf(properties) });
+}
+function poolConfig(properties) {
+    if (properties.url) {
+        return { connectionString: withLibpqSslmodes(properties.url) };
+    }
+    const { host, port, database, username, password } = properties;
+    const config = { host, port, database, user: username, password };
+    switch (properties.tlsMode) {
+        case PostgresTlsMode.REQUIRE:
+            config.ssl = { rejectUnauthorized: false };
+            break;
+        case PostgresTlsMode.VERIFY_FULL:
+            config.ssl = properties.tlsCa
+                ? { rejectUnauthorized: true, ca: properties.tlsCa }
+                : { rejectUnauthorized: true };
+            break;
+    }
+    return config;
+}
+function withLibpqSslmodes(url) {
+    if (/[?&]uselibpqcompat=/.test(url)) {
+        return url;
+    }
+    return `${url}${url.includes("?") ? "&" : "?"}uselibpqcompat=true`;
+}
+const sslmodes = {
+    [PostgresTlsMode.UNSPECIFIED]: undefined,
+    [PostgresTlsMode.REQUIRE]: "require",
+    [PostgresTlsMode.VERIFY_FULL]: "verify-full",
+};
+function connectionStringOf(properties) {
+    if (properties.url) {
+        return properties.url;
+    }
+    const { host, port, database, username, password } = properties;
+    const url = new URL(connectionStringFor(host, port, database, username, password));
+    const sslmode = sslmodes[properties.tlsMode];
+    if (sslmode) {
+        url.searchParams.set("sslmode", sslmode);
+    }
+    return url.toString();
+}
+/**
+ * Renders a postgres connection URL from its parts, percent-encoding the
+ * username and password so any character in either survives.
+ */
+export function connectionStringFor(host, port, database, username, password) {
+    const url = new URL(`postgres://${host}:${port}/`);
+    url.pathname = `/${database}`;
+    url.username = username;
+    url.password = password;
+    return url.toString();
 }

package/dist/postgres/pg.d.ts

@@ -1,11 +1,12 @@
-import type { Component } from "../utils/component";
+import type { Component } from "../declaration/component.js";
+import type { PostgresProperties } from "../gen/proto/common/bindings/v1/bindings_pb.js";
 export interface PostgresConfig {
     version?: string;
-    migrations?: string;
 }
 export declare class Postgres implements Component {
     id: string;
-    constructor(id: string, config: PostgresConfig);
+    private type;
+    constructor(id: string, config?: PostgresConfig);
     __id(): string;
-    sql(query: string): Promise<{}>;
+    __config(): PostgresProperties;
 }

package/dist/postgres/pg.js

@@ -1,24 +1,28 @@
-import { rpc } from "../utils/rpc";
-import { getCallerFile } from "../utils/stack";
+import { getConfig } from "../binding/binding.js";
+import { declarationSite } from "../declaration/callsite.js";
+import { defer } from "../declaration/defer.js";
+import { ResourceType } from "../gen/proto/app/resources/v1/resources_pb.js";
+import { rpc } from "../runtime/rpc.js";
 export class Postgres {
     id;
+    type = ResourceType.POSTGRES;
     constructor(id, config) {
-        // remove non-serializable stuff
         this.id = id;
         if (process.env.OCEL_PHASE === "discovery") {
-            const source = getCallerFile();
-            rpc.register({
-                id: this.id,
-                type: "postgres",
-                source: source || "unknown",
-                config: {},
-            });
+            defer(rpc.resource.declare({
+                resource: { name: id, type: this.type },
+                config: {
+                    case: "postgres",
+                    value: { version: config?.version ?? "17" },
+                },
+                source: declarationSite(),
+            }));
         }
     }
     __id() {
         return this.id;
     }
-    async sql(query) {
-        return {};
+    __config() {
+        return getConfig(this.id, "postgres");
     }
 }

package/dist/providers/aws/dns.d.ts

@@ -0,0 +1,11 @@
+import type { DNSDescriptor } from "../../generated/config.js";
+/** Options for Route 53. */
+export interface Route53Options {
+    /**
+     * The hosted zone the records are written into. Omit it and ocel picks the
+     * zone that covers the hostname.
+     */
+    zone?: string;
+}
+/** Declares Route 53 as the DNS the project's records are written into. */
+export declare function route53(options?: Route53Options): DNSDescriptor;

package/dist/providers/aws/dns.js

@@ -0,0 +1,4 @@
+/** Declares Route 53 as the DNS the project's records are written into. */
+export function route53(options = {}) {
+    return { route53: options };
+}

package/dist/providers/aws/edge.d.ts

@@ -0,0 +1,6 @@
+import type { ApiGatewayEdgeOptions, CloudFrontEdgeOptions, EdgeDescriptor } from "../../generated/config.js";
+export type { ApiGatewayEdgeOptions, CloudFrontEdgeOptions } from "../../generated/config.js";
+/** Declares CloudFront as the edge the project's hostnames are served from. */
+export declare function cloudfront(options?: CloudFrontEdgeOptions): EdgeDescriptor;
+/** Declares API Gateway as the edge the project's hostnames are served from. */
+export declare function apiGateway(options?: ApiGatewayEdgeOptions): EdgeDescriptor;

package/dist/providers/aws/edge.js

@@ -0,0 +1,8 @@
+/** Declares CloudFront as the edge the project's hostnames are served from. */
+export function cloudfront(options = {}) {
+    return { cloudfront: options };
+}
+/** Declares API Gateway as the edge the project's hostnames are served from. */
+export function apiGateway(options = {}) {
+    return { "api-gateway": options };
+}

package/dist/providers/aws/index.d.ts

@@ -0,0 +1,4 @@
+import type { AwsProviderOptions, ProviderDescriptor } from "../../generated/config.js";
+export type { AwsProviderOptions };
+/** Declares AWS as the provider `ocel deploy` provisions into. */
+export default function awsProvider(options?: AwsProviderOptions): ProviderDescriptor;

package/dist/providers/aws/index.js

@@ -0,0 +1,4 @@
+/** Declares AWS as the provider `ocel deploy` provisions into. */
+export default function awsProvider(options = {}) {
+    return { aws: options };
+}

package/dist/providers/gcp/edge.d.ts

@@ -0,0 +1,14 @@
+import type { AlbEdgeOptions, EdgeDescriptor } from "../../generated/config.js";
+export type { AlbEdgeOptions } from "../../generated/config.js";
+/**
+ * Declares a global external Application Load Balancer, with Cloud CDN in
+ * front of Cloud Run, as the edge the project's hostnames are served from.
+ *
+ * One load balancer runs per bootstrap tier and every project in that tier
+ * is answered by it. It is the only piece of GCP infrastructure ocel provisions
+ * that costs money while it serves no traffic — roughly $18 a month per tier
+ * plus Premium-tier egress — so it is never the default: a project that names
+ * no edge is answered on the URL Cloud Run gives each service, and binds no
+ * hostname.
+ */
+export declare function alb(options?: AlbEdgeOptions): EdgeDescriptor;

package/dist/providers/gcp/edge.js

@@ -0,0 +1,14 @@
+/**
+ * Declares a global external Application Load Balancer, with Cloud CDN in
+ * front of Cloud Run, as the edge the project's hostnames are served from.
+ *
+ * One load balancer runs per bootstrap tier and every project in that tier
+ * is answered by it. It is the only piece of GCP infrastructure ocel provisions
+ * that costs money while it serves no traffic — roughly $18 a month per tier
+ * plus Premium-tier egress — so it is never the default: a project that names
+ * no edge is answered on the URL Cloud Run gives each service, and binds no
+ * hostname.
+ */
+export function alb(options = {}) {
+    return { alb: options };
+}

package/dist/providers/gcp/index.d.ts

@@ -0,0 +1,9 @@
+import type { GcpProviderOptions, ProviderDescriptor } from "../../generated/config.js";
+export type { GcpProviderOptions };
+/**
+ * Declares Google Cloud as the provider `ocel deploy` provisions into.
+ *
+ * Credentials are read from Application Default Credentials in the environment
+ * the provider runs in: `gcloud auth application-default login`.
+ */
+export default function gcpProvider(options: GcpProviderOptions): ProviderDescriptor;

package/dist/providers/gcp/index.js

@@ -0,0 +1,9 @@
+/**
+ * Declares Google Cloud as the provider `ocel deploy` provisions into.
+ *
+ * Credentials are read from Application Default Credentials in the environment
+ * the provider runs in: `gcloud auth application-default login`.
+ */
+export default function gcpProvider(options) {
+    return { gcp: options };
+}

package/dist/providers/vps/index.d.ts

@@ -0,0 +1,4 @@
+import type { ProviderDescriptor, VpsProviderOptions, VpsProxy, VpsTarget } from "../../generated/config.js";
+export type { VpsProviderOptions, VpsProxy, VpsTarget };
+/** Declares a VPS as the provider `ocel deploy` provisions into. */
+export default function vpsProvider(options: VpsProviderOptions): ProviderDescriptor;

package/dist/providers/vps/index.js

@@ -0,0 +1,4 @@
+/** Declares a VPS as the provider `ocel deploy` provisions into. */
+export default function vpsProvider(options) {
+    return { vps: options };
+}

package/dist/realtime/client-error.d.ts

@@ -0,0 +1,30 @@
+import type { RealtimeDenial } from "./handler.js";
+/**
+ * Why the realtime handler or the transport refused an operation, or why it could not be
+ * attempted: one of the handler's denial codes, or one the client names itself.
+ *
+ * - `headers-failed`: the `headers` function threw.
+ * - `handler-unreachable`: the handler could not be reached, did not answer in time, or
+ *   answered without JSON.
+ * - `handler-refused`: the handler answered with an HTTP error status.
+ * - `invalid-grant`: the handler granted a subscribe without the token it takes.
+ * - `connection-failed`: the socket could not be opened, or was not accepted in time.
+ * - `connection-lost`: the open socket dropped or went silent.
+ * - `subscribe-refused`: the transport refused a subscription the handler granted.
+ * - `unsupported-transport`: the handler named a transport this client does not speak.
+ * - `closed`: the client was closed.
+ */
+export type RealtimeErrorCode = RealtimeDenial | "headers-failed" | "handler-unreachable" | "handler-refused" | "invalid-grant" | "connection-failed" | "connection-lost" | "subscribe-refused" | "unsupported-transport" | "closed";
+/** An operation the realtime client could not complete. */
+export declare class RealtimeError extends Error {
+    name: string;
+    /** What refused the operation, or why it could not be attempted. */
+    readonly code: RealtimeErrorCode;
+    /**
+     * Whether the same operation may succeed if tried again: true for a network failure, a
+     * dropped connection or a failing rule, false for a denial that would be answered the
+     * same way. A subscription the client keeps retrying on its own reports `true`.
+     */
+    readonly retriable: boolean;
+    constructor(code: RealtimeErrorCode, retriable: boolean, message: string);
+}

package/dist/realtime/client-error.js

@@ -0,0 +1,17 @@
+/** An operation the realtime client could not complete. */
+export class RealtimeError extends Error {
+    name = "RealtimeError";
+    /** What refused the operation, or why it could not be attempted. */
+    code;
+    /**
+     * Whether the same operation may succeed if tried again: true for a network failure, a
+     * dropped connection or a failing rule, false for a denial that would be answered the
+     * same way. A subscription the client keeps retrying on its own reports `true`.
+     */
+    retriable;
+    constructor(code, retriable, message) {
+        super(message);
+        this.code = code;
+        this.retriable = retriable;
+    }
+}

package/dist/realtime/client-event-socket.d.ts

@@ -0,0 +1,8 @@
+import type { ClientTransport } from "./client-transport.js";
+/** The Ocel gateway's socket, which speaks the AppSync Events protocol. */
+export declare const gatewayTransport: ClientTransport;
+/**
+ * AppSync Events' socket. AppSync ends a connection after 24 hours, which reaches the
+ * client as a drop, so every live subscription is authorized again on the next socket.
+ */
+export declare const appSyncTransport: ClientTransport;

package/dist/realtime/client-event-socket.js

@@ -0,0 +1,169 @@
+import { RealtimeError } from "./client-error.js";
+const subprotocol = "aws-appsync-event-ws";
+const answerDeadlineMilliseconds = 10_000;
+function encodeBase64url(text) {
+    let binary = "";
+    for (const byte of new TextEncoder().encode(text))
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function describeErrors(frame) {
+    return (frame.errors ?? []).map((error) => error.message ?? error.errorType ?? "").join("; ");
+}
+function readEnvelopes(event) {
+    const texts = Array.isArray(event) ? event : [event];
+    return texts.flatMap((text) => {
+        if (typeof text !== "string")
+            return [];
+        try {
+            const decoded = JSON.parse(text);
+            return [typeof decoded === "string" ? decoded : text];
+        }
+        catch {
+            return [text];
+        }
+    });
+}
+function createEventSocketTransport(peer) {
+    return {
+        connect(grant, onDrop) {
+            return new Promise((resolve, reject) => {
+                const authorize = (token) => grant.host === undefined
+                    ? { Authorization: token }
+                    : { host: grant.host, Authorization: token };
+                const socket = new WebSocket(grant.url, [
+                    subprotocol,
+                    `header-${encodeBase64url(JSON.stringify(authorize(grant.token)))}`,
+                ]);
+                const pending = new Map();
+                const listeners = new Map();
+                let isOpen = false;
+                let hasEnded = false;
+                let isClosedByClient = false;
+                let silenceTimer;
+                let silenceLimitMilliseconds = 0;
+                const send = (frame) => {
+                    if (socket.readyState === WebSocket.OPEN)
+                        socket.send(JSON.stringify(frame));
+                };
+                const end = (error) => {
+                    if (hasEnded)
+                        return;
+                    hasEnded = true;
+                    clearTimeout(handshakeDeadline);
+                    clearTimeout(silenceTimer);
+                    for (const waiting of pending.values()) {
+                        clearTimeout(waiting.deadline);
+                        waiting.reject(error);
+                    }
+                    pending.clear();
+                    listeners.clear();
+                    if (!isOpen) {
+                        reject(error);
+                        return;
+                    }
+                    isOpen = false;
+                    if (!isClosedByClient)
+                        onDrop(error);
+                };
+                const abandon = (error) => {
+                    socket.close();
+                    end(error);
+                };
+                const handshakeDeadline = setTimeout(() => abandon(new RealtimeError("connection-failed", true, `${peer} did not accept the connection within ${answerDeadlineMilliseconds}ms`)), answerDeadlineMilliseconds);
+                const watchSilence = () => {
+                    if (silenceLimitMilliseconds <= 0)
+                        return;
+                    clearTimeout(silenceTimer);
+                    silenceTimer = setTimeout(() => abandon(new RealtimeError("connection-lost", true, `${peer} sent nothing for ${silenceLimitMilliseconds}ms`)), silenceLimitMilliseconds);
+                };
+                const settleSubscribe = (id) => {
+                    const waiting = pending.get(id);
+                    pending.delete(id);
+                    if (waiting)
+                        clearTimeout(waiting.deadline);
+                    return waiting;
+                };
+                const connection = {
+                    subscribe(id, channel, token, onEvent) {
+                        if (!isOpen) {
+                            return Promise.reject(new RealtimeError("connection-lost", true, "the connection is no longer open"));
+                        }
+                        return new Promise((subscribed, refused) => {
+                            const waiting = {
+                                resolve: () => {
+                                    if (waiting.isCancelled)
+                                        send({ type: "unsubscribe", id });
+                                    else
+                                        listeners.set(id, onEvent);
+                                    subscribed();
+                                },
+                                reject: refused,
+                                deadline: setTimeout(() => abandon(new RealtimeError("connection-lost", true, `${peer} did not answer a subscribe within ${answerDeadlineMilliseconds}ms`)), answerDeadlineMilliseconds),
+                                isCancelled: false,
+                            };
+                            pending.set(id, waiting);
+                            send({ type: "subscribe", id, channel, authorization: authorize(token) });
+                        });
+                    },
+                    unsubscribe(id) {
+                        const waiting = pending.get(id);
+                        if (waiting)
+                            waiting.isCancelled = true;
+                        if (listeners.delete(id))
+                            send({ type: "unsubscribe", id });
+                    },
+                    close() {
+                        isClosedByClient = true;
+                        socket.close(1000);
+                        end(new RealtimeError("closed", false, "the realtime client was closed"));
+                    },
+                };
+                socket.addEventListener("open", () => send({ type: "connection_init" }));
+                socket.addEventListener("message", (message) => {
+                    let frame;
+                    try {
+                        frame = JSON.parse(String(message.data));
+                    }
+                    catch {
+                        return;
+                    }
+                    watchSilence();
+                    switch (frame.type) {
+                        case "connection_ack":
+                            clearTimeout(handshakeDeadline);
+                            isOpen = true;
+                            silenceLimitMilliseconds = frame.connectionTimeoutMs ?? 0;
+                            watchSilence();
+                            resolve(connection);
+                            return;
+                        case "connection_error":
+                            abandon(new RealtimeError("connection-failed", true, `${peer} refused the connection: ${describeErrors(frame)}`));
+                            return;
+                        case "subscribe_success":
+                            settleSubscribe(frame.id ?? "")?.resolve();
+                            return;
+                        case "subscribe_error":
+                            settleSubscribe(frame.id ?? "")?.reject(new RealtimeError("subscribe-refused", false, `${peer} refused the subscription: ${describeErrors(frame)}`));
+                            return;
+                        case "data": {
+                            const listener = listeners.get(frame.id ?? "");
+                            if (listener)
+                                for (const envelope of readEnvelopes(frame.event))
+                                    listener(envelope);
+                            return;
+                        }
+                    }
+                });
+                socket.addEventListener("close", () => end(new RealtimeError(isOpen ? "connection-lost" : "connection-failed", true, isOpen ? `the connection to ${peer} closed` : `${peer} could not be reached`)));
+            });
+        },
+    };
+}
+/** The Ocel gateway's socket, which speaks the AppSync Events protocol. */
+export const gatewayTransport = createEventSocketTransport("the gateway");
+/**
+ * AppSync Events' socket. AppSync ends a connection after 24 hours, which reaches the
+ * client as a drop, so every live subscription is authorized again on the next socket.
+ */
+export const appSyncTransport = createEventSocketTransport("AppSync");

package/dist/realtime/client-transport.d.ts

@@ -0,0 +1,29 @@
+import { RealtimeError } from "./client-error.js";
+import type { Transport } from "./transport.js";
+/** What the realtime handler answered a connect with: where the socket is and its token. */
+export interface ConnectGrant {
+    url: string;
+    host?: string;
+    token: string;
+}
+/** One open socket to a transport, carrying any number of subscriptions. */
+export interface TransportConnection {
+    /**
+     * Subscribes `id` to `channel` with its subscribe token, resolving once the transport
+     * accepts it and rejecting with a {@link RealtimeError} when it refuses; each event
+     * then reaches `onEvent` as the envelope's JSON text.
+     */
+    subscribe(id: string, channel: string, token: string, onEvent: (envelope: string) => void): Promise<void>;
+    unsubscribe(id: string): void;
+    close(): void;
+}
+/** How a browser reaches one kind of transport. */
+export interface ClientTransport {
+    /**
+     * Opens a socket with `grant`, resolving once the transport accepts it. `onDrop` hears
+     * of a socket that ended without `close` being called.
+     */
+    connect(grant: ConnectGrant, onDrop: (error: RealtimeError) => void): Promise<TransportConnection>;
+}
+/** Loads the transport the realtime handler named, so a bundle carries only the one it uses. */
+export declare function loadTransport(name: Transport["name"]): Promise<ClientTransport>;