@rikalabs/akter 0.1.0-alpha.0

package/dist/runtime/workflows/manifest.d.ts

@@ -0,0 +1,34 @@
+import { Crypto, Effect } from "effect";
+import type { AnyWorkflow } from "../../members/workflow.ts";
+/** Serializes a manifest or manifest part; its key order is what the manifest hash covers. */
+export declare const toJson: <T extends object>(value: T) => string;
+/** What an open execution depends on: its steps, the schemas they record, and marker ranges. */
+interface Manifest {
+    readonly workflow: string;
+    readonly payload: string;
+    readonly result: string;
+    readonly steps: ReadonlyArray<{
+        readonly name: string;
+        readonly kind: string;
+        readonly fingerprint: string;
+        /** The schemas of the value the step records: an activity's success and error, a wait's event. */
+        readonly result: string;
+        readonly event: string | null;
+    }>;
+    readonly versions: Readonly<Record<string, {
+        readonly current: number;
+        readonly min: number;
+    }>>;
+}
+/** A workflow's manifest, its hash, and its steps by name. */
+export interface Declared {
+    readonly manifest: Manifest;
+    readonly hash: string;
+    readonly steps: ReadonlyMap<string, Manifest["steps"][number]>;
+}
+/**
+ * The member's manifest and its SHA-256. Constructors register at module
+ * load, so the manifest is fixed once a layer is built.
+ */
+export declare const manifestOf: (actorType: string, member: AnyWorkflow) => Effect.Effect<Declared, never, Crypto.Crypto>;
+export {};

package/dist/runtime/workflows/manifest.js

@@ -0,0 +1,39 @@
+import { Crypto, Effect, Schema } from "effect";
+/** Serializes a manifest or manifest part; its key order is what the manifest hash covers. */
+export const toJson = (value) => JSON.stringify(value);
+const utf8 = new TextEncoder();
+const fingerprintOf = (schemas) => toJson(schemas.map((schema) => Schema.toJsonSchemaDocument(schema)));
+const hex = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+const cache = new WeakMap();
+/**
+ * The member's manifest and its SHA-256. Constructors register at module
+ * load, so the manifest is fixed once a layer is built.
+ */
+export const manifestOf = Effect.fnUntraced(function* (actorType, member) {
+    const cached = cache.get(member);
+    if (cached !== undefined)
+        return cached;
+    const manifest = {
+        workflow: member.tag,
+        payload: fingerprintOf([member.payload]),
+        result: fingerprintOf([member.success, member.error]),
+        steps: [...member.registry.steps.values()].map((step) => ({
+            name: step.name,
+            kind: step.kind,
+            fingerprint: fingerprintOf(step.payload === undefined ? step.result : [step.payload, ...step.result]),
+            result: fingerprintOf(step.result),
+            event: step.event ?? null,
+        })),
+        versions: member.versions,
+    };
+    const digest = yield* (yield* Crypto.Crypto)
+        .digest("SHA-256", utf8.encode(toJson([actorType, manifest])))
+        .pipe(Effect.orDie);
+    const entry = {
+        manifest,
+        hash: hex(digest),
+        steps: new Map(manifest.steps.map((step) => [step.name, step])),
+    };
+    cache.set(member, entry);
+    return entry;
+});

package/dist/runtime/workflows/steps.d.ts

@@ -0,0 +1,33 @@
+import { Effect, Exit, Schema } from "effect";
+import { RecordedExit } from "../../contexts/workflow.ts";
+import type { DeclaredError, ValueSchema } from "../../members/command.ts";
+import type { VersionRange, Workflow } from "../../members/workflow.ts";
+type Fields = Readonly<Record<string, ValueSchema>>;
+/** Encodes a step's exit with its own schemas, and decodes a recorded one back. */
+export declare const exitCodec: <S extends ValueSchema, E extends DeclaredError>({ success, error: errorSchema, }: {
+    readonly success: S;
+    readonly error: E;
+}) => {
+    encode: (exit: Exit.Exit<S["Type"], unknown>) => Effect.Effect<RecordedExit>;
+    decode: (recorded: RecordedExit) => Effect.Effect<Exit.Exit<S["Type"], E["Type"]>>;
+};
+declare const make: <const Tag extends string, const PayloadFields extends Fields = {}, Success extends ValueSchema = Schema.Void, Error extends DeclaredError = Schema.Never>(tag: Tag, options?: {
+    readonly payload?: PayloadFields;
+    readonly success?: Success;
+    readonly error?: Error;
+    readonly key?: (payload: Schema.Struct<PayloadFields>["Type"]) => string;
+    readonly versions?: Readonly<Record<string, VersionRange>>;
+}) => Workflow<Tag, Schema.Struct<PayloadFields>, Success, Error>;
+/**
+ * `WorkflowMember.make` is `Actor.workflow`: declares a workflow by tag.
+ * `key` derives the execution key from the payload (the start's command id when
+ * omitted), and `versions` marks code changes that old executions must not see.
+ * Throws on an invalid tag or version range.
+ *
+ * @example
+ * const Checkout = Actor.workflow("Checkout", { payload: { orderId: Schema.String } })
+ */
+export declare const WorkflowMember: {
+    make: typeof make;
+};
+export {};

