Table of Contents

Class PoolOptions

Namespace
CobaltPdf.WebKit
Assembly
CobaltPDF.WebKit.dll

Configuration options for the rendering worker pool and the bundle provisioner. The defaults are sized for a typical Azure App Service Linux dyno; override anything that does not fit your host.

public class PoolOptions
Inheritance
PoolOptions
Inherited Members

Properties

AutoDownloadBundle

If true (default), the library transparently downloads the matching bundle on first render when no pre-extracted bundle is found. Set to false to force a hard failure when the bundle is absent — useful in air-gapped environments where any outbound call should surface.

public bool AutoDownloadBundle { get; set; }

Property Value

bool

BrowserLeaseTimeout

Maximum time a caller waits for a free lease. Default 30 s.

public TimeSpan BrowserLeaseTimeout { get; set; }

Property Value

TimeSpan

BundleBaseUrl

Base URL the bundle tarball is fetched from. Null = use the manifest default (DefaultBaseUrl). The final URL is {BundleBaseUrl}/v{version}/cobalt-webkit-bundle-{rid}.tar.gz.

Override when self-hosting (private feed, air-gapped Artifactory). Also honoured via the COBALT_BUNDLE_BASE_URL environment variable when this property is left null.

public string? BundleBaseUrl { get; set; }

Property Value

string

BundleCacheDirectory

Directory used to cache extracted bundles. Null = auto-detect:

  • COBALT_BUNDLE_CACHE_DIR env var, if set.
  • /home/site/cobaltbundle if /home/site exists (Azure App Service Linux marker).
  • $XDG_CACHE_HOME/CobaltPdfWebKit, then ~/.cache/CobaltPdfWebKit.
  • /tmp/CobaltPdfWebKit as final fallback.
public string? BundleCacheDirectory { get; set; }

Property Value

string

BundleDownloadTimeout

Maximum time the bundle download is allowed to run. Default 5 minutes. A 500 MB tarball over a slow link can legitimately take that long.

public TimeSpan BundleDownloadTimeout { get; set; }

Property Value

TimeSpan

BundleSha256Override

Override for the expected bundle SHA-256, lower-case hex. Null = use the value pinned in BundleManifest. Set this only when self-hosting a bundle with a different content hash. Also honoured via the COBALT_BUNDLE_SHA256 environment variable when null.

public string? BundleSha256Override { get; set; }

Property Value

string

ContainerMemoryLimit

Per-render container memory cap (e.g. "2g"). Null = unlimited. Prefer MaxMemoryMb which gives a clean error message instead of an opaque OOM-kill exit code.

public string? ContainerMemoryLimit { get; set; }

Property Value

string

DockerExecutable

Optional override for the docker binary path.

public string DockerExecutable { get; set; }

Property Value

string

DockerImage

Docker image used on Windows / macOS development and by the explicit Docker fallback on Linux. Defaults to the public dev image published alongside this library — override only when self-hosting in a private registry or pinning a specific patch.

Replace ghcr.io/cobaltpdf with your own org/owner if you publish under a different namespace; see bundle/publish-image.sh.

This is a multi-arch image (linux/amd64 + linux/arm64), so it runs natively on Intel and Apple-Silicon Macs as well as Windows/WSL2.

public string DockerImage { get; set; }

Property Value

string

ExtraArgs

Engine-specific extra arguments. Chromium flags are accepted for API compatibility but ignored (this backend uses WebKitGTK, not Chromium).

public List<string> ExtraArgs { get; set; }

Property Value

List<string>

ForceDocker

Dev hosts only (Windows/macOS). Force the Docker backend instead of WSL — for a dev box that has Docker but not WSL. Off by default. Also enabled by COBALT_FORCE_DOCKER=1. Ignored on Linux — a Linux host always renders inline from the bundle, so this flag never turns a native Linux deployment into a (usually unavailable) docker-in-container call.

public bool ForceDocker { get; set; }

Property Value

bool

ForceWsl

Dev hosts only (Windows/macOS). Force the WSL backend, failing fast if WSL isn't available. Off by default. Also enabled by COBALT_FORCE_WSL=1. Ignored on Linux — a Linux deployment always renders inline from the bundle, so this flag is safe to leave set in code shared between dev and production.

public bool ForceWsl { get; set; }

Property Value

bool

MaxMemoryMb

Maximum memory (MiB) the render subprocess (inline or container) is allowed to consume.

  • Soft cap (in-process): render.py polls usage and aborts cleanly above this value, surfacing a descriptive error.
  • Hard cap (Docker only): --memory is set to MaxMemoryMb + 256 MB so the kernel OOM-kills before the host is affected.
