bookclerk_plugin_sdk.tools

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

Last updated View as Markdown

check / fmt / types / package / sync-embed — mirrors Rust/TS author tools.

Validates plugin.toml, formats manifests, generates the Env typing stub, vendors workerd embeds, and packs release archives. Workerd authors:

  • from bookclerk_plugin_sdk.workerd import BookclerkEntrypoint, js (bookclerk-workerd injects that module — no relative filepath embed)

See docs/plugins/README.md for manifest fields and runtime requirements.

Name Kind Summary
AppliedCompatibilityDate class Date passed to workerd, and a fallback warning when the author date is newer.
validate_author_compatibility_date function Reject a compatibility date that is not a real YYYY-MM-DD.
apply_author_compatibility_date function Resolve an author compatibility date against this Bookclerk release.
validate_author_compatibility_flags function Enforce the Python flag pair. Does not insert missing flags.
declares_python function True when the manifest declares Python. Flags are not evidence.
unimplemented_surface function Spawn/load refusal for a declared-but-unbuilt surface.
is_valid_queue_name function True when name is [a-z0-9][a-z0-9._-]* and at most 63 chars.
validate_module_declarations function Check main and [[modules]] extensions.
module_load_key function Relative key a modules-directory walk uses for a [[modules]] path.
workerd_module_is_embedded function True when the walk embeds this filename.
validate_logo function Classify and validate a plugin.toml logo value.
validate_plugin_id function Validate a plugin id against the strict [a-z0-9_]{2,32} grammar.
own_user_agent_host_ascii function Normalize an own-agent host to the form the host's policy holds.
validate_manifest function Validate a parsed plugin.toml mapping.
check_main_module_source function Check a workerd main module against the v3 author model.
check_plugin function Validate a plugin directory and its plugin.toml.
sync_embed function Vendor SDK sources under modules/ for offline workerd archives.
format_manifest function Emit canonical TOML matching Rust format_manifest gold fixtures.
fmt_plugin_toml function Format plugin.toml in place, or check that it is already canonical.
package_plugin function Pack a plugin into a .tar.gz archive and update SHA256SUMS.
env_properties_for function Compute the Env protocol members for a validated manifest.
render_env_types function Render the bookclerk_configuration.py typing stub for a validated manifest.
generate_types function Write bookclerk_configuration.py beside a plugin's plugin.toml.
PYTHON_WORKERD_FLAGS constant Compatibility flags required for Python Workers under bookclerk-workerd.
WORKERD_PIN_COMPAT_DATE constant Newest compatibility_date the pinned workerd binary honors.
MAX_QUEUE_NAME_LEN constant Longest queue name.
RESERVED_QUEUE_PREFIXES constant Queue-name prefixes only the host may use.
MIN_MESSAGE_RETENTION_SECS constant Shortest message_retention_period in seconds, as in Cloudflare Queues.
MAX_MESSAGE_RETENTION_SECS constant Longest message_retention_period in seconds (14 days), as in Cloudflare Queues.
HOST_EVENT_TYPES constant Domain event types only the host emits; plugins consume them but cannot produce them.
MAX_KV_NAMESPACE_VALUE_BYTES constant Largest max_value_bytes a [[kv_namespaces]] row may declare (1 MiB).
MAX_KV_NAMESPACE_KEYS constant Largest max_keys a [[kv_namespaces]] row may declare.
LOGO_EXTENSIONS constant Allowed file extensions for embedded plugin.toml logo paths.
MAX_OWN_USER_AGENT_HOSTS constant Most hosts one [capabilities.network.own_user_agent] table may list.
MAX_OWN_USER_AGENT_REASON_CHARS constant Longest own_user_agent.reason, in characters.
AI_TASK_NAMES constant Model tasks [ai].serves and [ai].calls may name.
ENTRYPOINT_NAMES constant Entrypoint wire names accepted in entrypoints.
ENTRYPOINT_EXPORT_CLASSES constant Exported class name the launcher binds for each entrypoints wire name.
TYPES_OUTPUT_FILE constant Default types output filename next to plugin.toml.
MAX_CRON_TRIGGERS constant Most [triggers] crons entries one manifest may declare.

Classes

AppliedCompatibilityDate

class AppliedCompatibilityDate(NamedTuple)

