@rikalabs/akter 0.1.0-alpha.0

package/dist/runtime/turn/receipt.js

@@ -0,0 +1,32 @@
+import { Crypto, Effect, Schema } from "effect";
+import { ActorError, CommandConflict, Unauthorized } from "../../errors/actor.js";
+import { Outcome } from "../request.js";
+import { callerKey } from "../../identity/caller.js";
+const OutcomeJson = Schema.fromJsonString(Outcome);
+const encodeOutcomeJson = Schema.encodeEffect(OutcomeJson);
+/** Encodes an outcome to the JSON text a receipt stores. */
+export const encodeOutcome = (outcome) => encodeOutcomeJson(outcome);
+const decodeOutcome = Schema.decodeEffect(OutcomeJson);
+const utf8 = new TextEncoder();
+/** SHA-256 over Postgres's JSONB text normalization of a payload, as stored in receipts. */
+export const hashCanonical = Effect.fnUntraced(function* (canonical) {
+    const bytes = yield* (yield* Crypto.Crypto)
+        .digest("SHA-256", utf8.encode(canonical))
+        .pipe(Effect.orDie);
+    return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString("hex");
+});
+/**
+ * Access and conflict rules for a retained receipt, shared by admission and
+ * replay. Fails with `ActorError` `Unauthorized` when the caller differs and
+ * `CommandConflict` when the command or payload hash differs; otherwise it
+ * returns the stored outcome. A stored outcome that cannot be decoded is a defect.
+ */
+export const checkReceipt = Effect.fnUntraced(function* (request, hash, receipt) {
+    if (receipt.caller_key !== callerKey(request.caller))
+        return yield* ActorError.make({ reason: Unauthorized.make({ code: "receipt_access_denied" }) });
+    if (receipt.command !== request.command || receipt.payload_hash !== hash)
+        return yield* ActorError.make({
+            reason: CommandConflict.make({ commandId: request.commandId }),
+        });
+    return yield* decodeOutcome(receipt.outcome).pipe(Effect.orDie);
+});

package/dist/runtime/turn/relay.d.ts

