@rikalabs/akter 0.1.0-alpha.0

package/dist/actor/turns.js

@@ -0,0 +1,332 @@
+import { Context, DateTime, Duration, Effect, Fiber, Option, Result, Schema } from "effect";
+import { InsideTurn } from "../contexts/command.js";
+import { Due, emptyOutbox, InTurn, jobKey, openOutbox } from "../handles/intents.js";
+import { ActorRef, principal } from "../identity/caller.js";
+import { childId } from "../identity/child.js";
+import { isCursor } from "../runtime/events/cursor.js";
+import { Outcome } from "../runtime/request.js";
+import { broadcastsTo } from "./connections.js";
+import { descriptorOf } from "./descriptor.js";
+const utf8 = new TextEncoder();
+/**
+ * Encoded bytes of every event one turn may emit. The turn appends them in
+ * one statement inside its transaction, so the budget bounds that statement.
+ */
+const MAX_EMIT_BYTES = 1_048_576;
+/** When and under which key `turn.enqueue` stages a job. */
+const enqueueSchedule = (options) => {
+    if (options?.key !== undefined)
+        jobKey(options.key);
+    if (options?.after !== undefined && options.at !== undefined)
+        throw new Error("turn.enqueue takes after or at, not both");
+    let due;
+    if (options?.after !== undefined) {
+        const millis = Duration.toMillis(Duration.fromInputUnsafe(options.after));
+        if (!Number.isFinite(millis) || millis < 0)
+            throw new Error("turn.enqueue after needs a finite, non-negative duration");
+        due = Due.cases.After.make({ millis: Math.ceil(millis) });
+    }
+    if (options?.at !== undefined)
+        due = Due.cases.At.make({ epochMillis: DateTime.toEpochMillis(options.at) });
+    return { due, key: options?.key };
+};
+/** A declared failure as the turn's failure outcome; any other error is a defect. */
+const declaredFailure = Effect.fnUntraced(function* ({ isError, encodeError }, error) {
+    if (!isError(error))
+        return yield* Effect.die(error);
+    const value = yield* encodeError(error).pipe(Effect.orDie);
+    return yield* Effect.fail({
+        outcome: Outcome.cases.Failure.make({ value }),
+        state: [],
+        complete: false,
+        events: [],
+        outbox: emptyOutbox,
+    });
+});
+/** Job tags each actor type has already warned about, so each warns once per process. */
+const warned = new WeakMap();
+/**
+ * Logs once per job tag that a keyed job routes neither cancellation nor dead
+ * letters, since an ambiguous cancellation is then only dead-lettered.
+ */
+const warnUnrouted = (descriptor, tag) => Effect.suspend(() => {
+    const policy = descriptor.jobs.get(tag).policy;
+    const tags = warned.get(descriptor) ?? new Set();
+    if (tags.has(tag) || policy.onCancelled !== undefined || policy.onDeadLetter !== undefined)
+        return Effect.void;
+    warned.set(descriptor, tags.add(tag));
+    return Effect.logWarning(`Keyed job ${tag} has neither onCancelled nor onDeadLetter; an ambiguous cancellation is only dead-lettered`);
+});
+/**
+ * One command member's turn. Its capabilities die once the handler returns
+ * and when used from a fiber other than the handler's, because the turn's one
+ * connection takes no concurrent statements; forked fibers inherit
+ * `InsideTurn`, so the owning fiber is compared as well and a misuse is
+ * recorded so a swallowed defect still fails the turn. The turn's services are
+ * provided as one merged context, since each nested provide copies it.
+ */
+const commandTurn = (descriptor, Turn, handle, codecs, services, actors) => Effect.fnUntraced(function* (request, rows, { head, connections: listConnections, }) {
+    const { name, fields } = descriptor;
+    let open = true;
+    const broadcasts = [];
+    const turn = Symbol();
+    const dirty = new Set();
+    const emitted = [];
+    let emittedBytes = 0;
+    const loaded = yield* descriptor.state.decodeStored(rows);
+    let current = loaded.state;
+    if (loaded.upcast)
+        for (const key of Object.keys(fields))
+            dirty.add(key);
+    const set = Effect.fnUntraced(function* (patch) {
+        if (!open || (yield* InsideTurn) !== turn)
+            return yield* Effect.die(new Error("State capability escaped its turn"));
+        for (const key of Object.keys(patch)) {
+            if (!(key in fields))
+                return yield* Effect.die(new Error(`Undeclared state key: ${key}`));
+            dirty.add(key);
+        }
+        current = yield* descriptor.state.roundTrip({ ...current, ...patch });
+    });
+    const emit = Effect.fnUntraced(function* (event) {
+        if (!open || (yield* InsideTurn) !== turn)
+            return yield* Effect.die(new Error("Event capability escaped its turn"));
+        const declared = descriptor.events.get(event._tag);
+        if (declared === undefined || !Schema.is(declared)(event))
+            return yield* Effect.die(new Error(`Undeclared event: ${event._tag}`));
+        const { value, version } = yield* descriptor.eventCodecs
+            .get(declared.identifier)
+            .encode(event)
+            .pipe(Effect.orDie);
+        emittedBytes += utf8.encode(value).byteLength;
+        if (emittedBytes > MAX_EMIT_BYTES)
+            return yield* Effect.die(new Error(`Events emitted in one turn exceed ${MAX_EMIT_BYTES} bytes`));
+        emitted.push({ tag: declared.identifier, value, version });
+    });
+    const view = { set };
+    const owner = Fiber.getCurrent();
+    let misused;
+    const escaped = (capability) => Effect.gen(function* () {
+        if (!open || (yield* InsideTurn) !== turn)
+            return yield* Effect.die(new Error(`${capability} capability escaped its turn`));
+        if (Fiber.getCurrent() !== owner) {
+            misused = `${capability} capability used from a fiber other than its turn's; timeout, race, and concurrent combinators run on other fibers`;
+            return yield* Effect.die(new Error(misused));
+        }
+    });
+    const wroteTables = new Set();
+    const wroteBlobs = new Set();
+    const bindings = yield* Effect.context();
+    let tables;
+    let blobs;
+    /**
+     * Binds the turn's owned tables on first use, in the context the turn
+     * started with. Most turns touch no table, and binding builds the
+     * actor's row predicates.
+     */
+    const tableAccess = () => (tables ??= Effect.runSyncWith(bindings)(actors.tables({
+        ref: request.ref,
+        placement: descriptor.placement,
+        tables: descriptor.tables,
+        guard: escaped("Table"),
+        wrote: (table) => wroteTables.add(table),
+    }, true)));
+    /** Binds the turn's blobs on first use, like `tableAccess`. */
+    const blobAccess = () => (blobs ??= Effect.runSyncWith(bindings)(actors.blobs({
+        ref: request.ref,
+        placement: descriptor.placement,
+        blobs: descriptor.blobs,
+        guard: escaped("Blob"),
+        wrote: (blobName) => wroteBlobs.add(blobName),
+        maxBytes: descriptor.policy.blobMaxBytes,
+        maxEntries: descriptor.policy.blobMaxEntries,
+        timeoutMs: descriptor.policy.executionMs,
+    }, true)));
+    for (const key of Object.keys(fields))
+        Object.defineProperty(view, key, { enumerable: true, get: () => current[key] });
+    const outbox = openOutbox({
+        sender: request.ref,
+        commandId: request.commandId,
+        head,
+        onBehalfOf: Option.getOrUndefined(principal(request.caller)),
+    });
+    const mint = Effect.fnUntraced(function* (child) {
+        yield* escaped("Mint");
+        const target = descriptorOf(child);
+        if (target === undefined || !target.mintable)
+            return yield* Effect.die(new Error("turn.mint needs an unkeyed actor that declares createdBy"));
+        if (target.parent !== undefined && target.parent.name !== name)
+            return yield* Effect.die(new Error(`turn.mint(${target.name}) needs a turn of its parent ${target.parent.name}`));
+        const proof = outbox.nextMint();
+        const minted = yield* actors.mintChildId({
+            parent: descriptor.singleton ? { ...request.ref, id: "" } : request.ref,
+            commandId: request.commandId,
+            ordinal: proof.ordinal,
+            child: target.name,
+        });
+        const id = target.parent === undefined ? minted : childId({ parent: request.ref.id, local: minted });
+        outbox.minted(ActorRef.make({ tenant: request.ref.tenant, actor: target.name, id }), target.policy.createdBy, proof);
+        return id;
+    });
+    const enqueue = Effect.fnUntraced(function* (instance, options) {
+        if (!open || (yield* InsideTurn) !== turn)
+            return yield* Effect.die(new Error("Job capability escaped its turn"));
+        const declared = descriptor.jobs.get(instance._tag);
+        if (declared === undefined)
+            return yield* Effect.die(new Error(`Unbound job: ${instance._tag}`));
+        const scheduled = yield* Effect.sync(() => enqueueSchedule(options));
+        if (scheduled.key !== undefined)
+            yield* warnUnrouted(descriptor, instance._tag);
+        const { value, version } = yield* declared.codec.encode(instance).pipe(Effect.orDie);
+        outbox.enqueue({
+            job: instance._tag,
+            payload: value,
+            version,
+            capped: declared.policy.perActor !== undefined,
+            ...scheduled,
+        });
+    });
+    const changeSubscription = (op) => Effect.fnUntraced(function* (declared, id, options) {
+        yield* escaped("Subscription");
+        if (!descriptor.subscriptions.includes(declared) || declared.route !== undefined)
+            return yield* Effect.die(new Error(`${declared.tag} is not a dynamic subscription of ${name}`));
+        const source = descriptorOf(declared.source);
+        const from = options?.from ?? "now";
+        if (from !== "now" && from !== "start" && !isCursor(from))
+            return yield* Effect.die(new Error(`subscribe from is "now", "start", or a cursor, not ${from}`));
+        outbox.subscribe({
+            subscription: declared.tag,
+            source: ActorRef.make({
+                tenant: request.ref.tenant,
+                actor: declared.source.name,
+                id: yield* source.decodeId(id).pipe(Effect.orDie),
+            }),
+            op,
+            from,
+            events: declared.events.map((event) => event.identifier),
+        });
+    });
+    const cancelJob = Effect.fnUntraced(function* (key) {
+        if (!open || (yield* InsideTurn) !== turn)
+            return yield* Effect.die(new Error("Job capability escaped its turn"));
+        yield* Effect.sync(() => jobKey(key));
+        outbox.cancelJob(key);
+    });
+    const context = {
+        id: request.ref.id,
+        ref: request.ref,
+        caller: request.caller,
+        principal: principal(request.caller),
+        commandId: request.commandId,
+        state: Object.freeze(view),
+        emit,
+        rows: (table) => tableAccess().rows(table),
+        group: ((build) => Effect.suspend(() => tableAccess().group(build))),
+        blob: (declared) => blobAccess()(declared),
+        mint,
+        enqueue,
+        cancelJob,
+        broadcast: broadcastsTo({ descriptor, broadcasts, guard: escaped }),
+        subscribe: changeSubscription("subscribe"),
+        unsubscribe: (declared, id) => changeSubscription("remove")(declared, id),
+        connections: (member) => Effect.gen(function* () {
+            yield* escaped("Connections");
+            if (listConnections === undefined)
+                return [];
+            return (yield* listConnections(member.tag)).map(({ connectionId, caller }) => ({
+                connectionId,
+                caller,
+            }));
+        }),
+    };
+    return yield* Effect.gen(function* () {
+        const input = yield* codecs.decodePayload(request.payload).pipe(Effect.orDie);
+        const output = yield* handle(input.value);
+        if (misused !== undefined)
+            return yield* Effect.die(new Error(misused));
+        const uncreated = outbox.uncreated();
+        if (uncreated !== undefined)
+            return yield* Effect.die(new Error(`Minted actor ${uncreated.actor}/${uncreated.id} has no creating intent`));
+        const keyed = outbox.keyedCreation();
+        if (keyed !== undefined)
+            return yield* Effect.die(new Error(`Minted actor ${keyed.actor}/${keyed.id} has a keyed creating intent`));
+        const value = yield* codecs.encodeSuccess({ value: output }).pipe(Effect.orDie);
+        return {
+            outcome: Outcome.cases.Success.make({ value }),
+            state: yield* descriptor.state.writes(current, dirty),
+            complete: loaded.upcast,
+            events: emitted,
+            outbox: outbox.close(),
+            broadcasts,
+            writes: { tables: [...wroteTables], blobs: [...wroteBlobs] },
+        };
+    }).pipe(Effect.catch((error) => declaredFailure(codecs, error)), Effect.ensuring(Effect.sync(() => {
+        open = false;
+        outbox.close();
+    })), Effect.provideContext(services.pipe(Context.add(InsideTurn, turn), Context.add(InTurn, outbox.marker), Context.add(Turn, context))));
+});
+/**
+ * A reducer's turns. `reduce` receives its own decoded copy of state, so
+ * mutating it in place cannot hide a change, and its result round-trips
+ * through the state schema. A batched reducer's queued inputs are combined in
+ * order and reduced once; it declares no errors, so a combined turn fails only
+ * by defect.
+ */
+const reducerTurns = (descriptor, reducer) => {
+    const codecs = descriptor.codecs.get(reducer.tag);
+    const reduceOnce = Effect.fnUntraced(function* (rows, input) {
+        const loaded = yield* descriptor.state.decodeStored(rows);
+        const given = yield* descriptor.state.roundTrip(loaded.state);
+        const reduced = reducer.reduce(given, input);
+        if (Result.isFailure(reduced))
+            return yield* declaredFailure(codecs, reduced.failure);
+        const next = yield* descriptor.state.roundTrip(reduced.success);
+        const dirty = new Set(Object.keys(descriptor.fields).filter((key) => loaded.upcast || !descriptor.state.equivalences[key](loaded.state[key], next[key])));
+        const value = yield* codecs
+            .encodeSuccess({ value: reducer.batch === undefined ? next : undefined })
+            .pipe(Effect.orDie);
+        return {
+            outcome: Outcome.cases.Success.make({ value }),
+            state: yield* descriptor.state.writes(next, dirty),
+            complete: loaded.upcast,
+            events: [],
+            outbox: emptyOutbox,
+        };
+    });
+    const decodePayload = (request) => codecs.decodePayload(request.payload).pipe(Effect.orDie, Effect.map((input) => input.value));
+    const single = {
+        internal: false,
+        handler: false,
+        run: Effect.fnUntraced(function* (request, rows) {
+            return yield* reduceOnce(rows, yield* decodePayload(request));
+        }),
+    };
+    const batch = reducer.batch;
+    if (batch === undefined)
+        return single;
+    return {
+        ...single,
+        merge: Effect.fnUntraced(function* (requests, rows) {
+            const inputs = yield* Effect.forEach(requests, decodePayload);
+            const combined = inputs.reduce((first, second) => batch.combine(first, second));
+            return yield* reduceOnce(rows, combined).pipe(Effect.catch(() => Effect.die(new Error(`Batched reducer ${reducer.tag} failed`))));
+        }),
+    };
+};
+/** Every command and reducer turn of one activation, keyed by tag. */
+export const turnsOf = ({ descriptor, Turn, handlers, services, actors, }) => Effect.gen(function* () {
+    const commands = new Map();
+    for (const member of descriptor.commands) {
+        const handle = handlers[member.tag];
+        if (handle === undefined)
+            return yield* Effect.die(new Error(`Missing handler ${member.tag}`));
+        commands.set(member.tag, {
+            internal: descriptor.internalMembers.has(member),
+            handler: descriptor.handlerTags.has(member.tag),
+            run: commandTurn(descriptor, Turn, handle, descriptor.codecs.get(member.tag), services, actors),
+        });
+    }
+    for (const reducer of descriptor.reducers)
+        commands.set(reducer.tag, reducerTurns(descriptor, reducer));
+    return commands;
+});

