@rikalabs/akter 0.1.0-alpha.0

package/dist/runtime/subscriptions/identity.d.ts

@@ -0,0 +1,31 @@
+import { Effect } from "effect";
+import type { Request, SubscriptionEnvelope } from "../request.ts";
+import type { ActorRef } from "../../identity/caller.ts";
+/**
+ * The identity of one subscription delivery: which subscription, subscriber,
+ * source, epoch, and position it applies. Two subscriptions, two subscribers
+ * of one source, or two epochs of one subscription never share one.
+ */
+export declare const deliveryIdentity: ({ subscriber, envelope, }: {
+    readonly subscriber: ActorRef;
+    readonly envelope: SubscriptionEnvelope;
+}) => Effect.Effect<string, never, never>;
+/**
+ * What a receipt's payload hash binds: a delivery's identity rather than its
+ * re-encoded bytes, so a redelivery after a schema-compatible deploy replays
+ * instead of conflicting; any other request's payload.
+ */
+export declare const hashedPayload: (request: Request) => Effect.Effect<string, never, never>;
+/**
+ * A delivery's command id: `v1.<s>.<s + retryWindow>.<digest>`, where `s` is
+ * fixed by the delivered record (an event's emit time, a gap's detection
+ * time, a control row's schedule), so a redelivery repeats the id. The digest
+ * is SHA-256 of the identity shaped as a version-8 UUID, which external
+ * admission never accepts, so no caller can plant a receipt under it.
+ */
+export declare const deliveryCommandId: (args_0: {
+    readonly subscriber: ActorRef;
+    readonly envelope: SubscriptionEnvelope;
+    readonly issuedAt: number;
+    readonly retryWindowMs: number;
+}) => Effect.Effect<string, never, never>;

package/dist/runtime/subscriptions/identity.js

@@ -0,0 +1,45 @@
+import { Effect, Schema } from "effect";
+const encodeIdentity = Schema.encodeEffect(Schema.fromJsonString(Schema.Array(Schema.String)));
+/**
+ * The identity of one subscription delivery: which subscription, subscriber,
+ * source, epoch, and position it applies. Two subscriptions, two subscribers
+ * of one source, or two epochs of one subscription never share one.
+ */
+export const deliveryIdentity = ({ subscriber, envelope, }) => encodeIdentity([
+    "subscription/v1",
+    subscriber.tenant,
+    subscriber.actor,
+    envelope.subscription,
+    subscriber.id,
+    envelope.sourceType,
+    envelope.sourceId,
+    envelope.epoch,
+    envelope.kind,
+    envelope.position,
+]).pipe(Effect.orDie);
+/**
+ * What a receipt's payload hash binds: a delivery's identity rather than its
+ * re-encoded bytes, so a redelivery after a schema-compatible deploy replays
+ * instead of conflicting; any other request's payload.
+ */
+export const hashedPayload = (request) => request.delivery === undefined
+    ? Effect.succeed(request.payload)
+    : deliveryIdentity({ subscriber: request.ref, envelope: request.delivery });
+/**
+ * A delivery's command id: `v1.<s>.<s + retryWindow>.<digest>`, where `s` is
+ * fixed by the delivered record (an event's emit time, a gap's detection
+ * time, a control row's schedule), so a redelivery repeats the id. The digest
+ * is SHA-256 of the identity shaped as a version-8 UUID, which external
+ * admission never accepts, so no caller can plant a receipt under it.
+ */
+export const deliveryCommandId = Effect.fnUntraced(function* ({ subscriber, envelope, issuedAt, retryWindowMs, }) {
+    const identity = yield* deliveryIdentity({ subscriber, envelope });
+    const digest = yield* Effect.promise(() => globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(identity)));
+    const bytes = new Uint8Array(digest).slice(0, 16);
+    bytes[6] = (bytes[6] & 0x0f) | 0x80;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const raw = Buffer.from(bytes).toString("hex");
+    const uuid = `${raw.slice(0, 8)}-${raw.slice(8, 12)}-${raw.slice(12, 16)}-${raw.slice(16, 20)}-${raw.slice(20)}`;
+    const issued = Math.max(1, Math.floor(issuedAt));
+    return `v1.${issued}.${issued + retryWindowMs}.${uuid}`;
+});

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

