@gjermundgaraba/effect-actions-cloudflare 0.0.0-stage → 0.22.0

package/dist/sockets.d.mts

@@ -0,0 +1,115 @@
+import { State } from "./state.mjs";
+import { Context, Effect, Layer } from "effect";
+import { HttpRouter, HttpServerResponse } from "effect/http";
+import { RpcServer } from "effect/rpc";
+/** What a protocol does with the events of the sockets carrying its tag. */
+interface Receiver {
+  /** Hands a message to the protocol. */
+  readonly message: (socket: WebSocket, data: string | ArrayBuffer) => Effect.Effect<void>;
+  /** Tells the protocol the socket closed or failed. */
+  readonly close: (socket: WebSocket) => Effect.Effect<void>;
+}
+declare const Sockets_base: Context.ServiceClass<Sockets, "effect-actions-cloudflare/ActionDurableObject/Sockets", {
+  /** Hands a message on `socket`, as `webSocketMessage` receives it, to its protocol. */
+  readonly message: (socket: WebSocket, data: string | ArrayBuffer) => Effect.Effect<boolean>;
+  /**
+   * Completes the closing handshake of any socket, replying with the client's `code` and
+   * `reason`, as `webSocketClose` receives them, and tells the socket's protocol it closed,
+   * interrupting its running calls.
+   */
+  readonly close: (socket: WebSocket, code: number, reason: string) => Effect.Effect<boolean>;
+  /** Tells the socket's protocol it failed, which ends it as a close does. */
+  readonly error: (socket: WebSocket) => Effect.Effect<boolean>;
+  /**
+   * Hands the events of the sockets carrying `tag` to `receiver`, as a protocol builds, or
+   * answers `false` when another protocol already holds that tag.
+   */
+  readonly register: (tag: string, receiver: Receiver) => boolean;
+  /** The next socket's id, never one an open socket has or this instance gave before. */
+  readonly allocate: Effect.Effect<number>;
+}>;
+/**
+ * The object's dispatcher for the sockets the protocols of its routes accept, such as
+ * `layerWebSocket`'s: each event method hands a socket's event to the protocol whose tag the
+ * socket carries, and succeeds with `true` once that protocol has it, or with `false` when no
+ * protocol accepted the socket, such as one the object accepted itself, which the caller answers.
+ * `handlers` and `make` provide one per instance, which the protocols register with as the routes
+ * build: a requirement of `layerWebSocket`, named as a type alone.
+ *
+ * **Gotchas**
+ *
+ * - A socket accepted by an earlier version of the routes at another `path` carries a tag no protocol holds now, and is answered `false`: close it, or serve that `path` again.
+ */
+export declare class Sockets extends Sockets_base {
+  /** One dispatcher, with no protocol registered, for the instance whose `State` it is given. */
+  static readonly layer: Layer.Layer<Sockets, never, State>;
+}
+/**
+ * The answer router middleware gives a WebSocket upgrade it refuses, such as one from a foreign
+ * `Origin`, as `layerWebSocket`'s `protocol` refuses a page of another version: 101, with a socket of its own closed at once with
+ * `code` and `reason`, which the page's Effect client fails its calls and streams with, as
+ * `SocketCloseError`. A browser cannot read the status of an upgrade it was refused, so this is
+ * how a refusal reaches the page.
+ *
+ * **Gotchas**
+ *
+ * - A 403, or any other status, reaches a browser's WebSocket as a bare 1006, as a network drop, and Effect's client connects again, half a second later and growing to every five seconds, for good.
+ * - Effect's client connects again after this close as well, as often and for good, each upgrade waking the object, unless its `retryPolicy` is the core's `ActionRpc.reconnectUntil(code)`, the client half of this refusal.
+ * - Its socket is accepted without the hibernation API and the library's route never runs, so the object keeps nothing of it; that accepted end ties up its request until the close handshake completes, so the object stays awake until the page answers the close.
+ * - `code` is an integer from 4000 to 4999, the codes the core's `watch` ends at, connecting again after any other: another dies.
+ */
+export declare const refuseUpgrade: (code: number, reason: string) => Effect.Effect<HttpServerResponse.HttpServerResponse>;
+/** `layerWebSocket`'s options. */
+export interface LayerWebSocketOptions {
+  /** The upgrade route. */
+  readonly path: HttpRouter.PathInput;
+  /**
+   * The version of the rpcs the route serves, which a page names in its socket's URL, as
+   * `?protocol=<version>`: an upgrade naming none, or another, is refused with
+   * `refuseUpgrade(code, reason)`, which a page's client stops at given the core's
+   * `ActionRpc.reconnectUntil(code)`.
+   */
+  readonly protocol?: {
+    /** The version served, compared with the query parameter as a string. */
+    readonly version: string;
+    /** The close code of a refusal, which a page's client stops at and its `watch` ends at: an integer from 4000 to 4999, the private-use codes; another fails `layerWebSocket`'s build. */
+    readonly code: number;
+    /** The close reason of a refusal, at most 123 bytes UTF-8 encoded, as a close frame holds: a longer one, the default included, fails `layerWebSocket`'s build. By default `This server speaks protocol <version>: reload the page`, which fits a `version` of up to 78 bytes: give a reason with a longer one. */
+    readonly reason?: string;
+  };
+}
+/**
+ * The `RpcServer.Protocol` `ActionRpc.layer` serves on, in an object's routes: WebSockets the
+ * object accepts at `path`, with the runtime's hibernation API, for the runtime to hold while
+ * the object hibernates, speaking JSON, the client's `RpcSerialization.layerJson` over
+ * `RpcClient.layerProtocolSocket`. A socket keeps its upgrade request's headers, as Effect's own
+ * socket protocol does, its credential included, and each message is authenticated with those
+ * under its own, its own winning. It keeps each event subscription `ActionRpc.layer` admits
+ * across hibernation. It registers with the instance's `Sockets`, which hands it their events,
+ * and requires it.
+ *
+ * **Gotchas**
+ *
+ * - An idle object is evicted while its sockets stay open: a message constructs a new instance, which builds the routes and then answers it.
+ * - A message's event ends once the message is handed to the server: a call doing I/O or waiting on a timer keeps the object from hibernating, billed as long, and one waiting only on in-memory state, such as a `Deferred`, is lost if the object hibernates. A call an eviction, a deploy or a crash cut off closes its socket with 1012 as the next instance builds, so its client fails it with a `SocketCloseError` and connects again; on celld 0.6.2, which drops attachments, it waits for good.
+ * - An `ActionRpc` event subscription is kept in the object's storage, under `effect-actions/subscription/`, its headers, tokens and cookies included, with it, and resumed from the position it reached when the object next wakes, on any event, authenticated again from those headers: a token that expired meanwhile ends it with `Unauthenticated`.
+ * - A kept subscription that cannot be resumed, such as one a later version of this package stores in another shape, closes its socket with 1000, logged, so the page's client connects again and its `watch` subscribes anew.
+ * - A native stream rpc or a streaming action is not kept: waiting on in-memory state, it is lost if the object hibernates, its socket closed with 1012 as the next instance builds; serve what a page follows as an event.
+ * - Each chunk that moves a kept subscription's position is one small storage write, and it is sent with no heartbeat: Effect's socket client tells a dead socket by its pings.
+ * - `storage.deleteAll()` deletes the kept subscriptions too, so a watch hears nothing more once the object hibernates: close the sockets with it, so their clients connect again and watch anew.
+ * - A client's close frame is answered with its own code and reason, as the closing handshake asks, whatever the `compatibility_date`: where the runtime already replied, under `web_socket_auto_reply_to_close`, the second reply is ignored; a socket the class accepted itself is the class's to answer.
+ * - An upgrade whose headers, cookies included, exceed the runtime's 16 KiB attachment is answered 431, and a call whose id would take the attachment past it fails at once with a defect naming it, never run; a request to `path` that is no upgrade is answered 426.
+ * - workerd keeps a socket's headers across hibernation; celld 0.6.2 drops them when it evicts an idle object, so a message relying on the upgrade's token is refused as unauthenticated: send a token on each message.
+ * - The upgrade's URL and query are not kept, as Effect's own socket protocol keeps neither: a message has no URL, so an API key in the query never authenticates; `protocol` reads the upgrade's query for a version, and router middleware reads it for any other judge, refusing with `refuseUpgrade`.
+ * - A browser WebSocket sets no header on its upgrade, so a page sends its token on each message, with `RpcClient.withHeaders`; under a cookie scheme the browser sends the cookie on any page's upgrade, which is never preflighted, so refuse a foreign `Origin` with router middleware, which runs for the upgrade, returning `refuseUpgrade`: a 403 reaches the page as a bare 1006, and its client connects again for good.
+ * - The verifier runs for every message, so a token that expires refuses the next call: a client renews it on its messages, or connects again.
+ * - Router middleware around the routes runs for the upgrade request alone, never for a socket's messages: list an `RpcMiddleware` in `ActionRpc.layer`'s `middleware` for a per-message service.
+ * - Each protocol of one object needs a `path` of its own: a router prefix does not tell two apart, and two at one `path` fail the build.
+ * - The runtime answers a client's pings itself, every five seconds, so an open page does not wake the object.
+ * - Effect's `RpcServer.layerProtocolWebsocket` cannot upgrade a web handler's request: on Workers, serve sockets with this.
+ * - A handler's die under a plain `RpcServer.layer` is Effect's fatal `Defect`, failing every call in flight on that socket, a call made in the dying one's continuation included, as Effect's own design, unlike over the object's stub: serve with `RpcServer.layer(group, { disableFatalDefects: true })`, or through `ActionRpc.layer`, to fail that call alone.
+ *
+ * Guide: `docs/ActionDurableObject.md` in this package.
+ */
+export declare const layerWebSocket: (options: LayerWebSocketOptions) => Layer.Layer<RpcServer.Protocol, never, Sockets | State | HttpRouter.HttpRouter>;
+export {};

