@rikalabs/akter 0.1.0-alpha.0

package/dist/client/sessions/connection.d.ts

@@ -0,0 +1,118 @@
+import { Data, Effect } from "effect";
+import type { ServedConnection } from "../../actor/served.ts";
+import type { ValueSchema } from "../../members/command.ts";
+import type { AnyConnection } from "../../members/connection.ts";
+import type { ProgressJob } from "../../members/job.ts";
+/**
+ * One job's progress as its client receives it: the job's tag and a frame
+ * decoded by that job's `progress` schema. Unions over the jobs a connection
+ * member lists, so narrowing on `job` types `frame`.
+ */
+export type ProgressUpdate<J extends ProgressJob = ProgressJob> = J extends ProgressJob ? {
+    readonly job: J["tag"];
+    readonly frame: J["progress"]["Type"];
+} : never;
+/** The progress a connection member's client receives: one update per job the member lists. */
+export type ProgressOfConnection<M extends AnyConnection> = ProgressUpdate<NonNullable<M["progress"]>["jobs"][number]>;
+type Messages<Frame> = Data.TaggedEnum<{
+    Frame: {
+        readonly frame: Frame;
+        /** The flushed-through event cursor the frame was sent above; absent under `stampCursor: false`. */
+        readonly cursor: string | undefined;
+        /** The cursor of the event the frame was sent from, to deduplicate on after a resync. */
+        readonly event: string | undefined;
+    };
+    /** The actor's owner died; frames since `after` may be lost. Replay events after it, or reload state. */
+    Resync: {
+        readonly after: string | undefined;
+        readonly reason: "OwnerLost";
+        /** Milliseconds the client has to resynchronize before the connection closes. */
+        readonly deadline: number;
+    };
+    ResyncReplayed: {};
+    Progress: ProgressUpdate & {
+        readonly jobId: string;
+        readonly attempt: number;
+        readonly seq: number;
+    };
+}>;
+/**
+ * An executor's progress on a job the member lists: display-only, lossy, and
+ * never replayed after a resync. `frame` is decoded by that job's `progress`
+ * schema; `seq` counts the attempt's reports, so a gap is a dropped one.
+ */
+export type ProgressMessage<Progress extends ProgressUpdate = ProgressUpdate> = Extract<Messages<never>, {
+    readonly _tag: "Progress";
+}> & Progress;
+/**
+ * What a connection's client receives, in order: member frames, the holder's
+ * resync notices, and executor progress for a member that lists jobs.
+ * `Progress` is the member's `ProgressUpdate`, so its messages narrow by `job`.
+ */
+export type ConnectionMessage<Frame, Progress extends ProgressUpdate = ProgressUpdate> = Exclude<Messages<Frame>, {
+    readonly _tag: "Progress";
+}> | ProgressMessage<Progress>;
+/** Options of one `connect` call. */
+export interface ConnectOptions {
+    /** Stops waiting for the connection to open. */
+    readonly signal?: AbortSignal;
+    /**
+     * Resynchronizes after an owner loss: replay events after `after`, or reload
+     * state. The connection acknowledges the resync once this settles; without
+     * it, the resync is acknowledged at once and only seen in `messages`. A
+     * callback that throws, at once or later, still settles the acknowledgment.
+     */
+    readonly onResync?: (resync: {
+        readonly after: string | undefined;
+    }) => void | Promise<void>;
+}
+/** An open connection: typed frames both ways. */
+export interface ClientConnection<Server, Client, Progress extends ProgressUpdate = ProgressUpdate> {
+    /** The server's id for this connection. */
+    readonly connectionId: string;
+    /** The flushed-through event cursor when it opened: replay events after it to catch up. */
+    readonly cursor: string | undefined;
+    /**
+     * Every message in order. The iteration ends when this client closes the
+     * connection and throws its `ActorError` otherwise: `SessionEnded`
+     * `ServerClosed` when the actor closed it, and `HolderLost` with
+     * `resync: true` for a dropped socket. Consume either this or `frames`, not both.
+     */
+    readonly messages: AsyncIterable<ConnectionMessage<Server, Progress>>;
+    /** The member frames of `messages`, without the resync notices or progress. */
+    readonly frames: AsyncIterable<Server>;
+    /** Sends one frame; rejects with `SessionEnded` `HolderLost` once the session ended or its socket stopped being open. */
+    readonly send: (frame: Client) => Promise<void>;
+    /** Closes the connection. The `messages` iteration then ends without an error. */
+    readonly close: () => Promise<void>;
+}
+interface SocketSource {
+    readonly member: ServedConnection;
+    readonly url: string;
+    /** The `authorization` credential to send in `hello` and `reauthenticate`, read afresh each time. */
+    readonly authorization: Effect.Effect<string | undefined>;
+    readonly params: ValueSchema["Type"];
+    readonly options: ConnectOptions;
+}
+/**
+ * Opens one connection over WebSocket: `hello` with the credential and
+ * params, then member frames both ways. It resolves once the server sent
+ * `open`, and rejects with the declared `open` failure or the `ActorError`
+ * that refused it.
+ *
+ * The credential is read before the socket opens, so a provider that throws
+ * or rejects fails `connect` with its own error; it is read again for each
+ * renewal, and a provider that fails then leaves the old credential to expire,
+ * which the server ends the session at. Incoming messages are handled one at
+ * a time, in arrival order, with the socket's close after them. A message
+ * with a `t` this client doesn't know is ignored, as the protocol says; one
+ * that is broken ends the session, as does a frame cursor that isn't a
+ * position. Nothing reads the socket once the session ends, so a failure this
+ * client detected closes it too. After a resync, a frame whose event the
+ * client already had is a duplicate and is dropped. Progress is lossy by
+ * design: one this client can't read is dropped and the session goes on. The
+ * holder ignores a resync acknowledgment before the member's own replay; a
+ * second one after it is harmless.
+ */
+export declare const connect: <Server, Client>({ member, url, authorization, params, options, }: SocketSource) => Promise<ClientConnection<Server, Client>>;
+export {};

