Skip to content

Open source CapCut alternative.

TypeScript
13.3 KB
Raw Blame
// The cloud backend: hosted Cut APIs on the deployment itself, session-authed
// (same-origin cookie; no `u=` param — the server derives the account from
// the session). Routes mirror the engine's JSON shapes under /api/cut-cloud.
// Media bytes ride presigned R2 URLs minted by those routes, not this
// transport.
import { throttleWait } from "../network";
import { observeOperationResponse, operationFailure } from "../operationFailure";
import { UserError } from "../userError";
import {
  DOC_SEQ_HEADER,
  DOC_WRITER_HEADER,
  HTTP_CONFLICT,
  type CutBackend,
  type CutRequestInit,
  type StorageFull,
} from "./types";

const cloudPath = (path: string) => path.replace(/^\/api\/cut\//, "/api/cut-cloud/");

// A headless session's transport: an absolute origin and auth headers folded
// into every cloud call. The page binds nothing — its calls are same-origin
// and the session cookie rides on its own.
let session: { base: string; headers: Record<string, string> } | null = null;
export function bindCloudSession(base: string, headers: Record<string, string>) {
  session = { base: base.replace(/\/$/, ""), headers };
  sessionWriter = newWriter();
}

/** A request on the hosted site as this process's user: same-origin in the
 * page, the bound session's origin and headers in a headless process. */
type CloudSession = { base: string; headers: Record<string, string> } | null;

async function requestWithSession(
  bound: CloudSession,
  path: string,
  init?: RequestInit,
  storageFull: StorageFull = "wall"
): Promise<Response> {
  const headers = new Headers(bound?.headers);
  new Headers(init?.headers).forEach((value, key) => headers.set(key, value));

  // The firewall refuses a burst from one address before any route runs
  // (site/firewall/), so the same request goes again once the window passes.
  // A route that throttles answers JSON with its reason, and that stands.
  for (let attempt = 1; ; attempt++) {
    await firewallGate();
    const res = await fetch((bound?.base ?? "") + path, { ...init, headers });
    const wait = throttleWait(res);
    if (wait === null || !firewallRefusal(res)) {
      return observeOperationResponse(res, storageFull);
    }
    holdFirewall(wait);
    if (attempt > FIREWALL_RETRIES || !resendable(init?.body) || init?.signal?.aborted) {
      return observeOperationResponse(res, storageFull);
    }
    await res.body?.cancel().catch(() => {});
  }
}

// How many times a request the firewall refused goes again.
const FIREWALL_RETRIES = 2;

// The firewall counts one address, so one refusal holds every cloud request
// this process sends until its window passes. Each then goes at a random
// point in a spread after it, half the window wide, so the burst that tripped
// the window does not land in the next one all at once: a 10 s window
// reopens over 10–15 s.
const FIREWALL_SPREAD = 0.5;
let firewallOpensAt = 0;
let firewallWindowMs = 0;

function holdFirewall(waitMs: number) {
  const opensAt = Date.now() + waitMs;
  if (opensAt <= firewallOpensAt) {
    return;
  }
  firewallOpensAt = opensAt;
  firewallWindowMs = waitMs;
}

async function firewallGate() {
  const wait = firewallOpensAt - Date.now();
  if (wait <= 0) {
    return;
  }
  await new Promise((r) => setTimeout(r, wait + Math.random() * firewallWindowMs * FIREWALL_SPREAD));
}

/** Whether a throttle came from the firewall: its refusal is plain text. */
const firewallRefusal = (res: Response) => !/json/i.test(res.headers.get("content-type") ?? "");

/** Whether a request body can be sent a second time: a stream is spent once
 * read, e.g. a piped upload. */
const resendable = (body: RequestInit["body"]) => !(typeof ReadableStream !== "undefined" && body instanceof ReadableStream);

export type CloudUsage = {
  bytes: number;
  /** null = unlimited. */
  quotaBytes: number | null;
  /** Present when the account's Pro ended and it holds more than the free cap:
   * the sweep reclaims storage after `deadline` unless `overBytes` is freed. */
  grace?: { deadline: string; overBytes: number };
};

/** The account's cloud storage usage — cloud-only by construction, so it hits
 * the hosted route directly on the session cookie. */
export async function fetchCloudUsage(): Promise<CloudUsage> {
  const res = await fetch("/api/cut-cloud/usage");
  if (!res.ok) throw new Error(`usage ${res.status}`);
  return (await res.json()) as CloudUsage;
}

export function cloudRequest(path: string, init?: RequestInit, storageFull?: StorageFull): Promise<Response> {
  return requestWithSession(session, path, init, storageFull);
}

/** Capture transport credentials for work that outlives the active project. */
export function captureCloudBackend(): CutBackend {
  const bound = session ? { base: session.base, headers: { ...session.headers } } : null;
  const writer = newWriter();
  return {
    ...cloudBackend,
    fetch: (path, init) =>
      cloudFetch(path, init, (url, options, storageFull) => requestWithSession(bound, url, options, storageFull), writer),
    url: (path) => (bound?.base ?? "") + cloudPath(path),
  };
}

// Cloud project docs are versioned for lost-write detection: GET hands the
// current version out in a header, PUT sends it back as ?v= and gets the
// incremented one in its body. The map lives in the transport so call sites
// keep the engine's unversioned shapes.
const docVersions = new Map<string, string>();

// Versions only grow, so the map keeps the newest it has seen. A GET response
// that lands after a save carries the version from before it — writing that
// back would make the next PUT report a conflict against this same session.
function noteVersion(projectId: string, v: string | number | undefined | null) {
  if (v === undefined || v === null) return;
  const next = Number(v);
  const known = Number(docVersions.get(projectId));
  if (!Number.isFinite(next)) return;
  if (!Number.isFinite(known) || next > known) docVersions.set(projectId, String(next));
}

/** The doc version the transport last saw acknowledged for a project — what a
 * dirty snapshot records as the base its edits were made on top of. */
export function knownDocVersion(projectId: string): string | null {
  return docVersions.get(projectId) ?? null;
}

// A dirty snapshot resumed from disk was edited on top of a specific version.
// Its push must carry that base — not whatever version the open's own GET
// just reported — so a server copy that moved on answers 409 instead of being
// silently overwritten. The pin holds until a PUT settles (ok or conflict);
// transient failures keep it, so the retry still carries the base.
const basePins = new Map<string, string>();

export function pinDocBase(projectId: string, version: string | null) {
  if (version === null) basePins.delete(projectId);
  else basePins.set(projectId, version);
}

// A writer is one transport's identity on the server: the page load, a bound
// headless session, or a captured backend. Each save it sends carries the next
// number in its sequence, so a save that follows its own unacknowledged one
// (the response was lost, the save retried on the old version) applies, and a
// delayed save that its own later one overtook answers 409.
type DocWriter = { id: string; seq: number };
const newWriter = (): DocWriter => ({ id: crypto.randomUUID(), seq: 0 });
let sessionWriter = newWriter();

// One doc PUT on the wire per project: each waits for the one before it and
// reads the version at dispatch. Two saves in flight would carry the same ?v=
// and the later one would 409 against its own session's write.
const putChains = new Map<string, Promise<unknown>>();

// Doc GETs in flight, so a PUT racing the open never goes out unversioned —
// an unversioned PUT is first-save semantics and would apply unconditionally.
const docGets = new Map<string, Promise<void>>();

// /projects/:id only — /projects/folders is the folder collection, not a doc.
const PROJECT_DOC = /^\/api\/cut\/projects\/(?!folders$)([^/?]+)$/;

async function cloudFetch(
  path: string,
  options?: CutRequestInit,
  request = cloudRequest,
  writer = sessionWriter
): Promise<Response> {
  const { observe, storageFull, ...init } = options ?? {};
  const doc = PROJECT_DOC.exec(path);
  const method = (init?.method ?? "GET").toUpperCase();
  if (observe || !doc || (method !== "GET" && method !== "PUT")) return request(cloudPath(path), init, storageFull);
  const projectId = decodeURIComponent(doc[1]);

  if (method === "GET") {
    const req = request(cloudPath(path), init);
    const tracked = req.then(
      (res) => {
        if (res.ok) noteVersion(projectId, res.headers.get("x-cut-doc-version"));
      },
      () => {}
    );
    docGets.set(projectId, tracked);
    void tracked.then(() => {
      if (docGets.get(projectId) === tracked) docGets.delete(projectId);
    });
    return req;
  }

  const prev = putChains.get(projectId) ?? Promise.resolve();
  const run = prev.then(() => putDoc(projectId, path, writer, init, request));
  // The chain survives a failed link; the failure is the caller's to handle.
  putChains.set(projectId, run.catch(() => undefined));
  return run;
}

async function putDoc(
  projectId: string,
  path: string,
  writer: DocWriter,
  init?: RequestInit,
  request = cloudRequest
): Promise<Response> {
  await docGets.get(projectId);
  // A pinned base outranks the map; with neither, an unversioned PUT is the
  // first save and succeeds unconditionally.
  const v = basePins.get(projectId) ?? docVersions.get(projectId);
  const headers = new Headers(init?.headers);
  headers.set(DOC_WRITER_HEADER, writer.id);
  headers.set(DOC_SEQ_HEADER, String(++writer.seq));
  const res = await request(cloudPath(path) + (v ? `?v=${encodeURIComponent(v)}` : ""), { ...init, headers });
  if (res.ok || res.status === HTTP_CONFLICT) basePins.delete(projectId);
  if (res.status === HTTP_CONFLICT) {
    const body = (await res
      .clone()
      .json()
      .catch(() => null)) as { doc?: unknown; version?: number | string } | null;
    noteVersion(projectId, body?.version);
    if (typeof window !== "undefined")
      window.dispatchEvent(
        new CustomEvent("cut-cloud-doc-conflict", {
          detail: { projectId, doc: body?.doc, version: body?.version },
        })
      );
  } else if (res.ok) {
    const body = (await res
      .clone()
      .json()
      .catch(() => null)) as { version?: number | string } | null;
    noteVersion(projectId, body?.version);
  }
  return res;
}

export interface SignedMediaBatch {
  /** fileName -> signed URL. */
  urls: Map<string, string>;
  /** Wall-clock ms when the batch's URLs stop working; null when the mint
   * came back empty or without an expiry. */
  expiresAt: number | null;
}

/** Batch-mint signed R2 GET URLs for a cloud or shared project's media files.
 * Anything the mint misses keeps the /media route, whose 302 serves the same
 * bytes. Network errors and 5xx retry with a short backoff — this runs right
 * after a laptop wakes, when the link may still be coming up. Dispatches
 * through the active backend so the shared driver's token prefix applies;
 * lazy import because ./index imports this module. */
export async function fetchSignedMediaUrls(
  projectId: string,
  fileNames: string[]
): Promise<SignedMediaBatch> {
  const out: SignedMediaBatch = { urls: new Map(), expiresAt: null };
  if (fileNames.length === 0) return out;
  const { apiFetch } = await import("./index");
  for (let attempt = 0; attempt < 3; attempt++) {
    if (attempt > 0) await new Promise((r) => setTimeout(r, 500 * 2 ** (attempt - 1)));
    try {
      const res = await apiFetch("/api/cut/media/presign-get", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ items: fileNames.map((fileName) => ({ projectId, fileName })) }),
      });
      if (res.status >= 500) continue;
      if (!res.ok) return out; // 4xx: the route fallback still streams
      const body = (await res.json()) as {
        urls?: { fileName: string; url: string }[];
        expiresIn?: number;
      };
      for (const u of body.urls ?? []) out.urls.set(u.fileName, u.url);
      if (out.urls.size > 0 && typeof body.expiresIn === "number") {
        out.expiresAt = Date.now() + body.expiresIn * 1000;
      }
      return out;
    } catch {
      // Network down — retry; signed URLs stay an optimization either way.
    }
  }
  return out;
}

type QuotaBody = { error?: string; bytes?: number; quotaBytes?: number } | null | undefined;

/** The storage wall a reply is, coded so the page words it; null for any
 * other reply. The host decides how a quota failure is presented.
 *
 *   throw quotaError(res.status, body) ?? errorFromBody(body, new UserError("upload_failed", "Upload failed."));
 */
export function quotaError(status: number, body: QuotaBody): UserError | null {
  const failure = operationFailure(status, body);
  return failure?.code === "storage_quota_exceeded" ? new UserError(failure.code, failure.message) : null;
}

export const cloudBackend: CutBackend = {
  kind: "cloud",
  caps: {
    importUrl: true, // executed by the render worker
    liveMic: true, // hosted LLM STT (lib/cloudTranscribe.ts)
    transcribe: true, // hosted LLM STT (lib/cloudTranscribe.ts)
    captionAi: true, // hosted Gemini twin (server/cloud/captions.ts)
    revealInFinder: false,
    watch: true, // browser seek + canvas contact sheets (lib/media.ts)
  },
  fetch: (path, init) => cloudFetch(path, init),
  url: (path) => cloudPath(path),
};