@runlane/realtime 0.0.0-stage → 0.5.1

package/dist/index.cjs

@@ -0,0 +1,686 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_wire = require("./wire-xCr4QuVn.cjs");
+let _runlane_contracts_realtime = require("@runlane/contracts/realtime");
+let _runlane_utilities_browser = require("@runlane/utilities/browser");
+let eventsource_encoder = require("eventsource-encoder");
+let zod = require("zod");
+zod = require_wire.__toESM(zod, 1);
+let jose = require("jose");
+// src/access.ts
+function intersectGrants(app, token) {
+	if (token === void 0) return app;
+	const permissions = app.permissions.filter((permission) => token.permissions.includes(permission));
+	let streams = app.streams ?? token.streams;
+	if (app.streams !== void 0 && token.streams !== void 0) streams = app.streams.filter((name) => token.streams?.includes(name));
+	return {
+		permissions,
+		...streams === void 0 ? {} : { streams }
+	};
+}
+function permitsStream(grant, name) {
+	return grant.permissions.includes(_runlane_contracts_realtime.RunReadPermission.Streams) && (grant.streams === void 0 || grant.streams.includes(name));
+}
+function projectEvent(event, grant) {
+	if (event.type === _runlane_contracts_realtime.RunSubscriptionEventType.Stream) return permitsStream(grant, event.record.name) ? event : void 0;
+	if (event.type === _runlane_contracts_realtime.RunSubscriptionEventType.Meta) return grant.permissions.includes(_runlane_contracts_realtime.RunReadPermission.Meta) ? event : void 0;
+	if (!grant.permissions.includes(_runlane_contracts_realtime.RunReadPermission.Status)) return void 0;
+	if (event.type === _runlane_contracts_realtime.RunSubscriptionEventType.Status) {
+		const status = { ...event };
+		if (!grant.permissions.includes(_runlane_contracts_realtime.RunReadPermission.Output)) {
+			delete status.output;
+			delete status.failure;
+		}
+		if (status.failure !== void 0) status.failure = _runlane_contracts_realtime.runRealtimeSnapshotSchema.shape.failure.parse(status.failure);
+		return status;
+	}
+	return {
+		...event,
+		run: projectSnapshot(event.run, grant)
+	};
+}
+function projectSnapshot(source, grant) {
+	const { meta, output, failure, ...status } = _runlane_contracts_realtime.runRealtimeSnapshotSchema.parse(source);
+	return {
+		...status,
+		...grant.permissions.includes(_runlane_contracts_realtime.RunReadPermission.Meta) && meta !== void 0 ? { meta } : {},
+		...grant.permissions.includes(_runlane_contracts_realtime.RunReadPermission.Output) ? {
+			...output === void 0 ? {} : { output },
+			...failure === void 0 ? {} : { failure }
+		} : {}
+	};
+}
+// src/tokens.ts
+const tokenPartsSchema = zod.z.tuple([
+	zod.z.string(),
+	zod.z.string(),
+	zod.z.string()
+]);
+const headerSchema = zod.z.strictObject({
+	alg: zod.z.literal("HS256"),
+	typ: zod.z.literal("JWT"),
+	kid: zod.z.string().min(1).max(128)
+});
+const algorithmSchema = zod.z.object({
+	name: zod.z.literal("HMAC"),
+	hash: zod.z.object({ name: zod.z.literal("SHA-256") }),
+	length: zod.z.number().int().min(256)
+});
+const encoder$1 = new TextEncoder();
+const decoder = new TextDecoder("utf-8", { fatal: true });
+const maximumTokenLength = 16384;
+/** Strict construction schema; claim and header constraints remain the canonical owners. */
+const realtimeTokenOptionsSchema = zod.z.strictObject({
+	audience: _runlane_contracts_realtime.verifiedRunTokenSchema.shape.audience,
+	keyId: headerSchema.shape.kid,
+	key: zod.z.instanceof(CryptoKey),
+	verifyKeys: zod.z.record(headerSchema.shape.kid, zod.z.instanceof(CryptoKey)).readonly().optional()
+}).refine((tokens) => !Object.hasOwn(tokens.verifyKeys ?? {}, tokens.keyId), "tokens.keyId must not also appear in verifyKeys.");
+const createTokenOptionsSchema = zod.z.strictObject({
+	runId: zod.z.string(),
+	grant: _runlane_contracts_realtime.runAccessGrantSchema.optional(),
+	expiresIn: (0, _runlane_contracts_realtime.createDurationSchema)("expiresIn must be whole seconds between 1s and realtime.maxTokenTTL.").optional()
+});
+/** Signs one run/environment/audience grant using an HMAC-SHA256 key of at least 256 bits. */
+async function signRunToken(environment, tokens, input) {
+	try {
+		const options = createTokenOptionsSchema.parse(input);
+		const header = headerSchema.parse({
+			alg: "HS256",
+			typ: "JWT",
+			kid: tokens.keyId
+		});
+		requireHmacKey(tokens.key, "sign");
+		const ttl = tokenLifetime(options.expiresIn?.milliseconds);
+		const issuedAt = Math.floor(require_wire.realtimeClock.now() / 1e3);
+		const claims = _runlane_contracts_realtime.verifiedRunTokenSchema.parse({
+			environment,
+			runId: options.runId,
+			grant: options.grant ?? { permissions: Object.values(_runlane_contracts_realtime.RunReadPermission) },
+			audience: tokens.audience,
+			issuedAt,
+			expiresAt: issuedAt + ttl / 1e3,
+			version: 1
+		});
+		const token = await new jose.CompactSign(encoder$1.encode(JSON.stringify(claims))).setProtectedHeader(header).sign(tokens.key);
+		if (token.length > maximumTokenLength) throw invalidToken();
+		return token;
+	} catch (cause) {
+		if (cause instanceof _runlane_contracts_realtime.RunlaneError) throw cause;
+		const message = cause instanceof zod.z.ZodError ? `Token ${cause.issues[0]?.path.join(".") ?? "expiresIn"} is invalid: ${cause.issues[0]?.message ?? "Check the token options."}` : "Token signing failed; check key and claims.";
+		const field = cause instanceof zod.z.ZodError ? cause.issues[0]?.path[0] : void 0;
+		let code = _runlane_contracts_realtime.ErrorCode.InternalError;
+		if (cause instanceof zod.z.ZodError) code = field === "environment" || field === "runId" || field === "grant" ? _runlane_contracts_realtime.ErrorCode.ValidationFailed : _runlane_contracts_realtime.ErrorCode.ConfigurationInvalid;
+		throw new _runlane_contracts_realtime.RunlaneError({
+			code,
+			message,
+			retryable: false,
+			cause
+		});
+	}
+}
+function tokenLifetime(ttl = require_wire.realtimeTiming.tokenTTL) {
+	if (ttl < 1e3 || ttl > require_wire.realtimeTiming.maxTokenTTL || ttl % 1e3 !== 0) throw new _runlane_contracts_realtime.RunlaneError({
+		code: _runlane_contracts_realtime.ErrorCode.ConfigurationInvalid,
+		message: "expiresIn must be whole seconds between 1s and realtime.maxTokenTTL.",
+		retryable: false
+	});
+	return ttl;
+}
+/** Verifies a scoped token and records only bounded rejection reasons through the supplied telemetry. */
+async function verifyRunToken(token, options, diagnostics = {}, operation = "verify") {
+	let reason = "malformed";
+	try {
+		if (token.length > maximumTokenLength) throw invalidToken();
+		const [head, body, signature] = tokenPartsSchema.parse(token.split("."));
+		reason = "header";
+		const header = headerSchema.parse(JSON.parse(decoder.decode(decodeBase64(head))));
+		reason = "unknown_key";
+		const key = Object.hasOwn(options.keys, header.kid) ? options.keys[header.kid] : void 0;
+		if (key === void 0) throw invalidToken();
+		reason = "key";
+		requireHmacKey(key, "verify");
+		reason = "signature";
+		decodeBase64(signature);
+		const verified = await (0, jose.compactVerify)(token, key, { algorithms: ["HS256"] });
+		reason = "claims";
+		decodeBase64(body);
+		const claims = _runlane_contracts_realtime.verifiedRunTokenSchema.parse(JSON.parse(decoder.decode(verified.payload)));
+		const now = Math.floor(require_wire.realtimeClock.now() / 1e3);
+		const rejection = tokenClaimRejection(claims, options.audience, now);
+		if (rejection !== void 0) {
+			reason = rejection;
+			throw invalidToken();
+		}
+		return claims;
+	} catch (cause) {
+		(0, _runlane_contracts_realtime.recordRunlaneTelemetryMetric)(diagnostics, {
+			name: _runlane_contracts_realtime.RunlaneMetricName.RealtimeTokenRejectedCount,
+			value: 1,
+			attributes: {
+				[_runlane_contracts_realtime.RunlaneMetricAttribute.Operation]: operation,
+				[_runlane_contracts_realtime.RunlaneMetricAttribute.Reason]: reason
+			}
+		});
+		(0, _runlane_contracts_realtime.recordRunlaneTelemetryLog)(diagnostics, {
+			type: _runlane_contracts_realtime.RunlaneLogEventType.RealtimeTokenRejected,
+			level: _runlane_contracts_realtime.RunlaneLogLevel.Warn,
+			attributes: {
+				[_runlane_contracts_realtime.RunlaneLogAttribute.Operation]: operation,
+				[_runlane_contracts_realtime.RunlaneLogAttribute.Reason]: reason
+			}
+		});
+		throw invalidToken(cause);
+	}
+}
+function tokenClaimRejection(claims, audience, now) {
+	if (claims.audience !== audience) return "audience";
+	if (claims.issuedAt > now + require_wire.realtimeTiming.issuedAtLeeway / 1e3) return "issued_at";
+	if (claims.expiresAt <= now) return "expired";
+	if (claims.expiresAt <= claims.issuedAt || (claims.expiresAt - claims.issuedAt) * 1e3 > require_wire.realtimeTiming.maxTokenTTL) return "lifetime";
+}
+/** Shared key policy for signing, verification, and handler startup checks. */
+function requireHmacKey(key, usage) {
+	if (!(key instanceof CryptoKey) || key.type !== "secret" || !algorithmSchema.safeParse(key.algorithm).success || !key.usages.includes(usage)) throw new _runlane_contracts_realtime.RunlaneError({
+		code: _runlane_contracts_realtime.ErrorCode.ConfigurationInvalid,
+		message: `key must be an HMAC-SHA256 key of at least 256 bits with ${usage} usage.`,
+		retryable: false
+	});
+}
+function decodeBase64(value) {
+	if (!/^[A-Za-z0-9_-]+$/.test(value)) throw invalidToken();
+	const bytes = jose.base64url.decode(value);
+	if (jose.base64url.encode(bytes) !== value) throw invalidToken();
+	return bytes;
+}
+function invalidToken(cause) {
+	return new _runlane_contracts_realtime.RunlaneError({
+		code: _runlane_contracts_realtime.ErrorCode.AccessDenied,
+		message: "Run access denied.",
+		retryable: false,
+		cause
+	});
+}
+// src/handler.ts
+const encoder = new TextEncoder();
+const runIdSchema = (0, _runlane_contracts_realtime.createRunlaneIdSchema)("Run id");
+const pollInterval = (0, _runlane_contracts_realtime.createDurationSchema)().parse(_runlane_contracts_realtime.contractDefaults.streams.pollInterval).milliseconds;
+const handlerOptionsSchema = zod.strictObject({
+	runlane: _runlane_utilities_browser.objectSurfaceSchema,
+	authorize: (0, _runlane_utilities_browser.createFunctionSchema)("authorize must be a function.").optional(),
+	tokens: realtimeTokenOptionsSchema.optional(),
+	telemetry: _runlane_utilities_browser.objectSurfaceSchema.optional(),
+	onTelemetryError: (0, _runlane_utilities_browser.createFunctionSchema)("onTelemetryError must be a function.").optional()
+}).refine((options) => options.authorize !== void 0 || options.tokens !== void 0, "Configure authorize for session access, tokens for bearer access, or both.");
+/** Mounts authorized, bounded SSE reads without starting workers or adding runtime storage work. */
+function createRunlaneRealtime(options) {
+	const checked = handlerOptionsSchema.safeParse(options);
+	if (!checked.success) throw require_wire.invalidOptions(checked.error, "handler");
+	const tokens = checked.data.tokens;
+	if (tokens !== void 0) {
+		requireHmacKey(tokens.key, "sign");
+		requireHmacKey(tokens.key, "verify");
+		for (const key of Object.values(tokens.verifyKeys ?? {})) requireHmacKey(key, "verify");
+	}
+	const verification = tokens === void 0 ? void 0 : {
+		audience: tokens.audience,
+		keys: {
+			...tokens.verifyKeys,
+			[tokens.keyId]: tokens.key
+		}
+	};
+	return {
+		async createToken(input) {
+			if (tokens === void 0) throw new _runlane_contracts_realtime.RunlaneError({
+				code: _runlane_contracts_realtime.ErrorCode.ConfigurationInvalid,
+				message: "Configure tokens before calling createToken."
+			});
+			return signRunToken(options.runlane.environment, tokens, input);
+		},
+		async handle(request) {
+			let operation = "subscribe";
+			try {
+				const route = parseRoute(request);
+				operation = route.name === void 0 ? "subscribe" : "read";
+				const token = await requestToken(request, route.runId, options, verification);
+				return await openConnection(options, request, route, await authorizeGrant(options, request, route, token, operation), token);
+			} catch (cause) {
+				const error = publicError(cause);
+				if (error.code === _runlane_contracts_realtime.ErrorCode.AccessDenied) recordDenial(options, cause, operation);
+				return Response.json({ error }, {
+					status: request.method === "GET" ? httpStatus(error.code) : 405,
+					headers: {
+						"cache-control": "no-store",
+						...request.method === "GET" ? {} : { allow: "GET" }
+					}
+				});
+			}
+		}
+	};
+}
+async function authorizeGrant(options, request, route, token, operation) {
+	let app;
+	try {
+		app = options.authorize === void 0 ? token?.grant : await options.authorize({
+			request,
+			runId: route.runId,
+			...token === void 0 ? {} : { token }
+		});
+	} catch (cause) {
+		(0, _runlane_contracts_realtime.recordRunlaneTelemetryMetric)(options, {
+			name: _runlane_contracts_realtime.RunlaneMetricName.RealtimeAuthorizationErrorCount,
+			value: 1,
+			attributes: {
+				[_runlane_contracts_realtime.RunlaneMetricAttribute.Operation]: operation,
+				[_runlane_contracts_realtime.RunlaneMetricAttribute.Reason]: "authorize_exception"
+			}
+		});
+		(0, _runlane_contracts_realtime.recordRunlaneTelemetryLog)(options, {
+			type: _runlane_contracts_realtime.RunlaneLogEventType.RealtimeAuthorizationFailed,
+			level: _runlane_contracts_realtime.RunlaneLogLevel.Error,
+			attributes: {
+				[_runlane_contracts_realtime.RunlaneLogAttribute.Operation]: operation,
+				[_runlane_contracts_realtime.RunlaneLogAttribute.Reason]: "authorize_exception"
+			}
+		});
+		throw new _runlane_contracts_realtime.RunlaneError({
+			code: _runlane_contracts_realtime.ErrorCode.InternalError,
+			message: "Realtime authorization failed.",
+			cause
+		});
+	}
+	if (app === void 0) throw accessDenied();
+	const parsed = _runlane_contracts_realtime.runAccessGrantSchema.safeParse(app);
+	if (!parsed.success) throw invalidRequest("Realtime grant is invalid.", parsed.error);
+	const grant = intersectGrants(parsed.data, token?.grant);
+	if (grant.permissions.length === 0 || route.name !== void 0 && !permitsStream(grant, route.name)) throw accessDenied();
+	return grant;
+}
+function recordDenial(options, cause, operation) {
+	const reason = accessDenialReasonSchema.safeParse(cause instanceof _runlane_contracts_realtime.RunlaneError ? cause.meta?.reason : void 0).data ?? "token_rejected";
+	if (reason !== "token_rejected") (0, _runlane_contracts_realtime.recordRunlaneTelemetryLog)(options, {
+		type: _runlane_contracts_realtime.RunlaneLogEventType.RealtimeAuthorizationDenied,
+		level: _runlane_contracts_realtime.RunlaneLogLevel.Warn,
+		attributes: {
+			[_runlane_contracts_realtime.RunlaneLogAttribute.Operation]: operation,
+			[_runlane_contracts_realtime.RunlaneLogAttribute.Reason]: reason
+		}
+	});
+	(0, _runlane_contracts_realtime.recordRunlaneTelemetryMetric)(options, {
+		name: _runlane_contracts_realtime.RunlaneMetricName.RealtimeAuthorizationDeniedCount,
+		value: 1,
+		attributes: {
+			[_runlane_contracts_realtime.RunlaneMetricAttribute.Operation]: operation,
+			[_runlane_contracts_realtime.RunlaneMetricAttribute.Reason]: reason
+		}
+	});
+}
+function parseRoute(request) {
+	if (request.method !== "GET") throw new _runlane_contracts_realtime.RunlaneError({
+		code: _runlane_contracts_realtime.ErrorCode.ValidationFailed,
+		message: "Realtime routes require GET.",
+		retryable: false
+	});
+	const url = new URL(request.url);
+	if (Array.from(url.searchParams.keys()).some((key) => key !== "after" && key !== require_wire.streamSelectionQuery.name) || url.searchParams.getAll("after").length > 1) throw invalidRequest("Only one after and one streams query parameter are accepted; use Authorization for credentials.");
+	const match = /\/runs\/([^/]+)\/(events|streams\/([^/]+))$/.exec(url.pathname);
+	if (match?.[1] === void 0) throw new _runlane_contracts_realtime.RunlaneError({
+		code: _runlane_contracts_realtime.ErrorCode.RunNotFound,
+		message: "Realtime route was not found.",
+		retryable: false
+	});
+	let runId;
+	let name;
+	try {
+		runId = runIdSchema.parse(decodeURIComponent(match[1]));
+		name = match[3] === void 0 ? void 0 : _runlane_contracts_realtime.runStreamNameSchema.parse(decodeURIComponent(match[3]));
+	} catch (cause) {
+		throw invalidRequest("Run id or stream name is invalid.", cause);
+	}
+	const selections = url.searchParams.getAll(require_wire.streamSelectionQuery.name);
+	if (selections.length > 1 || selections.length === 1 && (name !== void 0 || selections[0] !== require_wire.streamSelectionQuery.none)) throw invalidRequest("Stream selection requires one streams=none parameter on the events route.");
+	return {
+		runId,
+		...name === void 0 ? {} : { name },
+		...selections.length === 1 ? { streams: false } : {},
+		...parseResumeCursor(request, url)
+	};
+}
+function parseResumeCursor(request, url) {
+	const header = request.headers.get("last-event-id");
+	const query = url.searchParams.get("after");
+	if (header !== null && query !== null && header !== query) throw invalidCursor();
+	const raw = header ?? query;
+	const parsed = raw === null ? void 0 : _runlane_contracts_realtime.runCursorSchema.safeParse(raw);
+	if (parsed !== void 0 && !parsed.success) throw invalidCursor();
+	return parsed?.success ? { after: parsed.data } : {};
+}
+async function openConnection(options, request, route, grant, token) {
+	const started = require_wire.realtimeClock.now();
+	const operation = route.name === void 0 ? "subscribe" : "read";
+	const control = new AbortController();
+	const expires = Math.min(started + require_wire.realtimeTiming.connectionDuration, token === void 0 ? Infinity : token.expiresAt * 1e3);
+	const stop = () => control.abort();
+	request.signal.addEventListener("abort", stop, { once: true });
+	if (request.signal.aborted) stop();
+	const expiry = setTimeout(stop, Math.max(0, expires - require_wire.realtimeClock.now()));
+	const frames = sourceFrames(options.runlane, route, grant, control.signal);
+	let pending;
+	let cursor = route.after;
+	let closed = false;
+	const finish = () => {
+		if (closed) return;
+		closed = true;
+		clearTimeout(expiry);
+		request.signal.removeEventListener("abort", stop);
+		control.abort();
+		frames.return().catch(() => void 0);
+		(0, _runlane_contracts_realtime.recordRunlaneTelemetryMetric)(options, {
+			name: _runlane_contracts_realtime.RunlaneMetricName.RealtimeConnectionDurationMs,
+			value: Math.max(0, require_wire.realtimeClock.now() - started),
+			attributes: { [_runlane_contracts_realtime.RunlaneMetricAttribute.Operation]: operation }
+		});
+	};
+	const next = async () => {
+		if (control.signal.aborted || require_wire.realtimeClock.now() >= expires) return void 0;
+		pending ??= (0, _runlane_contracts_realtime.runWithRunlaneTelemetrySpan)(options, { name: route.name === void 0 ? _runlane_contracts_realtime.RunlaneSpanName.RealtimeSubscribe : _runlane_contracts_realtime.RunlaneSpanName.RealtimeRead }, () => frames.next()).catch((cause) => {
+			const { cursor, ...error } = publicSourceError(cause);
+			throw new _runlane_contracts_realtime.RunlaneError({
+				...error,
+				cause,
+				...cursor === void 0 ? {} : { meta: { cursor } }
+			});
+		});
+		const timer = new AbortController();
+		const abortTimer = () => timer.abort();
+		control.signal.addEventListener("abort", abortTimer, { once: true });
+		try {
+			const result = await Promise.race([pending, (0, _runlane_utilities_browser.waitForAbortableTimeout)(require_wire.realtimeTiming.heartbeatInterval, timer.signal).then(() => void 0)]);
+			if (require_wire.realtimeClock.now() >= expires) return void 0;
+			if (result === void 0) return encoder.encode((0, eventsource_encoder.encode)({ comment: "heartbeat" }));
+			pending = void 0;
+			if (result.done) return void 0;
+			const frame = result.value;
+			const bytes = encodeFrame(frame, cursor);
+			cursor = frame.cursor ?? cursor;
+			return bytes;
+		} finally {
+			timer.abort();
+			control.signal.removeEventListener("abort", abortTimer);
+		}
+	};
+	let first;
+	try {
+		first = await next();
+	} catch (cause) {
+		finish();
+		throw cause;
+	}
+	const body = new ReadableStream({
+		start(controller) {
+			const end = () => {
+				if (closed) return;
+				controller.close();
+				finish();
+			};
+			control.signal.addEventListener("abort", end, { once: true });
+			if (control.signal.aborted) end();
+		},
+		async pull(controller) {
+			try {
+				const bytes = control.signal.aborted || require_wire.realtimeClock.now() >= expires ? void 0 : first ?? await next();
+				if (closed) return;
+				first = void 0;
+				if (bytes === void 0) {
+					controller.close();
+					finish();
+					return;
+				}
+				controller.enqueue(bytes);
+			} catch (cause) {
+				if (closed) return;
+				controller.enqueue(encoder.encode((0, eventsource_encoder.encode)({
+					event: "error",
+					data: JSON.stringify(publicError(cause, cursor))
+				})));
+				controller.close();
+				finish();
+			}
+		},
+		cancel() {
+			finish();
+		}
+	}, { highWaterMark: 0 });
+	return new Response(body, { headers: {
+		"content-type": "text/event-stream; charset=utf-8",
+		"cache-control": "no-store",
+		"x-accel-buffering": "no"
+	} });
+}
+function encodeFrame(frame, cursor) {
+	const data = JSON.stringify(frame.data);
+	const bytes = encoder.encode((0, eventsource_encoder.encode)({
+		event: frame.event,
+		data,
+		...frame.cursor === void 0 ? {} : { id: frame.cursor }
+	}));
+	if (bytes.byteLength > _runlane_contracts_realtime.realtimeDefaults.maxEventBytes) throw new _runlane_contracts_realtime.RunlaneError({
+		code: _runlane_contracts_realtime.ErrorCode.EventTooLarge,
+		message: "Realtime event exceeds the serialized UTF-8 byte limit.",
+		retryable: false,
+		...cursor === void 0 ? {} : { meta: { cursor } }
+	});
+	return bytes;
+}
+async function* sourceFrames(source, route, grant, signal) {
+	if (route.name === void 0) {
+		for await (const event of source.runs.subscribe(route.runId, {
+			after: route.after,
+			signal,
+			streams: route.streams === false || !grant.permissions.includes(_runlane_contracts_realtime.RunReadPermission.Streams) ? false : grant.streams
+		})) {
+			if (signal.aborted) return;
+			const projected = projectEvent(event, grant);
+			yield projected === void 0 ? {
+				event: "checkpoint",
+				cursor: event.cursor,
+				data: {}
+			} : {
+				event: projected.type,
+				cursor: projected.cursor,
+				data: projected
+			};
+		}
+		if (!signal.aborted) yield {
+			event: "end",
+			data: {}
+		};
+		return;
+	}
+	yield* namedFrames(source, route.runId, route.name, route.after, signal);
+}
+async function* namedFrames(source, runId, name, initial, signal) {
+	let after = initial;
+	let terminal = false;
+	while (!signal.aborted) {
+		const controller = new AbortController();
+		const waiting = source.lane?.runSignal?.wait({
+			environment: source.environment,
+			runId,
+			signal: AbortSignal.any([signal, controller.signal]),
+			timeoutMs: pollInterval
+		}).catch((cause) => {
+			throw new _runlane_contracts_realtime.RunlaneError({
+				code: _runlane_contracts_realtime.ErrorCode.AdapterContractViolation,
+				message: "Lane run signal wait must not reject.",
+				cause
+			});
+		});
+		waiting?.catch(() => void 0);
+		try {
+			const page = await source.runs.readStream(runId, name, {
+				after,
+				limit: _runlane_contracts_realtime.contractDefaults.pagination.defaultLimit
+			});
+			yield* namedPageFrames(page, after);
+			after = page.cursor;
+			if (page.hasMore) continue;
+			if (terminal && page.records.length === 0) {
+				yield {
+					event: "end",
+					data: {}
+				};
+				return;
+			}
+			terminal = await readNamedRunTerminal(source, runId);
+			if (terminal) continue;
+			if (page.records.length === 0) await (waiting ?? (0, _runlane_utilities_browser.waitForAbortableTimeout)(pollInterval, signal));
+		} finally {
+			controller.abort();
+			await waiting;
+		}
+	}
+}
+async function readNamedRunTerminal(source, runId) {
+	const run = await source.runs.get(runId);
+	if (run === void 0) throw new _runlane_contracts_realtime.RunlaneError({
+		code: _runlane_contracts_realtime.ErrorCode.RunNotFound,
+		message: "Run was not found.",
+		retryable: false
+	});
+	return _runlane_contracts_realtime.runStatusValues.isTerminal(run.status);
+}
+function* namedPageFrames(page, after) {
+	for (const [index, record] of page.records.entries()) {
+		const last = index === page.records.length - 1;
+		yield {
+			event: "stream",
+			...last ? { cursor: page.cursor } : {},
+			data: {
+				...last ? { cursor: page.cursor } : {},
+				record
+			}
+		};
+	}
+	if (page.records.length === 0 && page.cursor !== after) yield {
+		event: "checkpoint",
+		cursor: page.cursor,
+		data: {}
+	};
+}
+function publicError(cause, cursor) {
+	const checkpoint = cursor ?? (cause instanceof _runlane_contracts_realtime.RunlaneError ? _runlane_contracts_realtime.runCursorSchema.safeParse(cause.meta?.cursor).data : void 0);
+	const resume = checkpoint === void 0 ? {} : { cursor: checkpoint };
+	if (cause instanceof _runlane_contracts_realtime.RunlaneError) {
+		const code = _runlane_contracts_realtime.runRealtimeErrorCodeSchema.safeParse(cause.code);
+		if (code.success && code.data !== _runlane_contracts_realtime.ErrorCode.InternalError) return {
+			code: code.data,
+			message: cause.message,
+			retryable: cause.retryable,
+			...resume
+		};
+	}
+	return {
+		code: _runlane_contracts_realtime.ErrorCode.InternalError,
+		message: "Realtime request failed.",
+		retryable: true,
+		...resume
+	};
+}
+function publicSourceError(cause) {
+	const error = publicError(cause);
+	if (cause instanceof _runlane_contracts_realtime.RunlaneError) switch (cause.code) {
+		case _runlane_contracts_realtime.ErrorCode.ConfigurationInvalid:
+		case _runlane_contracts_realtime.ErrorCode.ValidationFailed: return {
+			...error,
+			code: _runlane_contracts_realtime.ErrorCode.ValidationFailed,
+			message: "Realtime request is invalid.",
+			retryable: false
+		};
+		case _runlane_contracts_realtime.ErrorCode.RunCursorInvalid: return {
+			...error,
+			code: _runlane_contracts_realtime.ErrorCode.RunCursorInvalid,
+			message: "Run cursor is invalid.",
+			retryable: false
+		};
+		case _runlane_contracts_realtime.ErrorCode.RunNotFound: return {
+			...error,
+			code: _runlane_contracts_realtime.ErrorCode.RunNotFound,
+			message: "Run was not found.",
+			retryable: false
+		};
+		case _runlane_contracts_realtime.ErrorCode.OperationCancelled: return {
+			...error,
+			code: _runlane_contracts_realtime.ErrorCode.Disconnected,
+			message: "Realtime runtime is closing; reconnect to resume.",
+			retryable: true
+		};
+	}
+	return error;
+}
+function httpStatus(code) {
+	if (code === _runlane_contracts_realtime.ErrorCode.AccessDenied) return 403;
+	if (code === _runlane_contracts_realtime.ErrorCode.RunNotFound) return 404;
+	if (code === _runlane_contracts_realtime.ErrorCode.ValidationFailed || code === _runlane_contracts_realtime.ErrorCode.RunCursorInvalid) return 400;
+	return 500;
+}
+var AccessDenialReason = /* @__PURE__ */ function(AccessDenialReason) {
+	AccessDenialReason["ApplicationDenied"] = "application_denied";
+	AccessDenialReason["AuthorizationHeader"] = "authorization_header";
+	AccessDenialReason["VerificationUnconfigured"] = "verification_unconfigured";
+	AccessDenialReason["TokenScope"] = "token_scope";
+	return AccessDenialReason;
+}(AccessDenialReason || {});
+const accessDenialReasonSchema = zod.enum(AccessDenialReason);
+function accessDenied(reason = "application_denied") {
+	return new _runlane_contracts_realtime.RunlaneError({
+		code: _runlane_contracts_realtime.ErrorCode.AccessDenied,
+		message: "Run access denied.",
+		meta: { reason }
+	});
+}
+function invalidRequest(message, cause) {
+	return new _runlane_contracts_realtime.RunlaneError({
+		code: _runlane_contracts_realtime.ErrorCode.ValidationFailed,
+		message,
+		retryable: false,
+		cause
+	});
+}
+function invalidCursor() {
+	return new _runlane_contracts_realtime.RunlaneError({
+		code: _runlane_contracts_realtime.ErrorCode.RunCursorInvalid,
+		message: "Run cursor is invalid or conflicts with after.",
+		retryable: false
+	});
+}
+async function requestToken(request, runId, options, verification) {
+	const supplied = request.headers.get("authorization");
+	if (supplied === null) return void 0;
+	const match = /^Bearer ([a-z0-9_.-]+)$/i.exec(supplied);
+	if (match?.[1] === void 0) throw accessDenied("authorization_header");
+	if (verification === void 0) throw accessDenied("verification_unconfigured");
+	const token = await verifyRunToken(match[1], verification, options, new URL(request.url).pathname.endsWith("/events") ? "subscribe" : "read");
+	if (token.runId !== runId || token.environment.name !== options.runlane.environment.name) throw accessDenied("token_scope");
+	return token;
+}
+Object.defineProperty(exports, "ErrorCode", {
+	enumerable: true,
+	get: function() {
+		return _runlane_contracts_realtime.ErrorCode;
+	}
+});
+Object.defineProperty(exports, "RunReadPermission", {
+	enumerable: true,
+	get: function() {
+		return _runlane_contracts_realtime.RunReadPermission;
+	}
+});
+Object.defineProperty(exports, "RunlaneError", {
+	enumerable: true,
+	get: function() {
+		return _runlane_contracts_realtime.RunlaneError;
+	}
+});
+exports.createRunlaneRealtime = createRunlaneRealtime;
+
+//# sourceMappingURL=index.cjs.map