package/dist/client/sessions/connection.js

@@ -0,0 +1,162 @@
+import { Data, Deferred, Effect, Match, Option, Predicate, Queue, Schema, Stream } from "effect";
+import { ActorError, SessionEnded } from "../../errors/actor.js";
+import { ClientWireMessage, ServerWireMessage, SUBPROTOCOL } from "../../protocol/frames.js";
+import { aborted, decodeFailure, undecodableFailure } from "../transport.js";
+const ConnectionMessage = Data.taggedEnum();
+const encodeClient = Schema.encodeEffect(Schema.fromJsonString(ClientWireMessage));
+const decodeServer = Schema.decodeUnknownOption(Schema.fromJsonString(ServerWireMessage));
+const decodeTagged = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.Struct({ t: Schema.String })));
+const KNOWN = new Set(ServerWireMessage.members.map((member) => member.fields.t.literal));
+const encodeJson = Schema.encodeEffect(Schema.fromJsonString(Schema.Json));
+/** A frame's event cursor as a position, or `undefined` for text that isn't one. */
+const eventPosition = (cursor) => Option.getOrUndefined(Schema.decodeOption(Schema.BigIntFromString)(cursor));
+const ended = (cause, resync) => ActorError.make({ reason: SessionEnded.make({ cause, resync }) });
+const holderLost = ended("HolderLost", true);
+const isClientClosed = (failure) => Schema.is(ActorError)(failure) &&
+    Schema.is(SessionEnded)(failure.reason) &&
+    failure.reason.cause === "ClientClosed";
+/** Ends the message stream without an error. */
+const DONE = "done";
+/**
+ * Opens one connection over WebSocket: `hello` with the credential and
+ * params, then member frames both ways. It resolves once the server sent
+ * `open`, and rejects with the declared `open` failure or the `ActorError`
+ * that refused it.
+ *
+ * The credential is read before the socket opens, so a provider that throws
+ * or rejects fails `connect` with its own error; it is read again for each
+ * renewal, and a provider that fails then leaves the old credential to expire,
+ * which the server ends the session at. Incoming messages are handled one at
+ * a time, in arrival order, with the socket's close after them. A message
+ * with a `t` this client doesn't know is ignored, as the protocol says; one
+ * that is broken ends the session, as does a frame cursor that isn't a
+ * position. Nothing reads the socket once the session ends, so a failure this
+ * client detected closes it too. After a resync, a frame whose event the
+ * client already had is a duplicate and is dropped. Progress is lossy by
+ * design: one this client can't read is dropped and the session goes on. The
+ * holder ignores a resync acknowledgment before the member's own replay; a
+ * second one after it is harmless.
+ */
+export const connect = ({ member, url, authorization, params, options, }) => Effect.runPromise(Effect.gen(function* () {
+    const services = yield* Effect.context();
+    const run = Effect.runForkWith(services);
+    const encodeParams = Schema.encodeUnknownEffect(Schema.toCodecJson(member.params));
+    const encodeFrame = Schema.encodeUnknownEffect(Schema.toCodecJson(member.client));
+    const decodeFrame = Schema.decodeUnknownEffect(Schema.toCodecJson(member.server));
+    const progressDecoders = new Map([...member.progress].map(([tag, schema]) => [
+        tag,
+        Schema.decodeUnknownEffect(Schema.toCodecJson(schema)),
+    ]));
+    const declared = member.errors.length === 0
+        ? () => Option.none()
+        : Schema.decodeUnknownOption(Schema.toCodecJson(Schema.Union(member.errors)));
+    const failureOf = (error) => error === undefined
+        ? Effect.succeed(ended("ServerClosed", false))
+        : encodeJson(error).pipe(Effect.orDie, Effect.map((text) => decodeFailure(declared)({ status: 0, headers: new Headers(), text, sentAt: 0 })));
+    const hello = yield* encodeParams(params).pipe(Effect.mapError(undecodableFailure));
+    const messages = yield* Queue.unbounded();
+    const inbox = yield* Queue.unbounded();
+    const opened = yield* Deferred.make();
+    const credential = yield* authorization;
+    const ws = new WebSocket(url, SUBPROTOCOL);
+    let finished = false;
+    let highest = -1n;
+    let resync = undefined;
+    const write = (message) => encodeClient(message).pipe(Effect.orDie, Effect.map((text) => {
+        if (ws.readyState === WebSocket.OPEN)
+            ws.send(text);
+    }));
+    const finish = (failure) => Effect.gen(function* () {
+        if (finished)
+            return;
+        finished = true;
+        if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING)
+            ws.close(1000);
+        yield* Queue.fail(messages, isClientClosed(failure) ? DONE : failure);
+        yield* Deferred.fail(opened, failure);
+    });
+    const acknowledge = Effect.suspend(() => resync?.settled === true ? write({ t: "resyncDone" }) : Effect.void);
+    const frame = (message) => decodeFrame(message.frame).pipe(Effect.flatMap((decoded) => Effect.suspend(() => {
+        if (message.event !== undefined) {
+            const event = eventPosition(message.event);
+            if (event === undefined)
+                return finish(undecodableFailure());
+            if (event <= highest)
+                return Effect.void;
+            highest = event;
+        }
+        return Queue.offer(messages, ConnectionMessage.Frame({
+            frame: decoded,
+            cursor: message.cursor,
+            event: message.event,
+        }));
+    })), Effect.catch(() => finish(undecodableFailure())), Effect.asVoid);
+    const progress = (message) => Option.match(Option.fromNullishOr(progressDecoders.get(message.job)), {
+        onNone: () => Effect.void,
+        onSome: (decode) => decode(message.frame).pipe(Effect.flatMap((frame) => Queue.offer(messages, ConnectionMessage.Progress({
+            job: message.job,
+            jobId: message.jobId,
+            attempt: message.attempt,
+            seq: message.seq,
+            frame,
+        }))), Effect.catch(() => Effect.void), Effect.asVoid),
+    });
+    const resyncing = (message) => {
+        const state = { settled: false };
+        resync = state;
+        const settle = Effect.promise(() => Promise.resolve()
+            .then(() => options.onResync?.({ after: message.after }))
+            .catch(() => undefined)).pipe(Effect.andThen(Effect.sync(() => {
+            state.settled = true;
+        })), Effect.andThen(acknowledge));
+        return Queue.offer(messages, ConnectionMessage.Resync({
+            after: message.after,
+            reason: message.reason,
+            deadline: message.deadline,
+        })).pipe(Effect.andThen(Effect.sync(() => run(settle))), Effect.asVoid);
+    };
+    const handle = Match.type().pipe(Match.discriminatorsExhaustive("t")({
+        open: (message) => Deferred.succeed(opened, {
+            connectionId: message.connectionId,
+            baseline: message.baseline,
+        }).pipe(Effect.asVoid),
+        frame,
+        resync: resyncing,
+        resyncReplayed: () => Queue.offer(messages, ConnectionMessage.ResyncReplayed()).pipe(Effect.andThen(acknowledge)),
+        progress,
+        reauthenticate: () => authorization.pipe(Effect.flatMap((fresh) => fresh === undefined
+            ? Effect.void
+            : write({ t: "reauthenticate", authorization: fresh })), Effect.ignoreCause),
+        reauthenticated: () => Effect.void,
+        end: (message) => failureOf(message.error).pipe(Effect.flatMap(finish)),
+    }));
+    ws.onopen = () => run(write(credential === undefined
+        ? { t: "hello", params: hello }
+        : { t: "hello", authorization: credential, params: hello }));
+    ws.onmessage = (event) => Queue.offerUnsafe(inbox, String(event.data));
+    ws.onclose = () => Queue.offerUnsafe(inbox, DONE);
+    run(Queue.take(inbox).pipe(Effect.flatMap((text) => text === DONE
+        ? finish(holderLost)
+        : Option.match(decodeTagged(text), {
+            onNone: () => finish(undecodableFailure()),
+            onSome: ({ t }) => KNOWN.has(t)
+                ? Option.match(decodeServer(text), {
+                    onNone: () => finish(undecodableFailure()),
+                    onSome: handle,
+                })
+                : Effect.void,
+        })), Effect.forever));
+    const open = yield* Effect.raceFirst(Deferred.await(opened), aborted(options.signal).pipe(Effect.andThen(Effect.sync(() => ws.close(1000))), Effect.andThen(Effect.fail(ended("ClientClosed", false)))));
+    const stream = Stream.fromQueue(messages).pipe(Stream.catch((failure) => (failure === DONE ? Stream.empty : Stream.fail(failure))));
+    const connection = {
+        connectionId: open.connectionId,
+        cursor: open.baseline,
+        messages: Stream.toAsyncIterable(stream),
+        frames: Stream.toAsyncIterable(stream.pipe(Stream.filter((message) => Predicate.isTagged(message, "Frame")), Stream.map((message) => message.frame))),
+        send: (value) => Effect.runPromiseWith(services)(encodeFrame(value).pipe(Effect.mapError(undecodableFailure), Effect.flatMap((json) => finished || ws.readyState !== WebSocket.OPEN
+            ? Effect.fail(holderLost)
+            : write({ t: "frame", frame: json })))),
+        close: () => Effect.runPromiseWith(services)(Effect.sync(() => ws.close(1000)).pipe(Effect.andThen(finish(ended("ClientClosed", false))))),
+    };
+    return connection;
+}));