package/dist/runtime/workflows/steps.js

@@ -0,0 +1,152 @@
+import { Cause, Duration, Effect, Exit, Option, Schema } from "effect";
+import { CurrentWorkflow, RecordedExit } from "../../contexts/workflow.js";
+import { payloadCodec } from "../../members/payload.js";
+const WORKFLOW_TAG = /^[A-Za-z][A-Za-z0-9]{0,79}$/;
+const STEP_NAME = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const engine = Effect.gen(function* () {
+    const steps = yield* CurrentWorkflow;
+    if (steps === undefined)
+        return yield* Effect.die(new Error("Workflow step outside a workflow body"));
+    return steps;
+});
+/** Encodes a step's exit with its own schemas, and decodes a recorded one back. */
+export const exitCodec = ({ success, error: errorSchema, }) => {
+    const value = Schema.toCodecJson(success);
+    const error = Schema.toCodecJson(errorSchema);
+    const isError = Schema.is(errorSchema);
+    const encode = (exit) => {
+        if (Exit.isSuccess(exit))
+            return Schema.encodeEffect(value)(exit.value).pipe(Effect.map((encoded) => RecordedExit.cases.Success.make({ value: encoded })), Effect.orDie);
+        const failure = Cause.findErrorOption(exit.cause);
+        if (Option.isSome(failure) && isError(failure.value))
+            return Schema.encodeEffect(error)(failure.value).pipe(Effect.map((encoded) => RecordedExit.cases.Failure.make({ error: encoded })), Effect.orDie);
+        return Effect.succeed(RecordedExit.cases.Die.make({ message: Cause.pretty(exit.cause) }));
+    };
+    /** The recorded exit; a recorded defect is a defect again. */
+    const decode = (recorded) => RecordedExit.match(recorded, {
+        Success: ({ value: encoded }) => Schema.decodeEffect(value)(encoded).pipe(Effect.orDie, Effect.map((ok) => Exit.succeed(ok))),
+        Failure: ({ error: encoded }) => Schema.decodeEffect(error)(encoded).pipe(Effect.orDie, Effect.map((failed) => Exit.fail(failed))),
+        Die: ({ message }) => Effect.succeed(Exit.die(new Error(message))),
+    });
+    return { encode, decode };
+};
+const make = (tag, options = {}) => {
+    if (!WORKFLOW_TAG.test(tag))
+        throw new Error(`Invalid workflow name: ${tag}`);
+    const versions = options.versions ?? {};
+    for (const [name, range] of Object.entries(versions))
+        if (!STEP_NAME.test(name) ||
+            !Number.isInteger(range.min) ||
+            !Number.isInteger(range.current) ||
+            range.min < 0 ||
+            range.current < 1 ||
+            range.min > range.current)
+            throw new Error(`Workflow ${tag} version ${name} needs integers 0 <= min <= current, current >= 1`);
+    const registry = { steps: new Map() };
+    const identity = (name, kind) => ({
+        workflow: tag,
+        name,
+        kind,
+    });
+    const register = (entry) => {
+        if (!STEP_NAME.test(entry.name))
+            throw new Error(`Invalid step name: ${entry.name}`);
+        if (registry.steps.has(entry.name))
+            throw new Error(`Workflow ${tag} already has a step named ${entry.name}`);
+        registry.steps.set(entry.name, entry);
+    };
+    const step = (name, stepOptions) => {
+        const payload = (stepOptions?.payload ?? Schema.Void);
+        const success = (stepOptions?.success ?? Schema.Void);
+        const error = (stepOptions?.error ?? Schema.Never);
+        register({ name, kind: "activity", payload, result: [success, error] });
+        const codec = exitCodec({ success, error });
+        const decodePayload = Schema.decodeUnknownEffect(payload);
+        const self = identity(name, "activity");
+        return {
+            name,
+            kind: "activity",
+            run: (value, execute) => Effect.gen(function* () {
+                const steps = yield* engine;
+                const run = Effect.suspend(() => decodePayload(value).pipe(Effect.orDie)).pipe(Effect.flatMap((decoded) => execute(decoded)), Effect.exit, Effect.flatMap(codec.encode));
+                return yield* steps.activity(self, run).pipe(Effect.flatMap(codec.decode), Effect.flatten);
+            }),
+        };
+    };
+    const sleep = (name) => {
+        register({ name, kind: "clock", result: [] });
+        const self = identity(name, "clock");
+        const call = (duration) => Effect.gen(function* () {
+            const millis = Duration.toMillis(Duration.fromInputUnsafe(duration));
+            if (!Number.isFinite(millis) || millis < 0)
+                return yield* Effect.die(new Error(`Sleep ${name} needs a finite, non-negative duration`));
+            return yield* (yield* engine).sleep(self, Math.ceil(millis));
+        });
+        return Object.assign(call, { stepName: name, kind: "clock" });
+    };
+    const wait = (name, event) => {
+        register({ name, kind: "wait", result: [event], event: event.identifier });
+        const self = identity(name, "wait");
+        const codec = payloadCodec({ schema: event, tag: event.identifier });
+        const call = (waitOptions) => Effect.gen(function* () {
+            const timeoutMs = waitOptions?.timeout === undefined
+                ? undefined
+                : Math.ceil(Duration.toMillis(Duration.fromInputUnsafe(waitOptions.timeout)));
+            if (timeoutMs !== undefined && (!Number.isFinite(timeoutMs) || timeoutMs < 0))
+                return yield* Effect.die(new Error(`Wait ${name} needs a finite, non-negative timeout`));
+            const where = waitOptions?.where;
+            const matched = yield* (yield* engine).wait(self, event.identifier, (value, version) => codec.decode(value, version).pipe(Effect.flatMap((decoded) => where === undefined || where(decoded)
+                ? Effect.asSome(codec.upcast(value, version))
+                : Effect.succeedNone), Effect.orDie), timeoutMs);
+            if (Option.isNone(matched))
+                return Option.none();
+            return Option.some((yield* codec
+                .decode(matched.value, codec.chain.current)
+                .pipe(Effect.orDie)));
+        });
+        return Object.assign(call, { stepName: name, kind: "wait" });
+    };
+    const race = (name, raceOptions) => {
+        const error = (raceOptions.error ?? Schema.Never);
+        register({ name, kind: "deferred", result: [raceOptions.success, error] });
+        const codec = exitCodec({ success: raceOptions.success, error });
+        const self = identity(name, "deferred");
+        return {
+            name,
+            kind: "deferred",
+            run: (effects) => Effect.gen(function* () {
+                const steps = yield* engine;
+                if (effects.length === 0)
+                    return yield* Effect.die(new Error(`Race ${name} needs at least one effect`));
+                const run = Effect.raceAll(effects).pipe(Effect.exit, Effect.flatMap((exit) => Exit.isFailure(exit) && (Cause.hasDies(exit.cause) || Cause.hasInterrupts(exit.cause))
+                    ? Effect.failCause(exit.cause).pipe(Effect.orDie)
+                    : codec.encode(exit)));
+                return yield* steps.race(self, run).pipe(Effect.flatMap(codec.decode), Effect.flatten);
+            }),
+        };
+    };
+    return {
+        kind: "workflow",
+        tag,
+        payload: Schema.Struct(options.payload ?? {}),
+        success: (options.success ?? Schema.Void),
+        error: (options.error ?? Schema.Never),
+        key: options.key,
+        versions,
+        registry,
+        step,
+        sleep,
+        wait,
+        race,
+    };
+};
+/**
+ * `WorkflowMember.make` is `Actor.workflow`: declares a workflow by tag.
+ * `key` derives the execution key from the payload (the start's command id when
+ * omitted), and `versions` marks code changes that old executions must not see.
+ * Throws on an invalid tag or version range.
+ *
+ * @example
+ * const Checkout = Actor.workflow("Checkout", { payload: { orderId: Schema.String } })
+ */
+export const WorkflowMember = { make };

