@fungi.computer/carrier 0.0.0-stage → 0.1.0

package/dist/post.js

@@ -0,0 +1,437 @@
+import * as Schema from "effect/Schema";
+import { PostError, } from "./internal/post-contract.js";
+export { PostError, PostDeliveryResultSchema, } from "./internal/post-contract.js";
+import { deliverPost, postDisposition, deliveryReceipt, } from "./internal/post-execution.js";
+import { defineIdFamily } from "@fungi.computer/cairn";
+import { backoffDelay } from "@fungi.computer/almanac";
+import { maxDeliveryAttempts, postRetryPolicy } from "./post-outbox.js";
+export { makePostOutbox, postOutboxPending } from "./post-outbox.js";
+const Key = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(256));
+const JobPayload = Schema.Struct({ postKey: Key });
+const PageLimit = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1), Schema.isLessThanOrEqualTo(64));
+const ids = defineIdFamily({
+    family: "post",
+    version: 1,
+    kinds: { work: { prefix: "post_work" } },
+});
+/** Wire envelope parsed at the durable row and receiver boundaries. */
+export const PostEnvelopeSchema = Schema.Struct({
+    key: Key,
+    kind: Key,
+    address: Schema.Unknown,
+    event: Schema.Unknown,
+});
+/** Persisted Post row parser. */
+export const PostRowSchema = Schema.fromJsonString(Schema.Union([
+    Schema.Struct({
+        state: Schema.Literal("pending"),
+        envelope: PostEnvelopeSchema,
+        attempts: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+        nextAttemptAt: Schema.Number.check(Schema.isGreaterThanOrEqualTo(0)),
+        jobId: Schema.optional(Key),
+        delivery: Schema.optional(PostEnvelopeSchema),
+        nextKey: Schema.optional(Key),
+    }),
+    Schema.Struct({
+        state: Schema.Literal("delivered"),
+        receipt: Schema.optional(Schema.Json),
+        nextKey: Schema.optional(Key),
+    }),
+    Schema.Struct({
+        state: Schema.Literal("dead"),
+        envelope: PostEnvelopeSchema,
+        attempts: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+        reason: Schema.Literals(["refused", "exhausted"]),
+        receipt: Schema.optional(Schema.Json),
+        delivery: Schema.optional(PostEnvelopeSchema),
+        nextKey: Schema.optional(Key),
+    }),
+]));
+function receiptOperations(address, event, hooks) {
+    const { onCursor, onRefused, onDelivered } = hooks;
+    const decodeAddress = Schema.decodeUnknownSync(address);
+    const decodeEvent = Schema.decodeUnknownSync(event);
+    return {
+        recordCursor: onCursor === undefined
+            ? undefined
+            : (envelope, cursor) => {
+                onCursor(decodeAddress(envelope.address), decodeEvent(envelope.event), cursor);
+            },
+        recordRefused: onRefused === undefined
+            ? undefined
+            : (envelope) => {
+                onRefused(decodeAddress(envelope.address), decodeEvent(envelope.event));
+            },
+        recordDelivered: onDelivered === undefined
+            ? undefined
+            : (envelope) => {
+                onDelivered(decodeAddress(envelope.address), decodeEvent(envelope.event));
+            },
+        parseDelivery: (envelope) => ({
+            ...envelope,
+            address: Schema.encodeSync(address)(decodeAddress(envelope.address)),
+            event: Schema.encodeSync(event)(decodeEvent(envelope.event)),
+        }),
+    };
+}
+export function definePostRoute(route) {
+    const delivery = route.prepare === undefined
+        ? receiptOperations(route.address, route.event, route)
+        : receiptOperations(route.address, route.prepare.event, route);
+    const prepare = route.prepare;
+    return {
+        ...route,
+        ...delivery,
+        addressKind: Schema.decodeUnknownSync(Key)(route.addressKind),
+        prepareEnvelope: prepare === undefined
+            ? undefined
+            : async (envelope, signal) => ({
+                ...envelope,
+                event: Schema.encodeUnknownSync(prepare.event)(await prepare.run(Schema.decodeUnknownSync(route.address)(envelope.address), Schema.decodeUnknownSync(route.event)(envelope.event), signal)),
+            }),
+        encodeEnvelope: (envelope) => ({
+            ...envelope,
+            address: Schema.encodeUnknownSync(route.address)(envelope.address),
+            event: Schema.encodeUnknownSync(route.event)(envelope.event),
+        }),
+        nameOf: (envelope) => route.name(Schema.decodeUnknownSync(route.address)(envelope.address)),
+    };
+}
+const StoredRow = Schema.Struct({ key: Schema.String, value: Schema.String });
+const DueRow = Schema.Struct({
+    due: Schema.NullOr(Schema.Number.check(Schema.isGreaterThanOrEqualTo(0))),
+});
+const openPostStore = (owner) => {
+    const sql = owner.sql;
+    owner.transactionSync(() => {
+        sql.exec("CREATE TABLE IF NOT EXISTS carrier_post_rows (key TEXT PRIMARY KEY, value TEXT NOT NULL)");
+    });
+    return {
+        commit: (mutation) => owner.transactionSync(mutation),
+        read: (key) => {
+            const row = sql
+                .exec("SELECT key,value FROM carrier_post_rows WHERE key=?", key)
+                .toArray()[0];
+            return row === undefined
+                ? undefined
+                : Schema.decodeUnknownSync(StoredRow)(row).value;
+        },
+        put: (key, value) => {
+            sql.exec("INSERT INTO carrier_post_rows VALUES (?,?) ON CONFLICT(key) DO UPDATE SET value=excluded.value", key, value);
+        },
+        list: (limit, afterKey = "") => Schema.decodeUnknownSync(Schema.Array(StoredRow))(sql
+            .exec("SELECT key,value FROM carrier_post_rows WHERE key LIKE 'post:%' AND key>? ORDER BY key LIMIT ?", afterKey, limit)
+            .toArray()),
+        nextWake: () => Schema.decodeUnknownSync(DueRow)(sql
+            .exec("SELECT MIN(json_extract(value,'$.nextAttemptAt')) AS due FROM carrier_post_rows WHERE key LIKE 'post:%' AND json_extract(value,'$.state')='pending' AND json_type(value,'$.jobId')='text'")
+            .toArray()[0]).due,
+    };
+};
+/** Decode at both persisted and DO boundaries with the route's Effect Schema. */
+export function createPost(options) {
+    const store = openPostStore(options.owner);
+    const rowKey = (key) => `post:${key}`;
+    const tailKey = (queue) => `post-tail:${queue}`;
+    const headKey = (kind, queue) => `post-head:${JSON.stringify([kind, queue])}`;
+    const readRow = (key) => {
+        const raw = store.read(rowKey(key));
+        return raw === undefined
+            ? undefined
+            : Schema.decodeUnknownSync(PostRowSchema)(raw);
+    };
+    const nextWake = () => store.nextWake();
+    const putRow = (key, row) => {
+        store.put(rowKey(key), Schema.encodeSync(PostRowSchema)(row));
+    };
+    const routeFor = (envelope) => {
+        const route = options.routes[envelope.kind];
+        if (route === undefined)
+            throw new PostError("unknown address kind");
+        return route;
+    };
+    const queueOf = (envelope) => {
+        const route = routeFor(envelope);
+        return JSON.stringify([route.addressKind, route.nameOf(envelope)]);
+    };
+    const enqueueJob = (row) => {
+        const jobId = ids.work.generate();
+        putRow(row.envelope.key, { ...row, jobId });
+        options.transactional.enqueueAcceptedJob({
+            jobId,
+            queue: queueOf(row.envelope),
+            lane: "post",
+            priority: 0,
+            payload: { postKey: row.envelope.key },
+            state: "queued",
+        });
+    };
+    const send = (input) => {
+        const incoming = Schema.decodeUnknownSync(PostEnvelopeSchema)(input);
+        const route = routeFor(incoming);
+        const envelope = route.encodeEnvelope(incoming);
+        const existing = readRow(envelope.key);
+        if (existing !== undefined) {
+            if (existing.state !== "delivered" &&
+                JSON.stringify(existing.envelope) !== JSON.stringify(envelope))
+                throw new PostError("conflicting post key");
+            return;
+        }
+        const queue = queueOf(envelope);
+        const previousKey = store.read(tailKey(queue));
+        const previous = previousKey === undefined ? undefined : readRow(previousKey);
+        const row = {
+            state: "pending",
+            envelope,
+            attempts: 0,
+            nextAttemptAt: options.now(),
+        };
+        putRow(envelope.key, row);
+        if (previousKey !== undefined && previous?.state === "pending") {
+            putRow(previousKey, { ...previous, nextKey: envelope.key });
+        }
+        else {
+            enqueueJob(row);
+        }
+        store.put(tailKey(queue), envelope.key);
+        store.put(headKey(envelope.kind, queue), envelope.key);
+    };
+    const latest = (kind, address) => {
+        const route = options.routes[kind];
+        if (route === undefined)
+            throw new PostError("unknown address kind");
+        const queue = JSON.stringify([
+            route.addressKind,
+            route.nameOf({
+                address: Schema.encodeUnknownSync(route.address)(address),
+            }),
+        ]);
+        const key = store.read(headKey(kind, queue));
+        if (key === undefined)
+            return undefined;
+        const row = readRow(key);
+        if (row === undefined)
+            throw new PostError("latest delivery row is missing");
+        return { key, row };
+    };
+    const releaseNext = (nextKey) => {
+        if (nextKey === undefined)
+            return;
+        const next = readRow(nextKey);
+        if (next?.state === "pending" && next.jobId === undefined)
+            enqueueJob(next);
+    };
+    const finish = (key, row, terminal, metadata) => {
+        let receipt;
+        if (terminal.state === "dead") {
+            const dead = {
+                ...terminal,
+                envelope: row.envelope,
+                attempts: row.attempts,
+            };
+            receipt =
+                row.delivery === undefined ? dead : { ...dead, delivery: row.delivery };
+        }
+        else
+            receipt = terminal;
+        if (metadata !== undefined)
+            receipt = { ...receipt, receipt: metadata };
+        putRow(key, row.nextKey === undefined
+            ? receipt
+            : { ...receipt, nextKey: row.nextKey });
+        releaseNext(row.nextKey);
+    };
+    const execute = async (job) => {
+        const { postKey } = Schema.decodeUnknownSync(JobPayload)(job.payload);
+        const attempt = store.commit(() => {
+            const row = readRow(postKey);
+            if (row === undefined)
+                throw new PostError("delivery row is missing");
+            if (row.state !== "pending" || row.jobId !== job.jobId)
+                return undefined;
+            if (row.attempts >= maxDeliveryAttempts) {
+                finish(postKey, row, { state: "dead", reason: "exhausted" });
+                return undefined;
+            }
+            const attempts = row.attempts + 1;
+            const nextAttemptAt = options.now() + backoffDelay(attempts, postRetryPolicy);
+            const started = { ...row, attempts, nextAttemptAt };
+            // Preserve recovery evidence before invoking the receiver. A failed receipt
+            // write leaves this row available for retry after Watchdog settles the job.
+            putRow(postKey, started);
+            return started;
+        });
+        if (attempt === undefined)
+            return { kind: "completed" };
+        await options.scheduleWake(attempt.nextAttemptAt);
+        const route = routeFor(attempt.envelope);
+        const evidence = await deliverPost({
+            attempt,
+            route,
+            savePrepared: (envelope) => {
+                store.commit(() => {
+                    const current = readRow(postKey);
+                    if (current?.state !== "pending" || current.jobId !== job.jobId)
+                        throw new PostError("preparation superseded");
+                    putRow(postKey, { ...current, delivery: envelope });
+                });
+            },
+        });
+        let retryAt;
+        store.commit(() => {
+            // Another send may have linked a successor during the remote call.
+            const current = readRow(postKey);
+            if (current?.state !== "pending" || current.jobId !== job.jobId)
+                return;
+            const disposition = postDisposition(evidence, route, current.attempts, maxDeliveryAttempts);
+            if (disposition.state === "keep")
+                return;
+            if (disposition.state === "delivered") {
+                if (evidence.envelope === undefined)
+                    throw new PostError("missing delivered fact");
+                if (disposition.cursor !== undefined)
+                    route.recordCursor?.(evidence.envelope, disposition.cursor);
+                route.recordDelivered?.(evidence.envelope);
+                finish(postKey, current, { state: "delivered" }, deliveryReceipt(evidence));
+            }
+            else if (disposition.state === "dead") {
+                if (disposition.reason === "refused" && evidence.envelope !== undefined)
+                    route.recordRefused?.(evidence.envelope);
+                finish(postKey, current, disposition, deliveryReceipt(evidence));
+            }
+            else {
+                const due = options.now() + backoffDelay(current.attempts, postRetryPolicy);
+                if (due !== current.nextAttemptAt) {
+                    putRow(postKey, { ...current, nextAttemptAt: due });
+                    retryAt = due;
+                }
+            }
+        });
+        if (retryAt !== undefined)
+            await options.scheduleWake(retryAt);
+        return { kind: "completed" };
+    };
+    const enqueueDue = async (limit = 64, afterKey) => {
+        const pageSize = Schema.decodeUnknownSync(PageLimit)(limit);
+        const rows = store.list(pageSize, afterKey);
+        for (const stored of rows) {
+            const row = Schema.decodeUnknownSync(PostRowSchema)(stored.value);
+            if (row.state !== "pending" || row.jobId === undefined)
+                continue;
+            const work = await options.readJob(row.jobId);
+            if (work.status === "missing")
+                throw new PostError("delivery job is missing");
+            if (work.job.state !== "settled")
+                continue;
+            if (row.nextAttemptAt > options.now()) {
+                await options.scheduleWake(row.nextAttemptAt);
+                continue;
+            }
+            store.commit(() => {
+                const current = readRow(row.envelope.key);
+                if (current?.state !== "pending" || current.jobId !== row.jobId)
+                    return;
+                if (current.attempts >= maxDeliveryAttempts)
+                    finish(current.envelope.key, current, {
+                        state: "dead",
+                        reason: "exhausted",
+                    });
+                else
+                    enqueueJob(current);
+            });
+        }
+        return rows.length === pageSize ? rows.at(-1)?.key : undefined;
+    };
+    const retry = async (input) => {
+        const key = Schema.decodeUnknownSync(Key)(input);
+        const row = readRow(key);
+        if (row === undefined || row.state === "delivered")
+            return;
+        const work = row.state === "pending" && row.jobId !== undefined
+            ? await options.readJob(row.jobId)
+            : undefined;
+        if (work?.status === "missing")
+            throw new PostError("delivery job is missing");
+        if (work?.status === "found" && work.job.state !== "settled")
+            return;
+        store.commit(() => {
+            const current = readRow(key);
+            if (current === undefined || current.state === "delivered")
+                return;
+            if (current.state === "pending") {
+                if (row.state !== "pending" || current.jobId !== row.jobId)
+                    return;
+                const pending = {
+                    ...current,
+                    attempts: 0,
+                    nextAttemptAt: options.now(),
+                };
+                putRow(key, pending);
+                if (current.jobId !== undefined)
+                    enqueueJob(pending);
+            }
+            else {
+                const pending = {
+                    state: "pending",
+                    envelope: current.envelope,
+                    attempts: 0,
+                    nextAttemptAt: options.now(),
+                    delivery: current.delivery,
+                };
+                putRow(key, pending);
+                const queue = queueOf(pending.envelope);
+                const previousKey = store.read(tailKey(queue));
+                const previous = previousKey === undefined || previousKey === key
+                    ? undefined
+                    : readRow(previousKey);
+                if (previous?.state === "pending" && previousKey !== undefined)
+                    putRow(previousKey, { ...previous, nextKey: key });
+                else
+                    enqueueJob(pending);
+                store.put(tailKey(queue), key);
+            }
+        });
+        await options.scheduleWake(options.now());
+    };
+    const deadLetters = (limit = 64, afterKey) => {
+        const pageSize = Schema.decodeUnknownSync(PageLimit)(limit);
+        const rows = store.list(pageSize, afterKey);
+        const letters = rows.flatMap(({ key, value }) => {
+            const row = Schema.decodeUnknownSync(PostRowSchema)(value);
+            return row.state === "dead"
+                ? [
+                    {
+                        key,
+                        reason: row.reason,
+                        envelope: row.envelope,
+                        attempts: row.attempts,
+                    },
+                ]
+                : [];
+        });
+        return {
+            letters,
+            nextCursor: rows.length === pageSize ? rows.at(-1)?.key : undefined,
+        };
+    };
+    return Object.freeze({
+        send,
+        latest,
+        retry,
+        execute,
+        enqueueDue,
+        deadLetters,
+        read: readRow,
+        nextWake,
+    });
+}
+/** Consumer admission runs inside the receiver's own SQLite transaction. */
+export function admitPost(options) {
+    const key = Schema.decodeUnknownSync(Key)(options.key);
+    const event = Schema.decodeUnknownSync(options.schema)(options.event);
+    if (options.hasReceipt(key))
+        return "duplicate";
+    const result = options.apply(event);
+    if (result === "accepted")
+        options.putReceipt(key);
+    return result;
+}