package/dist/client/sessions/feed.d.ts

@@ -0,0 +1,42 @@
+import { Effect, Stream } from "effect";
+import type { ActorError } from "../../errors/actor.ts";
+import type { EventClass } from "../../members/event.ts";
+import { type Failure } from "../transport.ts";
+/** One committed event a feed delivered, with the cursor to resume after it. */
+export interface FeedEntry<E> {
+    /** Exclusive resume point: pass it as `after` to read the events that follow. */
+    readonly cursor: string;
+    /** The decoded event. */
+    readonly event: E;
+    /** The id of the command that committed the event. */
+    readonly commandId: string;
+    /** When the event committed, in milliseconds since the epoch. */
+    readonly timestamp: number;
+}
+/** Options of one event feed iteration. */
+export interface FeedOptions {
+    /** Resume after this cursor; omitted, the feed starts at the actor's first retained event. */
+    readonly after?: string;
+    /** Ends the iteration; the feed stops at once. */
+    readonly signal?: AbortSignal;
+}
+interface FeedSource<E extends EventClass> {
+    /** Fetches the feed after `cursor`, sent as `Last-Event-ID`, with fresh headers each time. */
+    readonly open: (cursor: string | undefined, signal: AbortSignal) => Effect.Effect<Response, ActorError>;
+    /** The event class the feed delivers; its identifier is the tag asked for. */
+    readonly event: E;
+    readonly options: FeedOptions;
+}
+/**
+ * The committed `event`s of one actor after `after`, as they commit: read
+ * from the server's event feed and reopened from the last cursor delivered
+ * whenever the connection drops, the server restarts, or the credential
+ * expires and is refreshed. It fails with `RetentionGap` if events after the
+ * cursor were pruned, and with `UnknownCursor` for a cursor the actor never
+ * issued. A dropped or refused feed reopens after the server's `retryAfter`,
+ * never sooner, or after a jittered, growing delay. Every event carries its
+ * cursor as `id`; the feed's own `end` carries none, so an event named `end` is
+ * still an event.
+ */
+export declare const feedStream: <E extends EventClass>({ open, event, options, }: FeedSource<E>) => Stream.Stream<FeedEntry<E["Type"]>, Failure>;
+export {};

