Skip to content
Python
13.8 KB
Raw Blame
// The waiter: turns form values into a filled workflow using only what app.json says,
// asks the gateway to clear the GPU when the app's models change, and submits with the Comfy SDK.
import { Comfy } from "@comfyorg/sdk";
import type { App, Input } from "./registry.ts";
import { isFileInput, modelKey } from "./registry.ts";

export type FileValue = { bytes: Uint8Array; name: string; type?: string };
export type Values = Record<string, unknown>;

/** Anything with setInput, so tests can pass a fake instead of the SDK's Workflow. */
export type Settable = { setInput(node: string, field: string, value: unknown): unknown };

export class InputError extends Error {}

function isFileValue(v: unknown): v is FileValue {
  return typeof v === "object" && v !== null && (v as FileValue).bytes instanceof Uint8Array;
}

function coerce(input: Input, raw: unknown): unknown {
  switch (input.type) {
    case "number":
    case "slider":
    case "seed": {
      const n = typeof raw === "number" ? raw : Number(raw);
      if (!Number.isFinite(n)) throw new InputError(`${input.id}: expected a number`);
      if (input.min !== undefined && n < input.min) throw new InputError(`${input.id}: must be ≥ ${input.min}`);
      if (input.max !== undefined && n > input.max) throw new InputError(`${input.id}: must be ≤ ${input.max}`);
      return input.type === "seed" ? Math.trunc(n) : n;
    }
    case "toggle":
      return raw === true || raw === "true" || raw === "1" || raw === "on";
    case "select": {
      if (input.multiple) return picks(input, raw);
      const opts = input.options ?? [];
      const hit = opts.find((o) => o.value === raw || String(o.value) === String(raw));
      if (!hit) throw new InputError(`${input.id}: "${String(raw)}" is not one of the options`);
      return hit.value;
    }
    default:
      return raw;
  }
}

/** A multiple select's value: the picked option values in the order picked, no repeats. The form sends a JSON list. */
function picks(input: Input, raw: unknown): string[] {
  let list: unknown[];
  if (Array.isArray(raw)) list = raw;
  else if (typeof raw === "string" && raw.trim().startsWith("[")) {
    try { list = JSON.parse(raw); } catch { throw new InputError(`${input.id}: expected a list`); }
    if (!Array.isArray(list)) throw new InputError(`${input.id}: expected a list`);
  } else list = raw === "" || raw === null || raw === undefined ? [] : [raw];
  const out: string[] = [];
  for (const r of list) {
    const hit = (input.options ?? []).find((o) => String(o.value) === String(r));
    if (!hit) throw new InputError(`${input.id}: "${String(r)}" is not one of the options`);
    const v = String(hit.value);
    if (v && !out.includes(v)) out.push(v);
  }
  const max = input.multiple?.max;
  if (max && out.length > max) throw new InputError(`${input.id}: at most ${max}`);
  return out;
}

/** The picks of a multiple select as the one string templates and binds get. */
export function joinPicks(input: Input, list: unknown): string {
  const items = Array.isArray(list) ? list.map(String).filter(Boolean) : [];
  if (!items.length) return "";
  const m = input.multiple ?? {};
  return `${m.prefix ?? ""}${items.join(m.join ?? ", ")}${m.suffix ?? ""}`;
}

/** Values as the workflow gets them: multiple selects joined. */
export function textValues(app: App, values: Values): Values {
  const out: Values = { ...values };
  for (const input of app.inputs) if (input.multiple && values[input.id] !== undefined) out[input.id] = joinPicks(input, values[input.id]);
  return out;
}

/** Fill defaults, coerce types, check required fields. File inputs pass through as FileValue. */
export function resolveValues(app: App, values: Values): Values {
  const out: Values = {};
  for (const input of app.inputs) {
    let v = values[input.id];
    // "" is a choice when a select offers it ("Any" in a builder writes nothing); elsewhere it means "use the default"
    const emptyIsOption = input.type === "select" && (Boolean(input.multiple) || (input.options ?? []).some((o) => o.value === ""));
    if (v === undefined || (v === "" && !emptyIsOption)) v = input.default;
    if (input.type === "seed" && (v === undefined || v === -1 || v === "-1")) {
      v = Math.floor(Math.random() * 2 ** 48);
    }
    if (v === undefined) {
      if (input.required || isFileInput(input)) throw new InputError(`${input.id}: required`);
      continue;
    }
    if (isFileInput(input)) {
      if (!isFileValue(v)) throw new InputError(`${input.id}: expected a file`);
      const maxMb = input.limits?.max_mb;
      if (maxMb && v.bytes.byteLength > maxMb * 1e6) throw new InputError(`${input.id}: file is over ${maxMb} MB`);
      out[input.id] = v;
    } else {
      out[input.id] = coerce(input, v);
    }
  }
  return out;
}