package/dist/sockets.mjs

@@ -0,0 +1,243 @@
+import { State } from "./state.mjs";
+import { RequestId, closeQuietly, groupTag, parser, sendFrame, socketIdOf, socketTag } from "./frames.mjs";
+import { makeSubscriptions } from "./subscriptions.mjs";
+import { Context, Effect, Exit, Function, Layer, Match, Predicate, Queue, Schema } from "effect";
+import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/http";
+import { RpcMessage, RpcSerialization, RpcServer } from "effect/rpc";
+import * as ActionRpc from "@gjermundgaraba/effect-actions/ActionRpc";
+// src/durable/sockets.ts
+const replyToClose = (socket, code, reason) => Effect.sync(() => {
+	if (code >= 1e3 && code !== 1005 && code !== 1006 && code !== 1015) closeQuietly(socket, code, reason);
+	else closeQuietly(socket);
+});
+/**
+* The object's dispatcher for the sockets the protocols of its routes accept, such as
+* `layerWebSocket`'s: each event method hands a socket's event to the protocol whose tag the
+* socket carries, and succeeds with `true` once that protocol has it, or with `false` when no
+* protocol accepted the socket, such as one the object accepted itself, which the caller answers.
+* `handlers` and `make` provide one per instance, which the protocols register with as the routes
+* build: a requirement of `layerWebSocket`, named as a type alone.
+*
+* **Gotchas**
+*
+* - A socket accepted by an earlier version of the routes at another `path` carries a tag no protocol holds now, and is answered `false`: close it, or serve that `path` again.
+*/
+var Sockets = class Sockets extends Context.Service()("effect-actions-cloudflare/ActionDurableObject/Sockets") {
+	/** One dispatcher, with no protocol registered, for the instance whose `State` it is given. */
+	static layer = Layer.effect(Sockets)(Effect.gen(function* () {
+		const state = yield* State;
+		const receivers = /* @__PURE__ */ new Map();
+		let next = Math.max(1, ...state.getWebSockets().map((socket) => socketIdOf(state.getTags(socket)) + 1));
+		const dispatch = (socket, event) => Effect.suspend(() => {
+			const receiver = state.getTags(socket).map((tag) => receivers.get(tag)).find((found) => found !== void 0);
+			return receiver === void 0 ? Effect.succeed(false) : Effect.as(event(receiver), true);
+		});
+		return Sockets.of({
+			message: (socket, data) => dispatch(socket, (receiver) => receiver.message(socket, data)),
+			close: (socket, code, reason) => Effect.andThen(replyToClose(socket, code, reason), dispatch(socket, (receiver) => receiver.close(socket))),
+			error: (socket) => dispatch(socket, (receiver) => receiver.close(socket)),
+			register: (tag, receiver) => {
+				if (receivers.has(tag)) return false;
+				receivers.set(tag, receiver);
+				return true;
+			},
+			allocate: Effect.sync(() => {
+				const id = next;
+				next += 1;
+				return id;
+			})
+		});
+	}));
+};
+const Attachment = Schema.Struct({
+	headers: Schema.Array(Schema.mutable(Schema.Tuple([Schema.String, Schema.String]))),
+	pending: Schema.optional(Schema.Array(RequestId))
+});
+const decodeAttachment = Schema.decodeUnknownExit(Schema.NullishOr(Attachment));
+/** The socket's attachment, failing when it does not decode, or `undefined` with none. */
+const attachmentOf = (socket) => Exit.map(decodeAttachment(socket.deserializeAttachment()), (held) => held ?? void 0);
+/** The socket's attachment, or `undefined` with none or one that does not decode. */
+const heldOf = (socket) => Exit.match(attachmentOf(socket), {
+	onFailure: Function.constUndefined,
+	onSuccess: (held) => held
+});
+const pendingOf = (socket) => heldOf(socket)?.pending ?? [];
+const tracked = (socket, update) => {
+	const held = heldOf(socket);
+	if (held === void 0) return true;
+	const pending = update(held.pending ?? []);
+	try {
+		socket.serializeAttachment(Attachment.make({
+			headers: held.headers,
+			...pending.length > 0 && { pending }
+		}));
+		return true;
+	} catch {
+		return false;
+	}
+};
+const settledBy = (response) => Match.value(response).pipe(Match.tag("Exit", ({ requestId }) => (pending) => pending.filter((id) => id !== requestId)), Match.tag("Defect", () => () => []), Match.orElse(Function.constUndefined));
+const lostCalls = "This server lost the calls it was answering on this socket: connect again";
+const untracked = "This socket's attachment, its upgrade's headers and the ids of its calls under way, would pass the runtime's 16 KiB: send fewer calls at once, or fewer or smaller headers on the upgrade";
+const encodeDefect = Schema.encodeSync(RpcSerialization.json.codecFor(Schema.Defect()));
+const upgraded = (client) => HttpServerResponse.raw(new Response(null, {
+	status: 101,
+	webSocket: client
+}), { status: 101 });
+const closeReasonBytes = 123;
+const bytesOf = (text) => new TextEncoder().encode(text).byteLength;
+const acceptedCode = (code) => Number.isInteger(code) && code >= 4e3 && code <= 4999;
+const refusalOf = (protocol) => Effect.gen(function* () {
+	if (protocol === void 0) return;
+	const { version, code, reason = `This server speaks protocol ${version}: reload the page` } = protocol;
+	if (!acceptedCode(code)) return yield* Effect.die(/* @__PURE__ */ new Error(`ActionDurableObject.layerWebSocket's protocol.code ${code} is not one it accepts, an integer from 4000 to 4999, the codes a watch ends at: give one of those`));
+	if (bytesOf(reason) > closeReasonBytes) return yield* Effect.die(/* @__PURE__ */ new Error(`ActionDurableObject.layerWebSocket's protocol.reason, given or the default naming its version, is ${bytesOf(reason)} bytes, more than the ${closeReasonBytes} a close frame holds: give a reason of at most ${closeReasonBytes} bytes, UTF-8 encoded`));
+	return {
+		version,
+		code,
+		reason
+	};
+});
+/**
+* The answer router middleware gives a WebSocket upgrade it refuses, such as one from a foreign
+* `Origin`, as `layerWebSocket`'s `protocol` refuses a page of another version: 101, with a socket of its own closed at once with
+* `code` and `reason`, which the page's Effect client fails its calls and streams with, as
+* `SocketCloseError`. A browser cannot read the status of an upgrade it was refused, so this is
+* how a refusal reaches the page.
+*
+* **Gotchas**
+*
+* - A 403, or any other status, reaches a browser's WebSocket as a bare 1006, as a network drop, and Effect's client connects again, half a second later and growing to every five seconds, for good.
+* - Effect's client connects again after this close as well, as often and for good, each upgrade waking the object, unless its `retryPolicy` is the core's `ActionRpc.reconnectUntil(code)`, the client half of this refusal.
+* - Its socket is accepted without the hibernation API and the library's route never runs, so the object keeps nothing of it; that accepted end ties up its request until the close handshake completes, so the object stays awake until the page answers the close.
+* - `code` is an integer from 4000 to 4999, the codes the core's `watch` ends at, connecting again after any other: another dies.
+*/
+const refuseUpgrade = (code, reason) => Effect.suspend(() => {
+	if (!acceptedCode(code)) return Effect.die(/* @__PURE__ */ new Error(`ActionDurableObject.refuseUpgrade's code ${code} is not one it accepts, an integer from 4000 to 4999, the codes a watch ends at: give one of those`));
+	const { 0: client, 1: server } = new WebSocketPair();
+	server.accept();
+	server.close(code, reason);
+	return Effect.succeed(upgraded(client));
+});
+/**
+* A hibernating `RpcServer.Protocol` over the object's WebSockets, speaking JSON, and its
+* upgrade route at `path`. Each socket carries two tags, its group's and its own id's, and keeps
+* its upgrade request's headers in its attachment, so both survive hibernation.
+*/
+const makeProtocol = (state, sockets, { path, protocol: version }) => Effect.gen(function* () {
+	const router = yield* HttpRouter.HttpRouter;
+	const context = yield* Effect.context();
+	const group = groupTag(path);
+	const refusal = yield* refusalOf(version);
+	const idOf = (socket) => socketIdOf(state.getTags(socket));
+	state.setWebSocketAutoResponse(new WebSocketRequestResponsePair(String(parser.encode(RpcMessage.constPing)), String(parser.encode(RpcMessage.constPong))));
+	const disconnects = yield* Queue.make();
+	const subscriptions = makeSubscriptions(state, path);
+	const send = (clientId, response) => sendFrame(state, clientId, response).pipe(Effect.andThen(Effect.sync(() => {
+		const settled = settledBy(response);
+		if (settled === void 0) return;
+		for (const socket of state.getWebSockets(socketTag(clientId))) tracked(socket, settled);
+	})), Effect.andThen(subscriptions.sent(clientId, response)));
+	const protocol = yield* RpcServer.Protocol.make((write) => {
+		if (!sockets.register(group, {
+			message: (socket, data) => {
+				const clientId = idOf(socket);
+				return Effect.gen(function* () {
+					const headers = (yield* Effect.orDie(attachmentOf(socket)))?.headers ?? [];
+					const messages = parser.decode(Predicate.isString(data) ? data : new Uint8Array(data));
+					const sent = messages.flatMap((message) => Predicate.isTagged(message, "Request") ? [message.id] : []);
+					const kept = sent.length === 0 || tracked(socket, (pending) => [...pending, ...sent]);
+					return yield* Effect.forEach(messages, (message) => {
+						if (!Predicate.isTagged(message, "Request")) return write(clientId, message);
+						return kept ? write(clientId, {
+							...message,
+							headers: [...headers, ...message.headers]
+						}) : send(clientId, RpcMessage.ResponseExitDieEncoded({
+							requestId: RpcMessage.RequestId(message.id),
+							encodedDefect: encodeDefect(untracked)
+						}));
+					}, { discard: true });
+				}).pipe(Effect.catchDefect((defect) => send(clientId, RpcMessage.ResponseDefectEncoded(encodeDefect(defect)))), Effect.asVoid, Effect.provideContext(context));
+			},
+			close: (socket) => {
+				const clientId = idOf(socket);
+				return Effect.andThen(subscriptions.closed(clientId), Effect.asVoid(Queue.offer(disconnects, clientId)));
+			}
+		})) return Effect.die(/* @__PURE__ */ new Error(`Two ActionDurableObject.layerWebSocket protocols of one object serve the path ${path}: a router prefix does not tell them apart: give each its own path, such as /a/rpc and /b/rpc`));
+		const resumed = subscriptions.resumed(write, (socket, kept) => {
+			if (pendingOf(socket).every(kept)) return true;
+			closeQuietly(socket, 1012, lostCalls);
+			return false;
+		});
+		return Effect.as(resumed, {
+			disconnects,
+			send,
+			end: (clientId) => Effect.sync(() => {
+				for (const socket of state.getWebSockets(socketTag(clientId))) closeQuietly(socket, 1e3);
+			}),
+			clientIds: Effect.sync(() => new Set(state.getWebSockets(group).map(idOf))),
+			initialMessage: Effect.succeedNone,
+			supportsAck: true,
+			supportsTransferables: false,
+			supportsSpanPropagation: true,
+			supportsNotifications: true,
+			codecFor: RpcSerialization.json.codecFor
+		});
+	});
+	yield* router.add("GET", path, Effect.gen(function* () {
+		const request = yield* HttpServerRequest.HttpServerRequest;
+		if (request.headers["upgrade"]?.toLowerCase() !== "websocket") return HttpServerResponse.text("Expected a WebSocket upgrade: connect with a WebSocket client, or forward the page's own Request to the object", { status: 426 });
+		if (refusal !== void 0) {
+			const { protocol: named } = yield* HttpServerRequest.ParsedSearchParams;
+			if (named !== refusal.version) return yield* refuseUpgrade(refusal.code, refusal.reason);
+		}
+		const { 0: client, 1: server } = new WebSocketPair();
+		const attached = yield* Effect.exit(Effect.try(() => {
+			server.serializeAttachment(Attachment.make({ headers: Object.entries(request.headers) }));
+		}));
+		if (Exit.isFailure(attached)) return HttpServerResponse.text("The headers a socket keeps exceed its attachment: send fewer or smaller cookies to this path, or the token on each message", { status: 431 });
+		state.acceptWebSocket(server, [group, socketTag(yield* sockets.allocate)]);
+		return upgraded(client);
+	}));
+	return {
+		...protocol,
+		[ActionRpc.subscriptionKeeper]: subscriptions.keeper
+	};
+});
+/**
+* The `RpcServer.Protocol` `ActionRpc.layer` serves on, in an object's routes: WebSockets the
+* object accepts at `path`, with the runtime's hibernation API, for the runtime to hold while
+* the object hibernates, speaking JSON, the client's `RpcSerialization.layerJson` over
+* `RpcClient.layerProtocolSocket`. A socket keeps its upgrade request's headers, as Effect's own
+* socket protocol does, its credential included, and each message is authenticated with those
+* under its own, its own winning. It keeps each event subscription `ActionRpc.layer` admits
+* across hibernation. It registers with the instance's `Sockets`, which hands it their events,
+* and requires it.
+*
+* **Gotchas**
+*
+* - An idle object is evicted while its sockets stay open: a message constructs a new instance, which builds the routes and then answers it.
+* - A message's event ends once the message is handed to the server: a call doing I/O or waiting on a timer keeps the object from hibernating, billed as long, and one waiting only on in-memory state, such as a `Deferred`, is lost if the object hibernates. A call an eviction, a deploy or a crash cut off closes its socket with 1012 as the next instance builds, so its client fails it with a `SocketCloseError` and connects again; on celld 0.6.2, which drops attachments, it waits for good.
+* - An `ActionRpc` event subscription is kept in the object's storage, under `effect-actions/subscription/`, its headers, tokens and cookies included, with it, and resumed from the position it reached when the object next wakes, on any event, authenticated again from those headers: a token that expired meanwhile ends it with `Unauthenticated`.
+* - A kept subscription that cannot be resumed, such as one a later version of this package stores in another shape, closes its socket with 1000, logged, so the page's client connects again and its `watch` subscribes anew.
+* - A native stream rpc or a streaming action is not kept: waiting on in-memory state, it is lost if the object hibernates, its socket closed with 1012 as the next instance builds; serve what a page follows as an event.
+* - Each chunk that moves a kept subscription's position is one small storage write, and it is sent with no heartbeat: Effect's socket client tells a dead socket by its pings.
+* - `storage.deleteAll()` deletes the kept subscriptions too, so a watch hears nothing more once the object hibernates: close the sockets with it, so their clients connect again and watch anew.
+* - A client's close frame is answered with its own code and reason, as the closing handshake asks, whatever the `compatibility_date`: where the runtime already replied, under `web_socket_auto_reply_to_close`, the second reply is ignored; a socket the class accepted itself is the class's to answer.
+* - An upgrade whose headers, cookies included, exceed the runtime's 16 KiB attachment is answered 431, and a call whose id would take the attachment past it fails at once with a defect naming it, never run; a request to `path` that is no upgrade is answered 426.
+* - workerd keeps a socket's headers across hibernation; celld 0.6.2 drops them when it evicts an idle object, so a message relying on the upgrade's token is refused as unauthenticated: send a token on each message.
+* - The upgrade's URL and query are not kept, as Effect's own socket protocol keeps neither: a message has no URL, so an API key in the query never authenticates; `protocol` reads the upgrade's query for a version, and router middleware reads it for any other judge, refusing with `refuseUpgrade`.
+* - A browser WebSocket sets no header on its upgrade, so a page sends its token on each message, with `RpcClient.withHeaders`; under a cookie scheme the browser sends the cookie on any page's upgrade, which is never preflighted, so refuse a foreign `Origin` with router middleware, which runs for the upgrade, returning `refuseUpgrade`: a 403 reaches the page as a bare 1006, and its client connects again for good.
+* - The verifier runs for every message, so a token that expires refuses the next call: a client renews it on its messages, or connects again.
+* - Router middleware around the routes runs for the upgrade request alone, never for a socket's messages: list an `RpcMiddleware` in `ActionRpc.layer`'s `middleware` for a per-message service.
+* - Each protocol of one object needs a `path` of its own: a router prefix does not tell two apart, and two at one `path` fail the build.
+* - The runtime answers a client's pings itself, every five seconds, so an open page does not wake the object.
+* - Effect's `RpcServer.layerProtocolWebsocket` cannot upgrade a web handler's request: on Workers, serve sockets with this.
+* - A handler's die under a plain `RpcServer.layer` is Effect's fatal `Defect`, failing every call in flight on that socket, a call made in the dying one's continuation included, as Effect's own design, unlike over the object's stub: serve with `RpcServer.layer(group, { disableFatalDefects: true })`, or through `ActionRpc.layer`, to fail that call alone.
+*
+* Guide: `docs/ActionDurableObject.md` in this package.
+*/
+const layerWebSocket = (options) => Layer.effect(RpcServer.Protocol)(Effect.gen(function* () {
+	return yield* makeProtocol(yield* State, yield* Sockets, options);
+}));
+export { Sockets, layerWebSocket, refuseUpgrade };

