Pulp Engine v0.12.0

Release date: 2026-03-22

Highlights

• Preview routes (POST /render/preview/html, POST /render/preview/pdf) are now gated by environment. In production without PREVIEW_ROUTES_ENABLED=true, these routes are not registered and return 404. In development and test they are unconditionally available.
• A startup warning is logged whenever PREVIEW_ROUTES_ENABLED=true is active in production.
• buildServer() accepts an optional loggerInstance parameter for test isolation.

Background

The preview endpoints accept an inline TemplateDefinition with no database lookup. They are intended exclusively for the visual editor’s real-time preview feature. Previously these routes were registered unconditionally in every environment; the only production-side protection was documentation instructing operators to restrict them at the reverse proxy layer.

That model is deployment-policy-only: a misconfigured reverse proxy silently exposes the routes to any API key holder. This release replaces that with in-product enforcement.

What changed

New env var: PREVIEW_ROUTES_ENABLED

Environment	PREVIEW_ROUTES_ENABLED	Preview routes
development or test	any value	Always registered — no config needed
production	absent or false (default)	Not registered — return 404
production	true	Registered — startup warning logged

Setting PREVIEW_ROUTES_ENABLED=true in production is an explicit, auditable opt-in. The server logs a warning at startup when preview routes are active in production. Defense-in-depth: also restrict /render/preview/* at the reverse proxy or network layer.

404 is returned (not 403) when routes are not registered — 404 does not confirm that the route ever existed, which is preferable to 403.

Route split

renderRoutes (the DB-backed public render plugin) and renderPreviewRoutes (the inline editor-only plugin) are now separate named exports. The server registers them independently; renderPreviewRoutes is only registered when the gating condition is met.

Migration

No action required for deployments that do not use the visual editor against the production API.

If the Pulp Engine visual editor is deployed and must reach a production API instance directly for real-time preview, set PREVIEW_ROUTES_ENABLED=true in the server environment before upgrading. Also restrict /render/preview/* at the network layer.

Files changed

File	Change
apps/api/src/config.ts	Added PREVIEW_ROUTES_ENABLED field (string → boolean, defaults to false)
apps/api/src/routes/render/render.ts	Split renderRoutes into renderRoutes + renderPreviewRoutes
apps/api/src/server.ts	Conditional registration of renderPreviewRoutes; startup warning; optional loggerInstance param
apps/api/src/__tests__/render-preview.test.ts	Added 3 production-gating tests
.env.example	Documented PREVIEW_ROUTES_ENABLED
README.md	Added production security section
docs/deployment-guide.md	Added env var table row, risk table row, checklist item
docs/api-guide.md	Replaced §3a “Production note” with availability matrix
docs/runbook.md	Added checklist item and smoke test §6
docs/release-v0.12.0.md	This file