@rikalabs/akter 0.1.0-alpha.0

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

@@ -0,0 +1,221 @@
+import { Cause, Crypto, Effect, Schema, Scope, Stream } from "effect";
+import { SqlClient } from "effect/sql";
+import { ActorError, SessionEnded } from "../../errors/actor.ts";
+import type { ActorRef, Caller } from "../../identity/caller.ts";
+import type { Placement } from "../storage/codec.ts";
+import { type ConnectionCommands } from "../../identity/connection.ts";
+import { ClientMessage, type Deliver, type Delivered } from "./protocol.ts";
+import type { Transport } from "./transport.ts";
+/** The largest encoded inbound frame or open params a holder accepts. */
+export declare const MAX_INBOUND_BYTES = 65536;
+/** Open connections one holder keeps at once. */
+export declare const MAX_HELD_CONNECTIONS = 50000;
+/** Bytes buffered across one holder's connections, both directions. */
+export declare const MAX_HELD_BYTES = 268435456;
+/** Outbound frames one connection may have waiting for its client. */
+export declare const MAX_OUTBOUND_FRAMES = 1024;
+/** Outbound bytes one connection may have waiting for its client. */
+export declare const MAX_OUTBOUND_BYTES = 1048576;
+/** How long a client has to answer `Resync` with `ResyncDone`. */
+export declare const RESYNC_DEADLINE_MS = 30000;
+/** A third owner loss within this window ends the connection instead of resyncing again. */
+export declare const RESYNC_WINDOW_MS = 300000;
+/** Inbound frames a connection may have in flight before its transport stops reading. */
+export declare const MAX_INFLIGHT_FRAMES = 32;
+/** One socket as its transport sees it. */
+export interface HeldConnection {
+    readonly connectionId: string;
+    /** The flushed-through cursor when the connection opened: replay events after it. */
+    readonly cursor: string;
+    readonly messages: Stream.Stream<ClientMessage, ActorError>;
+    readonly send: (frame: string) => Effect.Effect<void, ActorError>;
+    /** Tells the holder the client finished its replay after `Resync`. */
+    readonly resyncDone: Effect.Effect<void>;
+    /** Whether the session is open and inside its authorization bound now, so a result read for it may still be released. */
+    readonly authorized: Effect.Effect<boolean>;
+    /** Waits until fewer than `MAX_INFLIGHT_FRAMES` inbound frames are in flight, or the session ended. */
+    readonly writable: Effect.Effect<void>;
+    /**
+     * Renews the session's authorization for the same caller, as a fresh
+     * credential does: authorization runs again, and the credential's own expiry,
+     * if any, becomes the session's new cap.
+     */
+    readonly reauthenticate: (expiresAt: number | undefined) => Effect.Effect<void, ActorError>;
+    readonly close: Effect.Effect<void>;
+}
+/** What a transport asks a holder to open. */
+export interface OpenRequest {
+    readonly ref: ActorRef;
+    readonly member: string;
+    readonly caller: Caller;
+    readonly params: string;
+    /** The credential's own expiry, if it has one; the session never outlives it. */
+    readonly expiresAt?: number | undefined;
+    /** The event tags of a feed, which opens the framework feed member. */
+    readonly feed?: ReadonlyArray<string> | undefined;
+}
+declare const OpenRejected_base: Schema.Class<OpenRejected, Schema.TaggedStruct<"OpenRejected", {
+    readonly value: Schema.String;
+}>, Cause.YieldableError>;
+/** The declared failure an `open` handler returned, still encoded. */
+export declare class OpenRejected extends OpenRejected_base {
+}
+type Owner = {
+    readonly generation: string;
+    readonly owner: string;
+    readonly ownerEpoch: string;
+};
+type Address = {
+    readonly ref: ActorRef;
+    readonly connectionId: string;
+    readonly holder: string;
+    readonly holderEpoch: string;
+};
+/** The owner-side connection RPCs a holder calls for one actor. */
+export interface OwnerChannel {
+    readonly open: (request: Address & {
+        readonly member: string;
+        readonly caller: Caller;
+        readonly params: string;
+        readonly commands: ConnectionCommands;
+    }) => Effect.Effect<({
+        readonly _tag: "Opened";
+        readonly baseline: string;
+        readonly recovered?: boolean;
+    } & Owner) | {
+        readonly _tag: "Failed";
+        readonly value: string;
+    }, ActorError>;
+    readonly frame: (request: Address & {
+        readonly seq: number;
+        readonly frame: string;
+        readonly authorizedUntil: number;
+        readonly commands: ConnectionCommands;
+    }) => Effect.Effect<({
+        readonly _tag: "Acked";
+    } & Owner) | {
+        readonly _tag: "Closed";
+        readonly ended: SessionEnded;
+    }, ActorError>;
+    readonly close: (request: Address & {
+        readonly cause: SessionEnded;
+    }) => Effect.Effect<void, ActorError>;
+    readonly resync: (request: Address & {
+        readonly after?: string | undefined;
+        readonly authorizedUntil: number;
+    }) => Effect.Effect<({
+        readonly _tag: "Replayed";
+    } & Owner) | {
+        readonly _tag: "Closed";
+        readonly ended: SessionEnded;
+    }, ActorError>;
+}
+/** What a holder needs to know about an actor type it holds connections to. */
+export interface HeldActorType {
+    readonly deliveryMs: number;
+    /** How long a new owner may take to answer a resync: the dead owner's lock plus a wake. */
+    readonly takeoverMs: number;
+    readonly reauthorizeMs: number;
+    readonly retryWindowMs: number;
+    readonly placement: Placement;
+    readonly hasResync: (member: string) => boolean;
+    readonly hasMember: (member: string) => boolean;
+    readonly channel: OwnerChannel;
+    readonly routingKey: (ref: ActorRef) => bigint;
+}
+/** What a holder needs from its runner: the transport to owners, the actor types it serves, and the authorization hook. */
+interface HolderOptions {
+    readonly transport: () => Transport;
+    readonly actorType: (name: string) => HeldActorType | undefined;
+    readonly authorize: (request: {
+        readonly caller: Caller;
+        readonly ref: ActorRef;
+        readonly command: string;
+        readonly kind: "open" | "feed" | "watch" | "reauthorize";
+        readonly of?: "open" | "feed" | "watch";
+    }) => Effect.Effect<boolean>;
+}
+/**
+ * The socket side of connections on one runner: it holds each connection's
+ * buffers, caller, and authorization clock, orders inbound frames, applies the
+ * owner's ordered messages, and resyncs its connections in place when their
+ * owner dies. Actor activations never hold a socket.
+ *
+ * Authorization: nothing reaches a client or an owner past the connection's
+ * authorization bound. A session past its credential's expiry reports that;
+ * otherwise its last check is too old. A credential's expiry caps the session and
+ * its buffered frames go with it. An answer that arrives past the bound never
+ * extends it, and a credential that expired while authorization ran opens nothing.
+ * A holder that cannot confirm its rows for a whole bound stops serving them; a
+ * connection opened since the checks began failing counts from its open. A
+ * revoked client receives nothing more, including frames already queued.
+ *
+ * Buffering: a member frame evicts buffered progress oldest first before the
+ * connection counts as a slow consumer. A newer progress frame that would not fit
+ * is dropped and the waiting one stays. A progress marker delivers the newest
+ * frame of its job, or nothing if it was discarded.
+ *
+ * Owner ordering: an owner acknowledges each message before sending the next, so
+ * the first message a record sees follows everything its connections could have
+ * missed. Redelivered messages were already applied, and late messages from a
+ * dead or superseded generation are dropped. A gap makes every connection replay
+ * from its cursor. A newer generation over an unsealed older one means the older
+ * owner died, and every connection resyncs in place; a loss during a resync
+ * restarts it from the same cursor and keeps the frames it deferred. An older
+ * owner's progress never reaches a client after a newer owner's messages, and a
+ * ping answered after a newer owner was observed says nothing about that owner.
+ * Live frames wait until a resync's replay is acknowledged, and inbound frames are
+ * delivered one at a time after any pending resync. Acknowledgments before the new
+ * owner answered, or before the member's replay finished, are ignored. Until the
+ * new owner answers, the resync deadline bounds the takeover; then the client's
+ * acknowledgment does.
+ *
+ * Opening and closing: a connection registers before the owner commits so frames
+ * flushed after that commit find it. The owner may still commit an open the holder
+ * gave up on; such a late row is closed again. A lost owner's opening frames and
+ * unflushed broadcasts may be gone. An open handler that closed the connection
+ * leaves it ended with `ServerClosed`. On close the owner deletes the row, and the
+ * holder deletes its own if the owner cannot. Rows an unreachable owner dropped
+ * end their connections so clients reconnect. A graceful shutdown ends every
+ * connection with a resync hint and deletes its rows. A feed connection is
+ * authorized as each event tag it reads, all of which must pass.
+ */
+export declare const connectionHolder: (options: HolderOptions) => Effect.Effect<{
+    open: (request: OpenRequest) => Effect.Effect<{
+        connectionId: string;
+        cursor: string;
+        messages: Stream.Stream<{
+            readonly _tag: "Frame";
+            readonly frame: string;
+            readonly cursor?: string | undefined;
+            readonly event?: string | undefined;
+        } | {
+            readonly _tag: "Progress";
+            readonly job: string;
+            readonly jobId: string;
+            readonly attempt: number;
+            readonly seq: number;
+            readonly frame: string;
+        } | {
+            readonly _tag: "Resync";
+            readonly after: string | undefined;
+            readonly reason: "OwnerLost";
+            readonly deadlineMs: number;
+        } | {
+            readonly _tag: "ResyncReplayed";
+        }, ActorError, never>;
+        send: (frame: string) => Effect.Effect<void, ActorError, never>;
+        resyncDone: Effect.Effect<void, never, never>;
+        authorized: Effect.Effect<boolean, never, never>;
+        writable: Effect.Effect<void, never, never>;
+        reauthenticate: (expiresAt: number | undefined) => Effect.Effect<undefined, ActorError, never>;
+        close: Effect.Effect<void, never, never>;
+    }, ActorError | OpenRejected, never>;
+    deliver: (message: Deliver) => Effect.Effect<Delivered>;
+    size: () => number;
+    /** The clock authorization and credential expiry are measured on, in epoch milliseconds. */
+    now: Effect.Effect<number, never, never>;
+}, import("effect/sql/SqlError").SqlError, Crypto.Crypto | Scope.Scope | SqlClient.SqlClient>;
+/** The holder service `connectionHolder` builds. */
+export type Holder = Effect.Success<ReturnType<typeof connectionHolder>>;
+export type { Scope };