package/dist/client/sessions/feed.js

@@ -0,0 +1,43 @@
+import { Effect, Schema, Stream } from "effect";
+import { RetentionGap, UnknownCursor } from "../../errors/events.js";
+import { decodeFailure, undecodableFailure } from "../transport.js";
+import { IDLE_MS, readEvents, reconnecting, session } from "./sse.js";
+const decodeData = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Struct({ event: Schema.Json, commandId: Schema.String, timestamp: Schema.Finite })));
+const cursorError = Schema.decodeUnknownOption(Schema.toCodecJson(Schema.Union([UnknownCursor, RetentionGap])));
+/** A refusal's body, with its response's headers so a `Retry-After` is kept; an `end` message has none. */
+const failureOf = (text, status, headers = new Headers()) => decodeFailure(cursorError)({ status, headers, text, sentAt: 0 });
+/**
+ * The committed `event`s of one actor after `after`, as they commit: read
+ * from the server's event feed and reopened from the last cursor delivered
+ * whenever the connection drops, the server restarts, or the credential
+ * expires and is refreshed. It fails with `RetentionGap` if events after the
+ * cursor were pruned, and with `UnknownCursor` for a cursor the actor never
+ * issued. A dropped or refused feed reopens after the server's `retryAfter`,
+ * never sooner, or after a jittered, growing delay. Every event carries its
+ * cursor as `id`; the feed's own `end` carries none, so an event named `end` is
+ * still an event.
+ */
+export const feedStream = ({ open, event, options, }) => session({
+    signal: options.signal,
+    run: (emit) => {
+        const decodeEvent = Schema.decodeUnknownEffect(Schema.toCodecJson(event));
+        let last = options.after;
+        return reconnecting((delivered) => Effect.gen(function* () {
+            const response = yield* open(last, yield* Effect.abortSignal);
+            yield* readEvents({ response, refused: failureOf, idleMs: IDLE_MS }).pipe(Stream.runForEach((message) => Effect.gen(function* () {
+                if (message.id === undefined)
+                    return message.event === "end" ? yield* failureOf(message.data, 0) : undefined;
+                const data = yield* decodeData(message.data).pipe(Effect.mapError(undecodableFailure));
+                const decoded = yield* decodeEvent(data.event).pipe(Effect.mapError(undecodableFailure));
+                last = message.id;
+                yield* delivered;
+                yield* emit({
+                    cursor: message.id,
+                    event: decoded,
+                    commandId: data.commandId,
+                    timestamp: data.timestamp,
+                });
+            })));
+        }));
+    },
+});

