ocel 0.0.1-alpha.1 → 0.0.1

package/dist/realtime/handler.js

@@ -0,0 +1,287 @@
+import { encodeEvent, isParams, readRuntime, } from "./realtime.js";
+import { mintToken } from "./token.js";
+import { resolveTransport } from "./transport.js";
+import { encodeWireChannel } from "./wire.js";
+/** The most bytes a realtime handler reads of a request body before refusing it with 413. */
+export const maxRequestBytes = 1024 * 1024;
+const maxOperations = 50;
+const operationKeys = new Set(["op", "pattern", "params", "body"]);
+function respond(status, body, headers = {}) {
+    return new Response(body === undefined ? null : JSON.stringify(body), {
+        status,
+        headers: {
+            "cache-control": "no-store",
+            ...(body === undefined ? {} : { "content-type": "application/json" }),
+            ...headers,
+        },
+    });
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function readFirstHeaderValue(request, name) {
+    return request.headers.get(name)?.split(",")[0]?.trim() || undefined;
+}
+function readOwnOrigin(request) {
+    const url = new URL(request.url);
+    return {
+        scheme: readFirstHeaderValue(request, "x-forwarded-proto")?.toLowerCase() ??
+            url.protocol.slice(0, -1),
+        host: readFirstHeaderValue(request, "x-forwarded-host") ??
+            (request.headers.get("host") || url.host),
+    };
+}
+function resolveSocketURL(url, request) {
+    if (!url.startsWith("/"))
+        return url;
+    const own = readOwnOrigin(request);
+    return `${own.scheme === "https" ? "wss" : "ws"}://${own.host}${url}`;
+}
+function judgeOrigin(request, allowedOrigins) {
+    const origin = request.headers.get("origin");
+    if (origin === null)
+        return { allowed: true, cors: {} };
+    if (allowedOrigins.includes(origin)) {
+        return {
+            allowed: true,
+            cors: { "access-control-allow-origin": origin, vary: "Origin" },
+        };
+    }
+    let url;
+    try {
+        url = new URL(origin);
+    }
+    catch {
+        return { allowed: false };
+    }
+    const own = readOwnOrigin(request);
+    return url.host !== "" && url.protocol === `${own.scheme}:` && url.host === own.host
+        ? { allowed: true, cors: {} }
+        : { allowed: false };
+}
+function readSubject(auth) {
+    const id = auth?.id;
+    return typeof id === "string" || typeof id === "number" ? String(id) : "anonymous";
+}
+async function readBoundedText(request) {
+    const reader = request.body?.getReader();
+    if (!reader)
+        return "";
+    const chunks = [];
+    let bytes = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        bytes += value.byteLength;
+        if (bytes > maxRequestBytes) {
+            await reader.cancel();
+            return undefined;
+        }
+        chunks.push(value);
+    }
+    const joined = new Uint8Array(bytes);
+    let offset = 0;
+    for (const chunk of chunks) {
+        joined.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return new TextDecoder().decode(joined);
+}
+function copyRequest(request, text) {
+    return new Request(request, { body: text });
+}
+function parseBatch(text) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isPlainObject(value))
+        return undefined;
+    if (Object.keys(value).some((key) => key !== "connect" && key !== "ops"))
+        return undefined;
+    const { connect, ops: operations } = value;
+    if (!Array.isArray(operations) || (connect !== undefined && typeof connect !== "boolean")) {
+        return undefined;
+    }
+    return { connect: connect ?? false, operations };
+}
+async function runRule(rule) {
+    try {
+        return (await rule()) ? "allowed" : "forbidden";
+    }
+    catch {
+        return "rule-error";
+    }
+}
+async function evaluateOperation(batch, value, i) {
+    const deny = (code) => ({ denied: { i, code } });
+    if (!isPlainObject(value) ||
+        Object.keys(value).some((key) => !operationKeys.has(key)) ||
+        (value.op === "subscribe" && Object.hasOwn(value, "body"))) {
+        return deny("invalid-op");
+    }
+    const operation = value.op;
+    if (operation !== "subscribe" && operation !== "publish")
+        return deny("unknown-op");
+    const channel = typeof value.pattern === "string" ? batch.runtime.channels.get(value.pattern) : undefined;
+    if (!channel)
+        return deny("unknown-pattern");
+    if (operation === "publish" && !channel.publish)
+        return deny("no-publish-rule");
+    const params = value.params ?? {};
+    if (!isParams(params))
+        return deny("invalid-params");
+    const wire = encodeWireChannel(batch.runtime.name, channel.pattern, params, operation === "subscribe" && channel.wildcard);
+    if ("refused" in wire)
+        return deny(wire.refused);
+    return operation === "subscribe"
+        ? evaluateSubscribe(batch, channel, params, wire.channel, i)
+        : evaluatePublish(batch, channel, params, wire.channel, value, i);
+}
+async function evaluateSubscribe(batch, channel, params, wire, i) {
+    const rule = channel.subscribe;
+    if (rule !== "public") {
+        if (batch.auth === null)
+            return { denied: { i, code: "unauthenticated" } };
+        const request = copyRequest(batch.request, batch.text);
+        const verdict = await runRule(() => rule({ auth: batch.auth, params, request }));
+        if (verdict !== "allowed")
+            return { denied: { i, code: verdict } };
+    }
+    const { token } = mintToken(batch.properties, batch.runtime, batch.subject, "subscribe", wire);
+    return { grant: { i, wire, token } };
+}
+async function evaluatePublish(batch, channel, params, wire, operation, i) {
+    const rule = channel.publish;
+    if (!rule)
+        return { denied: { i, code: "no-publish-rule" } };
+    if (!Object.hasOwn(operation, "body"))
+        return { denied: { i, code: "invalid-body" } };
+    const event = await encodeEvent(channel, wire, operation.body);
+    if ("refused" in event)
+        return { denied: { i, code: event.refused } };
+    if (batch.auth === null)
+        return { denied: { i, code: "unauthenticated" } };
+    const request = copyRequest(batch.request, batch.text);
+    const verdict = await runRule(() => rule({ auth: batch.auth, params, body: event.body, request }));
+    if (verdict !== "allowed")
+        return { denied: { i, code: verdict } };
+    try {
+        await batch.runtime.publish("handler", event.channel, event.envelope);
+    }
+    catch {
+        return { denied: { i, code: "publish-failed" } };
+    }
+    return { grant: { i, wire } };
+}
+function isOperationNamed(value, name) {
+    return isPlainObject(value) && value.op === name;
+}
+function evaluateOperations(batch, operations) {
+    let publishing = Promise.resolve();
+    return Promise.all(operations.map((value, i) => {
+        if (!isOperationNamed(value, "publish"))
+            return evaluateOperation(batch, value, i);
+        const outcome = publishing.then(() => evaluateOperation(batch, value, i));
+        publishing = outcome.catch(() => undefined);
+        return outcome;
+    }));
+}
+async function serveBatch(runtime, request, cors) {
+    const mediaType = request.headers.get("content-type")?.split(";")[0]?.trim().toLowerCase();
+    if (mediaType !== "application/json") {
+        return respond(415, { error: "the realtime handler takes application/json" }, cors);
+    }
+    const tooLarge = () => respond(413, { error: `a request is at most ${maxRequestBytes} bytes` }, cors);
+    if (Number(request.headers.get("content-length") ?? 0) > maxRequestBytes)
+        return tooLarge();
+    const text = await readBoundedText(request);
+    if (text === undefined)
+        return tooLarge();
+    const parsed = parseBatch(text);
+    if (!parsed) {
+        return respond(400, { error: "the body is { connect?: boolean, ops: [{ op, pattern, params?, body? }] }" }, cors);
+    }
+    if (parsed.operations.length > maxOperations) {
+        return respond(400, { error: `a request holds at most ${maxOperations} ops` }, cors);
+    }
+    const properties = runtime.properties("handler");
+    const transport = resolveTransport(properties, runtime.name);
+    let auth = null;
+    if (runtime.authorize) {
+        try {
+            auth = (await runtime.authorize(copyRequest(request, text))) ?? null;
+        }
+        catch {
+            return respond(500, { error: "authorize failed" }, cors);
+        }
+    }
+    const batch = {
+        runtime,
+        text,
+        request,
+        auth,
+        subject: readSubject(auth),
+        properties,
+        transport,
+    };
+    const connect = parsed.connect
+        ? mintToken(properties, runtime, batch.subject, "connect", `/${runtime.name}`)
+        : undefined;
+    const outcomes = await evaluateOperations(batch, parsed.operations);
+    const answer = {
+        transport: transport.name,
+        url: resolveSocketURL(properties.url, request),
+        ...(transport.host === undefined ? {} : { host: transport.host }),
+        ...(connect === undefined ? {} : { connect }),
+        grants: outcomes.flatMap((outcome) => ("grant" in outcome ? [outcome.grant] : [])),
+        denied: outcomes.flatMap((outcome) => ("denied" in outcome ? [outcome.denied] : [])),
+    };
+    return respond(200, answer, cors);
+}
+/**
+ * Serves `rt` to browsers as Web `Request` to `Response` handlers, for a framework that
+ * speaks the Fetch API. It takes `POST` with `application/json` alone, serves its own
+ * origin and those in `allowedOrigins`, answers `Cache-Control: no-store`, and never sets
+ * a cookie.
+ */
+export function createWebRealtimeHandler(rt, options = {}) {
+    const runtime = readRuntime(rt);
+    const allowedOrigins = options.allowedOrigins ?? [];
+    const respondMethodNotAllowed = () => respond(405, { error: "the realtime handler takes POST" }, { allow: "POST" });
+    return {
+        async POST(request) {
+            let cors = {};
+            try {
+                const verdict = judgeOrigin(request, allowedOrigins);
+                if (!verdict.allowed) {
+                    return respond(403, { error: "this origin may not call the realtime handler" });
+                }
+                cors = verdict.cors;
+                return await serveBatch(runtime, request, cors);
+            }
+            catch {
+                return respond(500, { error: "the realtime handler failed" }, cors);
+            }
+        },
+        async GET() {
+            return respondMethodNotAllowed();
+        },
+        async OPTIONS(request) {
+            const origin = request.headers.get("origin");
+            if (origin === null || !allowedOrigins.includes(origin))
+                return respondMethodNotAllowed();
+            return respond(204, undefined, {
+                "access-control-allow-origin": origin,
+                "access-control-allow-methods": "POST",
+                "access-control-allow-headers": "authorization, content-type",
+                "access-control-max-age": "600",
+                vary: "Origin",
+            });
+        },
+    };
+}

