@rikalabs/akter 0.1.0-alpha.0

package/dist/runtime/connections/owner.d.ts

@@ -0,0 +1,263 @@
+import { type Context, Deferred, Effect, Option, Queue, Semaphore, Stream } from "effect";
+import { Entity, type Sharding } from "effect/cluster";
+import { SqlClient } from "effect/sql";
+import { ActorError, SessionEnded } from "../../errors/actor.ts";
+import { type Broadcast, type ConnectionResult, type OpenConnection, type Registration, type StoredProgress } from "../members.ts";
+import { type ActorRef, Caller, type Principal } from "../../identity/caller.ts";
+import type { ConnectionCommands } from "../../identity/connection.ts";
+import { type ActivationCache } from "../storage/generation.ts";
+import type { CommittedEvents } from "../turn/execute.ts";
+import { type WriteSet } from "./protocol.ts";
+import { type Authorize, type Subscription } from "./streams.ts";
+import { type Transport } from "./transport.ts";
+/** Encoded bytes one connection's session may hold. */
+export declare const MAX_SESSION_BYTES = 16384;
+/** What this activation knows of one job's progress. */
+interface JobProgress {
+    /** False once the job's route or settle committed, or its row is gone. */
+    open: boolean;
+    checkedAt: number;
+    /** The last frame, check, or close; the record goes `PROGRESS_RECORD_MS` after it. */
+    touchedAt: number;
+    attempt: number;
+    seq: number;
+    readonly principal: Option.Option<Principal>;
+    /** The job's encoded payload, for stream subscribers. */
+    readonly payload: string;
+    /** Channels this activation forwarded the job's progress to. */
+    readonly holders: Set<string>;
+}
+/** One progress message from an executor pool, as the owner receives it. */
+export interface ProgressDelivery {
+    readonly ref: ActorRef;
+    readonly jobId: string;
+    readonly job: string;
+    readonly attempt: number;
+    readonly seq: number;
+    readonly leaseUntil: number;
+    readonly frame: string;
+}
+interface Row {
+    readonly connectionId: string;
+    readonly member: string;
+    readonly holder: string;
+    readonly holderEpoch: string;
+    readonly caller: Caller;
+    /** The event cursor the connection opened at. */
+    readonly baseline: string;
+    session: string | undefined;
+    frameSeq: number;
+    /** Broadcasts committed while the connection is still opening, sent after its open frames. */
+    buffered?: Array<{
+        readonly frame: string;
+        readonly event?: string | undefined;
+    }>;
+}
+interface Channel {
+    readonly holder: string;
+    readonly epoch: string;
+    seq: number;
+}
+/**
+ * One actor's activation on this runner, shared by its command entity and its
+ * connection entity so both run under one generation fence. `rows` mirrors the
+ * actor's committed `actor_connections` rows once loaded.
+ */
+export interface Activation {
+    readonly ref: ActorRef;
+    readonly key: bigint;
+    readonly cache: ActivationCache;
+    presence: number;
+    rows: Map<string, Row> | undefined;
+    /** The committed event head this activation last read or wrote. */
+    head: string;
+    /** Completed, and replaced, each time `head` advances; followers wait on it. */
+    advanced: Deferred.Deferred<void>;
+    /** Open stream subscriptions, which end with this activation. */
+    readonly streams: Set<Subscription>;
+    /** Progress of jobs this activation received frames for. */
+    readonly progress: Map<string, JobProgress>;
+    /** Job ids whose check is reading the database now. */
+    readonly checking: Set<string>;
+    /** When each job's check last failed, so the next waits. */
+    readonly checkFailed: Map<string, number>;
+    readonly listeners: Set<{
+        readonly tag: string;
+        readonly jobId: string | undefined;
+        readonly queue: Queue.Queue<StoredProgress>;
+    }>;
+    progressTokens: number;
+    progressRefilledAt: number;
+    /** When `progress` was last swept of records nothing touched for `PROGRESS_RECORD_MS`. */
+    progressSweptAt: number;
+    /** The highest commit whose frames all went out to their holders. */
+    through: string;
+    readonly channels: Map<string, Channel>;
+    readonly flush: Semaphore.Semaphore;
+    /** Serializes the first load of `rows`, which opens may race to start. */
+    readonly loading: Semaphore.Semaphore;
+    readonly locks: Map<string, Semaphore.Semaphore>;
+    /** Connections this activation opened itself; every other one is resumed. */
+    readonly opened: Set<string>;
+    /** The entity that holds this activation awake, released through its own context. */
+    keptAwake: Context.Context<Sharding.Sharding | Entity.CurrentAddress> | undefined;
+    /** Serializes generation acquisition across the command and connection entities. */
+    readonly acquiring: Semaphore.Semaphore;
+}
+type Address = {
+    readonly ref: ActorRef;
+    readonly connectionId: string;
+    readonly holder: string;
+    readonly holderEpoch: string;
+};
+/**
+ * The owner side of connections for one actor type: the activation registry
+ * shared with commands, the fenced `actor_connections` writes, and ordered,
+ * post-commit delivery of frames to every holder.
+ *
+ * Ordering and safety: every holder learns this owner before any of its
+ * broadcasts, so it can resync if the owner dies, and a holder that cannot be
+ * reached is excluded, its rows dropped, so it ends those connections itself.
+ * Dropping a generation's state means whatever runs next acquires a new one,
+ * reloads the rows, and numbers each holder's messages from 1 again, which a
+ * holder requires of every new generation; a clean end tells holders not to
+ * resync. A flush that read an older head than a concurrent one never moves the
+ * cursor back. Ends run on their own fibers so one slow handler never holds up the
+ * rest. A handler defect closes only its connection.
+ *
+ * Connections: feeds are framework connections, so an actor type with feeds loads
+ * its rows like one with members, and a feed has no handler, so its open only
+ * inserts the row and fixes its baseline and its close only deletes the row. A
+ * feed's holder rereads events itself once the new owner answers, and a feed
+ * serves the current shape even under a `writeVersion`. A connection's lock lives
+ * only as long as its row. A retried open cannot know whether its opening frames
+ * reached the holder. The owner runs frames only from the connection's stored
+ * holder, and a frame or subscription that reaches it past its authorization bound
+ * never runs.
+ *
+ * Subscriptions: followers wait on `advanced`, and a new head wakes every one. A
+ * replay reads pages from where the previous stopped up to the head, which only
+ * moves after a commit, so nothing is skipped or read twice. The subscription
+ * limit is checked and taken in one step so concurrent subscriptions cannot all
+ * pass it. A hook that hangs is retried at the next tick while the bound still
+ * ends the session, and an answer past the bound never extends it. A stream
+ * subscriber's live progress is a sliding buffer, so a slow reader loses the
+ * oldest.
+ *
+ * Progress frames: a route or settle that committed while the job check read
+ * keeps the job closed. A row that has not counted an attempt yet does not
+ * prove a frame open. Every frame of a job shares one activation record so its
+ * order and holders stay whole, and a record decides after a permit wait, never a
+ * copy taken before it. A record nothing touched for a while goes, and a late
+ * frame runs the job check again.
+ */
+export declare const activationOwner: ({ registration, transport, authorize, clock, role, }: {
+    readonly registration: Registration;
+    readonly transport: Transport;
+    readonly authorize: Authorize;
+    readonly clock: {
+        readonly offsetMillis: () => number;
+    };
+    /** The tenant role handlers' event reads run as when row-level security is on. */
+    readonly role: string | undefined;
+}) => {
+    activations: Map<string, Activation>;
+    hasConnections: boolean;
+    hasStreams: boolean;
+    hasProgress: boolean;
+    progress: (activation: Activation, message: ProgressDelivery) => Effect.Effect<void, never, Entity.CurrentAddress | Sharding.Sharding | SqlClient.SqlClient>;
+    closeProgress: (activation: Activation, jobId: string) => Effect.Effect<void, never, SqlClient.SqlClient>;
+    progressClosed: (activation: Activation, message: {
+        readonly ref: ActorRef;
+        readonly jobId: string;
+        readonly attempt: number;
+    }) => Effect.Effect<void, never, SqlClient.SqlClient>;
+    feedBroadcasts: (committed: CommittedEvents) => Effect.Effect<Broadcast[], never, never>;
+    watchBroadcasts: (activation: Activation, writes: WriteSet, version: string) => Effect.Effect<Broadcast[], never, never>;
+    hibernate: (entityId: string) => Effect.Effect<void, never, SqlClient.SqlClient>;
+    subscribe: (activation: Activation, request: {
+        readonly member: string;
+        readonly caller: Caller;
+        readonly input: string;
+        readonly authorizedUntil: number;
+    }) => Stream.Stream<{
+        readonly _tag: "Done";
+    } | {
+        readonly _tag: "Element";
+        readonly value: string;
+    } | {
+        readonly _tag: "Started";
+        readonly owner: string;
+        readonly ownerEpoch: string;
+    }, ActorError | {
+        readonly _tag: "StreamFailed";
+        readonly value: string;
+    }, SqlClient.SqlClient>;
+    endStreams: (activation: Activation) => Effect.Effect<void, never, never>;
+    watchStreams: Effect.Effect<void, never, never>;
+    enter: (entityId: string, ref: ActorRef, key: bigint) => Effect.Effect<Activation, never, import("effect/Scope").Scope | SqlClient.SqlClient>;
+    prepare: (activation: Activation) => Effect.Effect<void, never, Entity.CurrentAddress | Sharding.Sharding | SqlClient.SqlClient>;
+    list: (activation: Activation) => (member: string) => Effect.Effect<readonly OpenConnection[], never, never>;
+    flush: (activation: Activation, broadcasts: ReadonlyArray<Broadcast>, head: string, own?: {
+        readonly connectionId: string;
+        readonly member: string;
+        readonly frames: ConnectionResult["sends"];
+        readonly replay?: boolean;
+    }) => Effect.Effect<void, never, SqlClient.SqlClient>;
+    open: (activation: Activation, request: Address & {
+        readonly member: string;
+        readonly caller: Caller;
+        readonly params: string;
+        readonly commands: ConnectionCommands;
+    }) => Effect.Effect<{
+        generation: string;
+        owner: string;
+        ownerEpoch: string;
+        _tag: "Opened";
+        baseline: string;
+        recovered: boolean;
+        value?: undefined;
+    } | {
+        _tag: "Failed";
+        value: string;
+    } | {
+        generation: string;
+        owner: string;
+        ownerEpoch: string;
+        value?: undefined;
+        _tag: "Opened";
+        baseline: string;
+    }, ActorError, Entity.CurrentAddress | Sharding.Sharding | SqlClient.SqlClient>;
+    frame: (activation: Activation, request: Address & {
+        readonly seq: number;
+        readonly frame: string;
+        readonly authorizedUntil: number;
+        readonly commands: ConnectionCommands;
+    }) => Effect.Effect<{
+        _tag: "Closed";
+        ended: SessionEnded;
+    } | {
+        generation: string;
+        owner: string;
+        ownerEpoch: string;
+        _tag: "Acked";
+    }, ActorError, Entity.CurrentAddress | Sharding.Sharding | SqlClient.SqlClient>;
+    close: (activation: Activation, request: Address & {
+        readonly cause: SessionEnded;
+    }) => Effect.Effect<void, ActorError, Entity.CurrentAddress | Sharding.Sharding | SqlClient.SqlClient>;
+    resync: (activation: Activation, request: Address & {
+        readonly after?: string | undefined;
+        readonly authorizedUntil: number;
+    }) => Effect.Effect<{
+        _tag: "Closed";
+        ended: SessionEnded;
+    } | {
+        generation: string;
+        owner: string;
+        ownerEpoch: string;
+        _tag: "Replayed";
+    }, ActorError, Entity.CurrentAddress | Sharding.Sharding | SqlClient.SqlClient>;
+};
+/** The owner service `activationOwner` builds. */
+export type Owner = ReturnType<typeof activationOwner>;
+export {};