@swirls/looms 0.0.2 → 0.2.0

package/dist/runtime/server/auth.d.ts

@@ -0,0 +1,41 @@
+import { Effect } from 'effect';
+/**
+ * What a route can do. `public` routes (health) are never passed to `authorize`; `read` and
+ * `write` cover run state, `worker` covers external worker callbacks, and `operations` covers
+ * operator repair endpoints.
+ */
+export type RouteAccess = 'public' | 'read' | 'write' | 'worker' | 'operations';
+export type AuthorizedAccess = Exclude<RouteAccess, 'public'>;
+export interface RouteInfo {
+    readonly access: AuthorizedAccess;
+    /** Stable route name, such as `runs.signal` or `effects.retry`. */
+    readonly name: string;
+    readonly runId?: string;
+}
+export type AuthDecision = {
+    readonly allowed: true;
+} | {
+    readonly allowed: false;
+    readonly status: number;
+    readonly error: string;
+};
+export type Authorize = (request: Request, route: RouteInfo) => Effect.Effect<AuthDecision>;
+export declare const authAllowed: AuthDecision;
+export declare function authDenied(status: number, error: string): AuthDecision;
+export declare function authResponse(decision: AuthDecision): Response | null;
+/**
+ * Used when a host supplies no `authorize`: run reads and writes stay open, while worker callbacks
+ * and operational endpoints are unavailable until a host opts in.
+ */
+export declare const defaultAuthorize: Authorize;
+export interface BearerTokens {
+    readonly read?: string;
+    readonly write?: string;
+    readonly worker?: string;
+    readonly operations?: string;
+}
+/**
+ * Requires `Authorization: Bearer <token>` for every access level that has a token. Levels without
+ * a token keep the default behavior: reads and writes are open, worker and operations routes 503.
+ */
+export declare function bearerAuth(tokens: BearerTokens): Authorize;

package/dist/runtime/server/auth.js

@@ -0,0 +1,45 @@
+import { Effect } from 'effect';
+export const authAllowed = { allowed: true };
+export function authDenied(status, error) {
+    return { allowed: false, status, error };
+}
+export function authResponse(decision) {
+    return decision.allowed
+        ? null
+        : Response.json({ error: decision.error }, { status: decision.status });
+}
+const unauthorized = authDenied(401, 'Unauthorized');
+function notConfigured(access) {
+    return authDenied(503, access === 'worker'
+        ? 'Worker callbacks are not configured'
+        : 'Operational endpoints are not configured');
+}
+/**
+ * Used when a host supplies no `authorize`: run reads and writes stay open, while worker callbacks
+ * and operational endpoints are unavailable until a host opts in.
+ */
+export const defaultAuthorize = (_request, route) => Effect.succeed(route.access === 'worker' || route.access === 'operations'
+    ? notConfigured(route.access)
+    : authAllowed);
+function constantTimeEquals(actual, expected) {
+    const length = Math.max(actual.length, expected.length);
+    let difference = actual.length ^ expected.length;
+    for (let index = 0; index < length; index += 1) {
+        difference |= (actual.charCodeAt(index) || 0) ^ (expected.charCodeAt(index) || 0);
+    }
+    return difference === 0;
+}
+/**
+ * Requires `Authorization: Bearer <token>` for every access level that has a token. Levels without
+ * a token keep the default behavior: reads and writes are open, worker and operations routes 503.
+ */
+export function bearerAuth(tokens) {
+    return (request, route) => {
+        const token = tokens[route.access];
+        if (token === undefined) {
+            return defaultAuthorize(request, route);
+        }
+        const header = request.headers.get('authorization') ?? '';
+        return Effect.succeed(constantTimeEquals(header, `Bearer ${token}`) ? authAllowed : unauthorized);
+    };
+}

package/dist/runtime/server/debugger-host.d.ts