package/dist/actor/workflows.d.ts

@@ -0,0 +1,16 @@
+import { Context, Effect } from "effect";
+import type { RegisteredWorkflow } from "../runtime/members.ts";
+import type { Handler } from "./codecs.ts";
+import type { Descriptor } from "./descriptor.ts";
+/**
+ * Every workflow's body. A body runs outside turns with the layer's context
+ * minus its `Scope`, since a body's scope is its run's, and calls as the
+ * execution's recorded principal through a `System({ source: "workflow" })`
+ * caller.
+ */
+export declare const workflowsOf: ({ descriptor, Workflow, bodies, services, }: {
+    readonly descriptor: Descriptor;
+    readonly Workflow: Context.Key<object, object>;
+    readonly bodies: Readonly<Record<string, Handler>>;
+    readonly services: Context.Context<never>;
+}) => Effect.Effect<ReadonlyMap<string, RegisteredWorkflow>, never, never>;

package/dist/actor/workflows.js

@@ -0,0 +1,37 @@
+import { Context, Effect, Option } from "effect";
+import { CurrentCaller, System, Tenant } from "../identity/caller.js";
+import { checkExecutionKey } from "../identity/execution.js";
+/**
+ * Every workflow's body. A body runs outside turns with the layer's context
+ * minus its `Scope`, since a body's scope is its run's, and calls as the
+ * execution's recorded principal through a `System({ source: "workflow" })`
+ * caller.
+ */
+export const workflowsOf = ({ descriptor, Workflow, bodies, services, }) => Effect.gen(function* () {
+    const registered = new Map();
+    for (const member of descriptor.workflows) {
+        const body = bodies[member.tag];
+        if (body === undefined)
+            return yield* Effect.die(new Error(`Missing workflow ${member.tag}`));
+        const codecs = descriptor.codecs.get(member.tag);
+        registered.set(member.tag, {
+            member,
+            steps: new Map(member.registry.steps),
+            key: (payload, fallback) => Effect.gen(function* () {
+                if (member.key === undefined)
+                    return fallback;
+                const input = yield* codecs.decodePayload(payload);
+                const key = member.key(input.value);
+                yield* checkExecutionKey(key);
+                return key;
+            }).pipe(Effect.orDie),
+            run: (payload, context) => codecs.decodePayload(payload).pipe(Effect.orDie, Effect.flatMap((input) => body(input.value)), Effect.exit, Effect.provideContext(Context.merge(Context.make(Workflow, context), services).pipe(Context.add(Tenant, context.ref.tenant), Context.add(CurrentCaller, System.make({
+                source: "workflow",
+                ref: context.ref,
+                onBehalfOf: Option.getOrUndefined(context.principal),
+            }))))),
+            encodeExit: descriptor.workflowExits.get(member.tag).encode,
+        });
+    }
+    return registered;
+});

