Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ ALLOW_ANY_PUBLIC_DOMAIN=false
ENGINE_PORT=3000
PORT=3000
HEADLESS=true
# Per-process shared budget for protected API routes, including failed auth.
REQUESTS_PER_MINUTE=600
RENDER_TIMEOUT_MS=20000
RENDER_MAX_REDIRECTS=10
RENDER_MAX_REQUESTS=250
Expand Down
8 changes: 4 additions & 4 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ jobs:
node-version: [20.x, 22.x, 24.x]
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7
with:
node-version: ${{ matrix.node-version }}
cache: npm
Expand All @@ -28,9 +28,9 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
- uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4
- uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4
- name: Build browser integration image
uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7
uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7
with:
context: .
target: test
Expand All @@ -39,7 +39,7 @@ jobs:
tags: prerenderbuddy/engine:test
- name: Run real Chromium fixture matrix
run: docker run --rm --shm-size=1g prerenderbuddy/engine:test
- uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7
- uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7
with:
context: .
load: true
Expand Down
4 changes: 2 additions & 2 deletions .github/workflows/codeql.yml
Original file line number Diff line number Diff line change
Expand Up @@ -19,9 +19,9 @@ jobs:
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
- name: Initialize CodeQL
uses: github/codeql-action/init@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6
uses: github/codeql-action/init@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4.38.0
with:
languages: javascript-typescript
build-mode: none
- name: Analyze
uses: github/codeql-action/analyze@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6
uses: github/codeql-action/analyze@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4.38.0
8 changes: 4 additions & 4 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ jobs:
with:
fetch-depth: 0

- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7
with:
node-version: 22.x
cache: npm
Expand Down Expand Up @@ -66,7 +66,7 @@ jobs:
npm test
npm audit --audit-level=moderate

- uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4
- uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4

- name: Build and run real Chromium fixtures
working-directory: ${{ steps.archive.outputs.source_dir }}
Expand Down Expand Up @@ -95,7 +95,7 @@ jobs:
docker logs engine-release-smoke
exit 1

- uses: docker/setup-qemu-action@96fe6ef7f33517b61c61be40b68a1882f3264fb8 # v4.2.0
- uses: docker/setup-qemu-action@99012661954931238ded8c8b007157a8430204e1 # v4.4.0

- name: Sign in to GitHub Container Registry
uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
Expand All @@ -105,7 +105,7 @@ jobs:
password: ${{ secrets.GITHUB_TOKEN }}

- name: Publish versioned runtime image
uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
with:
context: ${{ steps.archive.outputs.source_dir }}
target: runtime
Expand Down
8 changes: 8 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,14 @@

All notable changes are documented here. The project follows Semantic Versioning after the initial pre-1.0 stabilization period.

## Unreleased

- Align the Playwright npm package and digest-pinned browser container at 1.64.0 so Chromium fixtures use the matching executable.
- Update proxy-addr to 2.0.8, refresh Ubuntu packages during image builds, and update the supertest test dependency.
- Refresh pinned Node setup, Docker build/push, Buildx, QEMU and CodeQL actions.
- Limit protected API requests before authentication with a configurable per-process budget, preserving public health/readiness probes and the required external proxy controls.
- Check package/container Playwright alignment in the unit suite to prevent independent updates from breaking browser startup.

## 0.1.3 - 2026-08-03

- Verify public GHCR access with an anonymous registry token instead of attempting to change user-package visibility with a repository-scoped workflow token.
Expand Down
7 changes: 6 additions & 1 deletion Dockerfile
Original file line number Diff line number Diff line change
@@ -1,4 +1,9 @@
FROM mcr.microsoft.com/playwright:v1.62.1-noble@sha256:dcc5531e97840b9b5e794f2814476b21571c5124a3fca2267d73041f56e7580e AS base
FROM mcr.microsoft.com/playwright:v1.64.0-noble@sha256:06a9939e57531807f8d5fd76ce44b53165ffb7d7501d87ab10e285c20b1e971f AS base