package/dist/state.d.mts

@@ -0,0 +1,18 @@
+import { Context, Effect } from "effect";
+declare const State_base: Context.ServiceClass<State, "effect-actions-cloudflare/ActionDurableObject/State", DurableObjectState<unknown>>;
+/**
+ * The object's own `DurableObjectState`, `ctx`: its storage, its id, its alarm and its sockets.
+ * A startup service of the object's services, routes and alarm, one per instance, so a store
+ * over `storage.sql` is a Layer requiring it.
+ */
+export declare class State extends State_base {}
+/**
+ * The name the Worker reached the object by, `getByName(name)`, from `State`'s id: what the
+ * object is, such as its room, as a startup service, `Layer.effect(Room)(name)`.
+ *
+ * **Gotchas**
+ *
+ * - An object reached by an id that carries no name, from `idFromString` or `newUniqueId`, dies at once, `was reached by an id that carries none`: reach it with `getByName`.
+ */
+export declare const name: Effect.Effect<string, never, State>;
+export {};

package/dist/state.mjs

@@ -0,0 +1,18 @@
+import { Context, Effect } from "effect";
+// src/durable/state.ts
+/**
+* The object's own `DurableObjectState`, `ctx`: its storage, its id, its alarm and its sockets.
+* A startup service of the object's services, routes and alarm, one per instance, so a store
+* over `storage.sql` is a Layer requiring it.
+*/
+var State = class extends Context.Service()("effect-actions-cloudflare/ActionDurableObject/State") {};
+/**
+* The name the Worker reached the object by, `getByName(name)`, from `State`'s id: what the
+* object is, such as its room, as a startup service, `Layer.effect(Room)(name)`.
+*
+* **Gotchas**
+*
+* - An object reached by an id that carries no name, from `idFromString` or `newUniqueId`, dies at once, `was reached by an id that carries none`: reach it with `getByName`.
+*/
+const name = Effect.flatMap(Effect.service(State), ({ id }) => id.name === void 0 ? Effect.die(/* @__PURE__ */ new Error(`ActionDurableObject.name reads the name the Worker reached the object by, and the object ${id.toString()} was reached by an id that carries none, as from idFromString or newUniqueId: reach it with getByName(name)`)) : Effect.succeed(id.name));
+export { State, name };

