HTTP/2 shared rendering

HTTP/2 shared rendering is a performance feature for tiled viewing of large documents (where the viewer loads a page as many small image tiles instead of one full page image). When you enable it, tile requests on the same TCP connection reuse a connection-scoped rendering process. This avoids repeating per-request setup such as authentication, file materialization, and worker checkout for every tile.

The feature works on any reused connection, but it’s designed for HTTP/2. This protocol enables a client multiplex many concurrent tile requests on one connection without head-of-line blocking, which makes shared rendering useful at scale. HTTP/1.1 keep-alive connections also reuse the rendering process, but requests are serialized on the wire, so the performance gain is smaller.

When to enable it

Enable shared rendering if your workload includes tiled viewing of documents, especially large documents.

Common cases include:

• Viewing documents in the dashboard or a Web SDK integration
• Deployments behind an HTTP/2-capable proxy such as Caddy with h2c upstream
• Viewers that pan, zoom, or paginate through pages often

If you’re not sure whether this fits your workload, refer to the large documents guide.

Configuration

These environment variables control shared rendering:

If a request doesn’t match one of the shared rendering tile endpoints, Document Engine sends it through the normal request path. Enabling this feature doesn’t affect non-tile requests.

Recommended setup

• Terminate HTTP/2 in front of Document Engine, or use h2c between a proxy such as Caddy and Document Engine. This ensures tile requests are multiplexed onto a single upstream connection.
• Make sure clients reuse a single connection for tile requests. Creating a new connection per request defeats the optimization, regardless of HTTP version.

Compatibility

Enabling HTTP2_SHARED_RENDERING_PROCESS_ENABLE changes only performance behavior. Response bodies, status codes, and error shapes stay the same. The API doesn’t change, and clients don’t need changes beyond reusing connections.

Interaction with clustering

If you also enable clustering, tile requests stay cluster-aware. Document Engine resolves the owner node for a document and runs the rendering process on that owner. The client still receives the response on the connection it originally opened.

This behavior is supported:

• Tile requests for a given document_id go to the same owner node that handles other document-scoped requests for that document.
• If ownership moves during a scale event, in-flight rendering processes can finish, and subsequent requests resolve to the new owner.
• During graceful shutdown, Document Engine drains remote rendering processes before the node exits.

You don’t have to enable clustering to use shared rendering, and you don’t have to enable shared rendering to use clustering. Enable them independently, or enable both together.

Observability

The shared rendering path emits telemetry events that you can export through your monitoring pipeline.

Notable event names include:

• http2.stream.worker_checkout
• http2.stream.render_tile
• http2.stream.render_process.exists
• http2.stream.render_process.new

Standard request logs and the Sent 200 in ... timing line still apply. Refer to the metrics reference and logs guides for more information.

Related configuration

• Large documents — Refer to the large documents guide to plan upload and timeout settings before you enable shared rendering for large files.
• Horizontal scaling — Refer to the horizontal scaling guide to understand how clustering changes routing for document-scoped requests, including tile requests.
• Configuration options — Refer to the configuration options guide for the full environment variable reference.