@mcp-b/do-runtime 0.5.0 → 0.6.0

package/dist/index.js

@@ -1,4 +1,4 @@
-import { a as hasUserErrorDetail, c as setUserErrorDetail, d as tryCurrentSlice, f as CanceledError, i as captureGateStack, m as OutputGate, n as IoContext, o as isExceptionFromInputGateBroken, p as InputGate, r as atCheckpointEnd, s as requireInputLock, t as BrokenActorError, u as tryCurrentIoContext } from "./chunks/io-context-RmmjNtwm.js";
+import { a as hasUserErrorDetail, c as setUserErrorDetail, d as tryCurrentSlice, f as CanceledError, i as captureGateStack, m as OutputGate, n as IoContext, o as isExceptionFromInputGateBroken, p as InputGate, r as atCheckpointEnd, s as requireInputLock, t as BrokenActorError, u as tryCurrentIoContext } from "./chunks/io-context-BBgKEsdR.js";
 import { RpcTarget as RpcTarget$1 } from "./cloudflare-workers.js";
 import { a as SqliteDatabase, c as getText, l as hasCurrentSqliteTable, o as getBlob, s as getInt64, t as ensureRuntimeStorageVersion, u as isNull } from "./chunks/sqlite-migrations-DsWmLP_B.js";
 import { ALARM_RETRY_MAX_TRIES, ALARM_RETRY_START_SECONDS, AlarmScheduler, RETRY_BACKOFF_MAX, RETRY_JITTER_FACTOR, alarmRetryDelayMs } from "./server/alarm-scheduler.js";
@@ -46,10 +46,10 @@ var ColoLocalActorNamespace = class {
 		return this.#channel.getColoLocalActor({ actorId });
 	}
 };
-var textEncoder$1 = new TextEncoder();
+var textEncoder$2 = new TextEncoder();
 /** `kj::String::size()` is bytes; `String.prototype.length` is UTF-16 code units. */
 function utf8Length(value) {
-	return textEncoder$1.encode(value).length;
+	return textEncoder$2.encode(value).length;
 }
 /**
 * ← `DurableObjectId` (`actor.h:42-84`). "DurableObjectId type seen by
@@ -1750,11 +1750,9 @@ function asRawRow(values) {
 * `transformMaybeBackpressure` keeps the branch because
 * `DeleteAllResults.backpressure` is still a promise in `io/actor-cache.ts`.
 *
-* Not ported, because the substrate has no equivalent: Hibernatable WebSockets,
-* which is the whole reason `DurableObjectState`'s eight WebSocket methods are
-* named throwing stubs; V8's private wire bytes, replaced by a browser-safe
-* structured-clone encoding with the same public value semantics; the billing
-* counters
+* Not ported, because the substrate has no equivalent: V8's private wire bytes,
+* replaced by a browser-safe structured-clone encoding with the same public
+* value semantics; the billing counters
 * (`billingUnits`, `ActorObserver`, `updateStorageWriteUnit`) and the trace
 * spans, both already absent throughout; `enableSql`, a workerd namespace option
 * that exists to simulate a non-SQLite Durable Object; and `ReplicaActorOutgoingFactory`,
@@ -1773,14 +1771,6 @@ var FACET_NAME_MAX_LENGTH = 256;
 /** Root is at depth 0, so the deepest allowed facet is at depth 3. */
 var FACET_TREE_MAX_DEPTH = 4;
 /**
-* The substrate boundary named in the package README: Hibernatable WebSockets
-* exist so the platform can evict an actor while keeping its sockets open, and
-* Chrome exposes no equivalent lifecycle. Under this repo's fail-closed tenet
-* the throw IS the specified behaviour, which is why §2.5 orders the four
-* silent no-op stubs beside it replaced.
-*/
-var HIBERNATION_UNIMPLEMENTED_MESSAGE = "Hibernatable WebSockets are not available in this runtime: they exist so the platform can evict a Durable Object while keeping its sockets open, and there is no equivalent lifecycle to be faithful to.";
-/**
 * ← what falls off the end of `DurableObjectFacets::get`'s class switch
 * (`actor-state.c++:1029-1043`).
 *
@@ -1828,7 +1818,7 @@ function isPutOptions(value) {
 var NULL_CHARACTER = "\0";
 /** ← the `0xff` upstream strips from the tail of a prefix, in UTF-16 code units. */
 var MAX_CODE_UNIT = 65535;
