@gradio/client 2.5.1 → 2.7.0

package/src/test/init.test.ts

@@ -7,7 +7,6 @@ import {
 	expect,
 	vi
 } from "vitest";
-
 import { Client, client, duplicate } from "..";
 import {
 	transformed_api_info,
@@ -16,6 +15,7 @@ import {
 } from "./test_data";
 import { initialise_server } from "./server";
 import { SPACE_NOT_FOUND_MSG } from "../constants";
+import { HttpResponse, http } from "msw";
 
 const app_reference = "hmb/hello_world";
 const broken_app_reference = "hmb/bye_world";
@@ -65,6 +65,29 @@ describe("Client class", () => {
 			expect(app.config).toEqual(config_response);
 		});
 
+		test("forwards a page query when resolving config and API info", async () => {
+			const requested_urls: string[] = [];
+			server.use(
+				http.get(`${direct_app_reference}/config`, ({ request }) => {
+					requested_urls.push(request.url);
+					return HttpResponse.json(config_response);
+				}),
+				http.get(`${direct_app_reference}/info`, ({ request }) => {
+					requested_urls.push(request.url);
+					return HttpResponse.json(response_api_info);
+				})
+			);
+
+			await Client.connect(direct_app_reference, {
+				query_params: { page: "details" }
+			});
+
+			expect(requested_urls).toEqual([
+				`${direct_app_reference}/config?page=details`,
+				`${direct_app_reference}/info?page=details`
+			]);
+		});
+
 		test("connecting successfully to a private running app with a space reference", async () => {
 			const app = await Client.connect("hmb/secret_world", {
 				token: "hf_123"
@@ -76,6 +99,29 @@ describe("Client class", () => {
 			});
 		});
 
+		test("signs initial file values in a private Space config", async () => {
+			const props = config_response.components[0].props;
+			props.value = {
+				path: "/tmp/cat.png",
+				url: `${secret_direct_app_reference}/gradio_api/file=/tmp/cat.png`,
+				meta: { _type: "gradio.FileData" }
+			};
+			try {
+				const app = await Client.connect("hmb/secret_world", {
+					token: "hf_123"
+				});
+				const value = app.config?.components[0].props.value as {
+					url: string;
+				};
+
+				expect(value.url).toBe(
+					`${secret_direct_app_reference}/gradio_api/file=/tmp/cat.png?__sign=jwt_123`
+				);
+			} finally {
+				delete props.value;
+			}
+		});
+
 		test("connecting successfully to a private running app with a direct app URL ", async () => {
 			const app = await Client.connect(secret_direct_app_reference, {
 				token: "hf_123"

package/src/test/run_history.test.ts

@@ -7,7 +7,9 @@ import {
 	delete_run_history,
 	on_run_history_change,
 	read_run_history,
+	read_run_history_storage,
 	run_history_url,
+	set_run_history_storage,
 	stage_run_history_replay,
 	start_run_history,
 	update_run_history,
@@ -25,6 +27,8 @@ const replacement_apps = Array.from(
 const in_browser = typeof window !== "undefined";
 
 afterEach(() => {
+	set_run_history_storage(scope, { type: "browser" });
+	set_run_history_storage(other_scope, { type: "browser" });
 	clear_run_history(scope);
 	clear_run_history(other_scope);
 	for (const replacement_app of replacement_apps) {
@@ -34,6 +38,48 @@ afterEach(() => {
 });
 
 describe.skipIf(!in_browser)("run history", () => {
+	test("uses this browser as the default history storage", () => {
+		expect(read_run_history_storage(scope)).toEqual({ type: "browser" });
+	});
+
+	test("remembers a bucket while switching storage destinations", () => {
+		set_run_history_storage(scope, {
+			type: "bucket",
+			bucket_id: "alice/app-history"
+		});
+		expect(read_run_history_storage(scope)).toEqual({
+			type: "bucket",
+			bucket_id: "alice/app-history"
+		});
+
+		set_run_history_storage(scope, {
+			type: "browser",
+			bucket_id: "alice/app-history"
+		});
+		expect(read_run_history_storage(scope)).toEqual({
+			type: "browser",
+			bucket_id: "alice/app-history"
+		});
+	});
+
+	test("does not duplicate bucket runs in local storage", () => {
+		set_run_history_storage(scope, {
+			type: "bucket",
+			bucket_id: "alice/app-history"
+		});
+
+		const id = start_run_history({
+			app_id,
+			endpoint: "/predict",
+			api_name: "/predict",
+			fn_index: 0,
+			inputs: ["hello"]
+		});
+
+		expect(id).toBeNull();
+		expect(read_run_history(scope)).toEqual([]);
+	});
+
 	test("stores runs per app id with the page and inputs", () => {
 		const id = start_run_history({
 			app_id,

package/src/test/server.ts

@@ -8,6 +8,7 @@ const IS_NODE =
 interface MockServer {
 	start: (opts: StartOptions) => void | ReturnType<SetupWorker["start"]>;
 	stop: () => void | Promise<void>;
+	use: (...handlers: any[]) => void;
 	resetHandlers: (...handlers: any[]) => void;
 }
 
@@ -18,6 +19,7 @@ export async function initialise_server(): Promise<MockServer> {
 		return {
 			start: (opts: StartOptions) => server.listen(opts),
 			stop: () => server.close(),
+			use: (...h) => server.use(...h),
 			resetHandlers: (...h) => server.resetHandlers(...h)
 		};
 	}
@@ -26,6 +28,7 @@ export async function initialise_server(): Promise<MockServer> {
 	return {
 		start: (opts: StartOptions) => worker.start(opts),
 		stop: () => worker.stop(),
+		use: (...h) => worker.use(...h),
 		resetHandlers: (...h) => worker.resetHandlers(...h)
 	};
 }

package/src/test/submit.test.ts

@@ -1,6 +1,9 @@
 import { describe, beforeAll, afterEach, afterAll, test, expect } from "vitest";
+import { HttpResponse, http } from "msw";
 
 import { Client } from "../client";
+import { set_run_history_storage } from "../utils/run_history";
+import { direct_space_url } from "./handlers";
 import { initialise_server } from "./server";
 
 let server: Awaited<ReturnType<typeof initialise_server>>;
@@ -9,7 +12,12 @@ beforeAll(async () => {
 	server = await initialise_server();
 	await server.start({ quiet: true });
 });
-afterEach(() => server.resetHandlers());
+afterEach(() => {
+	server.resetHandlers();
+	if (typeof window !== "undefined") {
+		set_run_history_storage({ app_id: 123 }, { type: "browser" });
+	}
+});
 afterAll(() => server.stop());
 
 async function race_with_timeout<T>(
@@ -29,6 +37,72 @@ async function race_with_timeout<T>(
 }
 
 describe("submit iterator", () => {
+	test("signs private Space file URLs before publishing data events", async () => {
+		const app = await Client.connect("hmb/hello_world", {
+			token: "hf_123",
+			events: ["data", "status"]
+		});
+		app.stream_status.open = true;
+
+		const iterator = app.submit("/predict", ["hi"]);
+		const event_id = await iterator.wait_for_id();
+		const callback = app.event_callbacks[event_id as string];
+
+		const events: any[] = [];
+		const consumer = (async () => {
+			for await (const event of iterator) events.push(event);
+		})();
+
+		await callback({
+			msg: "process_completed",
+			output: {
+				data: [
+					{
+						path: "/tmp/cat.png",
+						url: `${direct_space_url}/gradio_api/file=/tmp/cat.png`,
+						meta: { _type: "gradio.FileData" }
+					}
+				]
+			},
+			success: true
+		});
+		await consumer;
+
+		const data_event = events.find((event) => event.type === "data");
+		expect(data_event.data[0].url).toBe(
+			`${direct_space_url}/gradio_api/file=/tmp/cat.png?__sign=jwt_123`
+		);
+	});
+
+	test.skipIf(typeof window === "undefined")(
+		"sends the selected history bucket with queued submissions",
+		async () => {
+			const app = await Client.connect("hmb/hello_world");
+			const scope = {
+				app_id: app.config?.app_id,
+				username: app.config?.username
+			};
+			set_run_history_storage(scope, {
+				type: "bucket",
+				bucket_id: "alice/app-history"
+			});
+
+			let header: string | null = null;
+			server.resetHandlers(
+				http.post(`${direct_space_url}/queue/join`, ({ request }) => {
+					header = request.headers.get("x-gradio-history-bucket");
+					return HttpResponse.json({ event_id: "bucket-event" });
+				})
+			);
+
+			const iterator = app.submit("/predict", ["hi"]);
+			await expect(iterator.wait_for_id()).resolves.toBe("bucket-event");
+			expect(header).toBe("alice/app-history");
+			await iterator.return();
+			set_run_history_storage(scope, { type: "browser" });
+		}
+	);
+
 	test("next() after the iterator is closed resolves to {done: true}", async () => {
 		const app = await Client.connect("hmb/hello_world");
 		// Avoid opening a real SSE stream — the test does not need one.

package/src/test/upload.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it, vi } from "vitest";
+
+import type { Client } from "../client";
+import { FileData, upload } from "../upload";
+
+describe("upload", () => {
+	it("encodes uploaded file paths in file URLs", async () => {
+		const path = "/tmp/computer%20vision#Huggy.png";
+		const client = {
+			api_prefix: "/gradio_api",
+			upload_files: vi.fn().mockResolvedValue({ files: [path] })
+		} as unknown as Client;
+		const input = new FileData({
+			path,
+			blob: new File([], "computer%20vision#Huggy.png")
+		});
+
+		const result = await upload.call(client, [input], "https://example.com");
+
+		expect(result?.[0]).toMatchObject({
+			path,
+			url: "https://example.com/gradio_api/file=/tmp/computer%2520vision%23Huggy.png"
+		});
+	});
+});

package/src/types.ts

@@ -354,11 +354,11 @@ export interface ClientOptions {
 	 */
 	oauth_token?: string;
 	/**
-	 * Whether to save each call's inputs and outputs in this browser's local
-	 * storage, so they can be reviewed on the app's run history page. Defaults
-	 * to true, and only ever applies in a browser: in Node there is no storage
-	 * to write to and nothing is recorded. The app can turn it off for everyone
-	 * with `run_history=False` on `launch()`, which takes precedence over this.
+	 * Whether to save each call's inputs and outputs to the history destination
+	 * selected in this browser (local storage by default, or a connected bucket).
+	 * Defaults to true, and only ever applies in a browser: in Node there is no
+	 * selected destination and nothing is recorded. The app can turn it off for
+	 * everyone with `run_history=False` on `launch()`, which takes precedence.
 	 */
 	record_history?: boolean;
 }

package/src/upload.ts

@@ -30,10 +30,14 @@ export async function upload(
 				} else {
 					if (response.files) {
 						return response.files.map((f, i) => {
+							const encoded_path = f
+								.split("/")
+								.map((segment) => encodeURIComponent(segment))
+								.join("/");
 							const file = new FileData({
 								...file_data[i],
 								path: f,
-								url: `${root_url}${this.api_prefix}/file=${f}`
+								url: `${root_url}${this.api_prefix}/file=${encoded_path}`
 							});
 							return file;
 						});

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)
@@ -365,6 +412,7 @@ function apply_run_history_replay_impl(
 }
 
 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;
 
@@ -522,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 {

package/src/utils/submit.ts

@@ -10,7 +10,12 @@ import type {
 	SubmitIterable
 } from "../types";
 
-import { skip_queue, post_message, handle_payload } from "../helpers/data";
+import {
+	skip_queue,
+	post_message,
+	handle_payload,
+	sign_file_urls
+} from "../helpers/data";
 import { get_zerogpu_origin } from "../helpers/zerogpu";
 import {
 	handle_message,
@@ -30,6 +35,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,12 +69,13 @@ 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;
 
 		if (!api_info) throw new Error(NO_API_INFO_MSG);
 		if (!config) throw new Error("Could not resolve app config");
+		const root = config.root;
 
 		let { fn_index, endpoint_info, dependency } = get_endpoint_info(
 			api_info,
@@ -114,6 +121,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
@@ -162,6 +176,9 @@ export function submit(
 		// event subscription methods
 		function fire_event(event: GradioEvent): void {
 			update_run_history(history_scope, history_run_id, event);
+			if (event.type === "data" || event.type === "render") {
+				sign_file_urls(event.data, root, api_prefix, that.jwt);
+			}
 			if (all_events || events_to_publish[event.type]) {
 				push_event(event);
 			}
@@ -385,7 +402,8 @@ export function submit(
 								...payload,
 								session_hash,
 								event_id
-							}
+							},
+							addt_headers
 						);
 						if (status !== 200) {
 							fire_event({

package/src/utils/view_api.ts

@@ -28,7 +28,10 @@ export async function view_api(this: Client): Promise<any> {
 		if (typeof window !== "undefined" && window.gradio_api_info) {
 			api_info = window.gradio_api_info;
 		} else {
-			const url = join_urls(config.root, this.api_prefix, API_INFO_URL);
+			const url = new URL(
+				join_urls(config.root, this.api_prefix, API_INFO_URL)
+			);
+			if (this.page !== null) url.searchParams.set("page", this.page);
 			response = await this.fetch(url, {
 				headers,
 				credentials: this.options.credentials ?? "same-origin"