@gradio/client 2.3.1 → 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";
@@ -471,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 () => {
@@ -699,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

@@ -3,7 +3,8 @@ import {
 	get_jwt,
 	determine_protocol,
 	parse_and_set_cookies,
-	resolve_config
+	resolve_config,
+	resolve_config_root
 } from "../helpers/init_helpers";
 import { initialise_server } from "./server";
 import { beforeAll, afterEach, afterAll, it, expect, describe } from "vitest";
@@ -21,6 +22,24 @@ 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 = {
@@ -43,6 +62,53 @@ describe("resolve_config", () => {
 		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", () => {

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

@@ -162,8 +162,6 @@ describe("predict error handling", () => {
 				1000,
 				"predict() never settled for an unknown endpoint"
 			)
-		).rejects.toThrow(
-			"There is no endpoint matching that name of fn_index matching that number."
-		);
+		).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;
@@ -332,6 +340,13 @@ export interface ClientOptions {
 	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)) {

package/src/utils/predict.ts

@@ -37,7 +37,20 @@ export async function predict<T = unknown>(
 
 		if (message.type === "status") {
 			if (message.stage === "error") {
-				throw message;
+				// 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;

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;
 		});

package/src/utils/submit.ts

@@ -19,11 +19,13 @@ import {
 } from "../helpers/api_info";
 import {
 	BROKEN_CONNECTION_MSG,
+	NO_API_INFO_MSG,
 	QUEUE_FULL_MSG,
 	SSE_URL,
 	SSE_DATA_URL,
 	RESET_URL,
-	CANCEL_URL
+	CANCEL_URL,
+	WS_PROTOCOL_MSG
 } from "../constants";
 import { apply_diff_stream, close_stream } from "./stream";
 import { Client } from "../client";
@@ -60,7 +62,7 @@ export function submit(
 
 		const that = this;
 
-		if (!api_info) throw new Error("No API found");
+		if (!api_info) throw new Error(NO_API_INFO_MSG);
 		if (!config) throw new Error("Could not resolve app config");
 
 		let { fn_index, endpoint_info, dependency } = get_endpoint_info(
@@ -75,7 +77,7 @@ export function submit(
 		let stream: EventSource | null;
 		let protocol = config.protocol ?? "ws";
 		if (protocol === "ws") {
-			throw new Error("WebSocket protocol is not supported in this version");
+			throw new Error(WS_PROTOCOL_MSG);
 		}
 		let event_id_final = "";
 		let event_id_cb: () => string = () => event_id_final;
@@ -182,7 +184,10 @@ export function submit(
 				data: input_data || [],
 				event_data,
 				fn_index,
-				trigger_id
+				trigger_id,
+				...(options.oauth_token && endpoint_info?.oauth_token
+					? { oauth_token: options.oauth_token }
+					: {})
 			};
 			if (skip_queue(fn_index, config)) {
 				fire_event({
@@ -630,6 +635,22 @@ export function submit(
 			}
 		});
 
+		// Surface internal failures (e.g. malformed payloads or configs) as an
+		// error event instead of leaving the returned iterator hanging forever
+		// with an unhandled promise rejection.
+		job.catch((e) => {
+			fire_event({
+				type: "status",
+				stage: "error",
+				message: e instanceof Error ? e.message : String(e),
+				queue: !skip_queue(fn_index, config),
+				endpoint: _endpoint,
+				fn_index,
+				time: new Date()
+			});
+			close();
+		});
+
 		let done = false;
 		const values: (IteratorResult<GradioEvent> | PromiseLike<never>)[] = [];
 		const resolvers: ((
@@ -735,25 +756,37 @@ function get_endpoint_info(
 } {
 	let fn_index: number;
 	let endpoint_info: EndpointInfo<JsApiData>;
-	let dependency: Dependency;
+	let dependency: Dependency | undefined;
 
 	if (typeof endpoint === "number") {
 		fn_index = endpoint;
 		endpoint_info = api_info.unnamed_endpoints[fn_index];
-		dependency = config.dependencies.find((dep) => dep.id == endpoint)!;
+		dependency = config.dependencies.find((dep) => dep.id == endpoint);
 	} else {
 		const trimmed_endpoint = endpoint.replace(/^\//, "");
 
 		fn_index = api_map[trimmed_endpoint];
-		endpoint_info = api_info.named_endpoints[endpoint.trim()];
+		// named endpoints are keyed with a leading slash in the API info, but
+		// accept endpoint names passed without one (e.g. "predict")
+		endpoint_info =
+			api_info.named_endpoints[endpoint.trim()] ??
+			api_info.named_endpoints[`/${trimmed_endpoint}`];
 		dependency = config.dependencies.find(
 			(dep) => dep.id == api_map[trimmed_endpoint]
-		)!;
+		);
 	}
 
-	if (typeof fn_index !== "number") {
+	if (typeof fn_index !== "number" || !dependency) {
+		const valid_endpoints = config.dependencies
+			.filter((dep) => dep.api_name)
+			.map((dep) => `"/${dep.api_name}"`)
+			.join(", ");
 		throw new Error(
-			"There is no endpoint matching that name of fn_index matching that number."
+			`No endpoint matching ${JSON.stringify(endpoint)} was found. ` +
+				(valid_endpoints
+					? `Valid named endpoints are: ${valid_endpoints}. `
+					: "This app exposes no named endpoints. ") +
+				"An fn_index (number) of an existing dependency can also be used."
 		);
 	}
 	return { fn_index, endpoint_info, dependency };

package/vite.config.ts

@@ -38,7 +38,12 @@ logger.info = (log, options) => {
 };
 export default defineConfig(({ mode }) => {
 	const production = mode === "production";
-	const isBrowserBuild = process.env.BROWSER_BUILD === "true";
+	// Single-file, minified browser bundle served from CDNs at
+	// dist/index.min.js (see https://github.com/gradio-app/gradio/issues/10028)
+	const isCdnBuild = process.env.CDN_BUILD === "true";
+	// a CDN build is always a browser build (guards against CDN_BUILD=true
+	// without BROWSER_BUILD=true emitting es+cjs into the same file name)
+	const isBrowserBuild = process.env.BROWSER_BUILD === "true" || isCdnBuild;
 
 	if (mode === "preview") {
 		return {
@@ -50,15 +55,26 @@ export default defineConfig(({ mode }) => {
 		customLogger: logger,
 		build: {
 			emptyOutDir: false,
+			...(isCdnBuild ? { minify: true } : {}),
 			lib: {
 				entry: "src/index.ts",
-				formats: ["es"],
-				fileName: isBrowserBuild ? `browser` : `index`
+				// the node build also emits a CommonJS bundle (dist/index.cjs)
+				// so that require("@gradio/client") works on all supported
+				// node versions (see https://github.com/gradio-app/gradio/issues/9214)
+				formats: isBrowserBuild ? ["es"] : ["es", "cjs"],
+				fileName: (format) => {
+					if (isCdnBuild) return "index.min.js";
+					if (isBrowserBuild) return "browser.js";
+					return format === "cjs" ? "index.cjs" : "index.js";
+				}
 			},
 			rollupOptions: {
 				input: "src/index.ts",
 				output: {
-					dir: "dist"
+					dir: "dist",
+					// keep the CDN bundle as a single file so the documented
+					// <script type="module"> import works without extra chunks
+					inlineDynamicImports: isCdnBuild
 				}
 			}
 		},

package/dist/__vite-browser-external-DYxpcVy9.js

@@ -1,4 +0,0 @@
-const e = {};
-export {
-  e as default
-};