package/dist/realtime/hono.d.ts

@@ -0,0 +1,19 @@
+import type { Context } from "hono";
+import { type RealtimeHandlerOptions } from "./handler.js";
+import type { Realtime } from "./realtime.js";
+export type { RealtimeHandlerOptions } from "./handler.js";
+export * from "./index.js";
+/** A Hono handler serving a realtime resource. */
+export type HonoRealtimeHandler = (c: Context) => Promise<Response>;
+/**
+ * Serves `rt` to browsers from a Hono route, mounted at any path:
+ *
+ * ```ts
+ * app.all("/api/realtime", createRealtimeHandler(rt));
+ * ```
+ *
+ * It takes `POST` with `application/json` alone, serves its own origin and those in
+ * `allowedOrigins`, answers `Cache-Control: no-store`, and never sets a cookie.
+ * `authorize` receives the request as a Web `Request`.
+ */
+export declare function createRealtimeHandler(rt: Realtime<any, any>, options?: RealtimeHandlerOptions): HonoRealtimeHandler;

package/dist/realtime/hono.js

@@ -0,0 +1,24 @@
+import { createWebRealtimeHandler } from "./handler.js";
+export * from "./index.js";
+/**
+ * Serves `rt` to browsers from a Hono route, mounted at any path:
+ *
+ * ```ts
+ * app.all("/api/realtime", createRealtimeHandler(rt));
+ * ```
+ *
+ * It takes `POST` with `application/json` alone, serves its own origin and those in
+ * `allowedOrigins`, answers `Cache-Control: no-store`, and never sets a cookie.
+ * `authorize` receives the request as a Web `Request`.
+ */
+export function createRealtimeHandler(rt, options) {
+    const handler = createWebRealtimeHandler(rt, options);
+    return (c) => {
+        const request = c.req.raw;
+        if (request.method === "POST")
+            return handler.POST(request);
+        if (request.method === "OPTIONS")
+            return handler.OPTIONS(request);
+        return handler.GET(request);
+    };
+}