export function renderTemplate(template: string, values: Values): string {
  return template
    .replace(/\{([a-z][a-z0-9_]*)\}/g, (_, k: string) => (values[k] === undefined ? "" : String(values[k])))
    .replace(/\s+,/g, ",")
    .replace(/,\s*,+/g, ",")
    .replace(/\s{2,}/g, " ")
    .trim()
    .replace(/,$/, "");
}

/** A value in an option's or preset's `sets`: a string with {placeholders} is filled like a bind template. */
export function setValue(value: unknown, values: Values): unknown {
  return typeof value === "string" && /\{[a-z][a-z0-9_]*\}/.test(value) ? renderTemplate(value, values) : value;
}

/**
 * Apply resolved values and an optional preset to a workflow.
 * `asset` turns a FileValue into whatever the workflow expects (an SDK asset handle).
 */
export function applyInputs(
  app: App,
  values: Values,
  wf: Settable,
  asset: (f: FileValue) => unknown,
  presetId?: string,
): void {
  values = textValues(app, values);
  for (const input of app.inputs) {
    const v = values[input.id];
    if (v === undefined) continue;
    for (const b of input.bind ?? []) {
      if (b.template) wf.setInput(b.node, b.field, renderTemplate(b.template, values));
      else wf.setInput(b.node, b.field, isFileValue(v) ? asset(v) : v);
    }
    // a select option can carry extra fields (the LoRA that goes with a style, an effect's prompt)
    const chosen = input.type === "select" ? input.options?.find((o) => o.value === v) : undefined;
    for (const s of chosen?.sets ?? []) wf.setInput(s.node, s.field, setValue(s.value, values));
  }
  if (presetId) {
    const preset = (app.presets ?? []).find((p) => p.id === presetId);
    if (!preset) throw new InputError(`preset "${presetId}" does not exist in ${app.id}`);
    for (const s of preset.sets) wf.setInput(s.node, s.field, setValue(s.value, values));
  }
}

type NodeError = { type?: string; message?: string; details?: string; extra_info?: { input_name?: string; received_value?: unknown } };
type NodeErrors = Record<string, { class_type?: string; errors?: NodeError[] } | NodeError[]>;

/**
 * Turn ComfyUI's validation errors (relayed by the proxy as details.node_errors) into lines a
 * person can act on. When a loader asks for a model file the backend does not have, say which
 * pack to download. Returns null for errors that are not workflow validation errors.
 */
export function explainSubmitError(app: App, e: unknown): string | null {
  const err = e as { code?: string; details?: { node_errors?: NodeErrors } | null; message?: string };
  if (err?.code !== "invalid_workflow") return null;
  const modelFiles = new Set(app.models.map((m) => m.file.split("/").pop()));
  const lines: string[] = [];
  let missingModel = false;
  for (const [node, entry] of Object.entries(err.details?.node_errors ?? {})) {
    const errors = Array.isArray(entry) ? entry : entry.errors ?? [];
    const cls = Array.isArray(entry) ? "" : entry.class_type ?? "";
    for (const x of errors) {
      const received = x.extra_info?.received_value ?? /'([^']+)' not in/.exec(x.details ?? "")?.[1];
      if (x.type === "value_not_in_list" && typeof received === "string" && modelFiles.has(received)) {
        missingModel = true;
        lines.push(`${cls || "node"} (node ${node}): model file ${received} is not on the backend`);
      } else {
        const detail = (x.details ?? "").replace(/ not in \[.*$/s, " is not one of the allowed values");
        lines.push(`${cls || "node"} (node ${node}): ${x.message ?? x.type ?? "invalid"}${detail ? ` (${detail.slice(0, 200)})` : ""}`);
      }
    }
  }
  if (!lines.length) lines.push(err.message ?? "workflow rejected");
  if (missingModel) {
    lines.push(`Download the "${app.pack}" pack first:  modal run infra/modal_app.py::download --pack ${app.pack}`);
  }
  return `ComfyUI rejected the workflow:\n${lines.map((l) => `  ${l}`).join("\n")}`;
}

export type RunnerOptions = {
  /** Gateway in front of comfy-api-proxy, e.g. https://you--freefield-serve.modal.run */
  baseUrl?: string;
  /** Token the gateway expects; sent by the SDK as a bearer token. */
  token?: string;
  /** Let draft apps run too (default: FREEFIELD_DRAFTS=1). Drafts have a workflow nobody has run on a GPU yet. */
  allowDrafts?: boolean;
  fetch?: typeof fetch;
};

export class Runner {
  readonly baseUrl: string;
  readonly token?: string;
  readonly allowDrafts: boolean;
  private comfy: Comfy;
  private doFetch: typeof fetch;

