@rikalabs/akter 0.1.0-alpha.0

package/dist/actor/reads.d.ts

@@ -0,0 +1,47 @@
+import { Context, Effect } from "effect";
+import { type EventEntry } from "../contexts/command.ts";
+import { type EventClass } from "../members/event.ts";
+import type { AnyStream } from "../members/stream.ts";
+import type { InternalActors } from "../runtime/actors.ts";
+import type { EventReader, RegisteredQuery, RegisteredStream } from "../runtime/members.ts";
+import type { Handler, StreamHandler } from "./codecs.ts";
+import type { Descriptor } from "./descriptor.ts";
+/**
+ * `read.events` over `readEvents`: an undeclared event class or a `limit`
+ * outside 1..10,000 is a defect of the handler. `label` names the capability
+ * in that defect.
+ */
+export declare const eventsWith: ({ descriptor, readEvents, label, }: {
+    readonly descriptor: Descriptor;
+    readonly readEvents: EventReader;
+    readonly label?: string;
+}) => (event: EventClass, options?: {
+    readonly after?: string | undefined;
+    readonly limit?: number | undefined;
+}) => Effect.Effect<EventEntry<unknown>[], import("../index.ts").RetentionGap | import("../index.ts").UnknownCursor, never>;
+/**
+ * Registers every query's handler. A query runs with its own `InsideTurn`
+ * marker, so a command or query call from it is a defect instead of a write,
+ * and its capabilities die once it returns or from another fiber. A watched
+ * run records what it reads; a `watch: true` handler gets no layer services.
+ */
+export declare const queriesOf: ({ descriptor, Read, handlers, services, actors, }: {
+    readonly descriptor: Descriptor;
+    readonly Read: Context.Key<object, object>;
+    readonly handlers: Readonly<Record<string, Handler>>;
+    readonly services: Context.Context<never>;
+    readonly actors: InternalActors["Service"];
+}) => Effect.Effect<ReadonlyMap<string, RegisteredQuery>, never, never>;
+/**
+ * A stream member's live feed for one subscriber. It runs on the activation
+ * with its own `InsideTurn` marker and `InStream`, and its capabilities die
+ * once the stream ends. `read.progress` reaches only jobs its member lists.
+ */
+export declare const streamOf: ({ descriptor, Read, member, handle, services, actors, }: {
+    readonly descriptor: Descriptor;
+    readonly Read: Context.Key<object, object>;
+    readonly member: AnyStream;
+    readonly handle: StreamHandler;
+    readonly services: Context.Context<never>;
+    readonly actors: InternalActors["Service"];
+}) => RegisteredStream;

package/dist/actor/reads.js