@@ -0,0 +1,11 @@
+import { Effect } from 'effect';
+import type { DebuggerHost } from '@swirls/looms/core';
+import { type Authorize } from './auth';
+export interface DebuggerMount {
+    readonly basePath: string;
+    readonly host: DebuggerHost;
+}
+export declare function mountDebugger(host: DebuggerHost): DebuggerMount;
+/** Path below the mount, or null when `pathname` is outside it. */
+export declare function debuggerPath(mount: DebuggerMount, pathname: string): string | null;
+export declare function serveDebugger(req: Request, mount: DebuggerMount, path: string, authorize: Authorize): Effect.Effect<Response | null>;

package/dist/runtime/server/debugger-host.js

@@ -0,0 +1,32 @@
+import { Effect } from 'effect';
+import { authResponse } from './auth.js';
+import { isLoomsApiPath } from './http.js';
+export function mountDebugger(host) {
+    const path = host.basePath;
+    if (!path.startsWith('/') || path.includes('//') || path.split('/').includes('..')) {
+        throw new Error(`debugger basePath must be an absolute URL path: ${path}`);
+    }
+    const basePath = path.endsWith('/') ? path.slice(0, -1) : path;
+    if (basePath === '') {
+        throw new Error('debugger basePath must not be /');
+    }
+    if (isLoomsApiPath(basePath)) {
+        throw new Error(`debugger basePath overlaps the HTTP API: ${basePath}`);
+    }
+    return { basePath, host };
+}
+/** Path below the mount, or null when `pathname` is outside it. */
+export function debuggerPath(mount, pathname) {
+    if (pathname === mount.basePath) {
+        return '';
+    }
+    return pathname.startsWith(`${mount.basePath}/`) ? pathname.slice(mount.basePath.length) : null;
+}
+export function serveDebugger(req, mount, path, authorize) {
+    return authorize(req, { access: 'read', name: 'debugger' }).pipe(Effect.flatMap((decision) => {
+        const denied = authResponse(decision);
+        return denied
+            ? Effect.succeed(denied)
+            : Effect.promise(() => mount.host.fetch(req, { basePath: mount.basePath, path }));
+    }));
+}

package/dist/runtime/server/fetch-handler.d.ts

@@ -0,0 +1,18 @@
+import type { EventStore } from '@swirls/looms/core';
+import type { LoomsRuntime } from '../runtime';
+import { type Authorize } from './auth';
+import { type DebuggerMount } from './debugger-host';
+export interface FetchHandlerOptions {
+    readonly runtime: LoomsRuntime;
+    readonly store: EventStore;
+    /**
+     * Decides whether a request may use a route. Defaults to open reads and writes with worker and
+     * operations routes unavailable; use `bearerAuth` or your own policy to change that.
+     */
+    readonly authorize?: Authorize;
+    /** Debugger UI served beside the API and authorized as `{ access: 'read', name: 'debugger' }`. */
+    readonly debugger?: DebuggerMount;
+}
+/** Whether the fetch handler answers `pathname`: the HTTP API or the debugger mount. */
+export declare function handlesPath(pathname: string, mount: DebuggerMount | undefined): boolean;
+export declare function createFetchHandler(options: FetchHandlerOptions): (req: Request) => Promise<Response | null>;

package/dist/runtime/server/fetch-handler.js