package/dist/client/sessions/sse.d.ts

@@ -0,0 +1,47 @@
+import { Effect, type Scope, Stream } from "effect";
+import { type Failure } from "../transport.ts";
+/**
+ * One SSE message as a session reads it. `id` is set only when the message
+ * introduced a new, non-empty last event id. A standard parser gives every
+ * message the last id seen, so a message without its own `id` line, such as a
+ * feed's terminal `end`, inherits the previous one; `id` hides that.
+ */
+export interface Message {
+    readonly event: string;
+    readonly id: string | undefined;
+    readonly data: string;
+}
+/** No bytes for this long, keepalive comments included, means the stream is dead. */
+export declare const IDLE_MS = 45000;
+/**
+ * The messages of an SSE response, parsed by the standard parser: CR, LF, and
+ * CRLF line ends split anywhere across chunks, a leading BOM, UTF-8 split
+ * across chunks, and an `id` containing NUL ignored. A `200` without a body
+ * fails as undecodable, and any other status fails with `refused` of its body. With `idleMs`, a body that
+ * sends no bytes for that long ends the stream. Ending the stream cancels the
+ * body.
+ */
+export declare const readEvents: ({ response, refused, idleMs, }: {
+    readonly response: Response;
+    readonly refused: (text: string, status: number, headers: Headers) => Failure;
+    readonly idleMs?: number | undefined;
+}) => Stream.Stream<Message, Failure>;
+/**
+ * The values `run` emits as a Stream that ends when `run` returns and fails
+ * with what it fails with. `signal` interrupts it, closing `run`'s scope.
+ */
+export declare const session: <A>({ signal, run, }: {
+    readonly signal: AbortSignal | undefined;
+    readonly run: (emit: (value: A) => Effect.Effect<void>) => Effect.Effect<void, Failure, Scope.Scope>;
+}) => Stream.Stream<A, Failure>;
+/**
+ * Runs `attempt`, one connection of a feed or a watch, again after every end
+ * that another attempt can resolve: a closed or idle body, a retryable
+ * `ActorError`, or one expired credential. An attempt calls `delivered` after
+ * each value, which resets the backoff and permits one more credential
+ * refresh. The next attempt waits for the server's `retryAfter` when the end
+ * carried one, else a jittered delay growing from 100 ms to 5 s. Any other
+ * failure ends the session. Which position the next attempt resumes from is
+ * the attempt's own state, not this loop's.
+ */
+export declare const reconnecting: (attempt: (delivered: Effect.Effect<void>) => Effect.Effect<void, Failure, Scope.Scope>) => Effect.Effect<never, Failure, never>;