# Refresh Ubuntu security fixes, including OpenSSL, in both build stages.
RUN apt-get update \
&& apt-get upgrade --yes --no-install-recommends \
&& rm -rf /var/lib/apt/lists/*

WORKDIR /app
ENV PLAYWRIGHT_BROWSERS_PATH=/ms-playwright
Expand Down
9 changes: 7 additions & 2 deletions docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,10 @@ The engine exposes an HTTP API on port `3000` by default. Except for liveness an

`GET /ready` returns `200 {"ready":true}` when Chromium is connected, or `503 {"ready":false}`. These endpoints intentionally require no token so container orchestrators can call them.

## Request-rate protection (unreleased)

All non-probe API requests share a per-process budget configured by `REQUESTS_PER_MINUTE` (default 600 per minute). Authentication failures also consume it. A rejected request returns `429 {"error":"Request rate limit exceeded"}` and a `Retry-After` header. `RateLimit` and `RateLimit-Policy` describe the shared budget. Liveness/readiness are exempt. This control is in the maintenance branch and is not included in published `v0.1.3`.

## Render

Use either `GET /render?url=<encoded-url>` or:
Expand Down Expand Up @@ -52,10 +56,11 @@ JSON errors use `{"error":"message"}`. Stable statuses are:
| `401` | Missing or incorrect token |
| `403` | Destination, redirect, CORS preflight, or navigation rejected by policy |
| `404` | Unknown endpoint or cache miss; a render may also preserve an origin `404` as HTML |
| `413` | Rendered HTML exceeds the configured limit |
| `413` | Request body exceeds 16 KB, or rendered HTML exceeds the configured limit |
| `422` | Per-render browser request budget exhausted |
| `429` | Protected API request budget exhausted (unreleased) |
| `500` | Browser or unexpected render failure |
| `503` | Chromium not ready, render capacity reached, or coalescing wait exceeded |
| `504` | Render timed out |

Capacity responses may include `Retry-After`. Clients should retry `503` and `504` only with bounded exponential backoff and jitter. Do not retry policy `403`, size `413`, or request-budget `422` responses without changing the request or configuration.
Honor `Retry-After` on `429` before retrying. Capacity responses may include `Retry-After`. Clients should retry `503` and `504` only with bounded exponential backoff and jitter. Do not retry policy `403`, size `413`, or request-budget `422` responses without changing the request or configuration.
10 changes: 10 additions & 0 deletions docs/security-review.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,3 +71,13 @@ npm pack --dry-run
```

The Chromium matrix covers static HTML, server-rendered metadata/content, hydrated app shells, same-site redirects, cross-site and excessive redirect blocks, 404/503 status preservation, blocked subresources, popup/WebSocket/service-worker egress attempts, request storms, timeouts, oversized output, malformed responses, and SIGTERM shutdown.

## Maintenance review — 2026-10-18 (unreleased)

The maintenance branch aligns the Playwright package and digest-pinned browser image at 1.64.0, retains the patched proxy-addr 2.0.8 dependency, and refreshes Ubuntu packages while building both container stages. The dependency, Node, real-Chromium, runtime vulnerability and readiness gates remain required. Published v0.1.3 and its immutable tag are unchanged.

Authenticated endpoints now share an explicit process-local request-rate limiter, before JSON parsing, authorization, URL validation or browser allocation. It includes unsuccessful token attempts and returns 429 with Retry-After. One constant budget key avoids trusting forwarded IP headers or allocating attacker-controlled per-client buckets. The default is 600 protected requests per minute, configurable with startup validation. Health/readiness do not consume that budget. This addresses the common missing-rate-limiting finding on the five authenticated route variants without dismissing the alerts or treating render concurrency as a request-rate control.

Malformed JSON and oversized bodies consume the same budget; oversized request bodies return a stable 413 response. Allowed browser origins can read Retry-After, RateLimit and RateLimit-Policy through the existing CORS boundary.

The limiter is an additional local protection. It does not replace private ingress, TLS, reverse-proxy limits, host resource limits or egress controls. Its counter is local to each process and resets on restart; multiple engine replicas do not share a distributed budget. No managed-service routing or infrastructure is part of this change.
7 changes: 7 additions & 0 deletions docs/self-hosting.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ The container reads these environment variables:
| `PORT` | `3000` | Container HTTP port |
| `ENGINE_PORT` | `3000` | Host-only Compose port; used by `docker-compose.yml`, not the Node process |
| `HEADLESS` | `true` | Keep enabled in normal operation |
| `REQUESTS_PER_MINUTE` | `600` | Unreleased: shared protected-API budget per process; integer from 1 to 1,000,000 |
| `RENDER_TIMEOUT_MS` | `20000` | Bounded between 1 and 120 seconds |
| `RENDER_MAX_REDIRECTS` | `10` | Bounded between 0 and 20 hops |
| `RENDER_MAX_REQUESTS` | `250` | Bounded between 10 and 2,000 HTTP(S) requests; exhaustion terminates the render |
Expand All @@ -43,6 +44,12 @@ The container reads these environment variables:

An entry in `ALLOWED_DOMAINS` permits only that exact hostname. List both apex and `www` hostnames if both should be rendered.

## Request-rate protection (unreleased)

The maintenance branch adds a shared one-minute budget before JSON parsing and authorization. It covers `/render`, `/cache/read`, `/cache/clear`, `/internal/metrics`, and unknown non-probe requests. It counts both successful and rejected authentication attempts before protected work runs. The default is 600 requests per minute across all callers and those endpoints together; tune `REQUESTS_PER_MINUTE` to your workload. `/health` and `/ready` remain outside the budget so orchestrator probes keep working.

Exhausted requests return `429` JSON with `Retry-After`, `RateLimit` and `RateLimit-Policy` headers. Follow the retry delay with bounded backoff. Each process has its own in-memory budget, which resets on restart. The engine does not trust client-supplied forwarding headers to create new budgets, retain client IPs, or maintain per-IP buckets. Keep external proxy limits and private ingress in place, especially when running multiple replicas. Published `v0.1.3` does not contain this new control.

## Resource baseline

Start a single engine with 2 vCPU, 2 GB RAM, and the configured 1 GB shared-memory allocation. Page complexity matters more than URL count, so treat this as a starting point and measure representative workloads. Version 0.1 requires no Redis or external queue: its cache and duplicate-render coordination are deliberately process-local.
Expand Down
80 changes: 48 additions & 32 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

5 changes: 3 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -42,10 +42,11 @@
},
"dependencies": {
"express": "^5.2.1",
"express-rate-limit": "8.7.1",
"ipaddr.js": "2.5.0",
"playwright": "1.62.1"
"playwright": "1.64.0"
},
"devDependencies": {
"supertest": "^7.1.4"
"supertest": "^7.3.0"
}
}
20 changes: 17 additions & 3 deletions src/app.js
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
import express from 'express';
import { getAllowedOrigins } from './config.js';
import { rateLimit } from 'express-rate-limit';
import { getAllowedOrigins, getRequestsPerMinute } from './config.js';
import { createRoutes } from './routes.js';

export function createApp(options = {}) {
const app = express();
app.disable('x-powered-by');
app.use(express.json({ limit: '16kb', strict: true }));
app.use((req, res, next) => {
res.setHeader('X-Content-Type-Options', 'nosniff');
res.setHeader('X-Frame-Options', 'DENY');
Expand All @@ -19,17 +19,31 @@ export function createApp(options = {}) {
res.setHeader('Vary', 'Origin');
res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
res.setHeader('Access-Control-Allow-Headers', 'Authorization, Content-Type, X-Prerender-Token, X-Prerender-Cache-Ttl-Seconds');
res.setHeader('Access-Control-Expose-Headers', 'X-Prerender-Cache, X-Prerender-Cache-Ttl, X-Prerender-Time, X-Prerender-Final-Url, X-Prerender-Coordination');
res.setHeader('Access-Control-Expose-Headers', 'X-Prerender-Cache, X-Prerender-Cache-Ttl, X-Prerender-Time, X-Prerender-Final-Url, X-Prerender-Coordination, Retry-After, RateLimit, RateLimit-Policy');
}
if (req.method === 'OPTIONS') {
return origin && allowedOrigins.includes(origin) ? res.sendStatus(204) : res.sendStatus(403);
}
return next();
});
// Bound requests before JSON parsing, token checks or browser allocation.
// One constant key gives the process a shared, bounded-memory budget.
app.use(rateLimit({
windowMs: 60_000,
limit: getRequestsPerMinute(),
keyGenerator: () => 'engine',
skip: (req) => ['GET', 'HEAD'].includes(req.method) && /^\/(health|ready)\/?$/i.test(req.path),
standardHeaders: 'draft-8',
legacyHeaders: false,
identifier: 'engine-requests',
message: { error: 'Request rate limit exceeded' },
}));
app.use(express.json({ limit: '16kb', strict: true }));
app.use(createRoutes(options));
app.use((req, res) => res.status(404).json({ error: 'Not found' }));
app.use((error, req, res, next) => {
if (res.headersSent) return next(error);
if (error?.type === 'entity.too.large') return res.status(413).json({ error: 'Request body exceeds the 16 KB limit' });
if (error instanceof SyntaxError) return res.status(400).json({ error: 'Invalid JSON body' });
console.error('Unhandled request error:', error?.message || 'unknown');
return res.status(500).json({ error: 'Internal server error' });
Expand Down
Loading
Loading