@@ -0,0 +1,62 @@
+import { Effect, Predicate } from 'effect';
+import { authResponse, defaultAuthorize } from './auth.js';
+import { debuggerPath, serveDebugger } from './debugger-host.js';
+import { acceptsEventStream, isLoomsApiPath, toErrorResponse } from './http.js';
+import { matchRoute } from './route-table.js';
+import { definitionRoutes } from './routes/definitions.js';
+import { effectRoutes } from './routes/effects.js';
+import { operationRoutes } from './routes/operations.js';
+import { runRoutes } from './routes/runs.js';
+function createRoutes(options) {
+    return [
+        ...definitionRoutes(options),
+        ...runRoutes(options),
+        ...effectRoutes(options),
+        ...operationRoutes(options),
+    ];
+}
+function authorizeRoute(req, matched, authorize) {
+    const { access, name } = matched.route;
+    if (access === 'public') {
+        return Effect.succeed(null);
+    }
+    const runId = matched.params.runId;
+    return authorize(req, Predicate.isString(runId) ? { access, name, runId } : { access, name }).pipe(Effect.map(authResponse));
+}
+/** Whether the fetch handler answers `pathname`: the HTTP API or the debugger mount. */
+export function handlesPath(pathname, mount) {
+    return isLoomsApiPath(pathname) || (mount !== undefined && debuggerPath(mount, pathname) !== null);
+}
+export function createFetchHandler(options) {
+    const routes = createRoutes(options);
+    const authorize = options.authorize ?? defaultAuthorize;
+    const mount = options.debugger;
+    return (req) => {
+        const url = new URL(req.url);
+        const mountedPath = mount ? debuggerPath(mount, url.pathname) : null;
+        if (mount && mountedPath !== null) {
+            return respond(serveDebugger(req, mount, mountedPath, authorize));
+        }
+        if (!isLoomsApiPath(url.pathname)) {
+            return Promise.resolve(null);
+        }
+        const accept = req.headers.get('accept') ?? '';
+        if (req.method === 'GET' && accept.includes('text/html') && !acceptsEventStream(req)) {
+            return Promise.resolve(null);
+        }
+        return respond(Effect.gen(function* () {
+            const matched = matchRoute(routes, req.method, url.pathname);
+            if (!matched) {
+                return new Response('Not Found', { status: 404 });
+            }
+            const denied = yield* authorizeRoute(req, matched, authorize);
+            if (denied) {
+                return denied;
+            }
+            return yield* matched.route.handle({ req, url, params: matched.params });
+        }));
+    };
+}
+function respond(effect) {
+    return Effect.runPromise(effect.pipe(Effect.catch((error) => Effect.succeed(toErrorResponse(error))), Effect.catchCause((cause) => Effect.logError('[@swirls/looms/runtime] request failed', cause).pipe(Effect.as(Response.json({ error: 'Internal server error' }, { status: 500 }))))));
+}

package/dist/runtime/server/http.d.ts

@@ -0,0 +1,38 @@
+import { Effect, Schema } from 'effect';
+import { EventStoreTag, type EventStore, type JsonValue } from '@swirls/looms/core';
+import { type LoomsRuntime } from '../runtime';
+export interface RouteOptions {
+    readonly runtime: LoomsRuntime;
+    readonly store: EventStore;
+}
+declare const RequestBodyError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "RequestBodyError";
+} & Readonly<A>;
+export declare class RequestBodyError extends RequestBodyError_base<{
+    readonly cause: unknown;
+    readonly message: string;
+}> {
+    constructor(cause: unknown);
+}
+declare const RequestQueryError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "RequestQueryError";
+} & Readonly<A>;
+export declare class RequestQueryError extends RequestQueryError_base<{
+    readonly message: string;
+}> {
+}
+export declare const EventInputBodySchema: Schema.Struct<{
+    readonly type: Schema.String;
+    readonly payload: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly threadId: Schema.optional<Schema.NullOr<Schema.String>>;
+}>;
+export declare function isLoomsApiPath(path: string): boolean;
+export declare function provideStore<A, E>(effect: Effect.Effect<A, E, EventStoreTag>, store: EventStore): Effect.Effect<A, E>;
+export declare const readJson: (req: Request) => Effect.Effect<JsonValue, RequestBodyError>;
+export declare function extractIdempotencyKey(req: Request, bodyKey?: string): string | undefined;
+export declare function acceptsEventStream(req: Request): boolean;
+export declare function readIntegerQuery(url: URL, name: string, options: {
+    minimum: number;
+}): Effect.Effect<number | null, RequestQueryError>;
+export declare function toErrorResponse(err: Error): Response;
+export {};

package/dist/runtime/server/http.js

