Python plugin SDK

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

Last updated View as Markdown

This page shows how to write a Bookclerk plugin in Python with bookclerk-plugin-sdk (api_version = 3). A Python plugin is a Python Worker in a workerd isolate; bookclerk-workerd injects bookclerk_plugin_sdk.workerd and the modules it uses (including bookclerk_plugin_sdk.db_value for database bindings) into the isolate, so you import them rather than vendor a path.

Import What it holds
bookclerk_plugin_sdk.workerd BookclerkEntrypoint, CliEntrypoint and the js bridge
python -m bookclerk_plugin_sdk The author CLI

Install

pip install bookclerk-plugin-sdk          # from PyPI
pip install -e packages/plugin-sdk-python # from this repository

Declare Python Workers in plugin.toml:

api_version = 3
runtime = "workerd"
[workerd]
compatibility_flags = ["python_workers", "disable_python_external_sdk"]
main_module = "plugin.py"

Author model

The module-level Default class extends BookclerkEntrypoint and implements the triggers plugin.toml declares: event(batch) for [[events.consumers]], job(job) for [triggers] jobs, scheduled(controller) for [triggers] crons and database_migrations(binding) for [[databases]]. Every named entrypoint in entrypoints = [...] is a module-level class with the matching name extending its base: Storefront(StorefrontEntrypoint), Storage(StorageEntrypoint), RemoteLibrary(RemoteLibraryEntrypoint), DatabaseAdapter(DatabaseAdapterEntrypoint), Cli(CliEntrypoint), Oidc(OidcEntrypoint), Metadata(MetadataEntrypoint), Covers(CoverEntrypoint), MetadataFiles(MetadataFilesEntrypoint), Notifier(NotifierEntrypoint), Ingress(IngressEntrypoint) and Ai(AiEntrypoint). The Python SDK serves direct [ingress] plugins only; the ORIGIN binding a relay plugin hands requests to is in the TypeScript SDK.

from bookclerk_plugin_sdk.workerd import (
    BookclerkEntrypoint,
    CliEntrypoint,
    EventBatch,
    cli_args,
    json_payload,
)

class Cli(CliEntrypoint):
    async def describe(self):
        return {"commands": [{"name": "ping", "about": "Probe", "args": []}]}

    async def invoke(self, params):
        message = cli_args(params).get("message", "hi")
        return {
            "exitCode": 0,
            "stdout": f"pong: {message}\n",
            "stderr": "",
            "payload": json_payload({"pong": message}),
        }

class Default(BookclerkEntrypoint):
    async def event(self, batch: EventBatch):
        for msg in batch.messages:
            if msg.type != "book_acquired":
                msg.reject(f"unexpected {msg.type}")
                continue
            print(f"saw {msg.json().get('titleId', '')} via {self.env.CONFIG}")
            msg.ack()

Identity (apiVersion, id, capabilities) comes from plugin.toml; an optional describe() on Default only refines displayName and similar fields.

A database adapter runs each host batch through execute_adapter_batch or execute_adapter_batch_streamed (in bookclerk_plugin_sdk.db_value), which stores the guest's replay receipt before COMMIT and, for a streamed reply, rolls back when the frames do not fit one scalar or the adapter's advertised streamed budget (execute_stream_limits(caps)) (see Isolate adapter batches).

Triggers

Each EventMessage records one outcome, ack(), retry(retry_at=..., delay_seconds=..., reason=...), reject(reason), dead_letter(reason) or suspend(checkpoint=..., wake_at=...), and the first call wins. Untouched messages ack on return and retry on raise. A job(job) handler returns to complete, raises to reject, or calls job.suspend(...) or job.retry_later(...).

The env bindings

Granted bindings arrive on self.env per invocation: CONFIG, SECRETS, EVENTS, WORK_FS, and one entry per [[databases]] binding. A binding's await limits() returns the DbCapabilities its session negotiated; a request or result over one of them raises a PluginError whose code is limit_exceeded and whose limit names the cap. On a host that predates limits() the call raises unsupported. all() reads through the session's streamed budget when it advertises one, prepare(sql).iterate() yields rows one at a time from the same read, db.chunk(statements) splits a long list into batches that each fit one request, and db.write_chunks(...) commits those batches resumably; see Working within database limits. A storefront's scan can hand its paging to scan_page(params, fetch) (from bookclerk_plugin_sdk.scan_page import scan_page, which also works inside a workerd isolate), which slices the store's own pages into replies the host accepts; see Paged scans. Generate a typed Env protocol from plugin.toml:

