@fungi.computer/carrier 0.0.0-stage → 0.1.0

package/dist/post-postgres.js

@@ -0,0 +1,79 @@
+import * as Schema from "effect/Schema";
+import { purgePostgresQueues, } from "@fungi.computer/watchdog/postgres";
+import { jobSelect, openSqlPost, postSchema, preparePost, } from "./internal/post-sql.js";
+/** Carrier-owned PostgreSQL schema, applied by the deployment migration owner. */
+export const postPostgresSchema = postSchema(true);
+const Job = Schema.Struct({
+    job_id: Schema.String,
+    queue_name: Schema.String,
+    lane: Schema.String,
+    priority: Schema.Number,
+    payload_json: Schema.fromJsonString(Schema.Unknown),
+});
+/** Bind the Post registry to a PostgreSQL owner and the shared delivery engine. */
+export function createPostgresPost(options) {
+    const enqueue = async (client, source) => {
+        const native = source;
+        const rows = (await client.query(native.text, [...native.values]))
+            .rows;
+        for (const raw of rows) {
+            const job = Schema.decodeUnknownSync(Job)(raw);
+            await options.watchdog.enqueue(client, {
+                jobId: job.job_id,
+                queue: job.queue_name,
+                lane: job.lane,
+                priority: job.priority,
+                payload: job.payload_json,
+                state: "queued",
+            });
+        }
+    };
+    const runtime = openSqlPost({
+        query: async (statement) => (await options.database.query(statement.text, [
+            ...statement.values,
+        ])).rows,
+        commit: async (statements, key, jobId) => {
+            const client = await options.database.connect();
+            try {
+                await client.query("BEGIN");
+                for (const statement of statements)
+                    await client.query(statement.text, [...statement.values]);
+                await enqueue(client, jobSelect(key, true, jobId));
+                await client.query("COMMIT");
+            }
+            catch (error) {
+                await client.query("ROLLBACK");
+                throw error;
+            }
+            finally {
+                client.release();
+            }
+        },
+    }, options);
+    return {
+        ...runtime,
+        send: async (client, envelope) => {
+            const prepared = preparePost(options, envelope);
+            await client.query(prepared.statement.text, [
+                ...prepared.statement.values,
+            ]);
+            await enqueue(client, jobSelect(prepared.key, true));
+        },
+    };
+}
+/** Purge selected recipient queues, including all envelopes and attempts.
+ * The trusted SELECT yields queue_name from producer/envelope facts, not job state. */
+export function purgePostgresPost(source) {
+    return [
+        // Serialize erasure with send/retry before taking the jobs' deletion snapshot.
+        {
+            text: `UPDATE carrier_post_rows SET post_key=post_key WHERE queue_name IN (SELECT queue_name FROM (${source.text}) AS erasure)`,
+            values: source.values,
+        },
+        ...purgePostgresQueues(source),
+        {
+            text: `DELETE FROM carrier_post_rows WHERE queue_name IN (SELECT queue_name FROM (${source.text}) AS erasure)`,
+            values: source.values,
+        },
+    ];
+}

package/dist/post.d.ts

