Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

9.7 KB
Raw Blame
import { assertRunwayCatalogModel } from './runwayModelCatalog.js';
/**
 * Runway developer API — the shared task transport for image and video backends.
 *
 * Runway runs every generation as a task: POST the input to
 * `/v1/image_to_video` (or `/v1/text_to_video`), which answers `{ id }`; poll
 * `GET /v1/tasks/{id}` until SUCCEEDED / FAILED / CANCELLED, then download
 * `output[0]` (a signed URL that expires, so it is fetched at once).
 * `DELETE /v1/tasks/{id}` cancels a task that is still running.
 *
 * Same submit/poll/cancel rules as `falQueue.js`: a lost submit response marks
 * the run unsettled (it may still bill), a transient status failure is retried
 * on the poll cadence without resubmitting, and every abandonment path sends
 * the remote cancel once.
 */

import { maintenance } from '../lib/maintenanceAdmission.js';
import { ServerError } from '../lib/errorHandler.js';
import { fetchWithTimeout } from '../lib/fetchWithTimeout.js';
import { openAsBlob } from 'node:fs';
import { basename } from 'node:path';

export const RUNWAY_API_BASE = 'https://api.dev.runwayml.com';
// Every request names the API version it was written against.
export const RUNWAY_API_VERSION = '2024-11-06';

export const RUNWAY_SUBMIT_TIMEOUT_MS = 60_000;
export const RUNWAY_POLL_TIMEOUT_MS = 15_000;
// Runway asks for polling no faster than every 5 seconds.
export const RUNWAY_POLL_INTERVAL_MS = 5000;
export const RUNWAY_MAX_STATUS_RETRIES = 2;

/** The Runway API key: the settings-stored key, else the `RUNWAYML_API_SECRET` env var. */
export function resolveRunwayApiKey(settings) {
  const fromSettings = (settings?.videoGen?.runway?.apiKey || '').trim();
  if (fromSettings) return fromSettings;
  return (process.env.RUNWAYML_API_SECRET || '').trim() || null;
}

const headers = (apiKey, json = false) => ({
  Authorization: `Bearer ${apiKey}`,
  'X-Runway-Version': RUNWAY_API_VERSION,
  ...(json ? { 'Content-Type': 'application/json' } : {}),
});

/** Upload just before dispatch: ephemeral URIs expire after 24h and never enter queue params. */
export async function uploadRunwayVideo({ apiKey, filePath, signal }) {
  signal?.throwIfAborted();
  const file = await openAsBlob(filePath);
  if (file.size < 512 || file.size > 200 * 1024 * 1024) throw new Error('Runway uploads must be 512 bytes–200 MB.');
  const registration = await fetchWithTimeout(`${RUNWAY_API_BASE}/v1/uploads`, {
    method: 'POST', headers: headers(apiKey, true), signal,
    body: JSON.stringify({ filename: basename(filePath), type: 'ephemeral' }),
  }, RUNWAY_SUBMIT_TIMEOUT_MS);
  if (!registration.ok) throw new Error(`Runway upload registration failed: HTTP ${registration.status}`);
  const data = await registration.json();
  if (typeof data.uploadUrl !== 'string' || !data.uploadUrl.startsWith('https://')
    || typeof data.runwayUri !== 'string' || !data.runwayUri.startsWith('runway://')
    || !data.fields || typeof data.fields !== 'object' || Array.isArray(data.fields)
    || Object.values(data.fields).some((value) => typeof value !== 'string')) throw new Error('Invalid Runway upload registration.');
  signal?.throwIfAborted();
  const form = new FormData();
  for (const [key, value] of Object.entries(data.fields)) form.append(key, value);
  form.append('file', file, basename(filePath));
  // The signed storage fields authorize this POST. Never send the API key to storage.
  const uploaded = await fetchWithTimeout(data.uploadUrl, { method: 'POST', body: form, signal }, 10 * 60 * 1000);
  await uploaded.body?.cancel?.();
  if (!uploaded.ok) throw new Error(`Runway media upload failed: HTTP ${uploaded.status}`);
  signal?.throwIfAborted();
  return data.runwayUri;
}

/** A short, single-line reason from a Runway error body (`error`, `issues`), or ''. */
function runwayErrorDetail(payload) {
  if (!payload || typeof payload !== 'object') return '';
  const issues = Array.isArray(payload.issues)
    ? payload.issues.map((issue) => [Array.isArray(issue?.path) ? issue.path.join('.') : null, issue?.message].filter(Boolean).join(': ')).filter(Boolean)
    : [];
  const reason = [typeof payload.error === 'string' ? payload.error : null, ...issues].filter(Boolean).join(' — ');
  return reason.replace(/\s+/g, ' ').trim().slice(0, 300);
}

/** Per-request bookkeeping shared by `cancelRunwayTask` and `awaitRunwayTask`. */
export const createRunwayTaskEntry = (apiKey) => ({
  apiKey, controller: new AbortController(), aborted: false, taskId: null, remoteTerminal: false, cancelPromise: null,
});

/**
 * Best-effort, idempotent cancellation of the remote task. Never rethrows: the
 * local job still finalizes as failed/canceled either way. Never fires once
 * Runway reported a terminal status (DELETE would then delete the finished task).
 */