package/dist/realtime/index.d.ts

@@ -0,0 +1,2 @@
+export { UnprovisionedResourceError } from "../binding/unprovisioned.js";
+export { type ChannelParams, type ChannelRules, type ChannelShape, type PublishContext, type PublishMessage, type PublishRefusal, Realtime, type RealtimeOptions, RealtimePublishError, realtime, type SubscribeContext, } from "./realtime.js";

package/dist/realtime/index.js

@@ -0,0 +1,2 @@
+export { UnprovisionedResourceError } from "../binding/unprovisioned.js";
+export { Realtime, RealtimePublishError, realtime, } from "./realtime.js";

package/dist/realtime/next.d.ts

@@ -0,0 +1,26 @@
+import type { NextRequest } from "next/server";
+import { type RealtimeHandlerOptions } from "./handler.js";
+import type { Realtime } from "./realtime.js";
+export type { RealtimeHandlerOptions } from "./handler.js";
+export * from "./index.js";
+/** The route handlers a Next.js `route.ts` exports to serve a realtime resource. */
+export interface NextRealtimeHandlers {
+    /** Serves a batch of `connect`, `subscribe` and `publish` requests. */
+    POST: (request: NextRequest | Request) => Promise<Response>;
+    /** Refuses with 405: the handler takes POST alone. */
+    GET: (request: NextRequest | Request) => Promise<Response>;
+    /** Answers the CORS preflight of an origin in `allowedOrigins`, and refuses any other. */
+    OPTIONS: (request: NextRequest | Request) => Promise<Response>;
+}
+/**
+ * Serves `rt` to browsers from a Next.js route handler, mounted at any path:
+ *
+ * ```ts
+ * // app/api/realtime/route.ts
+ * export const { GET, POST, OPTIONS } = createRealtimeHandler(rt);
+ * ```
+ *
+ * It takes `POST` with `application/json` alone, serves its own origin and those in
+ * `allowedOrigins`, answers `Cache-Control: no-store`, and never sets a cookie.
+ */
+export declare function createRealtimeHandler(rt: Realtime<any, any>, options?: RealtimeHandlerOptions): NextRealtimeHandlers;