@@ -0,0 +1,66 @@
+import { Data, Effect, Schema } from 'effect';
+import { EventStoreTag, InvalidEventError, InvalidInputError, JsonValueSchema, } from '@swirls/looms/core';
+import { RunOverloadedError, StartRunConflictError } from '../runtime.js';
+export class RequestBodyError extends Data.TaggedError('RequestBodyError') {
+    constructor(cause) {
+        super({ cause, message: 'Invalid JSON request body' });
+        this.name = 'RequestBodyError';
+    }
+}
+export class RequestQueryError extends Data.TaggedError('RequestQueryError') {
+}
+export const EventInputBodySchema = Schema.Struct({
+    type: Schema.String,
+    payload: JsonValueSchema,
+    threadId: Schema.optional(Schema.NullOr(Schema.String)),
+});
+const LOOMS_API_ROOTS = ['/health', '/runs', '/definitions', '/operations'];
+export function isLoomsApiPath(path) {
+    return LOOMS_API_ROOTS.some((root) => path === root || path.startsWith(`${root}/`));
+}
+export function provideStore(effect, store) {
+    return Effect.provideService(effect, EventStoreTag, store);
+}
+export const readJson = (req) => Effect.tryPromise({
+    try: () => req.json(),
+    catch: (cause) => new RequestBodyError(cause),
+}).pipe(Effect.flatMap(Schema.decodeUnknownEffect(JsonValueSchema)), Effect.mapError((cause) => cause instanceof RequestBodyError ? cause : new RequestBodyError(cause)));
+export function extractIdempotencyKey(req, bodyKey) {
+    return (bodyKey ??
+        req.headers.get('idempotency-key') ??
+        req.headers.get('x-idempotency-key') ??
+        undefined);
+}
+export function acceptsEventStream(req) {
+    return (req.headers.get('accept') ?? '')
+        .split(',')
+        .some((value) => value.split(';', 1)[0]?.trim().toLowerCase() === 'text/event-stream');
+}
+export function readIntegerQuery(url, name, options) {
+    const raw = url.searchParams.get(name);
+    if (raw === null) {
+        return Effect.succeed(null);
+    }
+    const value = Number(raw);
+    if (!Number.isSafeInteger(value) || value < options.minimum || raw.trim() === '') {
+        return Effect.fail(new RequestQueryError({
+            message: `${name} must be an integer greater than or equal to ${options.minimum}`,
+        }));
+    }
+    return Effect.succeed(value);
+}
+export function toErrorResponse(err) {
+    if (err instanceof RequestBodyError || err instanceof RequestQueryError) {
+        return Response.json({ error: err.message }, { status: 400 });
+    }
+    if (err instanceof InvalidInputError || err instanceof InvalidEventError) {
+        return Response.json({ error: err.message, issues: err.issues }, { status: 400 });
+    }
+    if (err instanceof RunOverloadedError) {
+        return Response.json({ error: err.message }, { status: 429 });
+    }
+    if (err instanceof StartRunConflictError) {
+        return Response.json({ error: err.message, mismatches: err.mismatches }, { status: 409 });
+    }
+    return Response.json({ error: err.message }, { status: 500 });
+}

package/dist/runtime/server/route-table.d.ts

@@ -0,0 +1,55 @@
+import type { Effect } from 'effect';
+import type { RouteAccess } from './auth';
+export type ParamValue = string | number;
+/** Decodes one path segment, or returns null when the segment does not match. */
+export interface ParamDecoder<T extends ParamValue> {
+    decode(raw: string): T | null;
+}
+export declare const text: ParamDecoder<string>;
+export declare const integer: ParamDecoder<number>;
+export declare function oneOf<const T extends string>(values: readonly T[]): ParamDecoder<T>;
+type PathParamNames<TPath extends string> = TPath extends `${string}:${infer Param}/${infer Rest}` ? Param | PathParamNames<`/${Rest}`> : TPath extends `${string}:${infer Param}` ? Param : never;
+type ParamDecoders<TPath extends string> = {
+    readonly [K in PathParamNames<TPath>]?: ParamDecoder<ParamValue>;
+};
+type DecodedParams<TPath extends string, TDecoders> = {
+    readonly [K in PathParamNames<TPath>]: K extends keyof TDecoders ? TDecoders[K] extends ParamDecoder<infer T> ? T : string : string;
+};
+export interface RouteContext<TParams> {
+    readonly req: Request;
+    readonly url: URL;
+    readonly params: TParams;
+}
+export interface RouteDefinition<TPath extends string, TDecoders extends ParamDecoders<TPath>> {
+    readonly method: 'GET' | 'POST';
+    /** Path pattern such as `/runs/:runId/effects/:effectId`; parameters decode as text by default. */
+    readonly path: TPath;
+    readonly name: string;
+    readonly access: RouteAccess;
+    readonly params?: TDecoders;
+    handle(context: RouteContext<DecodedParams<TPath, TDecoders>>): Effect.Effect<Response, Error>;
+}
+type Segment = {
+    readonly kind: 'literal';
+    readonly value: string;
+} | {
+    readonly kind: 'param';
+    readonly name: string;
+    readonly decoder: ParamDecoder<ParamValue>;
+};
+export type RouteParams = Readonly<Record<string, ParamValue>>;
+export interface Route {
+    readonly method: 'GET' | 'POST';
+    readonly name: string;
+    readonly access: RouteAccess;
+    readonly segments: readonly Segment[];
+    handle(context: RouteContext<RouteParams>): Effect.Effect<Response, Error>;
+}
+export declare function route<const TPath extends string, const TDecoders extends ParamDecoders<TPath> = Record<never, never>>(definition: RouteDefinition<TPath, TDecoders>): Route;
+export interface MatchedRoute {
+    readonly route: Route;
+    readonly params: RouteParams;
+}
+/** First route, in table order, whose method and path match. */
+export declare function matchRoute(routes: readonly Route[], method: string, pathname: string): MatchedRoute | null;
+export {};