export async function cancelRunwayTask(entry) {
  if (!entry) return;
  if (!entry.cancelPromise) {
    if (entry.remoteTerminal || !entry.taskId || !entry.apiKey) return;
    entry.cancelPromise = fetchWithTimeout(`${RUNWAY_API_BASE}/v1/tasks/${encodeURIComponent(entry.taskId)}`, {
      method: 'DELETE', headers: headers(entry.apiKey),
    }, RUNWAY_POLL_TIMEOUT_MS)
      .then(async (res) => {
        if (!res.ok && res.status !== 404) console.error(`❌ Runway cancellation request failed: HTTP ${res.status}`);
        await res.body?.cancel?.();
      })
      .catch((err) => console.error(`❌ Runway cancellation request failed: ${err?.message || err}`));
  }
  await entry.cancelPromise;
  // An accepted cancel does not prove the paid render stopped.
  if (!entry.remoteTerminal) maintenance.markCurrentUnsettled();
}

/** Submit one paid generation to a generation endpoint. Resolves to the task id. */
export async function submitRunwayTask({ apiKey, endpoint, body, signal }) {
  await assertRunwayCatalogModel(endpoint, body.model);
  signal?.throwIfAborted(); // a cancel during the catalog load must not start a paid render
  const res = await fetchWithTimeout(`${RUNWAY_API_BASE}/v1/${endpoint}`, {
    method: 'POST', headers: headers(apiKey, true), body: JSON.stringify(body),
  }, RUNWAY_SUBMIT_TIMEOUT_MS).catch((err) => {
    // A lost POST response is not proof the paid task was rejected.
    maintenance.markCurrentUnsettled();
    throw err;
  });
  const payload = await res.json().catch(() => null);
  if (!res.ok || typeof payload?.id !== 'string') {
    if (res.ok || res.status >= 500) maintenance.markCurrentUnsettled();
    const detail = runwayErrorDetail(payload);
    throw new ServerError(`Runway rejected the request: HTTP ${res.status}${detail ? ` — ${detail}` : ''}`, { status: 502, code: 'RUNWAY_SUBMIT_FAILED' });
  }
  return payload.id;
}

async function getRunwayTask({ apiKey, taskId }) {
  const res = await fetchWithTimeout(`${RUNWAY_API_BASE}/v1/tasks/${encodeURIComponent(taskId)}`, {
    headers: headers(apiKey),
  }, RUNWAY_POLL_TIMEOUT_MS);
  if (!res.ok) throw new ServerError(`Runway status check failed: HTTP ${res.status}`, { status: 502, code: 'RUNWAY_STATUS_FAILED' });
  return res.json();
}

/**
 * Poll a submitted task until Runway reports it terminal, the caller cancels it
 * (`entry.aborted`), or `deadline` passes. Resolves to `{ outcome: 'completed',
 * outputUrl }` or `{ outcome: 'canceled' | 'failed', reason? }` and never
 * throws; every abandonment path has already sent the remote cancel.
 * `onStatus(status, progress)` reports each non-terminal status (PENDING,
 * THROTTLED, RUNNING) for the caller's progress wording.
 */
export async function awaitRunwayTask({
  entry, apiKey, deadline, timeoutMs, onPoll = () => {}, onStatus = () => {}, pollIntervalMs = RUNWAY_POLL_INTERVAL_MS, verbatimFailure = false,
}) {
  let statusFailures = 0;
  // A cancel (entry.controller.abort()) ends the wait at once rather than after the next interval.
  const wait = () => new Promise((resolve) => {
    const signal = entry.controller.signal;
    if (signal.aborted) return resolve();
    const done = () => { clearTimeout(timer); signal.removeEventListener('abort', done); resolve(); };
    const timer = setTimeout(done, pollIntervalMs);
    signal.addEventListener('abort', done, { once: true });
  });
  while (Date.now() < deadline) {
    if (entry.aborted) {
      await cancelRunwayTask(entry);
      return { outcome: 'canceled' };
    }
    onPoll();
    let task;
    try {
      task = await getRunwayTask({ apiKey, taskId: entry.taskId });
    } catch (err) {
      statusFailures += 1;
      if (statusFailures > RUNWAY_MAX_STATUS_RETRIES) {
        await cancelRunwayTask(entry);
        return { outcome: 'failed', reason: `Runway status checks failed ${statusFailures} times in a row: ${err?.message || err}` };
      }
      await wait();
      continue;
    }
    statusFailures = 0;
    if (task?.status === 'SUCCEEDED') {
      entry.remoteTerminal = true;
      if (entry.aborted) return { outcome: 'canceled' };
      const outputUrl = Array.isArray(task.output) ? task.output.find((url) => typeof url === 'string' && url.trim()) : null;
      return outputUrl ? { outcome: 'completed', outputUrl } : { outcome: 'failed', reason: 'Runway finished but returned no output URL' };
    }
    if (task?.status === 'FAILED' || task?.status === 'CANCELLED' || task?.status === 'CANCELED') {
      entry.remoteTerminal = true;
      if (entry.aborted) return { outcome: 'canceled' };
      const code = typeof task.failureCode === 'string' ? ` (${task.failureCode})` : '';
      return { outcome: 'failed', reason: verbatimFailure && task.failure ? task.failure : `Runway render failed: ${task.failure || task.status.toLowerCase()}${code}` };
    }
    onStatus(task?.status, Number.isFinite(task?.progress) ? task.progress : null);
    await wait();
  }
  await cancelRunwayTask(entry);
  if (entry.aborted) return { outcome: 'canceled' };
  return { outcome: 'failed', reason: `Runway did not finish within ${Math.round(timeoutMs / 1000)}s` };
}