bookclerk_plugin_sdk.sparse_workerd.ensure
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. |
def package_root() -> Path
Return the bookclerk_plugin_sdk package directory.
Returns
Absolute path containing workerd.py, bridge/, and the pin file.
def load_pin(root: Path | None=None) -> dict[str, Any]
Load the pinned workerd release metadata.
Args
root: Package root containingworkerd-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.
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 toplatform.system()).machine: CPU arch override (defaults toplatform.machine()).
Returns
Pin key string, or None when the platform is unsupported.
def binary_name() -> str
Return the on-disk workerd binary filename for this OS.
Returns
workerd.exe on Windows, otherwise workerd.
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 containingrelease_tag.artifact: Asset filename from the pinassetstable.
Returns
Absolute HTTPS URL to the Cloudflare workerd release asset.
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).
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.
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 escapestrusted_root.
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 todefault_cache_dir).root: SDK root for loadingworkerd-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