bookclerk_plugin_sdk.sparse_workerd.ensure

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

Download / refresh the pinned Cloudflare workerd binary (mirrors ensure.rs).

Resolves the platform asset from workerd-pin.json, verifies sha256, and caches under the operator-selected directory (BOOKCLERK_WORKERD_CACHE or ~/.cache/bookclerk/workerd).

Name Kind Summary
package_root function Return the bookclerk_plugin_sdk package directory.
load_pin function Load the pinned workerd release metadata.
platform_key function Map OS/arch to a pin asset key such as linux-x86_64.
binary_name function Return the on-disk workerd binary filename for this OS.
download_url function Build the GitHub release download URL for a workerd artifact.
default_cache_dir function Resolve the workerd binary cache directory.
validate_fetch_url function Validate a URL before urlopen / download (request-forgery guard).
validate_spawn_executable function Validate a workerd (or helper) binary path before subprocess spawn.
ensure_workerd function Ensure a pinned workerd binary is available locally.

Functions

package_root

def package_root() -> Path

Return the bookclerk_plugin_sdk package directory.

Returns

Absolute path containing workerd.py, bridge/, and the pin file.

load_pin

def load_pin(root: Path | None=None) -> dict[str, Any]

Load the pinned workerd release metadata.

Args

  • root: Package root containing workerd-pin.json (defaults to this SDK).

Returns

Parsed pin dictionary (release tag, assets, version stamp).

Raises

  • FileNotFoundError: If the pin file is missing.
  • json.JSONDecodeError: If the pin file is not valid JSON.

platform_key

def platform_key(system: str | None=None, machine: str | None=None) -> str | None

Map OS/arch to a pin asset key such as linux-x86_64.

Args

  • system: OS name override (defaults to platform.system()).
  • machine: CPU arch override (defaults to platform.machine()).

Returns

Pin key string, or None when the platform is unsupported.

binary_name

def binary_name() -> str

Return the on-disk workerd binary filename for this OS.

Returns

workerd.exe on Windows, otherwise workerd.

download_url

def download_url(pin: dict[str, Any], artifact: str) -> str

Build the GitHub release download URL for a workerd artifact.

Args

  • pin: Loaded pin metadata containing release_tag.
  • artifact: Asset filename from the pin assets table.

Returns

Absolute HTTPS URL to the Cloudflare workerd release asset.

default_cache_dir

def default_cache_dir() -> Path

Resolve the workerd binary cache directory.

Honors BOOKCLERK_WORKERD_CACHE as the selected install root (any writable location, including paths outside $HOME and this package). Otherwise uses ~/.cache/bookclerk/workerd. Derived files stay under that root.

Returns

Path to the cache directory (may not exist yet).

validate_fetch_url

def validate_fetch_url(url: str) -> str

Validate a URL before urlopen / download (request-forgery guard).

Allows https: anywhere, or http: only to loopback hosts.

Args

  • url: Absolute URL string.

Returns

The same URL when it passes scheme/host checks.

Raises

  • ValueError: When the URL is invalid or uses a disallowed scheme/host.

validate_spawn_executable

def validate_spawn_executable(
    bin_path: Path | str,
    trusted_root: Path | str | None=None,
) -> Path

Validate a workerd (or helper) binary path before subprocess spawn.

Requires an absolute path with no NUL bytes. When trusted_root is set, requires the binary to stay under that root via resolve_under.

Args

  • bin_path: Candidate executable path.
  • trusted_root: Optional directory the binary must remain under.

Returns

Absolute validated Path.

Raises

  • ValueError: When the path is relative, contains NUL, or escapes trusted_root.

ensure_workerd

def ensure_workerd(cache_dir: Path | None=None, root: Path | None=None) -> Path

Ensure a pinned workerd binary is available locally.

Reuses BOOKCLERK_WORKERD_BIN or a cached binary when that file exists and the version stamp or --version output matches the pin. The selected cache directory is the trusted install root (not this package directory). A stamp without a binary is a cache miss.

Args

  • cache_dir: Override cache directory (defaults to default_cache_dir).
  • root: SDK root for loading workerd-pin.json.

Returns

Path to an executable workerd binary matching the pin.

Raises

  • RuntimeError: If no asset exists for this platform or the download hash mismatches.
  • OSError: If the binary cannot be written or executed.
  • ValueError: If a resolved binary path fails spawn validation.

Generated from packages/plugin-sdk-python at main · View as Markdown