python -m bookclerk_plugin_sdk types .   # writes bookclerk_configuration.py

Pushed sockets

A plugin that declares [sockets] (see Pushed sockets) gets self.env.SOCKETS, a SocketsBinding shaped like Durable Objects' hibernatable WebSockets. The host holds the connection, so the plugin may sleep between messages, and each message reaches the default entrypoint:

class Default(BookclerkEntrypoint):
    async def scheduled(self, controller):
        if await self.env.SOCKETS.get_web_sockets():
            return
        await self.env.SOCKETS.connect(
            "wss://abs.example.com/socket.io/?EIO=4&transport=websocket",
            headers={"Authorization": f"Bearer {self.env.SECRETS['token']}"},
            auto_responses=[("2", "3")],  # answered without waking the plugin
            attachment={"library": "main"},
        )

    async def web_socket_message(self, ws, message):
        library = ws.deserialize_attachment()["library"]
        ...

    async def web_socket_close(self, ws, code, reason, was_clean):
        ...

Text arrives as str and binary as bytes. await ws.send(...), await ws.close(code, reason) and await ws.serialize_attachment(value) act on the host's socket; the attachment is JSON of at most 2 KiB, kept for the socket's life.

A remote library whose message announced a new user returns {"poll_events": True} from web_socket_message, and the host calls poll_events right away instead of at its next scheduled poll.

Inbound webhooks

A plugin that declares [[webhooks]] (see Inbound webhooks) gets self.env.WEBHOOKS, a WebhooksBinding:

class Default(BookclerkEntrypoint):
    async def scheduled(self, controller) -> None:
        page = await self.env.WEBHOOKS.pull("events", batch_size=50)
        if page.missed:
            await self.relist()  # requests expired unread: resynchronize
        for message in page.messages:
            await self.handle(json.loads(message.body))
        await self.env.WEBHOOKS.ack("events", acks=[m.lease_id for m in page.messages])

    async def webhook_delivered(self, name: str, waiting: int) -> None:
        """Optional: called on a running plugin as soon as a request is stored."""

await self.env.WEBHOOKS.url("events") returns the URL to hand the outside service, or None when the library has no public https address or webhooks are off. Each WebhookMessage has lease_id, timestamp (a UTC datetime), attempts, headers and body (bytes).

Network grant

self.env.NETWORK is the grant in effect, as a dict (see Network grant). A setting whose destination still awaits approval shows "state": "pending":

rows = self.env.NETWORK["settings"]
row = next((r for r in rows if r["key"] == "server_url"), None)
if row and row["state"] == "pending":
    raise RuntimeError(f"Approve {row['destination']} on the plugin's consent form")

A refused fetch answers 403 with an x-bookclerk-error: network_not_granted header; report it rather than retrying.

Testing database code

create_test_database() from bookclerk_plugin_sdk.testkit gives a pytest suite the same binding a host grants, served by the bookclerk-db-testkit executable under one capability profile with the plugin's database_migrations applied. bookclerk-plugin test . runs the suite once per profile (first-party, d1 and minimum):

from bookclerk_plugin_sdk.testkit import create_test_database

async with await create_test_database(migrations=MIGRATIONS) as db:  # profile from `bookclerk-plugin test`
    await db.binding.prepare("INSERT INTO notes (body) VALUES (?)").bind(body).run()

The echo_workerd_python example (examples/plugins-echo-workerd-python/) is a worked plugin: a notes table it writes with chunk(), lists with iterate() or key-paged reads, sizes with limits(), and tests under every profile. A plugin's own pyproject.toml is what makes bookclerk-plugin test run pytest. See Testing against the limits.

Author tools

python -m bookclerk_plugin_sdk check .
python -m bookclerk_plugin_sdk types .
python -m bookclerk_plugin_sdk package --out dist .
python -m bookclerk_plugin_sdk smoke .   # download the pinned workerd, then describe + health

smoke does not need a built bookclerk-workerd. It downloads the pinned Cloudflare workerd into ~/.cache/bookclerk/workerd (override with BOOKCLERK_WORKERD_CACHE or BOOKCLERK_WORKERD_BIN).

Next steps

Reference

The sections below are generated from the SDK's source: one page per module, and what the package itself exports.

