@apifuse/provider-sdk 2.1.0-beta.2 → 2.1.0-beta.4

package/src/runtime/insights.ts

@@ -27,7 +27,7 @@ const DNS_WARN_MS = 5;
 const BROWSER_IDLE_MS = 5_000;
 const REFRESH_WARN_RATE = 0.1;
 
-const TLS_REUSE_FIX = `const session = ctx.tls.createSession({ profile: 'chrome-146' });
+const TLS_REUSE_FIX = `const session = ctx.stealth.createSession({ profile: 'chrome-146' });
 const resp = await session.fetch(url, opts);`;
 
 const TRANSFORM_FIX = `transformResponse: (raw) => {
@@ -39,11 +39,11 @@ const LARGE_RESPONSE_FIX = `const resp = await ctx.http.get('/items', {
 });`;
 
 const DNS_FIX = `// Enable DNS caching or reuse a long-lived session per host.
-const session = ctx.tls.createSession({ profile: 'chrome-146' });
+const session = ctx.stealth.createSession({ profile: 'chrome-146' });
 await session.fetch(url, opts);`;
 
 const PROXY_FIX = `// Re-check whether this operation really needs a proxy.
-await ctx.tls.fetch(url, { ...opts, proxy: undefined });`;
+await ctx.stealth.fetch(url, { ...opts, proxy: undefined });`;
 
 const BROWSER_FIX = `await page.waitForSelector('[data-ready="true"]', {
 	timeout: 5_000,
@@ -128,12 +128,12 @@ function makeInsight(
 	};
 }
 
-function isTlsSpan(span: Span): boolean {
-	return span.name.startsWith("tls.");
+function isStealthSpan(span: Span): boolean {
+	return span.name.startsWith("stealth.");
 }
 
 function isRequestSpan(span: Span): boolean {
-	return span.name === "tls.fetch" || span.name.startsWith("http.");
+	return span.name === "stealth.fetch" || span.name.startsWith("http.");
 }
 
 function isBrowserSpan(span: Span): boolean {
@@ -146,11 +146,11 @@ function hasProxy(span: Span): boolean {
 }
 
 function getTlsReuseInsight(spans: Span[]): InsightResult {
-	const tlsSpans = spans.filter(isTlsSpan);
+	const tlsSpans = spans.filter(isStealthSpan);
 	if (tlsSpans.length === 0) {
 		return {
 			triggered: false,
-			message: "✓ TLS connection reuse: no TLS spans sampled yet",
+			message: "✓ Stealth connection reuse: no stealth spans sampled yet",
 		};
 	}
 
@@ -162,14 +162,14 @@ function getTlsReuseInsight(spans: Span[]): InsightResult {
 	if (1 - reuseRate >= 0.8) {
 		return {
 			triggered: true,
-			message: `⚠ TLS connection reuse: ${formatPercent(reuseRate * 100)} reused — TLS handshakes are happening on most requests`,
+			message: `⚠ Stealth connection reuse: ${formatPercent(reuseRate * 100)} reused — stealth handshakes are happening on most requests`,
 			fix: TLS_REUSE_FIX,
 		};
 	}
 
 	return {
 		triggered: false,
-		message: `✓ TLS connection reuse: ${formatPercent(reuseRate * 100)} (good)`,
+		message: `✓ Stealth connection reuse: ${formatPercent(reuseRate * 100)} (good)`,
 	};
 }
 
@@ -237,7 +237,7 @@ function getDnsRepeatedCandidate(spans: Span[]): DnsHostInsight | null {
 		{ dnsDurations: number[]; reuseCount: number; totalCount: number }
 	>();
 
-	for (const span of spans.filter(isTlsSpan)) {
+	for (const span of spans.filter(isStealthSpan)) {
 		const hostname = parseHostname(getStringAttribute(span, "url"));
 		const dnsMs = getNumberAttribute(span, "dns_ms");
 		if (!hostname || dnsMs === undefined) {

package/src/runtime/instrumentation.ts

@@ -15,7 +15,12 @@ export type InstrumentedProviderContext<T extends ProviderContext> = Omit<
 	trace: TraceContext;
 };
 
-type InstrumentedNamespace = "http" | "tls" | "browser" | "session" | "state";
+type InstrumentedNamespace =
+	| "http"
+	| "stealth"
+	| "browser"
+	| "session"
+	| "state";
 
 const BROWSER_PAGE_METHODS = new Set([
 	"goto",
@@ -105,7 +110,7 @@ function getMethod(
 		return methodName.toUpperCase();
 	}
 
-	if (namespace === "tls") {
+	if (namespace === "stealth") {
 		const options =
 			typeof args[1] === "object" && args[1] !== null ? args[1] : undefined;
 		if (options && "method" in options && typeof options.method === "string") {
@@ -141,7 +146,10 @@ function buildSpanAttributes(
 		attributes.method = method;
 	}
 
-	if (status !== undefined && (namespace === "http" || namespace === "tls")) {
+	if (
+		status !== undefined &&
+		(namespace === "http" || namespace === "stealth")
+	) {
 		attributes.status = status;
 	}
 
@@ -398,7 +406,7 @@ export function wrapWithInstrumentation<T extends ProviderContext>(
 
 			if (
 				property === "http" ||
-				property === "tls" ||
+				property === "stealth" ||
 				property === "browser" ||
 				property === "session" ||
 				property === "state"

package/src/runtime/key-derivation.ts

@@ -41,7 +41,7 @@ function computeInfo(providerId: string): Buffer {
 export function decodeMasterKey(encoded: string): Buffer {
 	if (typeof encoded !== "string" || encoded.length === 0) {
 		throw new ConfigurationError(
-			"master key is empty; set APIFUSE_MASTER_KEY_V{n} in the external secret manager",
+			"master key is empty; set APIFUSE__KEYRING__MASTER_KEY_V{n} in the external secret manager",
 		);
 	}
 

package/src/runtime/keyring.ts

@@ -22,9 +22,10 @@ export interface KeyRing {
 	): Promise<void>;
 }
 
-const DEFAULT_KEY_PREFIX = "APIFUSE_MASTER_KEY_V";
-const DEFAULT_ACCEPT_LIST_VAR = "APIFUSE_MASTER_KEY_ACCEPT_LIST";
-const DEFAULT_WRITER_VERSION_VAR = "APIFUSE_MASTER_KEY_WRITER_VERSION";
+const DEFAULT_KEY_PREFIX = "APIFUSE__KEYRING__MASTER_KEY_V";
+const DEFAULT_ACCEPT_LIST_VAR = "APIFUSE__KEYRING__MASTER_KEY_ACCEPT_LIST";
+const DEFAULT_WRITER_VERSION_VAR =
+	"APIFUSE__KEYRING__MASTER_KEY_WRITER_VERSION";
 
 function parseAcceptList(raw: string | undefined): number[] {
 	if (!raw || raw.trim().length === 0) {

package/src/runtime/proxy-errors.ts

@@ -0,0 +1,132 @@
+import { TransportError } from "../errors";
+
+export const PROXY_AUTH_IP_DENIED_CODE = "PROXY_AUTH_IP_DENIED";
+export const PROXY_AUTH_IP_DENIED_MESSAGE =
+	"Proxy source IP is not authorized. Add the runtime egress IP to the proxy provider allowlist.";
+export const PROXY_EDGE_AUTH_REJECTED_CODE = "PROXY_EDGE_AUTH_REJECTED";
+export const PROXY_EDGE_AUTH_REJECTED_MESSAGE =
+	"Proxy provider rejected a candidate endpoint during authentication. The SDK will retry or refresh the proxy pool when safe.";
+export const PROXY_POOL_STALE_CODE = "PROXY_POOL_STALE";
+export const PROXY_EDGE_TLS_REJECTED_CODE = "PROXY_EDGE_TLS_REJECTED";
+export const PROXY_POOL_EXHAUSTED_CODE = "PROXY_POOL_EXHAUSTED";
+export const PROXY_POOL_EXHAUSTED_MESSAGE =
+	"Proxy provider pool was exhausted. The SDK refreshed the proxy allocation, but all candidate endpoints failed.";
+
+const PROXY_POOL_STALE_STATUS_CODES = new Set([509, 512]);
+const PROXY_EDGE_TLS_REJECTED_STATUS_CODES = new Set([495]);
+
+const PROXY_AUTH_IP_DENIED_PATTERN =
+	/\b(?:source|egress|client)\s+ip\b.{0,120}\b(?:deny|denied|unauthori[sz]ed|not\s+authori[sz]ed|white\s*list|allow\s*list)\b|\b(?:white\s*list|allow\s*list)\b.{0,120}\b(?:source|egress|client)\s+ip\b/i;
+const PROXY_EDGE_AUTH_REJECTED_PATTERN =
+	/\bauth\s+ip\s+err\b|\bproxy\b.{0,120}\bauth(?:entication)?\b.{0,120}\b(?:reject(?:ed)?|fail(?:ed)?|invalid|den(?:y|ied)|unauthori[sz]ed)\b|\bauth(?:entication)?\b.{0,120}\b(?:reject(?:ed)?|fail(?:ed)?|invalid|den(?:y|ied)|unauthori[sz]ed)\b.{0,120}\bproxy\b/i;
+const PROXY_POOL_STALE_MESSAGE_PATTERN =
+	/\bproxy\b.{0,120}\b(?:pool|lease|expired|unavailable|exhausted|non[\s-]?200\s+code:\s*(?:509|512))\b|\bnon[\s-]?200\s+code:\s*(?:509|512)\b.{0,120}\bproxy\b|\bsmartproxy\b.{0,120}\b(?:509|512)\b/i;
+const PROXY_EDGE_TLS_REJECTED_MESSAGE_PATTERN =
+	/\b(?:smartproxy|proxy)\b.{0,160}\b(?:495|ssl|tls|cert(?:ificate)?|handshake|edge|connect|non[\s-]?200)\b|\b(?:495|ssl|tls|cert(?:ificate)?|handshake|edge|connect|non[\s-]?200)\b.{0,160}\b(?:smartproxy|proxy)\b/i;
+
+export function isProxyAuthIpDeniedMessage(message: string): boolean {
+	return PROXY_AUTH_IP_DENIED_PATTERN.test(message);
+}
+
+export function createProxyAuthIpDeniedError(cause?: Error): TransportError {
+	return new TransportError(PROXY_AUTH_IP_DENIED_MESSAGE, {
+		code: PROXY_AUTH_IP_DENIED_CODE,
+		cause,
+	});
+}
+
+export function isProxyEdgeAuthRejectedMessage(message: string): boolean {
+	return PROXY_EDGE_AUTH_REJECTED_PATTERN.test(message);
+}
+
+export function createProxyEdgeAuthRejectedError(
+	cause?: Error,
+): TransportError {
+	return new TransportError(PROXY_EDGE_AUTH_REJECTED_MESSAGE, {
+		code: PROXY_EDGE_AUTH_REJECTED_CODE,
+		cause,
+	});
+}
+
+export function isProxyPoolStaleStatus(status: number): boolean {
+	return PROXY_POOL_STALE_STATUS_CODES.has(status);
+}
+
+export function isProxyEdgeTlsRejectedResponse(
+	status: number,
+	evidence: string,
+): boolean {
+	return (
+		PROXY_EDGE_TLS_REJECTED_STATUS_CODES.has(status) &&
+		PROXY_EDGE_TLS_REJECTED_MESSAGE_PATTERN.test(evidence)
+	);
+}
+
+export function isProxyPoolStaleMessage(message: string): boolean {
+	return PROXY_POOL_STALE_MESSAGE_PATTERN.test(message);
+}
+
+export function isProxyPoolRefreshableError(error: unknown): boolean {
+	if (
+		error instanceof TransportError &&
+		error.code === PROXY_AUTH_IP_DENIED_CODE
+	) {
+		return false;
+	}
+
+	if (
+		error instanceof TransportError &&
+		(error.code === PROXY_POOL_STALE_CODE ||
+			error.code === PROXY_EDGE_AUTH_REJECTED_CODE ||
+			error.code === PROXY_EDGE_TLS_REJECTED_CODE)
+	) {
+		return true;
+	}
+
+	const cause = error instanceof Error ? error.cause : undefined;
+	const message = [
+		error instanceof Error ? error.message : String(error),
+		cause instanceof Error ? cause.message : "",
+	].join(" ");
+	return (
+		PROXY_POOL_STALE_MESSAGE_PATTERN.test(message) ||
+		PROXY_EDGE_AUTH_REJECTED_PATTERN.test(message)
+	);
+}
+
+export const isProxyPoolStaleError = isProxyPoolRefreshableError;
+
+export function createProxyPoolStaleError(
+	status: number,
+	cause?: Error,
+): TransportError {
+	return new TransportError(
+		`Proxy provider pool failed with status ${status}`,
+		{
+			code: PROXY_POOL_STALE_CODE,
+			status,
+			cause,
+		},
+	);
+}
+
+export function createProxyEdgeTlsRejectedError(
+	status: number,
+	cause?: Error,
+): TransportError {
+	return new TransportError(
+		`Proxy edge TLS request was rejected with status ${status}`,
+		{
+			code: PROXY_EDGE_TLS_REJECTED_CODE,
+			status,
+			cause,
+		},
+	);
+}
+
+export function createProxyPoolExhaustedError(cause?: Error): TransportError {
+	return new TransportError(PROXY_POOL_EXHAUSTED_MESSAGE, {
+		code: PROXY_POOL_EXHAUSTED_CODE,
+		cause,
+	});
+}

package/src/runtime/proxy-telemetry.ts

@@ -0,0 +1,253 @@
+import type {
+	ProxyAttemptTelemetryEvent,
+	ProxyCacheStatus,
+	ProxyResolutionTelemetryEvent,
+	ProxyTelemetrySink,
+	SmartproxyAllocatorBodyClass,
+} from "../config/loader";
+
+export const PROVIDER_TELEMETRY_HEADER = "X-ApiFuse-Provider-Telemetry";
+
+type ProviderTelemetryHeader = {
+	v: 1;
+	proxy?: {
+		provider: "smartproxy";
+		cacheStatus: ProxyCacheStatus;
+		cacheHit: boolean;
+		resolutionMs: number;
+		allocatorMs?: number;
+		allocatorStatus?: number;
+		allocatorBodyClass?: SmartproxyAllocatorBodyClass;
+		allocatorAttempts?: number;
+		lockWaitMs?: number;
+		redisReadMs?: number;
+		redisWriteMs?: number;
+		poolAgeMs?: number;
+		poolExpiresInMs?: number;
+		attempts: number;
+		refreshes?: number;
+		attemptSamples?: CompactProxyAttemptSample[];
+	};
+};
+
+type CompactProxyAttemptSample = {
+	n: number;
+	a: number;
+	i?: number;
+	h?: string;
+	o: "ok" | "error";
+	c?: string;
+	s?: number;
+	d?: number;
+};
+
+const MAX_HEADER_BYTES = 4_096;
+const MAX_PROXY_ATTEMPT_SAMPLES = 24;
+
+const CACHE_STATUS_SEVERITY: Record<ProxyCacheStatus, number> = {
+	disabled: 0,
+	memory_hit: 1,
+	redis_hit: 2,
+	soft_stale_refresh: 3,
+	redis_corrupt: 4,
+	redis_error: 5,
+	lock_wait: 6,
+	allocator: 7,
+};
+
+function sumOptional(
+	left: number | undefined,
+	right: number | undefined,
+): number | undefined {
+	const total = (left ?? 0) + (right ?? 0);
+	return total > 0 ? total : undefined;
+}
+
+function maxOptional(
+	left: number | undefined,
+	right: number | undefined,
+): number | undefined {
+	const values = [left, right].filter(
+		(value): value is number => typeof value === "number",
+	);
+	return values.length > 0 ? Math.max(...values) : undefined;
+}
+
+function worseStatus(
+	left: ProxyCacheStatus,
+	right: ProxyCacheStatus,
+): ProxyCacheStatus {
+	return CACHE_STATUS_SEVERITY[right] > CACHE_STATUS_SEVERITY[left]
+		? right
+		: left;
+}
+
+function encodeBase64Url(value: string): string {
+	return Buffer.from(value, "utf8").toString("base64url");
+}
+
+export class ProxyTelemetryCollector implements ProxyTelemetrySink {
+	#events: ProxyResolutionTelemetryEvent[] = [];
+	#attempts: ProxyAttemptTelemetryEvent[] = [];
+
+	recordProxyResolution(event: ProxyResolutionTelemetryEvent): void {
+		this.#events.push({
+			provider: "smartproxy",
+			cacheStatus: event.cacheStatus,
+			cacheHit: event.cacheHit,
+			resolutionMs: Math.max(0, Math.floor(event.resolutionMs)),
+			allocatorMs:
+				event.allocatorMs === undefined
+					? undefined
+					: Math.max(0, Math.floor(event.allocatorMs)),
+			allocatorStatus:
+				event.allocatorStatus === undefined
+					? undefined
+					: Math.max(0, Math.floor(event.allocatorStatus)),
+			allocatorBodyClass: event.allocatorBodyClass,
+			allocatorAttempts:
+				event.allocatorAttempts === undefined
+					? undefined
+					: Math.max(1, Math.floor(event.allocatorAttempts)),
+			lockWaitMs:
+				event.lockWaitMs === undefined
+					? undefined
+					: Math.max(0, Math.floor(event.lockWaitMs)),
+			redisReadMs:
+				event.redisReadMs === undefined
+					? undefined
+					: Math.max(0, Math.floor(event.redisReadMs)),
+			redisWriteMs:
+				event.redisWriteMs === undefined
+					? undefined
+					: Math.max(0, Math.floor(event.redisWriteMs)),
+			poolAgeMs:
+				event.poolAgeMs === undefined
+					? undefined
+					: Math.max(0, Math.floor(event.poolAgeMs)),
+			poolExpiresInMs:
+				event.poolExpiresInMs === undefined
+					? undefined
+					: Math.max(0, Math.floor(event.poolExpiresInMs)),
+			attempts: Math.max(1, Math.floor(event.attempts || 1)),
+			refreshes:
+				event.refreshes === undefined
+					? undefined
+					: Math.max(0, Math.floor(event.refreshes)),
+		});
+	}
+
+	recordProxyAttempt(event: ProxyAttemptTelemetryEvent): void {
+		if (this.#attempts.length >= MAX_PROXY_ATTEMPT_SAMPLES) return;
+		this.#attempts.push({
+			provider: "smartproxy",
+			attempt: Math.max(1, Math.floor(event.attempt || 1)),
+			...(event.poolIndex === undefined
+				? {}
+				: { poolIndex: Math.max(0, Math.floor(event.poolIndex)) }),
+			...(event.proxyHash ? { proxyHash: event.proxyHash.slice(0, 16) } : {}),
+			outcome: event.outcome === "ok" ? "ok" : "error",
+			...(event.errorCode ? { errorCode: event.errorCode.slice(0, 80) } : {}),
+			...(event.status === undefined
+				? {}
+				: { status: Math.max(0, Math.floor(event.status)) }),
+			...(event.durationMs === undefined
+				? {}
+				: { durationMs: Math.max(0, Math.floor(event.durationMs)) }),
+		});
+	}
+
+	toHeaderValue(): string | undefined {
+		const [first, ...rest] = this.#events;
+		if (!first) return undefined;
+
+		const aggregate = rest.reduce<ProxyResolutionTelemetryEvent>(
+			(acc, event) => ({
+				provider: "smartproxy",
+				cacheStatus: worseStatus(acc.cacheStatus, event.cacheStatus),
+				cacheHit: acc.cacheHit && event.cacheHit,
+				resolutionMs: acc.resolutionMs + event.resolutionMs,
+				allocatorMs: sumOptional(acc.allocatorMs, event.allocatorMs),
+				allocatorStatus: event.allocatorStatus ?? acc.allocatorStatus,
+				allocatorBodyClass: event.allocatorBodyClass ?? acc.allocatorBodyClass,
+				allocatorAttempts: sumOptional(
+					acc.allocatorAttempts,
+					event.allocatorAttempts,
+				),
+				lockWaitMs: sumOptional(acc.lockWaitMs, event.lockWaitMs),
+				redisReadMs: sumOptional(acc.redisReadMs, event.redisReadMs),
+				redisWriteMs: sumOptional(acc.redisWriteMs, event.redisWriteMs),
+				poolAgeMs: maxOptional(acc.poolAgeMs, event.poolAgeMs),
+				poolExpiresInMs: maxOptional(
+					acc.poolExpiresInMs,
+					event.poolExpiresInMs,
+				),
+				attempts: acc.attempts + event.attempts,
+				refreshes: sumOptional(acc.refreshes, event.refreshes),
+			}),
+			first,
+		);
+		const payload: ProviderTelemetryHeader = {
+			v: 1,
+			proxy: {
+				provider: "smartproxy",
+				cacheStatus: aggregate.cacheStatus,
+				cacheHit: aggregate.cacheHit,
+				resolutionMs: aggregate.resolutionMs,
+				...(aggregate.allocatorMs !== undefined
+					? { allocatorMs: aggregate.allocatorMs }
+					: {}),
+				...(aggregate.allocatorStatus !== undefined
+					? { allocatorStatus: aggregate.allocatorStatus }
+					: {}),
+				...(aggregate.allocatorBodyClass !== undefined
+					? { allocatorBodyClass: aggregate.allocatorBodyClass }
+					: {}),
+				...(aggregate.allocatorAttempts !== undefined
+					? { allocatorAttempts: aggregate.allocatorAttempts }
+					: {}),
+				...(aggregate.lockWaitMs !== undefined
+					? { lockWaitMs: aggregate.lockWaitMs }
+					: {}),
+				...(aggregate.redisReadMs !== undefined
+					? { redisReadMs: aggregate.redisReadMs }
+					: {}),
+				...(aggregate.redisWriteMs !== undefined
+					? { redisWriteMs: aggregate.redisWriteMs }
+					: {}),
+				...(aggregate.poolAgeMs !== undefined
+					? { poolAgeMs: aggregate.poolAgeMs }
+					: {}),
+				...(aggregate.poolExpiresInMs !== undefined
+					? { poolExpiresInMs: aggregate.poolExpiresInMs }
+					: {}),
+				attempts: aggregate.attempts,
+				...(aggregate.refreshes !== undefined
+					? { refreshes: aggregate.refreshes }
+					: {}),
+				...(this.#attempts.length > 0
+					? {
+							attemptSamples: this.#attempts.map((attempt, index) => ({
+								n: index + 1,
+								a: attempt.attempt,
+								...(attempt.poolIndex === undefined
+									? {}
+									: { i: attempt.poolIndex }),
+								...(attempt.proxyHash ? { h: attempt.proxyHash } : {}),
+								o: attempt.outcome,
+								...(attempt.errorCode ? { c: attempt.errorCode } : {}),
+								...(attempt.status === undefined ? {} : { s: attempt.status }),
+								...(attempt.durationMs === undefined
+									? {}
+									: { d: attempt.durationMs }),
+							})),
+						}
+					: {}),
+			},
+		};
+
+		const encoded = encodeBase64Url(JSON.stringify(payload));
+		if (encoded.length > MAX_HEADER_BYTES) return undefined;
+		return encoded;
+	}
+}

package/src/runtime/request-options.ts

@@ -0,0 +1,66 @@
+import type {
+	RequestParamPrimitive,
+	RequestParams,
+	RequestParamValue,
+} from "../types";
+
+function isParamArray(
+	value: RequestParamValue,
+): value is readonly RequestParamPrimitive[] {
+	return Array.isArray(value);
+}
+
+function appendQueryValue(
+	searchParams: URLSearchParams,
+	key: string,
+	value: string | number | boolean | null | undefined,
+): void {
+	if (value === null || value === undefined) {
+		return;
+	}
+	searchParams.append(key, String(value));
+}
+
+export function appendQueryParams(url: string, params?: RequestParams): string {
+	if (!params || Object.keys(params).length === 0) {
+		return url;
+	}
+
+	const parsed = new URL(url);
+	for (const [key, value] of Object.entries(params)) {
+		if (isParamArray(value)) {
+			for (const item of value)
+				appendQueryValue(parsed.searchParams, key, item);
+			continue;
+		}
+		appendQueryValue(parsed.searchParams, key, value);
+	}
+
+	return parsed.toString();
+}
+
+export function normalizeHttpRequestBody(
+	body: unknown,
+): string | Buffer | undefined {
+	if (body === undefined) {
+		return undefined;
+	}
+
+	if (typeof body === "string" || Buffer.isBuffer(body)) {
+		return body;
+	}
+
+	if (body instanceof URLSearchParams) {
+		return body.toString();
+	}
+
+	if (body instanceof ArrayBuffer) {
+		return Buffer.from(body);
+	}
+
+	if (ArrayBuffer.isView(body)) {
+		return Buffer.from(body.buffer, body.byteOffset, body.byteLength);
+	}
+
+	return JSON.stringify(body);
+}

package/src/runtime/state.ts

@@ -0,0 +1,76 @@
+import { ProviderError } from "../errors";
+import type {
+	ProviderRuntimeState,
+	ProviderStateNamespace,
+	StateCasResult,
+	StateNamespaceOptions,
+	StateValue,
+	StateWriteOptions,
+} from "../types";
+
+export class UnsupportedProviderStateError extends ProviderError {
+	constructor(
+		message = "Provider runtime state is not available in this runtime",
+	) {
+		super(message, { code: "PROVIDER_STATE_UNSUPPORTED" });
+		this.name = "UnsupportedProviderStateError";
+	}
+}
+
+class UnsupportedProviderStateNamespace implements ProviderStateNamespace {
+	async list<T>(_options?: {
+		limit?: number;
+		prefix?: string;
+	}): Promise<StateValue<T>[]> {
+		throw new UnsupportedProviderStateError();
+	}
+	async get<T>(_key: string): Promise<StateValue<T> | null> {
+		throw new UnsupportedProviderStateError();
+	}
+	async set<T>(
+		_key: string,
+		_value: T,
+		_options?: StateWriteOptions,
+	): Promise<StateValue<T>> {
+		throw new UnsupportedProviderStateError();
+	}
+	async patch<T extends Record<string, unknown>>(
+		_key: string,
+		_partial: Partial<T>,
+		_options?: StateWriteOptions,
+	): Promise<StateValue<T>> {
+		throw new UnsupportedProviderStateError();
+	}
+	async compareAndSet<T>(
+		_key: string,
+		_expectedVersion: number,
+		_value: T,
+		_options?: StateWriteOptions,
+	): Promise<StateCasResult<T>> {
+		throw new UnsupportedProviderStateError();
+	}
+	async delete(_key: string): Promise<void> {
+		throw new UnsupportedProviderStateError();
+	}
+	async increment(
+		_key: string,
+		_field: string,
+		_delta?: number,
+		_options?: StateWriteOptions,
+	): Promise<StateValue<Record<string, unknown>>> {
+		throw new UnsupportedProviderStateError();
+	}
+}
+
+class UnsupportedProviderRuntimeState implements ProviderRuntimeState {
+	namespace(
+		_name: string,
+		_options: StateNamespaceOptions,
+	): ProviderStateNamespace {
+		return new UnsupportedProviderStateNamespace();
+	}
+}
+
+export function createUnsupportedProviderRuntimeState(): ProviderRuntimeState {
+	return new UnsupportedProviderRuntimeState();
+}