@gradio/client 0.16.0 → 0.17.0

package/src/helpers/spaces.ts

@@ -0,0 +1,192 @@
+import type { SpaceStatusCallback } from "../types";
+
+export async function check_space_status(
+	id: string,
+	type: "subdomain" | "space_name",
+	status_callback: SpaceStatusCallback
+): Promise<void> {
+	let endpoint =
+		type === "subdomain"
+			? `https://huggingface.co/api/spaces/by-subdomain/${id}`
+			: `https://huggingface.co/api/spaces/${id}`;
+	let response;
+	let _status;
+	try {
+		response = await fetch(endpoint);
+		_status = response.status;
+		if (_status !== 200) {
+			throw new Error();
+		}
+		response = await response.json();
+	} catch (e) {
+		status_callback({
+			status: "error",
+			load_status: "error",
+			message: "Could not get space status",
+			detail: "NOT_FOUND"
+		});
+		return;
+	}
+
+	if (!response || _status !== 200) return;
+	const {
+		runtime: { stage },
+		id: space_name
+	} = response;
+
+	switch (stage) {
+		case "STOPPED":
+		case "SLEEPING":
+			status_callback({
+				status: "sleeping",
+				load_status: "pending",
+				message: "Space is asleep. Waking it up...",
+				detail: stage
+			});
+
+			setTimeout(() => {
+				check_space_status(id, type, status_callback);
+			}, 1000); // poll for status
+			break;
+		case "PAUSED":
+			status_callback({
+				status: "paused",
+				load_status: "error",
+				message:
+					"This space has been paused by the author. If you would like to try this demo, consider duplicating the space.",
+				detail: stage,
+				discussions_enabled: await discussions_enabled(space_name)
+			});
+			break;
+		case "RUNNING":
+		case "RUNNING_BUILDING":
+			status_callback({
+				status: "running",
+				load_status: "complete",
+				message: "",
+				detail: stage
+			});
+			break;
+		case "BUILDING":
+			status_callback({
+				status: "building",
+				load_status: "pending",
+				message: "Space is building...",
+				detail: stage
+			});
+
+			setTimeout(() => {
+				check_space_status(id, type, status_callback);
+			}, 1000);
+			break;
+		default:
+			status_callback({
+				status: "space_error",
+				load_status: "error",
+				message: "This space is experiencing an issue.",
+				detail: stage,
+				discussions_enabled: await discussions_enabled(space_name)
+			});
+			break;
+	}
+}
+
+const RE_DISABLED_DISCUSSION =
+	/^(?=[^]*\b[dD]iscussions{0,1}\b)(?=[^]*\b[dD]isabled\b)[^]*$/;
+export async function discussions_enabled(space_id: string): Promise<boolean> {
+	try {
+		const r = await fetch(
+			`https://huggingface.co/api/spaces/${space_id}/discussions`,
+			{
+				method: "HEAD"
+			}
+		);
+		const error = r.headers.get("x-error-message");
+
+		if (error && RE_DISABLED_DISCUSSION.test(error)) return false;
+		return true;
+	} catch (e) {
+		return false;
+	}
+}
+
+export async function get_space_hardware(
+	space_id: string,
+	hf_token?: `hf_${string}` | undefined
+): Promise<(typeof hardware_types)[number]> {
+	const headers: { Authorization?: string } = {};
+	if (hf_token) {
+		headers.Authorization = `Bearer ${hf_token}`;
+	}
+
+	try {
+		const res = await fetch(
+			`https://huggingface.co/api/spaces/${space_id}/runtime`,
+			{ headers }
+		);
+
+		if (res.status !== 200)
+			throw new Error("Space hardware could not be obtained.");
+
+		const { hardware } = await res.json();
+
+		return hardware.current;
+	} catch (e: any) {
+		throw new Error(e.message);
+	}
+}
+
+export async function set_space_timeout(
+	space_id: string,
+	timeout: number,
+	hf_token?: `hf_${string}`
+): Promise<any> {
+	const headers: { Authorization?: string } = {};
+	if (hf_token) {
+		headers.Authorization = `Bearer ${hf_token}`;
+	}
+
+	const body: {
+		seconds?: number;
+	} = {
+		seconds: timeout
+	};
+
+	try {
+		const res = await fetch(
+			`https://huggingface.co/api/spaces/${space_id}/sleeptime`,
+			{
+				method: "POST",
+				headers: { "Content-Type": "application/json", ...headers },
+				body: JSON.stringify(body)
+			}
+		);
+
+		if (res.status !== 200) {
+			throw new Error(
+				"Could not set sleep timeout on duplicated Space. Please visit *ADD HF LINK TO SETTINGS* to set a timeout manually to reduce billing charges."
+			);
+		}
+
+		const response = await res.json();
+		return response;
+	} catch (e: any) {
+		throw new Error(e.message);
+	}
+}
+
+export const hardware_types = [
+	"cpu-basic",
+	"cpu-upgrade",
+	"cpu-xl",
+	"t4-small",
+	"t4-medium",
+	"a10g-small",
+	"a10g-large",
+	"a10g-largex2",
+	"a10g-largex4",
+	"a100-large",
+	"zero-a10g",
+	"h100",
+	"h100x8"
+] as const;

