feat(video-export): service-backed MP4 render + in-app one-click export (#866) (#937)

* feat(video-export): service-backed MP4 render + in-app one-click export (#866)

Adds the last mile of classroom video export: turning the self-contained
Hyperframes project ZIP (#865) into an MP4 via an isolated render service,
one-click in-app.

- render-service/: standalone Node 22 + Chromium + FFmpeg container wrapping
  @hyperframes/producer's library API. Async job model (POST /render -> 202
  jobId, GET poll, GET download, DELETE cancel). Swappable JobStore /
  ArtifactStore seams (in-memory + local-disk now; Redis/S3 + presigned-302
  download later) so it scales horizontally without changing the HTTP contract.
  Concurrency + per-user guards are config knobs.
- App integration: thin Next proxy routes under app/api/export-video/* (forward
  only, no rendering) + capability probe. use-render-video.ts uploads the ZIP,
  polls via runPolledTask, downloads the MP4; shared buildExportZip prefix with
  the existing ZIP path. Export menu gains resolution/fps/quality selectors and
  a progress bar; degrades to ZIP download when RENDER_SERVICE_URL is unset.
- docker-compose: render-service under an opt-in "video-export" profile.
- Entry is main.ts (not server.ts): the producer auto-starts its own server on
  :9847 when the process entry path ends with /src/server.ts.

Verified end-to-end in the container: rendered a real 640s (10.7 min) classroom
ZIP to a valid H.264 720p + AAC MP4 (duration matches source) in ~9.6 min
(~0.9x realtime, 4-worker frame capture). Degrade path, queued-cancel + cleanup,
and per-user 429 guard all exercised. pnpm check / lint / tsc / i18n pass.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(video-export): global render progress store, percent+ETA UI, ring on export button (#866)

Addresses two UX issues found while driving the in-app MP4 export:

1. Progress display was raw and unfriendly (showed producer's English stage
   strings like "Capturing frame 5130/19220") and had no time estimate. Now the
   menu shows only "<percent>% · about <remaining> left". ETA is computed from a
   recent-speed estimate (percent-per-ms over the last sample), EMA-smoothed —
   which tracks the render's non-uniform pace (prep -> frame capture with a
   4->1 worker drop -> encode) far better than a whole-run average, and never
   shows a stale/rising ETA.
2. Switching scenes mid-render unmounted the export menu and lost the progress
   (and reset the local "already rendering" ref, allowing a duplicate submit).
   The whole render lifecycle now lives in a global store
   (lib/store/video-render.ts), so progress survives menu close / scene switch
   and duplicate submits are guarded by status. A persistent CircularProgress
   ring on the export button shows live progress whether or not the menu is open.

Also fixes the progress scale: the producer reports progress as 0..100, but our
HTTP contract (and success path) is 0..1 — the service now normalizes it, so the
client no longer showed "2000%".

- lib/store/video-render.ts: new global store owning submit->poll->download,
  recent-speed ETA, duplicate-submit guard.
- lib/video-export-app/use-render-video.ts: thin facade over the store.
- components/ui/circular-progress.tsx: lightweight SVG progress ring.
- components/stage/{header-controls,video-export-menu}.tsx: ring on the export
  button; menu shows percent + ETA, subscribes to the store.
- render-service/src/render-manager.ts: normalize producer progress 0..100 -> 0..1.
- i18n: percent/ETA strings across all 8 locales (drops the stage-based string).
- render-service/package-lock.json: complete integrity hashes (reproducible npm ci).

Verified: ETA logic checked against the real segmented render curve (worker drop
raises ETA, encode speedup drives it to ~0); progress scale fix confirmed live
against the container (0.2 -> 20%). tsc / lint / prettier / i18n pass.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(video-export): persist render options in the store, not the menu component

Selecting 720p/24fps/draft, switching scenes, and reopening the export menu
showed the defaults again (1080p/30/standard). The selections lived in the
VideoExportMenu component's local state, which reset when the menu unmounted on
a scene switch — the running render still used the chosen options, but the UI
misrepresented them.

Move resolution/fps/quality into the global video-render store (with a
setOptions action). The menu now reads/writes the store, so selections survive
menu close / scene switch, and while a render runs the selectors reflect the
options that render is actually using. startRender() reads options from the
store instead of taking them as an argument.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(video-export): deployment correctness + resource/isolation controls (PR #937 review)

Addresses the blocking findings from wyuc's review. Output fidelity was fine;
these harden deployment and production resource/isolation boundaries.

#1 Compose advertised MP4 but couldn't render in prod:
- Capability now probes the service's /health (checkRenderServiceHealth), so a
  configured-but-absent service reports disabled and the UI degrades to ZIP
  instead of 502-ing.
- RENDER_SERVICE_URL is operator-supplied trusted config, so the proxy no longer
  runs it through the SSRF guard — the one-command `docker compose --profile
  video-export up` now works without globally weakening SSRF via
  ALLOW_LOCAL_NETWORKS. resolveRenderServiceUrl() is now synchronous.
- Client degrades to ZIP on any failed submit (not only 501).

#2 Unbounded upload/queue (ZIP-bomb / DoS):
- unzip.ts bounds the archive via fflate's filter BEFORE decompression: entry
  count, per-entry and total expanded size, and compression ratio.
- Proxy rejects oversized uploads (413) by Content-Length before forwarding.
- RenderManager enforces a global queue-depth cap (RENDER_MAX_QUEUE).
- All limits are env-tunable knobs in config.ts.

#3 Per-user guard was ineffective + admission ran after extraction:
- Identity is derived server-side (client IP) and forwarded as x-openmaic-client;
  the service ignores any client-supplied userId, and the proxy strips it.
- Admission is split into reserve()/submit()/release(): the slot is reserved
  BEFORE extraction, so a rejected caller never triggers a decompression.

Additional risks:
- Per-job wall-clock watchdog (RENDER_JOB_DEADLINE_MS) aborts + fails a hung
  render so it can't hold a slot/scratch forever.
- Download proxy bounds only the time-to-headers, not the body stream, so large
  MP4s over slow links no longer truncate.
- Client cancels the server job (DELETE) when a started render fails/times out.
- Compose puts render-service on an internal:true network (no host/internet
  route), sandboxing the Chromium that runs the uploaded HTML; the export ZIP is
  self-contained so no outbound is needed. README documents the standalone caveat.

Not closing #866: the smoke/golden-render CI acceptance criterion remains a
follow-up (see PR description).

Verified in-container: legal render 202; ZIP-bomb (entry-count + compression-
ratio) rejected 400 before any decompression; per-identity guard 429 with a
spoofed multipart userId ignored; reserve-before-extract leaves no scratch dir
on rejection; watchdog aborts an overrunning job and frees the slot. tsc / lint /
prettier / i18n pass; render-service tsc passes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(video-export): real audio durations + burned-in subtitles (PR #937 review)

Two export-fidelity issues found in wyuc's deeper E2E:

A. Narration was scheduled from estimated durations, cutting audio off mid-
   sentence and advancing the timeline early. The scheduler trusted
   AudioFileRecord.duration (recorded only since #861), so the many existing
   classrooms without it fell back to text-length estimates — measured 4.35s
   average / 10.23s max underestimate across 47 clips. timeline-deps now probes
   the real duration from each narration blob via an off-document <audio>
   (symmetric to the existing video probe), preferring it over the stored
   duration, then the estimate only when no audio asset exists. Everything
   downstream (narration starts, scene/total duration, subtitle cues) re-derives
   from the corrected value in the pure compiler — no compiler change needed.

B. The final MP4 had no subtitles (only H.264+AAC), and the ZIP's SRT/VTT used
   the same estimated boundaries. The emitter now renders a burned-in subtitle
   overlay: one caption box + a hidden div per cue, revealed/hidden by the paused
   GSAP timeline at each cue's start/end (corrected timings from A), so Chromium's
   frame capture bakes them in. The producer has no subtitle track of its own, so
   burn-in is the v1 approach.

Verified: emitter unit tests + snapshot updated (subtitle overlay + toggle
statements, escaped text, hidden-by-default); 82 video-export tests pass incl.
the determinism red-line proxy. Rendered a synthetic subtitle project through the
container and confirmed by pixel analysis that captions appear only within their
cue window (2429 near-white px in the caption band at t=1.5s vs 0 at t=0.05s).
tsc / lint / prettier / i18n pass.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(video-export): subtitle layout + upload/admission hardening (PR #937 review)

Address the three P1 blockers plus actionable P2s from the 6a585c29 review.

P1:
- emit-hyperframes: stack every subtitle cue in one grid cell and toggle
  display:none/inline-block, so inactive cues leave the flow instead of
  pushing the active cue up into the slide title. Adds a multi-cue
  regression test the single-cue snapshot couldn't catch.
- render route + service: cap the upload by actual bytes (capBodyStream),
  not the spoofable Content-Length; the app now streams the multipart body
  through instead of buffering it via formData(). maxUploadBytes is now read.
- render-service: move makeProjectDir() inside the release()-guarded block
  so an ENOENT/ENOSPC no longer permanently leaks the admission slot; mkdir
  the scratch root at startup for the standalone path.

P2:
- config: allow RENDER_MAX_JOBS_PER_USER=0 to disable the per-identity guard.
- timeline-deps: per-probe timeout + bounded concurrency so a stuck audio
  blob can't wedge export in "compiling" forever.
- render route: only trust x-forwarded-for/x-real-ip under
  TRUST_PROXY_HEADERS=true; otherwise all callers share one "direct" bucket.
- render-service: add vitest tests (unzip limits/traversal, reservation
  arithmetic, body cap, config zero-disable) and a dedicated CI job.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(video-export): sync render-service lockfile so `npm ci` passes in CI

The vitest devDependency's transitive esbuild@0.28.1 (and its platform
optionals) were missing from package-lock.json, so the new CI job's
`npm ci` failed with EUSAGE. Regenerated the lockfile from a clean install.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(video-export): dedupe esbuild so render-service `npm ci` installs on linux

@hyperframes/core pins esbuild@0.25.12 exactly, hoisting it to the top and
forcing vite@8 (via vitest) to keep a nested esbuild@0.28.1 copy. npm fails to
flag that nested copy's platform-specific optionals as optional, so `npm ci`
tried to install @esbuild/aix-ppc64 on linux and died with EBADPLATFORM.

Add an `esbuild: 0.28.1` override so a single copy is shared (satisfies tsx
~0.28 and vite ^0.27||^0.28); esbuild is build-time only, so pinning the
producer's bundled build tool is runtime-inert.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(video-export): resource/isolation hardening (PR #937 round-2 review)

Address the round-2 P1/P2/P3 findings (P1#1 lockfile EBADPLATFORM was already
fixed by the earlier esbuild-dedupe commit; CI Render Service job is green).

P1:
- Admission before buffering (#2): the render service now reserve()s the slot
  from the header identity BEFORE parsing/buffering the multipart, so concurrent
  near-cap uploads are bounded by the queue depth, not just each body by the cap.
- Chromium egress lockdown (#3): the producer exposes no browser-arg hook and the
  render shares the internal network with the app, so a container entrypoint
  installs an iptables egress lockdown (drop all outbound except loopback +
  established replies) then drops privileges. Needs CAP_NET_ADMIN (added in
  compose); graceful warn-and-continue if unavailable. The self-contained ZIP
  needs no outbound.
- Default one-render bottleneck (#4): with no trusted proxy every caller is
  "direct", so RENDER_MAX_JOBS_PER_USER=1 throttled the whole deployment. Default
  compose now sets it to 0 and relies on concurrency + global queue caps.
- Non-blocking bounded extraction (#5): unzipSync -> fflate async unzip (worker,
  off the event loop), keeping the pre-decompression filter; default expanded
  ceiling 1GB -> 512MB; a semaphore caps concurrent extractions; compose adds a
  container mem_limit.

P2:
- Raise the app submit timeout/maxDuration (300MB upload can't finish in 60s).
- video-render store: only degrade to ZIP when the service is genuinely
  unavailable (501/unreachable); surface real 429/413/5xx instead of an
  unsolicited download.
- useExportVideo dedupe guard moved to module scope so it survives the menu
  unmounting (no second concurrent ZIP pipeline).
- .env.example: RENDER_SERVICE_URL bypasses SSRF; drop the ALLOW_LOCAL_NETWORKS note.

P3:
- Deadline overruns are marked failed (not cancelled).
- submit() decrements the identity slot if jobs.create throws (no leak).
- CI sets PUPPETEER_SKIP_DOWNLOAD; unzip tests use tiny fixtures + low env limits.

Tests: render-service now 22 tests (unzip limits/traversal, admission incl.
create-leak, body cap, semaphore, config); app video-export suite unchanged.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(video-export): buffer under the extraction permit + fail-closed egress (PR #937 round-3)

Address the two remaining round-3 P1 boundary blockers.

P1#1 — buffering was outside the gate: `bounded.formData()` materialized the
whole uploaded file into memory BEFORE `extractionGate.run()`, so up to
RENDER_MAX_QUEUE (20) admitted bodies could each buffer ~300MB (≈6GB vs the 4g
mem_limit) before the 2-permit gate. Move the entire RAM-heavy section —
formData buffering, file read, and unzip — INSIDE the permit; the queue
reservation still runs first (a rejected caller consumes nothing). Requests
beyond the permit wait with their body unconsumed (socket backpressure), so at
most maxConcurrentExtractions bodies are buffered at once. Refactored main.ts
into a testable `createApp(deps)` factory and added an integration test proving
peak concurrency in the buffering+extraction section never exceeds the permits.

P1#2 — egress lockdown failed open: the entrypoint warned and started normally
if iptables setup failed, so /health stayed green while Chromium could reach the
app. With RENDER_EGRESS_LOCKDOWN=true (default) it now FAILS CLOSED — exits
non-zero if not root, iptables is missing, or the rules don't apply. Operators
accepting an unisolated setup opt out with RENDER_EGRESS_LOCKDOWN=false. Added
scripts/egress-smoke.sh to assert the boundary (lockdown active, loopback works,
new outbound blocked).

Verified: image builds; container boots as `render` with lockdown active and
serves /health; fail-closed exits 1 without CAP_NET_ADMIN; egress smoke passes
(outbound blocked); 23/23 render-service tests + tsc; app tsc + root prettier clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
杨慎 2026-07-20 11:28:34 +08:00 committed by GitHub
parent 34448beb6c
commit 84b1907255
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
57 changed files with 6208 additions and 107 deletions

View File

@ -33,3 +33,7 @@ logs
data
docs
.claude
# isolated MP4 render service — built as its own image (render-service/Dockerfile),
# never part of the main app image.
render-service

View File

@ -273,6 +273,15 @@ DEFAULT_MODEL=
# Required for self-hosted models like Ollama. Do NOT enable on public deployments.
# ALLOW_LOCAL_NETWORKS=true
# Optional MP4 render service (issue #866). When set, the in-app "Export Video"
# menu offers one-click MP4 rendering; when unset, it degrades to downloading a
# project ZIP for local CLI rendering. Point this at the isolated render-service
# container (see render-service/ and the "video-export" docker-compose profile).
# This is operator-supplied trusted config: the app forwards uploads to it
# without the SSRF guard, so a private/compose-network target works WITHOUT
# setting ALLOW_LOCAL_NETWORKS.
# RENDER_SERVICE_URL=http://render-service:9000
# --- Access Control -----------------------------------------------------------
# Set a password to restrict site access. When set, users must enter this code
# before using the app. Leave empty or remove to disable access control.

View File

@ -50,6 +50,38 @@ jobs:
- name: Unit Tests (storage)
run: pnpm --filter @openmaic/storage test
render-service:
name: Render Service (typecheck + tests)
runs-on: ubuntu-latest
# The producer dep bundles puppeteer; skip its Chromium download — the unit
# tests exercise the service's boundaries (unzip, admission, body caps) and
# never launch a browser.
env:
PUPPETEER_SKIP_DOWNLOAD: "true"
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
# render-service is its own npm package (own lockfile, Node-only deps),
# excluded from the root eslint/tsc/pnpm workspace — so it gets its own
# install + quality gate here rather than riding on the `check` job.
cache: npm
cache-dependency-path: render-service/package-lock.json
- name: Install
working-directory: render-service
run: npm ci
- name: TypeScript
working-directory: render-service
run: npm run typecheck
- name: Unit Tests
working-directory: render-service
run: npm test
e2e:
name: E2E Tests
runs-on: ubuntu-latest

View File

@ -248,6 +248,18 @@ cp .env.example .env.local
docker compose up --build
```
### Optional: MP4 Video Export (Render Service)
The "Export Video" menu builds a self-contained [Hyperframes](https://www.npmjs.com/package/@hyperframes/producer) project entirely in the browser. Turning that into an MP4 needs Chromium + FFmpeg on Node 22, so it runs in an isolated `render-service` container rather than the app.
It's opt-in. Start it with the `video-export` compose profile:
```bash
docker compose --profile video-export up --build
```
The app auto-detects the service via `RENDER_SERVICE_URL` (preset in `docker-compose.yml`) and enables one-click MP4 rendering. Without the profile — or when `RENDER_SERVICE_URL` is unset — export degrades to downloading the project ZIP for local CLI rendering. See [`render-service/README.md`](render-service/README.md) for standalone setup and tuning (`RENDER_MAX_CONCURRENCY`, etc.).
### Optional: MinerU (Advanced Document Parsing)
[MinerU](https://github.com/opendatalab/MinerU) provides enhanced parsing for complex tables, formulas, and OCR. You can use the [MinerU official API](https://mineru.net/) or [self-host your own instance](https://opendatalab.github.io/MinerU/quick_start/docker_deployment/).

View File

@ -0,0 +1,16 @@
import { apiSuccess } from '@/lib/server/api-response';
import { checkRenderServiceHealth } from '@/lib/server/render-service';
export const dynamic = 'force-dynamic';
/**
* Report whether one-click MP4 export is available. "Available" means the
* service is configured AND its `/health` responds — so a configured-but-absent
* service (e.g. RENDER_SERVICE_URL set but the container not started) reports
* disabled and the menu shows only "Download ZIP" rather than advertising an
* MP4 export that would then fail. Never leaks the service URL to the client.
*/
export async function GET() {
const enabled = await checkRenderServiceHealth();
return apiSuccess({ enabled });
}

View File

@ -0,0 +1,66 @@
import { NextResponse, type NextRequest } from 'next/server';
import { apiError } from '@/lib/server/api-response';
import { proxyFetch } from '@/lib/server/proxy-fetch';
import { resolveRenderServiceUrl } from '@/lib/server/render-service';
import { createLogger } from '@/lib/logger';
const log = createLogger('ExportVideo Download API');
export const dynamic = 'force-dynamic';
/**
* Stream the rendered MP4 back to the browser.
*
* Uses `redirect: 'manual'` so that if the render service's artifact store
* returns a `302` (a presigned object-storage URL, in a demo-scale deployment)
* we pass that redirect straight through and the browser downloads directly
* from storage — bypassing this proxy. The OSS default (local-disk artifacts)
* streams the bytes through here.
*/
export async function GET(req: NextRequest, context: { params: Promise<{ jobId: string }> }) {
const { jobId } = await context.params;
const resolved = resolveRenderServiceUrl();
if ('error' in resolved) {
return apiError('PROVIDER_DISABLED', 501, 'Render service is not configured');
}
// Bound only the time to obtain the response headers — NOT the body stream.
// A total-duration timeout would truncate a large MP4 over a slow connection,
// so we abort just the initial fetch and clear the timer once headers arrive.
const controller = new AbortController();
const headerTimeout = setTimeout(() => controller.abort(), 30_000);
try {
const upstream = await proxyFetch(
`${resolved.url}/render/${encodeURIComponent(jobId)}/download`,
{ method: 'GET', redirect: 'manual', signal: controller.signal },
);
clearTimeout(headerTimeout);
// Presigned-URL artifact store: hand the redirect to the browser.
if (upstream.status === 302 || upstream.status === 301) {
const location = upstream.headers.get('location');
if (location) return NextResponse.redirect(location, 302);
}
if (!upstream.ok || !upstream.body) {
const status = upstream.status === 404 || upstream.status === 409 ? upstream.status : 502;
return apiError('UPSTREAM_ERROR', status, 'Render output not available');
}
return new NextResponse(upstream.body, {
status: 200,
headers: {
'Content-Type': 'video/mp4',
...(upstream.headers.get('content-length')
? { 'Content-Length': upstream.headers.get('content-length')! }
: {}),
'Content-Disposition': `attachment; filename="${jobId}.mp4"`,
'Cache-Control': 'private, no-store',
},
});
} catch (error) {
clearTimeout(headerTimeout);
log.error(`Failed to download render output ${jobId}:`, error);
return apiError('UPSTREAM_ERROR', 502, 'Failed to reach render service');
}
}

View File

@ -0,0 +1,57 @@
import { type NextRequest } from 'next/server';
import { apiError, apiSuccess } from '@/lib/server/api-response';
import { proxyFetch } from '@/lib/server/proxy-fetch';
import { resolveRenderServiceUrl } from '@/lib/server/render-service';
import { createLogger } from '@/lib/logger';
const log = createLogger('ExportVideo Job API');
export const dynamic = 'force-dynamic';
/** Relay a render job's status. Polled by the client while a render runs. */
export async function GET(req: NextRequest, context: { params: Promise<{ jobId: string }> }) {
const { jobId } = await context.params;
const resolved = resolveRenderServiceUrl();
if ('error' in resolved) {
return apiError('PROVIDER_DISABLED', 501, 'Render service is not configured');
}
try {
const upstream = await proxyFetch(`${resolved.url}/render/${encodeURIComponent(jobId)}`, {
method: 'GET',
signal: AbortSignal.timeout(15_000),
});
const data = (await upstream.json().catch(() => ({}))) as Record<string, unknown>;
if (!upstream.ok) {
const status = upstream.status === 404 ? 404 : 502;
return apiError('UPSTREAM_ERROR', status, 'Render job lookup failed');
}
return apiSuccess({ ...data, pollIntervalMs: 3000 });
} catch (error) {
log.error(`Failed to poll render job ${jobId}:`, error);
return apiError('UPSTREAM_ERROR', 502, 'Failed to reach render service');
}
}
/** Cancel a queued/running render job. */
export async function DELETE(req: NextRequest, context: { params: Promise<{ jobId: string }> }) {
const { jobId } = await context.params;
const resolved = resolveRenderServiceUrl();
if ('error' in resolved) {
return apiError('PROVIDER_DISABLED', 501, 'Render service is not configured');
}
try {
const upstream = await proxyFetch(`${resolved.url}/render/${encodeURIComponent(jobId)}`, {
method: 'DELETE',
signal: AbortSignal.timeout(15_000),
});
if (!upstream.ok && upstream.status !== 404) {
return apiError('UPSTREAM_ERROR', 502, 'Failed to cancel render job');
}
return apiSuccess({ cancelled: true });
} catch (error) {
log.error(`Failed to cancel render job ${jobId}:`, error);
return apiError('UPSTREAM_ERROR', 502, 'Failed to reach render service');
}
}

View File

@ -0,0 +1,113 @@
import { type NextRequest } from 'next/server';
import { apiError, apiSuccess } from '@/lib/server/api-response';
import { proxyFetch } from '@/lib/server/proxy-fetch';
import { resolveRenderServiceUrl } from '@/lib/server/render-service';
import { capBodyStream } from '@/lib/server/capped-stream';
import { createLogger } from '@/lib/logger';
const log = createLogger('ExportVideo Render API');
// Only forwards the upload to the isolated render service; the render itself
// happens there, so this route stays lightweight despite large ZIP bodies. The
// budget must cover *uploading* up to MAX_UPLOAD_BYTES over a slow link (a
// 300 MB body needs ~40 Mbps to finish in 60s), not the render — so it's sized
// for the transfer, well above the old 60s.
export const maxDuration = 300;
/** Reject uploads larger than this (compressed ZIP bytes), enforced on real bytes. */
const MAX_UPLOAD_BYTES = 300 * 1024 * 1024;
/** Upload-forwarding budget. Covers a large body over a slow link; the render is async. */
const SUBMIT_TIMEOUT_MS = 300_000;
/**
* Derive a client identity for the render service's per-identity guard.
*
* `x-forwarded-for` / `x-real-ip` are only trustworthy when a trusted reverse
* proxy sets them; if the app is exposed directly (as the default Compose does),
* a client can rotate them to defeat the guard. So we only honor them when
* `TRUST_PROXY_HEADERS=true` is set by the operator (who then must ensure a real
* proxy overwrites the headers). Otherwise every caller collapses to a single
* `direct` bucket — a conservative shared limit rather than a spoofable one.
*/
function clientIdentity(req: NextRequest): string {
if (process.env.TRUST_PROXY_HEADERS !== 'true') return 'direct';
const fwd = req.headers.get('x-forwarded-for');
if (fwd) return fwd.split(',')[0].trim() || 'anonymous';
return req.headers.get('x-real-ip')?.trim() || 'anonymous';
}
/**
* Submit an export ZIP for MP4 rendering. Streams the multipart body straight
* to the render service (no `formData()` buffering here) and relays its
* `202 { jobId }`. Returns 501 when the service is not configured so the client
* can degrade to a local ZIP download.
*/
export async function POST(req: NextRequest) {
const resolved = resolveRenderServiceUrl();
if ('error' in resolved) {
return apiError('PROVIDER_DISABLED', 501, 'Render service is not configured');
}
// Fast-path reject an oversized body by its declared length. This is only a
// courtesy 413 for honest clients — `Content-Length` is client-supplied and
// omitted on chunked uploads, so the real bound is the byte-counting cap on
// the stream below (belt-and-suspenders with the service's own archive guards).
const contentLength = Number(req.headers.get('content-length') ?? '0');
if (Number.isFinite(contentLength) && contentLength > MAX_UPLOAD_BYTES) {
return apiError('INVALID_REQUEST', 413, 'Export archive is too large');
}
const contentType = req.headers.get('content-type') ?? '';
if (!contentType.includes('multipart/form-data') || !req.body) {
return apiError('INVALID_REQUEST', 400, 'Expected multipart/form-data');
}
// Forward the raw multipart body verbatim, bounded to MAX_UPLOAD_BYTES of
// actual bytes. We deliberately do NOT parse it: the render service derives
// identity from the header below and ignores any multipart `userId`, so
// there's nothing to strip — and re-parsing would defeat the streaming bound.
const capped = capBodyStream(req.body, MAX_UPLOAD_BYTES);
try {
// Long enough for the upload of a multi-MB ZIP; the render is async.
const upstream = await proxyFetch(`${resolved.url}/render`, {
method: 'POST',
body: capped.stream,
// duplex is required to send a streaming request body via fetch.
duplex: 'half',
headers: {
'content-type': contentType,
'x-openmaic-client': clientIdentity(req),
},
signal: AbortSignal.timeout(SUBMIT_TIMEOUT_MS),
} as RequestInit);
const data = (await upstream.json().catch(() => ({}))) as Record<string, unknown>;
if (!upstream.ok) {
const detail = typeof data.error === 'string' ? data.error : upstream.statusText;
const status = upstream.status === 429 ? 429 : upstream.status === 413 ? 413 : 502;
const code =
upstream.status === 429
? 'RATE_LIMITED'
: upstream.status === 413
? 'INVALID_REQUEST'
: 'UPSTREAM_ERROR';
return apiError(code, status, 'Render service rejected the request', detail);
}
return apiSuccess({ jobId: data.jobId, pollIntervalMs: 3000 }, 202);
} catch (error) {
// A cap trip aborts the forwarded stream, surfacing here as a fetch error.
if (capped.exceeded()) {
return apiError('INVALID_REQUEST', 413, 'Export archive is too large');
}
log.error('Failed to submit render job:', error);
return apiError(
'UPSTREAM_ERROR',
502,
'Failed to reach render service',
error instanceof Error ? error.message : String(error),
);
}
}

View File

@ -5,7 +5,6 @@ import {
Archive,
Download,
FileDown,
Film,
Loader2,
Monitor,
Moon,
@ -20,8 +19,10 @@ import { useStageStore } from '@/lib/store';
import { useMediaGenerationStore } from '@/lib/store/media-generation';
import { useExportPPTX } from '@/lib/export/use-export-pptx';
import { useExportClassroom } from '@/lib/export/use-export-classroom';
import { useExportVideo, VIDEO_RESOLUTIONS } from '@/lib/video-export-app/use-export-video';
import { isVideoExportEnabled } from '@/lib/config/feature-flags';
import { useVideoRenderStore } from '@/lib/store/video-render';
import { CircularProgress } from '@/components/ui/circular-progress';
import { VideoExportMenu } from './video-export-menu';
import { LanguageSwitcher } from '../language-switcher';
import { SettingsDialog } from '../settings';
import {
@ -80,8 +81,13 @@ export function HeaderControls({
const mediaTasks = useMediaGenerationStore((s) => s.tasks);
const { exporting: isExporting, exportPPTX, exportResourcePack } = useExportPPTX();
const { exporting: isExportingZip, exportClassroomZip } = useExportClassroom();
const { exporting: isExportingVideo, exportVideo } = useExportVideo();
const videoExportEnabled = isVideoExportEnabled();
// Video render lives in a global store so its progress ring stays on the
// export button even after the menu closes / scenes switch mid-render.
const videoRendering = useVideoRenderStore(
(s) => s.status === 'compiling' || s.status === 'rendering',
);
const videoRenderPercent = useVideoRenderStore((s) => s.percent);
const [exportMenuOpen, setExportMenuOpen] = useState(false);
const exportRef = useRef<HTMLDivElement>(null);
@ -245,28 +251,32 @@ export function HeaderControls({
<div className="relative" ref={exportRef}>
<button
onClick={() => {
if (canExport && !isExporting && !isExportingZip && !isExportingVideo) {
if (canExport && !isExporting && !isExportingZip) {
setExportMenuOpen(!exportMenuOpen);
}
}}
disabled={!canExport || isExporting || isExportingZip || isExportingVideo}
disabled={!canExport || isExporting || isExportingZip}
title={
canExport
? isExporting || isExportingZip || isExportingVideo
? isExporting || isExportingZip
? t('export.exporting')
: t('export.pptx')
: t('share.notReady')
}
className={cn(
'shrink-0 p-2 rounded-full transition-all',
canExport && !isExporting && !isExportingZip && !isExportingVideo
canExport && !isExporting && !isExportingZip
? 'text-gray-400 dark:text-gray-500 hover:bg-white dark:hover:bg-gray-700 hover:text-gray-800 dark:hover:text-gray-200 hover:shadow-sm'
: 'text-gray-300 dark:text-gray-600 cursor-not-allowed opacity-50',
)}
aria-label={t('export.pptx')}
>
{isExporting || isExportingZip || isExportingVideo ? (
{isExporting || isExportingZip ? (
<Loader2 className="w-4 h-4 animate-spin" />
) : videoRendering ? (
// Persistent ring: video render runs in the background; keep it
// visible on the button whether or not the menu is open.
<CircularProgress value={videoRenderPercent} size={20} className="text-primary" />
) : (
<Download className="w-4 h-4" />
)}
@ -314,37 +324,7 @@ export function HeaderControls({
</div>
</div>
</button>
{videoExportEnabled && (
<>
<div className="border-t border-gray-200 dark:border-gray-700" />
<div className="px-4 pt-2.5 pb-1 flex items-center gap-2.5 text-sm">
<Film className="w-4 h-4 text-gray-400 shrink-0" />
<div>
<div>{t('export.video')}</div>
<div className="text-[11px] text-gray-400 dark:text-gray-500">
{t('export.videoDesc')}
</div>
</div>
</div>
<div className="px-4 pb-2.5 flex gap-1.5">
{(Object.keys(VIDEO_RESOLUTIONS) as (keyof typeof VIDEO_RESOLUTIONS)[]).map(
(res) => (
<button
key={res}
onClick={() => {
setExportMenuOpen(false);
exportVideo(res);
}}
disabled={isExportingVideo}
className="flex-1 px-2 py-1.5 text-xs rounded-md border border-gray-200 dark:border-gray-700 hover:bg-gray-100 dark:hover:bg-gray-700 transition-colors disabled:opacity-50"
>
{res === '4k' ? '4K' : res}
</button>
),
)}
</div>
</>
)}
{videoExportEnabled && <VideoExportMenu onClose={() => setExportMenuOpen(false)} />}
</div>
)}
</div>

View File

@ -0,0 +1,199 @@
'use client';
/**
* Video-export section of the header export menu.
*
* Two paths sharing the same project ZIP:
* - **Render MP4** (when the render service is configured) — uploads the ZIP to
* the service, polls the async job, downloads the finished MP4. Exposes
* resolution / fps / quality selectors and a live progress bar.
* - **Download ZIP** — the always-available degrade path: saves the
* self-contained project for local CLI rendering.
*
* Capability is probed on mount (`/api/export-video/capability`) so the MP4
* action only appears when it will actually work; otherwise only the ZIP
* download shows, with a short hint.
*/
import { useEffect, useState } from 'react';
import { Film, Loader2 } from 'lucide-react';
import { Progress } from '@/components/ui/progress';
import { useI18n } from '@/lib/hooks/use-i18n';
import { cn } from '@/lib/utils';
import { useExportVideo } from '@/lib/video-export-app/use-export-video';
import { useRenderVideo } from '@/lib/video-export-app/use-render-video';
import {
VIDEO_FPS,
VIDEO_QUALITIES,
VIDEO_RESOLUTIONS,
type VideoResolution,
} from '@/lib/video-export-app/build-export-zip';
const RESOLUTIONS = Object.keys(VIDEO_RESOLUTIONS) as VideoResolution[];
/**
* Format an ETA (ms) as a short localized "about X min Y sec" / "about Y sec"
* string. Rounds seconds up so it never shows "0 sec" while still working.
*/
function formatRemaining(
ms: number,
t: (key: string, options?: Record<string, unknown>) => string,
): string {
const totalSec = Math.max(1, Math.ceil(ms / 1000));
const min = Math.floor(totalSec / 60);
const sec = totalSec % 60;
return min > 0 ? t('export.videoEtaMinSec', { min, sec }) : t('export.videoEtaSec', { sec });
}
/** A row of mutually-exclusive small pill buttons. */
function OptionRow<T extends string | number>({
label,
options,
value,
onChange,
format,
disabled,
}: {
label: string;
options: readonly T[];
value: T;
onChange: (v: T) => void;
format?: (v: T) => string;
disabled?: boolean;
}) {
return (
<div className="px-4 pb-2">
<div className="text-[11px] text-gray-400 dark:text-gray-500 mb-1">{label}</div>
<div className="flex gap-1.5">
{options.map((opt) => (
<button
key={String(opt)}
onClick={() => onChange(opt)}
disabled={disabled}
className={cn(
'flex-1 px-2 py-1.5 text-xs rounded-md border transition-colors disabled:opacity-50',
opt === value
? 'border-primary bg-primary/10 text-primary'
: 'border-gray-200 dark:border-gray-700 hover:bg-gray-100 dark:hover:bg-gray-700',
)}
>
{format ? format(opt) : String(opt)}
</button>
))}
</div>
</div>
);
}
export function VideoExportMenu({ onClose }: { onClose: () => void }) {
const { t } = useI18n();
const { exporting: isExportingVideo, exportVideo } = useExportVideo();
const { rendering, percent, etaMs, options, setOptions, renderVideo } = useRenderVideo();
const { resolution, fps, quality } = options;
// undefined = unknown (still probing); true/false = capability answer.
const [serviceEnabled, setServiceEnabled] = useState<boolean | undefined>(undefined);
useEffect(() => {
let active = true;
fetch('/api/export-video/capability')
.then((r) => r.json())
.then((d: { enabled?: boolean }) => {
if (active) setServiceEnabled(Boolean(d.enabled));
})
.catch(() => {
if (active) setServiceEnabled(false);
});
return () => {
active = false;
};
}, []);
const busy = isExportingVideo || rendering;
return (
<>
<div className="border-t border-gray-200 dark:border-gray-700" />
<div className="px-4 pt-2.5 pb-1 flex items-center gap-2.5 text-sm">
<Film className="w-4 h-4 text-gray-400 shrink-0" />
<div>
<div>{t('export.video')}</div>
<div className="text-[11px] text-gray-400 dark:text-gray-500">
{t('export.videoDesc')}
</div>
</div>
</div>
<OptionRow
label={t('export.videoResolution')}
options={RESOLUTIONS}
value={resolution}
onChange={(resolution) => setOptions({ resolution })}
format={(r) => (r === '4k' ? '4K' : r)}
disabled={busy}
/>
{/* fps + quality only matter for MP4 rendering. */}
{serviceEnabled && (
<>
<OptionRow
label={t('export.videoFps')}
options={VIDEO_FPS}
value={fps}
onChange={(fps) => setOptions({ fps })}
disabled={busy}
/>
<OptionRow
label={t('export.videoQuality')}
options={VIDEO_QUALITIES}
value={quality}
onChange={(quality) => setOptions({ quality })}
format={(q) => t(`export.videoQuality_${q}`)}
disabled={busy}
/>
</>
)}
{rendering && (
<div className="px-4 pb-2">
<Progress value={percent} />
<div className="mt-1 text-[11px] text-gray-400 dark:text-gray-500">
{etaMs != null
? t('export.videoProgressWithEta', {
percent,
remaining: formatRemaining(etaMs, t),
})
: t('export.videoProgress', { percent })}
</div>
</div>
)}
<div className="px-4 pb-2.5 flex flex-col gap-1.5">
{serviceEnabled && (
<button
onClick={() => renderVideo()}
disabled={busy}
className="w-full px-2 py-1.5 text-xs rounded-md bg-primary text-primary-foreground hover:opacity-90 transition-opacity disabled:opacity-50 flex items-center justify-center gap-1.5"
>
{rendering && <Loader2 className="w-3 h-3 animate-spin" />}
{t('export.videoRenderMp4')}
</button>
)}
<button
onClick={() => {
exportVideo(resolution);
onClose();
}}
disabled={busy}
className="w-full px-2 py-1.5 text-xs rounded-md border border-gray-200 dark:border-gray-700 hover:bg-gray-100 dark:hover:bg-gray-700 transition-colors disabled:opacity-50 flex items-center justify-center gap-1.5"
>
{isExportingVideo && <Loader2 className="w-3 h-3 animate-spin" />}
{t('export.videoDownloadZip')}
</button>
{serviceEnabled === false && (
<div className="text-[11px] text-gray-400 dark:text-gray-500">
{t('export.videoServiceHint')}
</div>
)}
</div>
</>
);
}

View File

@ -0,0 +1,69 @@
'use client';
/**
* `CircularProgress` — a small determinate progress ring.
*
* Rendered as an SVG with two stacked circles (track + arc); the arc length is
* driven by `value` via stroke-dashoffset. Sized to overlay an icon button, so
* it defaults small and inherits color from `currentColor`. Purely presentational.
*/
import { cn } from '@/lib/utils';
interface CircularProgressProps {
/** Progress 0..100. */
value: number;
/** Outer diameter in px. */
size?: number;
/** Ring thickness in px. */
strokeWidth?: number;
className?: string;
}
export function CircularProgress({
value,
size = 24,
strokeWidth = 2.5,
className,
}: CircularProgressProps) {
const clamped = Math.max(0, Math.min(100, value));
const radius = (size - strokeWidth) / 2;
const circumference = 2 * Math.PI * radius;
const offset = circumference * (1 - clamped / 100);
const center = size / 2;
return (
<svg
width={size}
height={size}
viewBox={`0 0 ${size} ${size}`}
className={cn('shrink-0', className)}
role="progressbar"
aria-valuenow={Math.round(clamped)}
aria-valuemin={0}
aria-valuemax={100}
>
{/* Track */}
<circle
cx={center}
cy={center}
r={radius}
fill="none"
strokeWidth={strokeWidth}
className="stroke-current opacity-20"
/>
{/* Arc — starts at 12 o'clock, fills clockwise. */}
<circle
cx={center}
cy={center}
r={radius}
fill="none"
strokeWidth={strokeWidth}
strokeLinecap="round"
strokeDasharray={circumference}
strokeDashoffset={offset}
className="stroke-current transition-[stroke-dashoffset] duration-500"
transform={`rotate(-90 ${center} ${center})`}
/>
</svg>
);
}

View File

@ -5,11 +5,74 @@ services:
- "3000:3000"
env_file:
- .env.local
environment:
# Point the app at the render service when it's running. This wins over any
# RENDER_SERVICE_URL in .env.local; the service only starts under the
# "video-export" profile. The app's capability check probes the service's
# /health, so if the profile is off (service absent) the app reports the
# MP4 export disabled and degrades to the ZIP-download path — this URL
# being set does not, by itself, advertise a working render.
- RENDER_SERVICE_URL=http://render-service:9000
networks:
- default # outbound internet (LLM/media provider APIs, etc.)
- render # reach the render service over the isolated network
volumes:
# Optional: mount server-providers.yml for provider config
# - ./server-providers.yml:/app/server-providers.yml:ro
- openmaic-data:/app/data
restart: unless-stopped
# Isolated MP4 render service (Node 22 + Chromium + FFmpeg) for classroom video
# export (issue #866). Opt-in: only starts with `--profile video-export`, since
# the image is heavy (bundles Chromium + FFmpeg) and the capability is optional.
#
# docker compose --profile video-export up --build
#
# Sits on the `render` network (`internal: true`, no host/internet gateway).
# It shares that network with `openmaic` only so the app can reach it; to stop
# the untrusted Chromium from initiating connections *back* to the app over
# that shared network, the container's entrypoint installs an iptables egress
# lockdown (needs CAP_NET_ADMIN) that drops all outbound except loopback and
# replies on app-initiated connections. The export ZIP is self-contained, so
# the render needs no outbound at all.
render-service:
build: ./render-service
profiles:
- video-export
expose:
- "9000"
# Required for the entrypoint's iptables egress lockdown. Without it the
# service still boots, but logs a warning and does NOT block Chromium egress.
cap_add:
- NET_ADMIN
environment:
- PORT=9000
# Tune for the host; each concurrent render drives a full Chromium + FFmpeg.
- RENDER_MAX_CONCURRENCY=2
# In this default topology the app is exposed directly and does NOT set
# TRUST_PROXY_HEADERS, so every caller collapses to one identity. A
# per-identity limit would then throttle the whole deployment to a single
# render, so disable it here and rely on RENDER_MAX_CONCURRENCY + the global
# RENDER_MAX_QUEUE cap. Set this >0 only with a trusted proxy supplying
# per-user identity (see render-service/README.md).
- RENDER_MAX_JOBS_PER_USER=0
# Bound RAM: each render (Chromium + FFmpeg + archive expansion) is memory
# heavy, and extraction is capped separately (RENDER_MAX_CONCURRENT_EXTRACTIONS).
# Raise for higher RENDER_MAX_CONCURRENCY / larger classrooms.
mem_limit: 4g
networks:
- render
restart: unless-stopped
networks:
default: {}
# Isolated network for app <-> render-service traffic. `internal: true` means
# no route to the host or internet. Both services share it so the app can
# reach the render service; the render container additionally blocks its own
# egress (iptables, see the service's entrypoint) so the untrusted Chromium
# can't use this shared network to reach the app.
render:
internal: true
volumes:
openmaic-data:

View File

@ -29,6 +29,9 @@ const eslintConfig = defineConfig([
'.worktrees/**',
// Playwright e2e tests (not React code):
'e2e/**',
// Isolated MP4 render service: its own package, tsconfig, and Node-only
// deps (@hyperframes/producer). Linted/typechecked under render-service/.
'render-service/**',
]),
{
rules: {

View File

@ -61,6 +61,21 @@
"videoSuccess": "تم تصدير مشروع الفيديو",
"videoFailed": "فشل تصدير الفيديو",
"videoWarnings": "{{assets}} من الموارد مفقودة و {{diagnostics}} من المشكلات في تقرير التصدير.",
"videoMp4Success": "تم عرض الفيديو",
"videoServiceUnavailable": "خدمة العرض غير مُهيأة — تم تنزيل ملف ZIP للمشروع للعرض محليًا.",
"videoResolution": "الدقة",
"videoFps": "معدل الإطارات",
"videoQuality": "الجودة",
"videoQuality_draft": "مسودة",
"videoQuality_standard": "قياسي",
"videoQuality_high": "عالية",
"videoProgress": "{{percent}}%",
"videoProgressWithEta": "{{percent}}% · يتبقّى ~{{remaining}}",
"videoEtaMinSec": "{{min}} د {{sec}} ث",
"videoEtaSec": "{{sec}} ث",
"videoRenderMp4": "عرض MP4",
"videoDownloadZip": "تنزيل ملف ZIP للمشروع",
"videoServiceHint": "يتطلب عرض MP4 خدمة العرض. نزّل ملف ZIP للعرض محليًا.",
"noSlides": "لا توجد شرائح للتصدير",
"noSlidesSkipped": "لا توجد شرائح في هذه الدورة — تم تخطي PPTX",
"nothingToExport": "لا يوجد محتوى للتصدير"

View File

@ -61,6 +61,21 @@
"videoSuccess": "Video project exported",
"videoFailed": "Video export failed",
"videoWarnings": "{{assets}} asset(s) missing and {{diagnostics}} issue(s) in the export report.",
"videoMp4Success": "Video rendered",
"videoServiceUnavailable": "Render service not configured — downloaded the project ZIP for local rendering.",
"videoResolution": "Resolution",
"videoFps": "Frame rate",
"videoQuality": "Quality",
"videoQuality_draft": "Draft",
"videoQuality_standard": "Standard",
"videoQuality_high": "High",
"videoProgress": "{{percent}}%",
"videoProgressWithEta": "{{percent}}% · about {{remaining}} left",
"videoEtaMinSec": "{{min}} min {{sec}} sec",
"videoEtaSec": "{{sec}} sec",
"videoRenderMp4": "Render MP4",
"videoDownloadZip": "Download project ZIP",
"videoServiceHint": "MP4 rendering needs the render service. Download the ZIP to render locally.",
"noSlides": "No slides to export",
"noSlidesSkipped": "No slides in this course — PPTX skipped",
"nothingToExport": "Nothing to export"

View File

@ -61,6 +61,21 @@
"videoSuccess": "動画プロジェクトをエクスポートしました",
"videoFailed": "動画のエクスポートに失敗しました",
"videoWarnings": "{{assets}} 個の素材が不足しており、エクスポートレポートに {{diagnostics}} 件の問題があります。",
"videoMp4Success": "動画をレンダリングしました",
"videoServiceUnavailable": "レンダーサービスが未設定です — ローカルレンダリング用にプロジェクト ZIP をダウンロードしました。",
"videoResolution": "解像度",
"videoFps": "フレームレート",
"videoQuality": "品質",
"videoQuality_draft": "ドラフト",
"videoQuality_standard": "標準",
"videoQuality_high": "高",
"videoProgress": "{{percent}}%",
"videoProgressWithEta": "{{percent}}% · 残り約 {{remaining}}",
"videoEtaMinSec": "{{min}} 分 {{sec}} 秒",
"videoEtaSec": "{{sec}} 秒",
"videoRenderMp4": "MP4 をレンダリング",
"videoDownloadZip": "プロジェクト ZIP をダウンロード",
"videoServiceHint": "MP4 レンダリングにはレンダーサービスが必要です。ZIP をダウンロードしてローカルでレンダリングできます。",
"noSlides": "エクスポート可能なスライドがありません",
"noSlidesSkipped": "このコースにスライドがないため、PPTX をスキップしました",
"nothingToExport": "エクスポートできるものがありません"

View File

@ -61,6 +61,21 @@
"videoSuccess": "동영상 프로젝트를 내보냈습니다",
"videoFailed": "동영상 내보내기 실패",
"videoWarnings": "{{assets}}개의 에셋이 누락되었고 내보내기 보고서에 {{diagnostics}}개의 문제가 있습니다.",
"videoMp4Success": "동영상이 렌더링되었습니다",
"videoServiceUnavailable": "렌더 서비스가 구성되지 않았습니다 — 로컬 렌더링용 프로젝트 ZIP을 다운로드했습니다.",
"videoResolution": "해상도",
"videoFps": "프레임 속도",
"videoQuality": "품질",
"videoQuality_draft": "초안",
"videoQuality_standard": "표준",
"videoQuality_high": "고품질",
"videoProgress": "{{percent}}%",
"videoProgressWithEta": "{{percent}}% · 약 {{remaining}} 남음",
"videoEtaMinSec": "{{min}}분 {{sec}}초",
"videoEtaSec": "{{sec}}초",
"videoRenderMp4": "MP4 렌더링",
"videoDownloadZip": "프로젝트 ZIP 다운로드",
"videoServiceHint": "MP4 렌더링에는 렌더 서비스가 필요합니다. ZIP을 다운로드하여 로컬에서 렌더링하세요.",
"noSlides": "내보낼 슬라이드가 없습니다",
"noSlidesSkipped": "이 코스에 슬라이드가 없어 PPTX를 건너뛰었습니다",
"nothingToExport": "내보낼 항목이 없습니다"

View File

@ -61,6 +61,21 @@
"videoSuccess": "Projeto de vídeo exportado",
"videoFailed": "Falha na exportação do vídeo",
"videoWarnings": "{{assets}} recurso(s) ausente(s) e {{diagnostics}} problema(s) no relatório de exportação.",
"videoMp4Success": "Vídeo renderizado",
"videoServiceUnavailable": "Serviço de renderização não configurado — o ZIP do projeto foi baixado para renderização local.",
"videoResolution": "Resolução",
"videoFps": "Taxa de quadros",
"videoQuality": "Qualidade",
"videoQuality_draft": "Rascunho",
"videoQuality_standard": "Padrão",
"videoQuality_high": "Alta",
"videoProgress": "{{percent}}%",
"videoProgressWithEta": "{{percent}}% · ~{{remaining}} restante(s)",
"videoEtaMinSec": "{{min}} min {{sec}} s",
"videoEtaSec": "{{sec}} s",
"videoRenderMp4": "Renderizar MP4",
"videoDownloadZip": "Baixar ZIP do projeto",
"videoServiceHint": "A renderização de MP4 requer o serviço de renderização. Baixe o ZIP para renderizar localmente.",
"noSlides": "Não há slides para exportar",
"noSlidesSkipped": "Este curso não tem slides — PPTX ignorado",
"nothingToExport": "Nada para exportar"

View File

@ -61,6 +61,21 @@
"videoSuccess": "Видеопроект экспортирован",
"videoFailed": "Ошибка экспорта видео",
"videoWarnings": "Отсутствует ресурсов: {{assets}}; проблем в отчёте об экспорте: {{diagnostics}}.",
"videoMp4Success": "Видео отрендерено",
"videoServiceUnavailable": "Сервис рендеринга не настроен — ZIP проекта загружен для локального рендеринга.",
"videoResolution": "Разрешение",
"videoFps": "Частота кадров",
"videoQuality": "Качество",
"videoQuality_draft": "Черновик",
"videoQuality_standard": "Стандарт",
"videoQuality_high": "Высокое",
"videoProgress": "{{percent}}%",
"videoProgressWithEta": "{{percent}}% · осталось ~{{remaining}}",
"videoEtaMinSec": "{{min}} мин {{sec}} с",
"videoEtaSec": "{{sec}} с",
"videoRenderMp4": "Рендерить MP4",
"videoDownloadZip": "Скачать ZIP проекта",
"videoServiceHint": "Для рендеринга MP4 нужен сервис рендеринга. Скачайте ZIP для локального рендеринга.",
"noSlides": "Нет слайдов для экспорта",
"noSlidesSkipped": "В этом курсе нет слайдов — PPTX пропущен",
"nothingToExport": "Нет данных для экспорта"

View File

@ -61,6 +61,21 @@
"videoSuccess": "视频工程已导出",
"videoFailed": "视频导出失败",
"videoWarnings": "有 {{assets}} 个素材缺失,导出报告中有 {{diagnostics}} 个问题。",
"videoMp4Success": "视频已渲染",
"videoServiceUnavailable": "未配置渲染服务 —— 已下载项目 ZIP 供本地渲染。",
"videoResolution": "分辨率",
"videoFps": "帧率",
"videoQuality": "质量",
"videoQuality_draft": "草稿",
"videoQuality_standard": "标准",
"videoQuality_high": "高",
"videoProgress": "{{percent}}%",
"videoProgressWithEta": "{{percent}}% · 预计剩余 {{remaining}}",
"videoEtaMinSec": "{{min}} 分 {{sec}} 秒",
"videoEtaSec": "{{sec}} 秒",
"videoRenderMp4": "渲染 MP4",
"videoDownloadZip": "下载项目 ZIP",
"videoServiceHint": "渲染 MP4 需要渲染服务。可下载 ZIP 在本地渲染。",
"noSlides": "无可导出的幻灯片",
"noSlidesSkipped": "本课程无幻灯片,已跳过 PPTX",
"nothingToExport": "没有可导出的内容"

View File

@ -61,6 +61,21 @@
"videoSuccess": "影片專案已匯出",
"videoFailed": "影片匯出失敗",
"videoWarnings": "有 {{assets}} 個素材缺失,匯出報告中有 {{diagnostics}} 個問題。",
"videoMp4Success": "影片已算圖",
"videoServiceUnavailable": "未設定算圖服務 —— 已下載專案 ZIP 供本機算圖。",
"videoResolution": "解析度",
"videoFps": "影格率",
"videoQuality": "品質",
"videoQuality_draft": "草稿",
"videoQuality_standard": "標準",
"videoQuality_high": "高",
"videoProgress": "{{percent}}%",
"videoProgressWithEta": "{{percent}}% · 預計剩餘 {{remaining}}",
"videoEtaMinSec": "{{min}} 分 {{sec}} 秒",
"videoEtaSec": "{{sec}} 秒",
"videoRenderMp4": "算圖 MP4",
"videoDownloadZip": "下載專案 ZIP",
"videoServiceHint": "算圖 MP4 需要算圖服務。可下載 ZIP 在本機算圖。",
"noSlides": "無可匯出的幻燈片",
"noSlidesSkipped": "本課程無幻燈片,已跳過 PPTX",
"nothingToExport": "沒有可匯出的內容"

View File

@ -0,0 +1,46 @@
/**
* A byte-capped wrapper around a request body stream.
*
* `Content-Length` is client-supplied and easy to omit, lie about, or sidestep
* with a chunked (`Transfer-Encoding: chunked`) upload — so a length check alone
* can't stop an unbounded body from being buffered into memory. This wraps the
* body stream so the *actual* bytes are counted as they flow, and the stream is
* aborted the instant they exceed `capBytes`. Nothing downstream (a proxying
* `fetch`, a `formData()` parse) ever buffers more than the cap.
*
* Returns the capped stream plus an `exceeded()` probe so the caller can tell a
* cap trip apart from an ordinary malformed-body error after the consumer throws.
*/
export interface CappedBody {
stream: ReadableStream<Uint8Array>;
exceeded: () => boolean;
}
export function capBodyStream(body: ReadableStream<Uint8Array>, capBytes: number): CappedBody {
let total = 0;
let tripped = false;
const reader = body.getReader();
const stream = new ReadableStream<Uint8Array>({
async pull(controller) {
const { done, value } = await reader.read();
if (done) {
controller.close();
return;
}
total += value.byteLength;
if (total > capBytes) {
tripped = true;
controller.error(new Error('Upload exceeds the maximum allowed size'));
await reader.cancel().catch(() => {});
return;
}
controller.enqueue(value);
},
cancel(reason) {
void reader.cancel(reason).catch(() => {});
},
});
return { stream, exceeded: () => tripped };
}

View File

@ -0,0 +1,60 @@
/**
* Server-side config + helpers for the isolated MP4 render service (issue #866).
*
* The render service is an opt-in capability: it's only reachable when
* `RENDER_SERVICE_URL` is set. When unset, the app degrades to letting the user
* download the project ZIP for local CLI rendering, so callers treat "not
* configured" as a normal, expected state — not an error.
*/
import { proxyFetch } from '@/lib/server/proxy-fetch';
import { createLogger } from '@/lib/logger';
const log = createLogger('RenderService');
/** The configured base URL of the render service, or null when the capability is off. */
export function getRenderServiceUrl(): string | null {
const raw = process.env.RENDER_SERVICE_URL?.trim();
return raw ? raw.replace(/\/+$/, '') : null;
}
/** Whether the render service is configured (URL present — not a reachability check). */
export function isRenderServiceConfigured(): boolean {
return getRenderServiceUrl() !== null;
}
/**
* Resolve the render service base URL, or `{ error: 'not_configured' }`.
*
* `RENDER_SERVICE_URL` is operator-supplied deployment config, not user input,
* so it is deliberately NOT run through the SSRF guard: the guard exists to stop
* user-controlled URLs from reaching internal hosts, whereas this URL is
* *meant* to point at an internal service (e.g. `http://render-service:9000`
* on the compose network). Running the guard here would reject the intended
* deployment unless the operator globally weakened SSRF via
* `ALLOW_LOCAL_NETWORKS`, which we do not want to require.
*/
export function resolveRenderServiceUrl(): { url: string } | { error: 'not_configured' } {
const url = getRenderServiceUrl();
return url ? { url } : { error: 'not_configured' };
}
/**
* Whether the configured render service is actually reachable and healthy.
* Probes `GET /health` with a short timeout. Returns false (rather than
* throwing) when unconfigured or unreachable, so the capability endpoint can
* report a truthful enabled/disabled state and the UI degrades cleanly.
*/
export async function checkRenderServiceHealth(): Promise<boolean> {
const url = getRenderServiceUrl();
if (!url) return false;
try {
const res = await proxyFetch(`${url}/health`, {
method: 'GET',
signal: AbortSignal.timeout(3000),
});
return res.ok;
} catch (error) {
log.info('Render service health check failed:', error instanceof Error ? error.message : error);
return false;
}
}

267
lib/store/video-render.ts Normal file
View File

@ -0,0 +1,267 @@
'use client';
/**
* Global store for the one-click MP4 render (issue #866).
*
* The render is async and long (a 10-minute classroom takes ~10 minutes), so
* its progress must outlive the export menu: the user can close the menu, switch
* scenes, and reopen the menu, and still see live progress. Keeping the state in
* a component (as the first cut did) meant it died with the menu, and the
* re-mounted menu reset its "already rendering" ref — letting the user submit a
* duplicate render. Hoisting the whole lifecycle here fixes both.
*
* The store owns the submit → poll → download loop. Progress is a percentage
* plus an estimated time remaining (extrapolated from elapsed time and smoothed
* with an EMA); no producer stage strings are surfaced. i18n stays out of the
* store: callers pass `t`, and toasts use sonner's global singleton so they
* still fire if the calling component has unmounted.
*/
import { create } from 'zustand';
import { saveAs } from 'file-saver';
import { toast } from 'sonner';
import { createLogger } from '@/lib/logger';
import { runPolledTask } from '@/lib/media/polled-task';
import {
buildExportZip,
NoScenesError,
sanitizeFilename,
type VideoFps,
type VideoQuality,
type VideoResolution,
} from '@/lib/video-export-app/build-export-zip';
const log = createLogger('VideoRenderStore');
const POLL_INTERVAL_MS = 3000;
const MAX_POLL_ATTEMPTS = Math.ceil((60 * 60 * 1000) / POLL_INTERVAL_MS);
/** Below this percent the extrapolated ETA is too noisy to show. */
const ETA_MIN_PERCENT = 3;
/**
* EMA weight for the newest *speed* sample (percent-per-ms). Lower = smoother
* and laggier. We smooth speed rather than the whole-run average because this
* render is not uniform (prep → frame capture, which drops 4→1 worker mid-way,
* → encode): a recent-speed estimate reacts to those regime changes, and the
* EMA keeps it from jittering on the producer's uneven percent updates.
*/
const SPEED_SMOOTHING = 0.3;
export type VideoRenderStatus = 'idle' | 'compiling' | 'rendering' | 'succeeded' | 'failed';
/** Minimal i18n surface the store needs, injected by callers. */
type Translate = (key: string, options?: Record<string, unknown>) => string;
export interface RenderOptions {
resolution?: VideoResolution;
fps?: VideoFps;
quality?: VideoQuality;
}
/** Fully-resolved render options (the store always holds concrete values). */
type ResolvedOptions = Required<RenderOptions>;
const DEFAULT_OPTIONS: ResolvedOptions = {
resolution: '1080p',
fps: 30,
quality: 'standard',
};
interface JobStatusResponse {
jobId: string;
status: 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled';
progress?: number;
currentStage?: string;
error?: string;
done?: boolean;
}
interface VideoRenderState {
status: VideoRenderStatus;
/** 0..100. */
percent: number;
/** Estimated milliseconds remaining, or null while unknown. */
etaMs: number | null;
filename: string | null;
error: string | null;
/**
* The user's selected render options. Held in the store (not the menu
* component) so they survive the menu unmounting on scene switches and, while
* a render runs, reflect the options that render is actually using.
*/
options: ResolvedOptions;
setOptions: (patch: Partial<ResolvedOptions>) => void;
/** True while a render is in flight (compiling or rendering). */
isActive: () => boolean;
startRender: (t: Translate) => Promise<void>;
reset: () => void;
}
/** Whether a status means a render is still in flight. */
function inFlight(status: VideoRenderStatus): boolean {
return status === 'compiling' || status === 'rendering';
}
export const useVideoRenderStore = create<VideoRenderState>()((set, get) => ({
status: 'idle',
percent: 0,
etaMs: null,
filename: null,
error: null,
options: DEFAULT_OPTIONS,
setOptions: (patch) => set((s) => ({ options: { ...s.options, ...patch } })),
isActive: () => inFlight(get().status),
reset: () => set({ status: 'idle', percent: 0, etaMs: null, filename: null, error: null }),
startRender: async (t) => {
// Guard against a duplicate submit — the whole reason state lives here.
if (inFlight(get().status)) return;
const { resolution, fps, quality } = get().options;
set({ status: 'compiling', percent: 0, etaMs: null, filename: null, error: null });
const toastId = toast.loading(t('export.videoCompiling'));
let zipBlob: Blob;
let stageName: string;
let missingCount = 0;
let errorCount = 0;
try {
const built = await buildExportZip(resolution);
({ zipBlob, stageName, missingCount, errorCount } = built);
} catch (error) {
if (error instanceof NoScenesError) {
toast.error(t('export.videoNoScenes'), { id: toastId });
} else {
log.error('Video render (compile) failed:', error);
toast.error(t('export.videoFailed'), { id: toastId });
}
set({ status: 'failed', error: 'compile' });
return;
}
const filename = `${sanitizeFilename(stageName)}.mp4`;
set({ status: 'rendering', filename });
// ETA via recent speed: track the previous (percent, timestamp) sample,
// derive an instantaneous percent-per-ms rate, EMA-smooth it, and project
// the remaining percent onto it. Reacts to the render's speed regime
// changes (worker drop, encode) far better than a whole-run average.
let lastPercent: number | null = null;
let lastTs = 0;
let smoothedSpeed: number | null = null; // percent per ms
// Set once the service accepts the job. Lets the catch below distinguish a
// *submit* failure (nothing started) from a failure after the render began
// (hard error, and cancel the server job to free its slot).
let submittedJobId: string | null = null;
// HTTP status of a failed submit, so the catch can tell "service genuinely
// unavailable" (degrade to ZIP) from a real rejection like 429/413/5xx
// (surface the error instead of an unsolicited download). null = fetch threw.
let submitStatus: number | null = null;
try {
const form = new FormData();
form.append('project', zipBlob, 'project.zip');
form.append('fps', String(fps));
form.append('quality', quality);
form.append('format', 'mp4');
toast.loading(t('export.videoRendering'), { id: toastId });
const mp4 = await runPolledTask<Blob>({
label: 'render-video',
intervalMs: POLL_INTERVAL_MS,
maxAttempts: MAX_POLL_ATTEMPTS,
submit: async () => {
const res = await fetch('/api/export-video/render', { method: 'POST', body: form });
const data = (await res.json().catch(() => ({}))) as {
jobId?: string;
error?: string;
details?: string;
};
if (!res.ok || !data.jobId) {
submitStatus = res.status;
const detail = [data.error, data.details].filter(Boolean).join(': ');
return { status: 'failed', message: detail || `HTTP ${res.status}` };
}
submittedJobId = data.jobId;
return { status: 'submitted', taskId: data.jobId };
},
poll: async (jobId) => {
const res = await fetch(`/api/export-video/render/${jobId}`);
const data = (await res.json().catch(() => ({}))) as JobStatusResponse;
if (!res.ok) return { status: 'failed', message: data.error || `HTTP ${res.status}` };
const percent = Math.round((data.progress ?? 0) * 100);
// Derive a recent speed (percent/ms) from the delta since the last
// sample, EMA-smooth it, then project the remaining percent. Only
// forward progress updates the speed; stalls/regressions are ignored
// so a paused stage doesn't blow the ETA up to infinity.
const now = Date.now();
let etaMs = get().etaMs;
if (lastPercent != null && percent > lastPercent && now > lastTs) {
const sample = (percent - lastPercent) / (now - lastTs);
smoothedSpeed =
smoothedSpeed == null
? sample
: SPEED_SMOOTHING * sample + (1 - SPEED_SMOOTHING) * smoothedSpeed;
}
if (percent >= ETA_MIN_PERCENT && percent < 100 && smoothedSpeed && smoothedSpeed > 0) {
etaMs = (100 - percent) / smoothedSpeed;
}
if (lastPercent == null || percent > lastPercent) {
lastPercent = percent;
lastTs = now;
}
set({ percent, etaMs });
if (data.status === 'succeeded') {
const dl = await fetch(`/api/export-video/render/${jobId}/download`);
if (!dl.ok) return { status: 'failed', message: `download HTTP ${dl.status}` };
return { status: 'done', result: await dl.blob() };
}
if (data.status === 'failed' || data.status === 'cancelled') {
return { status: 'failed', message: data.error || data.status };
}
return { status: 'pending', detail: data.currentStage };
},
});
saveAs(mp4, filename);
set({ status: 'succeeded', percent: 100, etaMs: 0 });
toast.success(t('export.videoMp4Success'), { id: toastId });
if (missingCount > 0 || errorCount > 0) {
toast.warning(t('export.videoWarnings', { assets: missingCount, diagnostics: errorCount }));
}
} catch (error) {
const message = error instanceof Error ? error.message : String(error);
if (submittedJobId == null) {
// The submit never succeeded. Only degrade to the ZIP when the service
// is genuinely unavailable — not configured (501) or unreachable (fetch
// threw, submitStatus null). For real rejections (429 busy, 413 too
// large, 5xx) surface the actual reason instead of silently downloading
// a ZIP the user didn't ask for, so the failure is honest and retryable.
const unavailable = submitStatus == null || submitStatus === 501;
if (unavailable) {
saveAs(zipBlob, `${sanitizeFilename(stageName)}-video.zip`);
set({ status: 'idle', percent: 0, etaMs: null });
toast.info(t('export.videoServiceUnavailable'), { id: toastId });
} else {
set({ status: 'failed', error: message });
toast.error(t('export.videoFailed'), { id: toastId });
}
} else {
// The render started but failed / timed out. Cancel the server job so it
// doesn't hold a concurrency slot and scratch space, then surface the error.
void fetch(`/api/export-video/render/${submittedJobId}`, { method: 'DELETE' }).catch(
() => {},
);
log.error('Video render failed:', error);
set({ status: 'failed', error: message });
toast.error(t('export.videoFailed'), { id: toastId });
}
}
},
}));

View File

@ -0,0 +1,88 @@
'use client';
/**
* `buildExportZip` — the shared prefix of both video-export paths.
*
* Runs the whole browser-side pipeline up to (and including) the self-contained
* ZIP: load DI deps (Dexie durations + asset presence) → pure-compile to the
* `VideoTimeline` IR → emit the Hyperframes project text → collect asset bytes
* (slide snapshots + narration/media) → package the ZIP.
*
* Both `useExportVideo` (download the ZIP for local CLI rendering) and
* `useRenderVideo` (upload the ZIP to the render service for MP4) call this so
* the two paths can never drift.
*
* App-side / impure: reads the store + Dexie and does IO.
*/
import { compileVideoTimeline, emitHyperframes } from '@/lib/video-export';
import { useStageStore } from '@/lib/store';
import { db } from '@/lib/utils/database';
import { createVideoTimelineDeps } from './timeline-deps';
import { collectVideoAssets } from './collect';
import { packageVideoZip } from './package-zip';
/** Selectable render resolutions (16:9). Width drives slide-snapshot render width too. */
export const VIDEO_RESOLUTIONS = {
'720p': { width: 1280, height: 720 },
'1080p': { width: 1920, height: 1080 },
'4k': { width: 3840, height: 2160 },
} as const;
export type VideoResolution = keyof typeof VIDEO_RESOLUTIONS;
/** Selectable frame rates for MP4 rendering. */
export const VIDEO_FPS = [24, 30, 60] as const;
export type VideoFps = (typeof VIDEO_FPS)[number];
/** Producer quality presets (speed vs fidelity). */
export const VIDEO_QUALITIES = ['draft', 'standard', 'high'] as const;
export type VideoQuality = (typeof VIDEO_QUALITIES)[number];
export interface BuildExportZipResult {
zipBlob: Blob;
stageName: string;
/** Number of asset-plan entries whose bytes couldn't be produced. */
missingCount: number;
/** Non-info diagnostics from the compiler. */
errorCount: number;
}
export class NoScenesError extends Error {}
/**
* Build the export ZIP for the current stage at the given resolution. Throws
* {@link NoScenesError} when there's nothing to export.
*/
export async function buildExportZip(resolution: VideoResolution): Promise<BuildExportZipResult> {
const { stage, scenes } = useStageStore.getState();
if (!stage?.id || scenes.length === 0) {
throw new NoScenesError('No scenes to export');
}
const { width, height } = VIDEO_RESOLUTIONS[resolution];
const latest = await db.stages.get(stage.id).catch(() => undefined);
const stageName = latest?.name || stage.name || 'classroom';
// 1. DI deps (Dexie durations + asset presence) → 2. pure compile to IR.
const deps = await createVideoTimelineDeps({ stage: { id: stage.id }, scenes });
const ir = compileVideoTimeline({ stage: { id: stage.id, name: stageName }, scenes }, deps);
// 3. emit the Hyperframes project text.
const project = emitHyperframes(ir, { width, height });
// 4. collect asset bytes (slide snapshots + narration/media).
const { blobs, missing } = await collectVideoAssets(ir, scenes, deps.records, {
frameWidth: width,
});
// 5. package the self-contained ZIP.
const zipBlob = await packageVideoZip(project, blobs);
const errorCount = ir.diagnostics.filter((d) => d.severity !== 'info').length;
return { zipBlob, stageName, missingCount: missing.length, errorCount };
}
export function sanitizeFilename(name: string): string {
return name.replace(/[\\/:*?"<>|]/g, '_') || 'classroom';
}

View File

@ -52,20 +52,52 @@ function formatFromMime(mimeType: string | undefined): string | undefined {
return mimeType?.split('/')[1] || undefined;
}
/** Per-probe timeout (ms). A blob whose metadata never loads must not wedge export. */
const PROBE_TIMEOUT_MS = 10_000;
/** How many media-duration probes run at once (bounded so a big deck can't thrash). */
const PROBE_CONCURRENCY = 6;
/**
* Run `worker` over `items` with bounded concurrency, collecting results. Order
* is not significant to callers (they key results into a Map), so this drains a
* shared cursor from `PROBE_CONCURRENCY` lanes.
*/
async function mapWithConcurrency<T>(
items: T[],
limit: number,
worker: (item: T) => Promise<void>,
): Promise<void> {
let cursor = 0;
const lanes = Array.from({ length: Math.min(limit, items.length) }, async () => {
while (cursor < items.length) {
const i = cursor++;
await worker(items[i]);
}
});
await Promise.all(lanes);
}
/**
* Probe a video blob's natural duration (ms) via an off-document `<video>`.
* Resolves `null` when metadata never loads (the compiler then caps the dwell).
* A watchdog forces `null` after {@link PROBE_TIMEOUT_MS} so a blob that never
* fires `loadedmetadata`/`error` can't leave the whole export stuck compiling.
*/
function probeVideoDurationMs(blob: Blob): Promise<number | null> {
return new Promise((resolve) => {
const url = URL.createObjectURL(blob);
const video = document.createElement('video');
video.preload = 'metadata';
let settled = false;
const done = (value: number | null) => {
if (settled) return;
settled = true;
clearTimeout(timer);
URL.revokeObjectURL(url);
video.removeAttribute('src');
resolve(value);
};
const timer = setTimeout(() => done(null), PROBE_TIMEOUT_MS);
video.onloadedmetadata = () =>
done(Number.isFinite(video.duration) ? Math.round(video.duration * 1000) : null);
video.onerror = () => done(null);
@ -73,6 +105,41 @@ function probeVideoDurationMs(blob: Blob): Promise<number | null> {
});
}
/**
* Probe a narration audio blob's natural duration (ms) via an off-document
* `<audio>`. Symmetric to {@link probeVideoDurationMs}. Resolves `null` when
* metadata never loads, and — via the same watchdog — after
* {@link PROBE_TIMEOUT_MS} if neither event ever fires.
*
* This is the source of truth for narration timing: the TTS-time
* `AudioFileRecord.duration` was only recorded for classrooms generated after
* #861, so most existing courses have it unset and would otherwise fall back to
* text-length *estimates* — which run short and truncate the narration / advance
* the timeline early. Reading the real bytes makes the scheduled dwell match the
* clip for every classroom that actually has audio.
*/
function probeAudioDurationMs(blob: Blob): Promise<number | null> {
return new Promise((resolve) => {
const url = URL.createObjectURL(blob);
const audio = document.createElement('audio');
audio.preload = 'metadata';
let settled = false;
const done = (value: number | null) => {
if (settled) return;
settled = true;
clearTimeout(timer);
URL.revokeObjectURL(url);
audio.removeAttribute('src');
resolve(value);
};
const timer = setTimeout(() => done(null), PROBE_TIMEOUT_MS);
audio.onloadedmetadata = () =>
done(Number.isFinite(audio.duration) ? Math.round(audio.duration * 1000) : null);
audio.onerror = () => done(null);
audio.src = url;
});
}
/**
* Load the Dexie-backed records for a classroom and build the synchronous
* compiler deps over them. Audio durations come from the stored records
@ -100,6 +167,20 @@ export async function createVideoTimelineDeps(input: {
if (record) audioById.set(audioId, record);
}
// Probe real audio durations from the local blobs up front, so the compiler's
// sync `audioDurationMs` is an accurate table lookup rather than a text-length
// estimate. Only local blobs can be probed here; an ossKey-only (evicted)
// record has no bytes to read, so it falls back to the stored duration (or
// estimate) — the same asymmetry the video probe accepts. Probes run with
// bounded concurrency (each has its own timeout) so a large deck resolves
// quickly without one stuck blob wedging the export.
const audioDurationMsByAudioId = new Map<string, number>();
const probableAudio = [...audioById].filter(([, record]) => record.blob.size > 0);
await mapWithConcurrency(probableAudio, PROBE_CONCURRENCY, async ([audioId, record]) => {
const ms = await probeAudioDurationMs(record.blob);
if (ms !== null) audioDurationMsByAudioId.set(audioId, ms);
});
// Media: all generated media for this stage, keyed by elementId.
const mediaRecords = await db.mediaFiles.where('stageId').equals(stage.id).toArray();
const mediaByElementId = new Map<string, MediaFileRecord>();
@ -111,17 +192,24 @@ export async function createVideoTimelineDeps(input: {
// Probe video durations up front so `videoDurationMs` can be synchronous.
// Only local blobs are probed; ossKey-only (evicted) records have no bytes to
// probe here, so the compiler caps their dwell — the bytes are still fetched at
// collect time for the render.
// collect time for the render. Bounded concurrency + per-probe timeout, as above.
const videoDurationMsByElementId = new Map<string, number>();
for (const [elementId, record] of mediaByElementId) {
if (record.type !== 'video' || record.error || record.blob.size === 0) continue;
const probableVideo = [...mediaByElementId].filter(
([, record]) => record.type === 'video' && !record.error && record.blob.size > 0,
);
await mapWithConcurrency(probableVideo, PROBE_CONCURRENCY, async ([elementId, record]) => {
const ms = await probeVideoDurationMs(record.blob);
if (ms !== null) videoDurationMsByElementId.set(elementId, ms);
}
});
const timing: TimingProbe = {
audioDurationMs(action: SpeechAction): number | null {
const record = action.audioId ? audioById.get(action.audioId) : undefined;
if (!action.audioId) return null;
// Prefer the real probed duration; fall back to the stored TTS duration
// (older records), then null (→ compiler estimates from text length).
const probed = audioDurationMsByAudioId.get(action.audioId);
if (probed != null) return probed;
const record = audioById.get(action.audioId);
if (!record || typeof record.duration !== 'number') return null;
return Math.round(record.duration * 1000);
},
@ -135,11 +223,13 @@ export async function createVideoTimelineDeps(input: {
if (!action.audioId) return null;
const record = audioById.get(action.audioId);
if (!record) return { id: action.audioId, present: false };
const probed = audioDurationMsByAudioId.get(action.audioId);
return {
id: action.audioId,
mimeType: record.blob.type || undefined,
format: record.format || 'mp3',
durationMs: typeof record.duration === 'number' ? record.duration * 1000 : undefined,
durationMs:
probed ?? (typeof record.duration === 'number' ? record.duration * 1000 : undefined),
// Present when locally held or fetchable from its CDN ossKey at collect time.
present: record.blob.size > 0 || !!record.ossKey,
};

View File

@ -1,99 +1,76 @@
'use client';
/**
* `useExportVideo` — the classroom → Hyperframes video-export flow.
* `useExportVideo` — download the classroom as a self-contained Hyperframes
* project ZIP for local CLI rendering.
*
* Orchestrates the whole pipeline app-side: load the DI deps (Dexie durations +
* asset presence), run the pure compiler to the `VideoTimeline` IR, emit the
* Hyperframes project text, collect the asset bytes (slide snapshots + narration
* / media), package the self-contained ZIP, and download it. Mirrors the existing
* export hooks (`use-export-classroom`): imperative store read, a single sonner
* toast id for progress, `saveAs` for download, `{ exporting, exportVideo }` out.
* This is the degrade path (and #865's original behavior): the whole pipeline
* runs in the browser via {@link buildExportZip}, then the ZIP is saved to disk.
* When the render service is configured, `useRenderVideo` uploads the same ZIP
* to produce an MP4 in-app instead.
*
* App-side / impure: this is the composition root that wires the pure compiler
* (`@/lib/video-export`) to its browser-backed dependencies.
* App-side / impure: imperative store read, a single sonner toast id for
* progress, `saveAs` for download.
*/
import { useCallback, useRef, useState } from 'react';
import { useCallback, useState } from 'react';
import { saveAs } from 'file-saver';
import { toast } from 'sonner';
import { compileVideoTimeline } from '@/lib/video-export';
import { useStageStore } from '@/lib/store';
import { useI18n } from '@/lib/hooks/use-i18n';
import { db } from '@/lib/utils/database';
import { createLogger } from '@/lib/logger';
import { createVideoTimelineDeps } from './timeline-deps';
import { collectVideoAssets } from './collect';
import { packageVideoZip } from './package-zip';
import { emitHyperframes } from '@/lib/video-export';
import {
buildExportZip,
NoScenesError,
sanitizeFilename,
VIDEO_RESOLUTIONS,
type VideoResolution,
} from './build-export-zip';
const log = createLogger('ExportVideo');
/** Selectable render resolutions (16:9). Width drives slide-snapshot render width too. */
export const VIDEO_RESOLUTIONS = {
'720p': { width: 1280, height: 720 },
'1080p': { width: 1920, height: 1080 },
'4k': { width: 3840, height: 2160 },
} as const;
// Re-exported for existing importers (e.g. the export menu).
export { VIDEO_RESOLUTIONS };
export type { VideoResolution };
export type VideoResolution = keyof typeof VIDEO_RESOLUTIONS;
function sanitizeFilename(name: string): string {
return name.replace(/[\\/:*?"<>|]/g, '_') || 'classroom';
}
// Module-level, NOT a per-hook ref: this hook lives in the export menu, which
// unmounts as soon as the ZIP click closes it — a per-instance ref would reset
// to false on the next mount and let a second concurrent snapshot/ZIP pipeline
// start. A module singleton makes the in-flight guard survive remounts.
let exportInFlight = false;
export function useExportVideo() {
const [exporting, setExporting] = useState(false);
const exportingRef = useRef(false);
const { t } = useI18n();
const exportVideo = useCallback(
async (resolution: VideoResolution = '1080p') => {
if (exportingRef.current) return;
if (exportInFlight) return;
const { stage, scenes } = useStageStore.getState();
if (!stage?.id || scenes.length === 0) {
toast.error(t('export.videoNoScenes'));
return;
}
exportingRef.current = true;
exportInFlight = true;
setExporting(true);
const toastId = toast.loading(t('export.videoCompiling'));
const { width, height } = VIDEO_RESOLUTIONS[resolution];
try {
const latest = await db.stages.get(stage.id).catch(() => undefined);
const stageName = latest?.name || stage.name || 'classroom';
// 1. DI deps (Dexie durations + asset presence) → 2. pure compile to IR.
const deps = await createVideoTimelineDeps({ stage: { id: stage.id }, scenes });
const ir = compileVideoTimeline({ stage: { id: stage.id, name: stageName }, scenes }, deps);
// 3. emit the Hyperframes project text.
const project = emitHyperframes(ir, { width, height });
// 4. collect asset bytes (slide snapshots + narration/media).
toast.loading(t('export.videoRendering'), { id: toastId });
const { blobs, missing } = await collectVideoAssets(ir, scenes, deps.records, {
frameWidth: width,
});
const { zipBlob, stageName, missingCount, errorCount } = await buildExportZip(resolution);
// 5. package the self-contained ZIP.
toast.loading(t('export.videoPackaging'), { id: toastId });
const zipBlob = await packageVideoZip(project, blobs);
saveAs(zipBlob, `${sanitizeFilename(stageName)}-video.zip`);
toast.success(t('export.videoSuccess'), { id: toastId });
const errors = ir.diagnostics.filter((d) => d.severity !== 'info').length;
if (missing.length > 0 || errors > 0) {
toast.warning(t('export.videoWarnings', { assets: missing.length, diagnostics: errors }));
if (missingCount > 0 || errorCount > 0) {
toast.warning(
t('export.videoWarnings', { assets: missingCount, diagnostics: errorCount }),
);
}
} catch (error) {
log.error('Video export failed:', error);
toast.error(t('export.videoFailed'), { id: toastId });
if (error instanceof NoScenesError) {
toast.error(t('export.videoNoScenes'), { id: toastId });
} else {
log.error('Video export failed:', error);
toast.error(t('export.videoFailed'), { id: toastId });
}
} finally {
exportingRef.current = false;
exportInFlight = false;
setExporting(false);
}
},

View File

@ -0,0 +1,35 @@
'use client';
/**
* `useRenderVideo` — thin React facade over the global {@link useVideoRenderStore}.
*
* The render lifecycle (build ZIP → upload → poll → download) and the selected
* options both live in the store, so they survive the export menu unmounting
* (scene switches, menu close) and can be observed from anywhere — e.g. the
* persistent ring on the export button. This hook just binds `t` and re-exports
* the reactive slice the menu needs.
*/
import { useCallback } from 'react';
import { useI18n } from '@/lib/hooks/use-i18n';
import { useVideoRenderStore } from '@/lib/store/video-render';
export function useRenderVideo() {
const { t } = useI18n();
const status = useVideoRenderStore((s) => s.status);
const percent = useVideoRenderStore((s) => s.percent);
const etaMs = useVideoRenderStore((s) => s.etaMs);
const options = useVideoRenderStore((s) => s.options);
const setOptions = useVideoRenderStore((s) => s.setOptions);
const startRender = useVideoRenderStore((s) => s.startRender);
const renderVideo = useCallback(() => startRender(t), [startRender, t]);
return {
rendering: status === 'compiling' || status === 'rendering',
percent,
etaMs,
options,
setOptions,
renderVideo,
};
}

View File

@ -124,6 +124,66 @@ function renderNarration(scene: VideoTimelineScene): string[] {
});
}
/**
* Subtitle overlay: one absolutely-positioned caption band at the bottom of the
* stage, plus one `<div>` per cue stacked in the *same* absolute slot within it.
* The captions are *burned in* — the paused GSAP timeline reveals each cue at
* its `startMs` and hides it at its `endMs`, so Chromium's frame capture bakes
* them into the video (the producer has no subtitle track of its own). Cue
* timings are the IR's, which now derive from real audio durations, so they
* stay aligned with the narration.
*
* Every cue is stacked in one grid cell of the band and toggled with
* `display:none`/`inline-block`. Two things matter here, both regressions from
* the first cut:
* - Inactive cues must be **removed from layout** (`display:none`), not merely
* hidden (`visibility:hidden`): a hidden-but-laid-out cue still occupies a
* row, so with many cues the band grows several rows tall and the active cue
* drifts upward into the slide/title area.
* - All cues share **one grid cell** (`grid-area:1/1`), so the active cue
* always sits in the same spot regardless of which cue it is.
*
* Returns the overlay HTML and the `tl.set` statements that toggle display.
*/
function renderSubtitles(
ir: VideoTimeline,
height: number,
): { html: string; statements: string[] } {
const cues = ir.subtitles.filter((c) => c.text.trim());
if (cues.length === 0) return { html: '', statements: [] };
// Scale caption type to the render height so it reads at any resolution.
const fontPx = Math.max(16, Math.round(height * 0.033));
const padV = Math.round(fontPx * 0.35);
const padH = Math.round(fontPx * 0.7);
const bottom = Math.round(height * 0.055);
// Each cue occupies the same grid cell and is hidden (display:none) until its
// window, so inactive cues take no layout space and never shift the active one.
const cueDivs = cues
.map(
(c, i) =>
` <div id="subtitle-cue-${i}" style="grid-area:1/1;display:none;justify-self:center;max-width:80%;padding:${padV}px ${padH}px;background:rgba(0,0,0,0.66);color:#fff;font-size:${fontPx}px;line-height:1.3;border-radius:${padV}px;white-space:pre-wrap;text-shadow:0 1px 2px rgba(0,0,0,0.9)">${escapeHtml(c.text)}</div>`,
)
.join('\n');
const html = [
`<div id="subtitles" style="position:absolute;left:0;right:0;bottom:${bottom}px;z-index:50;display:grid;justify-items:center;text-align:center;pointer-events:none;font-family:system-ui,sans-serif">`,
cueDivs,
`</div>`,
].join('\n');
// Toggle each cue with `display` so hidden cues leave the flow entirely
// (visibility:hidden would keep their box and push the active cue out of slot).
const statements: string[] = [];
for (let i = 0; i < cues.length; i++) {
const c = cues[i];
statements.push(`tl.set('#subtitle-cue-${i}',{display:'inline-block'},${sec(c.startMs)});`);
statements.push(`tl.set('#subtitle-cue-${i}',{display:'none'},${sec(c.endMs)});`);
}
return { html, statements };
}
function renderReadme(project: {
compositionId: string;
width: number;
@ -198,6 +258,10 @@ export function emitHyperframes(
}
}
// Burned-in subtitle overlay, driven by the same paused timeline.
const subtitles = renderSubtitles(ir, height);
statements.push(...subtitles.statements);
// Extend the timeline to the full composition length even if the last tween
// ends earlier, so clips (esp. video/audio) are not cut short.
statements.push(`tl.set({}, {}, ${totalSec});`);
@ -218,6 +282,7 @@ export function emitHyperframes(
<div id="${compositionId}" data-composition-id="${compositionId}" data-start="0" data-duration="${totalSec}" data-width="${width}" data-height="${height}" style="position:relative;width:${width}px;height:${height}px;overflow:hidden;background:#000">
${sceneHtml.filter(Boolean).join('\n')}
${effectHtml.join('\n')}
${subtitles.html}
</div>
<script src="${escapeHtml(gsapVendorPath)}"></script>
<script>

View File

@ -0,0 +1,6 @@
node_modules
dist
npm-debug.log
.env
.env.*
*.md

3
render-service/.gitignore vendored Normal file
View File

@ -0,0 +1,3 @@
node_modules
dist
*.log

63
render-service/Dockerfile Normal file
View File

@ -0,0 +1,63 @@
# Isolated render service: Node 22 + system Chromium + FFmpeg.
#
# Debian (bookworm-slim), NOT Alpine: @hyperframes/producer drives Chromium via
# puppeteer, and Chromium + its shared libraries are far simpler to provision on
# glibc/Debian than on musl/Alpine. We install the distro Chromium and point
# puppeteer at it (PUPPETEER_EXECUTABLE_PATH) so no second browser is downloaded.
FROM node:22-bookworm-slim AS base
ENV PUPPETEER_SKIP_DOWNLOAD=true \
PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium \
NODE_ENV=production
# chromium + ffmpeg + the fonts/libs a headless Chrome needs to render text and
# composite frames. iptables lets the entrypoint lock down egress (block the
# untrusted Chromium from reaching the app); ca-certificates covers TLS for any
# asset the composition might still reference before lockdown.
RUN apt-get update \
&& apt-get install -y --no-install-recommends \
chromium \
ffmpeg \
iptables \
ca-certificates \
fonts-liberation \
fonts-noto-color-emoji \
fonts-noto-cjk \
&& rm -rf /var/lib/apt/lists/*
WORKDIR /app
# ---- Dependencies (cached layer) ----
FROM base AS deps
COPY package.json package-lock.json ./
RUN npm ci --omit=dev --no-audit --no-fund
# ---- Runner ----
FROM base AS runner
# Non-root: Chromium must run with --no-sandbox in a container, so drop privileges.
RUN groupadd --system --gid 1001 render \
&& useradd --system --uid 1001 --gid render --home-dir /app render \
&& mkdir -p /tmp/openmaic-renders \
&& chown -R render:render /app /tmp/openmaic-renders
COPY --from=deps /app/node_modules ./node_modules
COPY --chown=render:render package.json tsconfig.json ./
COPY --chown=render:render src ./src
COPY docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
RUN chmod +x /usr/local/bin/docker-entrypoint.sh
ENV PORT=9000 \
PRODUCER_TMP_PROJECT_DIR=/tmp/openmaic-renders
# NOTE: we intentionally do NOT set `USER render` here. The container starts as
# root so the entrypoint can install the iptables egress lockdown (needs
# CAP_NET_ADMIN), then drops to the unprivileged `render` user via setpriv for
# the Node/Chromium process. See docker-entrypoint.sh.
EXPOSE 9000
# The entrypoint applies the egress lockdown, drops privileges, then runs tsx on
# the TypeScript entry. NOTE: the entry is `main.ts`, not `server.ts`, because
# @hyperframes/producer auto-starts its own bundled server when the process
# entry path ends with `/src/server.ts` (or `/public-server.js`).
ENTRYPOINT ["/usr/local/bin/docker-entrypoint.sh"]

136
render-service/README.md Normal file
View File

@ -0,0 +1,136 @@
# @openmaic/render-service
Isolated MP4 render service for OpenMAIC's classroom video export (issue #866).
The main app compiles a classroom to a self-contained Hyperframes project ZIP
(`index.html` + `assets/` + vendored GSAP) entirely in the browser. This service
takes that ZIP and renders it to an MP4 with [`@hyperframes/producer`], which
drives headless Chromium (frame capture) + FFmpeg (encode). It runs in its own
Node 22 container because the producer needs Node ≥ 22, Chromium, and FFmpeg —
none of which belong in the Next.js runtime.
It is an **opt-in capability**: when the app has no `RENDER_SERVICE_URL`
configured, in-app export degrades to downloading the project ZIP for local CLI
rendering. Nothing here is required for the app to run.
## HTTP API
Rendering is asynchronous (a 10-minute video can take tens of minutes): submit,
poll, then download. Job ids are opaque.
| Method + path | Purpose |
| --- | --- |
| `POST /render` | multipart: `project` (the ZIP) + `fps`, `quality`, `format` fields → `202 { jobId }` |
| `GET /render/:jobId` | `{ status, progress, currentStage, framesRendered, totalFrames, done, error }` |
| `GET /render/:jobId/download` | stream the MP4 (or `302` to a presigned URL) once `succeeded` |
| `DELETE /render/:jobId` | cancel a queued/running job |
| `GET /health` | `{ ok: true }` |
`status` is one of `queued | running | succeeded | failed | cancelled`;
`progress` is `0..1`.
## Environment
| Var | Default | Meaning |
| --- | --- | --- |
| `PORT` | `9000` | Listen port. |
| `RENDER_MAX_CONCURRENCY` | `2` | Renders that execute simultaneously; extras queue FIFO. |
| `RENDER_MAX_CONCURRENT_EXTRACTIONS` | `2` | Archives expanded simultaneously; bounds the RAM multiplier (≈ this × max expanded size). |
| `RENDER_MAX_JOBS_PER_USER` | `1` | Active jobs allowed per client identity (0 disables the guard — see note below). |
| `RENDER_MAX_QUEUE` | `20` | Max jobs in the system (reserved+queued+running) before new submits get `429`. |
| `RENDER_JOB_TTL_MS` | `1800000` | How long finished jobs + artifacts live before cleanup. |
| `RENDER_JOB_DEADLINE_MS` | `2700000` | Hard per-job wall-clock deadline; overruns are aborted and marked **failed**. |
| `RENDER_MAX_UPLOAD_BYTES` | `314572800` | Max compressed archive size accepted (300 MB); enforced on real bytes, before buffering. |
| `RENDER_MAX_ENTRIES` | `5000` | Max entries allowed in the archive. |
| `RENDER_MAX_ENTRY_BYTES` | `209715200` | Max expanded size of any single entry (200 MB). |
| `RENDER_MAX_EXPANDED_BYTES` | `536870912` | Max total expanded size across all entries (512 MB). |
| `RENDER_MAX_COMPRESSION_RATIO` | `200` | Max expanded:compressed ratio per entry (ZIP-bomb guard). |
| `RENDER_EGRESS_LOCKDOWN` | `true` | Install the iptables egress lockdown at startup (needs root + `CAP_NET_ADMIN`); **fails closed** — the container exits if the rules can't be applied. Set `false` to run unisolated. |
| `PRODUCER_TMP_PROJECT_DIR` | `/tmp/openmaic-renders` | Scratch dir for unzipped projects + outputs. |
| `PUPPETEER_EXECUTABLE_PATH` | `/usr/bin/chromium` | System Chromium (set in the image). |
Client identity for the per-user guard is taken from the `x-openmaic-client`
header, which the app's proxy sets. A client-supplied `userId` form field is
ignored. The app derives that header from `x-forwarded-for`/`x-real-ip` **only
when the operator sets `TRUST_PROXY_HEADERS=true`** (and a real reverse proxy
overwrites those headers); otherwise all callers share one `direct` identity, so
the default directly-exposed Compose topology can't be gamed by spoofing
forwarding headers.
> **Per-user guard vs. shared identity.** When identity can't be trusted (no
> reverse proxy → everyone is `direct`), a `RENDER_MAX_JOBS_PER_USER` of 1 would
> throttle the *whole deployment* to one render at a time. The default Compose
> therefore sets `RENDER_MAX_JOBS_PER_USER=0` (guard off) and relies on
> `RENDER_MAX_CONCURRENCY` + `RENDER_MAX_QUEUE`. Enable the per-user guard only
> behind a trusted proxy that supplies a real per-user identity.
## Security / isolation
The uploaded archive is untrusted, so extraction is bounded *before* any bytes
are decompressed (entry count, per-entry and total expanded size, and
compression ratio — see the limits above), guarding against ZIP bombs.
Extraction runs on fflate's worker (off the event loop) and is concurrency-capped
so admitted jobs can't stack the per-archive RAM ceiling.
The composition HTML is then executed in headless Chromium. Two boundaries keep
that untrusted page contained:
- **No inbound-to-app bridge.** The container's entrypoint installs an iptables
egress lockdown (drop all outbound except loopback + replies on app-initiated
connections), so Chromium can't open connections back to the app — even though
they share the Compose network so the app can reach the service. This needs the
container to run with `CAP_NET_ADMIN` (`cap_add: [NET_ADMIN]`, already set in
the Compose file). With `RENDER_EGRESS_LOCKDOWN=true` (the default) the entrypoint
**fails closed**: if the rules can't be applied (missing capability, backend
mismatch) the container exits non-zero rather than start an unisolated service
the app would still advertise as healthy. An operator who knowingly accepts an
unisolated standalone setup opts out with `RENDER_EGRESS_LOCKDOWN=false`.
`scripts/egress-smoke.sh <image>` asserts the boundary end-to-end (lockdown
active, loopback works, a new outbound connection is blocked).
- **No internet.** In Compose the `render` network is `internal: true` (no host
or internet gateway). The export ZIP bundles every asset (and GSAP) at build
time, so the render needs no outbound at all.
**When running standalone, place the service on an isolated network yourself**
(and keep the egress lockdown on, or accept the risk with the toggle) — it needs
no outbound access.
## Run
### Docker (recommended)
The root `docker-compose.yml` wires this service under the `video-export`
profile and points the app at it:
```bash
docker compose --profile video-export up --build
```
### Standalone (development)
Requires Node ≥ 22, plus Chromium and FFmpeg on `PATH`:
```bash
cd render-service
npm install
PUPPETEER_EXECUTABLE_PATH=$(which chromium) npm start
```
## Scalability
The service is built with two swap points so it can move from a single OSS host
to a horizontally-scaled demo deployment without changing the HTTP contract or
the app:
- **`JobStore`** (`src/job-store.ts`) — Part A ships `InMemoryJobStore`. A
`RedisJobStore` implementing the same interface lets any replica serve poll /
download requests.
- **`ArtifactStore`** (`src/artifact-store.ts`) — Part A ships
`LocalDiskArtifactStore` (streams through the app proxy). An `S3ArtifactStore`
whose `locate` returns a presigned URL makes the download route `302` the
browser straight to object storage, bypassing the proxy.
Chunked distributed rendering (`@hyperframes/producer/distributed`) to cut
single-job latency is a further, separate follow-up.
[`@hyperframes/producer`]: https://www.npmjs.com/package/@hyperframes/producer

View File

@ -0,0 +1,64 @@
#!/bin/sh
# Render-service entrypoint.
#
# The service renders UNTRUSTED, uploaded HTML in Chromium. The export ZIP is
# fully self-contained (all assets + vendored GSAP are bundled at build time and
# served to Chromium over loopback), so the render needs ZERO outbound network.
# We enforce that here: block all egress except loopback and replies on already
# established (app-initiated) connections. This is the boundary that stops the
# untrusted page from initiating connections back to the app (e.g. the compose
# `openmaic` service) or anywhere else, even though both share a Docker network.
#
# Requires the container to start as root with CAP_NET_ADMIN (compose:
# `cap_add: [NET_ADMIN]`). We install the rules as root, then drop to the
# unprivileged `render` user for the Node process.
#
# FAIL CLOSED: when the lockdown is requested (RENDER_EGRESS_LOCKDOWN=true, the
# default) but cannot be installed, we EXIT non-zero rather than start an
# unisolated service that /health would still report as healthy — the app would
# otherwise advertise MP4 rendering while Chromium could reach the app. An
# operator who knowingly accepts an unisolated standalone setup must opt out
# explicitly with RENDER_EGRESS_LOCKDOWN=false.
set -eu
lockdown() {
# ESTABLISHED,RELATED lets the Hono API respond to the app's inbound requests;
# loopback lets the producer's file server + Chromium talk locally. Everything
# else outbound (new connections, DNS to resolve `openmaic`, etc.) is dropped.
# IPv4 rules must all succeed; IPv6 is best-effort (the stack/table may be
# absent), but when present we still default-drop so v6 can't be an escape.
iptables -A OUTPUT -o lo -j ACCEPT || return 1
iptables -A OUTPUT -m state --state ESTABLISHED,RELATED -j ACCEPT || return 1
iptables -P OUTPUT DROP || return 1
if command -v ip6tables >/dev/null 2>&1; then
ip6tables -A OUTPUT -o lo -j ACCEPT 2>/dev/null || true
ip6tables -A OUTPUT -m state --state ESTABLISHED,RELATED -j ACCEPT 2>/dev/null || true
ip6tables -P OUTPUT DROP 2>/dev/null || true
fi
return 0
}
if [ "${RENDER_EGRESS_LOCKDOWN:-true}" = "true" ]; then
if [ "$(id -u)" != "0" ]; then
echo "[render-service] FATAL: egress lockdown requested but not running as root (need root + CAP_NET_ADMIN). Set RENDER_EGRESS_LOCKDOWN=false to run unisolated." >&2
exit 1
fi
if ! command -v iptables >/dev/null 2>&1; then
echo "[render-service] FATAL: egress lockdown requested but iptables is not installed. Set RENDER_EGRESS_LOCKDOWN=false to run unisolated." >&2
exit 1
fi
if ! lockdown; then
echo "[render-service] FATAL: egress lockdown requested but iptables rules failed to apply (missing CAP_NET_ADMIN or backend mismatch). Refusing to start unisolated. Set RENDER_EGRESS_LOCKDOWN=false to override." >&2
exit 1
fi
echo "[render-service] egress lockdown active (outbound blocked except loopback)"
else
echo "[render-service] WARNING: egress lockdown DISABLED (RENDER_EGRESS_LOCKDOWN=false). Chromium can reach the Docker network — only safe on a network you have isolated yourself." >&2
fi
# Drop privileges to the unprivileged render user for the Node process. When
# already running as that user (no lockdown / non-root start), exec directly.
if [ "$(id -u)" = "0" ]; then
exec setpriv --reuid=render --regid=render --init-groups node_modules/.bin/tsx src/main.ts
fi
exec node_modules/.bin/tsx src/main.ts

2816
render-service/package-lock.json generated Normal file

File diff suppressed because it is too large Load Diff

View File

@ -0,0 +1,31 @@
{
"name": "@openmaic/render-service",
"version": "0.1.0",
"private": true,
"type": "module",
"description": "Isolated Node 22 + Chromium + FFmpeg service that renders exported Hyperframes projects to MP4 (OpenMAIC issue #866).",
"engines": {
"node": ">=22"
},
"scripts": {
"dev": "tsx watch src/main.ts",
"start": "tsx src/main.ts",
"typecheck": "tsc --noEmit",
"test": "vitest run"
},
"dependencies": {
"@hono/node-server": "^1.13.7",
"@hyperframes/producer": "^0.7.58",
"fflate": "^0.8.2",
"hono": "^4.6.14",
"tsx": "^4.19.2"
},
"devDependencies": {
"@types/node": "^22.10.2",
"typescript": "^5.7.2",
"vitest": "^4.1.10"
},
"overrides": {
"esbuild": "0.28.1"
}
}

View File

@ -0,0 +1,40 @@
#!/bin/sh
# Container egress smoke: verify the render service's security boundary holds —
# a NEW outbound connection from the render container is blocked, while loopback
# (the producer's file server) and inbound-response traffic still work.
#
# Run against a built image (default: openmaic-render-service:pr937):
# render-service/scripts/egress-smoke.sh [image]
#
# Requires Docker with CAP_NET_ADMIN available (the compose default). Exits 0
# only if: the container boots with lockdown active, /health answers over
# loopback, and a new outbound connection is refused/timed out.
set -eu
IMAGE="${1:-openmaic-render-service:pr937}"
NAME="rs-egress-smoke-$$"
cleanup() { docker rm -f "$NAME" >/dev/null 2>&1 || true; }
trap cleanup EXIT
echo "[smoke] starting $IMAGE with CAP_NET_ADMIN..."
docker run --rm -d --name "$NAME" --cap-add NET_ADMIN "$IMAGE" >/dev/null
sleep 6
echo "[smoke] checking lockdown is reported active..."
docker logs "$NAME" 2>&1 | grep -q "egress lockdown active" || {
echo "[smoke] FAIL: lockdown not active in logs"; docker logs "$NAME" 2>&1 | tail; exit 1;
}
echo "[smoke] loopback /health must answer..."
HEALTH=$(docker exec "$NAME" node -e 'fetch("http://127.0.0.1:9000/health").then(r=>r.json()).then(j=>{console.log(j.ok===true?"OK":"BAD");process.exit(0)}).catch(()=>{console.log("ERR");process.exit(0)})')
[ "$HEALTH" = "OK" ] || { echo "[smoke] FAIL: loopback health = $HEALTH"; exit 1; }
echo "[smoke] a NEW outbound connection must be blocked..."
OUT=$(docker exec "$NAME" node -e 'const s=require("net").connect({host:"deb.debian.org",port:80});s.setTimeout(4000);s.on("connect",()=>{console.log("REACHABLE");process.exit(0)});s.on("timeout",()=>{console.log("BLOCKED");process.exit(0)});s.on("error",e=>{console.log("BLOCKED_"+e.code);process.exit(0)})')
case "$OUT" in
BLOCKED*) echo "[smoke] outbound blocked ($OUT)";;
*) echo "[smoke] FAIL: outbound was $OUT (expected blocked)"; exit 1;;
esac
echo "[smoke] PASS: lockdown active, loopback works, egress blocked."

View File

@ -0,0 +1,42 @@
/**
* ArtifactStore — the seam for where rendered MP4s live and how they're served.
*
* Part A ships {@link LocalDiskArtifactStore}: the MP4 stays on the service's
* disk and `locate` returns a `file` location the download route streams
* through the Next proxy. A demo deployment drops in an `S3ArtifactStore` whose
* `locate` returns a `url` location (a presigned URL); the download route then
* responds 302 and the browser pulls the file straight from object storage,
* bypassing the proxy's bandwidth/memory. Neither the route nor the app change.
*/
export type ArtifactLocation = { kind: 'file'; path: string } | { kind: 'url'; href: string };
export interface ArtifactStore {
/** Register the rendered output for a job. */
put(jobId: string, sourcePath: string): Promise<void>;
/** Where to fetch the job's artifact, or null if none/expired. */
locate(jobId: string): Promise<ArtifactLocation | null>;
/** Drop the artifact (best-effort). */
remove(jobId: string): Promise<void>;
}
/**
* Keeps the MP4 where the producer wrote it (the job's own output dir) and
* hands back its path. No copying — the render already targets a per-job path.
*/
export class LocalDiskArtifactStore implements ArtifactStore {
private readonly paths = new Map<string, string>();
async put(jobId: string, sourcePath: string): Promise<void> {
this.paths.set(jobId, sourcePath);
}
async locate(jobId: string): Promise<ArtifactLocation | null> {
const path = this.paths.get(jobId);
return path ? { kind: 'file', path } : null;
}
async remove(jobId: string): Promise<void> {
this.paths.delete(jobId);
}
}

View File

@ -0,0 +1,46 @@
/**
* A byte-capped wrapper around a request body stream.
*
* The Next proxy already bounds the forwarded body, but this service can also be
* reached directly (its contract is public and demo deployments may expose it),
* so it enforces its own ceiling. `Content-Length` is client-supplied and
* omitted on chunked uploads, so counting the declared length is not enough —
* this counts the *actual* bytes as they flow and aborts the stream the instant
* they exceed `capBytes`, before `formData()` / `arrayBuffer()` can buffer them.
*
* Returns the capped stream plus an `exceeded()` probe so the caller can tell a
* cap trip apart from an ordinary malformed-body error after the consumer throws.
*/
export interface CappedBody {
stream: ReadableStream<Uint8Array>;
exceeded: () => boolean;
}
export function capBodyStream(body: ReadableStream<Uint8Array>, capBytes: number): CappedBody {
let total = 0;
let tripped = false;
const reader = body.getReader();
const stream = new ReadableStream<Uint8Array>({
async pull(controller) {
const { done, value } = await reader.read();
if (done) {
controller.close();
return;
}
total += value.byteLength;
if (total > capBytes) {
tripped = true;
controller.error(new Error('Upload exceeds the maximum allowed size'));
await reader.cancel().catch(() => {});
return;
}
controller.enqueue(value);
},
cancel(reason) {
void reader.cancel(reason).catch(() => {});
},
});
return { stream, exceeded: () => tripped };
}

View File

@ -0,0 +1,63 @@
/**
* Config — every knob the render service reads from the environment, resolved
* once at import. Defaults suit an OSS single-host deployment; the demo layer
* only tunes values (and, later, points the store factories at Redis/S3).
*/
function intEnv(name: string, fallback: number): number {
const raw = process.env[name];
if (!raw) return fallback;
const n = Number.parseInt(raw, 10);
return Number.isFinite(n) && n > 0 ? n : fallback;
}
/**
* Like {@link intEnv} but accepts 0 as a valid value (still rejects negatives /
* non-numeric). Used for knobs where 0 has a distinct meaning — e.g. a per-user
* limit of 0 disables the guard entirely, as documented.
*/
function intEnvAllowZero(name: string, fallback: number): number {
const raw = process.env[name];
if (!raw) return fallback;
const n = Number.parseInt(raw, 10);
return Number.isFinite(n) && n >= 0 ? n : fallback;
}
const MB = 1024 * 1024;
export const config = {
port: intEnv('PORT', 9000),
/** Renders that execute simultaneously; extras queue FIFO. */
maxConcurrency: intEnv('RENDER_MAX_CONCURRENCY', 2),
/**
* Archives extracted simultaneously. Extraction holds the expanded archive in
* memory, so this bounds the RAM multiplier (≈ this × maxExpandedBytes) even
* when many jobs are admitted at once. Defaults to the render concurrency.
*/
maxConcurrentExtractions: intEnv('RENDER_MAX_CONCURRENT_EXTRACTIONS', 2),
/** Active (queued+running) jobs allowed per client identity. 0 disables the guard. */
maxJobsPerUser: intEnvAllowZero('RENDER_MAX_JOBS_PER_USER', 1),
/** Max jobs allowed in the system (queued+running) before new submits are rejected. */
maxQueue: intEnv('RENDER_MAX_QUEUE', 20),
/** How long a finished job's record + artifacts live before the sweeper reaps them. */
jobTtlMs: intEnv('RENDER_JOB_TTL_MS', 30 * 60 * 1000),
/**
* Hard per-job wall-clock deadline. A render exceeding this is aborted and
* marked failed so a hung job can't hold a concurrency slot + scratch forever.
*/
jobDeadlineMs: intEnv('RENDER_JOB_DEADLINE_MS', 45 * 60 * 1000),
/** Root dir for unzipped projects and rendered outputs. */
tmpDir: process.env.PRODUCER_TMP_PROJECT_DIR || '/tmp/openmaic-renders',
// ---- Archive limits (ZIP-bomb / DoS guards, enforced before extraction) ----
/** Max compressed upload size accepted (bytes). */
maxUploadBytes: intEnv('RENDER_MAX_UPLOAD_BYTES', 300 * MB),
/** Max number of entries in the archive. */
maxEntries: intEnv('RENDER_MAX_ENTRIES', 5000),
/** Max expanded size of any single entry (bytes). */
maxEntryBytes: intEnv('RENDER_MAX_ENTRY_BYTES', 200 * MB),
/** Max total expanded size across all entries (bytes). */
maxExpandedBytes: intEnv('RENDER_MAX_EXPANDED_BYTES', 512 * MB),
/** Max expanded:compressed ratio for a single entry (catches deep-compression bombs). */
maxCompressionRatio: intEnv('RENDER_MAX_COMPRESSION_RATIO', 200),
} as const;

View File

@ -0,0 +1,81 @@
/**
* JobStore — the seam that makes the render service horizontally scalable
* later without touching the HTTP contract or the app.
*
* Part A ships {@link InMemoryJobStore} (single-process, fine for OSS
* single-host). A demo deployment drops in a `RedisJobStore` implementing this
* same interface so poll/download requests can be served by any replica. The
* routes only ever see `JobStore`.
*/
import type { RenderJobRecord, RenderJobStatus } from './types.js';
import { isTerminal } from './types.js';
export interface JobStore {
create(record: RenderJobRecord): Promise<void>;
get(id: string): Promise<RenderJobRecord | null>;
/** Merge a partial patch into an existing record; no-op if it's gone. */
update(id: string, patch: Partial<RenderJobRecord>): Promise<void>;
remove(id: string): Promise<void>;
list(): Promise<RenderJobRecord[]>;
/** Count of active (queued or running) jobs for a user — for the per-user guard. */
countActiveForUser(userId: string): Promise<number>;
}
/** Process-local job registry backed by a Map, with a TTL sweeper for finished jobs. */
export class InMemoryJobStore implements JobStore {
private readonly jobs = new Map<string, RenderJobRecord>();
private readonly sweeper: NodeJS.Timeout;
/**
* @param ttlMs finished jobs older than this are reaped
* @param onReap called with a reaped record so the caller can delete its temp files
*/
constructor(
private readonly ttlMs: number,
private readonly onReap?: (record: RenderJobRecord) => void,
) {
this.sweeper = setInterval(() => this.sweep(), 60_000);
// Don't keep the process alive just for the sweeper.
this.sweeper.unref?.();
}
async create(record: RenderJobRecord): Promise<void> {
this.jobs.set(record.id, record);
}
async get(id: string): Promise<RenderJobRecord | null> {
return this.jobs.get(id) ?? null;
}
async update(id: string, patch: Partial<RenderJobRecord>): Promise<void> {
const existing = this.jobs.get(id);
if (!existing) return;
this.jobs.set(id, { ...existing, ...patch, updatedAtMs: Date.now() });
}
async remove(id: string): Promise<void> {
this.jobs.delete(id);
}
async list(): Promise<RenderJobRecord[]> {
return [...this.jobs.values()];
}
async countActiveForUser(userId: string): Promise<number> {
let n = 0;
for (const job of this.jobs.values()) {
if (job.userId === userId && !isTerminal(job.status)) n++;
}
return n;
}
private sweep(): void {
const now = Date.now();
for (const [id, job] of this.jobs) {
if (isTerminal(job.status) && now - job.updatedAtMs > this.ttlMs) {
this.jobs.delete(id);
this.onReap?.(job);
}
}
}
}

268
render-service/src/main.ts Normal file
View File

@ -0,0 +1,268 @@
/**
* @openmaic/render-service — HTTP entrypoint.
*
* Renders exported Hyperframes projects (the ZIP the app builds with
* `packageVideoZip`) to MP4 using `@hyperframes/producer`, isolated in a
* Node 22 + Chromium + FFmpeg container (issue #866).
*
* The contract is intentionally minimal and stable so the internals (in-memory
* vs Redis job store, local-disk vs S3 artifacts) can be swapped for a
* demo-scale deployment without the app noticing:
*
* POST /render multipart: project(zip) + fps/quality/format → 202 { jobId }
* GET /render/:jobId → { status, progress, currentStage, done, ... }
* GET /render/:jobId/download → stream MP4 (or 302 to a presigned URL)
* DELETE /render/:jobId → cancel
* GET /health → { ok: true }
*
* NOTE: this file must NOT be named `server.ts`. `@hyperframes/producer`'s main
* module auto-starts its own bundled HTTP server (on PRODUCER_PORT, default
* 9847) as an import side effect when the process entry path ends with
* `/src/server.ts` or `/public-server.js`. We use the producer as a library, so
* the entrypoint is `main.ts` to avoid spawning that phantom server.
*/
import { createReadStream } from 'node:fs';
import { mkdir, stat } from 'node:fs/promises';
import { Readable } from 'node:stream';
import { serve } from '@hono/node-server';
import { Hono } from 'hono';
import { config } from './config.js';
import { InMemoryJobStore } from './job-store.js';
import { LocalDiskArtifactStore } from './artifact-store.js';
import {
RenderManager,
RenderRejectedError,
makeProjectDir as defaultMakeProjectDir,
} from './render-manager.js';
import { InvalidProjectError, unzipProject as defaultUnzipProject } from './unzip.js';
import { capBodyStream } from './capped-stream.js';
import { Semaphore } from './semaphore.js';
import type { JobStore } from './job-store.js';
import type { ArtifactStore } from './artifact-store.js';
import { isTerminal, type RenderOptions } from './types.js';
/** Thrown inside the gated section for an oversized body (→ HTTP 413). */
class UploadTooLargeError extends Error {}
/** Thrown inside the gated section for a malformed request (→ HTTP 400). */
class BadRequestError extends Error {}
/** Collaborators the app depends on; injectable so the routes are testable. */
export interface AppDeps {
jobs: JobStore;
artifacts: ArtifactStore;
manager: RenderManager;
/** Bounds concurrent *buffering + extraction* (the whole RAM-heavy section). */
extractionGate: Semaphore;
/** Extract a validated archive into a dir. Overridable in tests. */
unzipProject?: (zip: Uint8Array, destDir: string) => Promise<void>;
/** Create a fresh per-render scratch dir. Overridable in tests. */
makeProjectDir?: () => Promise<string>;
}
/** Parse + validate the multipart render options. Returns options or an error string. */
function parseOptions(form: FormData): RenderOptions | string {
const fps = Number.parseInt(String(form.get('fps') ?? '30'), 10);
if (!Number.isFinite(fps) || fps <= 0 || fps > 120) return 'Invalid fps';
const quality = String(form.get('quality') ?? 'standard');
if (quality !== 'draft' && quality !== 'standard' && quality !== 'high') {
return 'Invalid quality (expected draft|standard|high)';
}
const format = String(form.get('format') ?? 'mp4');
if (format !== 'mp4') return 'Unsupported format (only mp4)';
return { fps, quality, format };
}
/**
* Build the render-service HTTP app over injected collaborators.
*
* Admission ordering is the security boundary here:
* 1. `reserve()` (queue + per-identity) runs FIRST, before anything is read —
* a rejected caller never buffers a byte.
* 2. The whole RAM-heavy section — buffering the multipart (`formData()` is
* what materializes the uploaded file into memory), parsing, reading the
* file bytes, and extracting — runs INSIDE `extractionGate`. So at most
* `maxConcurrentExtractions` bodies are ever buffered at once; the rest wait
* with their request body still unconsumed (backpressured on the socket),
* not held in RAM. This is what stops a near-cap burst from OOMing the box.
*/
export function createApp(deps: AppDeps): Hono {
const { jobs, artifacts, manager, extractionGate } = deps;
const unzipProject = deps.unzipProject ?? defaultUnzipProject;
const makeProjectDir = deps.makeProjectDir ?? defaultMakeProjectDir;
const app = new Hono();
app.get('/health', (c) => c.json({ ok: true }));
app.post('/render', async (c) => {
// Reject an oversized body by declared length first (courtesy 413 for honest
// clients). The real bound is the byte-counting cap below, since
// Content-Length is client-supplied and absent on chunked uploads.
const declared = Number(c.req.header('content-length') ?? '0');
if (Number.isFinite(declared) && declared > config.maxUploadBytes) {
return c.json({ error: 'Upload too large' }, 413);
}
// Identity is derived by the trusted proxy (client IP) and passed in a header;
// a client-supplied multipart `userId` is deliberately ignored so it can't be
// rotated to bypass the per-identity guard.
const identity = c.req.header('x-openmaic-client')?.trim() || 'anonymous';
// Reserve a queue slot BEFORE the buffering permit, so a rejected caller
// (queue full / per-identity limit) never enters buffering or extraction.
let reservation;
try {
reservation = manager.reserve(identity);
} catch (error) {
if (error instanceof RenderRejectedError) return c.json({ error: error.message }, 429);
throw error;
}
// From here every failure MUST release the reservation.
let projectDir: string | undefined;
try {
// The ENTIRE memory-heavy section runs under the extraction permit:
// buffering the body (formData), reading the file, and unzipping. Requests
// beyond the permit wait here with their body still unconsumed, so only
// `maxConcurrentExtractions` bodies are buffered concurrently.
const jobId = await extractionGate.run(async () => {
const raw = c.req.raw;
let form: FormData;
let capped: ReturnType<typeof capBodyStream> | undefined;
try {
if (raw.body) {
// Cap the raw body as it streams into formData(), so a chunked /
// length-lying upload can't exceed the byte ceiling mid-parse.
capped = capBodyStream(raw.body, config.maxUploadBytes);
const bounded = new Request(raw.url, {
method: raw.method,
headers: raw.headers,
body: capped.stream,
// duplex is required for a streaming request body.
duplex: 'half',
} as RequestInit);
form = await bounded.formData();
} else {
form = await c.req.formData();
}
} catch {
if (capped?.exceeded()) throw new UploadTooLargeError('Upload too large');
throw new BadRequestError('Expected multipart/form-data');
}
const options = parseOptions(form);
if (typeof options === 'string') throw new BadRequestError(options);
const file = form.get('project');
if (!(file instanceof File)) {
throw new BadRequestError('Missing "project" file field');
}
projectDir = await makeProjectDir();
const bytes = new Uint8Array(await file.arrayBuffer());
await unzipProject(bytes, projectDir);
return manager.submit(reservation, projectDir, options);
});
return c.json({ jobId }, 202);
} catch (error) {
manager.release(reservation);
if (projectDir) await manager.cleanupProject(projectDir);
if (error instanceof UploadTooLargeError) return c.json({ error: error.message }, 413);
if (error instanceof BadRequestError) return c.json({ error: error.message }, 400);
if (error instanceof InvalidProjectError) return c.json({ error: error.message }, 400);
if (error instanceof RenderRejectedError) return c.json({ error: error.message }, 429);
throw error;
}
});
app.get('/render/:jobId', async (c) => {
const job = await jobs.get(c.req.param('jobId'));
if (!job) return c.json({ error: 'Job not found' }, 404);
return c.json({
jobId: job.id,
status: job.status,
progress: job.progress,
currentStage: job.currentStage,
framesRendered: job.framesRendered,
totalFrames: job.totalFrames,
error: job.error,
done: isTerminal(job.status),
});
});
app.delete('/render/:jobId', async (c) => {
const ok = await manager.cancel(c.req.param('jobId'));
if (!ok) return c.json({ error: 'Job not found' }, 404);
return c.json({ cancelled: true });
});
app.get('/render/:jobId/download', async (c) => {
const jobId = c.req.param('jobId');
const job = await jobs.get(jobId);
if (!job) return c.json({ error: 'Job not found' }, 404);
if (job.status !== 'succeeded') {
return c.json({ error: `Job not ready (status: ${job.status})` }, 409);
}
const location = await artifacts.locate(jobId);
if (!location) return c.json({ error: 'Artifact expired or missing' }, 404);
// Presigned-URL stores (demo layer) redirect the browser straight to storage.
if (location.kind === 'url') return c.redirect(location.href, 302);
const { size } = await stat(location.path).catch(() => ({ size: 0 }));
if (!size) return c.json({ error: 'Artifact missing on disk' }, 404);
const webStream = Readable.toWeb(createReadStream(location.path)) as ReadableStream;
return new Response(webStream, {
headers: {
'Content-Type': 'video/mp4',
'Content-Length': String(size),
'Content-Disposition': `attachment; filename="${jobId}.mp4"`,
},
});
});
return app;
}
/** Wire the production collaborators and start the server (skipped under tests). */
async function main(): Promise<void> {
const artifacts = new LocalDiskArtifactStore();
let manager: RenderManager;
const jobs = new InMemoryJobStore(config.jobTtlMs, (record) => {
// A reaped job's artifact + project dir go with it.
void artifacts.remove(record.id);
void manager.cleanupProject(record.projectDir);
});
manager = new RenderManager(jobs, artifacts);
const app = createApp({
jobs,
artifacts,
manager,
// Bounds concurrent buffering + extraction so the per-archive RAM ceiling
// can't stack across a burst of admitted requests.
extractionGate: new Semaphore(config.maxConcurrentExtractions),
});
// Ensure the scratch root exists before accepting work. On the documented
// standalone path nothing creates /tmp/openmaic-renders, so without this every
// makeProjectDir() would ENOENT. mktemp still creates a fresh subdir per job.
await mkdir(config.tmpDir, { recursive: true }).catch(() => {});
serve({ fetch: app.fetch, port: config.port }, (info) => {
// eslint-disable-next-line no-console
console.log(
`[render-service] listening on :${info.port} (maxConcurrency=${config.maxConcurrency})`,
);
});
}
// Only auto-start when run as the entrypoint, not when imported by tests.
if (process.env.RENDER_SERVICE_NO_LISTEN !== 'true') {
await main();
}

View File

@ -0,0 +1,262 @@
/**
* RenderManager — owns a render job's whole lifecycle: admission (concurrency,
* per-identity, and global-queue guards), the FIFO queue, driving
* `@hyperframes/producer`, feeding progress into the JobStore, registering the
* artifact, a per-job wall-clock deadline, and cleanup.
*
* Admission is split from enqueue so a caller is bounded *before* the expensive
* archive extraction: `reserve(identity)` atomically claims a slot (or throws),
* the route extracts, then `submit()` consumes the reservation. `release()`
* undoes a reservation if extraction/submit fails. All counters are plain
* fields mutated synchronously on the single-threaded event loop, so the
* check-then-increment is atomic; a Redis-backed store would make it
* distributed for the demo layer.
*/
import { randomUUID } from 'node:crypto';
import { mkdtemp, rm } from 'node:fs/promises';
import { join } from 'node:path';
import { createRenderJob, executeRenderJob } from '@hyperframes/producer';
import type { JobStore } from './job-store.js';
import type { ArtifactStore } from './artifact-store.js';
import type { RenderJobRecord, RenderOptions } from './types.js';
import { config } from './config.js';
/** Thrown when admission control rejects a submission (mapped to HTTP 429). */
export class RenderRejectedError extends Error {}
/** An accepted admission slot, returned by {@link RenderManager.reserve}. */
export interface Reservation {
identity: string;
consumed: boolean;
}
interface QueuedJob {
record: RenderJobRecord;
options: RenderOptions;
abort: AbortController;
}
export class RenderManager {
private running = 0;
private readonly queue: QueuedJob[] = [];
/** Live AbortControllers for queued/running jobs, keyed by jobId (for cancel). */
private readonly controllers = new Map<string, AbortController>();
/** Active (reserved + queued + running) count per identity, for the per-user guard. */
private readonly activeByIdentity = new Map<string, number>();
/** Reserved-but-not-yet-submitted count, included in the global queue-depth cap. */
private pending = 0;
constructor(
private readonly jobs: JobStore,
private readonly artifacts: ArtifactStore,
) {}
/** Total jobs occupying the system: reserved + queued + running. */
private get inSystem(): number {
return this.pending + this.queue.length + this.running;
}
/**
* Atomically claim an admission slot for `identity`, or throw
* {@link RenderRejectedError}. Must be paired with {@link consume} (on
* success) or {@link release} (on failure). Reserve before extracting the
* archive so a rejected caller never triggers a decompression.
*/
reserve(identity: string): Reservation {
if (this.inSystem >= config.maxQueue) {
throw new RenderRejectedError('The render queue is full; try again shortly.');
}
if (config.maxJobsPerUser > 0) {
const active = this.activeByIdentity.get(identity) ?? 0;
if (active >= config.maxJobsPerUser) {
throw new RenderRejectedError(
`A render is already in progress (limit ${config.maxJobsPerUser}).`,
);
}
}
this.activeByIdentity.set(identity, (this.activeByIdentity.get(identity) ?? 0) + 1);
this.pending += 1;
return { identity, consumed: false };
}
/** Release a reservation that will not become a job (extraction/submit failed). */
release(reservation: Reservation): void {
if (reservation.consumed) return;
reservation.consumed = true;
this.pending = Math.max(0, this.pending - 1);
this.decrementIdentity(reservation.identity);
}
private decrementIdentity(identity: string): void {
const next = (this.activeByIdentity.get(identity) ?? 0) - 1;
if (next <= 0) this.activeByIdentity.delete(identity);
else this.activeByIdentity.set(identity, next);
}
/**
* Enqueue a render against a held reservation. `projectDir` already contains
* the unzipped project (with index.html). Returns the new jobId.
*/
async submit(
reservation: Reservation,
projectDir: string,
options: RenderOptions,
): Promise<string> {
if (reservation.consumed) {
throw new RenderRejectedError('Reservation already used');
}
// Convert the reservation into a real queued job: the identity count stays,
// but it's no longer "pending".
reservation.consumed = true;
this.pending = Math.max(0, this.pending - 1);
const id = randomUUID();
const now = Date.now();
const record: RenderJobRecord = {
id,
userId: reservation.identity,
status: 'queued',
progress: 0,
currentStage: 'queued',
createdAtMs: now,
updatedAtMs: now,
projectDir,
};
// If persisting the job fails, the identity slot claimed at reserve() would
// otherwise leak (run() never runs to decrement it). Release it here.
try {
await this.jobs.create(record);
} catch (error) {
this.decrementIdentity(reservation.identity);
throw error;
}
const abort = new AbortController();
this.controllers.set(id, abort);
this.queue.push({ record, options, abort });
this.pump();
return id;
}
/** Cancel a queued or running job. */
async cancel(id: string): Promise<boolean> {
const controller = this.controllers.get(id);
if (!controller) return false;
controller.abort();
// If still queued (not yet running), drop it and finalize now.
const queuedIdx = this.queue.findIndex((q) => q.record.id === id);
if (queuedIdx >= 0) {
const [q] = this.queue.splice(queuedIdx, 1);
this.controllers.delete(id);
if (q.record.userId) this.decrementIdentity(q.record.userId);
await this.jobs.update(id, { status: 'cancelled', currentStage: 'cancelled' });
await this.cleanupProject(q.record.projectDir);
}
return true;
}
/** Start as many queued jobs as the concurrency budget allows. */
private pump(): void {
while (this.running < config.maxConcurrency && this.queue.length > 0) {
const next = this.queue.shift()!;
this.running++;
// Fire-and-forget: run() owns its own error handling and always decrements.
void this.run(next);
}
}
private async run({ record, options, abort }: QueuedJob): Promise<void> {
const { id, projectDir } = record;
const outputPath = join(projectDir, 'output.mp4');
// Wall-clock watchdog: abort a render that overruns the deadline so it can't
// hold a concurrency slot + scratch dir indefinitely. executeRenderJob
// honors the same AbortSignal we pass for user cancellation. `timedOut`
// distinguishes a deadline abort (→ failed) from a user cancel (→ cancelled).
let timedOut = false;
const deadline = setTimeout(() => {
timedOut = true;
abort.abort();
}, config.jobDeadlineMs);
if (typeof deadline.unref === 'function') deadline.unref();
try {
await this.jobs.update(id, { status: 'running', currentStage: 'preparing' });
const job = createRenderJob({
fps: options.fps,
quality: options.quality,
format: options.format,
});
await executeRenderJob(
job,
projectDir,
outputPath,
async (j) => {
// Producer mutates the same `job` object; mirror the fields we expose.
// Producer's `progress` is 0..100; our HTTP contract is 0..1, so
// normalize here (clamped) — success is set to 1 below.
const progress =
typeof j.progress === 'number' ? Math.max(0, Math.min(1, j.progress / 100)) : 0;
await this.jobs.update(id, {
status: 'running',
progress,
currentStage: j.currentStage || j.status,
...(typeof j.framesRendered === 'number' ? { framesRendered: j.framesRendered } : {}),
...(typeof j.totalFrames === 'number' ? { totalFrames: j.totalFrames } : {}),
});
},
abort.signal,
);
if (abort.signal.aborted) {
// Deadline overrun is a failure, not a user cancellation.
await this.jobs.update(id, {
status: timedOut ? 'failed' : 'cancelled',
currentStage: timedOut ? 'failed' : 'cancelled',
...(timedOut ? { error: 'Render exceeded the deadline' } : {}),
});
await this.cleanupProject(projectDir);
return;
}
await this.artifacts.put(id, outputPath);
await this.jobs.update(id, {
status: 'succeeded',
progress: 1,
currentStage: 'complete',
outputPath,
});
} catch (error) {
// A deadline abort surfaces as a thrown RenderCancelledError; report it as
// failed (with a clear reason), reserving `cancelled` for user cancels.
const cancelledByUser = abort.signal.aborted && !timedOut;
await this.jobs.update(id, {
status: cancelledByUser ? 'cancelled' : 'failed',
currentStage: cancelledByUser ? 'cancelled' : 'failed',
error: timedOut
? 'Render exceeded the deadline'
: error instanceof Error
? error.message
: String(error),
});
// On failure/cancel the artifact is worthless — reclaim the project dir now.
await this.cleanupProject(projectDir);
} finally {
clearTimeout(deadline);
this.controllers.delete(id);
if (record.userId) this.decrementIdentity(record.userId);
this.running--;
this.pump();
}
}
/** Best-effort recursive delete of a job's unzipped project dir. */
async cleanupProject(dir: string): Promise<void> {
await rm(dir, { recursive: true, force: true }).catch(() => {});
}
}
/** Create a fresh, empty per-render project directory under the configured tmp root. */
export async function makeProjectDir(): Promise<string> {
return mkdtemp(join(config.tmpDir, 'render-'));
}

View File

@ -0,0 +1,39 @@
/**
* A minimal counting semaphore for bounding concurrency of an async section.
*
* Used to cap how many archive extractions run at once: extraction holds the
* expanded archive in memory, so without a bound a burst of admitted jobs would
* multiply the per-archive RAM ceiling. `run()` acquires a permit, runs the
* task, and always releases — FIFO, so callers don't starve.
*/
export class Semaphore {
private available: number;
private readonly waiters: Array<() => void> = [];
constructor(permits: number) {
this.available = Math.max(1, permits);
}
async run<T>(task: () => Promise<T>): Promise<T> {
await this.acquire();
try {
return await task();
} finally {
this.release();
}
}
private acquire(): Promise<void> {
if (this.available > 0) {
this.available -= 1;
return Promise.resolve();
}
return new Promise((resolve) => this.waiters.push(resolve));
}
private release(): void {
const next = this.waiters.shift();
if (next) next();
else this.available += 1;
}
}

View File

@ -0,0 +1,45 @@
/**
* Shared types for the render service.
*
* The public shape a client sees when polling a job. Deliberately decoupled
* from `@hyperframes/producer`'s internal `RenderJob` so the HTTP contract
* (and therefore the app) stays stable if the producer's internals change.
*/
/** Lifecycle of a render job as the app observes it. */
export type RenderJobStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled';
/** User-facing render options accepted by `POST /render`. */
export interface RenderOptions {
/** Integer frames per second. */
fps: number;
quality: 'draft' | 'standard' | 'high';
/** Only mp4 is supported in this phase; kept explicit for forward-compat. */
format: 'mp4';
}
/**
* A render job's observable state. `progress` is 0..1 (producer's native
* range); the HTTP layer surfaces it as-is and the client scales to a percent.
*/
export interface RenderJobRecord {
id: string;
/** Optional caller identity used only for the per-user concurrency guard. */
userId?: string;
status: RenderJobStatus;
progress: number;
currentStage: string;
framesRendered?: number;
totalFrames?: number;
error?: string;
createdAtMs: number;
updatedAtMs: number;
/** Absolute path to the unzipped project dir (for cleanup). */
projectDir: string;
/** Absolute path to the rendered MP4 once `succeeded`. */
outputPath?: string;
}
export function isTerminal(status: RenderJobStatus): boolean {
return status === 'succeeded' || status === 'failed' || status === 'cancelled';
}

View File

@ -0,0 +1,89 @@
/**
* unzip — expand the app's export ZIP into a project directory the producer can
* render. The archive layout is exactly what `packageVideoZip` produces:
* `index.html` + `assets/**` + the vendored GSAP, all project-relative.
*
* The archive is untrusted input, so extraction is bounded *before* any bytes
* are decompressed: fflate's `filter` runs per entry with the entry's declared
* compressed (`size`) and expanded (`originalSize`) sizes, letting us reject
* ZIP bombs (too many entries, an oversized entry, oversized total, or an
* implausible compression ratio) without ever materializing them. Path
* traversal (`../`) is rejected too.
*
* Decompression uses fflate's **async** `unzip`, which offloads the actual
* inflate to a worker thread instead of blocking the service's event loop (so
* `/health` and poll requests stay responsive during a large expansion). The
* `filter` still runs synchronously in the initial pass — that's the cheap,
* declared-size security gate — and a limit breach throws straight out of the
* `unzip()` call, which we translate into a rejected promise.
*/
import { mkdir, writeFile } from 'node:fs/promises';
import { dirname, relative, resolve, sep } from 'node:path';
import { unzip, type Unzipped, type UnzipFileInfo } from 'fflate';
import { config } from './config.js';
export class InvalidProjectError extends Error {}
/**
* Expand `zip` into `destDir`. Throws {@link InvalidProjectError} if the archive
* escapes `destDir`, trips a size/entry limit, or lacks an `index.html` entry.
*/
export async function unzipProject(zip: Uint8Array, destDir: string): Promise<void> {
let entryCount = 0;
let expandedTotal = 0;
// The filter is the security boundary: it runs for every entry using only the
// ZIP's declared sizes, before fflate decompresses anything. Throwing here
// aborts the whole unzip. Directory entries carry no data.
const filter = (file: UnzipFileInfo): boolean => {
if (file.name.endsWith('/')) return false;
entryCount += 1;
if (entryCount > config.maxEntries) {
throw new InvalidProjectError(`Archive has too many entries (> ${config.maxEntries})`);
}
if (file.originalSize > config.maxEntryBytes) {
throw new InvalidProjectError(`Archive entry too large: ${file.name}`);
}
// Ratio guard catches deeply-compressed bombs (a tiny entry claiming a
// huge expansion). Ignore tiny entries where the ratio is meaningless.
if (file.size > 0 && file.originalSize / file.size > config.maxCompressionRatio) {
throw new InvalidProjectError(`Archive entry compression ratio too high: ${file.name}`);
}
expandedTotal += file.originalSize;
if (expandedTotal > config.maxExpandedBytes) {
throw new InvalidProjectError('Archive expands beyond the allowed total size');
}
return true;
};
// Promisify the async (worker-offloaded) unzip. A filter breach throws
// synchronously out of unzip(); the decompression itself reports via callback.
const entries = await new Promise<Unzipped>((resolvePromise, rejectPromise) => {
try {
unzip(zip, { filter }, (err, data) => {
if (err) rejectPromise(err);
else resolvePromise(data);
});
} catch (err) {
rejectPromise(err);
}
});
const names = Object.keys(entries);
if (!names.some((n) => n === 'index.html' || n.endsWith('/index.html'))) {
throw new InvalidProjectError('Export archive is missing index.html');
}
const destRoot = resolve(destDir);
for (const [name, bytes] of Object.entries(entries)) {
const target = resolve(destRoot, name);
const rel = relative(destRoot, target);
if (rel.startsWith('..') || rel.startsWith(`..${sep}`)) {
throw new InvalidProjectError(`Unsafe path in archive: ${name}`);
}
await mkdir(dirname(target), { recursive: true });
await writeFile(target, bytes);
}
}

View File

@ -0,0 +1,54 @@
/**
* The upload body cap must count *actual* bytes and abort the stream the instant
* they exceed the limit — a `Content-Length` check alone is bypassable via a
* chunked or length-lying upload, so this is the real bound before `formData()`
* / `arrayBuffer()` can buffer a hostile body.
*/
import { describe, it, expect } from 'vitest';
import { capBodyStream } from '../src/capped-stream.js';
/** A ReadableStream that emits `count` chunks of `chunk` bytes each. */
function streamOf(chunk: number, count: number): ReadableStream<Uint8Array> {
let emitted = 0;
return new ReadableStream<Uint8Array>({
pull(controller) {
if (emitted >= count) {
controller.close();
return;
}
emitted++;
controller.enqueue(new Uint8Array(chunk));
},
});
}
async function drain(stream: ReadableStream<Uint8Array>): Promise<number> {
const reader = stream.getReader();
let total = 0;
for (;;) {
const { done, value } = await reader.read();
if (done) break;
total += value.byteLength;
}
return total;
}
describe('capBodyStream', () => {
it('passes a body under the cap through untouched', async () => {
const { stream, exceeded } = capBodyStream(streamOf(1000, 5), 10_000);
expect(await drain(stream)).toBe(5000);
expect(exceeded()).toBe(false);
});
it('aborts and flags a body that exceeds the cap', async () => {
const { stream, exceeded } = capBodyStream(streamOf(1000, 100), 5000);
await expect(drain(stream)).rejects.toBeTruthy();
expect(exceeded()).toBe(true);
});
it('does not flag exceeded when the body ends exactly at the cap', async () => {
const { stream, exceeded } = capBodyStream(streamOf(1000, 5), 5000);
expect(await drain(stream)).toBe(5000);
expect(exceeded()).toBe(false);
});
});

View File

@ -0,0 +1,47 @@
/**
* Config env parsing — specifically the knobs whose zero value is meaningful.
* `RENDER_MAX_JOBS_PER_USER=0` must *disable* the per-identity guard (documented
* behavior); the earlier `intEnv` rejected 0 and silently fell back to 1, so the
* guard couldn't be turned off. Config resolves env once at import, so each case
* resets the module registry and re-imports under a fresh environment.
*/
import { describe, it, expect, afterEach, vi } from 'vitest';
const KEY = 'RENDER_MAX_JOBS_PER_USER';
const original = process.env[KEY];
afterEach(() => {
if (original === undefined) delete process.env[KEY];
else process.env[KEY] = original;
vi.resetModules();
});
async function loadConfig() {
vi.resetModules();
const mod = await import('../src/config.js');
return mod.config;
}
describe('config maxJobsPerUser', () => {
it('accepts 0 to disable the per-identity guard', async () => {
process.env[KEY] = '0';
expect((await loadConfig()).maxJobsPerUser).toBe(0);
});
it('accepts a positive override', async () => {
process.env[KEY] = '5';
expect((await loadConfig()).maxJobsPerUser).toBe(5);
});
it('falls back to the default (1) for negative or non-numeric values', async () => {
process.env[KEY] = '-3';
expect((await loadConfig()).maxJobsPerUser).toBe(1);
process.env[KEY] = 'nonsense';
expect((await loadConfig()).maxJobsPerUser).toBe(1);
});
it('falls back to the default when unset', async () => {
delete process.env[KEY];
expect((await loadConfig()).maxJobsPerUser).toBe(1);
});
});

View File

@ -0,0 +1,119 @@
/**
* Admission-control arithmetic for {@link RenderManager}. These guard the
* reserve → submit/release lifecycle that bounds a caller *before* the archive
* is extracted:
* - the global queue-depth cap (`RENDER_MAX_QUEUE`) counts reserved slots;
* - the per-identity cap (`RENDER_MAX_JOBS_PER_USER`) can't be bypassed;
* - `release()` fully undoes a reservation (the leak the route fix depends on:
* if a post-reserve step like makeProjectDir throws, the slot must come back).
*
* We drive the manager directly with in-memory stores so nothing invokes the
* real Chromium/FFmpeg producer — this is pure counter arithmetic.
*/
import { describe, it, expect } from 'vitest';
import { RenderManager, RenderRejectedError } from '../src/render-manager.js';
import type { JobStore } from '../src/job-store.js';
import type { ArtifactStore, ArtifactLocation } from '../src/artifact-store.js';
import type { RenderJobRecord } from '../src/types.js';
function fakeJobStore(): JobStore {
const jobs = new Map<string, RenderJobRecord>();
return {
async create(record) {
jobs.set(record.id, record);
},
async get(id) {
return jobs.get(id) ?? null;
},
async update(id, patch) {
const existing = jobs.get(id);
if (existing) jobs.set(id, { ...existing, ...patch });
},
async remove(id) {
jobs.delete(id);
},
async list() {
return [...jobs.values()];
},
async countActiveForUser() {
return 0;
},
};
}
const fakeArtifacts: ArtifactStore = {
async put() {},
async locate(): Promise<ArtifactLocation | null> {
return null;
},
async remove() {},
};
function newManager(): RenderManager {
return new RenderManager(fakeJobStore(), fakeArtifacts);
}
describe('RenderManager admission control', () => {
it('reserve then release fully restores the per-identity slot', () => {
const m = newManager();
// Default RENDER_MAX_JOBS_PER_USER is 1.
const r = m.reserve('alice');
// A second reserve for the same identity is now rejected...
expect(() => m.reserve('alice')).toThrow(RenderRejectedError);
// ...until the first is released (the makeProjectDir-failure path).
m.release(r);
expect(() => m.reserve('alice')).not.toThrow();
});
it('release is idempotent and does not double-decrement', () => {
const m = newManager();
const r = m.reserve('bob');
m.release(r);
m.release(r); // no-op, must not free a slot that isn't held
// bob now has one free slot; a fresh reserve + a stale release must not
// let a second concurrent reserve through.
const r2 = m.reserve('bob');
expect(() => m.reserve('bob')).toThrow(RenderRejectedError);
m.release(r2);
});
it('enforces the per-identity cap across distinct identities independently', () => {
const m = newManager();
const a = m.reserve('alice');
const b = m.reserve('bob'); // different identity: allowed
expect(a.identity).toBe('alice');
expect(b.identity).toBe('bob');
expect(() => m.reserve('alice')).toThrow(RenderRejectedError);
m.release(a);
m.release(b);
});
it('rejects reservations once the global queue is full', () => {
const m = newManager();
// Reserve up to RENDER_MAX_QUEUE (default 20) with unique identities so the
// per-user guard never fires first, then the next reserve trips the queue cap.
const held = [];
for (let i = 0; i < 20; i++) held.push(m.reserve(`user-${i}`));
expect(() => m.reserve('user-overflow')).toThrow(/queue is full/i);
held.forEach((r) => m.release(r));
// Once released, capacity is back.
expect(() => m.reserve('user-again')).not.toThrow();
});
it('does not leak the identity slot when jobs.create fails', async () => {
// submit() consumes the reservation and persists the job; if create() throws
// (a fallible JobStore, e.g. a future Redis backend), run() never runs to
// decrement the identity — so submit() must decrement it itself.
const store = fakeJobStore();
store.create = async () => {
throw new Error('store down');
};
const m = new RenderManager(store, fakeArtifacts);
const r = m.reserve('carol');
await expect(
m.submit(r, '/tmp/whatever', { fps: 30, quality: 'draft', format: 'mp4' }),
).rejects.toThrow('store down');
// The slot must be free again: a fresh reserve for the same identity succeeds.
expect(() => m.reserve('carol')).not.toThrow();
});
});

View File

@ -0,0 +1,139 @@
/**
* Integration test for the admission/buffering boundary of `POST /render`.
*
* The security property under test (round-3 review P1#1): only
* `maxConcurrentExtractions` requests may be inside the RAM-heavy section
* (multipart buffering → file read → extraction) at once. Everything else waits
* with its body unconsumed, so a burst of near-cap uploads can't stack in memory.
*
* We drive the real Hono app (`createApp`) with a fake manager/stores and a
* `unzipProject` stub that parks — recording how many calls are simultaneously
* "inside" — so we can assert the peak never exceeds the gate's permit count.
*/
import { describe, it, expect, beforeAll } from 'vitest';
import { Semaphore } from '../src/semaphore.js';
import type { JobStore } from '../src/job-store.js';
import type { ArtifactStore, ArtifactLocation } from '../src/artifact-store.js';
import type { RenderJobRecord } from '../src/types.js';
// Prevent main.ts from binding a port when we import it.
process.env.RENDER_SERVICE_NO_LISTEN = 'true';
// Loaded in beforeAll after the env guard above is set.
let createApp: typeof import('../src/main.js').createApp;
let RenderManager: typeof import('../src/render-manager.js').RenderManager;
beforeAll(async () => {
({ createApp } = await import('../src/main.js'));
({ RenderManager } = await import('../src/render-manager.js'));
});
function fakeJobStore(): JobStore {
const jobs = new Map<string, RenderJobRecord>();
return {
async create(r) {
jobs.set(r.id, r);
},
async get(id) {
return jobs.get(id) ?? null;
},
async update(id, patch) {
const e = jobs.get(id);
if (e) jobs.set(id, { ...e, ...patch });
},
async remove(id) {
jobs.delete(id);
},
async list() {
return [...jobs.values()];
},
async countActiveForUser() {
return 0;
},
};
}
const fakeArtifacts: ArtifactStore = {
async put() {},
async locate(): Promise<ArtifactLocation | null> {
return null;
},
async remove() {},
};
/** Build a valid-looking multipart body for `POST /render`. */
function renderRequest(sizeBytes = 4096, identity = 'anon'): Request {
const form = new FormData();
form.append('project', new Blob([new Uint8Array(sizeBytes)]), 'project.zip');
form.append('fps', '24');
form.append('quality', 'draft');
form.append('format', 'mp4');
return new Request('http://test/render', {
method: 'POST',
body: form,
headers: { 'x-openmaic-client': identity },
});
}
describe('POST /render buffering/extraction bound', () => {
it('never lets more than the permit count into the buffering+extraction section', async () => {
const PERMITS = 2;
const REQUESTS = 8;
let inside = 0;
let peak = 0;
const release: Array<() => void> = [];
// Each extraction parks until we release it, so all admitted requests pile
// up at the gate simultaneously — exposing any over-admission.
const unzipProject = () =>
new Promise<void>((resolve) => {
inside++;
peak = Math.max(peak, inside);
release.push(() => {
inside--;
resolve();
});
});
let n = 0;
const makeProjectDir = async () => `/tmp/fake-${n++}`;
const jobs = fakeJobStore();
// A big per-user cap so all REQUESTS are admitted (we're testing the gate,
// not the per-identity guard); unique identities would also work.
const manager = new RenderManager(jobs, fakeArtifacts);
const app = createApp({
jobs,
artifacts: fakeArtifacts,
manager,
extractionGate: new Semaphore(PERMITS),
unzipProject,
makeProjectDir,
});
// Fire all requests with distinct identities so admission never rejects them.
const inFlight = Array.from({ length: REQUESTS }, (_, i) =>
app.fetch(renderRequest(4096, `user-${i}`)),
);
// Let the event loop settle so every request that CAN enter the gate has.
await new Promise((r) => setTimeout(r, 50));
// The invariant: at most PERMITS extractions are parked inside right now.
expect(inside).toBeLessThanOrEqual(PERMITS);
expect(peak).toBeLessThanOrEqual(PERMITS);
// Drain: release parked calls; each release frees a permit for a waiter.
while (release.length > 0) {
release.shift()!();
await new Promise((r) => setTimeout(r, 5));
}
const responses = await Promise.all(inFlight);
// Every request ultimately succeeds (202) once it passes through the gate.
for (const res of responses) expect(res.status).toBe(202);
// Peak concurrency never exceeded the permit count across the whole run.
expect(peak).toBe(PERMITS);
});
});

View File

@ -0,0 +1,64 @@
/**
* The extraction semaphore bounds how many archive expansions run at once, so a
* burst of admitted jobs can't stack the per-archive RAM ceiling. It must never
* run more than `permits` tasks concurrently, and must always release (even when
* a task throws) so it can't wedge.
*/
import { describe, it, expect } from 'vitest';
import { Semaphore } from '../src/semaphore.js';
/** A deferred we can resolve from the test to control task completion timing. */
function deferred<T = void>() {
let resolve!: (v: T) => void;
const promise = new Promise<T>((r) => (resolve = r));
return { promise, resolve };
}
describe('Semaphore', () => {
it('never exceeds the permit count concurrently', async () => {
const sem = new Semaphore(2);
let active = 0;
let peak = 0;
const gates = [deferred(), deferred(), deferred(), deferred()];
const runs = gates.map((g, i) =>
sem.run(async () => {
active++;
peak = Math.max(peak, active);
await g.promise;
active--;
return i;
}),
);
// Let the first wave schedule, then release tasks one at a time.
await Promise.resolve();
expect(active).toBeLessThanOrEqual(2);
gates.forEach((g) => g.resolve());
const results = await Promise.all(runs);
expect(peak).toBe(2); // exactly the permit count, never more
expect(results).toEqual([0, 1, 2, 3]);
});
it('releases the permit when a task throws', async () => {
const sem = new Semaphore(1);
await expect(
sem.run(async () => {
throw new Error('boom');
}),
).rejects.toThrow('boom');
// If the failed task leaked its permit, this would hang; it resolves instead.
await expect(sem.run(async () => 'ok')).resolves.toBe('ok');
});
it('runs tasks when permits are available without blocking', async () => {
const sem = new Semaphore(3);
const results = await Promise.all([
sem.run(async () => 1),
sem.run(async () => 2),
sem.run(async () => 3),
]);
expect(results).toEqual([1, 2, 3]);
});
});

View File

@ -0,0 +1,106 @@
/**
* Security-boundary tests for archive extraction: the ZIP is untrusted input,
* so `unzipProject` must reject bombs (entry count / entry size / total size /
* compression ratio) *before* decompressing, reject path traversal, and require
* an `index.html`. These are the guards standing between a hostile upload and
* the render host.
*
* The size/ratio limits are read from env at config import, so each limit case
* stubs a *tiny* limit and re-imports the module — that trips the guard with a
* few KB instead of allocating hundreds of MB (which would blow the test timeout
* and stress CI memory), while exercising the exact same code path.
*/
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import { mkdtemp, rm, readFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { zipSync, strToU8 } from 'fflate';
let dest: string;
beforeEach(async () => {
dest = await mkdtemp(join(tmpdir(), 'unzip-test-'));
});
afterEach(async () => {
await rm(dest, { recursive: true, force: true });
vi.unstubAllEnvs();
vi.resetModules();
});
/** Import `unzipProject` fresh so config picks up any stubbed env for this case. */
async function freshUnzip() {
vi.resetModules();
return import('../src/unzip.js');
}
/** Build a ZIP from a name→string map. */
function zip(files: Record<string, string>): Uint8Array {
const entries: Record<string, Uint8Array> = {};
for (const [name, content] of Object.entries(files)) entries[name] = strToU8(content);
return zipSync(entries);
}
describe('unzipProject', () => {
it('extracts a valid project with index.html', async () => {
const { unzipProject } = await freshUnzip();
const archive = zip({ 'index.html': '<!doctype html>', 'assets/app.js': 'console.log(1)' });
await unzipProject(archive, dest);
expect(await readFile(join(dest, 'index.html'), 'utf8')).toContain('<!doctype html>');
expect(await readFile(join(dest, 'assets/app.js'), 'utf8')).toContain('console.log');
});
it('rejects an archive missing index.html', async () => {
const { unzipProject, InvalidProjectError } = await freshUnzip();
const archive = zip({ 'assets/app.js': 'x' });
await expect(unzipProject(archive, dest)).rejects.toBeInstanceOf(InvalidProjectError);
});
it('rejects path traversal outside the destination', async () => {
const { unzipProject, InvalidProjectError } = await freshUnzip();
// fflate preserves the literal entry name; a `../` escape must be caught.
const archive = zipSync({
'index.html': strToU8('<!doctype html>'),
'../escape.txt': strToU8('pwned'),
});
await expect(unzipProject(archive, dest)).rejects.toBeInstanceOf(InvalidProjectError);
await expect(readFile(join(dest, '..', 'escape.txt'), 'utf8')).rejects.toBeTruthy();
});
it('rejects too many entries', async () => {
vi.stubEnv('RENDER_MAX_ENTRIES', '3');
const { unzipProject, InvalidProjectError } = await freshUnzip();
const files: Record<string, string> = { 'index.html': '<!doctype html>' };
for (let i = 0; i < 5; i++) files[`f${i}.txt`] = 'x';
await expect(unzipProject(zip(files), dest)).rejects.toBeInstanceOf(InvalidProjectError);
});
it('rejects a single entry that expands beyond the per-entry cap', async () => {
vi.stubEnv('RENDER_MAX_ENTRY_BYTES', '64');
const { unzipProject, InvalidProjectError } = await freshUnzip();
// 2KB of random-ish text: exceeds the 64-byte cap and won't compress past
// the ratio guard, so the per-entry-size guard is what trips.
const body = Array.from({ length: 2048 }, (_, i) => String.fromCharCode(33 + (i % 90))).join(
'',
);
const archive = zip({ 'index.html': '<!doctype html>', 'big.txt': body });
await expect(unzipProject(archive, dest)).rejects.toBeInstanceOf(InvalidProjectError);
});
it('rejects total expansion beyond the aggregate cap', async () => {
vi.stubEnv('RENDER_MAX_EXPANDED_BYTES', '32');
const { unzipProject, InvalidProjectError } = await freshUnzip();
const body = Array.from({ length: 200 }, (_, i) => String.fromCharCode(33 + (i % 90))).join('');
const archive = zip({ 'index.html': '<!doctype html>', 'a.txt': body });
await expect(unzipProject(archive, dest)).rejects.toBeInstanceOf(InvalidProjectError);
});
it('rejects an implausible compression ratio (zip bomb)', async () => {
vi.stubEnv('RENDER_MAX_COMPRESSION_RATIO', '5');
vi.stubEnv('RENDER_MAX_ENTRY_BYTES', String(1024 * 1024 * 1024)); // don't let size trip first
const { unzipProject, InvalidProjectError } = await freshUnzip();
// Highly repetitive content deflates far past a 5:1 ratio.
const bomb = 'a'.repeat(200 * 1024);
const archive = zip({ 'index.html': '<!doctype html>', 'bomb.txt': bomb });
await expect(unzipProject(archive, dest)).rejects.toBeInstanceOf(InvalidProjectError);
});
});

View File

@ -0,0 +1,19 @@
{
"compilerOptions": {
"target": "ES2022",
"module": "ESNext",
"lib": ["ES2022"],
"moduleResolution": "bundler",
"outDir": "dist",
"rootDir": "src",
"strict": true,
"noFallthroughCasesInSwitch": true,
"esModuleInterop": true,
"resolveJsonModule": true,
"isolatedModules": true,
"skipLibCheck": true,
"types": ["node"]
},
"include": ["src"],
"exclude": ["node_modules", "dist"]
}

View File

@ -0,0 +1,10 @@
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
include: ['test/**/*.test.ts'],
// Node environment: these test the service's server-side boundaries
// (unzip limits, admission arithmetic, body caps), no DOM needed.
environment: 'node',
},
});

View File

@ -40,6 +40,9 @@ exports[`emitHyperframes > matches the HTML snapshot 1`] = `
<div style="width:10px;height:10px;border-radius:9999px;background-color:#00ff88;box-shadow:0 0 8px 2px #00ff8860"></div>
</div>
</div>
<div id="subtitles" style="position:absolute;left:0;right:0;bottom:59px;z-index:50;display:grid;justify-items:center;text-align:center;pointer-events:none;font-family:system-ui,sans-serif">
<div id="subtitle-cue-0" style="grid-area:1/1;display:none;justify-self:center;max-width:80%;padding:13px 25px;background:rgba(0,0,0,0.66);color:#fff;font-size:36px;line-height:1.3;border-radius:13px;white-space:pre-wrap;text-shadow:0 1px 2px rgba(0,0,0,0.9)">Welcome to the lesson</div>
</div>
</div>
<script src="assets/vendor/gsap.min.js"></script>
<script>
@ -86,6 +89,8 @@ tl.fromTo('#fx-0-2-ring',{scale:1,opacity:0.6},{scale:2.8,opacity:0,duration:1.5
tl.to('#fx-0-2',{autoAlpha:0,x:-1056,y:-591.6,duration:0.25,ease:EASE_IN},4.75);
tl.set('#fx-0-2',{autoAlpha:0},5);
tl.set('#fx-0-2-ring',{opacity:0},5);
tl.set('#subtitle-cue-0',{display:'inline-block'},0);
tl.set('#subtitle-cue-0',{display:'none'},2);
tl.set({}, {}, 7);
window.__timelines = window.__timelines || {};
window.__timelines["openmaic"] = tl;

View File

@ -86,6 +86,20 @@ describe('emitHyperframes', () => {
expect(html).toContain('#00ff88'); // authored laser color survives into the DOM
});
it('burns in a subtitle overlay driven by the timeline', () => {
// A caption container plus one cue div per non-empty speech action.
expect(html).toContain('id="subtitles"');
expect(html).toContain('id="subtitle-cue-0"');
// Cues start hidden (display:none, out of layout) and are toggled by the
// paused timeline — see the multi-cue positioning test below for why
// display (not visibility) matters.
expect(html).toMatch(/id="subtitle-cue-0"[^>]*display:none/);
expect(html).toMatch(/tl\.set\('#subtitle-cue-0',\{display:'inline-block'\},[\d.]+\);/);
expect(html).toMatch(/tl\.set\('#subtitle-cue-0',\{display:'none'\},[\d.]+\);/);
// Narration text is rendered into the caption.
expect(html).toContain('Welcome to the lesson');
});
it('references vendored GSAP, never a CDN', () => {
expect(html).toContain('<script src="assets/vendor/gsap.min.js"></script>');
expect(project.gsapVendorPath).toBe('assets/vendor/gsap.min.js');
@ -96,6 +110,57 @@ describe('emitHyperframes', () => {
});
});
describe('emitHyperframes multi-cue subtitle positioning (regression)', () => {
// A scene with several narration cues; the earlier cut left inactive cues in
// layout (visibility:hidden + inline-block), so the band grew multiple rows
// tall and the active cue drifted up into the slide/title area.
const ir = compileVideoTimeline(
{
stage: { id: 'stage', name: 'Multi Cue' },
scenes: [
slide(
'intro',
[
speech('sp1', 'First caption line', { audioId: 'a1' }),
speech('sp2', 'Second caption line', { audioId: 'a2' }),
speech('sp3', 'Third caption line', { audioId: 'a3' }),
],
{ title: 'Intro', elements: [] },
),
],
},
{
timing: stubProbe({ sp1: 2000, sp2: 2000, sp3: 2000 }, {}),
assets: stubAssets({ sp1: audioMeta('a1'), sp2: audioMeta('a2'), sp3: audioMeta('a3') }, {}),
},
);
const html = emitHyperframes(ir, { width: 1920, height: 1080 }).files.find(
(f) => f.path === 'index.html',
)!.content;
it('stacks every cue in one grid cell so the active cue never shifts', () => {
// All cues share grid-area 1/1 — one slot, not one row each.
const cueCount = (html.match(/id="subtitle-cue-\d+"/g) ?? []).length;
expect(cueCount).toBe(3);
expect(html.match(/grid-area:1\/1/g)?.length).toBe(3);
expect(html).toContain('id="subtitles" style="position:absolute');
// The container is a grid so the single occupied cell owns the whole band.
expect(html).toMatch(/id="subtitles"[^>]*display:grid/);
});
it('removes inactive cues from layout (display:none, never visibility:hidden)', () => {
// Every cue starts display:none; toggled cues use display, not visibility —
// a visibility-hidden cue would keep its box and push the active one out of slot.
for (let i = 0; i < 3; i++) {
expect(html).toMatch(new RegExp(`id="subtitle-cue-${i}"[^>]*display:none`));
expect(html).toContain(`tl.set('#subtitle-cue-${i}',{display:'inline-block'}`);
expect(html).toContain(`tl.set('#subtitle-cue-${i}',{display:'none'}`);
}
expect(html).not.toContain('visibility:hidden');
expect(html).not.toContain("visibility:'hidden'");
});
});
describe('emitHyperframes determinism red-lines (hyperframes lint proxy)', () => {
const project = emitHyperframes(compileSample());
const html = project.files.find((f) => f.path === 'index.html')!.content;

View File

@ -30,5 +30,13 @@
".next/dev/types/**/*.ts",
"**/*.mts"
],
"exclude": ["node_modules", "dist", "packages/*/src", "packages/docs", "openclaw", "e2e"]
"exclude": [
"node_modules",
"dist",
"packages/*/src",
"packages/docs",
"openclaw",
"e2e",
"render-service"
]
}