@@ -0,0 +1,224 @@
+import { Context, DateTime, Effect, Fiber, Schema, Stream } from "effect";
+import { InsideTurn, InStream, } from "../contexts/command.js";
+import { CurrentCaller, principal, Tenant } from "../identity/caller.js";
+import { DEFAULT_REPLAY_LIMIT, MAX_REPLAY_LIMIT } from "../members/event.js";
+import { Outcome } from "../runtime/request.js";
+import { ownership } from "../tables/owned.js";
+/** A committed event decoded at the class's current version, with its cursor and command. */
+const entryOf = (descriptor, event, stored) => Effect.map(descriptor.eventCodecs
+    .get(event.identifier)
+    .decode(stored.value, stored.version)
+    .pipe(Effect.orDie), (decoded) => ({
+    cursor: stored.cursor,
+    event: decoded,
+    commandId: stored.commandId,
+    timestamp: DateTime.makeUnsafe(stored.timestampMs),
+}));
+/**
+ * `read.events` over `readEvents`: an undeclared event class or a `limit`
+ * outside 1..10,000 is a defect of the handler. `label` names the capability
+ * in that defect.
+ */
+export const eventsWith = ({ descriptor, readEvents, label = "read.events", }) => (event, options) => Effect.gen(function* () {
+    if (descriptor.events.get(event.identifier) !== event)
+        return yield* Effect.die(new Error(`Undeclared event: ${event.identifier}`));
+    const limit = options?.limit ?? DEFAULT_REPLAY_LIMIT;
+    if (!Number.isInteger(limit) || limit < 1 || limit > MAX_REPLAY_LIMIT)
+        return yield* Effect.die(new Error(`${label} limit must be an integer from 1 to ${MAX_REPLAY_LIMIT}`));
+    return yield* Effect.forEach(yield* readEvents(event.identifier, options?.after, limit), (stored) => entryOf(descriptor, event, stored));
+});
+const recordingRead = (context, reads) => ({
+    get id() {
+        reads.caller = true;
+        return context.id;
+    },
+    get ref() {
+        reads.caller = true;
+        return context.ref;
+    },
+    get caller() {
+        reads.caller = true;
+        return context.caller;
+    },
+    get principal() {
+        reads.caller = true;
+        return context.principal;
+    },
+    get state() {
+        reads.state = true;
+        return context.state;
+    },
+    cursor: context.cursor,
+    events: (event, options) => {
+        reads.events.add(event.identifier);
+        return context.events(event, options);
+    },
+    rows: (table) => {
+        reads.tables.add(ownership(table)?.name ?? "");
+        return context.rows(table);
+    },
+    get group() {
+        reads.group = true;
+        return context.group;
+    },
+    blob: (declared) => {
+        reads.blobs.add(declared.name);
+        return context.blob(declared);
+    },
+    follow: context.follow,
+    progress: context.progress,
+});
+/**
+ * Registers every query's handler. A query runs with its own `InsideTurn`
+ * marker, so a command or query call from it is a defect instead of a write,
+ * and its capabilities die once it returns or from another fiber. A watched
+ * run records what it reads; a `watch: true` handler gets no layer services.
+ */
+export const queriesOf = ({ descriptor, Read, handlers, services, actors, }) => Effect.gen(function* () {
+    const registered = new Map();
+    for (const member of descriptor.queries) {
+        const handle = handlers[member.tag];
+        if (handle === undefined)
+            return yield* Effect.die(new Error(`Missing query handler ${member.tag}`));
+        const { decodePayload, encodeSuccess, isError, encodeError } = descriptor.codecs.get(member.tag);
+        const watch = descriptor.watches.has(member.tag);
+        registered.set(member.tag, {
+            watch,
+            run: Effect.fnUntraced(function* (request, rows, cursor, readEvents, reads) {
+                const { state } = yield* descriptor.state.decodeStored(rows);
+                let open = true;
+                const query = Symbol();
+                const owner = Fiber.getCurrent();
+                const escaped = (capability) => Effect.gen(function* () {
+                    if (!open || (yield* InsideTurn) !== query)
+                        return yield* Effect.die(new Error(`${capability} capability escaped its query`));
+                    if (Fiber.getCurrent() !== owner)
+                        return yield* Effect.die(new Error(`${capability} capability used from a fiber other than its query's; timeout, race, and concurrent combinators run on other fibers`));
+                });
+                const access = yield* actors.tables({
+                    ref: request.ref,
+                    placement: descriptor.placement,
+                    tables: descriptor.tables,
+                    guard: escaped("Table"),
+                }, false);
+                const blob = yield* actors.blobs({
+                    ref: request.ref,
+                    placement: descriptor.placement,
+                    blobs: descriptor.blobs,
+                    guard: escaped("Blob"),
+                    maxBytes: descriptor.policy.blobMaxBytes,
+                    maxEntries: descriptor.policy.blobMaxEntries,
+                    timeoutMs: descriptor.policy.executionMs,
+                }, false);
+                const context = {
+                    id: request.ref.id,
+                    ref: request.ref,
+                    caller: request.caller,
+                    principal: principal(request.caller),
+                    state: Object.freeze(state),
+                    cursor,
+                    events: eventsWith({ descriptor, readEvents }),
+                    rows: access.rows,
+                    group: access.group,
+                    blob: blob,
+                    follow: () => Stream.die(new Error("read.follow is only available in stream handlers")),
+                    progress: () => Stream.die(new Error("Progress is only available in stream handlers")),
+                };
+                return yield* Effect.gen(function* () {
+                    const input = yield* decodePayload(request.payload).pipe(Effect.orDie);
+                    const output = yield* handle(input.value);
+                    const value = yield* encodeSuccess({ value: output }).pipe(Effect.orDie);
+                    return Outcome.cases.Success.make({ value });
+                }).pipe(Effect.catch(Effect.fnUntraced(function* (error) {
+                    if (!isError(error))
+                        return yield* Effect.die(error);
+                    const value = yield* encodeError(error).pipe(Effect.orDie);
+                    return Outcome.cases.Failure.make({ value });
+                })), Effect.catchDefect((cause) => Effect.succeed(Outcome.cases.Defect.make({ cause }))), Effect.ensuring(Effect.sync(() => {
+                    open = false;
+                })), Effect.provideService(Read, reads === undefined ? context : recordingRead(context, reads)), Effect.provideContext(watch ? Context.empty() : services), Effect.provideService(InsideTurn, query));
+            }),
+        });
+    }
+    return registered;
+});
+/**
+ * A stream member's live feed for one subscriber. It runs on the activation
+ * with its own `InsideTurn` marker and `InStream`, and its capabilities die
+ * once the stream ends. `read.progress` reaches only jobs its member lists.
+ */
+export const streamOf = ({ descriptor, Read, member, handle, services, actors, }) => {
+    const { decodePayload, encodeSuccess, isError, encodeError } = descriptor.codecs.get(member.tag);
+    const progressCodecs = new Map((member.progress?.jobs ?? []).map((job) => [
+        job.tag,
+        {
+            job: Schema.decodeEffect(Schema.fromJsonString(Schema.toCodecJson(job))),
+            frame: Schema.decodeEffect(Schema.fromJsonString(Schema.toCodecJson(job.progress))),
+        },
+    ]));
+    return {
+        progress: new Set(progressCodecs.keys()),
+        run: (payload, input) => Stream.unwrap(Effect.gen(function* () {
+            const { state } = yield* descriptor.state.decodeStored(input.state);
+            let open = true;
+            const stream = Symbol();
+            const guard = (capability) => open
+                ? Effect.void
+                : Effect.die(new Error(`${capability} capability escaped its stream`));
+            const access = yield* actors.tables({
+                ref: input.ref,
+                placement: descriptor.placement,
+                tables: descriptor.tables,
+                guard: guard("Table"),
+            }, false);
+            const blob = yield* actors.blobs({
+                ref: input.ref,
+                placement: descriptor.placement,
+                blobs: descriptor.blobs,
+                guard: guard("Blob"),
+                maxBytes: descriptor.policy.blobMaxBytes,
+                maxEntries: descriptor.policy.blobMaxEntries,
+                timeoutMs: descriptor.policy.executionMs,
+            }, false);
+            const context = {
+                id: input.ref.id,
+                ref: input.ref,
+                caller: input.caller,
+                principal: principal(input.caller),
+                state: Object.freeze(state),
+                cursor: input.cursor,
+                events: eventsWith({
+                    descriptor,
+                    readEvents: input.events,
+                }),
+                rows: access.rows,
+                group: access.group,
+                blob: blob,
+                follow: ((event, options) => descriptor.events.get(event.identifier) !== event
+                    ? Stream.die(new Error(`Undeclared event: ${event.identifier}`))
+                    : input
+                        .follow(event.identifier, options?.after)
+                        .pipe(Stream.mapEffect((stored) => entryOf(descriptor, event, stored)))),
+                progress: ((job, options) => {
+                    const codecs = progressCodecs.get(job.tag);
+                    if (codecs === undefined || member.progress?.jobs.includes(job) !== true)
+                        return Stream.die(new Error(`Stream ${member.tag} does not list progress of ${job.tag}`));
+                    return input.progress(job.tag, options?.jobId).pipe(Stream.mapEffect((stored) => Effect.gen(function* () {
+                        const entry = {
+                            jobId: stored.jobId,
+                            job: (yield* codecs.job(stored.job)),
+                            attempt: stored.attempt,
+                            seq: stored.seq,
+                            frame: (yield* codecs.frame(stored.frame)),
+                        };
+                        return entry;
+                    }).pipe(Effect.orDie)));
+                }),
+            };
+            const { value } = yield* decodePayload(payload).pipe(Effect.orDie);
+            return handle(value).pipe(Stream.mapEffect((output) => encodeSuccess({ value: output }).pipe(Effect.orDie)), Stream.catch((error) => isError(error)
+                ? Stream.fromEffect(Effect.flatMap(encodeError(error).pipe(Effect.orDie), (failure) => Effect.fail({ failure })))
+                : Stream.die(error)), Stream.ensuring(Effect.sync(() => (open = false))), Stream.provideService(Read, context), Stream.provideService(InStream, { stream }), Stream.provideContext(services), Stream.provideService(CurrentCaller, input.caller), Stream.provideService(Tenant, input.ref.tenant), Stream.provideService(InsideTurn, stream));
+        })),
+    };
+};