package/dist/stub.d.mts

@@ -0,0 +1,59 @@
+import { StubRequest } from "./calls.mjs";
+import { Effect, Layer, Scope } from "effect";
+import { Rpc, RpcClient, RpcClientError, RpcGroup, RpcSchema } from "effect/rpc";
+/**
+ * What a call reaches an object's rpcs through: a `DurableObjectStub` of a class `make` returns,
+ * or of a class delegating `effectActionsRpc` to `handlers`, as `getByName` returns it. Its
+ * answer is untyped data until the client checks it: Workers RPC's types rewrite a returned
+ * tuple as an array.
+ */
+export interface Stub {
+  readonly effectActionsRpc: (request: StubRequest) => Promise<readonly unknown[]>;
+}
+/**
+ * The `RpcClient.Protocol` `RpcClient.make` and `ActionRpc.client` call an object's rpcs with,
+ * over `stub`, or over the stub a function returns as each call is sent: each call is one call
+ * of the object's `effectActionsRpc` method, its messages and their answer passed as values,
+ * each schema's plain form, which the object serves through `make`'s or `handlers`' `calls`. The stub's own failure is an `RpcClientError`, as an HTTP transport's
+ * is, in every call's errors.
+ *
+ * **Gotchas**
+ *
+ * - A stub given is held, and many exceptions leave a stub broken, failing every later call through it with the same error: give a function, `() => env.ROOM.getByName(name)`, called as each call is sent, for a new stub each time; one that throws is a defect, not an `RpcClientError`, as it is no failure of the stub.
+ * - An `RpcClientError`'s `RpcClientDefect` holds the runtime's error as its `cause`: `.retryable` true allows repeating the call, as Cloudflare's guide says, and `.durableObjectReset` true needs a new stub, which a function gives.
+ * - Workers RPC limits a call's arguments and its answer to 32 MiB, serialized: past it, the call fails with the runtime's `limited to 32MiB` error.
+ * - An object serving no `calls`, once built, or a class without the method, fails each call, with the object's or the runtime's message as the error's cause; an object whose build fails fails it with that failure first.
+ * - A call's interruption does not reach the object, as a stub call cannot be cancelled: its answer is dropped.
+ * - Unary: an rpc that streams fails with a defect at its first chunk, so a handler returning a stream that never emits leaves the call waiting for good; `client` gives such an rpc no method.
+ * - `RpcClient.make` over it forks a fiber started on a timer of the request that builds it, which workerd drops when that request ends: a client first built lazily inside a Worker's request that ends without waiting on I/O never starts it, and every later call waits until workerd cancels it as hung; build the client per request or, shared, at module scope under Effect's sync scheduler, as `HttpRouter.toWebHandler`'s gotchas show, where a `ManagedRuntime.make` builds only at its first run, so one made at module scope is still built inside a request; an object's build, under the microtask scheduler, did not strand it in the tests.
+ *
+ * Guide: `docs/ActionDurableObject-stub.md` in this package.
+ */
+export declare const layerStubClient: (stub: Stub | (() => Stub)) => Layer.Layer<RpcClient.Protocol>;
+type Unary<Rpcs extends Rpc.Any> = Rpcs extends Rpc.Any ? [Rpc.SuccessSchema<Rpcs>] extends [RpcSchema.Stream<infer _A, infer _E>] ? never : Rpcs : never;
+/**
+ * A group's rpcs, as `client.<rpc>(payload)`: Effect's native client, each call failing with
+ * the rpc's declared errors or an `RpcClientError`. An rpc that streams has no method: the
+ * transport is unary.
+ */
+export type Client<Group> = RpcClient.RpcClient<Unary<RpcGroup.Rpcs<Group>>, RpcClientError.RpcClientError>;
+/**
+ * The rpcs of `group`, as `(stubOf) => client`, for a Worker or an object calling objects of
+ * one class: `room(() => env.CHAT_ROOM.getByName(name)).latestAt()`. One native client, built
+ * in the given `Scope`, serves every object, and each call gets its stub from `stubOf` as it is
+ * sent, so no stub is held, nothing is kept per object and an eviction changes nothing: a
+ * client over one object may be kept for good. Each call goes over `layerStubClient`'s
+ * transport, whose gotchas hold here too: a call fails with the rpc's declared errors and the
+ * stub's own failure, an `RpcClientError`, as Effect's native client does.
+ *
+ * **Gotchas**
+ *
+ * - `stubOf` reads `env` as each call is sent, from the `env` import of `cloudflare:workers` or the `env` `make`'s `services` function is given, never as the module evaluates; one that throws is a defect.
+ * - Only names you accept should reach `getByName`: each name is another object.
+ * - An `ActionRpc` binding's `group` fails here, `Expected null`, as `ActionRpc.layer` carries its values as JSON over the stub's protocol passing values: call such an object's actions and native rpcs with `ActionRpc.client` over `layerStubClient(() => stub)`.
+ * - An rpc that streams has no method, as `Client` types it.
+ *
+ * Guide: `docs/ActionDurableObject-stub.md` in this package.
+ */
+export declare const client: <Rpcs extends Rpc.Any>(group: RpcGroup.RpcGroup<Rpcs>) => Effect.Effect<(stubOf: () => Stub) => Client<RpcGroup.RpcGroup<Rpcs>>, never, Scope.Scope | Rpc.MiddlewareClient<Rpcs>>;
+export {};

