@gradio/client 2.4.0 → 2.5.1

package/src/utils/run_history.ts

@@ -0,0 +1,589 @@
+import type { GradioEvent, StatusMessage } from "../types";
+
+// Keyed on the app id, so two different apps served on the same port never
+// share a history. The id is regenerated whenever an app starts, so a restart
+// begins a fresh history and leaves the previous one orphaned; `prune_apps`
+// keeps those from accumulating.
+//
+// The key also carries the logged-in user, because local storage outlives a
+// session: without it, whoever logs into an authenticated app next on this
+// browser would open the previous user's runs.
+const KEY_ROOT = "gradio:run-history:";
+const STORAGE_PREFIX = `${KEY_ROOT}v2:`;
+const REPLAY_PREFIX = `${KEY_ROOT}replay:v2:`;
+const MAX_RUNS = 100;
+const MAX_APPS = 8;
+
+export type AppId = string | number | null | undefined;
+
+/**
+ * Which history to read or write. `Config` satisfies this shape, so callers
+ * that hold one can pass it straight through.
+ */
+export interface RunHistoryScope {
+	app_id?: AppId;
+	/** The authenticated user, when the app uses `auth`. */
+	username?: string | null;
+}
+
+/**
+ * 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
+ * exported function routes through this.
+ */
+function safely<T>(operation: () => T, fallback: T): T {
+	try {
+		return operation();
+	} catch (error) {
+		console.warn("Could not update the run history.", error);
+		return fallback;
+	}
+}
+
+export type RunStatus = "running" | "completed" | "failed";
+
+export interface StoredRunComponent {
+	type: string;
+	component_class_id: string;
+	props: Record<string, unknown>;
+}
+
+export interface StoredRun {
+	id: string;
+	endpoint: string | number;
+	api_name: string;
+	fn_index: number;
+	page: string;
+	inputs: unknown;
+	outputs: unknown | null;
+	input_components?: (StoredRunComponent | null)[];
+	output_components?: (StoredRunComponent | null)[];
+	status: RunStatus;
+	error?: string;
+	started_at: string;
+	/** When the server started running the function, if it reported queueing. */
+	process_started_at?: string;
+	completed_at?: string;
+	/** How long the function itself took, server-reported where available. */
+	duration_ms?: number;
+	/** How long the run waited in the queue before the function started. */
+	queued_ms?: number;
+	/** Whether the run produced its output in chunks, i.e. came from a generator. */
+	streamed?: boolean;
+}
+
+interface StartRunOptions extends RunHistoryScope {
+	endpoint: string | number;
+	api_name: string;
+	fn_index: number;
+	inputs: unknown;
+	input_components?: (StoredRunComponent | null)[];
+	output_components?: (StoredRunComponent | null)[];
+}
+
+/**
+ * The URL of the run history page for an app. `root` never carries a trailing
+ * slash, so it cannot simply be concatenated with the path.
+ */
+export function run_history_url(
+	root: string,
+	api_prefix = "/gradio_api"
+): string {
+	return `${root.replace(/\/+$/, "")}${api_prefix}/runs`;
+}
+
+function storage_key(scope: RunHistoryScope | null | undefined): string | null {
+	if (typeof window === "undefined") return null;
+	const app_id = scope?.app_id;
+	if (app_id === null || app_id === undefined || app_id === "") return null;
+
+	try {
+		if (!window.localStorage) return null;
+		// Encoded so that a username containing the separator cannot be made to
+		// collide with another user's key.
+		const user = scope?.username
+			? `:user:${encodeURIComponent(scope.username)}`
+			: "";
+		return `${STORAGE_PREFIX}${app_id}${user}`;
+	} catch {
+		return null;
+	}
+}
+
+function replay_key(scope: RunHistoryScope | null | undefined): string | null {
+	const key = storage_key(scope);
+	return key ? key.replace(STORAGE_PREFIX, REPLAY_PREFIX) : null;
+}
+
+/** When a run was most recently saved under a key, for deciding what to drop. */
+function last_saved_at(key: string): number {
+	try {
+		const runs = JSON.parse(window.localStorage.getItem(key) || "[]");
+		// Runs are stored newest first.
+		return Array.isArray(runs) && runs.length
+			? Date.parse(runs[0]?.started_at) || 0
+			: 0;
+	} catch {
+		return 0;
+	}
+}
+
+/**
+ * Drops the histories of long-gone app instances. Every restart mints a new app
+ * id, so without this the browser would keep every history an app ever had and
+ * eventually run out of room for the current one.
+ */
+function prune_apps(current_key: string): void {
+	const keys = Object.keys(window.localStorage).filter((key) =>
+		key.startsWith(KEY_ROOT)
+	);
+	const stale = [
+		// Keys written by an older layout can never be read again.
+		...keys.filter(
+			(key) => !key.startsWith(STORAGE_PREFIX) && !key.startsWith(REPLAY_PREFIX)
+		),
+		...keys
+			.filter((key) => key.startsWith(STORAGE_PREFIX) && key !== current_key)
+			.sort((a, b) => last_saved_at(b) - last_saved_at(a))
+			.slice(MAX_APPS - 1)
+	];
+	for (const key of stale) {
+		try {
+			window.localStorage.removeItem(key);
+			window.sessionStorage.removeItem(
+				key.replace(STORAGE_PREFIX, REPLAY_PREFIX)
+			);
+		} catch {
+			// Nothing to do if the browser will not let us clean up.
+		}
+	}
+}
+
+function make_id(): string {
+	if (typeof crypto !== "undefined" && crypto.randomUUID) {
+		return crypto.randomUUID();
+	}
+	return `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+}
+
+function clone_for_storage(value: unknown): unknown {
+	const seen = new WeakSet<object>();
+	try {
+		return JSON.parse(
+			JSON.stringify(value, (_key, item) => {
+				if (typeof item === "bigint") return item.toString();
+				if (typeof item === "object" && item !== null) {
+					if (seen.has(item)) return "[Circular]";
+					seen.add(item);
+				}
+				return item;
+			})
+		);
+	} catch {
+		return "[Unserializable value]";
+	}
+}
+
+function read_run_history_impl(
+	scope: RunHistoryScope | null | undefined
+): StoredRun[] {
+	const key = storage_key(scope);
+	if (!key) return [];
+
+	try {
+		const value = JSON.parse(window.localStorage.getItem(key) || "[]");
+		return Array.isArray(value) ? value : [];
+	} catch {
+		return [];
+	}
+}
+
+function write_run_history(
+	scope: RunHistoryScope | null | undefined,
+	runs: StoredRun[]
+): void {
+	const key = storage_key(scope);
+	if (!key) return;
+
+	let next = runs.slice(0, MAX_RUNS);
+	let pruned = false;
+	while (next.length > 0) {
+		try {
+			window.localStorage.setItem(key, JSON.stringify(next));
+			return;
+		} catch {
+			// Reclaim the space held by app instances that are long gone before
+			// giving up on the oldest runs of the current one.
+			if (!pruned) {
+				pruned = true;
+				prune_apps(key);
+				continue;
+			}
+			next = next.slice(0, -1);
+		}
+	}
+	try {
+		window.localStorage.removeItem(key);
+	} catch {
+		// Run history must never interfere with an app submission.
+	}
+}
+
+function clear_run_history_impl(
+	scope: RunHistoryScope | null | undefined
+): void {
+	const key = storage_key(scope);
+	if (!key) return;
+	try {
+		window.localStorage.removeItem(key);
+	} catch {
+		// Storage may be disabled by the browser.
+	}
+	notify_run_history_change();
+}
+
+function delete_run_history_impl(
+	scope: RunHistoryScope | null | undefined,
+	id: string
+): void {
+	write_run_history(
+		scope,
+		read_run_history_impl(scope).filter((run) => run.id !== id)
+	);
+	notify_run_history_change();
+}
+
+const CHANGE_EVENT = "gradio:run-history-change";
+
+function notify_run_history_change(): void {
+	if (typeof window === "undefined") return;
+	try {
+		window.dispatchEvent(new Event(CHANGE_EVENT));
+	} catch {
+		// Nothing depends on the notification arriving.
+	}
+}
+
+/**
+ * Subscribes to runs being added, deleted or cleared. `storage` covers other
+ * tabs; the custom event covers this one, which `storage` never fires for.
+ * Only counts change, not per-run progress, so listeners stay cheap.
+ *
+ * @returns a function that unsubscribes.
+ */
+function on_run_history_change_impl(listener: () => void): () => void {
+	if (typeof window === "undefined") return () => {};
+	window.addEventListener(CHANGE_EVENT, listener);
+	window.addEventListener("storage", listener);
+	return () => {
+		window.removeEventListener(CHANGE_EVENT, listener);
+		window.removeEventListener("storage", listener);
+	};
+}
+
+function stage_run_history_replay_impl(
+	scope: RunHistoryScope | null | undefined,
+	run: StoredRun
+): void {
+	const key = replay_key(scope);
+	if (!key) return;
+	try {
+		window.sessionStorage.setItem(key, JSON.stringify(run));
+	} catch {
+		// Session storage may be disabled by the browser.
+	}
+}
+
+function consume_run_history_replay_impl(
+	scope: RunHistoryScope | null | undefined
+): StoredRun | null {
+	const key = replay_key(scope);
+	if (!key) return null;
+	try {
+		const value = window.sessionStorage.getItem(key);
+		window.sessionStorage.removeItem(key);
+		return value ? (JSON.parse(value) as StoredRun) : null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * 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 {
+	const key = storage_key(options);
+	if (!key) return null;
+
+	// A new app id means a new key, so clear out the ones left behind before
+	// adding to this one.
+	prune_apps(key);
+
+	const run: StoredRun = {
+		id: make_id(),
+		endpoint: options.endpoint,
+		api_name: options.api_name,
+		fn_index: options.fn_index,
+		page: `${window.location.pathname}${window.location.search}`,
+		inputs: clone_for_storage(options.inputs),
+		outputs: null,
+		...(options.input_components
+			? {
+					input_components: clone_for_storage(
+						options.input_components
+					) as (StoredRunComponent | null)[]
+				}
+			: {}),
+		...(options.output_components
+			? {
+					output_components: clone_for_storage(
+						options.output_components
+					) as (StoredRunComponent | null)[]
+				}
+			: {}),
+		status: "running",
+		started_at: new Date().toISOString()
+	};
+	write_run_history(options, [run, ...read_run_history_impl(options)]);
+	notify_run_history_change();
+	return run.id;
+}
+
+function update_run_inputs_impl(
+	scope: RunHistoryScope | null | undefined,
+	id: string | null,
+	inputs: unknown
+): void {
+	if (!id) return;
+
+	const runs = read_run_history_impl(scope);
+	const run = runs.find((item) => item.id === id);
+	if (!run) return;
+	run.inputs = clone_for_storage(inputs);
+	write_run_history(scope, runs);
+}
+
+function update_run_history_impl(
+	scope: RunHistoryScope | null | undefined,
+	id: string | null,
+	event: GradioEvent
+): void {
+	if (!id) return;
+
+	const runs = read_run_history_impl(scope);
+	const run = runs.find((item) => item.id === id);
+	if (!run) return;
+
+	let finished = false;
+	if (event.type === "data") {
+		run.outputs = clone_for_storage(event.data);
+		deferred_outputs.set(id, run.outputs);
+	} else if (
+		event.type === "status" &&
+		event.original_msg === "process_starts"
+	) {
+		mark_process_start(run, event.time);
+	} else if (
+		event.type === "status" &&
+		(event.stage === "generating" || event.stage === "streaming")
+	) {
+		run.streamed = true;
+	} else if (event.type === "status" && event.stage === "complete") {
+		run.status = "completed";
+		mark_complete(run, event);
+		finished = true;
+	} else if (event.type === "status" && event.stage === "error") {
+		run.status = "failed";
+		run.error =
+			typeof event.message === "string"
+				? event.message
+				: JSON.stringify(event.message || "Unknown error");
+		mark_complete(run, event);
+		finished = true;
+	} else {
+		// Logs, renders and progress updates change nothing worth saving, and
+		// writing serialises every run we hold.
+		return;
+	}
+
+	if (finished) {
+		// Every call re-reads from storage, so a chunk that was held back above is
+		// missing from `run`. Put the last one back before this final write.
+		if (deferred_outputs.has(id)) run.outputs = deferred_outputs.get(id);
+		deferred_outputs.delete(id);
+		last_write.delete(id);
+	} else if (run.streamed) {
+		// A generator emits an event per chunk. Saving each one would stringify
+		// the whole history on the main thread over and over, so write at most
+		// once an interval and let the run's completion flush the rest.
+		const since = Date.now() - (last_write.get(id) ?? 0);
+		if (since < STREAM_WRITE_INTERVAL_MS) return;
+		last_write.set(id, Date.now());
+		deferred_outputs.delete(id);
+	}
+
+	write_run_history(scope, runs);
+}
+
+const STREAM_WRITE_INTERVAL_MS = 500;
+/** When each in-flight streamed run was last written. */
+const last_write = new Map<string, number>();
+/** The newest output of a streamed run that has not been written yet. */
+const deferred_outputs = new Map<string, unknown>();
+
+function mark_process_start(run: StoredRun, time: Date | undefined): void {
+	// The queue tells us when the function actually started, which lets us
+	// report a runtime that excludes however long the run sat in the queue.
+	if (run.process_started_at) return;
+	const started = time || new Date();
+	run.process_started_at = started.toISOString();
+	run.queued_ms = Math.max(0, started.getTime() - Date.parse(run.started_at));
+}
+
+function mark_complete(run: StoredRun, event: StatusMessage): void {
+	const completed = event.time || new Date();
+	run.completed_at = completed.toISOString();
+	// `cache_duration` is how long the function took on the server, which the
+	// queue reports on every completed run (not just cached ones). A generator
+	// reports it per chunk though, so the final value covers only the last one
+	// and the elapsed time is the honest number for a streamed run.
+	const server_duration =
+		!run.streamed &&
+		typeof event.cache_duration === "number" &&
+		event.cache_duration >= 0
+			? event.cache_duration * 1000
+			: null;
+	run.duration_ms =
+		server_duration ??
+		Math.max(
+			0,
+			completed.getTime() - Date.parse(run.process_started_at || run.started_at)
+		);
+}
+
+// Public API. Each of these is a no-op if anything goes wrong.
+
+export function read_run_history(
+	scope: RunHistoryScope | null | undefined
+): StoredRun[] {
+	return safely(() => read_run_history_impl(scope), []);
+}
+
+export function clear_run_history(
+	scope: RunHistoryScope | null | undefined
+): void {
+	safely(() => clear_run_history_impl(scope), undefined);
+}
+
+export function delete_run_history(
+	scope: RunHistoryScope | null | undefined,
+	id: string
+): void {
+	safely(() => delete_run_history_impl(scope, id), undefined);
+}
+
+export function stage_run_history_replay(
+	scope: RunHistoryScope | null | undefined,
+	run: StoredRun
+): void {
+	safely(() => stage_run_history_replay_impl(scope, run), undefined);
+}
+
+export function consume_run_history_replay(
+	scope: RunHistoryScope | null | undefined
+): StoredRun | null {
+	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);
+}
+
+export function update_run_inputs(
+	scope: RunHistoryScope | null | undefined,
+	id: string | null,
+	inputs: unknown
+): void {
+	safely(() => update_run_inputs_impl(scope, id, inputs), undefined);
+}
+
+export function update_run_history(
+	scope: RunHistoryScope | null | undefined,
+	id: string | null,
+	event: GradioEvent
+): void {
+	safely(() => update_run_history_impl(scope, id, event), undefined);
+}
+
+export function on_run_history_change(listener: () => void): () => void {
+	return safely(
+		() => on_run_history_change_impl(() => safely(listener, undefined)),
+		() => {}
+	);
+}

package/src/utils/submit.ts

@@ -29,6 +29,11 @@ import {
 } from "../constants";
 import { apply_diff_stream, close_stream } from "./stream";
 import { Client } from "../client";
+import {
+	start_run_history,
+	update_run_history,
+	update_run_inputs
+} from "./run_history";
 
 export function submit(
 	this: Client,
@@ -73,12 +78,65 @@ export function submit(
 		);
 
 		let resolved_data = map_data_to_params(data, endpoint_info);
-
-		let stream: EventSource | null;
 		let protocol = config.protocol ?? "ws";
 		if (protocol === "ws") {
 			throw new Error(WS_PROTOCOL_MSG);
 		}
+		const history_endpoint =
+			typeof dependency.api_name === "string"
+				? `/${dependency.api_name}`
+				: endpoint;
+		const history_api_name =
+			typeof dependency.api_name === "string"
+				? `/${dependency.api_name}`
+				: `Function ${fn_index}`;
+		// Kept index-aligned with the stored payloads (null for components we
+		// cannot resolve) so every saved value stays matched to its component.
+		const component_metadata = (id: number) => {
+			const component = config.components.find((item) => item.id === id);
+			if (!component) return null;
+			return {
+				type: component.type,
+				component_class_id: component.component_class_id,
+				props: component.props
+			};
+		};
+		// The run history covers the same endpoints the API page documents, which
+		// it selects with exactly this predicate (see `ApiDocs.svelte`). That also
+		// keeps out the dependencies Gradio wires up for itself, since example
+		// loading, flagging and clear buttons are all "undocumented" or "private"
+		// and some of them fire on page load. The trade is that a component whose
+		// UI submits through an undocumented dependency — `gr.ChatInterface` does
+		// — records nothing for its in-app use.
+		const is_documented_endpoint = dependency.api_visibility === "public";
+		// Either side may opt out: the app for everyone who uses it, and this
+		// caller for itself.
+		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_run_id =
+			!history_enabled || !is_documented_endpoint
+				? null
+				: start_run_history({
+						...history_scope,
+						endpoint: history_endpoint,
+						api_name: history_api_name,
+						fn_index,
+						// Aligned to `dependency.inputs` the same way the submitted payload
+						// is, so this placeholder matches the components until the uploaded
+						// files are swapped in by `update_run_inputs` below.
+						inputs: handle_payload(
+							resolved_data,
+							dependency,
+							config.components,
+							"input",
+							true
+						),
+						input_components: dependency.inputs.map(component_metadata),
+						output_components: dependency.outputs.map(component_metadata)
+					});
+
+		let stream: EventSource | null;
 		let event_id_final = "";
 		let event_id_cb: () => string = () => event_id_final;
 
@@ -103,6 +161,7 @@ export function submit(
 
 		// event subscription methods
 		function fire_event(event: GradioEvent): void {
+			update_run_history(history_scope, history_run_id, event);
 			if (all_events || events_to_publish[event.type]) {
 				push_event(event);
 			}
@@ -180,6 +239,7 @@ export function submit(
 				"input",
 				true
 			);
+			update_run_inputs(history_scope, history_run_id, input_data || []);
 			payload = {
 				data: input_data || [],
 				event_data,