rivetkit 2.3.19 → 2.3.21

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "rivetkit",
-	"version": "2.3.19",
+	"version": "2.3.21",
 	"description": "Lightweight libraries for building stateful actors on edge platforms",
 	"license": "Apache-2.0",
 	"keywords": [
@@ -213,14 +213,15 @@
 		"@rivet-dev/agent-os-core": "^0.1.1",
 		"@rivet-dev/services": "^0.1.5",
 		"@rivetkit/bare-ts": "^0.6.2",
-		"@rivetkit/engine-cli": "2.3.19",
-		"@rivetkit/engine-envoy-protocol": "2.3.19",
+		"@rivetkit/engine-api-full": "2.3.21",
+		"@rivetkit/engine-cli": "2.3.21",
+		"@rivetkit/engine-envoy-protocol": "2.3.21",
 		"@rivetkit/on-change": "6.0.1",
-		"@rivetkit/rivetkit-napi": "2.3.19",
-		"@rivetkit/rivetkit-wasm": "2.3.19",
-		"@rivetkit/traces": "2.3.19",
-		"@rivetkit/virtual-websocket": "2.3.19",
-		"@rivetkit/workflow-engine": "2.3.19",
+		"@rivetkit/rivetkit-napi": "2.3.21",
+		"@rivetkit/rivetkit-wasm": "2.3.21",
+		"@rivetkit/traces": "2.3.21",
+		"@rivetkit/virtual-websocket": "2.3.21",
+		"@rivetkit/workflow-engine": "2.3.21",
 		"cbor-x": "^1.6.0",
 		"drizzle-orm": "0.45.2",
 		"hono": "^4.7.0",
@@ -270,7 +271,7 @@
 	"stableVersion": "0.8.0",
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/rivet-dev/actors.git",
+		"url": "https://github.com/rivet-dev/rivet.git",
 		"directory": "rivetkit-typescript/packages/rivetkit"
 	}
 }

package/src/actor/actions.ts

@@ -1,4 +1,5 @@
 import type { PrimitiveSchema } from "./schema";
+import type { ActionSampleRates } from "./tracing";
 
 export type RuntimeActionHandler = (...args: any[]) => any;
 
@@ -46,6 +47,41 @@ export function flattenActionInputSchemas(
 	return flattened;
 }
 
