@gradio/client 2.5.0 → 2.6.0

package/src/utils/bucket_sync.ts

@@ -0,0 +1,153 @@
+/**
+ * Client for the durable run history in an HF Hub bucket
+ * (`/gradio_api/run-history/*`).
+ *
+ * Read-only by design. Records are written by the server from the run it
+ * actually executed — there is no push function here, and nothing in this
+ * module can create a record.
+ *
+ * Every call names the bucket it is talking about. The server holds no
+ * per-session binding, so two tabs (or two apps on one origin) cannot end up
+ * reading each other's history.
+ */
+
+const BUCKET_ID_RE = /^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-][a-zA-Z0-9_./-]*$/;
+
+export function is_valid_bucket_id(id: string): boolean {
+	if (!BUCKET_ID_RE.test(id)) return false;
+	return !id
+		.split("/")
+		.some((seg) => seg === "" || seg === "." || seg === "..");
+}
+
+/** Mirrors `HistoryRecord` in `gradio/history.py`. */
+export interface HistoryRecord {
+	record_id: string;
+	endpoint: string;
+	inputs: unknown;
+	outputs: unknown;
+	started_at: string;
+	schema_version: number;
+}
+
+export interface HistoryResult<T> {
+	ok: boolean;
+	status: number;
+	data: T;
+	detail?: string;
+}
+
+function url(
+	root: string,
+	path: string,
+	params?: Record<string, string>
+): string {
+	const query = params ? `?${new URLSearchParams(params)}` : "";
+	const base = root.replace(/\/+$/, "");
+	if (base) return `${base}/gradio_api/run-history/${path}${query}`;
+	// No configured root. A leading slash would drop any mount subpath
+	// (`mount_gradio_app(app, path="/myapp")`), so resolve against the document
+	// base, which gradio sets via <base href> on the app shell.
+	if (typeof document !== "undefined" && document.baseURI) {
+		return new URL(
+			`gradio_api/run-history/${path}${query}`,
+			document.baseURI
+		).toString();
+	}
+	return `gradio_api/run-history/${path}${query}`;
+}
+
+async function parse_error(res: Response): Promise<string> {
+	try {
+		const j = await res.json();
+		return typeof j?.detail === "string" ? j.detail : `${res.status}`;
+	} catch {
+		return `${res.status}`;
+	}
+}
+
+async function request<T>(
+	input: string,
+	init: RequestInit,
+	fallback: T,
+	pick: (body: any) => T
+): Promise<HistoryResult<T>> {
+	try {
+		const res = await fetch(input, { credentials: "include", ...init });
+		if (!res.ok) {
+			// An empty list and a failed request are different things: a 401 here
+			// means "sign in", not "no runs yet".
+			return {
+				ok: false,
+				status: res.status,
+				data: fallback,
+				detail: await parse_error(res)
+			};
+		}
+		return { ok: true, status: res.status, data: pick(await res.json()) };
+	} catch (e) {
+		return { ok: false, status: 0, data: fallback, detail: String(e) };
+	}
+}
+
+/**
+ * Create the bucket if it does not exist and confirm it is writable. Stores
+ * nothing server-side — the caller keeps its own choice and names it on every
+ * later request.
+ */
+export async function connect_bucket(
+	root: string,
+	bucket_id: string
+): Promise<HistoryResult<null>> {
+	if (!is_valid_bucket_id(bucket_id)) {
+		return {
+			ok: false,
+			status: 422,
+			data: null,
+			detail: "invalid bucket id"
+		};
+	}
+	return request(
+		url(root, "connect"),
+		{
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({ bucket_id })
+		},
+		null,
+		() => null
+	);
+}
+
+export async function list_user_buckets(
+	root: string
+): Promise<HistoryResult<string[]>> {
+	return request<string[]>(url(root, "buckets"), {}, [], (b) =>
+		Array.isArray(b?.buckets) ? b.buckets : []
+	);
+}
+
+export async function list_bucket_records(
+	root: string,
+	bucket: string
+): Promise<HistoryResult<HistoryRecord[]>> {
+	return request(url(root, "records", { bucket }), {}, [], (b) =>
+		Array.isArray(b?.records) ? b.records : []
+	);
+}
+
+export function asset_url(
+	root: string,
+	bucket: string,
+	endpoint: string,
+	record_id: string,
+	filename: string
+): string {
+	return url(
+		root,
+		`records/${encodeURIComponent(endpoint)}/${encodeURIComponent(
+			record_id
+		)}/assets/${encodeURIComponent(filename)}`,
+		{ bucket }
+	);
+}