package/dist/realtime/next.js

@@ -0,0 +1,16 @@
+import { createWebRealtimeHandler } from "./handler.js";
+export * from "./index.js";
+/**
+ * Serves `rt` to browsers from a Next.js route handler, mounted at any path:
+ *
+ * ```ts
+ * // app/api/realtime/route.ts
+ * export const { GET, POST, OPTIONS } = createRealtimeHandler(rt);
+ * ```
+ *
+ * It takes `POST` with `application/json` alone, serves its own origin and those in
+ * `allowedOrigins`, answers `Cache-Control: no-store`, and never sets a cookie.
+ */
+export function createRealtimeHandler(rt, options) {
+    return createWebRealtimeHandler(rt, options);
+}

package/dist/realtime/realtime.d.ts

@@ -0,0 +1,181 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import { type Duration } from "../delivery/duration.js";
+import type { RealtimeProperties } from "../gen/proto/common/bindings/v1/bindings_pb.js";
+import type { PatternParameters } from "../kv/pattern.js";
+import type { TokenIssuer } from "./token.js";
+import { type ChannelPattern, type WireRefusal } from "./wire.js";
+type MaybePromise<T> = T | Promise<T>;
+/** One value for each `:parameter` of a pattern such as `"orders/:orderId"`. */
+export type ChannelParams<TPattern extends string> = {
+    [Name in PatternParameters<TPattern>]: string;
+};
+/** What a `subscribe` rule decides from: the caller's auth, the channel's params and the request. */
+export interface SubscribeContext<TAuth, TParams> {
+    /** What `authorize` returned for this request. */
+    auth: TAuth;
+    /** The params the caller asked for; on a `wildcard` pattern, trailing ones may be missing. */
+    params: TParams;
+    /** The request the realtime handler received. */
+    request: Request;
+}
+/** What a `publish` rule decides from: a {@link SubscribeContext} and the event's body. */
+export interface PublishContext<TAuth, TParams, TBody> extends SubscribeContext<TAuth, TParams> {
+    /** The event the caller asked to publish, as its schema parsed it. */
+    body: TBody;
+}
+/** The parts of a channel's declaration its rules are typed from. */
+export interface ChannelShape {
+    /** A Standard Schema every event on the channel is validated against. */
+    schema: StandardSchemaV1;
+    /** Lets a subscriber leave off trailing params, receiving every channel under the rest. */
+    wildcard?: boolean;
+    /**
+     * `"public"`, which anyone may subscribe to, or a rule answering whether a caller may;
+     * a rule needs `authorize` on the resource.
+     */
+    subscribe: unknown;
+    /**
+     * A rule answering whether a caller may publish from a browser; it needs `authorize` on
+     * the resource. Without it, only the server publishes.
+     */
+    publish?: unknown;
+}
+type SubscribeParams<TPattern extends string, TChannel> = TChannel extends {
+    wildcard: true;
+} ? Partial<ChannelParams<TPattern>> : ChannelParams<TPattern>;
+type BodyOf<TChannel> = TChannel extends {
+    schema: infer TSchema extends StandardSchemaV1;
+} ? StandardSchemaV1.InferOutput<TSchema> : never;
+type BodyInputOf<TChannel> = TChannel extends {
+    schema: infer TSchema extends StandardSchemaV1;
+} ? StandardSchemaV1.InferInput<TSchema> : never;
+/** The access rules of one channel pattern. */
+export interface ChannelRules<TAuth, TPattern extends string, TChannel> {
+    /** `"public"`, which anyone may subscribe to, or a rule answering whether this caller may. */
+    subscribe: "public" | ((context: SubscribeContext<TAuth, SubscribeParams<TPattern, TChannel>>) => MaybePromise<boolean>);
+    /** A rule answering whether this caller may publish from a browser; without it, only the server publishes. */
+    publish?: (context: PublishContext<TAuth, ChannelParams<TPattern>, BodyOf<TChannel>>) => MaybePromise<boolean>;
+}
+/** How a realtime resource is declared. */
+export interface RealtimeOptions<TAuth, TChannels extends Record<string, ChannelShape>> {
+    /**
+     * Identifies the caller of the realtime handler from its request, with whatever auth the
+     * app already uses, and answers `null` for nobody. Its result is `auth` in every rule;
+     * its `id`, when a string or number, is the `sub` of every token minted for the caller.
+     */
+    authorize?: (request: Request) => MaybePromise<TAuth | null | undefined>;
+    /** How long each minted token lives, from 10 to 300 seconds; without it, 60 seconds. */
+    tokenTtl?: Duration;
+    /**
+     * The channel patterns, each at most 4 `/`-separated segments that are each a literal
+     * or a `:param`, mapped to the event schema and access rules of every channel it names.
+     */
+    channels: {
+        [TPattern in keyof TChannels]: {
+            [Key in keyof TChannels[TPattern]]: TChannels[TPattern][Key];
+        } & ChannelRules<TAuth, TPattern & string, TChannels[TPattern]>;
+    };
+}
+/** The `{ params, body }` a publish on `TPattern` takes. */
+export type PublishMessage<TPattern extends string, TChannel> = [
+    PatternParameters<TPattern>
+] extends [never] ? {
+    params?: Record<string, never>;
+    body: BodyInputOf<TChannel>;
+} : {
+    params: ChannelParams<TPattern>;
+    body: BodyInputOf<TChannel>;
+};
+/** A channel pattern as the resource declared it, its rules untyped. */
+export interface DeclaredChannel {
+    pattern: ChannelPattern;
+    schema: StandardSchemaV1;
+    wildcard: boolean;
+    subscribe: "public" | ((context: SubscribeContext<unknown, unknown>) => MaybePromise<boolean>);
+    publish?: (context: PublishContext<unknown, unknown, unknown>) => MaybePromise<boolean>;
+}
+/** What the realtime handler and publish read of a declared resource. */
+export interface RealtimeRuntime extends TokenIssuer {
+    channels: Map<string, DeclaredChannel>;
+    authorize?: (request: Request) => MaybePromise<unknown>;
+    properties(access: string): RealtimeProperties;
+    /** Hands the ocel runtime `envelope` to publish on the wire `channel`. */
+    publish(access: string, channel: string, envelope: string): Promise<void>;
+}
+/**
+ * Why `publish` refused an event: the pattern was never declared, the params are not all
+ * strings, a param is missing, unknown, empty or over 30 bytes, the body fails the
+ * pattern's schema, or the event is over 240 KiB.
+ */
+export type PublishRefusal = "unknown-pattern" | "invalid-params" | "invalid-body" | "body-too-large" | WireRefusal;
+/** Thrown by `publish` when the pattern, params or body cannot be published, naming why. */
+export declare class RealtimePublishError extends Error {
+    name: string;
+    /**
+     * The reason: `unknown-pattern`, `invalid-params`, `missing-param`, `unknown-param`,
+     * `empty-value`, `value-too-long`, `invalid-body` or `body-too-large`.
+     */
+    readonly code: PublishRefusal;
+    constructor(code: PublishRefusal, message: string);
+}
+/** Reads what the realtime handler serves of `rt`, throwing for one `realtime()` did not declare. */
+export declare function readRuntime(rt: Realtime): RealtimeRuntime;
+/** A declared realtime resource, and the handle its channels are published through. */
+export declare class Realtime<TAuth = unknown, TChannels extends Record<string, ChannelShape> = Record<string, ChannelShape>> {
+    /** The name this resource was declared under, which begins every channel. */
+    readonly name: string;
+    /** Type-only: the auth `authorize` answers and the declared channels, for a client's types. */
+    readonly types?: {
+        auth: TAuth;
+        channels: TChannels;
+    };
+    constructor(name: string, options: RealtimeOptions<TAuth, TChannels>);
+    /**
+     * Publishes `body` on the channel `params` fill in `pattern`, to every subscriber, after
+     * validating it against the pattern's schema. Every param is required. Throws a
+     * {@link RealtimePublishError} for a pattern, params or body that cannot be published.
+     */
+    publish<TPattern extends keyof TChannels & string>(pattern: TPattern, message: PublishMessage<TPattern, TChannels[TPattern]>): Promise<void>;
+}
+/** An event ready for the runtime to publish, or why it cannot be published. */
+export type PreparedEvent = {
+    channel: string;
+    body: unknown;
+    envelope: string;
+} | {
+    refused: PublishRefusal;
+    reason: string;
+};
+/** Whether `params` is an object mapping each name to a string. */
+export declare function isParams(params: unknown): params is Record<string, string>;
+/**
+ * Validates `body` against `channel`'s schema and encodes the envelope it is published in
+ * on `wire`, refusing a body the schema rejects or an event over 240 KiB.
+ */
+export declare function encodeEvent(channel: DeclaredChannel, wire: string, body: unknown): Promise<PreparedEvent>;
+/** Prepares the event the server publishes on `pattern`, or says why it cannot. */
+export declare function prepareEvent(runtime: RealtimeRuntime, pattern: string, params: unknown, body: unknown): Promise<PreparedEvent>;
+/**
+ * Declares a realtime resource named `name`: typed channels that browsers subscribe to
+ * and the server publishes on, each pattern with the rules that decide who may.
+ *
+ * ```ts
+ * export const rt = realtime("app", {
+ *   authorize: async (req) => (await getSession(req)) ?? null,
+ *   channels: {
+ *     "orders/:orderId": {
+ *       schema: OrderEvent,
+ *       subscribe: async ({ auth, params }) => ownsOrder(auth, params.orderId),
+ *     },
+ *     status: { schema: Status, subscribe: "public" },
+ *   },
+ * });
+ *
+ * await rt.publish("orders/:orderId", { params: { orderId }, body: { status: "shipped" } });
+ * ```
+ *
+ * Serve it to browsers with `createRealtimeHandler` from `ocel/realtime/next`,
+ * `ocel/realtime/express` or `ocel/realtime/hono`.
+ */
+export declare function realtime<TAuth, TChannels extends Record<string, ChannelShape>>(name: string, options: RealtimeOptions<TAuth, TChannels>): Realtime<TAuth, TChannels>;
+export {};