bookclerk_plugin_sdk.sparse_workerd.config
Materialize Cap'n Proto workerd config + bridge (mirrors config.rs).
Writes .bookclerk/ bridge + adapter assets and a Cap'n Proto config that embeds plugin
modules plus the injected Python/JS SDK. Used by the sparse smoke launcher and
authoring tools that do not ship the Rust bookclerk-workerd binary.
| Name | Kind | Summary |
|---|---|---|
GeneratedConfig |
class | Paths produced by materialize_config. |
manifest_capabilities |
function | Typed capability declaration a manifest implies (mirrors Rust capabilities()). |
manifest_describe_json |
function | PLUGIN_DESCRIBE JSON the adapter answers describe() from. |
escape_capnp |
function | Escape a string for embedding inside Cap'n Proto double quotes. |
is_legacy_sdk_embed |
function | Return whether name is a legacy vendored SDK path to skip. |
module_field_for |
function | Map a module filename to its Cap'n Proto embed field. |
collect_modules |
function | Collect embeddable module files under directory. |
plugin_global_outbound |
function | Map network mode to the plugin worker globalOutbound service name. |
own_user_agent_hosts_for |
function | Put own-agent host patterns into the ASCII form the egress worker matches. |
egress_domains_for |
function | Build the egress allow-list, adding Pyodide hosts when needed. |
allocate_workerd_state_dir |
function | Allocate a unique writable session directory for workerd generated embeds. |
materialize_config |
function | Write bridge assets and Cap'n Proto under a host session directory. |
SDK_JS_MODULE_NAMES |
constant | Module names used when embedding the TypeScript workerd SDK. |
SDK_PY_WORKERD_MODULE |
constant | Isolate module path for the Python workerd BookclerkEntrypoint base. |
SDK_PY_INIT_MODULE |
constant | Isolate module path for the package __init__ stub. |
SDK_PY_SIBLING_MODULES |
constant | SDK modules workerd.py imports inside the isolate, injected beside it, plus scan_page.py, which authors import directly. |
PYODIDE_EGRESS_HOSTS |
constant | Extra egress hosts allowed for Python Workers / Pyodide package fetch. |
SDK_PY_INIT |
constant | Source text embedded as bookclerk_plugin_sdk/__init__.py in the isolate. |
ADAPTER_JS |
constant | First-party adapter isolate module (mirrors ADAPTER_JS in config.rs). |
ENTRYPOINT_SERVICE_BINDINGS |
constant | (binding, exported class) the adapter receives per manifest entrypoint. |
class GeneratedConfig(NamedTuple)
Paths produced by materialize_config.
Fields
config_path: Pathlisten_addr: strstate_dir: Pathimport_path: Path
def manifest_capabilities(m: dict[str, Any]) -> dict[str, Any]
Typed capability declaration a manifest implies (mirrors Rust capabilities()).
Args
m: Validated manifest dict.
Returns
Wire-shaped PluginCapabilities object.
def manifest_describe_json(m: dict[str, Any]) -> str
PLUGIN_DESCRIBE JSON the adapter answers describe() from.
Args
m: Validated manifest dict.
Returns
Serialized wire-shaped PluginDescribe projection.
def escape_capnp(s: str) -> str
Escape a string for embedding inside Cap'n Proto double quotes.
Args
s: Raw string to escape.
Returns
Escaped string safe for Cap'n Proto text literals.
def is_legacy_sdk_embed(name: str) -> bool
Return whether name is a legacy vendored SDK path to skip.
Args
name: Module path relative to the pluginmodules/directory.
Returns
True if the file should be omitted in favor of host injection.
def module_field_for(name: str) -> tuple[str, bool]
Map a module filename to its Cap'n Proto embed field.
Args
name: Module path (used for extension detection).
Returns
A (field_name, is_python) pair such as ("pythonModule", True).
Raises
ValueError: When the extension is not implemented yet.
def collect_modules(directory: Path, *, plugin_root: Path | None=None) -> list[Path]
Collect embeddable module files under directory.
Symlinks are refused (matching the Rust workerd walker) so a nested
modules/leak -> /outside cannot recurse or embed files outside the
plugin install tree. The modules root itself is checked against
plugin_root (or directory when omitted) so a symlinked modules
directory cannot promote an outside tree into the embed set.
Args
directory: Plugin modules root to walk recursively.plugin_root: Original trusted plugin root; defaults todirectory.
Returns
Sorted list of .js/.mjs/.py/.wasm/.json file paths.
Raises
ValueError: When a directory entry or the modules root is a symlink.
def plugin_global_outbound(mode: str) -> str
Map network mode to the plugin worker globalOutbound service name.
Args
mode: Manifest network mode (outboundor deny-style).
Returns
"egress" for outbound mode, otherwise "blocked".
def own_user_agent_hosts_for(hosts: list[Any]) -> list[str]
Put own-agent host patterns into the ASCII form the egress worker matches.
As the host's policy does: UTS 46 IDNA for the name, the *. prefix
kept; a host it would refuse is left out.
Args
hosts:capabilities.network.own_user_agent.hostsas written.
Returns
The patterns that normalize, lowercased and in A-label form.
def egress_domains_for(needs_python: bool, mode: str, base: list[str]) -> list[str]
Build the egress allow-list, adding Pyodide hosts when needed.
Args
needs_python: Whether the plugin embeds Python modules.mode: Network mode from the manifest.base: Domains declared incapabilities.network.domains.
Returns
Domain list possibly extended with PYODIDE_EGRESS_HOSTS.
def allocate_workerd_state_dir(plugin_root: Path) -> Path
Allocate a unique writable session directory for workerd generated embeds.
Keys the leaf by a short hash of the plugin root plus a random suffix from
tempfile.mkdtemp under the OS temp dir — never mkdir of a raw operator
TMPDIR / plugin-root join (local threat-model path sink).
Args
plugin_root: Plugin install root (used only as an opaque id seed).
Returns
Absolute session directory.
def materialize_config(
plugin_root: Path,
manifest: dict[str, Any],
*,
listen_port: int,
bridge_token: str,
sdk_root: Path | None=None,
state_dir: Path | None=None,
config_name: str='workerd-config.capnp',
) -> GeneratedConfig
Write bridge assets and Cap'n Proto under a host session directory.
Generated embeds (.bookclerk/, Cap'n Proto) are written under
state_dir (allocated under $TMPDIR when omitted). Author modules
stay on the read-only install root and are referenced via Cap'n Proto
/modules/… embeds resolved with workerd serve --import-path.
Args
plugin_root: Plugin directory that containsmodules/.manifest: Parsedplugin.tomlmapping (must include[workerd]).listen_port: Loopback TCP port for the bridge RPC socket.bridge_token: Bearer token required by the bridge HTTP surface.sdk_root: SDK package root for bridge/SDK embeds (defaults to this package).state_dir: Existing session directory, orNoneto allocate one.config_name: Output Cap'n Proto filename under the session directory.
Returns
GeneratedConfig with config path, listen address, session dir,
and import path for --import-path.
Raises
ValueError: If[workerd]is missing, the compatibility date or flags are rejected, KV or Queues are declared, orbridge_tokenis empty.FileNotFoundError: If bridge assets, modules, main module, or SDK embeds cannot be found.
SDK_JS_MODULE_NAMES = ('@bookclerk/plugin-sdk/workerd', '@bookclerk/plugin-sdk')
Module names used when embedding the TypeScript workerd SDK.
SDK_PY_WORKERD_MODULE = 'bookclerk_plugin_sdk/workerd.py'
Isolate module path for the Python workerd BookclerkEntrypoint base.
SDK_PY_INIT_MODULE = 'bookclerk_plugin_sdk/__init__.py'
Isolate module path for the package __init__ stub.
SDK_PY_SIBLING_MODULES = (('bookclerk_plugin_sdk/_abi.py', '_abi.py', 'sdk-product-abi.py'), ('bookcle...
SDK modules workerd.py imports inside the isolate, injected beside it,
plus scan_page.py, which authors import directly.
Each entry is (isolate module path, source file name, embedded file name).
Together with __init__.py and workerd.py this is the SDK's in-package
import closure, lazy imports included; the launcher (bookclerk-workerd)
and the TypeScript sparse config inject the same list.
PYODIDE_EGRESS_HOSTS = ('cdn.jsdelivr.net', 'pypi.org', 'files.pythonhosted.org')
Extra egress hosts allowed for Python Workers / Pyodide package fetch.
SDK_PY_INIT = '"""Bookclerk plugin SDK (workerd isolate).\n\nUse: from bookclerk_plugin_sdk...
Source text embedded as bookclerk_plugin_sdk/__init__.py in the isolate.
ADAPTER_JS = 'import { wrapPluginFromBinding } from "@bookclerk/plugin-sdk/workerd";\nexpo...
First-party adapter isolate module (mirrors ADAPTER_JS in config.rs).
ENTRYPOINT_SERVICE_BINDINGS: dict[str, tuple[str, str]] = {'storefront': ('PLUGIN_STOREFRONT', 'Storefront'), 'storage': ('PLUGIN_STORA...
(binding, exported class) the adapter receives per manifest entrypoint.
Generated from packages/plugin-sdk-python at main · View as Markdown