package/dist/testing.d.ts

@@ -0,0 +1,16 @@
+/** String-row outbox for deterministic tests and quick starts; no persistence. */
+export type MemoryOutbox = Readonly<{
+    /** Store or replace one encoded row. */
+    put: (key: string, value: string) => Promise<void>;
+    /** Read a retained row, if present. */
+    read: (key: string) => Promise<string | undefined>;
+    /** Read a key-ordered page strictly after the supplied cursor. */
+    list: (limit: number, afterKey?: string) => Promise<readonly Readonly<{
+        key: string;
+        value: string;
+    }>[]>;
+    /** Remove one row. */
+    delete: (key: string) => Promise<void>;
+}>;
+/** Create an independent in-process outbox for trusted tests and examples. */
+export declare function createMemoryOutbox(): MemoryOutbox;

package/dist/testing.js

@@ -0,0 +1,20 @@
+/** Create an independent in-process outbox for trusted tests and examples. */
+export function createMemoryOutbox() {
+    const rows = new Map();
+    return {
+        put: (key, value) => {
+            rows.set(key, value);
+            return Promise.resolve();
+        },
+        read: (key) => Promise.resolve(rows.get(key)),
+        list: (limit, afterKey) => Promise.resolve([...rows]
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .filter(([key]) => afterKey === undefined || key > afterKey)
+            .slice(0, limit)
+            .map(([key, value]) => ({ key, value }))),
+        delete: (key) => {
+            rows.delete(key);
+            return Promise.resolve();
+        },
+    };
+}

