@restatedev/restate-sdk-tunnel 0.0.0-dev → 1.15.0-rc.4

package/dist/index.js

@@ -0,0 +1,927 @@
+import { createEndpointHandler } from "@restatedev/restate-sdk";
+import * as fs from "node:fs";
+import * as dns from "node:dns";
+import * as net from "node:net";
+import * as tls from "node:tls";
+import * as http2 from "node:http2";
+
+//#region src/targets.ts
+/**
+* Parse one explicit tunnel-server address: `"host:port"`, or a URL whose
+* scheme picks TLS (`https`) / plaintext (`http`) for that server.
+* Throws on a malformed address.
+*/
+function parseServerAddress(address) {
+	if (address.includes("://")) {
+		let url;
+		try {
+			url = new URL(address);
+		} catch {
+			throw new Error(`tunnel: invalid tunnel server URL ${JSON.stringify(address)}`);
+		}
+		if (url.protocol !== "http:" && url.protocol !== "https:") throw new Error(`tunnel: unsupported tunnel server scheme ${JSON.stringify(url.protocol)} (use http or https)`);
+		if (url.pathname !== "/" || url.search !== "") throw new Error(`tunnel: tunnel server URL must not have a path or query: ${JSON.stringify(address)}`);
+		const port$1 = url.port !== "" ? Number(url.port) : url.protocol === "https:" ? 443 : 80;
+		return {
+			host: url.hostname,
+			port: port$1,
+			servername: url.hostname,
+			plaintext: url.protocol === "http:"
+		};
+	}
+	const idx = address.lastIndexOf(":");
+	if (idx <= 0 || idx === address.length - 1) throw new Error(`tunnel: invalid tunnel server address ${JSON.stringify(address)} (expected "host:port" or a URL)`);
+	const host = address.slice(0, idx);
+	const port = Number(address.slice(idx + 1));
+	if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error(`tunnel: invalid port in tunnel server address ${JSON.stringify(address)}`);
+	return {
+		host,
+		port,
+		servername: host
+	};
+}
+/**
+* Resolve the current set of tunnel servers. Called fresh per connection
+* attempt, so DNS changes are picked up across redials.
+*
+* - Explicit `tunnelServers`: parsed as-is (no DNS here — the dial resolves
+*   the hostname).
+* - `srvName` (region-derived or given directly): a DNS SRV lookup, each
+*   record expanded to ALL of its addresses (priority asc, weight desc).
+*
+* Error taxonomy (mirrors the Rust resolver): a NEGATIVE answer for an SRV
+* target (the name genuinely has no address — ENOTFOUND/ENODATA) removes
+* that target, and an all-negative answer yields an EMPTY list (the
+* supervisor then reconciles everything away, like Rust's empty set). A
+* TRANSPORT error (EAI_AGAIN, timeouts, SERVFAIL) THROWS instead — the
+* supervisor must keep the existing connections serving and retry, not
+* tear down healthy slots over a resolver blip.
+*/
+async function resolveTargets(spec) {
+	if (spec.tunnelServers !== void 0) {
+		const targets$1 = spec.tunnelServers.map(parseServerAddress);
+		if (targets$1.length === 0) throw new Error("tunnel: tunnelServers is empty");
+		return targets$1;
+	}
+	const srvName = spec.srvName;
+	const records = await dns.promises.resolveSrv(srvName);
+	records.sort((a, b) => a.priority - b.priority || b.weight - a.weight);
+	const lookups = await Promise.allSettled(records.map((r) => dns.promises.lookup(r.name, { all: true })));
+	const targets = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (let i = 0; i < records.length; i++) {
+		const r = records[i];
+		const result = lookups[i];
+		if (result.status === "rejected") {
+			const code = result.reason?.code;
+			if (code === "ENOTFOUND" || code === "ENODATA") continue;
+			throw result.reason;
+		}
+		for (const a of result.value) {
+			const key = `${a.address}:${r.port}`;
+			if (seen.has(key)) continue;
+			seen.add(key);
+			targets.push({
+				host: a.address,
+				port: r.port,
+				servername: srvName
+			});
+		}
+	}
+	return targets;
+}
+/** Stable identity of a target — the unit of one tunnel connection. */
+function targetKey(t) {
+	return `${t.host}:${t.port}`;
+}
+
+//#endregion
+//#region src/options.ts
+const TUNNEL_NAME_ENV = "RESTATE_INPROC_TUNNEL_NAME";
+const ENVIRONMENT_ID_ENV = "RESTATE_INPROC_ENVIRONMENT_ID";
+const CLOUD_REGION_ENV = "RESTATE_INPROC_CLOUD_REGION";
+const SIGNING_PUBLIC_KEY_ENV = "RESTATE_INPROC_SIGNING_PUBLIC_KEY";
+const AUTH_TOKEN_FILE_ENV = "RESTATE_INPROC_AUTH_TOKEN_FILE";
+/** An env var set to the empty string is treated as unset. */
+function fromEnv(name) {
+	const value = process.env[name];
+	return value === void 0 || value === "" ? void 0 : value;
+}
+/** Resolve option > environment > throw. */
+function requireConfigured(value, name, envName) {
+	const resolved = value !== void 0 && value !== "" ? value : fromEnv(envName);
+	if (resolved === void 0) throw new Error(`tunnel: ${name} is required (pass the option or set ${envName})`);
+	return resolved;
+}
+/**
+* Both credentials travel as HTTP header values in the handshake. Node
+* silently strips header-illegal characters, which would surface as a
+* baffling `unauthorized` from the server — reject them loudly instead.
+*/
+function requireHeaderSafe(value, what) {
+	if (!/^[\x21-\x7e]+$/.test(value)) throw new Error(`tunnel: ${what} contains characters that cannot travel in an HTTP header (whitespace or non-printable)`);
+	return value;
+}
+function resolveAuthToken(option) {
+	if (option !== void 0 && option !== "") {
+		requireHeaderSafe(option, "authToken");
+		return () => option;
+	}
+	const tokenFile = fromEnv(AUTH_TOKEN_FILE_ENV);
+	if (tokenFile === void 0) throw new Error(`tunnel: authToken is required (pass the option or set ${AUTH_TOKEN_FILE_ENV})`);
+	const readToken = () => {
+		const stat = fs.statSync(tokenFile);
+		if (!stat.isFile()) throw new Error(`tunnel: auth token file ${tokenFile} is not a regular file`);
+		if (stat.size > 64 * 1024) throw new Error(`tunnel: auth token file ${tokenFile} is implausibly large for a token (${stat.size} bytes)`);
+		const token = fs.readFileSync(tokenFile, "utf8").trim();
+		if (token === "") throw new Error(`tunnel: auth token file ${tokenFile} is empty`);
+		return requireHeaderSafe(token, `auth token file ${tokenFile}`);
+	};
+	readToken();
+	return readToken;
+}
+function positive(value, fallback, name) {
+	if (value === void 0) return fallback;
+	if (!Number.isFinite(value) || value <= 0) throw new Error(`tunnel: ${name} must be a positive number`);
+	return value;
+}
+/**
+* Validate user options and apply defaults. Throws on misconfiguration.
+* Each identity/discovery option falls back to its RESTATE_INPROC_* env var
+* (option > environment > throw), so a pod the restate-operator configured
+* for `tunnelMode: in-process` needs no explicit configuration beyond the
+* auth token.
+*/
+function resolveOptions(options) {
+	const hasSrv = options.tunnelServersSrv !== void 0 && options.tunnelServersSrv !== "";
+	const hasServers = options.tunnelServers !== void 0 && options.tunnelServers.length > 0;
+	let region = options.region;
+	if ((region === void 0 || region === "") && !hasSrv && options.tunnelServers === void 0) region = fromEnv(CLOUD_REGION_ENV);
+	const hasRegion = region !== void 0 && region !== "";
+	const discoveryCount = Number(hasRegion) + Number(hasSrv) + Number(hasServers);
+	if (discoveryCount === 0) throw new Error(`tunnel: specify one of \`region\`, \`tunnelServersSrv\` or \`tunnelServers\` (or set ${CLOUD_REGION_ENV})`);
+	if (discoveryCount > 1) throw new Error("tunnel: specify exactly one of `region`, `tunnelServersSrv` or `tunnelServers`");
+	if (hasRegion && !/^[a-z0-9-]+(\.[a-z0-9-]+)*$/.test(region)) throw new Error(`tunnel: invalid region ${JSON.stringify(region)}`);
+	if (hasSrv && !/^[A-Za-z0-9._-]+$/.test(options.tunnelServersSrv)) throw new Error(`tunnel: invalid tunnelServersSrv ${JSON.stringify(options.tunnelServersSrv)}`);
+	if (hasServers) for (const address of options.tunnelServers) parseServerAddress(address);
+	const environmentId = requireConfigured(options.environmentId, "environmentId", ENVIRONMENT_ID_ENV);
+	if (!/^env_[A-Za-z0-9_-]+$/.test(environmentId)) throw new Error("tunnel: environmentId must be `env_` followed by alphanumerics (e.g. env_201k0yd4...)");
+	const authToken = resolveAuthToken(options.authToken);
+	const signingPublicKey = requireConfigured(options.signingPublicKey, "signingPublicKey", SIGNING_PUBLIC_KEY_ENV);
+	if (!signingPublicKey.startsWith("publickeyv1_")) throw new Error("tunnel: signingPublicKey must be a request-identity public key (publickeyv1_...)");
+	const tunnelName = requireConfigured(options.tunnelName, "tunnelName", TUNNEL_NAME_ENV);
+	if (!/^[A-Za-z0-9._-]+$/.test(tunnelName)) throw new Error(`tunnel: invalid tunnelName ${JSON.stringify(tunnelName)} — use letters, digits, '.', '_' or '-'`);
+	const pingIntervalMs = positive(options.pingIntervalMs, 75e3, "pingIntervalMs");
+	const pingTimeoutMs = positive(options.pingTimeoutMs, 1e4, "pingTimeoutMs");
+	return {
+		srvName: hasRegion ? srvNameForRegion(region) : hasSrv ? options.tunnelServersSrv : void 0,
+		tunnelServers: hasServers ? options.tunnelServers : void 0,
+		environmentId,
+		authToken,
+		signingPublicKey,
+		tunnelName,
+		bidirectional: options.bidirectional ?? true,
+		resolveIntervalMs: positive(options.resolveIntervalMs, 3e4, "resolveIntervalMs"),
+		supportsDrain: options.supportsDrain ?? true,
+		drainGraceMs: positive(options.drainGraceMs, 12e4, "drainGraceMs"),
+		connectTimeoutMs: positive(options.connectTimeoutMs, 5e3, "connectTimeoutMs"),
+		handshakeTimeoutMs: positive(options.handshakeTimeoutMs, 5e3, "handshakeTimeoutMs"),
+		reconnectInitialMs: positive(options.reconnectInitialMs, 10, "reconnectInitialMs"),
+		reconnectMaxMs: positive(options.reconnectMaxMs, 12e4, "reconnectMaxMs"),
+		reconnectFactor: positive(options.reconnectFactor, 2, "reconnectFactor"),
+		pingIntervalMs,
+		pingTimeoutMs,
+		pingMaxMissed: positive(options.pingMaxMissed, 2, "pingMaxMissed"),
+		maxConcurrentStreams: positive(options.maxConcurrentStreams, 4096, "maxConcurrentStreams"),
+		connectionWindowSize: positive(options.connectionWindowSize, 16 * 1024 * 1024, "connectionWindowSize"),
+		maxSessionMemory: positive(options.maxSessionMemory, 256, "maxSessionMemory"),
+		tls: options.tls ?? true,
+		logger: options.logger ?? (() => {})
+	};
+}
+/**
+* Build the `tls.connect` options for a tunnel target, or `undefined` for a
+* plaintext connection.
+*
+* Always offers ALPN `["h2"]` — the same offer every Rust tunnel client
+* makes — and the connection layer requires the negotiation to succeed:
+* Node's http2 will only run a server session over a TLS socket whose ALPN
+* negotiated `h2`. Tunnel servers advertise it since the standard-h2
+* control-traffic change; older servers (which cleared their ALPN list)
+* cannot serve this client.
+*/
+function buildTlsConnectOptions(tlsOption, servername) {
+	if (tlsOption === false) return void 0;
+	const base = {
+		servername,
+		ALPNProtocols: ["h2"]
+	};
+	if (tlsOption === true) return base;
+	return {
+		...base,
+		...tlsOption.servername !== void 0 && { servername: tlsOption.servername },
+		...tlsOption.ca !== void 0 && { ca: tlsOption.ca },
+		...tlsOption.cert !== void 0 && { cert: tlsOption.cert },
+		...tlsOption.key !== void 0 && { key: tlsOption.key },
+		...tlsOption.rejectUnauthorized !== void 0 && { rejectUnauthorized: tlsOption.rejectUnauthorized }
+	};
+}
+/** The DNS SRV name for region-based tunnel-server discovery. */
+function srvNameForRegion(region) {
+	return `tunnel.${region}.restate.cloud`;
+}
+
+//#endregion
+//#region src/handshake.ts
+const START_TUNNEL_PATH = "/_/start-tunnel";
+/** Handshake deadline — mirrors the tunnel server's own 5s timeout. */
+const HANDSHAKE_TIMEOUT_MS = 5e3;
+/**
+* Run the receiver side of the /_/start-tunnel exchange on its stream.
+* Resolves with an outcome; never rejects.
+*/
+function performHandshake(req, res, creds, timeoutMs = HANDSHAKE_TIMEOUT_MS) {
+	return new Promise((resolve) => {
+		let settled = false;
+		const finish = (outcome) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(deadline);
+			resolve(outcome);
+		};
+		const deadline = setTimeout(() => {
+			finish({
+				kind: "retryable",
+				reason: `handshake trailers not received within ${timeoutMs}ms`
+			});
+			req.stream.destroy();
+		}, timeoutMs);
+		deadline.unref();
+		const onTrailers = (trailers) => {
+			const status = trailers["tunnel-status"];
+			if (status !== "ok") {
+				if (status === "unauthorized" || status === "bad-tunnel-name") finish({
+					kind: "fatal",
+					reason: `tunnel-status: ${String(status)}`
+				});
+				else finish({
+					kind: "retryable",
+					reason: `tunnel-status: ${String(status ?? "<missing>")}`
+				});
+				return;
+			}
+			const tunnelName = trailers["tunnel-name"];
+			const proxyUrl = trailers["proxy-url"];
+			const tunnelUrl = trailers["tunnel-url"];
+			if (typeof tunnelName !== "string" || typeof proxyUrl !== "string" || typeof tunnelUrl !== "string") {
+				finish({
+					kind: "retryable",
+					reason: "handshake ok but proxy-url/tunnel-url/tunnel-name missing"
+				});
+				return;
+			}
+			if (tunnelName !== creds.tunnelName) {
+				finish({
+					kind: "fatal",
+					reason: `tunnel-name mismatch: requested ${JSON.stringify(creds.tunnelName)}, got ${JSON.stringify(tunnelName)}`
+				});
+				return;
+			}
+			finish({
+				kind: "ok",
+				info: {
+					tunnelName,
+					proxyUrl,
+					tunnelUrl
+				}
+			});
+		};
+		req.stream.on("trailers", onTrailers);
+		req.on("end", () => {
+			if (!settled && req.trailers && Object.keys(req.trailers).length > 0) onTrailers(req.trailers);
+		});
+		req.on("error", (err) => {
+			finish({
+				kind: "retryable",
+				reason: `handshake stream error: ${err.message}`
+			});
+		});
+		req.stream.on("close", () => {
+			finish({
+				kind: "retryable",
+				reason: "handshake stream closed before trailers"
+			});
+		});
+		req.resume();
+		res.writeHead(200, {
+			authorization: `Bearer ${creds.authToken}`,
+			"environment-id": creds.environmentId,
+			"tunnel-name": creds.tunnelName,
+			...creds.supportsDrain && { "supports-drain": "true" }
+		});
+		res.end();
+	});
+}
+
+//#endregion
+//#region src/forwarded.ts
+/**
+* Strip the tunnel's forwarded prefix `/<scheme>/<host>/<port>` and return
+* the tail — the path the SDK should see.
+*
+* A forwarded invocation arrives down the tunnel with its destination
+* encoded in the path (`/http/my-service.ns.svc.cluster.local/9080/invoke/...`);
+* the cloud proxy has already stripped the `/<env>/<tunnel>` rendezvous
+* prefix. For an in-process SDK deployment the scheme/host/port are
+* vestigial (the receiver *is* the service), so we drop exactly those three
+* segments and keep the tail (`/discover`, `/invoke/<svc>/<handler>`, …).
+*
+* The tail is passed through without re-encoding: the SDK verifies each
+* request's identity JWT against the signed service-relative path (its
+* routing and verification tolerate extra path *prefixes*, but re-encoding,
+* normalization or case folding of the tail itself would break the match).
+* The query string is preserved (it is not part of `aud`).
+*
+* Returns `null` if the path isn't a forwarded `/<scheme>/<host>/<port>/...`
+* path.
+*/
+function forwardedTail(rawUrl) {
+	const qIdx = rawUrl.indexOf("?");
+	const path = qIdx === -1 ? rawUrl : rawUrl.slice(0, qIdx);
+	const query = qIdx === -1 ? "" : rawUrl.slice(qIdx);
+	const seg = path.split("/");
+	if (seg.length < 4 || seg[1] === "" || seg[2] === "" || !/^\d+$/.test(seg[3])) return null;
+	const tail = "/" + seg.slice(4).join("/");
+	return query ? tail + query : tail;
+}
+
+//#endregion
+//#region src/connection.ts
+/**
+* Run one connection attempt. Resolves (never rejects) with the outcome
+* when the connection ends; `slotSignal` aborts the attempt at any phase.
+*/
+function runConnection(target, slotSignal, deps) {
+	let authToken;
+	try {
+		authToken = deps.opts.authToken();
+	} catch (err) {
+		return Promise.resolve({
+			kind: "retryable",
+			reason: `auth token unavailable: ${err instanceof Error ? err.message : String(err)}`
+		});
+	}
+	return new ConnectionAttempt(target, slotSignal, deps, authToken).run();
+}
+var ConnectionAttempt = class {
+	settled = false;
+	/** Set when the handshake confirms ok — the connection's serve epoch. */
+	openedAt;
+	serving = false;
+	/** Assigned when /_/start-tunnel arrives; the gate streams park on (C3). */
+	handshakePromise;
+	/** Drain handover requested — settle detaches instead of destroying (C2). */
+	detachForDrain = false;
+	socket;
+	session;
+	connectTimer;
+	firstRequestTimer;
+	watchdog;
+	resolveRun;
+	plaintext;
+	log;
+	constructor(target, slotSignal, deps, authToken) {
+		this.target = target;
+		this.slotSignal = slotSignal;
+		this.deps = deps;
+		this.authToken = authToken;
+		this.log = deps.opts.logger;
+		this.plaintext = target.plaintext ?? deps.opts.tls === false;
+		slotSignal.addEventListener("abort", this.onStop, { once: true });
+		const tlsOptions = this.plaintext ? void 0 : buildTlsConnectOptions(deps.opts.tls, target.servername);
+		this.socket = this.plaintext ? net.connect({
+			host: target.host,
+			port: target.port
+		}) : tls.connect({
+			host: target.host,
+			port: target.port,
+			...tlsOptions
+		});
+		deps.activeSockets.add(this.socket);
+		this.connectTimer = setTimeout(() => {
+			this.settle({
+				kind: "retryable",
+				reason: `connect timeout after ${deps.opts.connectTimeoutMs}ms`
+			});
+		}, deps.opts.connectTimeoutMs);
+		this.connectTimer.unref();
+	}
+	run() {
+		return new Promise((resolve) => {
+			this.resolveRun = resolve;
+			this.socket.on("error", (err) => {
+				this.settle({
+					kind: "retryable",
+					reason: `socket error: ${err.message}`
+				});
+			});
+			this.socket.on("close", () => {
+				this.settle(this.endOutcome("connection closed before handshake completed"));
+			});
+			this.socket.once(this.plaintext ? "connect" : "secureConnect", () => this.onConnected());
+		});
+	}
+	onStop = () => this.settle({
+		kind: "retryable",
+		reason: "tunnel closed"
+	});
+	uptimeMs() {
+		return this.openedAt === void 0 ? 0 : Date.now() - this.openedAt;
+	}
+	/** The end-of-connection outcome: "served" once established, else retryable. */
+	endOutcome(reason) {
+		return this.openedAt !== void 0 ? {
+			kind: "served",
+			uptimeMs: this.uptimeMs()
+		} : {
+			kind: "retryable",
+			reason
+		};
+	}
+	/** C1: the single exit point. C2: drain handover detaches instead. */
+	settle(outcome) {
+		if (this.settled) return;
+		this.settled = true;
+		if (this.watchdog !== void 0) clearInterval(this.watchdog);
+		if (this.firstRequestTimer !== void 0) clearTimeout(this.firstRequestTimer);
+		clearTimeout(this.connectTimer);
+		this.slotSignal.removeEventListener("abort", this.onStop);
+		if (this.detachForDrain && this.session !== void 0 && !this.session.destroyed) this.deps.draining.add(this.session, this.socket, this.deps.opts.drainGraceMs);
+		else {
+			this.session?.destroy();
+			this.socket.destroy();
+		}
+		this.deps.activeSockets.delete(this.socket);
+		this.resolveRun(outcome);
+	}
+	onConnected() {
+		clearTimeout(this.connectTimer);
+		this.socket.setNoDelay(true);
+		this.log(`tunnel: connected to ${this.target.host}:${this.target.port}, starting handshake`);
+		if (!this.plaintext) {
+			if (this.socket.alpnProtocol !== "h2") {
+				this.settle({
+					kind: "retryable",
+					reason: "tunnel server did not negotiate h2 ALPN — it predates standard-h2 control traffic and cannot serve this client"
+				});
+				return;
+			}
+		}
+		const stream = this.socket;
+		const h2 = http2.createServer({
+			maxSessionMemory: this.deps.opts.maxSessionMemory,
+			settings: {
+				maxConcurrentStreams: this.deps.opts.maxConcurrentStreams,
+				initialWindowSize: 1024 * 1024,
+				maxFrameSize: 65536
+			}
+		}, (req, res) => this.handleRequest(req, res));
+		h2.on("session", (s) => {
+			this.session = s;
+			try {
+				s.setLocalWindowSize?.(this.deps.opts.connectionWindowSize);
+			} catch {}
+			s.on("close", () => {
+				this.settle(this.endOutcome("session closed before handshake completed"));
+			});
+			s.on("error", (err) => {
+				this.settle(this.endOutcome(`session error: ${err.message}`));
+			});
+		});
+		h2.on("sessionError", (err) => {
+			this.settle(this.endOutcome(`session error: ${err.message}`));
+		});
+		this.firstRequestTimer = setTimeout(() => {
+			if (this.handshakePromise === void 0) this.settle({
+				kind: "retryable",
+				reason: "server never initiated /_/start-tunnel"
+			});
+		}, this.deps.opts.handshakeTimeoutMs);
+		this.firstRequestTimer.unref();
+		h2.emit("connection", stream);
+	}
+	handleRequest(req, res) {
+		const rawPath = (req.url ?? "").split("?")[0];
+		if (this.handshakePromise === void 0 && req.method === "GET" && rawPath === START_TUNNEL_PATH) {
+			this.startHandshake(req, res);
+			return;
+		}
+		if (rawPath === "/_/health") {
+			res.writeHead(200);
+			res.end();
+			return;
+		}
+		if (rawPath === "/_/drain-tunnel") {
+			this.handleDrainRequest(res);
+			return;
+		}
+		if (this.serving) {
+			this.dispatchForwarded(req, res);
+			return;
+		}
+		if (this.handshakePromise === void 0) {
+			res.writeHead(503);
+			res.end("tunnel: not ready");
+			return;
+		}
+		this.parkOnGate(req, res);
+	}
+	/** First stream: run the handshake; its outcome opens the gate (C3). */
+	startHandshake(req, res) {
+		if (this.firstRequestTimer !== void 0) clearTimeout(this.firstRequestTimer);
+		this.handshakePromise = performHandshake(req, res, {
+			authToken: this.authToken,
+			environmentId: this.deps.opts.environmentId,
+			tunnelName: this.deps.opts.tunnelName,
+			supportsDrain: this.deps.opts.supportsDrain
+		}, this.deps.opts.handshakeTimeoutMs).then((outcome) => {
+			if (this.settled) return { ok: false };
+			if (outcome.kind === "ok") {
+				this.openedAt = Date.now();
+				this.serving = true;
+				this.log(`tunnel: established (name=${outcome.info.tunnelName}, proxy=${outcome.info.proxyUrl})`);
+				this.deps.onEstablished(outcome.info);
+				this.startWatchdog();
+				return { ok: true };
+			}
+			this.settle(outcome);
+			return { ok: false };
+		});
+	}
+	/** Strip the destination prefix and hand the stream to the SDK. */
+	dispatchForwarded(req, res) {
+		const tail = forwardedTail(req.url ?? "");
+		if (tail === null) {
+			res.writeHead(400);
+			res.end("tunnel: malformed forwarded path");
+			return;
+		}
+		req.url = tail;
+		this.deps.sdkHandler(req, res);
+	}
+	/**
+	* C3: a stream that raced the handshake parks on its outcome (bounded by
+	* handshakeTimeoutMs) rather than rejecting work the cloud sent the
+	* moment it registered the tunnel.
+	*/
+	parkOnGate(req, res) {
+		this.handshakePromise.then(({ ok }) => {
+			if (this.settled || res.stream.destroyed) return;
+			try {
+				if (ok) this.dispatchForwarded(req, res);
+				else {
+					res.writeHead(503);
+					res.end("tunnel: not ready");
+				}
+			} catch {}
+		});
+	}
+	handleDrainRequest(res) {
+		res.writeHead(200);
+		res.end();
+		if (!this.deps.opts.supportsDrain) {
+			this.log("tunnel: received /_/drain-tunnel (drain not advertised) — acknowledging");
+			return;
+		}
+		if (this.serving) this.beginDrain();
+		else if (this.handshakePromise !== void 0) this.handshakePromise.then(({ ok }) => {
+			if (ok) this.beginDrain();
+		});
+	}
+	/** Handover: detach (C2) and settle so the slot dials a replacement. */
+	beginDrain() {
+		if (this.settled || this.detachForDrain) return;
+		this.log("tunnel: drain requested — opening a replacement connection");
+		this.detachForDrain = true;
+		this.settle({
+			kind: "drained",
+			uptimeMs: this.uptimeMs()
+		});
+	}
+	/**
+	* Periodic h2 PING; consecutive misses mean the connection is half-open
+	* (the OS may never surface it) — kill and redial. Started once serving.
+	*/
+	startWatchdog() {
+		let missed = 0;
+		this.watchdog = setInterval(() => {
+			const s = this.session;
+			if (s === void 0 || s.destroyed) return;
+			let acked = false;
+			try {
+				s.ping((err) => {
+					if (err === null) {
+						acked = true;
+						missed = 0;
+					}
+				});
+			} catch {
+				return;
+			}
+			setTimeout(() => {
+				if (acked || s.destroyed) return;
+				missed++;
+				if (missed >= this.deps.opts.pingMaxMissed) {
+					this.log(`tunnel: ${missed} consecutive pings missed — reconnecting`);
+					this.settle({
+						kind: "served",
+						uptimeMs: this.uptimeMs()
+					});
+				}
+			}, this.deps.opts.pingTimeoutMs).unref();
+		}, this.deps.opts.pingIntervalMs);
+		this.watchdog.unref();
+	}
+};
+
+//#endregion
+//#region src/draining.ts
+var DrainingRegistry = class {
+	entries = /* @__PURE__ */ new Set();
+	/**
+	* Take ownership of a detached (draining) connection: let it serve its
+	* in-flight streams for up to `graceMs`, then tear it down. The entry
+	* removes itself if the session ends earlier on its own.
+	*/
+	add(session, socket, graceMs) {
+		const entry = {
+			session,
+			socket,
+			timer: setTimeout(() => {
+				this.entries.delete(entry);
+				session.destroy();
+				socket.destroy();
+			}, graceMs)
+		};
+		entry.timer.unref();
+		this.entries.add(entry);
+		session.on("close", () => {
+			clearTimeout(entry.timer);
+			this.entries.delete(entry);
+			socket.destroy();
+		});
+	}
+	/** Tear down every draining connection. Idempotent. */
+	destroyAll() {
+		for (const entry of this.entries) {
+			clearTimeout(entry.timer);
+			entry.session.destroy();
+			entry.socket.destroy();
+		}
+		this.entries.clear();
+	}
+};
+
+//#endregion
+//#region src/backoff.ts
+/**
+* Backoff resets only when a served connection stayed up at least this long
+* (mirrors the Rust client's 5s "opened" guard). Without it, a server that
+* authorizes the handshake but immediately drops the connection would be
+* redialed at the backoff floor forever — a full TLS+h2+auth round trip
+* every ~10ms.
+*/
+const MIN_UPTIME_FOR_BACKOFF_RESET_MS = 5e3;
+/**
+* Jittered exponential backoff: each `next()` returns the current delay
+* with ±50% jitter and advances the schedule toward `maxMs`; `reset()`
+* returns to the floor. Jitter keeps multi-homed slots from redialing in
+* lockstep after a fleet-wide blip (thundering herd).
+*/
+var Backoff = class {
+	currentMs;
+	constructor(initialMs, factor, maxMs) {
+		this.initialMs = initialMs;
+		this.factor = factor;
+		this.maxMs = maxMs;
+		this.currentMs = initialMs;
+	}
+	next() {
+		const d = this.currentMs;
+		this.currentMs = Math.min(this.currentMs * this.factor, this.maxMs);
+		return d * (.5 + Math.random());
+	}
+	reset() {
+		this.currentMs = this.initialMs;
+	}
+};
+
+//#endregion
+//#region src/util.ts
+/** Sleep that wakes early (resolving) when the signal aborts. */
+function delay(ms, signal) {
+	return new Promise((resolve) => {
+		if (signal.aborted) {
+			resolve();
+			return;
+		}
+		const t = setTimeout(() => {
+			signal.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			clearTimeout(t);
+			resolve();
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
+}
+/**
+* Race a promise against a signal: resolves `null` the moment the signal
+* aborts, otherwise passes the promise's result through (rejections
+* propagate). The abort listener is removed when the race settles, so
+* repeated calls against a long-lived signal don't accumulate listeners.
+*/
+async function raceAbortable(promise, signal) {
+	if (signal.aborted) return null;
+	let onAbort;
+	const aborted = new Promise((resolve) => {
+		onAbort = () => resolve(null);
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
+	try {
+		return await Promise.race([promise, aborted]);
+	} finally {
+		signal.removeEventListener("abort", onAbort);
+	}
+}
+
+//#endregion
+//#region src/connect.ts
+/**
+* Connect this deployment to a Restate Cloud tunnel and serve `services`
+* over it. Returns immediately; connection management runs in the
+* background until `close()` (or the `signal`) stops it. See
+* {@link TunnelConnection.ready} to await the first successful handshake.
+*/
+function connectTunnel(options) {
+	const opts = resolveOptions(options);
+	const log = opts.logger;
+	const sdkHandler = createEndpointHandler({
+		services: options.services,
+		bidirectional: opts.bidirectional,
+		identityKeys: [opts.signingPublicKey]
+	});
+	let stopped = false;
+	let fatalError;
+	let connectionCount = 0;
+	let lastInfo;
+	const activeSockets = /* @__PURE__ */ new Set();
+	const draining = new DrainingRegistry();
+	const slots = /* @__PURE__ */ new Map();
+	const stopController = new AbortController();
+	const supervisorWake = new AbortController();
+	stopController.signal.addEventListener("abort", () => supervisorWake.abort(), { once: true });
+	let readyResolve;
+	let readyReject;
+	const ready = new Promise((resolve, reject) => {
+		readyResolve = resolve;
+		readyReject = reject;
+	});
+	ready.catch(() => {});
+	const keepAlive = setInterval(() => {}, 2147483647);
+	const connectionDeps = {
+		opts,
+		sdkHandler,
+		draining,
+		activeSockets,
+		onEstablished: (info) => {
+			connectionCount++;
+			lastInfo = info;
+			readyResolve();
+		}
+	};
+	const stopAllSlots = () => {
+		for (const slot of slots.values()) slot.ctl.abort();
+		supervisorWake.abort();
+	};
+	/** The per-server loop: dial → serve → classify outcome → backoff → redial. */
+	const runSlot = async (target, ctl) => {
+		const backoff = new Backoff(opts.reconnectInitialMs, opts.reconnectFactor, opts.reconnectMaxMs);
+		while (!stopped && !ctl.signal.aborted && fatalError === void 0) {
+			const outcome = await runConnection(target, ctl.signal, connectionDeps);
+			if (stopped || ctl.signal.aborted) break;
+			if (outcome.kind === "fatal") {
+				fatalError = /* @__PURE__ */ new Error(`tunnel: ${outcome.reason}`);
+				log(`tunnel: FATAL — ${outcome.reason}; stopping all connections`);
+				readyReject(fatalError);
+				stopAllSlots();
+				break;
+			}
+			if (outcome.kind === "served" || outcome.kind === "drained") {
+				const heldLongEnough = outcome.uptimeMs >= MIN_UPTIME_FOR_BACKOFF_RESET_MS;
+				if (heldLongEnough) backoff.reset();
+				if (outcome.kind === "drained" && heldLongEnough) {
+					log("tunnel: draining — reconnecting immediately");
+					continue;
+				}
+				log(outcome.kind === "drained" ? "tunnel: drained shortly after connecting — reconnecting with backoff" : "tunnel: connection ended — reconnecting");
+			} else log(`tunnel: ${outcome.reason} — reconnecting`);
+			await delay(backoff.next(), ctl.signal);
+		}
+	};
+	const startSlot = (key, target) => {
+		const ctl = new AbortController();
+		stopController.signal.addEventListener("abort", () => ctl.abort(), {
+			once: true,
+			signal: ctl.signal
+		});
+		const slot = {
+			ctl,
+			done: Promise.resolve()
+		};
+		slot.done = runSlot(target, ctl).finally(() => {
+			if (slots.get(key) === slot) slots.delete(key);
+		});
+		slots.set(key, slot);
+	};
+	const loopDone = (async () => {
+		while (!stopped && fatalError === void 0) {
+			let targets;
+			try {
+				const resolution = resolveTargets(opts);
+				resolution.catch(() => {});
+				const raced = await raceAbortable(resolution, supervisorWake.signal);
+				if (raced === null) break;
+				targets = raced;
+			} catch (err) {
+				log(`tunnel: target resolution failed: ${err instanceof Error ? err.message : String(err)} — retrying`);
+				await delay(Math.min(5e3, opts.resolveIntervalMs), supervisorWake.signal);
+				continue;
+			}
+			if (stopped || fatalError !== void 0) break;
+			const desired = new Map(targets.map((t) => [targetKey(t), t]));
+			for (const [key, target] of desired) if (!slots.has(key)) {
+				log(`tunnel: starting connection to ${key}`);
+				startSlot(key, target);
+			}
+			for (const [key, slot] of slots) if (!desired.has(key)) {
+				log(`tunnel: ${key} no longer resolves — tearing down`);
+				slot.ctl.abort();
+			}
+			if (opts.srvName === void 0) break;
+			await delay(opts.resolveIntervalMs, supervisorWake.signal);
+		}
+		await Promise.all([...slots.values()].map((s) => s.done));
+		draining.destroyAll();
+		clearInterval(keepAlive);
+		readyReject(fatalError ?? /* @__PURE__ */ new Error("tunnel: closed before the first handshake"));
+	})();
+	const close = async () => {
+		if (!stopped) {
+			stopped = true;
+			stopController.abort();
+			stopAllSlots();
+			for (const socket of activeSockets) socket.destroy();
+			activeSockets.clear();
+			draining.destroyAll();
+			clearInterval(keepAlive);
+		}
+		await loopDone;
+	};
+	if (options.signal?.aborted) close();
+	else options.signal?.addEventListener("abort", () => void close(), { once: true });
+	return {
+		close,
+		get connectionCount() {
+			return connectionCount;
+		},
+		get tunnelName() {
+			return lastInfo?.tunnelName;
+		},
+		get proxyUrl() {
+			return lastInfo?.proxyUrl;
+		},
+		get tunnelUrl() {
+			return lastInfo?.tunnelUrl;
+		},
+		get deploymentUrl() {
+			if (lastInfo === void 0) return void 0;
+			try {
+				const proxy = new URL(lastInfo.proxyUrl);
+				if (proxy.port === "") proxy.port = "9080";
+				return `${proxy.toString().replace(/\/$/, "")}/http/in-process/9080/`;
+			} catch {
+				return `${lastInfo.proxyUrl}/http/in-process/9080/`;
+			}
+		},
+		get error() {
+			return fatalError;
+		},
+		ready
+	};
+}
+
+//#endregion
+export { connectTunnel };
+//# sourceMappingURL=index.js.map