package/dist/client/sessions/sse.js

@@ -0,0 +1,112 @@
+import { Cause, Clock, Duration, Effect, Option, Queue, Random, Schema, Stream, } from "effect";
+import { Sse } from "effect/encoding";
+import { ActorError, Unauthorized } from "../../errors/actor.js";
+import { aborted, networkFailure, undecodableFailure } from "../transport.js";
+/**
+ * The framework bounds no single served message except a feed's events, at
+ * the 1 MiB a turn may emit; watch results and stream elements are as large as
+ * the query or handler makes them. The parser therefore takes any size the
+ * server sends instead of Effect's 10 MiB default.
+ */
+const DECODE = { maxEventSize: Number.POSITIVE_INFINITY };
+/** No bytes for this long, keepalive comments included, means the stream is dead. */
+export const IDLE_MS = 45_000;
+const MAX_BACKOFF_MS = 5_000;
+/**
+ * The chunks of `body`, read in the consuming fiber so the first read is
+ * issued as soon as the response arrives, ending when the body closes or,
+ * with `idleMs`, once no chunk arrived for that long. The idle watchdog
+ * cancels the body, which ends the pending read, instead of racing each read
+ * against a timer: a raced or forked read can miss a chunk that arrives just
+ * before the body fails. Closing the stream cancels the body.
+ */
+const chunks = (body, idleMs) => Stream.unwrap(Effect.gen(function* () {
+    const reader = body.getReader();
+    const cancel = Effect.promise(() => reader.cancel().catch(() => undefined));
+    let last = yield* Clock.currentTimeMillis;
+    yield* Effect.addFinalizer(() => cancel);
+    if (idleMs !== undefined)
+        yield* Effect.gen(function* () {
+            while (true) {
+                const wait = last + idleMs - (yield* Clock.currentTimeMillis);
+                if (wait <= 0)
+                    return yield* cancel;
+                yield* Effect.sleep(Duration.millis(wait));
+            }
+        }).pipe(Effect.forkScoped);
+    return Stream.fromEffectRepeat(Effect.tryPromise({ try: () => reader.read(), catch: networkFailure }).pipe(Effect.flatMap((read) => (read.done ? Cause.done() : Effect.succeed(read.value))), Effect.tap(() => Clock.currentTimeMillis.pipe(Effect.map((now) => {
+        last = now;
+    })))));
+}));
+/**
+ * The messages of an SSE response, parsed by the standard parser: CR, LF, and
+ * CRLF line ends split anywhere across chunks, a leading BOM, UTF-8 split
+ * across chunks, and an `id` containing NUL ignored. A `200` without a body
+ * fails as undecodable, and any other status fails with `refused` of its body. With `idleMs`, a body that
+ * sends no bytes for that long ends the stream. Ending the stream cancels the
+ * body.
+ */
+export const readEvents = ({ response, refused, idleMs, }) => {
+    if (response.status !== 200)
+        return Stream.fromEffect(Effect.tryPromise({ try: () => response.text(), catch: networkFailure }).pipe(Effect.flatMap((text) => Effect.fail(refused(text, response.status, response.headers)))));
+    const body = response.body;
+    if (body === null)
+        return Stream.fail(undecodableFailure());
+    return chunks(body, idleMs).pipe(Stream.decodeText, Stream.pipeThroughChannel(Sse.decode(DECODE)), Stream.mapError((error) => Sse.Retry.is(error)
+        ? networkFailure()
+        : Schema.is(ActorError)(error)
+            ? error
+            : undecodableFailure()), Stream.mapAccum(() => undefined, (seen, message) => [
+        message.id,
+        [
+            {
+                event: message.event,
+                data: message.data,
+                id: message.id === seen || message.id === "" ? undefined : message.id,
+            },
+        ],
+    ]));
+};
+/**
+ * The values `run` emits as a Stream that ends when `run` returns and fails
+ * with what it fails with. `signal` interrupts it, closing `run`'s scope.
+ */
+export const session = ({ signal, run, }) => Stream.callback((out) => run((value) => Queue.offer(out, value).pipe(Effect.asVoid)).pipe(Effect.scoped, Effect.catch((failure) => Queue.fail(out, failure)), Effect.andThen(Queue.end(out)))).pipe(Stream.interruptWhen(aborted(signal)));
+const isExpired = (failure) => Schema.is(Unauthorized)(failure.reason) && failure.reason.code === "expired";
+/**
+ * Runs `attempt`, one connection of a feed or a watch, again after every end
+ * that another attempt can resolve: a closed or idle body, a retryable
+ * `ActorError`, or one expired credential. An attempt calls `delivered` after
+ * each value, which resets the backoff and permits one more credential
+ * refresh. The next attempt waits for the server's `retryAfter` when the end
+ * carried one, else a jittered delay growing from 100 ms to 5 s. Any other
+ * failure ends the session. Which position the next attempt resumes from is
+ * the attempt's own state, not this loop's.
+ */
+export const reconnecting = Effect.fnUntraced(function* (attempt) {
+    let failures = 0;
+    let authRetried = false;
+    const delivered = Effect.sync(() => {
+        failures = 0;
+        authRetried = false;
+    });
+    while (true) {
+        const ended = yield* attempt(delivered).pipe(Effect.scoped, Effect.flip, Effect.option);
+        let hinted = undefined;
+        if (Option.isSome(ended)) {
+            const failure = ended.value;
+            if (!Schema.is(ActorError)(failure))
+                return yield* failure;
+            const refresh = !authRetried && isExpired(failure);
+            if (!failure.isRetryable && !refresh)
+                return yield* failure;
+            if (refresh)
+                authRetried = true;
+            hinted = Option.getOrUndefined(failure.retryAfter);
+        }
+        const backoff = Math.min(MAX_BACKOFF_MS, 100 * 2 ** failures);
+        failures += 1;
+        const jitter = yield* Random.nextBetween(0.5, 1.5);
+        yield* Effect.sleep(Duration.millis(hinted ?? Math.round(backoff * jitter)));
+    }
+});