package/dist/runtime/server/route-table.js

@@ -0,0 +1,74 @@
+export const text = {
+    decode: (raw) => {
+        try {
+            return decodeURIComponent(raw);
+        }
+        catch {
+            return null;
+        }
+    },
+};
+export const integer = {
+    decode: (raw) => (/^\d+$/.test(raw) ? Number(raw) : null),
+};
+export function oneOf(values) {
+    return { decode: (raw) => values.find((value) => value === raw) ?? null };
+}
+export function route(definition) {
+    const decoders = definition.params ?? {};
+    const segments = definition.path
+        .split('/')
+        .slice(1)
+        .map((part) => {
+        if (!part.startsWith(':')) {
+            return { kind: 'literal', value: part };
+        }
+        const name = part.slice(1);
+        return { kind: 'param', name, decoder: decoders[name] ?? text };
+    });
+    // SAFETY: matchRoute only calls a route with every path parameter decoded by its decoders.
+    return {
+        method: definition.method,
+        name: definition.name,
+        access: definition.access,
+        segments,
+        handle: (context) => 
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+        definition.handle(context),
+    };
+}
+function matchSegments(segments, parts) {
+    if (segments.length !== parts.length) {
+        return null;
+    }
+    const params = {};
+    for (const [index, segment] of segments.entries()) {
+        const part = parts[index];
+        if (segment.kind === 'literal') {
+            if (segment.value !== part) {
+                return null;
+            }
+            continue;
+        }
+        const value = segment.decoder.decode(part);
+        if (value === null) {
+            return null;
+        }
+        params[segment.name] = value;
+    }
+    return params;
+}
+/** First route, in table order, whose method and path match. */
+export function matchRoute(routes, method, pathname) {
+    const parts = pathname.split('/').slice(1);
+    for (const candidate of routes) {
+        if (candidate.method !== method) {
+            continue;
+        }
+        const params = matchSegments(candidate.segments, parts);
+        if (params) {
+            return { route: candidate, params };
+        }
+    }
+    return null;
+}

package/dist/runtime/server/routes/definitions.d.ts

@@ -0,0 +1,3 @@
+import type { RouteOptions } from '../http';
+import { type Route } from '../route-table';
+export declare function definitionRoutes({ runtime }: RouteOptions): readonly Route[];

package/dist/runtime/server/routes/definitions.js

@@ -0,0 +1,20 @@
+import { Effect } from 'effect';
+import { publishDefinition } from '@swirls/looms/core';
+import { route } from '../route-table.js';
+export function definitionRoutes({ runtime }) {
+    return [
+        route({
+            method: 'GET',
+            path: '/definitions',
+            name: 'definitions.list',
+            access: 'read',
+            handle: () => {
+                const catalog = {
+                    definitions: runtime.registry.definitions.map(publishDefinition),
+                    projections: [...runtime.registry.projections.keys()],
+                };
+                return Effect.succeed(Response.json(catalog));
+            },
+        }),
+    ];
+}