package/dist/actor/served.d.ts

@@ -0,0 +1,120 @@
+import { Effect, type Result, Schema } from "effect";
+import { type DeclaredError, type MemberKind, type ValueSchema } from "../members/command.ts";
+import type { ProgressJob } from "../members/job.ts";
+/** A public member as a served endpoint sees it: wire schemas and the runtime's payload codec. */
+export interface ServedMember {
+    readonly kind: MemberKind;
+    readonly tag: string;
+    readonly input: ValueSchema;
+    readonly output: ValueSchema;
+    readonly errors: ReadonlyArray<DeclaredError>;
+    /** Decodes a JSON request body (`undefined` when empty) into the runtime payload. */
+    readonly payload: (body: Schema.Json | undefined) => Effect.Effect<string, Schema.SchemaError>;
+    /** Status per declared error, in declaration order. */
+    readonly failureStatus: (value: string) => Effect.Effect<number, Schema.SchemaError>;
+    /** A reducer's pure transition, which a client applies before its receipt arrives. */
+    readonly reducer: OptimisticReducer | undefined;
+    /** True for a query declared `watch: true`, which is also served as a watch. */
+    readonly watch: boolean;
+}
+/** An actor's decoded state. */
+export type StateValue = Schema.Struct.Type<Schema.Struct.Fields>;
+/** What a client needs to run a reducer on its own copy of committed state. */
+export interface OptimisticReducer {
+    /** The actor's state schema. */
+    readonly state: ValueSchema & {
+        readonly Type: StateValue;
+    };
+    readonly reduce: (state: StateValue, input: ValueSchema["Type"]) => Result.Result<StateValue, unknown>;
+    /**
+     * True for a batched reducer, which replies nothing, so its receipt carries
+     * no committed state. The field keeps its served name for the client.
+     */
+    readonly commutative: boolean;
+}
+/** A connection member as a served WebSocket route sees it. */
+export interface ServedConnection {
+    readonly tag: string;
+    readonly params: ValueSchema;
+    readonly server: ValueSchema;
+    readonly client: ValueSchema;
+    readonly errors: ReadonlyArray<DeclaredError>;
+    /** False when frames carry no cursors, so clients always resync from state. */
+    readonly stampCursor: boolean;
+    /** Decodes a `hello` frame's `params` (`undefined` when absent) into the runtime's encoding. */
+    readonly openParams: (json: Schema.Json | undefined) => Effect.Effect<string, Schema.SchemaError>;
+    /** Decodes a client member frame into the runtime's encoding. */
+    readonly clientFrame: (json: Schema.Json) => Effect.Effect<string, Schema.SchemaError>;
+    /** A runtime-encoded server frame as the JSON value a client reads. */
+    readonly serverFrame: (encoded: string) => Effect.Effect<Schema.Json, Schema.SchemaError>;
+    /** A declared `open` failure, as the runtime stores it, as the JSON a client reads. */
+    readonly openFailure: (encoded: string) => Effect.Effect<Schema.Json, Schema.SchemaError>;
+    /** The progress schema of each job whose executor progress this member receives, by tag. */
+    readonly progress: ReadonlyMap<string, ValueSchema>;
+}
+/** What `Actor.serve` and `X.client` need of one actor definition. */
+export interface ServedDefinition {
+    /** The actor type's name, its path segment in served routes. */
+    readonly name: string;
+    /** How a client addresses instances: by id, as the singleton, or by an id it mints. */
+    readonly key: "keyed" | "singleton" | "minted";
+    /** Decodes an id path segment into the runtime's id; fails when it breaks the key schema. */
+    readonly decodeId: (id: string) => Effect.Effect<string, Schema.SchemaError>;
+    /** The path segment a client sends for a typed id. */
+    readonly encodeId: (id: string) => Effect.Effect<string, Schema.SchemaError>;
+    /** `api` members only; `internal` commands are never served. */
+    readonly members: ReadonlyArray<ServedMember>;
+    /** Connection members, served as WebSocket upgrades. */
+    readonly connections: ReadonlyArray<ServedConnection>;
+    /** Tags of the events served as SSE event feeds. */
+    readonly feeds: ReadonlyArray<string>;
+    /** Names of the declared content blobs, served for download and grants. */
+    readonly contents: ReadonlyArray<string>;
+    /** `Actor.stream` members, served over SSE; each element is one encoded `success` value. */
+    readonly streams: ReadonlyArray<ServedMember>;
+}
+/** The HTTP status a served response uses for `error`: its `httpApiStatus`, or 422. */
+export declare const declaredStatus: (error: DeclaredError) => number;
+/** Rejects declared errors a served response could not tell apart from a framework one. */
+export declare const checkDeclaredErrors: (member: {
+    readonly tag: string;
+    readonly error: DeclaredError;
+}) => void;
+/** A member and the codecs `servedMember` builds its served view from. */
+interface ServedMemberSource {
+    readonly member: {
+        readonly kind: MemberKind;
+        readonly tag: string;
+        readonly payload: ValueSchema;
+        readonly success: ValueSchema;
+        readonly error: DeclaredError;
+        readonly state?: {
+            readonly fields: Readonly<Record<string, ValueSchema>>;
+        };
+        /** Method syntax keeps the parameters bivariant, so every reducer's `reduce` fits. */
+        reduce?(state: StateValue, payload: ValueSchema["Type"]): Result.Result<StateValue, unknown>;
+        readonly batch?: object | undefined;
+        readonly watch?: boolean;
+    };
+    readonly codecs: {
+        readonly encodePayload: (value: {
+            readonly value: unknown;
+        }) => Effect.Effect<string, Schema.SchemaError>;
+        readonly decodeError: (value: string) => Effect.Effect<DeclaredError["Type"], Schema.SchemaError>;
+    };
+}
+/** A public member's served view: its wire schemas, body decoder, and failure statuses. */
+export declare const servedMember: ({ member, codecs }: ServedMemberSource) => ServedMember;
+/** A connection member's served view: its WebSocket frame codecs and progress schemas. */
+export declare const servedConnection: (member: {
+    readonly tag: string;
+    readonly payload: ValueSchema;
+    readonly server: ValueSchema;
+    readonly client: ValueSchema;
+    readonly error: DeclaredError;
+    readonly stampCursor: boolean;
+    readonly progress: {
+        readonly jobs: ReadonlyArray<ProgressJob>;
+    } | undefined;
+}) => ServedConnection;
+export {};

