@rikalabs/akter 0.1.0-alpha.0

package/dist/actor/descriptor.js

@@ -0,0 +1,367 @@
+import { Effect, Predicate, Schema } from "effect";
+import { handleOf } from "./handles.js";
+import { childId, parseChildId } from "../identity/child.js";
+import { isMintedId } from "../identity/mint.js";
+import { SubscriptionFailure } from "../errors/subscription.js";
+import { isWorkflow } from "../members/workflow.js";
+import { isBlob, isContent } from "../members/blob.js";
+import { payloadChain, payloadCodec, } from "../members/payload.js";
+import { resolvePolicy } from "../policies/command.js";
+import { resolveJobPolicy } from "../policies/job.js";
+import { resolveSchedules } from "../policies/schedules.js";
+import { ownership } from "../tables/owned.js";
+import { exitCodec } from "../runtime/workflows/steps.js";
+import { ActorStates } from "../state/migration.js";
+import { memberCodecs, stateCodec, valueCodec, } from "./codecs.js";
+import { checkDeclaredErrors, servedConnection, servedMember, } from "./served.js";
+const SingletonKeySchema = Schema.TaggedStruct("Singleton", {});
+/** Whether a definition's `key` is `Actor.singleton`. */
+export const isSingletonKey = Schema.is(SingletonKeySchema);
+/** Marker for a singleton actor's `key`: one instance per tenant, resolved with `X.get()`. */
+export const singleton = SingletonKeySchema.make({});
+/** How many levels below its actor-placed root a parent-placed actor may sit. */
+const MAX_PLACEMENT_DEPTH = 4;
+const isUUIDv7 = Schema.is(Schema.String.check(Schema.isUUID(7)));
+const NAME = Schema.String.check(Schema.isPattern(/^[A-Za-z][A-Za-z0-9]{0,79}$/u));
+const descriptors = new WeakMap();
+/** The descriptor of an `Actor.make` definition, or undefined for any other value. */
+export const descriptorOf = (definition) => descriptors.get(definition);
+const tagMatches = (api, internal) => {
+    const tags = new Set();
+    for (const [key, member] of [...Object.entries(api), ...Object.entries(internal)]) {
+        if (key !== member.tag)
+            throw new Error(`Command key ${key} must equal its tag ${member.tag}`);
+        if (tags.has(member.tag) ||
+            member.tag === "ref" ||
+            member.tag === "state" ||
+            member.tag.startsWith("$"))
+            throw new Error(`Duplicate or reserved command: ${member.tag}`);
+        tags.add(member.tag);
+    }
+    for (const member of Object.values(internal)) {
+        if (member.kind !== "command")
+            throw new Error(`Internal members must be commands: ${member.tag}`);
+    }
+};
+const placementOf = (name, declared, singleton, createdBy) => {
+    const option = declared.placement ?? "tenant";
+    if (option === "tenant" || option === "actor")
+        return { placement: option, parent: undefined, depth: 0 };
+    if (!Predicate.hasProperty(option, "parent"))
+        throw new Error(`placement is "tenant", "actor", or { parent }`);
+    const parent = descriptorOf(option.parent);
+    if (parent === undefined)
+        throw new Error("placement.parent takes an Actor.make definition");
+    if (parent.placement === "tenant")
+        throw new Error(`${name}'s parent ${parent.name} is tenant-placed, so its children already share its shard; place ${name} by "tenant"`);
+    if (parent.depth + 1 > MAX_PLACEMENT_DEPTH)
+        throw new Error(`${name} would be ${parent.depth + 1} levels below its root; parent placement allows ${MAX_PLACEMENT_DEPTH}`);
+    if (singleton)
+        throw new Error(`Singleton ${name} cannot be parent-placed`);
+    if (declared.key === undefined && createdBy === undefined)
+        throw new Error(`Parent-placed ${name} needs a key or createdBy`);
+    const placement = { parent: parent.name, placement: parent.placement };
+    return { placement, parent, depth: parent.depth + 1 };
+};
+const idSchemaOf = (name, key, parent) => {
+    const isLocalId = Schema.isSchema(key) ? Schema.is(key) : isMintedId;
+    if (parent !== undefined)
+        return Schema.String.check(Schema.makeFilter((id) => {
+            const parts = parseChildId(id);
+            return parts !== undefined && parent.isId(parts.parent) && isLocalId(parts.local);
+        }, { expected: `c1.<byte length>.<${parent.name} id>.<${name} local id>` }));
+    if (Schema.isSchema(key))
+        return key;
+    if (key === undefined)
+        return Schema.String.check(Schema.makeFilter((id) => isUUIDv7(id) || isMintedId(id), {
+            expected: "a UUID v7 or a minted UUID v8",
+        }));
+    return Schema.String.check(Schema.isUUID(7));
+};
+const compileJobs = (declared, commands) => {
+    const jobs = new Map();
+    for (const [key, binding] of Object.entries(declared.jobs ?? {})) {
+        const job = binding?.job;
+        if (job === undefined || !Schema.isSchema(job) || job.tag === undefined)
+            throw new Error(`jobs.${key} must bind an Actor.job value`);
+        if (key !== job.tag)
+            throw new Error(`jobs.${key} must be keyed by its job's tag ${job.tag}`);
+        jobs.set(job.tag, {
+            job,
+            codec: payloadCodec({ schema: job, tag: job.tag }),
+            policy: resolveJobPolicy({ path: `jobs.${key}`, declared: binding, commands }),
+        });
+    }
+    return jobs;
+};
+const compileSubscriptions = (name, singleton, internal, subscriptions, decodeId) => {
+    const tags = new Set();
+    const handlerTags = new Set();
+    for (const declared of subscriptions) {
+        if (declared?.kind !== "subscription")
+            throw new Error("subscriptions takes Actor.subscription values");
+        if (tags.has(declared.tag))
+            throw new Error(`Duplicate subscription: ${declared.tag}`);
+        tags.add(declared.tag);
+        if (internal[declared.handler.tag] !== declared.handler)
+            throw new Error(`Subscription ${declared.tag}'s handler must be a command in internal`);
+        handlerTags.add(declared.handler.tag);
+        const source = descriptorOf(declared.source);
+        if (source === undefined)
+            throw new Error(`Subscription ${declared.tag}'s source must be an Actor.make definition`);
+        if (source.policy.subscribers !== undefined && !source.policy.subscribers.includes(name))
+            throw new Error(`${declared.source.name} policy.allowedSubscriberTypes does not allow ${name} (subscription ${declared.tag})`);
+        const toSingleton = declared.route !== undefined && !Predicate.isFunction(declared.route);
+        if (singleton && declared.route !== undefined && !toSingleton)
+            throw new Error(`Singleton ${name} routes subscription ${declared.tag} with Actor.singleton`);
+        if (!singleton && toSingleton)
+            throw new Error(`Subscription ${declared.tag} routes to Actor.singleton, but ${name} is keyed`);
+    }
+    const registered = subscriptions.map((declared) => {
+        const decoders = new Map(declared.events.map((event) => [event.identifier, payloadCodec({ schema: event, tag: event.identifier })]));
+        const route = declared.route;
+        const codecOf = (tag) => {
+            const codec = decoders.get(tag);
+            return codec === undefined
+                ? Effect.fail(SubscriptionFailure.make({ message: `Subscription ${declared.tag} names no ${tag}` }))
+                : Effect.succeed(codec);
+        };
+        return {
+            tag: declared.tag,
+            sourceType: declared.source.name,
+            handler: declared.handler.tag,
+            events: declared.events.map((event) => event.identifier),
+            retired: declared.retired,
+            routed: route === undefined ? undefined : Predicate.isFunction(route) ? "id" : "singleton",
+            upcast: (tag, version, value) => Effect.flatMap(codecOf(tag), (codec) => codec.upcast(value, version)).pipe(Effect.catchTag("PayloadError", (error) => Effect.fail(SubscriptionFailure.make({ message: error.message })))),
+            route: (tag, value, source) => Effect.gen(function* () {
+                if (!Predicate.isFunction(route))
+                    return "singleton";
+                const codec = yield* codecOf(tag);
+                const event = yield* codec.decode(value, codec.chain.current);
+                const id = yield* Effect.try({
+                    try: () => route(event, source),
+                    catch: (cause) => SubscriptionFailure.make({ message: String(cause) }),
+                });
+                return yield* decodeId(id);
+            }).pipe(Effect.catchTags({
+                SchemaError: (error) => Effect.fail(SubscriptionFailure.make({ message: error.message })),
+                PayloadError: (error) => Effect.fail(SubscriptionFailure.make({ message: error.message })),
+            })),
+        };
+    });
+    return { handlerTags, registered };
+};
+/**
+ * Validates a declaration and compiles its descriptor, throwing on the first
+ * invalid part. It publishes nothing: `publish` records the descriptor and
+ * its table ownership only after the whole definition has compiled, so a
+ * rejected definition leaves every registry as it was.
+ */
+export const compile = ({ name, declared, }) => {
+    NAME.make(name);
+    const api = declared.api ?? {};
+    const internal = declared.internal ?? {};
+    tagMatches(api, internal);
+    const members = [...Object.values(api), ...Object.values(internal)];
+    const commands = members.filter((member) => member.kind === "command");
+    const queries = members.filter((member) => member.kind === "query");
+    const connections = members.filter((member) => member.kind === "connection");
+    const streams = members.filter((member) => member.kind === "stream");
+    const reducers = members.filter((member) => member.kind === "reducer");
+    const workflows = members.filter(isWorkflow);
+    for (const member of Object.values(internal))
+        if (isWorkflow(member))
+            throw new Error(`Workflow ${member.tag} must be in api`);
+    const fields = declared.state?.fields ?? {};
+    const policy = resolvePolicy({
+        declared: declared.policy,
+        createdBy: declared.createdBy,
+        commands,
+    });
+    const cron = resolveSchedules({ declared: declared.schedules, commands });
+    const singleton = isSingletonKey(declared.key);
+    const jobs = compileJobs(declared, commands);
+    const progressJobs = new Set();
+    for (const member of [...connections, ...streams])
+        for (const job of member.progress?.jobs ?? []) {
+            if (jobs.get(job.tag)?.job !== job || job.progress === undefined)
+                throw new Error(`${member.tag} lists progress of ${job.tag}, which is not a bound job with a progress schema`);
+            progressJobs.add(job.tag);
+        }
+    if ("set" in fields)
+        throw new Error("State key 'set' is reserved");
+    for (const reducer of reducers)
+        if (reducer.state !== declared.state)
+            throw new Error(`Reducer ${reducer.tag} must declare its actor's state`);
+    const tables = declared.tables ?? [];
+    const { placement, parent, depth } = placementOf(name, declared, singleton, policy.createdBy);
+    for (const table of tables) {
+        const info = ownership(table);
+        if (info === undefined)
+            throw new Error("tables takes Actor.table values");
+        if (tables.indexOf(table) !== tables.lastIndexOf(table))
+            throw new Error(`Table ${info.name} is listed twice`);
+        if (info.owner !== undefined && info.owner !== name)
+            throw new Error(`Table ${info.name} is already owned by actor ${info.owner}`);
+        if (info.adopted && policy.createdBy !== undefined)
+            throw new Error(`Actor ${name} mints its ids and cannot adopt table ${info.name}: legacy rows carry ids it never minted`);
+    }
+    const events = new Map();
+    for (const event of declared.events ?? []) {
+        if (events.has(event.identifier))
+            throw new Error(`Duplicate event: ${event.identifier}`);
+        events.set(event.identifier, event);
+    }
+    const feeds = new Set();
+    for (const event of declared.feeds ?? []) {
+        if (events.get(event.identifier) !== event)
+            throw new Error(`Feed ${event.identifier} is not one of ${name}'s events`);
+        feeds.add(event.identifier);
+    }
+    const eventCodecs = new Map([...events.values()].map((event) => [event.identifier, payloadCodec({ schema: event, tag: event.identifier })]));
+    const blobs = declared.blobs ?? [];
+    const blobNames = new Set();
+    for (const blob of blobs) {
+        if (!isBlob(blob))
+            throw new Error("blobs takes Actor.blob and Actor.content values");
+        if (blobNames.has(blob.name))
+            throw new Error(`Blob ${blob.name} is listed twice`);
+        blobNames.add(blob.name);
+    }
+    const migrations = declared.state?.migrations ?? [];
+    ActorStates.validateChain(fields, migrations);
+    const idSchema = idSchemaOf(name, declared.key, parent);
+    const decodeIdSchema = Schema.decodeEffect(idSchema);
+    const encodeIdSchema = Schema.encodeEffect(idSchema);
+    const decodeId = singleton
+        ? () => Effect.succeed("singleton")
+        : (id) => decodeIdSchema(id);
+    const encodeId = singleton
+        ? () => Effect.succeed("singleton")
+        : (id) => encodeIdSchema(id);
+    const subscriptions = declared.subscriptions ?? [];
+    const { handlerTags, registered } = compileSubscriptions(name, singleton, internal, subscriptions, (id) => decodeIdSchema(id));
+    for (const member of Object.values(api))
+        checkDeclaredErrors(member);
+    const codecs = new Map(members.map((member) => [member.tag, memberCodecs(member)]));
+    const connectionCodecs = new Map(connections.map((member) => {
+        const server = valueCodec(member.server);
+        const client = valueCodec(member.client);
+        const session = member.session === undefined ? undefined : valueCodec(member.session);
+        return [
+            member.tag,
+            {
+                encodeServer: Schema.encodeEffect(server),
+                decodeClient: Schema.decodeEffect(client),
+                encodeSession: session === undefined ? undefined : Schema.encodeEffect(session),
+                decodeSession: session === undefined ? undefined : Schema.decodeEffect(session),
+            },
+        ];
+    }));
+    const payloads = (writes) => [
+        ...[...events.values()].map((event) => ({
+            actorType: name,
+            kind: "event",
+            tag: event.identifier,
+            chain: payloadChain(event),
+            writes,
+        })),
+        ...[...jobs.values()].map(({ job }) => ({
+            actorType: name,
+            kind: "job",
+            tag: job.tag,
+            chain: payloadChain(job),
+            writes,
+        })),
+    ];
+    const mintable = declared.key === undefined && policy.createdBy !== undefined;
+    const minted = !singleton && declared.key === undefined && parent === undefined;
+    const served = {
+        name,
+        key: singleton ? "singleton" : minted ? "minted" : "keyed",
+        decodeId,
+        encodeId,
+        members: Object.values(api)
+            .filter((member) => member.kind !== "connection" && member.kind !== "stream" && member.kind !== "workflow")
+            .map((member) => servedMember({ member, codecs: codecs.get(member.tag) })),
+        connections: connections.map(servedConnection),
+        feeds: [...feeds],
+        contents: blobs.flatMap((blob) => (isContent(blob) ? [blob.name] : [])),
+        streams: streams.map((member) => servedMember({ member, codecs: codecs.get(member.tag) })),
+    };
+    const descriptor = Object.freeze({
+        name,
+        access: declared.access,
+        singleton,
+        mintable,
+        minted,
+        placement,
+        depth,
+        parent,
+        idSchema,
+        decodeId,
+        encodeId,
+        isId: singleton ? (id) => id === "singleton" : Schema.is(idSchema),
+        childId: (parentId, local) => {
+            if (parent === undefined)
+                throw new Error(`${name} is not parent-placed`);
+            return childId({ parent: parentId, local });
+        },
+        api,
+        internalCommands: internal,
+        members,
+        commands,
+        queries,
+        reducers,
+        connections,
+        streams,
+        workflows,
+        internalMembers: new Set(Object.values(internal)),
+        handlerTags,
+        watches: new Set(queries.flatMap((member) => ("watch" in member && member.watch === true ? [member.tag] : []))),
+        codecs,
+        connectionCodecs,
+        workflowExits: new Map(workflows.map((member) => [
+            member.tag,
+            exitCodec({ success: member.success, error: member.error }),
+        ])),
+        fields,
+        state: stateCodec({ fields, migrations, maxBytes: policy.stateMaxBytes }),
+        events,
+        eventCodecs,
+        feeds,
+        jobs,
+        progressJobs,
+        policy,
+        cron,
+        tables,
+        blobs,
+        subscriptions,
+        registeredSubscriptions: registered,
+        payloads,
+        definitionPayloads: {
+            declarations: payloads(true),
+            keepEventsMs: policy.keepEventsMs,
+            commandTimeoutMs: policy.executionMs,
+        },
+        served,
+        internal: {
+            handle: (id, tenant, caller) => handleOf(descriptor, id, true, caller, tenant),
+        },
+    });
+    return descriptor;
+};
+/**
+ * Records `descriptor` for `definition` and gives its tables to the actor
+ * type. `compile` has already validated every table, so this cannot fail
+ * part-way.
+ */
+export const publish = ({ definition, descriptor, }) => {
+    for (const table of descriptor.tables) {
+        const info = ownership(table);
+        info.owner = descriptor.name;
+        info.placement = descriptor.placement;
+    }
+    descriptors.set(definition, descriptor);
+};