+/**
+ * Flatten per-action sample rates into dot-separated action names.
+ *
+ * @throws TypeError when a rate names something that is not an action.
+ */
+export function flattenActionTraceSamplers(
+	actions: unknown,
+	rates: ActionSampleRates = {},
+): Record<string, number> {
+	const handlers = flattenActionHandlers(actions);
+	const flattened = Object.fromEntries(flattenSampleRates(rates, []));
+	for (const name of Object.keys(flattened)) {
+		if (!Object.hasOwn(handlers, name)) {
+			throw new TypeError(
+				`tracing.actions.${name} does not name an action`,
+			);
+		}
+	}
+	return flattened;
+}
+
+function flattenSampleRates(
+	rates: ActionSampleRates,
+	path: readonly string[],
+): Array<[name: string, rate: number]> {
+	return Object.entries(rates).flatMap(
+		([segment, rate]): Array<[name: string, rate: number]> => {
+			const childPath = [...path, segment];
+			return typeof rate === "number"
+				? [[childPath.join("."), rate]]
+				: flattenSampleRates(rate, childPath);
+		},
+	);
+}
+
 interface ActionEntry {
 	name: string;
 	path: string[];

package/src/actor/config.ts

@@ -16,6 +16,7 @@ import type {
 	PrimitiveSchema,
 	QueueSchemaConfig,
 } from "./schema";
+import type { ActionSampleRates, ActorTracingOptions } from "./tracing";
 
 export const DEFAULT_SLEEP_GRACE_PERIOD = 15_000;
 
@@ -1342,6 +1343,12 @@ export const ActorOptionsSchema = GlobalActorOptionsBaseSchema.extend(
 export type ActorOptions = z.infer<typeof ActorOptionsSchema>;
 export type ActorOptionsInput = z.input<typeof ActorOptionsSchema>;
 
+const zSampleRate = z.number().min(0).max(1);
+
+const zActionSampleRates: z.ZodType<ActionSampleRates> = z.lazy(() =>
+	z.record(z.string(), z.union([zSampleRate, zActionSampleRates])),
+);
+
 export const ActorConfigSchema = z
 	.object({
 		onCreate: zFunction().optional(),
@@ -1359,6 +1366,13 @@ export const ActorConfigSchema = z
 		onWebSocket: zFunction().optional(),
 		actions: zActionTree.default(() => ({})),
 		actionInputSchemas: z.record(z.string(), z.any()).optional(),
+		tracing: z
+			.object({
+				sampler: zSampleRate.optional(),
+				actions: zActionSampleRates.optional(),
+			})
+			.strict()
+			.optional(),
 		connParamsSchema: z.any().optional(),
 		events: z.record(z.string(), z.any()).optional(),
 		queues: z.record(z.string(), z.any()).optional(),
@@ -1904,6 +1918,12 @@ interface BaseActorConfig<
 	 */
 	actionInputSchemas?: ActionInputSchemas;
 
+	/**
+	 * How much of this actor's work is recorded in traces. Defaults to the
+	 * process sampler from `OTEL_TRACES_SAMPLER`.
+	 */
+	tracing?: ActorTracingOptions<TActions>;
+
 	/**
 	 * Optional schema for validating connection params in native runtimes.
 	 */
@@ -2061,6 +2081,7 @@ export type ActorConfigInput<
 } & Omit<
 	z.input<typeof ActorConfigSchema>,
 	| "actions"
+	| "tracing"
 	| "events"
 	| "queues"
 	| "onCreate"
@@ -2437,6 +2458,12 @@ export const DocActorConfigSchema = z
 			.describe(
 				"Optional schemas for validating action argument tuples in native runtimes. May mirror nested action groups or use dot-separated low-level action names.",
 			),
+		tracing: z
+			.unknown()
+			.optional()
+			.describe(
+				"Trace sampling for this actor: `sampler` is the share of its invocations that are recorded, from 0 to 1, with optional per-action rates under `actions`. A rate lowers what is recorded and never raises it. Defaults to the process sampler from OTEL_TRACES_SAMPLER.",
+			),
 		connParamsSchema: z
 			.unknown()
 			.optional()

package/src/actor/definition.ts

@@ -1,6 +1,10 @@
 import type { AnyDatabaseProvider } from "@/common/database/config";
 import type { RegistryConfig } from "@/registry/config";
-import { flattenActionHandlers, flattenActionInputSchemas } from "./actions";
+import {
+	flattenActionHandlers,
+	flattenActionInputSchemas,
+	flattenActionTraceSamplers,
+} from "./actions";
 import {
 	type Actions,
 	type ActorConfig,
@@ -209,6 +213,7 @@ export function actor<
 	>;
 	flattenActionHandlers(config.actions);
 	flattenActionInputSchemas(config.actions, config.actionInputSchemas);
+	flattenActionTraceSamplers(config.actions, config.tracing?.actions);
 	return new ActorDefinition(config);
 }
 

package/src/actor/mod.ts

@@ -67,3 +67,8 @@ export {
 	queue,
 	type Type,
 } from "./schema";
+export type {
+	ActionSampleRates,
+	ActionTraceSamplers,
+	ActorTracingOptions,
+} from "./tracing";

package/src/actor/tracing.ts

@@ -0,0 +1,28 @@
+/** Sample rates keyed by action name, nested like the actor's action groups. */
+export interface ActionSampleRates {
+	readonly [name: string]: number | ActionSampleRates;
+}
+
+/**
+ * {@link ActionSampleRates} limited to the actions of one actor, so a rate for
+ * an action that does not exist is a compile error.
+ */
+export type ActionTraceSamplers<TActions> = {
+	readonly [K in keyof TActions]?: TActions[K] extends (
+		...args: never[]
+	) => unknown
+		? number
+		: ActionTraceSamplers<TActions[K]>;
+};
+
+/** Trace sampling for one actor definition. */
+export interface ActorTracingOptions<TActions> {
+	/**
+	 * Share of this actor's invocations that are recorded, from 0 to 1. A rate
+	 * lowers what is recorded and never raises it, so an invocation inside a
+	 * trace the caller did not record is not recorded at any rate.
+	 */
+	readonly sampler?: number;
+	/** Rates that replace `sampler` for single actions. */
+	readonly actions?: ActionTraceSamplers<TActions>;
+}

package/src/client/actor-conn.ts

@@ -51,6 +51,7 @@ import { ACTOR_CONNS_SYMBOL, type ClientRaw } from "./client";
 import * as errors from "./errors";
 import { isRetryableLifecycleReconnectSignal } from "./lifecycle-errors";
 import { logger } from "./log";
+import { isInvalidToken } from "./token-provider";
 import { outboundTelemetryHeaders } from "./outbound-telemetry";
 import {
 	createQueueSender,
@@ -183,6 +184,7 @@ export class ActorConnRaw {
 	#onOpenPromise?: ReturnType<typeof promiseWithResolvers<undefined>>;
 
 	#websocket?: UniversalWebSocket;
+	#authRetryAvailable = true;
 
 	#client: ClientRaw;
 	#driver: EngineControlClient;
@@ -531,6 +533,15 @@ export class ActorConnRaw {
 		if (error instanceof errors.ActorConnDisposed) {
 			return false;
 		}
+		if (
+			error instanceof errors.ActorError &&
+			isInvalidToken(error.group, error.code) &&
+			this.#driver.refreshAuthToken &&
+			this.#authRetryAvailable
+		) {
+			this.#authRetryAvailable = false;
+			return true;
+		}
 
 		if (
 			error instanceof errors.ActorError &&
@@ -679,6 +690,7 @@ export class ActorConnRaw {
 			});
 
 			// Update connection state (this also notifies handlers)
+			this.#authRetryAvailable = true;
 			this.#setConnStatus("connected");
 
 			// Resolve open promise
@@ -853,6 +865,7 @@ export class ActorConnRaw {
 
 	/** Called by the onclose event from drivers. */
 	async #handleOnClose(event: Event | CloseEventLike) {
+		const failedSocket = this.#websocket;
 		// We can't use `event instanceof CloseEvent` because it's not defined in NodeJS
 		const closeEvent = event as CloseEventLike;
 		const wasClean = closeEvent.wasClean;
@@ -882,6 +895,26 @@ export class ActorConnRaw {
 
 			if (parsed) {
 				const { group, code, rayId } = parsed;
+				if (
+					isInvalidToken(group, code) &&
+					closeEvent.code === 1008 &&
+					failedSocket
+				) {
+					try {
+						if (
+							!(await this.#driver.refreshAuthToken?.(
+								failedSocket,
+							))
+						) {
+							this.#authRetryAvailable = false;
+						}
+					} catch {
+						logger().warn("token renewal failed");
+						this.#authRetryAvailable = false;
+					}
+				} else if (isInvalidToken(group, code)) {
+					this.#authRetryAvailable = false;
+				}
 
 				if (this.#shouldReconnectForStaleActor(group, code)) {
 					this.#clearResolvedActorIdentity();
@@ -941,7 +974,7 @@ export class ActorConnRaw {
 			}
 
 			// Automatically reconnect if we were connected
-			if (wasConnected) {
+			if (wasConnected && this.#authRetryAvailable) {
 				logger().debug({
 					msg: "triggering reconnect",
 					connId: this.#connId,

package/src/client/actor-handle.ts

@@ -25,6 +25,13 @@ import { AsyncMutex } from "@/common/database/shared";
 import type { Encoding, JsonCompatValue } from "@/common/encoding";
 import { deconstructError } from "@/common/utils";
 import type { EngineControlClient } from "@/engine-client/driver";
+import type {
+	ActorIssueTokenOptions,
+	ActorTokenPermissions,
+	ActorTokenResource,
+	IssuedToken,
+	TokenGrant,
+} from "@/client/auth";
 import type { StartCallSpan, CurrentActorInvocation } from "@/registry/runtime";
 import {
 	decodeCborCompat,
@@ -993,6 +1000,27 @@ export class ActorHandleRaw {
 		);
 	}
 
+	/** Issue a token scoped to this actor. Defaults to actor gateway read access. */
+	async issueToken(options: ActorIssueTokenOptions = {}): Promise<IssuedToken> {
+		const actorId = await this.resolve();
+		const permissions: ActorTokenPermissions = options.permissions ?? {
+			actor_gateway: ["read"],
+		};
+		const grants: TokenGrant[] = (
+			Object.keys(permissions) as ActorTokenResource[]
+		).flatMap((resource) => {
+			const operations = permissions[resource];
+			return operations
+				? [{ resource, target: { id: actorId }, operations }]
+				: [];
+		});
+		return this.#driver.issueToken({
+			subject: options.subject,
+			expiresIn: options.expiresIn,
+			grants,
+		});
+	}
+
 	/**
 	 * Returns the raw URL for routing traffic to the actor.
 	 */
@@ -1048,4 +1076,4 @@ export type ActorHandle<AD extends AnyActorDefinition> = Omit<
 	// Resolve method returns the actor ID
 	resolve(): Promise<string>;
 } & ActorDefinitionQueueSend<AD> &
-	ActorDefinitionActions<AD>;
+	Omit<ActorDefinitionActions<AD>, keyof ActorHandleRaw>;

package/src/client/auth.ts

@@ -0,0 +1,37 @@
+import type { Rivet } from "@rivetkit/engine-api-full";
+
+/** A namespace-scoped Engine grant. The caller must provide every grant explicitly. */
+export type TokenGrant = Rivet.AuthTokenGrant;
+
+/** Options for `client.auth.issueToken()`. `expiresIn` is in seconds. */
+export type IssueTokenOptions = Pick<
+	Rivet.AuthTokenCreateRequest,
+	"subject" | "grants"
+> & {
+	expiresIn?: Rivet.AuthTokenCreateRequest["duration"];
+};
+
+/** Token timestamps are Unix milliseconds. */
+export interface IssuedToken {
+	token: Rivet.AuthTokenCreateResponse["token"];
+	issuedAt: Rivet.AuthTokenCreateResponse["issuedTs"];
+	expiresAt: Rivet.AuthTokenCreateResponse["expiresTs"];
+}
+
+/** Resources that can be scoped to a single actor ID. */
+export type ActorTokenResource = Extract<
+	Rivet.AuthTokenGrant["resource"],
+	"actor_gateway" | "actor" | "actor_kv"
+>;
+
+export type ActorTokenPermissions = Partial<
+	Record<ActorTokenResource, Rivet.AuthTokenGrant["operations"]>
+>;
+
+/** Options for `actor.issueToken()`. Omit permissions for gateway read access only. */
+export type ActorIssueTokenOptions = Pick<
+	IssueTokenOptions,
+	"subject" | "expiresIn"
+> & {
+	permissions?: ActorTokenPermissions;
+};

package/src/client/client.ts

@@ -1,4 +1,5 @@
 import type { AnyActorDefinition } from "@/actor/definition";
+import type { IssuedToken, IssueTokenOptions } from "@/client/auth";
 import type { ActorQuery } from "@/client/query";
 import type { Encoding } from "@/common/encoding";
 import type { EngineControlClient } from "@/engine-client/driver";
@@ -198,6 +199,10 @@ export interface ActorClientRuntimeOptions {
  */
 export class ClientRaw {
 	#disposed = false;
+	/** Issue namespace-scoped tokens with an explicit grant list. */
+	readonly auth: {
+		issueToken(options: IssueTokenOptions): Promise<IssuedToken>;
+	};
 
 	[ACTOR_CONNS_SYMBOL] = new Set<ActorConnRaw>();
 
@@ -215,6 +220,9 @@ export class ClientRaw {
 		options: ClientRawOptions & ActorClientRuntimeOptions = {},
 	) {
 		this.#driver = driver;
+		this.auth = {
+			issueToken: (issueOptions) => this.#driver.issueToken(issueOptions),
+		};
 
 		this.#encodingKind = options.encoding ?? "bare";
 		this.#gatewayOptions = options.gateway ?? {};
@@ -469,11 +477,11 @@ export class ClientRaw {
  *
  * @template A The actor registry type.
  */
-export type Client<A extends Registry<any>> = ClientRaw & {
+export type Client<A extends Registry<any>> = ClientRaw & Omit<{
 	[K in keyof ExtractActorsFromRegistry<A>]: ActorAccessor<
 		ExtractActorsFromRegistry<A>[K]
 	>;
-};
+}, keyof ClientRaw>;
 
 export type AnyClient = Client<Registry<any>>;
 

package/src/client/config.ts

@@ -1,5 +1,6 @@
 import z from "zod/v4";
 import { EncodingSchema } from "@/common/encoding";
+import { isLocalEngineEndpoint } from "@/common/engine";
 import type { RegistryConfig } from "@/registry/config";
 import type { GetUpgradeWebSocket } from "@/utils";
 import { tryParseEndpoint } from "@/utils/endpoint-parser";
@@ -10,6 +11,7 @@ import {
 	getRivetPool,
 	getRivetToken,
 } from "@/utils/env-vars";
+import type { GetToken } from "./token-provider";
 
 const DEFAULT_ENDPOINT = "http://localhost:6420";
 export const DEFAULT_MAX_QUERY_INPUT_SIZE = 4 * 1024;
@@ -54,6 +56,9 @@ export const ClientConfigSchemaBase = z.object({
 		.optional()
 		.transform((val) => val ?? getRivetToken()),
 
+	/** Issue and renew a client token on demand. Overrides the static token when provided. */
+	getToken: z.custom<GetToken>().optional(),
+
 	/** Namespace to connect to. */
 	namespace: z
 		.string()
@@ -131,7 +136,12 @@ export function transformClientConfig(
 		...config,
 		endpoint: parsedEndpoint?.endpoint,
 		namespace: parsedEndpoint?.namespace ?? config.namespace ?? "default",
-		token: parsedEndpoint?.token ?? config.token,
+		token:
+			parsedEndpoint?.token ??
+			config.token ??
+			(config.endpoint && isLocalEngineEndpoint(config.endpoint)
+				? "default"
+				: undefined),
 	};
 }
 
@@ -151,6 +161,7 @@ export function convertRegistryConfigToClientConfig(
 	return {
 		endpoint: config.endpoint,
 		token: config.token,
+		getToken: undefined,
 		namespace: config.namespace,
 		poolName: config.envoy.poolName,
 		headers: config.headers,

package/src/client/mod.ts

@@ -19,6 +19,14 @@ export {
 	UserError,
 } from "@/client/errors";
 export type { CreateRequest } from "@/client/query";
+export type {
+	ActorIssueTokenOptions,
+	ActorTokenPermissions,
+	ActorTokenResource,
+	IssuedToken,
+	IssueTokenOptions,
+	TokenGrant,
+} from "./auth";
 export type { Encoding } from "@/common/encoding";
 export type {
 	ActorActionFunction,
@@ -49,6 +57,7 @@ export type {
 	QueryOptions,
 	Region,
 } from "./client";
+export type { GetToken } from "./token-provider";
 
 /**
  * Creates a client with the actor accessor proxy.

package/src/client/token-provider.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, test, vi } from "vitest";
+import {
+	isInvalidToken,
+	isInvalidTokenResponse,
+	TokenProvider,
+} from "./token-provider";
+
+describe("renewable client tokens", () => {
+	test("single-flights initial issuance and concurrent rejection refreshes", async () => {
+		const getToken = vi.fn(
+			async ({ forceRefresh }: { forceRefresh: boolean }) =>
+				forceRefresh ? "renewed" : "initial",
+		);
+		const provider = new TokenProvider(getToken);
+		expect(
+			await Promise.all([provider.current(), provider.current()]),
+		).toEqual(["initial", "initial"]);
+		expect(getToken).toHaveBeenCalledTimes(1);
+		expect(
+			await Promise.all([
+				provider.refreshIfCurrent("initial"),
+				provider.refreshIfCurrent("initial"),
+			]),
+		).toEqual(["renewed", "renewed"]);
+		expect(getToken).toHaveBeenCalledTimes(2);
+		expect(await provider.refreshIfCurrent("initial")).toBe("renewed");
+		expect(getToken).toHaveBeenCalledTimes(2);
+	});
+
+	test("retries failed issuance and refuses empty credentials", async () => {
+		const getToken = vi
+			.fn()
+			.mockRejectedValueOnce(new Error("issuer down"))
+			.mockResolvedValueOnce("ok");
+		const provider = new TokenProvider(getToken);
+		await expect(provider.current()).rejects.toThrow("issuer down");
+		expect(await provider.current()).toBe("ok");
+		await expect(
+			new TokenProvider(async () => "").current(),
+		).rejects.toThrow("nonempty");
+	});
+
+	test("refreshes before a known JWT expiry and treats opaque tokens as unexpiring hints", async () => {
+		const payload = btoa(
+			JSON.stringify({ exp: Math.floor(Date.now() / 1_000) + 1 }),
+		).replaceAll("=", "");
+		const getToken = vi.fn(async () => `header.${payload}.signature`);
+		const provider = new TokenProvider(getToken);
+		await provider.current();
+		await provider.current();
+		expect(getToken).toHaveBeenCalledTimes(2);
+		const opaque = vi.fn(async () => "opaque");
+		const opaqueProvider = new TokenProvider(opaque);
+		await opaqueProvider.current();
+		await opaqueProvider.current();
+		expect(opaque).toHaveBeenCalledTimes(1);
+	});
+
+	test("only confirmed 401 invalid/expired errors permit renewal", () => {
+		expect(isInvalidToken("auth", "invalid_token")).toBe(true);
+		expect(isInvalidToken("auth", "token_expired")).toBe(true);
+		for (const code of [
+			"insufficient_permissions",
+			"verification_unavailable",
+			"issuance_unavailable",
+		]) {
+			expect(isInvalidToken("auth", code)).toBe(false);
+		}
+		expect(
+			isInvalidTokenResponse(
+				new Response(null, {
+					status: 401,
+					headers: { "x-rivet-error": "auth.token_expired" },
+				}),
+			),
+		).toBe(true);
+		expect(
+			isInvalidTokenResponse(
+				new Response(null, {
+					status: 503,
+					headers: { "x-rivet-error": "auth.token_expired" },
+				}),
+			),
+		).toBe(false);
+	});
+});

package/src/client/token-provider.ts

@@ -0,0 +1,93 @@
+/** Called when RivetKit needs a credential. Keep issuer secrets on your backend. */
+export type GetToken = (options: { forceRefresh: boolean }) => Promise<string>;
+
+/** Only a confirmed invalid/expired credential can trigger an automatic renewal. */
+export function isInvalidToken(group: string, code: string): boolean {
+	return (
+		group === "auth" &&
+		(code === "invalid_token" || code === "token_expired")
+	);
+}
+
+export function isInvalidTokenResponse(response: Response): boolean {
+	if (response.status !== 401) return false;
+	const error = response.headers.get("x-rivet-error");
+	if (!error) return false;
+	const separator = error.indexOf(".");
+	return (
+		separator > 0 &&
+		isInvalidToken(error.slice(0, separator), error.slice(separator + 1))
+	);
+}
+
+/** One token cache per client; concurrent requests and refreshes share the same issuance call. */
+export class TokenProvider {
+	#cached?: { token: string; expiresAt?: number };
+	#pending?: Promise<string>;
+	#pendingForce = false;
+
+	constructor(private readonly getToken: GetToken) {}
+
+	async current(): Promise<string> {
+		if (
+			this.#cached &&
+			(this.#cached.expiresAt === undefined ||
+				Date.now() < this.#cached.expiresAt - 5_000)
+		) {
+			return this.#cached.token;
+		}
+		return this.#load(false);
+	}
+
+	/** A late rejection for an older token must never erase a newer credential. */
+	async refreshIfCurrent(failedToken: string): Promise<string> {
+		if (this.#pending !== undefined) {
+			const wasForced = this.#pendingForce;
+			const refreshed = await this.#pending;
+			if (wasForced || refreshed !== failedToken) return refreshed;
+		}
+		if (this.#cached?.token !== failedToken) {
+			return this.current();
+		}
+		return this.#load(true);
+	}
+
+	#load(forceRefresh: boolean): Promise<string> {
+		if (this.#pending !== undefined) return this.#pending;
+
+		const pending = Promise.resolve()
+			.then(() => this.getToken({ forceRefresh }))
+			.then((token) => {
+				if (typeof token !== "string" || token.length === 0) {
+					throw new Error(
+						"getToken must resolve to a nonempty string",
+					);
+				}
+				this.#cached = { token, expiresAt: jwtExpiration(token) };
+				return token;
+			})
+			.finally(() => {
+				if (this.#pending === pending) this.#pending = undefined;
+			});
+		this.#pending = pending;
+		this.#pendingForce = forceRefresh;
+		return pending;
+	}
+}
+
+// This is only a cache hint, never a signature or authorization check. The Engine verifies JWTs.
+function jwtExpiration(token: string): number | undefined {
+	try {
+		const payload = token.split(".")[1];
+		if (!payload) return undefined;
+		const claims = JSON.parse(
+			atob(payload.replace(/-/g, "+").replace(/_/g, "/")),
+		) as { exp?: unknown };
+		return typeof claims.exp === "number" &&
+			Number.isSafeInteger(claims.exp)
+			? claims.exp * 1_000
+			: undefined;
+	} catch {
+		return undefined;
+	}
+}

package/src/client/utils.ts

@@ -229,6 +229,7 @@ export async function sendHttpRequest<
 					metadata: responseData.metadata,
 					rayId: rayId ?? undefined,
 					actor: responseData.actor,
+					statusCode: response.status,
 				},
 			);
 		} catch (error) {