package/dist/actor/served.js

@@ -0,0 +1,72 @@
+import { Effect, Schema, SchemaAST } from "effect";
+import { declaredErrors, } from "../members/command.js";
+/** Statuses the served protocol assigns to framework outcomes; a declared failure can't claim one. */
+const RESERVED_STATUSES = new Set([
+    400, 401, 403, 404, 409, 410, 413, 415, 429,
+]);
+/** Error tags the served protocol uses for framework outcomes; a declared error can't claim one. */
+const RESERVED_TAGS = new Set(["ActorError", "Defect"]);
+/** The HTTP status of a declared failure whose error sets no `httpApiStatus`. */
+const DECLARED_FAILURE_STATUS = 422;
+/** The HTTP status a served response uses for `error`: its `httpApiStatus`, or 422. */
+export const declaredStatus = (error) => SchemaAST.resolveAt("httpApiStatus")(error.ast) ?? DECLARED_FAILURE_STATUS;
+/** Rejects declared errors a served response could not tell apart from a framework one. */
+export const checkDeclaredErrors = (member) => {
+    for (const error of declaredErrors(member.error)) {
+        const tag = SchemaAST.resolveIdentifier(error.ast);
+        if (tag !== undefined && RESERVED_TAGS.has(tag))
+            throw new Error(`${member.tag} declares an error tagged ${tag}, which is reserved`);
+        const status = declaredStatus(error);
+        if (!Number.isInteger(status) || status < 400 || status > 499 || RESERVED_STATUSES.has(status))
+            throw new Error(`${member.tag} declares httpApiStatus ${status}; use an unreserved 4xx`);
+    }
+};
+/** A public member's served view: its wire schemas, body decoder, and failure statuses. */
+export const servedMember = ({ member, codecs }) => {
+    const decodeBody = Schema.decodeUnknownEffect(Schema.toCodecJson(member.payload));
+    const errors = declaredErrors(member.error);
+    const statuses = errors.map((error) => [Schema.is(error), declaredStatus(error)]);
+    return {
+        kind: member.kind,
+        tag: member.tag,
+        input: member.payload,
+        output: member.success,
+        errors,
+        payload: (body) => decodeBody(body ?? null).pipe(Effect.flatMap((value) => codecs.encodePayload({ value }))),
+        failureStatus: (value) => codecs
+            .decodeError(value)
+            .pipe(Effect.map((error) => statuses.find(([is]) => is(error))?.[1] ?? DECLARED_FAILURE_STATUS)),
+        reducer: member.kind === "reducer" && member.state !== undefined && member.reduce !== undefined
+            ? {
+                state: Schema.Struct(member.state.fields),
+                reduce: member.reduce.bind(member),
+                commutative: member.batch !== undefined,
+            }
+            : undefined,
+        watch: member.kind === "query" && member.watch === true,
+    };
+};
+const ValueJson = Schema.fromJsonString(Schema.Struct({ value: Schema.optionalKey(Schema.Json) }));
+const decodeValueJson = Schema.decodeUnknownEffect(ValueJson);
+const decodeJsonString = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Json));
+/** A connection member's served view: its WebSocket frame codecs and progress schemas. */
+export const servedConnection = (member) => {
+    const valueOf = (schema) => Schema.encodeEffect(Schema.fromJsonString(Schema.toCodecJson(Schema.Struct({ value: schema }))));
+    const decodeParams = Schema.decodeUnknownEffect(Schema.toCodecJson(member.payload));
+    const encodeParams = valueOf(member.payload);
+    const decodeClient = Schema.decodeUnknownEffect(Schema.toCodecJson(member.client));
+    const encodeClient = valueOf(member.client);
+    return {
+        tag: member.tag,
+        params: member.payload,
+        server: member.server,
+        client: member.client,
+        errors: declaredErrors(member.error),
+        stampCursor: member.stampCursor,
+        openParams: (json) => decodeParams(json ?? null).pipe(Effect.flatMap((value) => encodeParams({ value }))),
+        clientFrame: (json) => decodeClient(json).pipe(Effect.flatMap((value) => encodeClient({ value }))),
+        serverFrame: (encoded) => decodeValueJson(encoded).pipe(Effect.map(({ value }) => value ?? null)),
+        openFailure: decodeJsonString,
+        progress: new Map((member.progress?.jobs ?? []).map((job) => [job.tag, job.progress])),
+    };
+};

package/dist/actor/turns.d.ts

@@ -0,0 +1,13 @@
+import { Context, Effect } from "effect";
+import type { InternalActors } from "../runtime/actors.ts";
+import type { RegisteredCommand } from "../runtime/members.ts";
+import type { Handler } from "./codecs.ts";
+import { type Descriptor } from "./descriptor.ts";
+/** Every command and reducer turn of one activation, keyed by tag. */
+export declare const turnsOf: ({ descriptor, Turn, handlers, services, actors, }: {
+    readonly descriptor: Descriptor;
+    readonly Turn: Context.Key<object, object>;
+    readonly handlers: Readonly<Record<string, Handler>>;
+    readonly services: Context.Context<never>;
+    readonly actors: InternalActors["Service"];
+}) => Effect.Effect<ReadonlyMap<string, RegisteredCommand>, never, never>;