package/docs/api/README.md

@@ -0,0 +1,20 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+**@fungi.computer/carrier**
+
+---
+
+# @fungi.computer/carrier
+
+## Modules
+
+| Module                            | Description |
+| --------------------------------- | ----------- |
+| [cloudflare](cloudflare.md)       | -           |
+| [email](email.md)                 | -           |
+| [index](index.md)                 | -           |
+| [inspection](inspection.md)       | -           |
+| [post-d1](post-d1.md)             | -           |
+| [post-postgres](post-postgres.md) | -           |
+| [post](post.md)                   | -           |
+| [testing](testing.md)             | -           |

package/docs/api/cloudflare.md

@@ -0,0 +1,100 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/carrier**](README.md)
+
+---
+
+[@fungi.computer/carrier](README.md) / cloudflare
+
+# cloudflare
+
+## Type Aliases
+
+### CloudflareCarrierStorage
+
+```ts
+type CloudflareCarrierStorage = WatchdogSqliteOwner &
+  Pick<
+    DurableObjectStorage,
+    "transaction" | "getAlarm" | "setAlarm" | "deleteAlarm"
+  >;
+```
+
+Native SQLite and alarms; the Cloudflare adapter owns their atomic composition.
+
+---
+
+### CloudflareCarrierOptions
+
+```ts
+type CloudflareCarrierOptions = Readonly<{
+  storage: CloudflareCarrierStorage;
+  canSend?: (emailId) => Promise<boolean>;
+}> &
+  | Readonly<{
+  email: SendEmail;
+  transport?: never;
+}>
+  | Readonly<{
+  transport: Options["transport"];
+  email?: never;
+}>;
+```
+
+Native storage/wake composition with exactly one provider capability.
+
+---
+
+### CloudflareCarrier
+
+```ts
+type CloudflareCarrier = Pick<Carrier, "send" | "get"> &
+  Readonly<{
+    alarm: () => Promise<void>;
+  }>;
+```
+
+Ordinary submission operations and the native Durable Object alarm door.
+
+## Functions
+
+### createCloudflareCarrier()
+
+```ts
+function createCloudflareCarrier(options): Promise<CloudflareCarrier>;
+```
+
+Construct one owner per Durable Object. Forward its native alarm to `alarm`.
+Acceptance commits the Email, recipient Messages, Watchdog job and wake
+together.
+
+#### Parameters
+
+| Parameter | Type                                                    |
+| --------- | ------------------------------------------------------- |
+| `options` | [`CloudflareCarrierOptions`](#cloudflarecarrieroptions) |
+
+#### Returns
+
+`Promise`\<[`CloudflareCarrier`](#cloudflarecarrier)\>
+
+---
+
+### cloudflareEmailTransport()
+
+```ts
+function cloudflareEmailTransport(binding): (email) => Promise<SendEvidence>;
+```
+
+The native binding as a Carrier transport. Exported so a host that holds the
+binding elsewhere (the Hub's Cloudflare edge) classifies sends identically.
+
+#### Parameters
+
+| Parameter | Type        |
+| --------- | ----------- |
+| `binding` | `SendEmail` |
+
+#### Returns
+
+(`email`) => `Promise`\<[`SendEvidence`](index.md#sendevidence)\>

package/docs/api/email.md

@@ -0,0 +1,87 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/carrier**](README.md)
+
+---
+
+[@fungi.computer/carrier](README.md) / email
+
+# email
+
+## References
+
+### CarrierError
+
+Re-exports [CarrierError](index.md#carriererror)
+
+---
+
+### CarrierStatusSchema
+
+Re-exports [CarrierStatusSchema](index.md#carrierstatusschema)
+
+---
+
+### Address
+
+Re-exports [Address](index.md#address)
+
+---
+
+### Email
+
+Re-exports [Email](index.md#email)
+
+---
+
+### Host
+
+Re-exports [Host](index.md#host)
+
+---
+
+### Message
+
+Re-exports [Message](index.md#message)
+
+---
+
+### Options
+
+Re-exports [Options](index.md#options)
+
+---
+
+### ProviderRejection
+
+Re-exports [ProviderRejection](index.md#providerrejection)
+
+---
+
+### Receipt
+
+Re-exports [Receipt](index.md#receipt)
+
+---
+
+### SendEvidence
+
+Re-exports [SendEvidence](index.md#sendevidence)
+
+---
+
+### Submission
+
+Re-exports [Submission](index.md#submission)
+
+---
+
+### Carrier
+
+Re-exports [Carrier](index.md#carrier)
+
+---
+
+### createCarrier
+
+Re-exports [createCarrier](index.md#createcarrier)