Date passed to workerd, and a fallback warning when the author date is newer.

Host surfaces (events, jobs, and later bindings) must follow applied. That is the date workerd actually runs.

Fields

  • applied: str
  • warning: str | None

Functions

validate_author_compatibility_date

def validate_author_compatibility_date(date: str) -> None

Reject a compatibility date that is not a real YYYY-MM-DD.

A date newer than the pin is still valid. Load falls back and warns; see apply_author_compatibility_date.

Args

  • date: workerd.compatibility_date.

Raises

  • ValueError: When the date is not a calendar day.

apply_author_compatibility_date

def apply_author_compatibility_date(date: str) -> AppliedCompatibilityDate

Resolve an author compatibility date against this Bookclerk release.

workerd enables flags whose default-on date is on or before the date it is given, and refuses a date newer than the one baked into the binary. Wrangler warns and starts at the newest date that binary supports.

Args

  • date: workerd.compatibility_date.

Returns

The date to pass to workerd, and a warning when it was clamped.

Raises

  • ValueError: When the date is not a calendar day.

validate_author_compatibility_flags

def validate_author_compatibility_flags(flags: list[Any], python: bool) -> None

Enforce the Python flag pair. Does not insert missing flags.

Args

  • flags: Author compatibility_flags.
  • python: True when the manifest declares a Python module. A disk-only .py file is not enough.

Raises

  • ValueError: When a flag is outside the allowlist or the pair is wrong.

declares_python

def declares_python(m: dict[str, Any]) -> bool

True when the manifest declares Python. Flags are not evidence.

An explicit path is the load-set key. name is that key only when path is omitted.

Args

  • m: Manifest dictionary.

Returns

Whether Python flags and Pyodide consent hosts apply.

unimplemented_surface

def unimplemented_surface(m: dict[str, Any]) -> str | None

Spawn/load refusal for a declared-but-unbuilt surface.

Every manifest surface is implemented today ([[kv_namespaces]] and [queues] included); the hook stays so a future table can refuse load with "not implemented yet" without touching the callers.

Args

  • m: Manifest dictionary.

Returns

The refusal, or None when load may continue.

is_valid_queue_name

def is_valid_queue_name(name: str) -> bool

True when name is [a-z0-9][a-z0-9._-]* and at most 63 chars.

Args

  • name: Candidate queue name.

Returns

Whether the grammar accepts it.

validate_module_declarations

def validate_module_declarations(main_module: str, modules: list[Any]) -> None

Check main and [[modules]] extensions.

Args

  • main_module: [workerd].main_module.
  • modules: [[modules]] rows.

Raises

  • ValueError: When a file would not be embedded or its type disagrees.

module_load_key

def module_load_key(modules_dir: str, raw: str) -> str

Relative key a modules-directory walk uses for a [[modules]] path.

. segments are dropped, then a leading modules-dir prefix is removed, so ./modules/index.js and modules/pkg/./echo.wasm match walk keys. .. segments are left in place.

Args

  • modules_dir: [workerd].modules_dir.
  • raw: Author path or name.

Returns

Slash-separated key with a leading modules-dir prefix removed.

workerd_module_is_embedded

def workerd_module_is_embedded(path: str) -> bool

True when the walk embeds this filename.

Args

  • path: Module path or filename.

Returns

Whether the extension is .js, .mjs, .py, .wasm, or .json.

def validate_logo(raw: str) -> tuple[str, str]

Classify and validate a plugin.toml logo value.

Mirrors Rust validate_logo. Accepts absolute http/https URLs or relative image paths under the plugin root.

Args

  • raw: Raw logo string from the manifest.

Returns