package/dist/actor/handles.d.ts

@@ -0,0 +1,77 @@
+import { Effect, Stream } from "effect";
+import { ActorError } from "../errors/actor.ts";
+import { InvalidExecutionId } from "../errors/workflow.ts";
+import { Actors } from "../handles/actors.ts";
+import { ActorRef } from "../identity/caller.ts";
+import { type AnyWorkflow } from "../members/workflow.ts";
+import { InternalActors } from "../runtime/actors.ts";
+import type { Decoded, Failure } from "./codecs.ts";
+import type { Descriptor } from "./descriptor.ts";
+/** One method of a handle: a call returning an Effect, or a stream, before `Handle` types it. */
+type HandleMethod = (payload: Decoded) => Effect.Effect<Decoded, Failure> | Stream.Stream<Decoded, Failure>;
+/**
+ * The methods of a request/reply handle to `id`, which reach `internal`
+ * commands when `includeInternal` is set. Running a command method's Effect
+ * mints its command id once and reuses it on every rerun, so a retry is
+ * deduplicated by the receipt; a workflow step's call takes the step's id.
+ * Handles never deliver subscriptions, so an acknowledged outcome is a defect.
+ */
+export declare const handleOf: (descriptor: Descriptor, id: string, includeInternal: boolean, as?: {
+    readonly _tag: "Anonymous";
+} | {
+    readonly _tag: "System";
+    readonly source: "actor" | "cron" | "job" | "process" | "subscription" | "timer" | "workflow";
+    readonly ref?: {
+        readonly tenant: string;
+        readonly actor: string;
+        readonly id: string;
+    } | undefined;
+    readonly onBehalfOf?: {
+        readonly subject: string;
+    } | undefined;
+    readonly mint?: {
+        readonly commandId: string;
+        readonly ordinal: number;
+    } | undefined;
+} | {
+    readonly _tag: "User";
+    readonly subject: string;
+} | undefined, tenant?: string | undefined) => Effect.Effect<Readonly<Record<string, HandleMethod>> & {
+    readonly ref: ActorRef;
+}, never, Actors | InternalActors>;
+/**
+ * Mints a new UUIDv7 id and returns its handle. Only an unkeyed actor that is
+ * not parent-placed may be created by a caller; inside a turn it is a defect.
+ */
+export declare const createOf: (descriptor: Descriptor) => Effect.Effect<Readonly<Record<string, HandleMethod>> & {
+    readonly ref: ActorRef;
+}, never, Actors | InternalActors>;
+/**
+ * Durable intents to actor `id`, staged in the current command turn. The
+ * target shares the sending turn's tenant. A keyless workflow start is keyed
+ * by the turn's command id and its order among the turn's starts, so a
+ * retried turn restages the same executions. Commands that subscriptions
+ * deliver to are left out.
+ */
+export declare const intentsOf: (descriptor: Descriptor, id: string) => Effect.Effect<{
+    ref: {
+        readonly tenant: string;
+        readonly actor: string;
+        readonly id: string;
+    };
+}, never, import("../handles/intents.ts").InTurn>;
+/**
+ * Reattaches to a workflow execution by id without contacting its owner. An
+ * id of another tenant, actor type, or workflow fails `InvalidExecutionId`.
+ */
+export declare const runOfId: (descriptor: Descriptor, member: AnyWorkflow, executionId: string) => Effect.Effect<{
+    executionId: string;
+    poll: Effect.Effect<import("effect/Option").Option<import("effect/workflow/Workflow").Result<unknown, import("effect/Cause").YieldableError & {
+        readonly _tag: string;
+    }>>, ActorError, never>;
+    result: Effect.Effect<unknown, ActorError | (import("effect/Cause").YieldableError & {
+        readonly _tag: string;
+    }), never>;
+    interrupt: Effect.Effect<void, ActorError, never>;
+}, InvalidExecutionId, Actors | InternalActors>;
+export {};