Set 0 to disable both caps. Default 4096 MiB. 
public int MaxMemoryMb { get; set; }

Property Value

int

MaxSize

Maximum number of concurrent worker instances. Default 5.

public int MaxSize { get; set; }

Property Value

int

MaxUsesPerBrowser

Max number of renders per worker before it is recycled (process exits, fresh one takes its place). Default 5.

WebKitGTK accumulates ~200 MB of cache state per render in the worker's resident set even with per-render ephemeral WebContexts, because GTK, Cairo, Pango, fontconfig and pikepdf all keep their own caches. Recycling every 5 renders bounds steady-state RSS at the cold-start baseline (~460 MB) at the cost of a fresh-worker spin-up after every 5th job (~1 second of cold start, amortised across the next 5 renders).

Raise this if your workload is bursty and you'd rather pay for memory than for cold starts; lower it (or set it to 1) on memory-constrained hosts where you'd rather pay for cold starts than for memory.

public int MaxUsesPerBrowser { get; set; }

Property Value

int

MinSize

Minimum number of worker instances to keep warm. Default 1.

public int MinSize { get; set; }

Property Value

int

OnBundleDownloadProgress

Hook fired during bundle download/extract so the host app can surface progress (a spinner during startup, a log line, …). Null = silent.

public Action<BundleDownloadProgress>? OnBundleDownloadProgress { get; set; }

Property Value

Action<BundleDownloadProgress>

PostLoadSettle

Time to wait after page load before printing (a default safety net).

public TimeSpan PostLoadSettle { get; set; }

Property Value

TimeSpan

PreferWsl

Dev hosts only (Windows/macOS). When both WSL and Docker are available, prefer WSL. True by default — WSL is lighter, has no licensing surface, ships with Windows 10/11, and gives near-native render performance. Set false to prefer Docker (or use ForceDocker to force it). Ignored on Linux, which always renders inline.

public bool PreferWsl { get; set; }

Property Value

bool

QuietBundleDownload

When false (default), the provisioner writes a single human-readable notice to Console.Error at the start of a bundle download so customers' first-launch "why is this hanging?" question is answered. Set to true for silent production deployments where you only want the progress callback at OnBundleDownloadProgress to drive any UI.

public bool QuietBundleDownload { get; set; }

Property Value

bool

RenderTimeout

Maximum wall-clock time a single render may run before the worker is treated as wedged and force-recycled. The worker also self-aborts a stuck render internally (the value is passed through as RENDER_TIMEOUT_S); the C# side waits a small margin longer so a healthy-but-slow worker can report its own timeout error before we kill it. Prevents a hung render (e.g. a wedged cold-start child) from blocking the caller forever. Default 120 s.

public TimeSpan RenderTimeout { get; set; }

Property Value

TimeSpan

SkipWslDependencyCheck

Dev hosts only (Windows/macOS, WSL backend). When false (default), the first render against a WSL distro runs a one-time probe of the distro's glibc version (ldd --version) to select the correct bundle variant and surface a clear "install a newer distro" error if the glibc is too old — instead of a cryptic low-level loader failure. The bundle is fully self-contained (no apt packages required), so this is purely a glibc-compatibility check, not a dependency install check. Set true to skip it and fall back to the most-compatible variant — saves ~100–300 ms on the first call per distro.

public bool SkipWslDependencyCheck { get; set; }

Property Value

bool

StubModeOnWindows

When true and running on a non-Linux host, return a clearly-marked placeholder PDF (containing the URL that would have been rendered) instead of rendering for real. Lets developers exercise the surrounding integration — controllers, content-types, file downloads — on a Windows or macOS box without WSL or Docker installed.

On Linux this option has no effect — real WebKit rendering always runs.

Default: false in every build configuration, so Debug and Release behave identically and always render for real (via WSL on Windows / Docker otherwise). It is purely opt-in: set it to true only when you deliberately want placeholder output (e.g. unit-testing controllers without booting a backend). When it is false and no backend is available, the engine throws an actionable error ("run wsl --install Ubuntu…") rather than silently shipping a stub.

public bool StubModeOnWindows { get; set; }

Property Value

bool

WslDistribution

Name of the WSL distro to run renders in. Null = use the user's default distro (the one wsl.exe picks with no -d). Provide explicitly when a customer has multiple distros installed and only one is glibc-compatible.

public string? WslDistribution { get; set; }

Property Value

string