package/dist/client/calls.d.ts

@@ -0,0 +1,47 @@
+import { Effect, Option, Schema } from "effect";
+import type { ServedDefinition, ServedMember } from "../actor/served.ts";
+import { ActorError } from "../errors/actor.ts";
+import { ConsistencyToken } from "./clock.ts";
+import type { ClientOptions, QueryOptions } from "./make.ts";
+import { type Failure, type Reply } from "./transport.ts";
+/** A failed attempt, with the response it came from when there was one. */
+interface Attempted {
+    readonly failure: Failure;
+    readonly reply: Reply | undefined;
+}
+/** `path` under `baseUrl`, without doubling the slash between them. */
+export declare const joinUrl: ({ baseUrl, path }: {
+    readonly baseUrl: string;
+    readonly path: string;
+}) => string;
+/** A random RFC 9562 UUID of `version` 4 or 7; a v7 carries the local clock in its first 48 bits. */
+export declare const uuid: (version: 4 | 7) => Effect.Effect<string, never, never>;
+export declare const declaredDecoder: (member: ServedMember) => (body: Schema.Json) => Option.Option<Failure>;
+/**
+ * The transport attempt policy of one actor type's client at one base URL:
+ * fresh headers and credentials for each attempt, the database clock and
+ * retry window its ids are minted from, which minted ids might have been
+ * admitted, bounded retries under one id, and the offline queue. The typed
+ * handle projection lives in `clientOf`; nothing here knows member types.
+ */
+export declare const callsOf: ({ definition, options, }: {
+    readonly definition: ServedDefinition;
+    readonly options: ClientOptions;
+}) => {
+    authorization: Effect.Effect<string | undefined, never, never>;
+    token: ConsistencyToken;
+    openEvents: (path: Effect.Effect<string, ActorError>, signal: AbortSignal, init: {
+        readonly method?: string;
+        readonly body?: string | undefined;
+        readonly headers: Readonly<Record<string, string>>;
+    }) => Effect.Effect<Response, ActorError, never>;
+    mint: Effect.Effect<string, Failure, never>;
+    waiting: <A>(work: Effect.Effect<A, Failure>, call: QueryOptions, commandId: () => string | undefined) => Promise<A>;
+    withRetries: <A>(attempt: Effect.Effect<A, Attempted>, call: QueryOptions, commandId: () => string | undefined, after?: Promise<void>) => Promise<A>;
+    asAttempt: (commandId: string | undefined) => (error: Attempted | Failure) => Attempted;
+    poster: (member: ServedMember) => (path: string, payload: string | undefined, commandId: string | undefined) => Effect.Effect<unknown, Attempted, never>;
+    queue: import("./offline/queue.ts").CommandQueue<unknown> | undefined;
+    /** A fresh command id, retried like a call until it is minted. */
+    commandId: () => Promise<string>;
+};
+export {};