package/dist/serve/api.d.ts

@@ -0,0 +1,99 @@
+import { HttpApi, HttpApiGroup, OpenApi } from "effect/http-api";
+import { type ServedDefinition } from "../actor/served.ts";
+import { type AuthProvider } from "./auth.ts";
+/** The path of one served member, with `:id` for keyed and minted actors. */
+interface ServedRoute {
+    readonly definition: ServedDefinition;
+    readonly member: {
+        readonly tag: string;
+    };
+}
+/** The path of a served member below the base path, as the router and the OpenAPI document both spell it. */
+export declare const memberPath: ({ definition, member }: ServedRoute) => string;
+/** The path segment an actor's content routes are served under, so no member may take it. */
+export declare const CONTENT_ROUTE = "content";
+/** The operation id of the route that mints command ids. */
+export declare const MINT_OPERATION = "durable.commandIds";
+/** Operation ids of the protocol routes; no served member may reuse one. */
+export declare const PROTOCOL_OPERATIONS: ReadonlySet<string>;
+/** Paths of the protocol routes under the base path; `openapi.path` may not take one. */
+export declare const PROTOCOL_PATHS: ReadonlySet<string>;
+interface ServedRoutes {
+    readonly definitions: ReadonlyArray<ServedDefinition>;
+    /** The names and group keys of the fleet views served at `GET /fleet/{View}`. */
+    readonly fleet: ReadonlyArray<{
+        readonly name: string;
+        readonly groupBy: ReadonlyArray<string>;
+    }>;
+    readonly basePath: string;
+    /** Whether the runtime serves content, so `POST /content` and the content routes exist. */
+    readonly content: boolean;
+}
+/** The `HttpApi` of the served actors: the protocol group, then one group per actor with members, connections, feed, content, and streams. */
+export declare const buildServedApi: ({ definitions, fleet, basePath, content }: ServedRoutes) => HttpApi.HttpApi<string, HttpApiGroup.Constraint>;
+type ServedApi = ReturnType<typeof buildServedApi>;
+interface DocumentOptions {
+    readonly api: ServedApi;
+    readonly auth: AuthProvider<unknown>;
+    readonly title: string;
+    readonly version: string;
+}
+/** The OpenAPI security scheme a credential is documented as; a provider has at most one per scheme. */
+export declare const schemeName: (value: {
+    readonly _tag: "Assertion";
+} | {
+    readonly _tag: "Bearer";
+} | {
+    readonly _tag: "Cookie";
+    readonly name: string;
+} | {
+    readonly _tag: "Jwt";
+}) => string;
+/**
+ * The OpenAPI 3.1 document of `api`. Every authenticated operation lists the
+ * provider's credentials as alternatives, since any one of them authenticates.
+ */
+export declare const openApiDocument: ({ api, auth, title, version }: DocumentOptions) => {
+    openapi: "3.1.0";
+    security: Array<OpenApi.OpenAPISecurityRequirement>;
+    tags: Array<OpenApi.OpenAPISpecTag>;
+    servers?: Array<OpenApi.OpenAPISpecServer>;
+    info: {
+        description?: string;
+        license?: OpenApi.OpenAPISpecLicense;
+        summary?: string;
+        title: string;
+        version: string;
+    };
+    paths: {
+        [k: string]: {
+            [k: string]: OpenApi.OpenAPISpecParameter[] | ((OpenApi.OpenAPISpecOperation | Partial<Record<import("effect/http/HttpMethod").HttpMethod, OpenApi.OpenAPISpecOperation>>) & {
+                security: {
+                    [x: string]: never[];
+                }[];
+            });
+        };
+    };
+    components: {
+        schemas: import("effect/JsonSchema").Definitions;
+        securitySchemes: {
+            [k: string]: {
+                type: string;
+                scheme: string;
+            } | {
+                type: string;
+                scheme: string;
+                bearerFormat: string;
+            } | {
+                type: string;
+                in: string;
+                name: string;
+            } | {
+                type: string;
+                in: string;
+                name: string;
+            };
+        };
+    };
+};
+export {};