package/dist/runtime/server/routes/effects.d.ts

@@ -0,0 +1,3 @@
+import { type RouteOptions } from '../http';
+import { type Route } from '../route-table';
+export declare function effectRoutes({ runtime, store }: RouteOptions): readonly Route[];

package/dist/runtime/server/routes/effects.js

@@ -0,0 +1,59 @@
+import { Effect, Schema } from 'effect';
+import { EventInputBodySchema, provideStore, readJson } from '../http.js';
+import { integer, oneOf, route } from '../route-table.js';
+const WORKER_CALLBACK_KINDS = [
+    'started',
+    'heartbeat',
+    'complete',
+    'fail',
+    'cancelled',
+];
+const WorkerCallbackBodySchema = Schema.Struct({
+    events: Schema.optional(Schema.Array(EventInputBodySchema)),
+    error: Schema.optional(Schema.String),
+});
+function workerCallbackInput(params, body) {
+    const callback = { effectId: params.effectId, attempt: params.attempt };
+    switch (params.action) {
+        case 'complete':
+            return { ...callback, kind: 'complete', events: body.events ?? [] };
+        case 'fail':
+            return body.error ? { ...callback, kind: 'fail', error: body.error } : null;
+        default:
+            return { ...callback, kind: params.action };
+    }
+}
+export function effectRoutes({ runtime, store }) {
+    return [
+        route({
+            method: 'GET',
+            path: '/runs/:runId/effects',
+            name: 'effects.list',
+            access: 'read',
+            handle: ({ params }) => provideStore(runtime.inspectRun(params.runId), store).pipe(Effect.map((status) => Response.json({ runId: params.runId, effects: status.effects }))),
+        }),
+        route({
+            method: 'POST',
+            path: '/runs/:runId/effects/:effectId/retry',
+            name: 'effects.retry',
+            access: 'operations',
+            handle: ({ params }) => provideStore(runtime.retryEffect(params.runId, params.effectId), store).pipe(Effect.map((state) => Response.json({ runId: params.runId, effectId: params.effectId, state }))),
+        }),
+        route({
+            method: 'POST',
+            path: '/runs/:runId/effects/:effectId/:attempt/:action',
+            name: 'effects.workerCallback',
+            access: 'worker',
+            params: { attempt: integer, action: oneOf(WORKER_CALLBACK_KINDS) },
+            handle: ({ req, params }) => Effect.gen(function* () {
+                const body = yield* readJson(req).pipe(Effect.flatMap(Schema.decodeUnknownEffect(WorkerCallbackBodySchema)));
+                const input = workerCallbackInput(params, body);
+                if (!input) {
+                    return Response.json({ error: 'error required' }, { status: 400 });
+                }
+                const state = yield* provideStore(runtime.workerCallback(params.runId, input), store);
+                return Response.json({ runId: params.runId, state });
+            }),
+        }),
+    ];
+}

package/dist/runtime/server/routes/operations.d.ts

@@ -0,0 +1,3 @@
+import { type RouteOptions } from '../http';
+import { type Route } from '../route-table';
+export declare function operationRoutes({ runtime, store }: RouteOptions): readonly Route[];

package/dist/runtime/server/routes/operations.js

@@ -0,0 +1,14 @@
+import { Effect } from 'effect';
+import { provideStore } from '../http.js';
+import { route } from '../route-table.js';
+export function operationRoutes({ runtime, store }) {
+    return [
+        route({
+            method: 'POST',
+            path: '/operations/deadlines/rescan',
+            name: 'operations.rescanDeadlines',
+            access: 'operations',
+            handle: () => provideStore(runtime.recoverDeadlines, store).pipe(Effect.map((scheduled) => Response.json({ scheduled }))),
+        }),
+    ];
+}

package/dist/runtime/server/routes/runs.d.ts

@@ -0,0 +1,3 @@
+import { type RouteOptions } from '../http';
+import { type Route } from '../route-table';
+export declare function runRoutes({ runtime, store }: RouteOptions): readonly Route[];