A (\"remote\"|\"embedded\", value) pair with the validated URL or normalized relative path.

Raises

  • ValueError: If the logo is empty, uses a bad scheme, includes userinfo, or is an unsafe / non-image embedded path.

validate_plugin_id

def validate_plugin_id(id: str) -> None

Validate a plugin id against the strict [a-z0-9_]{2,32} grammar.

Mirrors Rust validate_plugin_id. Ids are globally unique across plugins. Invalid characters are rejected — never rewritten — so a/b and a_b cannot collide. Leading/trailing whitespace is rejected (non-lossy), not stripped.

Args

  • id: Candidate plugin id from plugin.toml.

Raises

  • ValueError: If the id fails length, charset, or underscore rules.

own_user_agent_host_ascii

def own_user_agent_host_ascii(raw: str) -> str | None

Normalize an own-agent host to the form the host's policy holds.

Trimmed, trailing dots dropped, the *. prefix kept, and every label in lowercase A-label form. The result has no * name, no forbidden host character (IDNA can map a fullwidth comma to ,) and no invalid xn-- label.

Args

  • raw: Host as written in plugin.toml.

Returns

The normalized pattern, or None when the host would refuse it.

validate_manifest

def validate_manifest(m: dict[str, Any]) -> None

Validate a parsed plugin.toml mapping.

Args

  • m: Manifest dictionary (typically from tomllib.loads).

Raises

  • ValueError: If required fields, runtime tables, or network capabilities are missing or inconsistent.

check_main_module_source

def check_main_module_source(
    main_name: str,
    src: str,
    entrypoints: list[str],
    language: str,
) -> None

Check a workerd main module against the v3 author model.

Requires the SDK import and a BookclerkEntrypoint default class, rejects the removed BookclerkPlugin base, and requires a class per manifest entrypoint (class Storage(StorageEntrypoint) for Python, export class Storage for JavaScript).

Args

  • main_name: Main module filename (for messages).
  • src: Main module source text.
  • entrypoints: Manifest entrypoints wire names.
  • language: "python" or "js".

Raises

  • ValueError: When the module does not follow the author model.

check_plugin

def check_plugin(plugin_dir: Path) -> str

Validate a plugin directory and its plugin.toml.

Args

  • plugin_dir: Path to the plugin root containing plugin.toml.

Returns

A short ok id=... entrypoints=... runtime=... status string.

Raises

  • ValueError: If the manifest or Python workerd sources are invalid.
  • FileNotFoundError: If required logo, modules, or native binaries are missing.
  • OSError: If plugin.toml cannot be read.

Examples

>>> # print(check_plugin(Path("./my-plugin")))
>>> # ok id=echo entrypoints=storefront runtime=workerd

sync_embed

def sync_embed(plugin_dir: Path) -> str

Vendor SDK sources under modules/ for offline workerd archives.

Prefer package imports — bookclerk-workerd injects bookclerk_plugin_sdk.workerd at runtime. This writes the same files so a staged tree is self-contained without host injection. It does not insert compatibility flags; the host and check require the author to write them.

Args

  • plugin_dir: Path to a workerd Python plugin root.

Returns

Status string describing the synced path (and flag updates, if any).

Raises

  • ValueError: If the plugin is not a Python workerd guest.
  • OSError: If files cannot be read or written.

Examples

>>> # print(sync_embed(Path("./my-python-workerd-plugin")))

format_manifest

def format_manifest(m: dict[str, Any]) -> str

Emit canonical TOML matching Rust format_manifest gold fixtures.

Flags are emitted as written. This function does not insert the Python pair.

Args

  • m: Validated manifest dictionary.

Returns

Canonical plugin.toml text ending with a newline.

fmt_plugin_toml

def fmt_plugin_toml(path: Path, *, check_only: bool) -> str

Format plugin.toml in place, or check that it is already canonical.

Args

  • path: Path to plugin.toml.
  • check_only: When True, raise if reformatting would change the file.

Returns

Status string (ok … or wrote …).

Raises

  • ValueError: If validation fails or check_only finds a drift.
  • OSError: If the file cannot be read or written.

package_plugin

def package_plugin(plugin_dir: Path, out_dir: Path) -> Path

Pack a plugin into a .tar.gz archive and update SHA256SUMS.

Args

  • plugin_dir: Path to the plugin root.
  • out_dir: Destination directory for the archive and checksums file.

Returns

Path to the created .tar.gz archive.

Raises

  • ValueError: If the manifest is invalid.
  • FileNotFoundError: If a required native binary, modules tree, or logo is missing.
  • subprocess.CalledProcessError: If tar fails.

Examples

>>> # archive = package_plugin(Path("./my-plugin"), Path("./dist"))
>>> # print(f"packed {archive}")

env_properties_for

def env_properties_for(m: dict[str, Any]) -> list[tuple[str, str, str]]

Compute the Env protocol members for a validated manifest.

Args

  • m: Validated manifest dict.

Returns

(binding, python_type, doc) tuples in stable emission order.

Raises

  • ValueError: When a [[databases]] binding collides with a reserved name or a binding is declared twice.

render_env_types

def render_env_types(m: dict[str, Any]) -> str

Render the bookclerk_configuration.py typing stub for a validated manifest.

The stub declares an Env typing.Protocol naming every binding the manifest grants so editors and type checkers can follow self.env.<BINDING> inside BookclerkEntrypoint subclasses.

Args

  • m: Validated manifest dict.

Returns

Python source text (ends with a newline).

Raises

  • ValueError: When binding names collide.

generate_types

def generate_types(plugin_dir: Path, out_file: Path | None=None) -> str

Write bookclerk_configuration.py beside a plugin's plugin.toml.

Args

  • plugin_dir: Plugin root containing plugin.toml.
  • out_file: Optional output path (default <plugin_dir>/bookclerk_configuration.py).

Returns

Status string naming the written file.

Raises

  • ValueError: When the manifest is invalid or bindings collide.
  • OSError: If files cannot be read or written.

Constants

PYTHON_WORKERD_FLAGS

PYTHON_WORKERD_FLAGS = ('python_workers', 'disable_python_external_sdk')

Compatibility flags required for Python Workers under bookclerk-workerd.

WORKERD_PIN_COMPAT_DATE

WORKERD_PIN_COMPAT_DATE = '2026-11-13'

Newest compatibility_date the pinned workerd binary honors.

MAX_QUEUE_NAME_LEN

MAX_QUEUE_NAME_LEN = 63

Longest queue name.

RESERVED_QUEUE_PREFIXES

RESERVED_QUEUE_PREFIXES = ('core.', 'node.')

Queue-name prefixes only the host may use.

MIN_MESSAGE_RETENTION_SECS

MIN_MESSAGE_RETENTION_SECS = 60

Shortest message_retention_period in seconds, as in Cloudflare Queues.

MAX_MESSAGE_RETENTION_SECS

MAX_MESSAGE_RETENTION_SECS = 1209600

Longest message_retention_period in seconds (14 days), as in Cloudflare Queues.

HOST_EVENT_TYPES

HOST_EVENT_TYPES = frozenset({'book_acquired', 'edition_acquire_changed', 'edition_linked', 'edi...

Domain event types only the host emits; plugins consume them but cannot produce them.

MAX_KV_NAMESPACE_VALUE_BYTES

MAX_KV_NAMESPACE_VALUE_BYTES = 1048576

Largest max_value_bytes a [[kv_namespaces]] row may declare (1 MiB).

MAX_KV_NAMESPACE_KEYS

MAX_KV_NAMESPACE_KEYS = 1000000

Largest max_keys a [[kv_namespaces]] row may declare.

LOGO_EXTENSIONS

LOGO_EXTENSIONS = ('.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg', '.ico')

Allowed file extensions for embedded plugin.toml logo paths.

MAX_OWN_USER_AGENT_HOSTS

MAX_OWN_USER_AGENT_HOSTS = 32

Most hosts one [capabilities.network.own_user_agent] table may list.

MAX_OWN_USER_AGENT_REASON_CHARS

MAX_OWN_USER_AGENT_REASON_CHARS = 300

Longest own_user_agent.reason, in characters.

AI_TASK_NAMES

AI_TASK_NAMES = ('textEmbeddings',)

Model tasks [ai].serves and [ai].calls may name.

ENTRYPOINT_NAMES

ENTRYPOINT_NAMES: tuple[str, ...] = ('storefront', 'storage', 'databaseAdapter', 'remoteLibrary', 'cli', 'oidc', ...

Entrypoint wire names accepted in entrypoints.

ENTRYPOINT_EXPORT_CLASSES

ENTRYPOINT_EXPORT_CLASSES: dict[str, str] = {'storefront': 'Storefront', 'storage': 'Storage', 'databaseAdapter': 'Databa...

Exported class name the launcher binds for each entrypoints wire name.

TYPES_OUTPUT_FILE

TYPES_OUTPUT_FILE = 'bookclerk_configuration.py'

Default types output filename next to plugin.toml.

MAX_CRON_TRIGGERS

MAX_CRON_TRIGGERS = 8

Most [triggers] crons entries one manifest may declare.

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