@@ -0,0 +1,189 @@
+import * as Schema from "effect/Schema";
+import { type PostDeliveryResult } from "./internal/post-contract.js";
+export { PostError, PostDeliveryResultSchema, } from "./internal/post-contract.js";
+export type { PostDeliveryResult } from "./internal/post-contract.js";
+import type { WatchdogRunningJob, WatchdogSqliteOwner, WatchdogRuntime, WatchdogTransactionalProjection } from "@fungi.computer/watchdog";
+export { makePostOutbox, postOutboxPending } from "./post-outbox.js";
+export type { PostOutbox, PostOutboxStore } from "./post-outbox.js";
+/** Wire envelope parsed at the durable row and receiver boundaries. */
+export declare const PostEnvelopeSchema: Schema.Struct<{
+    readonly key: Schema.String;
+    readonly kind: Schema.String;
+    readonly address: Schema.Unknown;
+    readonly event: Schema.Unknown;
+}>;
+/** Persisted Post row parser. */
+export declare const PostRowSchema: Schema.fromJsonString<Schema.Union<readonly [Schema.Struct<{
+    readonly state: Schema.Literal<"pending">;
+    readonly envelope: Schema.Struct<{
+        readonly key: Schema.String;
+        readonly kind: Schema.String;
+        readonly address: Schema.Unknown;
+        readonly event: Schema.Unknown;
+    }>;
+    readonly attempts: Schema.Int;
+    readonly nextAttemptAt: Schema.Number;
+    readonly jobId: Schema.optional<Schema.String>;
+    readonly delivery: Schema.optional<Schema.Struct<{
+        readonly key: Schema.String;
+        readonly kind: Schema.String;
+        readonly address: Schema.Unknown;
+        readonly event: Schema.Unknown;
+    }>>;
+    readonly nextKey: Schema.optional<Schema.String>;
+}>, Schema.Struct<{
+    readonly state: Schema.Literal<"delivered">;
+    readonly receipt: Schema.optional<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    readonly nextKey: Schema.optional<Schema.String>;
+}>, Schema.Struct<{
+    readonly state: Schema.Literal<"dead">;
+    readonly envelope: Schema.Struct<{
+        readonly key: Schema.String;
+        readonly kind: Schema.String;
+        readonly address: Schema.Unknown;
+        readonly event: Schema.Unknown;
+    }>;
+    readonly attempts: Schema.Int;
+    readonly reason: Schema.Literals<readonly ["refused", "exhausted"]>;
+    readonly receipt: Schema.optional<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    readonly delivery: Schema.optional<Schema.Struct<{
+        readonly key: Schema.String;
+        readonly kind: Schema.String;
+        readonly address: Schema.Unknown;
+        readonly event: Schema.Unknown;
+    }>>;
+    readonly nextKey: Schema.optional<Schema.String>;
+}>]>>;
+/** One addressed event identified by the producer's stable key. */
+export type PostEnvelope = Schema.Schema.Type<typeof PostEnvelopeSchema>;
+/** Pending row, terminal receipt, or dead letter. */
+export type PostRow = Schema.Schema.Type<typeof PostRowSchema>;
+/** Schema-correlated ordinary events or prepared delivery facts. */
+export type PostRoute<A, E, D = E, AI = A, EI = E, DI = EI> = Readonly<{
+    /** Fixed registry label shared by routes to one recipient namespace. */
+    addressKind: string;
+    /** Address parser for this kind. */
+    address: Schema.Codec<A, AI>;
+    /** Staged event parser for this kind. */
+    event: Schema.Codec<E, EI>;
+    /** Stable Durable Object name for one address. */
+    name: (address: A) => string;
+    /** Durable Object namespace for this kind. */
+    namespace: Readonly<{
+        /** Obtain the addressed Durable Object. */
+        getByName: (name: string) => Readonly<{
+            /** Idempotently apply one addressed envelope. */
+            deliver: (envelope: PostEnvelope) => Promise<PostDeliveryResult>;
+        }>;
+    }>;
+}> & (Readonly<{
+    /** Prepare one fact before receiver I/O; its callbacks consume that fact. */
+    prepare: Readonly<{
+        /** Parser for the prepared delivery fact. */
+        event: Schema.Codec<D, DI>;
+        /** Resolve the staged intent into a delivery fact. */
+        run: (address: A, intent: E, signal: AbortSignal) => Promise<D>;
+    }>;
+    /** Acknowledge delivery in the producer's receipt transaction. */
+    onDelivered?: (address: A, event: D) => void;
+    /** Commit the receiver cursor in the producer's receipt transaction. */
+    onCursor?: (address: A, event: D, cursor: number) => void;
+    /** Revoke a subscription after permanent refusal. */
+    onRefused?: (address: A, event: D) => void;
+}> | Readonly<{
+    /** An ordinary event is also its delivery fact. */
+    prepare?: undefined;
+    /** Acknowledge delivery in the producer's receipt transaction. */
+    onDelivered?: (address: A, event: E) => void;
+    /** Commit the receiver cursor in the producer's receipt transaction. */
+    onCursor?: (address: A, event: E, cursor: number) => void;
+    /** Revoke a subscription after permanent refusal. */
+    onRefused?: (address: A, event: E) => void;
+}>);
+/** Runtime operations that preserve the route's schema evidence. */
+export type PostRegistryRoute = Readonly<{
+    /** Recipient namespace identity used for per-address ordering. */
+    addressKind: string;
+    /** Parser for this address kind. */
+    address: Schema.Codec<unknown, unknown>;
+    /** Parser for this event kind. */
+    event: Schema.Codec<unknown, unknown>;
+    /** Encode a producer's domain values with this route's schemas. */
+    encodeEnvelope: (envelope: PostEnvelope) => PostEnvelope;
+    /** Decode a prepared wire fact, or the ordinary event when no preparation is needed. */
+    parseDelivery: (envelope: PostEnvelope) => PostEnvelope;
+    /** Prepare the wire fact before receiver I/O. */
+    prepareEnvelope?: ((envelope: PostEnvelope, signal: AbortSignal) => Promise<PostEnvelope>) | undefined;
+    /** Acknowledge producer domain state in the receipt transaction. */
+    recordDelivered?: ((envelope: PostEnvelope) => void) | undefined;
+    /** Decode the address and return its stable Durable Object name. */
+    nameOf: (envelope: Pick<PostEnvelope, "address">) => string;
+    /** Durable Object namespace. */
+    namespace: PostRoute<never, never>["namespace"];
+    /** Apply a typed receiver cursor in the producer transaction. */
+    recordCursor?: ((envelope: PostEnvelope, cursor: number) => void) | undefined;
+    /** Apply a typed permanent refusal in the producer transaction. */
+    recordRefused?: ((envelope: PostEnvelope) => void) | undefined;
+}>;
+/** Preserve each route's inferred address and event types in a registry. */
+export declare function definePostRoute<A, E, AI = A, EI = E>(route: Extract<PostRoute<A, E, E, AI, EI, EI>, {
+    prepare?: undefined;
+}>): PostRoute<A, E, E, AI, EI, EI> & Omit<PostRegistryRoute, "address" | "event">;
+export declare function definePostRoute<A, E, D, AI = A, EI = E, DI = EI>(route: Extract<PostRoute<A, E, D, AI, EI, DI>, {
+    prepare: unknown;
+}>): PostRoute<A, E, D, AI, EI, DI> & Omit<PostRegistryRoute, "address" | "event">;
+/** One producer's Post operations. */
+export type PostRuntime<R extends Record<string, PostRegistryRoute>> = Readonly<{
+    /** Write a row and Watchdog job in the producer's own transaction. */
+    send: <K extends keyof R & string>(input: Readonly<{
+        key: string;
+        kind: K;
+        address: Schema.Schema.Type<R[K]["address"]>;
+        event: Schema.Schema.Type<R[K]["event"]>;
+    }>) => void;
+    /** Run as the Watchdog executor for a claimed Post job. */
+    execute: (job: WatchdogRunningJob) => Promise<Readonly<{
+        kind: "completed";
+    }>>;
+    /** Recover settled delivery jobs and enqueue due retries after a wake. */
+    enqueueDue: (limit?: number, afterKey?: string) => Promise<string | undefined>;
+    /** Read an ordered page of refused or exhausted keys for operators. */
+    deadLetters: (limit?: number, afterKey?: string) => Readonly<{
+        letters: readonly Readonly<{
+            key: string;
+            reason: "refused" | "exhausted";
+            envelope: PostEnvelope;
+            attempts: number;
+        }>[];
+        nextCursor: string | undefined;
+    }>;
+    /** The latest staged event of one kind for an address, including its terminal receipt. */
+    latest: <K extends keyof R & string>(kind: K, address: Schema.Schema.Type<R[K]["address"]>) => Readonly<{
+        key: string;
+        row: PostRow;
+    }> | undefined;
+    /** Requeue a failed event or expedite its settled retry, preserving its prepared fact. */
+    retry: (key: string) => Promise<void>;
+    /** Inspect one producer-local row or receipt. */
+    read: (key: string) => PostRow | undefined;
+    /** Earliest pending queue head, including a settled job waiting to retry. */
+    nextWake: () => number | null;
+}>;
+/** Decode at both persisted and DO boundaries with the route's Effect Schema. */
+export declare function createPost<R extends Record<string, PostRegistryRoute>>(options: Readonly<{
+    routes: R;
+    owner: WatchdogSqliteOwner;
+    transactional: WatchdogTransactionalProjection;
+    readJob: WatchdogRuntime["read"];
+    now: () => number;
+    scheduleWake: (at: number) => Promise<void>;
+}>): PostRuntime<R>;
+/** Consumer admission runs inside the receiver's own SQLite transaction. */
+export declare function admitPost<E, I>(options: Readonly<{
+    key: string;
+    event: unknown;
+    schema: Schema.Codec<E, I>;
+    hasReceipt: (key: string) => boolean;
+    apply: (event: E) => PostDeliveryResult;
+    putReceipt: (key: string) => void;
+}>): PostDeliveryResult;