@@ -0,0 +1,175 @@
+import { Effect, Schema } from "effect";
+import { SqlClient, SqlError, type Statement } from "effect/sql";
+import { type BucketRange } from "../database/shards.ts";
+import { SubscriptionFailure } from "../../errors/subscription.ts";
+import type { ActorError } from "../../errors/actor.ts";
+import { Outcome, Request } from "../request.ts";
+import { type RegisteredSubscription } from "../members.ts";
+import { type Placement } from "../storage/codec.ts";
+/** A subscription this runner delivers: a subscriber type and one of its declarations. */
+export interface LocalSubscription {
+    readonly subscriberType: string;
+    readonly subscription: RegisteredSubscription;
+}
+/** Tuning for subscription work: concurrency, lease, and backoff bounds. */
+interface SubscriptionSettings {
+    /** Feed expansions, control registrations, and subscription deliveries each run this many at once. */
+    readonly concurrency: number;
+    /** Matching events one claimed subscription row delivers before it settles. */
+    readonly batch: number;
+    readonly claimLeaseMs: () => number;
+    readonly maxBackoffMs: number;
+    readonly retryWindowMs: number;
+}
+/** A claimed feed row to expand, or control row to register at its source. */
+declare const OutboxWork: Schema.Struct<{
+    readonly kind: Schema.Literals<readonly ["feed", "control"]>;
+    readonly routing_key: Schema.String;
+    readonly intent_id: Schema.String;
+    readonly attempts: Schema.Int;
+    readonly tenant_id: Schema.String;
+    readonly actor_type: Schema.String;
+    readonly actor_id: Schema.String;
+    readonly target_type: Schema.String;
+    readonly target_id: Schema.String;
+    readonly command: Schema.String;
+    readonly payload: Schema.String;
+    readonly scheduled_at_ms: Schema.String;
+    readonly claimed_until: Schema.String;
+}>;
+type OutboxWork = typeof OutboxWork.Type;
+/** A claimed subscription row to deliver. */
+declare const SubscriptionRow: Schema.Struct<{
+    readonly kind: Schema.Literal<"subscription">;
+    readonly routing_key: Schema.String;
+    readonly tenant_id: Schema.String;
+    readonly source_type: Schema.String;
+    readonly source_id: Schema.String;
+    readonly subscriber_type: Schema.String;
+    readonly subscription: Schema.String;
+    readonly subscriber_id: Schema.String;
+    readonly events: Schema.$Array<Schema.String>;
+    readonly epoch: Schema.String;
+    readonly delivered: Schema.String;
+    readonly attempts: Schema.Int;
+    readonly gap_through: Schema.NullOr<Schema.String>;
+    readonly claimed_until: Schema.String;
+}>;
+type SubscriptionRow = typeof SubscriptionRow.Type;
+/** A unit of relay work: an outbox row to expand or a subscription row to deliver. */
+export type SubscriptionWork = OutboxWork | SubscriptionRow;
+/**
+ * CTEs that claim subscription work and the selects that return each claimed
+ * item as a JSON `work` column, for the relay's one claim statement.
+ */
+export interface SubscriptionClaim {
+    readonly parts: ReadonlyArray<Statement.Fragment>;
+    readonly results: ReadonlyArray<Statement.Fragment>;
+}
+/** What the outbox relay runs of a runner's subscription work. */
+export interface SubscriptionRelay {
+    /** Undefined when this runner registers no subscription or has no free slot. */
+    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, SqlClient.SqlClient>;
+    /** Deletes rows of a subscription this runner no longer declares after a day due. */
+    readonly cleanupRemoved: (subscriberType: string, declared: ReadonlyArray<string>) => Effect.Effect<number, SubscriptionError, SqlClient.SqlClient>;
+    /** Widens a dynamic subscription's rows to the declared event classes, once per startup. */
+    readonly widen: (subscriberType: string, declared: RegisteredSubscription) => Effect.Effect<void, SubscriptionError, SqlClient.SqlClient>;
+}
+/**
+ * How an expansion hands the rows it leased to the relay: its free
+ * subscription-delivery slots now, and starting one leased row's delivery.
+ */
+export interface Handoff {
+    readonly free: Effect.Effect<number>;
+    readonly start: (work: SubscriptionWork) => Effect.Effect<void>;
+}
+/** How many of each kind of subscription work a runner has room to claim now. */
+export interface SubscriptionSlots {
+    readonly feed: number;
+    readonly control: number;
+    readonly subscription: number;
+}
+/** How subscription work can fail; the relay logs it and the row's lease or backoff retries it. */
+export type SubscriptionError = SqlError.SqlError | Schema.SchemaError | SubscriptionFailure;
+/**
+ * The relay's subscription work on one runner: expanding source feeds,
+ * registering dynamic subscriptions at their sources, and delivering due
+ * subscription rows of the subscriber types this runner registers. A runner
+ * that registers none claims none of it.
+ *
+ * Delivery: rows this runner can deliver that an expansion makes due are leased at
+ * once, up to its free delivery slots, and delivered without a claim pass; the
+ * rest become due for any runner. Updates bound their rows by the page's key
+ * range, read from the key index, rather than joining the page, so a planner on
+ * stale row counts cannot rescan the page for every stored row. A renewal never
+ * shortens a claim, so it cannot undo a lease a test clock moved. Shutdown
+ * releases a claim at once; the receipt and cursor make redelivery safe.
+ *
+ * Subscribing: a source that has never been created can be subscribed to. Only a
+ * refused subscribe leaves a tombstone at its own epoch. A subscription is due at
+ * once when history after its start already matches, so one to a quiet source
+ * still delivers it. Widening only adds this declaration's classes to the row's
+ * list. Every write that changes a row's `active` or `events` goes through
+ * `changeRows`, which moves the tag summary in the same transaction.
+ *
+ * Gaps: pruning removes a prefix, so history after `delivered` is missing when the
+ * oldest retained event is past its successor or nothing is retained. An
+ * operator's skip plants the position it skips through as the gap's end. The
+ * detection time fixes the gap's id and its range is kept, so a redelivery reports
+ * the same gap even after pruning advances. An id route needs the pruned event to
+ * name a subscriber. A short batch scanned every matching event through the head
+ * it read, and after a gap older than the pruning it stops at the gap to find the
+ * next one.
+ *
+ * Delivery outcomes: the subscriber reads the current shape, and a value its chain
+ * cannot read backs the row off at this event rather than skipping it. A failure
+ * backs the row off, and a stale or unsubscribed acknowledgement removes this
+ * epoch's row. The marked position is read before the settle in its own snapshot:
+ * a commit after it raised `marked` through its expansion, which the settle reads
+ * from the row.
+ */
+export declare const subscriptionRelay: (options: {
+    readonly deliver: (request: Request) => Effect.Effect<Outcome, ActorError>;
+    readonly local: () => ReadonlyArray<LocalSubscription>;
+    readonly placementOf: (actorType: string) => Effect.Effect<Placement | undefined>;
+    readonly wake: Effect.Effect<void>;
+    readonly settings: SubscriptionSettings;
+}) => Effect.Effect<{
+    claim: (slots: SubscriptionSlots, range: BucketRange) => SubscriptionClaim | undefined;
+    decode: (work: string) => Effect.Effect<{
+        readonly kind: "control" | "feed";
+        readonly routing_key: string;
+        readonly intent_id: string;
+        readonly attempts: number;
+        readonly tenant_id: string;
+        readonly actor_type: string;
+        readonly actor_id: string;
+        readonly target_type: string;
+        readonly target_id: string;
+        readonly command: string;
+        readonly payload: string;
+        readonly scheduled_at_ms: string;
+        readonly claimed_until: string;
+    } | {
+        readonly kind: "subscription";
+        readonly routing_key: string;
+        readonly tenant_id: string;
+        readonly source_type: string;
+        readonly source_id: string;
+        readonly subscriber_type: string;
+        readonly subscription: string;
+        readonly subscriber_id: string;
+        readonly events: readonly string[];
+        readonly epoch: string;
+        readonly delivered: string;
+        readonly attempts: number;
+        readonly gap_through: string | null;
+        readonly claimed_until: string;
+    }, never, never>;
+    run: (work: SubscriptionWork, handoff: Handoff) => Effect.Effect<void, SubscriptionError, SqlClient.SqlClient>;
+    widen: (subscriberType: string, declared: RegisteredSubscription) => Effect.Effect<void, SqlError.SqlError, SqlClient.SqlClient>;
+    cleanupRemoved: (subscriberType: string, declared: readonly string[]) => Effect.Effect<number, SqlError.SqlError, SqlClient.SqlClient>;
+}, never, SqlClient.SqlClient>;
+export {};