package/src/index.ts

@@ -1,11 +1,17 @@
-export {
-	client,
-	post_data,
-	upload_files,
-	duplicate,
-	api_factory
-} from "./client.js";
-export type { client_return } from "./client.js";
-export type { SpaceStatus } from "./types.js";
+export { Client } from "./client";
 
-export { FileData, upload, prepare_files } from "./upload.js";
+export { predict } from "./utils/predict";
+export { submit } from "./utils/submit";
+export { upload_files } from "./utils/upload_files";
+export { FileData, upload, prepare_files } from "./upload";
+
+export type {
+	SpaceStatus,
+	Status,
+	client_return,
+	UploadResponse
+} from "./types";
+
+// todo: remove in @gradio/client v1.0
+export { client } from "./client";
+export { duplicate } from "./utils/duplicate";

package/src/types.ts

@@ -1,13 +1,130 @@
+// API Data Types
+
+import { hardware_types } from "./helpers/spaces";
+
+export interface ApiData {
+	label: string;
+	type: {
+		type: any;
+		description: string;
+	};
+	component: string;
+	example_input?: any;
+	python_type: { type: string; description: string };
+	serializer: string;
+}
+
+export interface JsApiData {
+	label: string;
+	type: string;
+	description: string;
+	component: string;
+	example_input?: any;
+	serializer: string;
+	python_type: { type: string; description: string };
+}
+
+export interface EndpointInfo<T extends ApiData | JsApiData> {
+	parameters: T[];
+	returns: T[];
+	type?: DependencyTypes;
+}
+
+export interface ApiInfo<T extends ApiData | JsApiData> {
+	named_endpoints: Record<string, EndpointInfo<T>>;
+	unnamed_endpoints: Record<string, EndpointInfo<T>>;
+}
+
+export interface BlobRef {
+	path: string[];
+	type: string | undefined;
+	blob: Blob | false;
+}
+
+export type ParamType = string | Buffer | Record<string, any> | any[];
+
+// Event and Submission Types
+
+type event = <K extends EventType>(
+	eventType: K,
+	listener: EventListener<K>
+) => SubmitReturn;
+
+type predict = (
+	endpoint: string | number,
+	data?: unknown[],
+	event_data?: unknown
+) => Promise<unknown>;
+
+export type client_return = {
+	config: Config | undefined;
+	predict: predict;
+	submit: (
+		endpoint: string | number,
+		data: unknown[],
+		event_data?: unknown,
+		trigger_id?: number | null
+	) => SubmitReturn;
+	component_server: (
+		component_id: number,
+		fn_name: string,
+		data: unknown[]
+	) => any;
+	view_api: (fetch_implementation: typeof fetch) => Promise<ApiInfo<JsApiData>>;
+};
+
+export type SubmitReturn = {
+	on: event;
+	off: event;
+	cancel: () => Promise<void>;
+	destroy: () => void;
+};
+
+// Space Status Types
+
+export type SpaceStatus = SpaceStatusNormal | SpaceStatusError;
+
+export interface SpaceStatusNormal {
+	status: "sleeping" | "running" | "building" | "error" | "stopped";
+	detail:
+		| "SLEEPING"
+		| "RUNNING"
+		| "RUNNING_BUILDING"
+		| "BUILDING"
+		| "NOT_FOUND";
+	load_status: "pending" | "error" | "complete" | "generating";
+	message: string;
+}
+
+export interface SpaceStatusError {
+	status: "space_error" | "paused";
+	detail:
+		| "NO_APP_FILE"
+		| "CONFIG_ERROR"
+		| "BUILD_ERROR"
+		| "RUNTIME_ERROR"
+		| "PAUSED";
+	load_status: "error";
+	message: string;
+	discussions_enabled: boolean;
+}
+
+export type SpaceStatusCallback = (a: SpaceStatus) => void;
+
+// Configuration and Response Types
+// --------------------------------
 export interface Config {
-	auth_required: boolean | undefined;
+	auth_required: boolean;
+	analytics_enabled: boolean;
 	auth_message: string;
 	components: any[];
 	css: string | null;
 	js: string | null;
 	head: string | null;
-	dependencies: any[];
+	dependencies: Dependency[];
 	dev_mode: boolean;
 	enable_queue: boolean;
+	show_error: boolean;
 	layout: any;
 	mode: "blocks" | "interface";
 	root: string;
@@ -16,81 +133,91 @@ export interface Config {
 	title: string;
 	version: string;
 	space_id: string | null;
+	is_space: boolean;
 	is_colab: boolean;
 	show_api: boolean;
 	stylesheets: string[];
 	path: string;
-	protocol?: "sse_v2.1" | "sse_v2" | "sse_v1" | "sse" | "ws";
+	protocol: "sse_v3" | "sse_v2.1" | "sse_v2" | "sse_v1" | "sse" | "ws";
+	max_file_size?: number;
+}
+
+export interface Dependency {
+	targets: [number, string][];
+	inputs: number[];
+	outputs: number[];
+	backend_fn: boolean;
+	js: string | null;
+	scroll_to_output: boolean;
+	trigger: "click" | "load" | string;
+	max_batch_size: number;
+	show_progress: "full" | "minimal" | "hidden";
+	frontend_fn: ((...args: unknown[]) => Promise<unknown[]>) | null;
+	status?: string;
+	queue: boolean | null;
+	every: number | null;
+	batch: boolean;
+	api_name: string | null;
+	cancels: number[];
+	types: DependencyTypes;
+	collects_event_data: boolean;
+	pending_request?: boolean;
+	trigger_after?: number;
+	trigger_only_on_success?: boolean;
+	trigger_mode: "once" | "multiple" | "always_last";
+	final_event: Payload | null;
+	show_api: boolean;
+	zerogpu?: boolean;
+}
+
+export interface DependencyTypes {
+	continuous: boolean;
+	generator: boolean;
 }
 
 export interface Payload {
+	fn_index: number;
 	data: unknown[];
-	fn_index?: number;
-	event_data?: unknown;
 	time?: Date;
+	event_data?: unknown;
+	trigger_id?: number | null;
 }
 
 export interface PostResponse {
 	error?: string;
 	[x: string]: any;
 }
+
 export interface UploadResponse {
 	error?: string;
 	files?: string[];
 }
 
-export interface Status {
-	queue: boolean;
-	code?: string;
-	success?: boolean;
-	stage: "pending" | "error" | "complete" | "generating";
-	broken?: boolean;
-	size?: number;
-	position?: number;
-	eta?: number;
-	message?: string;
-	progress_data?: {
-		progress: number | null;
-		index: number | null;
-		length: number | null;
-		unit: string | null;
-		desc: string | null;
-	}[];
-	time?: Date;
-}
+// Client and File Handling Types
 
-export interface LogMessage {
-	log: string;
-	level: "warning" | "info";
+export interface DuplicateOptions extends ClientOptions {
+	private?: boolean;
+	hardware?: (typeof hardware_types)[number];
+	timeout?: number;
 }
 
-export interface SpaceStatusNormal {
-	status: "sleeping" | "running" | "building" | "error" | "stopped";
-	detail:
-		| "SLEEPING"
-		| "RUNNING"
-		| "RUNNING_BUILDING"
-		| "BUILDING"
-		| "NOT_FOUND";
-	load_status: "pending" | "error" | "complete" | "generating";
-	message: string;
+export interface ClientOptions {
+	hf_token?: `hf_${string}`;
+	status_callback?: SpaceStatusCallback | null;
 }
-export interface SpaceStatusError {
-	status: "space_error" | "paused";
-	detail:
-		| "NO_APP_FILE"
-		| "CONFIG_ERROR"
-		| "BUILD_ERROR"
-		| "RUNTIME_ERROR"
-		| "PAUSED";
-	load_status: "error";
-	message: string;
-	discussions_enabled: boolean;
+
+export interface FileData {
+	name: string;
+	orig_name?: string;
+	size?: number;
+	data: string;
+	blob?: File;
+	is_file?: boolean;
+	mime_type?: string;
+	alt_text?: string;
 }
-export type SpaceStatus = SpaceStatusNormal | SpaceStatusError;
 
-export type status_callback_function = (a: Status) => void;
-export type SpaceStatusCallback = (a: SpaceStatus) => void;
+// Event and Listener Types
 
 export type EventType = "data" | "status" | "log";
 
@@ -107,13 +234,27 @@ export type EventListener<K extends EventType> = (event: Event<K>) => void;
 export type ListenerMap<K extends EventType> = {
 	[P in K]?: EventListener<K>[];
 };
-export interface FileData {
-	name: string;
-	orig_name?: string;
+export interface LogMessage {
+	log: string;
+	level: "warning" | "info";
+}
+
+export interface Status {
+	queue: boolean;
+	code?: string;
+	success?: boolean;
+	stage: "pending" | "error" | "complete" | "generating";
+	broken?: boolean;
 	size?: number;
-	data: string;
-	blob?: File;
-	is_file?: boolean;
-	mime_type?: string;
-	alt_text?: string;
+	position?: number;
+	eta?: number;
+	message?: string;
+	progress_data?: {
+		progress: number | null;
+		index: number | null;
+		length: number | null;
+		unit: string | null;
+		desc: string | null;
+	}[];
+	time?: Date;
 }

package/src/upload.ts

@@ -1,26 +1,34 @@
-import { upload_files } from "./client";
-
-function is_url(str: string): boolean {
-	try {
-		const url = new URL(str);
-		return url.protocol === "http:" || url.protocol === "https:";
-	} catch {
-		return false;
-	}
-}
+import type { UploadResponse } from "./types";
+import { upload_files } from ".";
 
 export async function upload(
 	file_data: FileData[],
-	root: string,
+	root_url: string,
 	upload_id?: string,
-	upload_fn: typeof upload_files = upload_files
+	max_file_size?: number,
+	upload_fn: (
+		root_url: string,
+		files: (Blob | File)[],
+		upload_id?: string
+	) => Promise<UploadResponse> = upload_files
 ): Promise<(FileData | null)[] | null> {
 	let files = (Array.isArray(file_data) ? file_data : [file_data]).map(
 		(file_data) => file_data.blob!
 	);
 
+	const oversized_files = files.filter(
+		(f) => f.size > (max_file_size ?? Infinity)
+	);
+	if (oversized_files.length) {
+		throw new Error(
+			`File size exceeds the maximum allowed size of ${max_file_size} bytes: ${oversized_files
+				.map((f) => f.name)
+				.join(", ")}`
+		);
+	}
+
 	return await Promise.all(
-		await upload_fn(root, files, undefined, upload_id).then(
+		await upload_fn(root_url, files, upload_id).then(
 			async (response: { files?: string[]; error?: string }) => {
 				if (response.error) {
 					throw new Error(response.error);
@@ -30,7 +38,7 @@ export async function upload(
 							const file = new FileData({
 								...file_data[i],
 								path: f,
-								url: root + "/file=" + f
+								url: root_url + "/file=" + f
 							});
 							return file;
 						});
@@ -48,7 +56,7 @@ export async function prepare_files(
 	is_stream?: boolean
 ): Promise<FileData[]> {
 	return files.map(
-		(f, i) =>
+		(f) =>
 			new FileData({
 				path: f.name,
 				orig_name: f.name,

package/src/{client.node-test.ts → utils/client.node-test.ts}

@@ -16,12 +16,13 @@ const image_path = join(
 	"lion.jpg"
 );
 
-import { walk_and_store_blobs, client, handle_blob } from "./client";
+import { walk_and_store_blobs } from "../helpers/data";
+import { Client } from "..";
 
 describe.skip("extract blob parts", () => {
 	test("convert Buffer to Blob", async () => {
 		const image = readFileSync(image_path);
-		await client("gradio/hello_world_main");
+		await Client.connect("gradio/hello_world_main");
 		const parts = walk_and_store_blobs({
 			data: {
 				image
@@ -34,7 +35,7 @@ describe.skip("extract blob parts", () => {
 	test("leave node Blob as Blob", async () => {
 		const image = new Blob([readFileSync(image_path)]);
 
-		await client("gradio/hello_world_main");
+		await Client.connect("gradio/hello_world_main");
 		const parts = walk_and_store_blobs({
 			data: {
 				image
@@ -47,7 +48,7 @@ describe.skip("extract blob parts", () => {
 	test("handle deep structures", async () => {
 		const image = new Blob([readFileSync(image_path)]);
 
-		await client("gradio/hello_world_main");
+		await Client.connect("gradio/hello_world_main");
 		const parts = walk_and_store_blobs({
 			a: {
 				b: {
@@ -64,7 +65,7 @@ describe.skip("extract blob parts", () => {
 	test("handle deep structures with arrays", async () => {
 		const image = new Blob([readFileSync(image_path)]);
 
-		await client("gradio/hello_world_main");
+		await Client.connect("gradio/hello_world_main");
 		const parts = walk_and_store_blobs({
 			a: [
 				{
@@ -87,7 +88,7 @@ describe.skip("extract blob parts", () => {
 	test("handle deep structures with arrays 2", async () => {
 		const image = new Blob([readFileSync(image_path)]);
 
-		await client("gradio/hello_world_main");
+		await Client.connect("gradio/hello_world_main");
 		const obj = {
 			a: [
 				{
@@ -121,7 +122,7 @@ describe("handle_blob", () => {
 	test("handle blobs", async () => {
 		const image = new Blob([readFileSync(image_path)]);
 
-		const app = await client("gradio/hello_world_main");
+		const app = await Client.connect("gradio/hello_world_main");
 		const obj = [
 			{
 				a: [
@@ -136,7 +137,7 @@ describe("handle_blob", () => {
 			}
 		];
 
-		const parts = await handle_blob(app.config.root, obj, undefined);
+		const parts = await app.handle_blob(app.config.root, obj, undefined);
 		//@ts-ignore
 		// assert.isString(parts.data[0].a[0].b[0].data[0][0]);
 	});
@@ -146,7 +147,7 @@ describe.skip("private space", () => {
 	test("can access a private space", async () => {
 		const image = new Blob([readFileSync(image_path)]);
 
-		const app = await client("pngwn/hello_world", {
+		const app = await Client.connect("pngwn/hello_world", {
 			hf_token: "hf_"
 		});
 
@@ -165,7 +166,7 @@ describe.skip("private space", () => {
 			}
 		];
 
-		const parts = await handle_blob(app.config.root, obj, "hf_");
+		const parts = await app.handle_blob(app.config.root, obj, undefined);
 		//@ts-ignore
 		assert.isString(parts.data[0].a[0].b[0].data[0][0]);
 	});