package/dist/stub.mjs

@@ -0,0 +1,75 @@
+import { codecFor } from "./calls.mjs";
+import { RequestId } from "./frames.mjs";
+import { Context, Effect, Function, Layer, Option, Predicate, Schema } from "effect";
+import { RpcClient, RpcClientError, RpcSchema } from "effect/rpc";
+// src/durable/stub.ts
+const clientError = (reason) => new RpcClientError.RpcClientError({ reason });
+const isAnswer = Schema.is(Schema.Array(Schema.Struct({ _tag: Schema.String })));
+const completionOf = Schema.decodeUnknownOption(Schema.Union([Schema.TaggedStruct("Exit", { requestId: RequestId }), Schema.Struct({ _tag: Schema.Literals(["Defect", "ClientProtocolError"]) })]));
+const makeProtocol = (target) => RpcClient.Protocol.make((write) => Effect.succeed({
+	send: (clientId, request) => Predicate.isTagged(request, "Request") ? Effect.gen(function* () {
+		const stub = yield* target;
+		const answer = yield* Effect.tryPromise({
+			try: async () => await stub.effectActionsRpc([request]),
+			catch: (cause) => clientError(new RpcClientError.RpcClientDefect({
+				message: "The object's stub refused the call",
+				cause
+			}))
+		});
+		if (!(isAnswer(answer) && answer.some((response) => Option.exists(completionOf(response), (completion) => !Predicate.isTagged(completion, "Exit") || completion.requestId === request.id)))) return yield* clientError(new RpcClientError.RpcClientDefect({
+			message: "The object's answer ended before the call completed: delegate effectActionsRpc to handlers' own, returning its answer",
+			cause: request
+		}));
+		yield* Effect.forEach(answer, (response) => write(clientId, response), { discard: true });
+	}) : Effect.void,
+	supportsAck: false,
+	supportsTransferables: false,
+	codecFor
+}));
+/**
+* The `RpcClient.Protocol` `RpcClient.make` and `ActionRpc.client` call an object's rpcs with,
+* over `stub`, or over the stub a function returns as each call is sent: each call is one call
+* of the object's `effectActionsRpc` method, its messages and their answer passed as values,
+* each schema's plain form, which the object serves through `make`'s or `handlers`' `calls`. The stub's own failure is an `RpcClientError`, as an HTTP transport's
+* is, in every call's errors.
+*
+* **Gotchas**
+*
+* - A stub given is held, and many exceptions leave a stub broken, failing every later call through it with the same error: give a function, `() => env.ROOM.getByName(name)`, called as each call is sent, for a new stub each time; one that throws is a defect, not an `RpcClientError`, as it is no failure of the stub.
+* - An `RpcClientError`'s `RpcClientDefect` holds the runtime's error as its `cause`: `.retryable` true allows repeating the call, as Cloudflare's guide says, and `.durableObjectReset` true needs a new stub, which a function gives.
+* - Workers RPC limits a call's arguments and its answer to 32 MiB, serialized: past it, the call fails with the runtime's `limited to 32MiB` error.
+* - An object serving no `calls`, once built, or a class without the method, fails each call, with the object's or the runtime's message as the error's cause; an object whose build fails fails it with that failure first.
+* - A call's interruption does not reach the object, as a stub call cannot be cancelled: its answer is dropped.
+* - Unary: an rpc that streams fails with a defect at its first chunk, so a handler returning a stream that never emits leaves the call waiting for good; `client` gives such an rpc no method.
+* - `RpcClient.make` over it forks a fiber started on a timer of the request that builds it, which workerd drops when that request ends: a client first built lazily inside a Worker's request that ends without waiting on I/O never starts it, and every later call waits until workerd cancels it as hung; build the client per request or, shared, at module scope under Effect's sync scheduler, as `HttpRouter.toWebHandler`'s gotchas show, where a `ManagedRuntime.make` builds only at its first run, so one made at module scope is still built inside a request; an object's build, under the microtask scheduler, did not strand it in the tests.
+*
+* Guide: `docs/ActionDurableObject-stub.md` in this package.
+*/
+const layerStubClient = (stub) => Layer.effect(RpcClient.Protocol)(makeProtocol(Predicate.isFunction(stub) ? Effect.sync(stub) : Effect.succeed(stub)));
+const CurrentStub = Context.Reference("effect-actions-cloudflare/ActionDurableObject/CurrentStub", { defaultValue: Function.constUndefined });
+const currentStub = Effect.flatMap(Effect.service(CurrentStub), (stubOf) => stubOf === void 0 ? Effect.die(/* @__PURE__ */ new Error("No stub for the call")) : Effect.sync(stubOf));
+/**
+* The rpcs of `group`, as `(stubOf) => client`, for a Worker or an object calling objects of
+* one class: `room(() => env.CHAT_ROOM.getByName(name)).latestAt()`. One native client, built
+* in the given `Scope`, serves every object, and each call gets its stub from `stubOf` as it is
+* sent, so no stub is held, nothing is kept per object and an eviction changes nothing: a
+* client over one object may be kept for good. Each call goes over `layerStubClient`'s
+* transport, whose gotchas hold here too: a call fails with the rpc's declared errors and the
+* stub's own failure, an `RpcClientError`, as Effect's native client does.
+*
+* **Gotchas**
+*
+* - `stubOf` reads `env` as each call is sent, from the `env` import of `cloudflare:workers` or the `env` `make`'s `services` function is given, never as the module evaluates; one that throws is a defect.
+* - Only names you accept should reach `getByName`: each name is another object.
+* - An `ActionRpc` binding's `group` fails here, `Expected null`, as `ActionRpc.layer` carries its values as JSON over the stub's protocol passing values: call such an object's actions and native rpcs with `ActionRpc.client` over `layerStubClient(() => stub)`.
+* - An rpc that streams has no method, as `Client` types it.
+*
+* Guide: `docs/ActionDurableObject-stub.md` in this package.
+*/
+const client = (group) => Effect.gen(function* () {
+	const native = yield* RpcClient.make(group).pipe(Effect.provideServiceEffect(RpcClient.Protocol, makeProtocol(currentStub)), Effect.map((made) => made));
+	const rpcs = group.requests.values();
+	const unary = new Set([...rpcs].flatMap((rpc) => RpcSchema.isStreamSchema(rpc.successSchema) ? [] : [rpc._tag]));
+	return (stubOf) => Object.fromEntries(Object.entries(native).flatMap(([tag, method]) => unary.has(tag) ? [[tag, (...args) => method(...args).pipe(Effect.provideService(CurrentStub, stubOf))]] : []));
+});
+export { client, layerStubClient };