Modules

Module Summary
bookclerk_plugin_sdk.abi GENERATED FILE - do not edit. Run python3 scripts/gen-plugin-abi.py --write after changing crates/bookclerk-plugin-abi/schema/plugin.capnp.
bookclerk_plugin_sdk.cli CLI entry: bookclerk-plugin / python -m bookclerk_plugin_sdk.
bookclerk_plugin_sdk.db_value Universal Cap'n database value domain (DbValue) and unpacked codec.
bookclerk_plugin_sdk.guest_sql Guest SQL classification — must match host guest_statement_kind.
bookclerk_plugin_sdk.limits Typed limit_exceeded errors: the SQL-v1 cap a request or result broke.
bookclerk_plugin_sdk.path_guard Path containment helpers for authoring tools and sparse workerd launchers.
bookclerk_plugin_sdk.plugin_migration Resource bounds for plugin-owned databaseMigrations registration.
bookclerk_plugin_sdk.scan_page Paging helper for a storefront's scan.
bookclerk_plugin_sdk.sparse_workerd Sparse out-of-tree workerd launcher (no Rust bookclerk-workerd binary).
bookclerk_plugin_sdk.sparse_workerd.config Materialize Cap'n Proto workerd config + bridge (mirrors config.rs).
bookclerk_plugin_sdk.sparse_workerd.ensure Download / refresh the pinned Cloudflare workerd binary (mirrors ensure.rs).
bookclerk_plugin_sdk.sparse_workerd.smoke Out-of-tree workerd plugin smoke: ensure → materialize → describe + health.
bookclerk_plugin_sdk.testkit Contract conformance test kit: a plugin database binding like the host's.
bookclerk_plugin_sdk.tools check / fmt / types / package / sync-embed — mirrors Rust/TS author tools.
bookclerk_plugin_sdk.workerd Workerd author runtime — BookclerkEntrypoint and the named entrypoints.

Bookclerk Python plugin guest SDK.

Provides the workerd guest surface via bookclerk_plugin_sdk.workerd. Authors define a module-level Default class extending bookclerk_plugin_sdk.workerd.BookclerkEntrypoint (event(batch) / job(job) triggers) plus one class per plugin.toml entrypoint (class Cli(CliEntrypoint), class Storage(StorageEntrypoint), …). Native guests use the Rust SDK (serve / PluginWorker). See docs/plugins/README.md.

Typical import:

  • Workerd: from bookclerk_plugin_sdk.workerd import BookclerkEntrypoint, CliEntrypoint, js
  • Tools: python -m bookclerk_plugin_sdk check|fmt|types|package|smoke

Every ABI struct, union, enum, and interface in bookclerk_plugin_sdk.abi and the product constants in bookclerk_plugin_sdk._abi are generated from crates/bookclerk-plugin-abi/schema/plugin.capnp — the single ABI source of truth.

Name Kind Summary
WriteChunksError class A DatabaseBinding.write_chunks run that failed part way.
PLUGIN_ERROR_CODES constant Stable PluginError.code strings. Unknown future codes are forwarded as-is; SDKs surface them as a local unknown while keeping the raw wire code.
PRODUCT_API_VERSION constant Product ABI version (plugin.toml api_version / describe().apiVersion).

Re-exports

Classes

WriteChunksError

class WriteChunksError(PluginError)

A DatabaseBinding.write_chunks run that failed part way.

code, message and details are the failed batch's.

Attributes

  • next: Statements committed before the failure; resume with start=next. The failed batch may have committed with its reply lost: resuming resends it under the same operation id, so the host replays its receipt instead of writing it twice.

WriteChunksError.init

def __init__(self, next_offset: int, cause: PluginError) -> None

Constants

PLUGIN_ERROR_CODES

PLUGIN_ERROR_CODES: tuple[str, ...] = ('invalid_params', 'unauthorized', 'forbidden', 'not_found', 'unavailable', '...

Stable PluginError.code strings. Unknown future codes are forwarded as-is; SDKs surface them as a local unknown while keeping the raw wire code.

Wire strings of PluginErrorCode in ordinal order (snake_case Text codes).

PRODUCT_API_VERSION

PRODUCT_API_VERSION: int = 3

Product ABI version (plugin.toml api_version / describe().apiVersion).

Source: docs/plugins/sdk/python/README.md at main · View as Markdown