-var textEncoder = new TextEncoder();
+var textEncoder$1 = new TextEncoder();
 var textDecoder = new TextDecoder();
 /** A byte JSON could never begin with, `DO`, and the local codec version. */
 var VALUE_CODEC_HEADER = new Uint8Array([
@@ -1844,7 +1834,7 @@ var VALUE_CODEC_HEADER = new Uint8Array([
 * remain readable.
 */
 function serializeValue(value) {
-	const body = textEncoder.encode(JSON.stringify(serialize(value)));
+	const body = textEncoder$1.encode(JSON.stringify(serialize(value)));
 	const encoded = new Uint8Array(VALUE_CODEC_HEADER.byteLength + body.byteLength);
 	encoded.set(VALUE_CODEC_HEADER);
 	encoded.set(body, VALUE_CODEC_HEADER.byteLength);
@@ -2291,7 +2281,7 @@ var DurableObjectTransaction = class extends DurableObjectStorageOperations {
 * refuses, which is a bound a caller can hit.
 */
 function requireValidFacetName(name) {
-	if (textEncoder.encode(name).length > 256) throw new TypeError(`Facet name is too long (max 256 characters).`);
+	if (textEncoder$1.encode(name).length > 256) throw new TypeError(`Facet name is too long (max 256 characters).`);
 }
 /**
 * ← the `KJ_SWITCH_ONEOF(options.$class)` lambda (`actor-state.c++:1029-1043`).
@@ -2474,29 +2464,29 @@ var DurableObjectState = class {
 		if (options.mode !== "auto" && options.mode !== "disabled") throw new TypeError(`configureReadReplication() called with unknown mode setting: ${options.mode}.`);
 		return this.#ctx.awaitIo(storage.getActorCacheInterface().configureReadReplication(options.mode === "auto"));
 	}
-	acceptWebSocket(_ws, _tags) {
-		throw new Error(HIBERNATION_UNIMPLEMENTED_MESSAGE);
+	acceptWebSocket(ws, tags) {
+		this.#options.webSockets.acceptWebSocket(ws, tags);
 	}
-	getWebSockets(_tag) {
-		throw new Error(HIBERNATION_UNIMPLEMENTED_MESSAGE);
+	getWebSockets(tag) {
+		return tag === void 0 ? this.#options.webSockets.getWebSockets() : this.#options.webSockets.getWebSockets(tag);
 	}
-	setWebSocketAutoResponse(_maybeReqResp) {
-		throw new Error(HIBERNATION_UNIMPLEMENTED_MESSAGE);
+	setWebSocketAutoResponse(maybeReqResp) {
+		this.#options.webSockets.setWebSocketAutoResponse(maybeReqResp);
 	}
 	getWebSocketAutoResponse() {
-		throw new Error(HIBERNATION_UNIMPLEMENTED_MESSAGE);
+		return this.#options.webSockets.getWebSocketAutoResponse();
 	}
-	getWebSocketAutoResponseTimestamp(_ws) {
-		throw new Error(HIBERNATION_UNIMPLEMENTED_MESSAGE);
+	getWebSocketAutoResponseTimestamp(ws) {
+		return this.#options.webSockets.getWebSocketAutoResponseTimestamp(ws);
 	}
-	setHibernatableWebSocketEventTimeout(_timeoutMs) {
-		throw new Error(HIBERNATION_UNIMPLEMENTED_MESSAGE);
+	setHibernatableWebSocketEventTimeout(timeoutMs) {
+		this.#options.webSockets.setHibernatableWebSocketEventTimeout(timeoutMs);
 	}
 	getHibernatableWebSocketEventTimeout() {
-		throw new Error(HIBERNATION_UNIMPLEMENTED_MESSAGE);
+		return this.#options.webSockets.getHibernatableWebSocketEventTimeout();
 	}
-	getTags(_ws) {
-		throw new Error(HIBERNATION_UNIMPLEMENTED_MESSAGE);
+	getTags(ws) {
+		return this.#options.webSockets.getTags(ws);
 	}
 };
 //#endregion
@@ -2766,6 +2756,528 @@ function gateReader(ctx, reader) {
 	} });
 }
 //#endregion
+//#region src/api/web-socket.ts
+var WebSocketRequestResponsePairImpl = class {
+	#request;
+	#response;
+	constructor(request, response) {
+		this.#request = String(request);
+		this.#response = String(response);
+	}
+	get request() {
+		return this.#request;
+	}
+	get response() {
+		return this.#response;
+	}
+};
+var RuntimeWebSocketRequestResponsePair = new Proxy(WebSocketRequestResponsePairImpl, { apply() {
+	throw new TypeError("Failed to construct 'WebSocketRequestResponsePair': Please use the 'new' operator, this DOM object constructor cannot be called as a function.");
+} });
+/** ← the `JSG_REQUIRE(!native.state.is<Accepted>(), ...)` at the head of `accept()`. */
+var ALREADY_ACCEPTED_MESSAGE = "acceptWebSocket(): this socket has already been accepted by an actor. A socket's frames are delivered by exactly one read loop, and a second accept would deliver them under two gates.";
+var HIBERNATION_ALREADY_ACCEPTED_MESSAGE = "Cannot call `acceptWebSocket()` if the WebSocket was already accepted via `accept()`";
+var HIBERNATION_AFTER_ACCEPT_MESSAGE = "Can't accept() WebSocket after enabling hibernation.";
+var HIBERNATION_PAIR_USED_MESSAGE = "Cannot call `acceptWebSocket()` on this WebSocket because its pair has already been accepted or used in a Response.";
+var MAX_HIBERNATABLE_SOCKETS = 32768;
+var MAX_TAGS = 10;
+var MAX_TAG_LENGTH = 256;
+var MAX_ATTACHMENT_BYTES = 16384;
+var MAX_AUTO_RESPONSE_BYTES = 2048;
+var MAX_EVENT_TIMEOUT = 6048e5;
+var MAX_CLOSE_REASON_BYTES = 123;
+var WEB_SOCKET_READY_STATES = {
+	READY_STATE_CONNECTING: 0,
+	READY_STATE_OPEN: 1,
+	READY_STATE_CLOSING: 2,
+	READY_STATE_CLOSED: 3,
+	CONNECTING: 0,
+	OPEN: 1,
+	CLOSING: 2,
+	CLOSED: 3
+};
+var textEncoder = new TextEncoder();
+var SOCKET_EVENTS = [
+	"open",
+	"message",
+	"close",
+	"error"
+];
+var metadata = /* @__PURE__ */ new WeakMap();
+function socketMetadata(socket) {
+	let value = metadata.get(socket);
+	if (value === void 0) {
+		value = {};
+		metadata.set(socket, value);
+	}
+	return value;
+}
+function isRawWebSocket(value) {
+	return typeof value === "object" && value !== null && "addEventListener" in value && typeof value.addEventListener === "function" && "send" in value && typeof value.send === "function" && "close" in value && typeof value.close === "function";
+}
+function requireWebSocket(value, operation) {
+	if (!isRawWebSocket(value)) throw new TypeError(`Failed to execute '${operation}' on 'WebSocket': parameter 1 is not of type 'WebSocket'.`);
+	return value;
+}
+function serializeAttachment(socket, value) {
+	try {
+		structuredClone(value);
+	} catch (error) {
+		if (error instanceof DOMException && error.name === "DataCloneError") throw new DOMException(error.message.replace(/^Failed to execute 'structuredClone' on '[^']+': /, ""), "DataCloneError");
+		throw error;
+	}
+	const bytes = serializeValue(value);
+	const measuredBytes = typeof value === "string" ? textEncoder.encode(value).byteLength + 5 : bytes.byteLength;
+	if (measuredBytes > MAX_ATTACHMENT_BYTES) throw new Error(`A WebSocket 'attachment' cannot be larger than ${MAX_ATTACHMENT_BYTES} bytes.'attachment' was ${measuredBytes} bytes.`);
+	const state = socketMetadata(socket);
+	state.attachment = bytes;
+	if (state.accepted?.mode === "hibernatable") state.accepted.registry.attachmentChanged(socket, bytes);
+}
+function deserializeAttachment(socket) {
+	const attachment = socketMetadata(socket).attachment;
+	if (attachment === void 0) return null;
+	return deserializeValue("WebSocket attachment", attachment);
+}
+function serializeAttachmentMethod(value) {
+	if (arguments.length === 0) throw new TypeError("Failed to execute 'serializeAttachment' on 'WebSocket': parameter 1 is not of type 'Value'.");
+	serializeAttachment(requireWebSocket(this, "serializeAttachment"), value);
+}
+function deserializeAttachmentMethod() {
+	return deserializeAttachment(requireWebSocket(this, "deserializeAttachment"));
+}
+function cloneMessageData(data) {
+	if (typeof data === "string" || data instanceof Blob) return data;
+	if (data instanceof ArrayBuffer) return data.slice(0);
+	if (ArrayBuffer.isView(data)) return new Uint8Array(data.buffer, data.byteOffset, data.byteLength).slice().buffer;
+	return String(data);
+}
+var MemoryWebSocketEndpoint = class extends EventTarget {
+	peer;
+	#sentClose = false;
+	send(data) {
+		this.peer.dispatchEvent(new MessageEvent("message", { data: cloneMessageData(data) }));
+	}
+	close(code = 1e3, reason = "") {
+		if (this.#sentClose) return;
+		this.#sentClose = true;
+		this.peer.dispatchEvent(new CloseEvent("close", {
+			code,
+			reason,
+			wasClean: true
+		}));
+	}
+};
+/** One public socket identity, in classic or hibernatable mode after acceptance. */
+var AcceptedWebSocket = class AcceptedWebSocket extends EventTarget {
+	static READY_STATE_CONNECTING = WEB_SOCKET_READY_STATES.READY_STATE_CONNECTING;
+	static READY_STATE_OPEN = WEB_SOCKET_READY_STATES.READY_STATE_OPEN;
+	static READY_STATE_CLOSING = WEB_SOCKET_READY_STATES.READY_STATE_CLOSING;
+	static READY_STATE_CLOSED = WEB_SOCKET_READY_STATES.READY_STATE_CLOSED;
+	static CONNECTING = WEB_SOCKET_READY_STATES.CONNECTING;
+	static OPEN = WEB_SOCKET_READY_STATES.OPEN;
+	static CLOSING = WEB_SOCKET_READY_STATES.CLOSING;
+	static CLOSED = WEB_SOCKET_READY_STATES.CLOSED;
+	bufferedAmount = 0;
+	extensions = "";
+	protocol = "";
+	url = "";
+	#ctx;
+	#socket;
+	#pairState;
+	#delivery = { mode: "pending" };
+	#pump = Promise.resolve();
+	#pending = [];
+	#readyState = AcceptedWebSocket.OPEN;
+	#ownClose = false;
+	#peerClose = false;
+	#binaryType = "blob";
+	onopen = null;
+	onmessage = null;
+	onclose = null;
+	onerror = null;
+	constructor(ctx, socket, pairState) {
+		super();
+		this.#ctx = ctx;
+		this.#socket = socket;
+		this.#pairState = pairState;
+		if (pairState === void 0) this.#enableClassic();
+		for (const type of SOCKET_EVENTS) socket.addEventListener(type, (event) => {
+			this.#receive(type, event);
+		});
+	}
+	get readyState() {
+		return this.#readyState;
+	}
+	get binaryType() {
+		return this.#binaryType;
+	}
+	set binaryType(value) {
+		this.#binaryType = value;
+	}
+	accept() {
+		if (this.#delivery.mode === "hibernatable") throw new TypeError(HIBERNATION_AFTER_ACCEPT_MESSAGE);
+		if (this.#delivery.mode === "classic") throw new Error(ALREADY_ACCEPTED_MESSAGE);
+		if (this.#pairState !== void 0) this.#pairState.used = true;
+		this.#enableClassic();
+	}
+	send(data) {
+		if (this.#delivery.mode === "hibernatable" && this.#ownClose) throw new TypeError("Can't call WebSocket send() after close().");
+		if (this.#peerClose || this.#readyState === AcceptedWebSocket.CLOSED) return;
+		this.#markPairUsed();
+		this.#enqueue(() => this.#socket.send(data));
+	}
+	close(code, reason = "") {
+		if (this.#readyState === AcceptedWebSocket.CLOSED || this.#ownClose) return;
+		if (this.#delivery.mode === "hibernatable" || this.#pairState !== void 0) validateClose(code, reason);
+		this.#markPairUsed();
+		this.#ownClose = true;
+		this.#readyState = this.#peerClose ? AcceptedWebSocket.CLOSED : AcceptedWebSocket.CLOSING;
+		this.#enqueue(() => this.#socket.close(code, reason));
+	}
+	serializeAttachment(value) {
+		if (arguments.length === 0) serializeAttachmentMethod.call(this);
+		else serializeAttachment(this, value);
+	}
+	deserializeAttachment() {
+		return deserializeAttachment(this);
+	}
+	acceptHibernation(registry) {
+		if (this.#delivery.mode !== "pending") throw new Error(HIBERNATION_ALREADY_ACCEPTED_MESSAGE);
+		if (this.#pairState?.used === true && !this.#pairState.hibernationAccepted) throw new Error(HIBERNATION_PAIR_USED_MESSAGE);
+		if (this.#pairState !== void 0) {
+			this.#pairState.used = true;
+			this.#pairState.hibernationAccepted = true;
+		}
+		this.#activateHibernation(registry, this.#ctx);
+	}
+	rehydrateHibernation(registry, ctx) {
+		this.#activateHibernation(registry, ctx);
+	}
+	#activateHibernation(registry, ctx) {
+		this.#ctx = ctx;
+		this.#delivery = {
+			mode: "hibernatable",
+			registry
+		};
+		this.#pending = [];
+	}
+	markPairUsed() {
+		this.#markPairUsed();
+	}
+	#markPairUsed() {
+		if (this.#pairState !== void 0) this.#pairState.used = true;
+	}
+	#enableClassic() {
+		const delivery = {
+			mode: "classic",
+			criticalSection: this.#ctx.getCriticalSection()
+		};
+		this.#delivery = delivery;
+		socketMetadata(this).accepted = { mode: "classic" };
+		const pending = this.#pending;
+		this.#pending = [];
+		for (const item of pending) this.#deliverClassic(item.type, item.event, delivery.criticalSection);
+	}
+	#receive(type, event) {
+		if (type === "close") {
+			this.#receiveClose(event);
+			return;
+		}
+		const delivery = this.#delivery;
+		if (delivery.mode === "pending") this.#pending.push({
+			type,
+			event
+		});
+		else if (delivery.mode === "classic") this.#deliverClassic(type, event, delivery.criticalSection);
+		else delivery.registry.receive(this, type, event);
+	}
+	#receiveClose(event) {
+		if (this.#ownClose) this.#readyState = AcceptedWebSocket.CLOSED;
+		else {
+			this.#peerClose = true;
+			this.#readyState = AcceptedWebSocket.CLOSING;
+			if (this.#delivery.mode === "classic" && this.#pairState !== void 0) {
+				if (event.code === 1005 || event.code === 1006 || event.code === 1015) this.#readyState = AcceptedWebSocket.CLOSED;
+				else this.close(event.code, event.reason);
+			}
+		}
+		const delivery = this.#delivery;
+		if (delivery.mode === "pending") this.#pending.push({
+			type: "close",
+			event
+		});
+		else if (delivery.mode === "classic") this.#deliverClassic("close", event, delivery.criticalSection);
+		else delivery.registry.receive(this, "close", event);
+	}
+	#deliverClassic(type, event, criticalSection) {
+		this.#ctx.addWaitUntil(this.#ctx.run(() => {
+			const delivered = cloneEventFor(type, event);
+			this.dispatchEvent(delivered);
+			const handler = this[`on${type}`];
+			handler?.(delivered);
+		}, { input: criticalSection }));
+	}
+	#enqueue(write) {
+		const outputLock = this.#ctx.waitForOutputLocks();
+		this.#pump = this.#pump.then(async () => {
+			await outputLock;
+			write();
+		});
+		this.#ctx.addWaitUntil(this.#pump);
+	}
+};
+for (const [name, value] of Object.entries(WEB_SOCKET_READY_STATES)) Object.defineProperty(AcceptedWebSocket.prototype, name, {
+	value,
+	enumerable: true
+});
+var HibernatableWebSocketRegistry = class {
+	#ctx;
+	#dispatch;
+	#host;
+	#entries = [];
+	#autoResponse = null;
+	#eventTimeout = null;
+	#pairConstructor;
+	constructor(ctx, dispatch, host, rehydrated = []) {
+		this.#ctx = ctx;
+		this.#dispatch = dispatch;
+		this.#host = host;
+		for (const value of rehydrated) this.#rehydrate(value);
+	}
+	get WebSocketPair() {
+		const registry = this;
+		this.#pairConstructor ??= new Proxy(class WebSocketPair {}, { construct: () => registry.#createPair() });
+		return this.#pairConstructor;
+	}
+	acceptWebSocket(socket, tags) {
+		if (!isRawWebSocket(socket)) throw new TypeError("Failed to execute 'acceptWebSocket' on 'DurableObjectState': parameter 1 is not of type 'WebSocket'.");
+		const state = socketMetadata(socket);
+		if (state.accepted !== void 0) throw new Error(HIBERNATION_ALREADY_ACCEPTED_MESSAGE);
+		if (this.#entries.length >= MAX_HIBERNATABLE_SOCKETS) throw new Error(`only ${MAX_HIBERNATABLE_SOCKETS} websockets can be accepted on a single Durable Object instance`);
+		const normalizedTags = normalizeTags(tags);
+		if (socket instanceof AcceptedWebSocket) socket.acceptHibernation(this);
+		else this.#listenRaw(socket);
+		state.accepted = {
+			mode: "hibernatable",
+			registry: this
+		};
+		this.#entries.push({
+			socket,
+			tags: normalizedTags
+		});
+		this.#host?.accepted(socket, normalizedTags);
+	}
+	getWebSockets(tag) {
+		if (arguments.length > 0) {
+			if (typeof tag !== "string") return [];
+			return this.#entries.filter((entry) => entry.tags.includes(tag)).map((entry) => entry.socket);
+		}
+		return this.#entries.map((entry) => entry.socket).reverse();
+	}
+	getTags(socket) {
+		const state = isRawWebSocket(socket) ? metadata.get(socket) : void 0;
+		if (state?.accepted === void 0) throw new Error("you must call 'acceptWebSocket()' before attempting to access the tags of a WebSocket.");
+		if (state.accepted.mode !== "hibernatable") throw new Error("only hibernatable websockets can have tags.");
+		const entry = this.#entries.find((candidate) => candidate.socket === socket);
+		if (entry === void 0) throw new Error("you must call 'acceptWebSocket()' before attempting to access the tags of a WebSocket.");
+		return [...entry.tags];
+	}
+	setWebSocketAutoResponse(pair) {
+		if (pair === void 0) {
+			this.#autoResponse = null;
+			this.#host?.autoResponse(null);
+			return;
+		}
+		if (!(pair instanceof WebSocketRequestResponsePairImpl)) throw new TypeError("Failed to execute 'setWebSocketAutoResponse' on 'DurableObjectState': parameter 1 is not of type 'WebSocketRequestResponsePair'.");
+		validateAutoResponseSize("Request", pair.request);
+		validateAutoResponseSize("Response", pair.response);
+		this.#autoResponse = pair;
+		this.#host?.autoResponse({
+			request: pair.request,
+			response: pair.response
+		});
+	}
+	getWebSocketAutoResponse() {
+		const pair = this.#autoResponse;
+		return pair === null ? null : new RuntimeWebSocketRequestResponsePair(pair.request, pair.response);
+	}
+	getWebSocketAutoResponseTimestamp(socket) {
+		if (!isRawWebSocket(socket)) throw new TypeError("Failed to execute 'getWebSocketAutoResponseTimestamp' on 'DurableObjectState': parameter 1 is not of type 'WebSocket'.");
+		const timestamp = this.#entries.find((entry) => entry.socket === socket)?.autoResponseTimestamp;
+		return timestamp === void 0 ? null : new Date(timestamp);
+	}
+	setHibernatableWebSocketEventTimeout(value) {
+		if (value === void 0 || Number(value) === 0) {
+			this.#eventTimeout = null;
+			return;
+		}
+		const number = Number(value);
+		if (Number.isNaN(number)) throw new TypeError("The value cannot be converted because it is not an integer.");
+		if (number < 0) throw new TypeError("The value cannot be converted because it is negative and this API expects a positive number.");
+		if (number > 4294967295) throw new TypeError("Value out of range. Must be less than or equal to 4294967295.");
+		const timeout = Math.trunc(number);
+		if (timeout > MAX_EVENT_TIMEOUT) throw new Error(`Event timeout should not exceed ${MAX_EVENT_TIMEOUT} ms.`);
+		this.#eventTimeout = timeout;
+	}
+	getHibernatableWebSocketEventTimeout() {
+		return this.#eventTimeout;
+	}
+	attachmentChanged(socket, bytes) {
+		if (this.#entries.some((entry) => entry.socket === socket)) this.#host?.attachment(socket, bytes);
+	}
+	receive(socket, type, event) {
+		const entry = this.#entries.find((candidate) => candidate.socket === socket);
+		if (entry === void 0) return;
+		if (type === "message") {
+			const data = event.data;
+			if (typeof data === "string" && data === this.#autoResponse?.request) {
+				entry.autoResponseTimestamp = this.#ctx.now();
+				socket.send(this.#autoResponse.response);
+				return;
+			}
+			const message = cloneMessageData(data);
+			if (message instanceof Blob) {
+				this.#ctx.addWaitUntil(message.arrayBuffer().then((buffer) => {
+					this.#schedule(() => this.#dispatch.message(socket, buffer));
+				}));
+				return;
+			}
+			this.#schedule(() => this.#dispatch.message(socket, message));
+			return;
+		}
+		if (type === "close") {
+			this.#remove(entry);
+			const close = event;
+			this.#schedule(() => this.#dispatch.close(socket, close.code, close.reason, close.wasClean));
+			return;
+		}
+		if (type === "error") this.#schedule(() => this.#dispatch.error(socket, event));
+	}
+	#schedule(handler) {
+		this.#ctx.addWaitUntil(this.#ctx.run(handler).then(() => {}));
+	}
+	#remove(entry) {
+		const index = this.#entries.indexOf(entry);
+		if (index === -1) return;
+		this.#entries.splice(index, 1);
+		this.#host?.closed(entry.socket);
+	}
+	#listenRaw(socket) {
+		const state = socketMetadata(socket);
+		if (state.rawListenersInstalled === true) return;
+		state.rawListenersInstalled = true;
+		for (const type of [
+			"message",
+			"close",
+			"error"
+		]) socket.addEventListener(type, (event) => {
+			const accepted = socketMetadata(socket).accepted;
+			if (accepted?.mode === "hibernatable") accepted.registry.receive(socket, type, event);
+		});
+	}
+	#rehydrate(value) {
+		const socket = value.socket;
+		if (!isRawWebSocket(socket)) throw new TypeError("ActorContainerOptions.webSockets contains a non-WebSocket value.");
+		const tags = normalizeTags(value.tags);
+		const state = socketMetadata(socket);
+		state.accepted = {
+			mode: "hibernatable",
+			registry: this
+		};
+		if (value.attachment !== void 0) state.attachment = value.attachment.slice();
+		if (socket instanceof AcceptedWebSocket) socket.rehydrateHibernation(this, this.#ctx);
+		else this.#listenRaw(socket);
+		const entry = {
+			socket,
+			tags
+		};
+		if (value.autoResponseTimestamp !== void 0) entry.autoResponseTimestamp = value.autoResponseTimestamp;
+		this.#entries.push(entry);
+	}
+	#createPair() {
+		const pairState = {
+			used: false,
+			hibernationAccepted: false
+		};
+		const left = new MemoryWebSocketEndpoint();
+		const right = new MemoryWebSocketEndpoint();
+		left.peer = right;
+		right.peer = left;
+		return {
+			0: new AcceptedWebSocket(this.#ctx, left, pairState),
+			1: new AcceptedWebSocket(this.#ctx, right, pairState)
+		};
+	}
+};
+function acceptWebSocket(ctx, socket) {
+	const state = socketMetadata(socket);
+	if (state.accepted !== void 0) throw new Error(ALREADY_ACCEPTED_MESSAGE);
+	if (socket instanceof AcceptedWebSocket) {
+		socket.accept();
+		return socket;
+	}
+	state.accepted = { mode: "classic" };
+	return new AcceptedWebSocket(ctx, socket);
+}
+function markWebSocketUsed(socket) {
+	if (socket instanceof AcceptedWebSocket) socket.markPairUsed();
+}
+function installWebSocketGlobals(target, pairConstructor) {
+	const constructor = globalThis.WebSocket;
+	for (const [name, value] of Object.entries(WEB_SOCKET_READY_STATES)) {
+		defineValue(constructor, name, value);
+		defineValue(constructor.prototype, name, value);
+	}
+	defineValue(constructor.prototype, "serializeAttachment", serializeAttachmentMethod);
+	defineValue(constructor.prototype, "deserializeAttachment", deserializeAttachmentMethod);
+	defineValue(target, "WebSocket", constructor);
+	defineValue(target, "WebSocketPair", pairConstructor);
+	defineValue(target, "WebSocketRequestResponsePair", RuntimeWebSocketRequestResponsePair);
+}
+function defineValue(target, name, value) {
+	if (Object.getOwnPropertyDescriptor(target, name)?.configurable === false) return;
+	Object.defineProperty(target, name, {
+		configurable: true,
+		writable: true,
+		value
+	});
+}
+function normalizeTags(tags) {
+	if (tags === void 0) return [];
+	if (!Array.isArray(tags)) throw new TypeError("Failed to execute 'acceptWebSocket' on 'DurableObjectState': parameter 2 is not of type 'Array'.");
+	if (tags.length > MAX_TAGS) throw new Error(`a Hibernatable WebSocket cannot have more than ${MAX_TAGS} tags`);
+	const normalized = [...new Set(tags.map(String))];
+	for (const tag of normalized) if (tag.length > MAX_TAG_LENGTH) throw new Error(`"${tag}" is longer than the max tag length (${MAX_TAG_LENGTH} characters).`);
+	return normalized;
+}
+function validateAutoResponseSize(side, value) {
+	const bytes = textEncoder.encode(value).byteLength;
+	if (bytes > MAX_AUTO_RESPONSE_BYTES) throw new RangeError(`${side} cannot be larger than ${MAX_AUTO_RESPONSE_BYTES} bytes. A ${side.toLowerCase()} of size ${bytes} was provided.`);
+}
+function validateClose(code, reason) {
+	if (code !== void 0 && code !== 1e3 && (code < 3e3 || code > 4999)) throw new DOMException(`Invalid WebSocket close code: ${code}.`, "InvalidAccessError");
+	if (textEncoder.encode(reason).byteLength > MAX_CLOSE_REASON_BYTES) throw new DOMException(`WebSocket close reason must not be longer than ${MAX_CLOSE_REASON_BYTES} bytes when UTF-8 encoded.`, "SyntaxError");
+}
+function cloneEventFor(type, event) {
+	if (type === "message") {
+		const source = event;
+		return new MessageEvent("message", {
+			data: source.data,
+			origin: source.origin,
+			lastEventId: source.lastEventId
+		});
+	}
+	if (type === "close") {
+		const source = event;
+		return new CloseEvent("close", {
+			code: source.code,
+			reason: source.reason,
+			wasClean: source.wasClean
+		});
+	}
+	return new Event(type);
+}
+//#endregion
 //#region src/api/global-scope.ts
 /**
 * ← workerd `src/workerd/api/global-scope.{h,c++}` — the alarm half, and the
@@ -3019,10 +3531,11 @@ var ActorGlobalScope = class {
 	#readCurrentExternalEntry;
 	scheduler;
 	crypto;
-	constructor(ctx, options = {}) {
+	constructor(ctx, options) {
 		this.#ctx = ctx;
 		this.#fetch = options.fetch;
 		this.#readCurrentExternalEntry = options.currentExternalEntry;
+		installWebSocketGlobals(this, options.webSockets.WebSocketPair);
 		this.scheduler = new Scheduler(this);
 		this.crypto = new GatedCrypto((op) => {
 			this.#requireOwnSlice(op);
@@ -3127,6 +3640,7 @@ var ActorGlobalScope = class {
 * scope instead. A single-actor host simply writes `() => scope`.
 */
 function actorScopeBindings(resolve) {
+	const BoundWebSocketPair = new Proxy(class WebSocketPair {}, { construct: () => new (resolve()).WebSocketPair() });
 	return {
 		awaitIo: (promise) => resolve().awaitIo(promise),
 		scheduler: {
@@ -3143,6 +3657,9 @@ function actorScopeBindings(resolve) {
 		},
 		fetch: (input, init) => resolve().fetch(input, init),
 		crypto: scopeCrypto(resolve),
+		WebSocket: globalThis.WebSocket,
+		WebSocketPair: BoundWebSocketPair,
+		WebSocketRequestResponsePair: RuntimeWebSocketRequestResponsePair,
 		get currentExternalEntry() {
 			return resolve().currentExternalEntry;
 		}
@@ -3153,7 +3670,7 @@ function actorScopeBindings(resolve) {
 * an operation actually runs.
 *
 * That laziness is required rather than tidy, and both lanes proved it. A facet's
-* module destructures its seven names at module scope, which is BEFORE its container
+* module destructures its actor globals at module scope, which is BEFORE its container
 * exists — so a `crypto` that resolved on read threw at import. And on the root
 * path `globalThis.crypto` is read by things that are not the actor at all: capnweb,
 * the sqlite driver, the test runner. So the binding is a pair of plain objects
@@ -3199,8 +3716,8 @@ var ASYNC_SUBTLE_METHODS = [
 * one that is not.
 *
 * **A host should call this rather than assigning the names itself**, and the
-* reason is the failure it prevents: a host that installs five of the six leaves
-* one primitive ungated, and an ungated primitive that WORKS is invisible until
+* reason is the failure it prevents: a host that installs only a subset leaves a
+* primitive ungated, and an ungated primitive that WORKS is invisible until
 * a continuation after it touches storage — possibly never, on the path that
 * matters. The set is the package's, so it can grow without every host growing
 * with it.
@@ -3229,153 +3746,6 @@ function installActorScope(target, resolve) {
 		});
 	}
 }
-//#endregion
-//#region src/api/web-socket.ts
-/** ← the `JSG_REQUIRE(!native.state.is<Accepted>(), ...)` at the head of `accept()`. */
-var ALREADY_ACCEPTED_MESSAGE = "acceptWebSocket(): this socket has already been accepted by an actor. A socket's frames are delivered by exactly one read loop, and a second accept would deliver them under two gates.";
-/** Sockets this runtime has accepted, so the refusal above is answerable. */
-var accepted = /* @__PURE__ */ new WeakSet();
-/** The four events a `WebSocket` dispatches, which `readLoop` and its `.then` cover upstream. */
-var SOCKET_EVENTS = [
-	"open",
-	"message",
-	"close",
-	"error"
-];
-/**
-* ← `WebSocket::Accepted` (`web-socket.h:~300-360`), reached through
-* `accept()` → `internalAccept(js, IoContext::current().getCriticalSection())`
-* → `startReadLoop` (`web-socket.c++:133`, `:426`, `:429-433`, `:507`).
-*
-* An `EventTarget`, so a consumer registers listeners the way it would on a real
-* socket — but on THIS object rather than on the raw one, because this is what
-* runs them inside a gated slice.
-*/
-var AcceptedWebSocket = class extends EventTarget {
-	#ctx;
-	#socket;
-	/**
-	* ← `readLoop`'s `cs` parameter, captured at accept and replayed for every
-	* frame via `mapAddRef(cs)` (`web-socket.c++:1110`). A socket accepted inside
-	* `blockConcurrencyWhile` therefore delivers its messages inside that critical
-	* section — §1.8's second bullet, and the reason this is captured here rather
-	* than read when a frame arrives.
-	*/
-	#criticalSection;
-	/**
-	* ← `OutgoingMessagesMap outgoingMessages` plus `ensurePumping`
-	* (`web-socket.h:582-590`, `web-socket.c++:948-975`), as a chain.
-	*
-	* The table is insertion-ordered and the pump awaits each entry's own
-	* `outputLock` before sending it, so messages leave in order and message N
-	* waits only for the writes outstanding when IT was enqueued. A promise chain
-	* is the same two properties with nothing to schedule.
-	*/
-	#pump = Promise.resolve();
-	onopen = null;
-	onmessage = null;
-	onclose = null;
-	onerror = null;
-	constructor(ctx, socket) {
-		super();
-		this.#ctx = ctx;
-		this.#socket = socket;
-		this.#criticalSection = ctx.getCriticalSection();
-		for (const type of SOCKET_EVENTS) socket.addEventListener(type, (event) => {
-			this.#deliver(type, event);
-		});
-	}
-	/**
-	* ← `co_await context.run([...](auto& wLock) { dispatchEventImpl(...) }, mapAddRef(cs))`
-	* (`web-socket.c++:1065-1110`).
-	*
-	* The run rides `addWaitUntil`, as upstream's read loop does ("We put the read
-	* loop in a `waitUntil`, since there would otherwise be a race condition
-	* between delivering the final close message and the request being canceled",
-	* `web-socket.c++:537-541`). That is also what stops a listener's throw
-	* becoming an unhandled rejection: it lands in `waitUntilStatus()`.
-	*/
-	#deliver(type, event) {
-		this.#ctx.addWaitUntil(this.#ctx.run(() => {
-			const delivered = cloneEventFor(type, event);
-			this.dispatchEvent(delivered);
-			const handler = this[`on${type}`];
-			handler?.(delivered);
-		}, { input: this.#criticalSection }));
-	}
-	/**
-	* ← `WebSocket::send` (`web-socket.c++:~640`), which inserts a
-	* `GatedMessage{IoContext::current().waitForOutputLocksIfNecessary(), …}`.
-	*
-	* Synchronous, as upstream's is: the wait is the pump's, not the caller's. The
-	* output gate is what "blocks all outgoing messages from an actor that would
-	* allow the rest of the world to observe the actor's state" (§1.1), and a
-	* socket frame is exactly such a message.
-	*
-	* `waitForOutputLocksIfNecessary()` collapses to `waitForOutputLocks()` here
-	* for the reason the whole file collapses `kj::Maybe<Worker::Actor&>`: its
-	* body is `actor.map(…)` (`io-context.c++:383-386`) and every context in this
-	* runtime is an actor context.
-	*/
-	send(data) {
-		this.#enqueue(() => {
-			this.#socket.send(data);
-		});
-	}
-	/** ← `WebSocket::close`, which enqueues a `Close` through the same gate. */
-	close(code, reason) {
-		this.#enqueue(() => {
-			this.#socket.close(code, reason);
-		});
-	}
-	#enqueue(write) {
-		const outputLock = this.#ctx.waitForOutputLocks();
-		this.#pump = this.#pump.then(async () => {
-			await outputLock;
-			write();
-		});
-		this.#ctx.addWaitUntil(this.#pump);
-	}
-};
-/**
-* ← `accept()` / `state.acceptWebSocket()`, as the one verb.
-*
-* Named for what upstream names it, because the critical-section capture is a
-* property of accepting rather than of constructing: "a socket accepted inside a
-* `blockConcurrencyWhile` delivers its messages inside that critical section"
-* (§1.8).
-*/
-function acceptWebSocket(ctx, socket) {
-	if (accepted.has(socket)) throw new Error(ALREADY_ACCEPTED_MESSAGE);
-	accepted.add(socket);
-	return new AcceptedWebSocket(ctx, socket);
-}
-/**
-* An `Event` may be dispatched by exactly one target at a time, so the raw
-* socket's event object cannot be re-dispatched: `dispatchEvent` on an event
-* that is already dispatched throws `InvalidStateError`, and one that has
-* finished carries the raw socket as its `target`. Rebuilding it is what makes
-* `event.target` the accepted socket, which is what a listener expects.
-*/
-function cloneEventFor(type, event) {
-	if (type === "message") {
-		const source = event;
-		return new MessageEvent("message", {
-			data: source.data,
-			origin: source.origin,
-			lastEventId: source.lastEventId
-		});
-	}
-	if (type === "close") {
-		const source = event;
-		return new CloseEvent("close", {
-			code: source.code,
-			reason: source.reason,
-			wasClean: source.wasClean
-		});
-	}
-	return new Event(type);
-}
 /**
 * ← the message every unimplemented `ActorCacheInterface` PITR method throws.
 * `ActorSqlite` overrides two of the four; the other two keep this.
@@ -5608,14 +5978,16 @@ var ActorTree = class {
 * which is the whole mechanism behind §1.10's parent↔child re-entrancy.
 */
 var ActorImpl = class {
-	#inputGate = new InputGate();
-	#outputGate = new OutputGate();
+	#inputGate;
+	#outputGate;
 	#isFacet;
 	/** Assigned after construction; `storage` is a WXT auto-import in extension bundles. */
 	actorStorage;
 	classInstance = { kind: "before-ctor" };
-	constructor(isFacet) {
+	constructor(isFacet, hooks = {}) {
 		this.#isFacet = isFacet;
+		this.#inputGate = new InputGate(hooks.input);
+		this.#outputGate = new OutputGate(hooks.output);
 	}
 	getInputGate() {
 		return this.#inputGate;
@@ -5925,6 +6297,7 @@ var ActorContainerImpl = class {
 	#facets;
 	#tree;
 	#env;
+	#webSockets;
 	state;
 	facetTree;
 	globals;
@@ -5932,16 +6305,22 @@ var ActorContainerImpl = class {
 	#alarmTail = Promise.resolve();
 	constructor(options, db, tree, facetTree) {
 		const facet = options.facet;
-		this.#actor = new ActorImpl(facet !== void 0);
+		this.#actor = new ActorImpl(facet !== void 0, options.gateHooks);
 		this.#ctx = new IoContext(this.#actor, options.ports.timer);
 		this.#env = options.env;
 		this.#tree = tree;
 		this.#cache = new ActorSqlite(db, this.#actor.getOutputGate(), async () => {}, facet === void 0 ? options.ports.alarms : DEFAULT_ALARM_OUTLET);
 		this.#actor.actorStorage = this.#cache;
 		this.#durableStorage = new DurableObjectStorage(this.#ctx, this.#cache);
+		this.#webSockets = new HibernatableWebSocketRegistry(this.#ctx, {
+			message: (socket, message) => this.#runWebSocketHandler("webSocketMessage", socket, message),
+			close: (socket, code, reason, wasClean) => this.#runWebSocketHandler("webSocketClose", socket, code, reason, wasClean),
+			error: (socket, error) => this.#runWebSocketHandler("webSocketError", socket, error)
+		}, options.ports.hibernation, options.webSockets);
 		this.globals = new ActorGlobalScope(this.#ctx, {
 			fetch: options.ports.fetch,
-			currentExternalEntry: () => this.#currentExternalEntry
+			currentExternalEntry: () => this.#currentExternalEntry,
+			webSockets: this.#webSockets
 		});
 		this.facetTree = facetTree;
 		this.#facets = new FacetManagerImpl(this, options.ports.facets, facet?.id ?? 0, facet?.depth ?? 0, this.facetTree);
@@ -5955,7 +6334,8 @@ var ActorContainerImpl = class {
 			props: void 0,
 			storage: this.#durableStorage,
 			facets: this.#facets,
-			globals: actorScopeBindings(() => this.globals)
+			globals: actorScopeBindings(() => this.globals),
+			webSockets: this.#webSockets
 		});
 	}
 	get onBroken() {
@@ -6089,6 +6469,14 @@ var ActorContainerImpl = class {
 	drainWaitUntil() {
 		return this.#ctx.drainWaitUntil();
 	}
+	quiescence() {
+		return {
+			armedTimers: this.#ctx.getTimeoutCount(),
+			pendingWaitUntil: this.#ctx.waitUntilTaskCount(),
+			inputLockHeld: this.#ctx.hasCurrent(),
+			outputGateBroken: this.#ctx.isOutputGateBroken()
+		};
+	}
 	/** ← `WorkerdApi::compileGlobals`'s `Global::WorkerLoader` arm. */
 	workerLoader(channel, options) {
 		return new WorkerLoader(this.#ctx, channel, options);
@@ -6182,6 +6570,13 @@ var ActorContainerImpl = class {
 		if (!hasAlarmHandler(instance.instance)) throw new TypeError("Your Durable Object class must have an alarm() handler.");
 		return instance.instance.alarm(new AlarmInvocationInfo(scheduledTime, retryCount));
 	}
+	#runWebSocketHandler(name, socket, ...args) {
+		const instance = this.#actor.classInstance;
+		if (instance.kind !== "running") return void 0;
+		const handler = Reflect.get(instance.instance, name);
+		if (typeof handler !== "function") return void 0;
+		return Reflect.apply(handler, instance.instance, [socket, ...args]);
+	}
 };
 /**
 * Builds one actor: the two gates, the `IoContext` over them, the storage engine
@@ -6252,6 +6647,6 @@ function newRpcSession(port, localMain) {
 	return newMessagePortRpcSession(port, localMain);
 }
 //#endregion
-export { ACTOR_CLASS_SERIALIZATION_UNIMPLEMENTED_MESSAGE, ALARM_RETRY_MAX_TRIES, ALARM_RETRY_START_SECONDS, ALLOW_EXPERIMENTAL_MESSAGE, ALREADY_ACCEPTED_MESSAGE, AlarmInvocationInfo, AlarmScheduler, BYOB_READER_UNGATABLE_MESSAGE, BrokenActorError, CanceledError, DEAD_LOAD_CONTEXT_MESSAGE, DEFAULT_ALARM_OUTLET, FACET_ALARM_UNIMPLEMENTED_MESSAGE, FACET_NAME_MAX_LENGTH, FACET_TREE_MAX_DEPTH, FOREIGN_SLICE_MESSAGE, HIBERNATION_UNIMPLEMENTED_MESSAGE, LoopbackDurableObjectClass, NOT_BYTES_MESSAGE, NO_GLOBAL_OUTBOUND_MESSAGE, NO_MODULES_MESSAGE, PITR_UNIMPLEMENTED_MESSAGE, REPLICATION_UNIMPLEMENTED_MESSAGE, RETRY_BACKOFF_MAX, RETRY_JITTER_FACTOR, STREAMING_TAILS_EXPERIMENTAL_MESSAGE, WorkerLoader, WorkerStub, actorScopeBindings, alarmRetryDelayMs, asLoopbackDurableObjectClass, createActorContainer, createDurableObjectNamespace, gateRequestBody, installActorScope, jsModuleInPythonWorkerMessage, moduleFieldCountMessage, moduleNameMessage, newRpcSession, noFacets, notSerializableMessage, pythonModuleInJsWorkerMessage, typeScriptModuleNameMessage };
+export { ACTOR_CLASS_SERIALIZATION_UNIMPLEMENTED_MESSAGE, ALARM_RETRY_MAX_TRIES, ALARM_RETRY_START_SECONDS, ALLOW_EXPERIMENTAL_MESSAGE, ALREADY_ACCEPTED_MESSAGE, AlarmInvocationInfo, AlarmScheduler, BYOB_READER_UNGATABLE_MESSAGE, BrokenActorError, CanceledError, DEAD_LOAD_CONTEXT_MESSAGE, DEFAULT_ALARM_OUTLET, FACET_ALARM_UNIMPLEMENTED_MESSAGE, FACET_NAME_MAX_LENGTH, FACET_TREE_MAX_DEPTH, FOREIGN_SLICE_MESSAGE, LoopbackDurableObjectClass, NOT_BYTES_MESSAGE, NO_GLOBAL_OUTBOUND_MESSAGE, NO_MODULES_MESSAGE, PITR_UNIMPLEMENTED_MESSAGE, REPLICATION_UNIMPLEMENTED_MESSAGE, RETRY_BACKOFF_MAX, RETRY_JITTER_FACTOR, STREAMING_TAILS_EXPERIMENTAL_MESSAGE, RuntimeWebSocketRequestResponsePair as WebSocketRequestResponsePair, WorkerLoader, WorkerStub, actorScopeBindings, alarmRetryDelayMs, asLoopbackDurableObjectClass, createActorContainer, createDurableObjectNamespace, gateRequestBody, installActorScope, installWebSocketGlobals, jsModuleInPythonWorkerMessage, markWebSocketUsed, moduleFieldCountMessage, moduleNameMessage, newRpcSession, noFacets, notSerializableMessage, pythonModuleInJsWorkerMessage, typeScriptModuleNameMessage };
 
 //# sourceMappingURL=index.js.map