package/dist/client/sessions/stream.d.ts

@@ -0,0 +1,28 @@
+import { Effect, type Option, Schema, Stream } from "effect";
+import type { ServedMember } from "../../actor/served.ts";
+import type { ValueSchema } from "../../members/command.ts";
+import { type Failure } from "../transport.ts";
+/** Options of one stream subscription. */
+export interface StreamOptions {
+    /** Ends the subscription. */
+    readonly signal?: AbortSignal;
+}
+interface StreamSource {
+    /** The served stream member subscribed to. */
+    readonly member: ServedMember;
+    /** Posts the subscription with its encoded input and fresh headers. */
+    readonly open: (signal: AbortSignal) => Effect.Effect<Response, Failure>;
+    /** Decodes the member's declared errors from a served body. */
+    readonly declared: (body: Schema.Json) => Option.Option<Failure>;
+    readonly options: StreamOptions;
+}
+/**
+ * One subscription to an `Actor.stream` member: its elements as they arrive,
+ * ending when the stream ends by itself and failing with the `ActorError` or
+ * declared error that ended it. Streams have no cursor, so a dropped
+ * subscription is not resumed: it fails with a retryable `TransportError`,
+ * and the caller subscribes again. A stream that closes without an `end`
+ * message was cut, not finished.
+ */
+export declare const subscription: ({ member, open, declared, options, }: StreamSource) => Stream.Stream<ValueSchema["Type"], Failure>;
+export {};