package/src/utils/run_history.ts

@@ -11,6 +11,7 @@ import type { GradioEvent, StatusMessage } from "../types";
 const KEY_ROOT = "gradio:run-history:";
 const STORAGE_PREFIX = `${KEY_ROOT}v2:`;
 const REPLAY_PREFIX = `${KEY_ROOT}replay:v2:`;
+const DESTINATION_PREFIX = `${KEY_ROOT}destination:v1:`;
 const MAX_RUNS = 100;
 const MAX_APPS = 8;
 
@@ -26,6 +27,10 @@ export interface RunHistoryScope {
 	username?: string | null;
 }
 
+export type RunHistoryStorage =
+	| { type: "browser"; bucket_id?: string }
+	| { type: "bucket"; bucket_id: string };
+
 /**
  * Run history is a side effect of submitting, never the point of it, so no
  * failure in here may propagate into the caller and break the app. Every
@@ -115,6 +120,45 @@ function replay_key(scope: RunHistoryScope | null | undefined): string | null {
 	return key ? key.replace(STORAGE_PREFIX, REPLAY_PREFIX) : null;
 }
 
+function destination_key(
+	scope: RunHistoryScope | null | undefined
+): string | null {
+	const key = storage_key(scope);
+	return key ? key.replace(STORAGE_PREFIX, DESTINATION_PREFIX) : null;
+}
+
+function read_run_history_storage_impl(
+	scope: RunHistoryScope | null | undefined
+): RunHistoryStorage {
+	const key = destination_key(scope);
+	if (!key) return { type: "browser" };
+	try {
+		const value = JSON.parse(window.localStorage.getItem(key) || "null");
+		if (typeof value?.bucket_id === "string") {
+			return value.type === "bucket"
+				? { type: "bucket", bucket_id: value.bucket_id }
+				: { type: "browser", bucket_id: value.bucket_id };
+		}
+		return { type: "browser" };
+	} catch {
+		return { type: "browser" };
+	}
+}
+
+function set_run_history_storage_impl(
+	scope: RunHistoryScope | null | undefined,
+	storage: RunHistoryStorage
+): void {
+	const key = destination_key(scope);
+	if (!key) return;
+	if (storage.type === "browser" && !storage.bucket_id) {
+		window.localStorage.removeItem(key);
+	} else {
+		window.localStorage.setItem(key, JSON.stringify(storage));
+	}
+	notify_run_history_change();
+}
+
 /** When a run was most recently saved under a key, for deciding what to drop. */
 function last_saved_at(key: string): number {
 	try {
@@ -140,7 +184,10 @@ function prune_apps(current_key: string): void {
 	const stale = [
 		// Keys written by an older layout can never be read again.
 		...keys.filter(
-			(key) => !key.startsWith(STORAGE_PREFIX) && !key.startsWith(REPLAY_PREFIX)
+			(key) =>
+				!key.startsWith(STORAGE_PREFIX) &&
+				!key.startsWith(REPLAY_PREFIX) &&
+				!key.startsWith(DESTINATION_PREFIX)
 		),
 		...keys
 			.filter((key) => key.startsWith(STORAGE_PREFIX) && key !== current_key)
@@ -308,7 +355,64 @@ function consume_run_history_replay_impl(
 	}
 }
 
+/**
+ * The parts of an app config a replayed run writes back into. Kept structural
+ * so every entry point — the SPA and the SSR app each carry their own `Config`
+ * declaration — can hand its config straight over.
+ */
+export interface ReplayTarget {
+	components: { id: number; type: string; props: Record<string, any> }[];
+	dependencies: {
+		id: number;
+		api_name?: string | null;
+		inputs: number[];
+		outputs: number[];
+	}[];
+}
+
+function restore_run_impl(config: ReplayTarget, run: StoredRun): boolean {
+	const dependency = config.dependencies.find(
+		(item) =>
+			item.id === run.fn_index ||
+			(typeof item.api_name === "string" &&
+				`/${item.api_name.replace(/^\//, "")}` === run.api_name)
+	);
+	if (!dependency) return false;
+
+	const inputs = Array.isArray(run.inputs)
+		? run.inputs
+		: Object.values((run.inputs ?? {}) as Record<string, unknown>);
+	const outputs = Array.isArray(run.outputs)
+		? run.outputs
+		: run.outputs === null || run.outputs === undefined
+			? []
+			: [run.outputs];
+
+	const restore = (ids: number[], saved: unknown[]): void => {
+		for (const [index, id] of ids.entries()) {
+			const component = config.components.find((item) => item.id === id);
+			if (!component || index >= saved.length) continue;
+			// `gr.State` is held on the server and always saved as null, so
+			// writing it back would wipe out the component's real default.
+			if (component.type === "state") continue;
+			component.props.value = saved[index];
+		}
+	};
+
+	restore(dependency.inputs, inputs);
+	restore(dependency.outputs, outputs);
+	return true;
+}
+
+function apply_run_history_replay_impl(
+	config: ReplayTarget & RunHistoryScope
+): boolean {
+	const run = consume_run_history_replay_impl(config);
+	return run ? restore_run_impl(config, run) : false;
+}
+
 function start_run_history_impl(options: StartRunOptions): string | null {
+	if (read_run_history_storage_impl(options).type === "bucket") return null;
 	const key = storage_key(options);
 	if (!key) return null;
 
@@ -466,6 +570,21 @@ export function read_run_history(
 	return safely(() => read_run_history_impl(scope), []);
 }
 
+export function read_run_history_storage(
+	scope: RunHistoryScope | null | undefined
+): RunHistoryStorage {
+	return safely(() => read_run_history_storage_impl(scope), {
+		type: "browser"
+	});
+}
+
+export function set_run_history_storage(
+	scope: RunHistoryScope | null | undefined,
+	storage: RunHistoryStorage
+): void {
+	safely(() => set_run_history_storage_impl(scope, storage), undefined);
+}
+
 export function clear_run_history(
 	scope: RunHistoryScope | null | undefined
 ): void {
@@ -492,6 +611,19 @@ export function consume_run_history_replay(
 	return safely(() => consume_run_history_replay_impl(scope), null);
 }
 
+/**
+ * Applies the run staged by the history page, if this page load is the one it
+ * was staged for. Every entry point that renders an app has to call this, or
+ * "Load run" silently does nothing on that entry point.
+ *
+ * @returns whether a staged run was found and applied.
+ */
+export function apply_run_history_replay(
+	config: ReplayTarget & RunHistoryScope
+): boolean {
+	return safely(() => apply_run_history_replay_impl(config), false);
+}
+
 export function start_run_history(options: StartRunOptions): string | null {
 	return safely(() => start_run_history_impl(options), null);
 }

package/src/utils/submit.ts

@@ -30,6 +30,7 @@ import {
 import { apply_diff_stream, close_stream } from "./stream";
 import { Client } from "../client";
 import {
+	read_run_history_storage,
 	start_run_history,
 	update_run_history,
 	update_run_inputs
@@ -63,7 +64,7 @@ export function submit(
 			api_prefix
 		} = this;
 
-		const addt_headers = additional_headers || { "x-gradio-user": "api" };
+		const base_headers = additional_headers || { "x-gradio-user": "api" };
 
 		const that = this;
 
@@ -114,6 +115,13 @@ export function submit(
 		const history_enabled =
 			config.run_history !== false && this.options.record_history !== false;
 		const history_scope = { app_id: config.app_id, username: config.username };
+		const history_storage = read_run_history_storage(history_scope);
+		const addt_headers = {
+			...base_headers,
+			...(history_enabled && history_storage.type === "bucket"
+				? { "x-gradio-history-bucket": history_storage.bucket_id }
+				: {})
+		};
 		const history_run_id =
 			!history_enabled || !is_documented_endpoint
 				? null
@@ -385,7 +393,8 @@ export function submit(
 								...payload,
 								session_hash,
 								event_id
-							}
+							},
+							addt_headers
 						);
 						if (status !== 200) {
 							fire_event({