@@ -0,0 +1,179 @@
+import { Crypto, Effect } from "effect";
+import { SqlClient, Statement } from "effect/sql";
+import type { ActorError } from "../../errors/actor.ts";
+import { Outcome, Request } from "../request.ts";
+import { type RegisteredJob } from "../members.ts";
+import { type CappedGroup, type ClaimedJob } from "../jobs/attempt.ts";
+import { type CronSchedule } from "../cron/schedule.ts";
+import { type BucketRange } from "../database/shards.ts";
+import type { Handoff, SubscriptionError, SubscriptionClaim, SubscriptionSlots, SubscriptionWork } from "../subscriptions/relay.ts";
+/** The relay and executor pool settings of one runner, resolved from `Actors.layer`. */
+export interface RelaySettings {
+    /** Durable polling interval; each wait is jittered by ±10%. */
+    readonly pollMs: number;
+    /** Intent rows claimed by one claim statement at most. */
+    readonly passLimit: number;
+    /** Intents delivered at once on this runner. */
+    readonly deliveryConcurrency: number;
+    /** How long a claimed intent stays out of every runner's scans. */
+    readonly claimLeaseMs: () => number;
+    /** Cap on intent redelivery backoff. */
+    readonly maxBackoffMs: number;
+    /** Job attempts running at once on this runner. */
+    readonly executorConcurrency: number;
+    /** An attempt's claim; renewed every third of it while the attempt runs. */
+    readonly executorLeaseMs: number;
+    /** How long after its due time a relay-written command id stays retryable. */
+    readonly retryWindowMs: number;
+    /**
+     * How often a running attempt renews its claim and checks for a
+     * cancellation committed on another runner; at most a third of the lease.
+     */
+    readonly cancelCheckMs?: number | undefined;
+}
+/** An executor this runner has, by actor type and job tag. */
+interface LocalExecutor {
+    readonly actor: string;
+    readonly job: string;
+    readonly registered: RegisteredJob;
+}
+/**
+ * One row of the claim statement. An `intent` or `job` row is a claimed
+ * outbox row; a `skipped-*` row claims nothing and reports a probe whose
+ * candidates were all taken or locked; a `work` row carries claimed
+ * subscription work in `work`.
+ */
+interface ClaimedRow extends ClaimedJob {
+    readonly kind: "intent" | "job" | "skipped-intent" | "skipped-job" | "work";
+    readonly target_type: string;
+    readonly target_id: string;
+    readonly timer_key: string | null;
+    readonly scheduled_at: string;
+    readonly candidates: number;
+    readonly work: string | null;
+}
+/**
+ * The due-work probe: up to `limit` due rows of `kind` from one
+ * `(bucket, kind, due_at_ms)` index range per bucket, so its cost follows due
+ * rows of one kind, not stored actors or future timers. It takes no locks; a
+ * claim locks only the rows it takes from it. `only` filters inside each
+ * bucket's probe, so due rows the caller cannot claim never fill the
+ * per-bucket limit ahead of rows it can.
+ */
+export declare const candidates: ({ sql, kind, now, limit, only, range, }: {
+    readonly sql: SqlClient.SqlClient;
+    readonly kind: "intent" | "job" | "feed" | "control";
+    readonly now: Statement.Fragment;
+    readonly limit: number;
+    readonly only?: Statement.Fragment;
+    readonly range?: BucketRange | undefined;
+}) => Statement.Statement<import("effect/sql/SqlConnection").Row>;
+/** Intents to claim in one statement: up to `limit` free delivery slots. */
+interface IntentClaim {
+    readonly limit: number;
+    readonly leaseMs: number;
+    readonly maxBackoffMs: number;
+    /** Due candidates probed before locking; defaults to twice `limit`. */
+    readonly probe?: number | undefined;
+    /** Actor types registered here; `$cron:` ticks of any other type are left for their runners. */
+    readonly cronActors?: ReadonlyArray<string> | undefined;
+}
+/**
+ * Claims one capped group's jobs in its own transaction, under its actor's
+ * generation row lock, so claims on every runner see each other's running rows. It
+ * settles cancelled rows whose attempt ended, starts the oldest rows by
+ * `(ready_at_ms, intent_id)` while fewer than `cap` attempts hold a live
+ * lease, and moves the group's other due rows out of the due range as
+ * waiting, so they never fill a probe ahead of other actors' work. A waiting
+ * row becomes due again when an attempt of its group settles, or after one
+ * lease.
+ *
+ * An attempt renews, backs off, and settles its own row without the group's
+ * lock, so before it counts live leases the claim waits for those writes on
+ * the group's running rows. Otherwise `SKIP LOCKED` would pass over an older
+ * row whose lost lease is being renewed and start a younger one, and the
+ * renewal would then leave two attempts holding leases under a cap of one.
+ */
+export declare const claimCapped: ({ sql, now, group, cap, maxAttempts, permits, leaseMs, }: {
+    readonly sql: SqlClient.SqlClient;
+    readonly now: Statement.Fragment;
+    readonly group: CappedGroup;
+    readonly cap: number;
+    readonly maxAttempts: number;
+    readonly permits: number;
+    readonly leaseMs: number;
+}) => Effect.Effect<readonly ClaimedRow[], import("effect/sql/SqlError").SqlError, never>;
+/** The outbox clock inside a statement: its start time on the database plus the test offset. */
+export declare const outboxNow: ({ sql, offsetMillis, }: {
+    readonly sql: SqlClient.SqlClient;
+    readonly offsetMillis: number;
+}) => Statement.Statement<import("effect/sql/SqlConnection").Row>;
+/** The intent half of `claimDue` at a fixed `now`, as a statement to inspect. */
+export declare const claimIntents: ({ sql, now, range, ...intents }: IntentClaim & {
+    readonly sql: SqlClient.SqlClient;
+    readonly now: number;
+    readonly range?: BucketRange | undefined;
+}) => Statement.Statement<ClaimedRow>;
+/**
+ * The outbox relay of one runner among any number sharing the database. Each
+ * pass claims, for every family of work (intents, job attempts, and feed,
+ * control, and subscription work), only as many rows as the family has free
+ * fibers, then starts each one at once. A pass runs uninterruptibly under a
+ * lock, so every row a claim returns reaches a fiber that can release it.
+ * When both capped and uncapped jobs are due, passes alternate which claims
+ * first, so a steady stream of either can't take every permit.
+ *
+ * An intent is delivered as a direct command whose command id is the intent
+ * id, and its row is deleted only after the receiver's receipt has committed.
+ * A crash leaves the claim in place until its lease ends; any runner then
+ * redelivers, and the receipt deduplicates. A row that cannot form a request,
+ * a delivery that fails, and a defect outcome back off and retry with no retry
+ * limit; the logged warning and `attempts` are the operator signal. A declared
+ * failure is a committed receipt, so only a missing receipt retries. An
+ * interrupted delivery makes its row due at once.
+ *
+ * A job attempt runs on its own family and settles its row itself; see
+ * `jobAttempts`. A running attempt is registered before the pass releases its
+ * lock and until its outcome is written, so every clock jump after the claim
+ * moves its lease; a local cancellation signals running attempts directly.
+ *
+ * Subscription work runs in its own families, so a subscription backlog never
+ * delays intents, timers, or jobs; expansion work starts the rows it leased
+ * without a claim pass; `schedules` names the cron actors whose ticks this
+ * runner claims. The returned handle: `run` loops passes on a jittered poll
+ * and `wake`; `drain` waits for in-flight work, which may stage more, then
+ * claims again until a claim finds nothing while nothing was running (work
+ * runs only on fibers a pass starts, so none running means nothing can stage
+ * rows after that claim read), failing if deliveries keep staging due work,
+ * and counting toward that limit only rounds that drained every due row;
+ * `stop` ends claims and interrupts deliveries at once, since a delivery only
+ * waits on a turn its receiver's owner finishes or rolls back on its own, and
+ * the receiver's receipt answers a redelivery of work that did commit;
+ * `interruptAttempts` interrupts running attempts and returns how many,
+ * leaving their claims and `ambiguous` marks because the provider may have
+ * applied the call, so another runner takes the job over once the lease ends;
+ * `attemptsIdle` waits for attempts to end; `extendLeases` moves running
+ * attempts' leases with a jump of the outbox clock, as the renewals during
+ * that time would have, holding the pass lock so no claim reads the clock
+ * between the moved leases and the jump; `cancelled` makes running attempts
+ * check for cancellation now. Closing the scope stops further claims, after
+ * taking the lock so a pass in progress hands its rows to fibers first and
+ * they are interrupted and released.
+ */
+export declare const outboxRelay: (deliver: (request: Request) => Effect.Effect<Outcome, ActorError>, executors: () => ReadonlyArray<LocalExecutor>, settings: RelaySettings, subscriptions?: {
+    /** Feed, control, and subscription-delivery slots, each; separate from intent slots. */
+    readonly concurrency: number;
+    readonly claim: (slots: SubscriptionSlots, range: BucketRange) => SubscriptionClaim | undefined;
+    readonly decode: (work: string) => Effect.Effect<SubscriptionWork>;
+    readonly run: (work: SubscriptionWork, handoff: Handoff) => Effect.Effect<void, SubscriptionError>;
+} | undefined, schedules?: (() => ReadonlyMap<string, CronSchedule>) | undefined) => Effect.Effect<{
+    run: Effect.Effect<never, never, never>;
+    drain: Effect.Effect<undefined, never, never>;
+    stop: Effect.Effect<void, never, never>;
+    attemptsIdle: Effect.Effect<void, never, never>;
+    interruptAttempts: Effect.Effect<number, never, never>;
+    extendLeases: (millis: number, jump: Effect.Effect<void>) => Effect.Effect<void, never, never>;
+    wake: Effect.Effect<void, never, never>;
+    cancelled: Effect.Effect<void, never, never>;
+}, import("effect/sql/SqlError").SqlError, Crypto.Crypto | import("effect/Scope").Scope | SqlClient.SqlClient>;
+export {};