slidemind 0.3.13 → 0.3.14

package/src/bridge/client/render.mjs

@@ -0,0 +1,317 @@
+// Server-side OOXML render
+//
+// Two protocols, newest first:
+//   1. Render JOBS (preferred): POST creates a job, the CLI polls cheap status
+//      GETs and fetches the result when done. A full deck render routinely
+//      outlives the cloud ingress's ~240s request cap — only short polling
+//      requests survive that reliably, and they carry per-slide progress.
+//   2. Sync render (fallback): one POST held open for the whole render. Kept
+//      for older backends that don't serve /api/cli/capabilities yet.
+
+import { resolveBackendForPres } from "./presentations.mjs";
+import { bridgeFetch, envInt, sleep, backendSupportsRenderJobs, assertCliVersionSupported } from "./transport.mjs";
+
+// Rebuild a job failure into the exact error shape bridgeFetch throws for the
+// sync route, so callers (etag self-heal, error texts) can't tell the
+// protocols apart.
+export function jobFailureError(jobError, label) {
+  const status = jobError?.status ?? 500;
+  const detail = jobError?.error ?? "render_failed";
+  const err = new Error(
+    `slidemind bridge ${status} render job failed for ${label}: ${detail}`,
+  );
+  err.status = status;
+  err.code = detail;
+  err.body = { error: detail, ...(jobError?.extra ?? {}) };
+  return err;
+}
+
+// The render/translate routes exist on two surfaces sharing one contract:
+//   /api/cli/presentations/:presId  — brandId resolved from the pane registry
+//   /api/cli/brands/:brandId        — pane-free (bound deck, window optional)
+export function renderBasePath({ presId, brandId }) {
+  return brandId
+    ? `/api/cli/brands/${encodeURIComponent(brandId)}`
+    : `/api/cli/presentations/${encodeURIComponent(presId)}`;
+}
+
+export async function renderViaSync({ basePath, body, backendURL }) {
+  const res = await bridgeFetch(
+    `${basePath}/render-pptx`,
+    {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      // Server-side OOXML render is a heavy operation — a full deck of richly
+      // composed slides routinely runs well past the 35s default. Treat it like
+      // a mutation: give it a generous default and let env override it.
+      timeoutMs:
+        parseInt(process.env.SLIDEMIND_BRIDGE_RENDER_TIMEOUT_MS || "300000", 10) ||
+        300000,
+    },
+    backendURL,
+  );
+  return res.json(); // { ok, base64, slideCount, warnings, skippedSlides }
+}
+
+export async function renderViaJob({ basePath, label, body, backendURL, onProgress }) {
+  const pollMs = envInt("SLIDEMIND_BRIDGE_RENDER_POLL_MS", 2500);
+  const deadlineMs = envInt("SLIDEMIND_BRIDGE_RENDER_DEADLINE_MS", 900000);
+  const resultTimeoutMs = envInt(
+    "SLIDEMIND_BRIDGE_RENDER_RESULT_TIMEOUT_MS",
+    120000,
+  );
+
+  const createJob = async () => {
+    // Deliberately NOT wrapped in withTransientRetry: its blanket 404 retry
+    // would re-upload a multi-MB slide payload, and creation errors (stale
+    // etag, no CD, unknown presId) are definitive.
+    const res = await bridgeFetch(
+      `${basePath}/render-jobs`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+        timeoutMs:
+          parseInt(process.env.SLIDEMIND_BRIDGE_TIMEOUT_MS || "35000", 10) ||
+          35000,
+      },
+      backendURL,
+    );
+    const data = await res.json();
+    if (!data?.jobId) throw new Error("render-jobs returned no jobId");
+    return data.jobId;
+  };
+
+  let jobId = await createJob();
+  let resubmitted = false;
+  let lastReported = "";
+  const deadline = Date.now() + deadlineMs;
+
+  for (;;) {
+    if (Date.now() > deadline) {
+      const err = new Error(
+        `slidemind render did not finish within ${deadlineMs}ms ` +
+          "(raise SLIDEMIND_BRIDGE_RENDER_DEADLINE_MS for very large decks). " +
+          "The render keeps running server-side — retrying may pick up a warm cache.",
+      );
+      err.code = "bridge_timeout";
+      throw err;
+    }
+    await sleep(pollMs);
+
+    let status;
+    try {
+      const res = await bridgeFetch(
+        `/api/cli/render-jobs/${encodeURIComponent(jobId)}`,
+        { timeoutMs: 15000 },
+        backendURL,
+      );
+      status = await res.json();
+    } catch (err) {
+      // The job record vanished (backend Redis flush/restart) — same recovery
+      // as a lost replica: resubmit once.
+      if (err?.code === "job_not_found") {
+        if (resubmitted) throw jobFailureError({ status: 500, error: "job_lost" }, label);
+        resubmitted = true;
+        onProgress?.({ state: "restarted" });
+        jobId = await createJob();
+        continue;
+      }
+      // Rate-limited poll: honor the window, then resume.
+      if (err?.status === 429) {
+        const retryAfterSec = err?.body?.retryAfterSec;
+        await sleep(Math.min((retryAfterSec || 5) * 1000, 30000));
+        continue;
+      }
+      // Anything else (network blip, 5xx, replica restart) — polling is
+      // idempotent; just poll again until the deadline.
+      continue;
+    }
+
+    if (onProgress) {
+      const snapshot = JSON.stringify([status.state, status.progress]);
+      if (snapshot !== lastReported) {
+        lastReported = snapshot;
+        onProgress({ state: status.state, ...(status.progress ?? {}) });
+      }
+    }
+
+    if (status.state === "failed") {
+      const jobError = status.error ?? { status: 500, error: "render_failed" };
+      // The rendering replica died (deploy, crash, scale-in). Renders are
+      // idempotent — resubmit once before giving up.
+      if (jobError.error === "job_lost" && !resubmitted) {
+        resubmitted = true;
+        onProgress?.({ state: "restarted" });
+        jobId = await createJob();
+        continue;
+      }
+      throw jobFailureError(jobError, label);
+    }
+
+    if (status.state === "done") {
+      // The result may be tens of MB — generous timeout, and a couple of
+      // retries for transient blips (the stored result is re-fetchable).
+      for (let attempt = 0; ; attempt += 1) {
+        try {
+          const res = await bridgeFetch(
+            `/api/cli/render-jobs/${encodeURIComponent(jobId)}/result`,
+            { timeoutMs: resultTimeoutMs },
+            backendURL,
+          );
+          return res.json(); // { ok, base64, slideCount, warnings, skippedSlides }
+        } catch (err) {
+          if (
+            attempt >= 2 ||
+            err?.code === "result_expired" ||
+            err?.code === "job_not_found"
+          ) {
+            throw err;
+          }
+          await sleep(pollMs);
+        }
+      }
+    }
+  }
+}
+
+// Server-side OOXML render: ship authored slide JSX (+ deck-local assets) and
+// get back a native .pptx (base64) rendered against the presentation's own CD.
+// `slides`: { "<file>.jsx": "<jsx source>" }. `deckAssets`: { "assets/<f>": "<base64>" }.
+// `onProgress` (optional) receives `{ state, done?, total?, stage? }` ticks on
+// the job protocol; the sync fallback emits none.
+//
+// Target is EXACTLY ONE of:
+//   presId  — render via the pane registry (any add-in version)
+//   brandId — render via the pane-free brand route (needs backendURL + a
+//             backend advertising `brandRoutes`); `deckName` labels the render.
+export async function renderPptx({
+  presId = null,
+  brandId = null,
+  deckName = null,
+  slides,
+  deckAssets = null,
+  nativeSlides = null,
+  etag = null,
+  sourceGuids = null,
+  conversions = null,
+  reconcile = null,
+  backendURL = null,
+  onProgress = null,
+}) {
+  if (!presId && !brandId) {
+    throw new Error("renderPptx: presId or brandId is required");
+  }
+  const hasSlides = slides && Object.keys(slides).length > 0;
+  const hasNative = nativeSlides && Object.keys(nativeSlides).length > 0;
+  if (!hasSlides && !hasNative) {
+    throw new Error("renderPptx: slides or nativeSlides is required");
+  }
+  let be = backendURL;
+  if (!be) {
+    if (brandId) throw new Error("renderPptx: backendURL is required with brandId");
+    be = await resolveBackendForPres(presId);
+  }
+  // Version floor first: shipping a whole deck to a backend that no longer
+  // speaks this CLI's contract fails deep and confusingly; fail here instead
+  // with the actionable `slidemind update`.
+  await assertCliVersionSupported(be);
+  const basePath = renderBasePath({ presId, brandId });
+  const label = brandId ? (deckName ?? brandId) : presId;
+  const body = { slides: slides ?? {} };
+  if (deckAssets && Object.keys(deckAssets).length > 0) {
+    body.deckAssets = deckAssets;
+  }
+  // Reused native one-slide .pptx (base64), keyed by play-order filename — the
+  // server splices them in by numeric-aware sorted filename (contract #7).
+  if (hasNative) body.nativeSlides = nativeSlides;
+  if (etag) body.etag = etag;
+  // Deck-embedded source: known slide GUIDs (jsx path → sm-<uuid>) so the
+  // server's tag bake keeps identities stable; minted ones ride back as
+  // `sourceGuids` on the response.
+  if (sourceGuids && Object.keys(sourceGuids).length > 0) {
+    body.sourceGuids = sourceGuids;
+  }
+  // Reverse-converted slides (`slidemind adopt`): identity + fidelity evidence
+  // per converted jsx file, so the server can gate the first replacement of a
+  // converted slide against what it originally converted, plus the verbatim
+  // source package whose preserved natives (chart / OLE / SmartArt) it splices
+  // back into the rendered slide. Keyed exactly like `slides`. Additive: a deck
+  // with no conversions sends the same body it always did.
+  if (conversions && Object.keys(conversions).length > 0) {
+    body.conversions = conversions;
+  }
+  // Manual-edit reconcile: for every slide the user edited in PowerPoint since
+  // the last build, the baked baseline projection and the current one, keyed
+  // exactly like `slides`. The server diffs them, folds text edits into the jsx
+  // it renders, and reports the rest — the CLI owns no diff source. Additive: a
+  // deck with no pending edits sends the same body it always did, and the
+  // response's `reconcile` echo is what proves the backend understood it.
+  if (reconcile && Object.keys(reconcile).length > 0) {
+    body.reconcile = reconcile;
+  }
+  // The brand surface has no presId to label the render with — pass the deck
+  // slug so job records/temp dirs stay readable (server-side sanitized).
+  if (brandId && deckName) body.deckName = deckName;
+
+  if (await backendSupportsRenderJobs(be)) {
+    try {
+      return await renderViaJob({ basePath, label, body, backendURL: be, onProgress });
+    } catch (err) {
+      // The backend speaks the protocol but its job store is down — the sync
+      // route renders in-process without Redis, so fall back to it.
+      if (err?.code !== "jobs_unavailable") throw err;
+    }
+  }
+  return renderViaSync({ basePath, body, backendURL: be });
+}
+
+// Translate a deck the CLI captured LOCALLY (the shipped capture engine) into a
+// native .pptx. The slow Chrome work already ran client-side, so this is a fast
+// single synchronous request — the server runs only the IP-sensitive boxes→OOXML
+// half. Returns the same shape as renderPptx ({ ok, base64, slideCount, … }).
+export async function translateDeck({
+  presId = null,
+  brandId = null,
+  deckName = null,
+  captured,
+  nativeSlides = null,
+  etag = null,
+  backendURL = null,
+}) {
+  if (!presId && !brandId) {
+    throw new Error("translateDeck: presId or brandId is required");
+  }
+  if (!captured) throw new Error("translateDeck: captured is required");
+  let be = backendURL;
+  if (!be) {
+    if (brandId) throw new Error("translateDeck: backendURL is required with brandId");
+    be = await resolveBackendForPres(presId);
+  }
+  await assertCliVersionSupported(be);
+  const body = { captured };
+  // Reused native one-slide .pptx (base64), keyed by play-order filename — the
+  // server splices them in alongside the locally-captured JSX slides (contract
+  // #7). The slow capture already ran client-side; native slides are pass-through.
+  if (nativeSlides && Object.keys(nativeSlides).length > 0) {
+    body.nativeSlides = nativeSlides;
+  }
+  if (etag) body.etag = etag;
+  if (brandId && deckName) body.deckName = deckName;
+  const res = await bridgeFetch(
+    `${renderBasePath({ presId, brandId })}/translate`,
+    {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      // The body carries inlined image bytes and the response a base64 .pptx —
+      // bandwidth, not server compute. Give it the render-grade timeout.
+      timeoutMs:
+        parseInt(process.env.SLIDEMIND_BRIDGE_RENDER_TIMEOUT_MS || "300000", 10) ||
+        300000,
+    },
+    be,
+  );
+  return res.json(); // { ok, base64, slideCount, warnings, skippedSlides }
+}