package/dist/client/sessions/stream.js

@@ -0,0 +1,35 @@
+import { Effect, Schema, Stream } from "effect";
+import { decodeFailure, networkFailure, undecodableFailure } from "../transport.js";
+import { readEvents, session } from "./sse.js";
+const decodeJson = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Json));
+/** Ends the subscription's read loop after the stream's own successful `end`. */
+class Finished {
+    _tag = "Finished";
+}
+/**
+ * One subscription to an `Actor.stream` member: its elements as they arrive,
+ * ending when the stream ends by itself and failing with the `ActorError` or
+ * declared error that ended it. Streams have no cursor, so a dropped
+ * subscription is not resumed: it fails with a retryable `TransportError`,
+ * and the caller subscribes again. A stream that closes without an `end`
+ * message was cut, not finished.
+ */
+export const subscription = ({ member, open, declared, options, }) => session({
+    signal: options.signal,
+    run: (emit) => Effect.gen(function* () {
+        const decodeElement = Schema.decodeUnknownEffect(Schema.toCodecJson(member.output));
+        const failureOf = (text, status) => decodeFailure(declared)({ status, headers: new Headers(), text, sentAt: 0 });
+        const response = yield* open(yield* Effect.abortSignal);
+        const read = readEvents({ response, refused: failureOf }).pipe(Stream.runForEach((message) => Effect.gen(function* () {
+            const json = yield* decodeJson(message.data).pipe(Effect.mapError(undecodableFailure));
+            if (message.event !== "end")
+                return yield* emit(yield* decodeElement(json).pipe(Effect.mapError(undecodableFailure)));
+            return yield* json === null
+                ? Effect.fail(new Finished())
+                : Effect.fail(failureOf(message.data, 0));
+        })));
+        const cut = yield* read.pipe(Effect.as(true), Effect.catchIf((error) => error instanceof Finished, () => Effect.succeed(false)));
+        if (cut)
+            return yield* networkFailure();
+    }),
+});

package/dist/client/sessions/watch.d.ts

@@ -0,0 +1,34 @@
+import { Effect, type Option, Schema, Stream } from "effect";
+import { type Failure } from "../transport.ts";
+/** Options of one watch. */
+export interface WatchOptions {
+    /** Ends the iteration; the watch stops at once. */
+    readonly signal?: AbortSignal;
+}
+interface WatchSource<A> {
+    /** Decodes one result's JSON: the watched query's output, or a fleet page. */
+    readonly decode: (json: Schema.Json) => Effect.Effect<A, Failure>;
+    /**
+     * Posts the watch with its encoded input and fresh headers. `version` is the
+     * least commit version its first result must reflect, sent as
+     * `durable-min-version`.
+     */
+    readonly open: (version: string | undefined, signal: AbortSignal) => Effect.Effect<Response, Failure>;
+    /** Decodes the query's declared errors from a served body. */
+    readonly declared: (body: Schema.Json) => Option.Option<Failure>;
+    /** The consistency token the client holds when the watch starts. */
+    readonly token: () => string | undefined;
+    readonly options: WatchOptions;
+}
+/**
+ * One watch of served state, a query declared `watch: true` or a fleet view:
+ * its current result, then the newest result after each change. A watch is
+ * state, not history, so a dropped connection is reopened after a jittered,
+ * growing delay, or the server's `retryAfter`, with the greatest version any
+ * result carried as `durable-min-version`; its first result is the current
+ * state, never older than one already delivered. It fails with the query's
+ * declared error or the `ActorError` that ended it when a retry cannot help,
+ * and an expired credential is retried once.
+ */
+export declare const watchStream: <A>({ decode, open, declared, token, options, }: WatchSource<A>) => Stream.Stream<A, Failure>;
+export {};