@gradio/client 2.3.0 → 2.4.0

package/src/test/api_info.test.ts

@@ -1,7 +1,7 @@
 import {
 	INVALID_URL_MSG,
 	QUEUE_FULL_MSG,
-	SPACE_METADATA_ERROR_MSG
+	SPACE_NOT_FOUND_MSG
 } from "../constants";
 import { beforeAll, afterEach, afterAll, it, expect, describe } from "vitest";
 import {
@@ -10,7 +10,8 @@ import {
 	get_type,
 	process_endpoint,
 	join_urls,
-	map_data_to_params
+	map_data_to_params,
+	transform_api_info
 } from "../helpers/api_info";
 import { initialise_server } from "./server";
 import { transformed_api_info } from "./test_data";
@@ -184,6 +185,34 @@ describe("handle_message", () => {
 		});
 	});
 
+	it("should carry changed_state_ids in the streaming status when msg is 'process_streaming'", () => {
+		const data = {
+			msg: "process_streaming",
+			success: true,
+			code: 200,
+			time_limit: 30,
+			eta: 5,
+			progress_data: { current: 50, total: 100 },
+			output: { data: [1], changed_state_ids: [3] }
+		};
+		const last_status = "pending";
+		const result = handle_message(data, last_status);
+		expect(result).toEqual({
+			type: "streaming",
+			status: {
+				queue: true,
+				message: undefined,
+				stage: "streaming",
+				time_limit: 30,
+				code: 200,
+				progress_data: { current: 50, total: 100 },
+				changed_state_ids: [3],
+				eta: 5
+			},
+			data: { data: [1], changed_state_ids: [3] }
+		});
+	});
+
 	it("should return type 'complete' with success status when msg is 'process_completed' and success is true", () => {
 		const data = {
 			msg: "process_completed",
@@ -443,19 +472,13 @@ describe("process_endpoint", () => {
 		expect(result).toEqual(expected);
 	});
 
-	it("should throw an error when fetching space metadata fails", async () => {
+	it("should throw a clear error when the space does not exist or is private", async () => {
 		const app_reference = "hmb/bye_world";
 		const token = "hf_token";
 
-		try {
-			await process_endpoint(app_reference, token);
-		} catch (error) {
-			if (error instanceof Error) {
-				expect(error.message).toEqual(SPACE_METADATA_ERROR_MSG);
-			} else {
-				expect.fail("Error should not be unknown.");
-			}
-		}
+		await expect(process_endpoint(app_reference, token)).rejects.toThrow(
+			SPACE_NOT_FOUND_MSG(app_reference, 404)
+		);
 	});
 
 	it("should return the correct data when app_reference is a valid space domain", async () => {
@@ -671,3 +694,73 @@ describe("map_data_params", () => {
 		);
 	});
 });
+
+describe("transform_api_info", () => {
+	it("defaults parameters and returns to empty arrays when an endpoint entry is malformed", () => {
+		const api_info = {
+			named_endpoints: {
+				// missing `parameters` and `returns`, as returned by some legacy
+				// or misbehaving apps (see issue #10945)
+				"/predict": {}
+			},
+			unnamed_endpoints: {}
+		} as any;
+		const config = {
+			dependencies: [
+				{
+					id: 0,
+					api_name: "predict",
+					inputs: [1],
+					outputs: [2],
+					types: { generator: false, cancel: false }
+				}
+			],
+			components: [
+				{ id: 1, type: "textbox", props: {} },
+				{ id: 2, type: "textbox", props: {} }
+			]
+		} as any;
+
+		const result = transform_api_info(api_info, config, { predict: 0 });
+
+		expect(result.named_endpoints["/predict"].parameters).toEqual([]);
+		expect(result.named_endpoints["/predict"].returns).toEqual([]);
+	});
+
+	it("keeps oauth_token, which submit() needs to decide where a token may be sent", () => {
+		const api_info = {
+			named_endpoints: {
+				"/report": { parameters: [], returns: [], oauth_token: "optional" },
+				"/calculator": { parameters: [], returns: [] }
+			},
+			unnamed_endpoints: {}
+		} as any;
+		const config = {
+			dependencies: [
+				{
+					id: 0,
+					api_name: "report",
+					inputs: [],
+					outputs: [],
+					types: { generator: false, cancel: false }
+				},
+				{
+					id: 1,
+					api_name: "calculator",
+					inputs: [],
+					outputs: [],
+					types: { generator: false, cancel: false }
+				}
+			],
+			components: []
+		} as any;
+
+		const result = transform_api_info(api_info, config, {
+			report: 0,
+			calculator: 1
+		});
+
+		expect(result.named_endpoints["/report"].oauth_token).toBe("optional");
+		expect(result.named_endpoints["/calculator"].oauth_token).toBeUndefined();
+	});
+});

package/src/test/data.test.ts

@@ -97,6 +97,27 @@ describe("walk_and_store_blobs", () => {
 		expect(parts[0].path).toEqual(["0"]);
 	});
 
+	it("should preserve File instances (and their filenames)", async () => {
+		const file = new File(["test data"], "report.txt", {
+			type: "text/plain"
+		});
+		const parts = await walk_and_store_blobs([file]);
+
+		expect(parts).toHaveLength(1);
+		expect(parts[0].blob).toBe(file);
+		expect((parts[0].blob as File).name).toBe("report.txt");
+		expect((parts[0].blob as File).type).toBe("text/plain");
+	});
+
+	it("should preserve the MIME type of Blob instances", async () => {
+		const blob = new Blob(["test data"], { type: "image/png" });
+		const parts = await walk_and_store_blobs([blob]);
+
+		expect(parts).toHaveLength(1);
+		expect(parts[0].blob).toBe(blob);
+		expect(parts[0].blob && parts[0].blob.type).toBe("image/png");
+	});
+
 	it("should handle deep structures", async () => {
 		const image = new Blob([]);
 		const parts = await walk_and_store_blobs({ a: { b: { data: { image } } } });
@@ -371,11 +392,13 @@ describe("handle_file", () => {
 	);
 
 	it.skipIf(IS_NODE)(
-		"should handle a File object and return it as FileData",
+		"should handle a File object and return it unchanged, preserving its name and type",
 		() => {
 			const file = new File(["test image"], "test.png", { type: "image/png" });
-			const result = handle_file(file) as FileData;
-			expect(result).toBeInstanceOf(Blob);
+			const result = handle_file(file) as File;
+			expect(result).toBe(file);
+			expect(result.name).toBe("test.png");
+			expect(result.type).toBe("image/png");
 		}
 	);
 

package/src/test/init.test.ts

@@ -15,7 +15,7 @@ import {
 	response_api_info
 } from "./test_data";
 import { initialise_server } from "./server";
-import { SPACE_METADATA_ERROR_MSG } from "../constants";
+import { SPACE_NOT_FOUND_MSG } from "../constants";
 
 const app_reference = "hmb/hello_world";
 const broken_app_reference = "hmb/bye_world";
@@ -87,12 +87,28 @@ describe("Client class", () => {
 			});
 		});
 
+		test("connecting successfully to a private running app with the deprecated hf_token option", async () => {
+			const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+			const app = await Client.connect("hmb/secret_world", {
+				hf_token: "hf_123"
+			});
+
+			expect(app.config).toEqual({
+				...config_response,
+				root: "https://hmb-secret-world.hf.space"
+			});
+			expect(warn).toHaveBeenCalledWith(
+				expect.stringContaining("`hf_token` option has been renamed")
+			);
+			warn.mockRestore();
+		});
+
 		test("unsuccessfully attempting to connect to a private running app", async () => {
 			await expect(
 				Client.connect("hmb/secret_world", {
 					token: "hf_bad_token"
 				})
-			).rejects.toThrowError(SPACE_METADATA_ERROR_MSG);
+			).rejects.toThrowError(SPACE_NOT_FOUND_MSG("hmb/secret_world", 401));
 		});
 
 		test("viewing the api info of a running app", async () => {
@@ -139,7 +155,9 @@ describe("Client class", () => {
 		test("creating a duplicate of a broken app", async () => {
 			const duplicate = Client.duplicate(broken_app_reference);
 
-			await expect(duplicate).rejects.toThrow(SPACE_METADATA_ERROR_MSG);
+			await expect(duplicate).rejects.toThrow(
+				SPACE_NOT_FOUND_MSG(broken_app_reference, 404)
+			);
 		});
 	});
 

package/src/test/init_helpers.test.ts

@@ -2,12 +2,15 @@ import {
 	resolve_root,
 	get_jwt,
 	determine_protocol,
-	parse_and_set_cookies
+	parse_and_set_cookies,
+	resolve_config,
+	resolve_config_root
 } from "../helpers/init_helpers";
 import { initialise_server } from "./server";
 import { beforeAll, afterEach, afterAll, it, expect, describe } from "vitest";
 import { Client } from "../client";
 import { INVALID_CREDENTIALS_MSG, MISSING_CREDENTIALS_MSG } from "../constants";
+import { config_response } from "./test_data";
 
 let server: Awaited<ReturnType<typeof initialise_server>>;
 
@@ -18,6 +21,96 @@ beforeAll(async () => {
 afterEach(() => server.resetHandlers());
 afterAll(() => server.stop());
 
+describe("resolve_config", () => {
+	it("uses the public protocol and port for a same-host proxy root", () => {
+		expect(
+			resolve_config_root(
+				"http://machine.local:7862/gradio",
+				"https://machine.local:20443/gradio"
+			)
+		).toBe("https://machine.local:20443/gradio");
+	});
+
+	it("keeps the configured origin for a remote root", () => {
+		expect(
+			resolve_config_root(
+				"https://remote.example/gradio",
+				"https://host.example/page"
+			)
+		).toBe("https://remote.example/gradio");
+	});
+
+	it("requests /config without a Content-Type header and with same-origin credentials, so the cross-origin embed fetch is not blocked by CORS", async () => {
+		let captured_init: RequestInit | undefined;
+		const fake_client = {
+			options: {},
+			deep_link: null,
+			fetch: (_url: string, init: RequestInit) => {
+				captured_init = init;
+				return Promise.resolve(
+					new Response(JSON.stringify(config_response), { status: 200 })
+				);
+			}
+		} as unknown as Client;
+
+		await resolve_config.call(fake_client, "https://hmb-hello-world.hf.space");
+
+		expect(captured_init).toBeDefined();
+		const header_names = Object.keys(
+			captured_init?.headers as Record<string, string>
+		).map((h) => h.toLowerCase());
+		expect(header_names).not.toContain("content-type");
+		expect(captured_init?.credentials).toBe("same-origin");
+	});
+
+	const in_browser = typeof window !== "undefined";
+
+	it.skipIf(!in_browser)(
+		"uses the browser origin for a same-host config root behind a proxy",
+		async () => {
+			const page = new URL(window.location.href);
+			const internal_root = `${page.protocol}//${page.hostname}:7862/gradio`;
+			window.gradio_config = {
+				...config_response,
+				root: internal_root
+			};
+			const fake_client = {
+				options: {},
+				deep_link: null
+			} as unknown as Client;
+
+			try {
+				const config = await resolve_config.call(fake_client, internal_root);
+				expect(config?.root).toBe(`${page.origin}/gradio`);
+			} finally {
+				delete (window as Partial<Window>).gradio_config;
+			}
+		}
+	);
+
+	it.skipIf(!in_browser)(
+		"keeps a remote config root when the page and backend hostnames differ",
+		async () => {
+			const remote_root = "https://remote.example/gradio";
+			window.gradio_config = {
+				...config_response,
+				root: remote_root
+			};
+			const fake_client = {
+				options: {},
+				deep_link: null
+			} as unknown as Client;
+
+			try {
+				const config = await resolve_config.call(fake_client, remote_root);
+				expect(config?.root).toBe(remote_root);
+			} finally {
+				delete (window as Partial<Window>).gradio_config;
+			}
+		}
+	);
+});
+
 describe("resolve_root", () => {
 	it('should return the base URL if the root path starts with "http://"', () => {
 		const base_url = "https://huggingface.co";

package/src/test/post_data.test.ts

@@ -1,4 +1,5 @@
 import { Client } from "../client";
+import { post_data } from "../utils/post_data";
 
 import { initialise_server } from "./server";
 import { BROKEN_CONNECTION_MSG } from "../constants";
@@ -46,4 +47,24 @@ describe("post_data", () => {
 		expect(response).toEqual(BROKEN_CONNECTION_MSG);
 		expect(status).toBe(500);
 	});
+
+	it("honors the credentials client option, so authenticated cross-origin deployments can opt back into cookies", async () => {
+		let captured_init: RequestInit | undefined;
+		const fake_client = {
+			options: { credentials: "include" },
+			fetch: (_url: string, init: RequestInit) => {
+				captured_init = init;
+				return Promise.resolve(new Response("{}", { status: 200 }));
+			}
+		} as unknown as Client;
+
+		const [, status] = await post_data.call(
+			fake_client,
+			"https://hmb-hello-world.hf.space/gradio_api/queue/join",
+			{ data: "test" }
+		);
+
+		expect(status).toBe(200);
+		expect(captured_init?.credentials).toBe("include");
+	});
 });

package/src/test/refresh.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, test, vi } from "vitest";
+import { Client } from "../client";
+import type { Config } from "../types";
+
+describe("Client.refresh", () => {
+	test("refreshes from the app root without stripping the current page again", async () => {
+		const client = new Client("https://example.test/app/page");
+		client.config = {
+			root: "https://example.test/app",
+			dependencies: []
+		} as unknown as Config;
+
+		const refreshed_config = {
+			root: "https://example.test/app",
+			api_prefix: "/gradio_api",
+			dependencies: [{ id: 4, api_name: "generate" }]
+		} as unknown as Config;
+		const resolve_config = vi.fn().mockResolvedValue(refreshed_config);
+		Reflect.set(client, "resolve_config", resolve_config);
+		client.view_api = vi.fn().mockResolvedValue({});
+		client.get_url_config = vi.fn().mockReturnValue(refreshed_config);
+
+		await client.refresh();
+
+		expect(resolve_config).toHaveBeenCalledWith(
+			"https://example.test/app",
+			false
+		);
+		expect(client.api_map).toEqual({ generate: 4 });
+	});
+});

package/src/test/submit.test.ts

@@ -151,3 +151,17 @@ describe("submit iterator", () => {
 		expect(error_event).toBeDefined();
 	});
 });
+
+describe("predict error handling", () => {
+	test("predict() rejects its returned promise when the endpoint does not exist, so the error is catchable", async () => {
+		const app = await Client.connect("hmb/hello_world");
+
+		await expect(
+			race_with_timeout(
+				app.predict("nonexistent_endpoint", ["hi"]),
+				1000,
+				"predict() never settled for an unknown endpoint"
+			)
+		).rejects.toThrow('No endpoint matching "nonexistent_endpoint" was found');
+	});
+});

package/src/types.ts

@@ -36,6 +36,8 @@ export interface EndpointInfo<T extends ApiData | JsApiData> {
 	parameters: T[];
 	returns: T[];
 	type?: DependencyTypes;
+	/** Set when the endpoint's function takes a `gr.OAuthToken`. */
+	oauth_token?: "required" | "optional";
 }
 
 export interface ApiInfo<T extends ApiData | JsApiData> {
@@ -301,6 +303,7 @@ export interface Payload {
 	time?: Date;
 	event_data?: unknown;
 	trigger_id?: number | null;
+	oauth_token?: string;
 }
 
 export interface PostResponse {
@@ -323,6 +326,11 @@ export interface DuplicateOptions extends ClientOptions {
 
 export interface ClientOptions {
 	token?: `hf_${string}`;
+	/**
+	 * @deprecated Use `token` instead. Kept as an alias so that code written
+	 * for older versions of the client keeps working.
+	 */
+	hf_token?: `hf_${string}`;
 	status_callback?: SpaceStatusCallback | null;
 	auth?: [string, string] | null;
 	with_null_state?: boolean;
@@ -331,6 +339,14 @@ export interface ClientOptions {
 	query_params?: Record<string, string>;
 	session_hash?: string;
 	cookies?: string;
+	credentials?: RequestCredentials;
+	/**
+	 * A Hugging Face token passed to the app's own code, for endpoints whose
+	 * function takes a `gr.OAuthToken`. Unlike `token`, which only authenticates
+	 * you to the app, this lets the app act on your behalf, so it is sent only to
+	 * endpoints that declare they need it.
+	 */
+	oauth_token?: string;
 }
 
 export interface FileData {

package/src/utils/duplicate.ts

@@ -8,6 +8,7 @@ import { Client } from "../client";
 import { SPACE_METADATA_ERROR_MSG } from "../constants";
 import {
 	get_cookie_header,
+	normalise_token_option,
 	parse_and_set_cookies
 } from "../helpers/init_helpers";
 import { process_endpoint } from "../helpers/api_info";
@@ -16,6 +17,7 @@ export async function duplicate(
 	app_reference: string,
 	options: DuplicateOptions
 ): Promise<Client> {
+	normalise_token_option(options);
 	const { token, private: _private, hardware, timeout, auth } = options;
 
 	if (hardware && !hardware_types.includes(hardware)) {
@@ -35,7 +37,9 @@ export async function duplicate(
 			http_protocol,
 			host,
 			auth,
-			fetch
+			fetch,
+			undefined,
+			options.credentials
 		);
 
 		if (cookie_header) cookies = parse_and_set_cookies(cookie_header);

package/src/utils/post_data.ts

@@ -20,7 +20,7 @@ export async function post_data(
 			method: "POST",
 			body: JSON.stringify(body),
 			headers: { ...headers, ...additional_headers },
-			credentials: "include"
+			credentials: this.options.credentials ?? "same-origin"
 		});
 	} catch (e) {
 		return [{ error: BROKEN_CONNECTION_MSG }, 500];

package/src/utils/predict.ts

@@ -23,29 +23,44 @@ export async function predict<T = unknown>(
 		)!;
 	}
 
-	return new Promise(async (resolve, reject) => {
-		const app = this.submit(endpoint, data, null, null, true);
-		let result: unknown;
+	const app = this.submit(endpoint, data, null, null, true);
+	let result: unknown;
 
-		for await (const message of app) {
-			if (message.type === "data") {
-				if (status_complete) {
-					resolve(result as PredictReturn<T>);
-				}
-				data_returned = true;
-				result = message;
+	for await (const message of app) {
+		if (message.type === "data") {
+			data_returned = true;
+			result = message;
+			if (status_complete) {
+				return result as PredictReturn<T>;
 			}
+		}
 
-			if (message.type === "status") {
-				if (message.stage === "error") reject(message);
-				if (message.stage === "complete") {
-					status_complete = true;
-					// if complete message comes after data, resolve here
-					if (data_returned) {
-						resolve(result as PredictReturn<T>);
-					}
+		if (message.type === "status") {
+			if (message.stage === "error") {
+				// Throw a real `Error` (rather than the raw status object) so that
+				// uncaught failures surface a readable message instead of
+				// crashing Node with `ERR_UNHANDLED_REJECTION ... reason "#<Object>"`.
+				// The status fields are preserved on the error for callers that
+				// inspect them.
+				const { message: error_message, ...status } = message;
+				const error = new Error(
+					(typeof error_message === "string"
+						? error_message
+						: error_message && JSON.stringify(error_message)) ||
+						"An unknown error occurred while making a prediction."
+				);
+				Object.assign(error, status);
+				throw error;
+			}
+			if (message.stage === "complete") {
+				status_complete = true;
+				// if complete message comes after data, resolve here
+				if (data_returned) {
+					return result as PredictReturn<T>;
 				}
 			}
 		}
-	});
+	}
+
+	return result as PredictReturn<T>;
 }

package/src/utils/stream.ts

@@ -62,9 +62,15 @@ export async function open_stream(this: Client): Promise<void> {
 			}
 			let fn: (data: any) => void = event_callbacks[event_id];
 
-			if (typeof window !== "undefined" && typeof document !== "undefined") {
-				// fn(_data); // need to do this to put the event on the end of the event loop, so the browser can refresh between callbacks and not freeze in case of quick generations. See
-				setTimeout(fn, 0, _data); // need to do this to put the event on the end of the event loop, so the browser can refresh between callbacks and not freeze in case of quick generations. See https://github.com/gradio-app/gradio/pull/7055
+			if (
+				typeof window !== "undefined" &&
+				typeof document !== "undefined" &&
+				document.visibilityState !== "hidden"
+			) {
+				// Put the event at the end of the event loop so the browser can refresh
+				// between callbacks and not freeze during quick generations. Hidden tabs
+				// throttle timers, so process those messages immediately instead.
+				setTimeout(fn, 0, _data); // See https://github.com/gradio-app/gradio/pull/7055
 			} else {
 				fn(_data);
 			}
@@ -111,7 +117,14 @@ export function apply_diff_stream(
 		});
 	} else {
 		data.data.forEach((value: any, i: number) => {
-			let new_data = apply_diff(pending_diff_streams[event_id][i], value);
+			// A new output can appear mid-stream if the app was hot-reloaded
+			// while a generator was running; such outputs are diffed against
+			// null on the server, so start from null when we haven't seen it.
+			const prev =
+				i < pending_diff_streams[event_id].length
+					? pending_diff_streams[event_id][i]
+					: null;
+			let new_data = apply_diff(prev, value);
 			pending_diff_streams[event_id][i] = new_data;
 			data.data[i] = new_data;
 		});