bookclerk_workerd::config
Generate a real workerd Cap'n Proto config for one plugin isolate.
| Item | Kind | Summary |
|---|---|---|
BindingSpec |
struct | One workerd binding the wrapper or author isolate may receive. |
GeneratedConfig |
struct | Materialize bridge assets + config under root, return config path and socket addr hint. |
ListenSpec |
enum | How the bridge HTTP socket is exposed to bookclerk-workerd. |
EntrypointSource |
enum | How the plugin worker entrypoint is produced. |
BindingTarget |
enum | Realization of a BindingSpec. |
workerd_state_dir |
function | Where bridge assets + Cap'n Proto config are written. |
host_state_dir |
function | Host-chosen session directory from WORKERD_STATE_DIR_ENV. |
validate_host_state_dir |
function | Require dir to be an existing owner-only directory under $TMPDIR. |
adapter_binding_plan |
function | Bindings the generated adapter isolate receives (not the author isolate). |
entrypoint_binding |
function | Adapter binding name and author-exported class name for one named entrypoint (storefront → PLUGIN_STOREFRONT / Storefront). |
adapter_entrypoint_bindings |
function | PLUGIN_<ENTRYPOINT> service bindings the adapter isolate receives for every named entrypoint in manifest.entrypoints, in manifest order. |
manifest_describe_json |
function | Manifest-derived PluginDescribe bound on the adapter as PLUGIN_DESCRIBE. |
generated_backend_proxy_plan |
function | Entrypoint + bindings for a generated native-behind-workerd proxy. |
materialize_native_backend |
function | Materialize a generated control-plane adapter isolate for a native guest (no author [workerd] modules). |
materialize |
function | Materialize bridge assets + Cap'n Proto config into a writable state dir. |
plugin_global_outbound |
function | Plugin isolate globalOutbound: Deny → blocked; Outbound → egress proxy. |
egress_domains_for |
function | Egress allowlist: plugin domains, plus Pyodide CDN hosts when Python + Outbound. |
WORKERD_SERVE_EXPERIMENTAL |
constant | workerd serve flag that unlocks $experimental compatibility flags. |
SDK_JS_MODULE_NAMES |
constant | Package import names authors use for the workerd BookclerkEntrypoint SDK. |
SDK_PY_WORKERD_MODULE |
constant | Python package path for from bookclerk_plugin_sdk.workerd import …. |
SDK_PY_DB_VALUE_MODULE |
constant | Python module path for typed SQL value / execute codec helpers. |
SDK_PY_PRODUCT_ABI_MODULE |
constant | Python module path for the generated product ABI constants. |
SDK_PY_CAPNP_MODULE |
constant | Python module path for the Cap'n Proto reader and builder. |
SDK_PY_WIRE_MODULE |
constant | Python module path for the generated ABI codecs. |
SDK_PY_GUEST_SQL_MODULE |
constant | Python module path for guest-side SQL statement classification helpers. |
SDK_PY_LIMITS_MODULE |
constant | Python module path for the typed limit_exceeded helpers. |
SDK_PY_PLUGIN_MIGRATION_MODULE |
constant | Python module path for the plugin-owned migration registration checks. |
SDK_PY_SCAN_PAGE_MODULE |
constant | Python module path for the storefront scan paging helper. |
SDK_PY_INIT_MODULE |
constant | Python module path that initializes the sparse workerd guest SDK. |
WORKERD_STATE_DIR_ENV |
constant | Env var the host sets to the per-session workerd state directory. |
pub struct BindingSpec {
pub name: String,
pub target: BindingTarget,
}
One workerd binding the wrapper or author isolate may receive.
Fields
name: Binding name (HTTP,STORAGE,GRANTED, …).target: Where the binding is realized.
Implements: Clone, Debug
pub struct GeneratedConfig {
pub config_path: PathBuf,
pub listen: ListenSpec,
pub state_dir: PathBuf,
pub import_path: PathBuf,
}
Materialize bridge assets + config under root, return config path and socket addr hint.
Fields
config_path: Path to the generated workerd config file.listen: Listen address for the bridge socket.state_dir: Writable state directory for the isolate (outside the install root).import_path: Pass toworkerd serve -Iso Cap'n Proto/modules/…embeds resolve against the read-only plugin install root.
pub enum ListenSpec {
TcpLoopback(u16),
ReportedTcp,
Inherited,
}
How the bridge HTTP socket is exposed to bookclerk-workerd.
Variants
-
TcpLoopback:127.0.0.1:port— workerd binds a port the caller chose (unconfined smoke). -
ReportedTcp: workerd binds127.0.0.1:0itself and reports the port the operating system picked on its control channel (--control-fd, read withcrate::control::listen_port). Used on Windows, which has no--socket-fd: reserving a port, releasing it and letting workerd rebind it races every other bind on the host (issue #781).The generated config turns on structured logging with this variant, so isolate
console.*output on the shared stdout cannot pose as a control message. -
Inherited: The launcher already bound the bridge listener (a Unix socket) and workerd inherits it with--socket-fd. Neither process needs an IP socket, so the jail can deny them all.
pub fn workerd_socket_line(&self) -> String
Cap'n Proto sockets entry for the bridge RPC listener.
Inherited FDs omit address — workerd gets --socket-fd=rpc=<fd>.
pub fn client_base_url(&self) -> Option<String>
HTTP origin the workerd isolate uses to call back into Bookclerk.
None for Self::ReportedTcp, whose port is known only once workerd
reports it, and for Self::Inherited, which is a Unix socket.
pub fn port(&self) -> Option<u16>
TCP port the bridge socket binds.
None for Self::ReportedTcp, whose port is known only once workerd
reports it on its control channel, and for Self::Inherited, which
is a Unix socket.
pub fn reports_port(&self) -> bool
Whether workerd must report the bound port on --control-fd.
Implements: Clone, Debug
pub enum EntrypointSource {
AuthorModules { modules_dir: String, main_module: String, entrypoint: Option<String> },
GeneratedBackendProxy { module_source: String, entrypoint: String },
}
How the plugin worker entrypoint is produced.
The hybrid executor lives above this crate (bookclerk-plugin-host).
bookclerk-workerd only materializes these seams. Do not add
PluginExecutor here — a later host executor consumes EntrypointSource
Variants
AuthorModules: Author modules from the installmodules/directory.modules_dir: Directory containing author ES modules (relative to plugin root).main_module: Main module filename insidemodules_dir.entrypoint: Optional exported entrypoint class name.
GeneratedBackendProxy: Generated first-party backend-proxy worker (native jail / later container).module_source: Module source the launcher writes into the state dir.entrypoint: Exported entrypoint class name.
Implements: Clone, Debug
pub enum BindingTarget {
IsolateService { service: String },
ExternalFetch { address: String },
}
Realization of a BindingSpec.
Variants
IsolateService: Another named workerd service (isolate RPC).service: Service name in the generated config.
ExternalFetch: Externalfetch()/ raw streaming HTTP (Unix socket on POSIX).address:unix:/pathorhost:port.
Implements: Clone, Debug
pub fn workerd_state_dir(plugin_root: &Path) -> Result<PathBuf>
Where bridge assets + Cap'n Proto config are written.
Prefer $TMPDIR (the guest scratch dir inside a jail). The plugin install
root is read-only under Landlock, so materializing .bookclerk/ there fails.
Each call allocates a unique leaf (w + root prefix + nonce) with exclusive
create_dir, so concurrent sessions of the same plugin cannot clobber
workerd-config.capnp. GRANTED / native-proxy sockets use Linux abstract
names (or a relative unix:granted.sock) so $TMPDIR may exceed
sockaddr_un.
Callers that bind sockets first (the launcher) must pass the returned path
into materialize / materialize_native_backend so config and sockets
share one directory.
plugin_root- Filesystem path (plugin_root).
On success, the inner PathBuf value.
Returns an error when the directory cannot be created exclusively.
pub fn host_state_dir() -> Result<PathBuf>
Host-chosen session directory from WORKERD_STATE_DIR_ENV.
Returns an error when the variable is unset or validate_host_state_dir
rejects the path.
pub fn validate_host_state_dir(dir: &Path) -> Result<PathBuf>
Require dir to be an existing owner-only directory under $TMPDIR.
Returns an error when the path is relative, contains .., is not a
directory, escapes the process temp root, or cannot be chmodded owner-only.
pub fn adapter_binding_plan(granted: bool) -> Vec<BindingSpec>
Bindings the generated adapter isolate receives (not the author isolate).
granted- When true, include the host reverse-channelGRANTEDbinding.
pub fn entrypoint_binding(entrypoint: Entrypoint) -> (String, String)
Adapter binding name and author-exported class name for one named
entrypoint (storefront → PLUGIN_STOREFRONT / Storefront).
entrypoint- Named entrypoint from the manifest.
(binding, class) pair the generated config binds on the adapter isolate.
pub fn adapter_entrypoint_bindings(manifest: &PluginManifest) -> Vec<(String, String)>
PLUGIN_<ENTRYPOINT> service bindings the adapter isolate receives for
every named entrypoint in manifest.entrypoints, in manifest order.
manifest- Parsed plugin manifest.
(binding, class) pairs; empty when the plugin exports no named entrypoint.
pub fn manifest_describe_json(manifest: &PluginManifest) -> Result<String>
Manifest-derived PluginDescribe bound on the adapter as PLUGIN_DESCRIBE.
The adapter answers describe from this projection and lets the author's
optional describe() refine presentation fields only.
manifest- Parsed plugin manifest.
Returns an error when the describe struct cannot be serialized as JSON.
pub fn generated_backend_proxy_plan() -> (EntrypointSource, Vec<BindingSpec>)
Entrypoint + bindings for a generated native-behind-workerd proxy.
Does not require an author [workerd] module tree and binds no data-plane
service: the adapter isolate only owns the control plane (GRANTED,
BRIDGE_TOKEN, PLUGIN_DESCRIBE).
pub fn materialize_native_backend(
root: &Path,
manifest: &PluginManifest,
egress: &EgressProxy,
limits: EffectiveWorkerdLimits,
listen: ListenSpec,
granted_addr: Option<&str>,
bridge_token: &str,
state_dir: Option<&Path>,
) -> Result<GeneratedConfig>
Materialize a generated control-plane adapter isolate for a native guest
(no author [workerd] modules).
The host executor owns the process tree: it launches workerd and the
verified native guest, and forwards every entrypoint call to the guest as
typed Cap'n Proto. The adapter isolate decides describe / open policy
from the manifest projection bound as PLUGIN_DESCRIBE. Plugin input
cannot choose the executable or weaken the sandbox.
state_dir is an existing session directory from workerd_state_dir, or
None to allocate a unique directory.
Returns an error when state-dir I/O, describe serialization, or the config write fails.
pub fn materialize(
root: &Path,
manifest: &PluginManifest,
egress: &EgressProxy,
limits: EffectiveWorkerdLimits,
listen: ListenSpec,
granted_addr: Option<&str>,
bridge_token: &str,
state_dir: Option<&Path>,
) -> Result<GeneratedConfig>
Materialize bridge assets + Cap'n Proto config into a writable state dir.
TMPDIR contents (guest-writable scratch) — only generated launcher state:
.bookclerk/— first-party bridge / egress / host stub / injected SDKworkerd-config.capnpgranted.sock(created by the launcher, not this function)
Author modules/ stay in the read-only install root. Cap'n Proto paths
that look absolute (/…) are resolved via --import-path (same rules as
import "/workerd/workerd.capnp"), not the filesystem root — so embeds are
/modules/… with the plugin install root passed as -I.
Today's launcher materializes EntrypointSource::AuthorModules from the
install tree and a distinct adapter isolate that alone receives
GRANTED / BRIDGE_TOKEN. EntrypointSource::GeneratedBackendProxy and
BindingSpec are seams for a later host executor (native jail / container
behind a generated fetch() proxy) — that path must not require author
[workerd] modules. Direct native Cap'n Proto remains a host-selected
fallback, not plugin-selectable policy bypass.
granted_addr is an optional workerd external address (host:port,
unix:/path, unix:granted.sock, or Linux unix-abstract:name) for the
adapter-private GRANTED capability channel.
bridge_token is a per-isolate bearer shared by the launcher and the bridge
/rpc + /health routes (BRIDGE_TOKEN binding).
root- Cargo workspace root directory.manifest- Parsed plugin manifest.egress-egressinput for this call.listen- Daemon listen address (host:portor URL).granted_addr- OptionalGRANTEDexternal service address.bridge_token- Per-isolate bridge bearer token.state_dir- Existing session directory fromworkerd_state_dir, orNoneto allocate a unique directory.
On success, the inner GeneratedConfig value.
Returns an error when the underlying I/O, parse, network, or store operation fails.
pub fn plugin_global_outbound(mode: NetworkMode) -> &'static str
Plugin isolate globalOutbound: Deny → blocked; Outbound → egress proxy.
mode- Network mode from the plugin manifest.
&'static str result.
pub fn egress_domains_for(
needs_python: bool,
mode: NetworkMode,
base: &[String],
) -> Vec<String>
Egress allowlist: plugin domains, plus Pyodide CDN hosts when Python + Outbound.
Uses the same host set as bookclerk_plugin_manifest::consent_domains_for so
materialize cannot silently widen beyond what consent_request / grants cover.
needs_python- Boolean flagneeds_python.mode- Network mode from the plugin manifest.base- Stringbasefor this call.
Collected results (may be empty).
pub const WORKERD_SERVE_EXPERIMENTAL: &str = "--experimental";
workerd serve flag that unlocks $experimental compatibility flags.
Required so the egress worker can export a connect() handler. Author
isolates do not receive this compat flag unless their own manifest lists it.
pub const SDK_JS_MODULE_NAMES: &[&str] = _;
Package import names authors use for the workerd BookclerkEntrypoint SDK.
pub const SDK_PY_WORKERD_MODULE: &str = "bookclerk_plugin_sdk/workerd.py";
Python package path for from bookclerk_plugin_sdk.workerd import ….
pub const SDK_PY_DB_VALUE_MODULE: &str = "bookclerk_plugin_sdk/db_value.py";
Python module path for typed SQL value / execute codec helpers.
pub const SDK_PY_PRODUCT_ABI_MODULE: &str = "bookclerk_plugin_sdk/_abi.py";
Python module path for the generated product ABI constants.
pub const SDK_PY_CAPNP_MODULE: &str = "bookclerk_plugin_sdk/_capnp.py";
Python module path for the Cap'n Proto reader and builder.
pub const SDK_PY_WIRE_MODULE: &str = "bookclerk_plugin_sdk/_wire.py";
Python module path for the generated ABI codecs.
pub const SDK_PY_GUEST_SQL_MODULE: &str = "bookclerk_plugin_sdk/guest_sql.py";
Python module path for guest-side SQL statement classification helpers.
pub const SDK_PY_LIMITS_MODULE: &str = "bookclerk_plugin_sdk/limits.py";
Python module path for the typed limit_exceeded helpers.
pub const SDK_PY_PLUGIN_MIGRATION_MODULE: &str = "bookclerk_plugin_sdk/plugin_migration.py";
Python module path for the plugin-owned migration registration checks.
pub const SDK_PY_SCAN_PAGE_MODULE: &str = "bookclerk_plugin_sdk/scan_page.py";
Python module path for the storefront scan paging helper.
pub const SDK_PY_INIT_MODULE: &str = "bookclerk_plugin_sdk/__init__.py";
Python module path that initializes the sparse workerd guest SDK.
pub const WORKERD_STATE_DIR_ENV: &str = bookclerk_sandbox::WORKERD_STATE_DIR_ENV;
Env var the host sets to the per-session workerd state directory.
Generated from crates/bookclerk-workerd at main · View as Markdown