  constructor(opts: RunnerOptions = {}) {
    this.baseUrl = (opts.baseUrl ?? process.env.COMFY_BASE_URL ?? "").replace(/\/$/, "");
    if (!this.baseUrl) throw new Error("Set COMFY_BASE_URL to the gateway URL");
    this.token = opts.token ?? process.env.FREEFIELD_TOKEN ?? undefined;
    this.allowDrafts = opts.allowDrafts ?? process.env.FREEFIELD_DRAFTS === "1";
    process.env.COMFY_BASE_URL = this.baseUrl; // the SDK reads its base URL from the environment
    this.doFetch = opts.fetch ?? fetch;
    this.comfy = new Comfy({ apiKey: this.token, clientInfo: "freefield", fetch: opts.fetch });
  }

  /**
   * Ask the gateway to make room for this app. It compares the model set with the one
   * loaded last and unloads everything from VRAM when they differ. A backend without the
   * Freefield gateway (a bare comfy-api-proxy, a hosted Comfy API) answers 404 and manages
   * its own memory, so that is not an error.
   */
  async prepare(app: App): Promise<{ freed: boolean; skipped?: boolean }> {
    const res = await this.doFetch(`${this.baseUrl}/freefield/prepare`, {
      method: "POST",
      headers: {
        "content-type": "application/json",
        ...(this.token ? { authorization: `Bearer ${this.token}` } : {}),
      },
      body: JSON.stringify({ app: app.id, models: modelKey(app) }),
    });
    if (res.status === 404 || res.status === 405) return { freed: false, skipped: true };
    if (!res.ok) throw new Error(`gateway /freefield/prepare answered ${res.status}`);
    return (await res.json()) as { freed: boolean };
  }

  async submit(app: App, rawValues: Values, presetId?: string) {
    if (!app.workflowPath) throw new InputError(`${app.id} has no workflow yet`);
    if (app.status !== "ready" && !this.allowDrafts) {
      throw new InputError(`${app.id} is a draft; set FREEFIELD_DRAFTS=1 (or pass --draft) to run it anyway`);
    }
    const values = resolveValues(app, rawValues);
    await this.prepare(app);
    const wf = await this.comfy.workflows.fromFile(app.workflowPath);
    applyInputs(
      app,
      values,
      wf,
      (f) => this.comfy.assets.fromBytes(f.bytes, { filename: f.name, contentType: f.type || undefined }),
      presetId,
    );
    return this.comfy.submit(wf);
  }

  jobs() {
    return this.comfy.jobs;
  }

  /**
   * The job's event stream (GET /api/v2/jobs/{id}/events) read as it comes, frame by frame, without the SDK's
   * job.events(): that one drops any progress frame lower than the last, and comfy-api-proxy's first frames
   * can say 1.0 (history.ts, Meter). Reconnects while the signal is alive; a stream that answers anything
   * but 200 (the job is gone) ends quietly: the poll decides.
   */
  async *frames(jobId: string, signal: AbortSignal): AsyncIterable<Frame> {
    const url = `${this.baseUrl}/api/v2/jobs/${encodeURIComponent(jobId)}/events`;
    const headers = { accept: "text/event-stream", ...(this.token ? { authorization: `Bearer ${this.token}` } : {}) };
    let failures = 0;
    while (!signal.aborted) {
      let res: Response;
      try {
        res = await this.doFetch(url, { headers, signal });
      } catch {
        if (signal.aborted || ++failures > 20) return;
        await new Promise((r) => setTimeout(r, Math.min(10_000, 1000 * failures)));
        continue;
      }
      if (res.status !== 200 || !res.body) return;
      failures = 0;
      try {
        yield* parseSse(res.body);
      } catch {
        if (signal.aborted) return;
      }
      if (!signal.aborted) await new Promise((r) => setTimeout(r, 1000));
    }
  }
}

export type Frame = { event: string; data: Record<string, unknown> };

/** Server-sent events, as the spec reads them: `event:` and `data:` lines, a blank line ends a frame. */
export async function* parseSse(body: ReadableStream<Uint8Array>): AsyncIterable<Frame> {
  const reader = body.getReader();
  const decoder = new TextDecoder();
  let buf = "", event = "message", data: string[] = [];
  const flush = (): Frame | null => {
    const out = data.length ? { event, data: safeJson(data.join("\n")) } : null;
    event = "message"; data = [];
    return out;
  };
  for (;;) {
    const { value, done } = await reader.read();
    buf += done ? "\n\n" : decoder.decode(value, { stream: true });
    let nl: number;
    while ((nl = buf.indexOf("\n")) >= 0) {
      const line = buf.slice(0, nl).replace(/\r$/, "");
      buf = buf.slice(nl + 1);
      if (line === "") { const f = flush(); if (f) yield f; }
      else if (line.startsWith("event:")) event = line.slice(6).trim();
      else if (line.startsWith("data:")) data.push(line.slice(5).replace(/^ /, ""));
    }
    if (done) return;
  }
}

function safeJson(text: string): Record<string, unknown> {
  try {
    const v = JSON.parse(text);
    return v && typeof v === "object" ? (v as Record<string, unknown>) : { value: v };
  } catch {
    return { text };
  }
}