bookclerk_plugin_manifest
plugin.toml schema — parse, validate, and canonical format.
This crate is the Rust projection of the install-time plugin descriptor.
It is shared by the host (bookclerk-plugin-host), the workerd launcher
(bookclerk-workerd), and the Rust guest SDK author tools (check /
fmt). Language SDKs (TypeScript / Python) validate against the committed
JSON Schema in PLUGIN_TOML_SCHEMA_JSON (schema/plugin-toml.json),
which must stay in sync with the types here.
- Host / launcher authors — parse manifests at discovery, build
EgressPolicyfor isolate injection, map network + OAuth bindings to jail policy viaPluginManifest::jail_network_need. - Plugin authors / SDK tools — validate and pretty-print
plugin.tomlwithout pulling host dependencies.
| Module | Responsibility |
|---|---|
cron |
Five-field UTC cron schedules for [triggers] crons |
egress |
Hostname allowlist policy, IDNA normalization, Pyodide hosts |
error |
Parse / validate error type |
fmt |
Canonical TOML serialization for fmt --check |
id |
Strict plugin id grammar |
logo |
Remote URL vs embedded path logo validation |
types |
PluginManifest and nested capability / workerd tables |
workerd_contract |
Compatibility date, Python flag allowlist, module extensions |
Product narrative: docs/plugins/README.md (network consent, egress matching,
packaging). ABI contract: bookclerk-plugin-abi.
use bookclerk_plugin_manifest::parse;
let manifest = parse(r#"
api_version = 3
id = "echo"
runtime = "native"
command = "./echo"
entrypoints = ["cli"]
[capabilities.network]
mode = "deny"
"#).expect("valid plugin.toml");
assert_eq!(manifest.id, "echo");
| Item | Kind | Summary |
|---|---|---|
parse |
function | Parses and validates a plugin.toml document. |
PLUGIN_TOML_SCHEMA_JSON |
constant | Embedded JSON Schema text for authoring tools (check in TS/Python SDKs). |
address::address_allowedaddress::canonical_ipaddress::is_local_networkaddress::is_public_internetaddress::is_restricted_hostnameaddress::workerd_network_allowaddress::CidrGrantcron::CronErrorcron::CronSchedulecron::UnixMinutecron::MAX_CRON_SOURCE_BYTESegress::consent_domains_foregress::host_matchesegress::host_user_agentegress::manifest_needs_pythonegress::normalize_domain_patternegress::normalize_hostnameegress::normalize_local_nameegress::normalize_own_user_agent_hostegress::normalize_tcp_hostegress::split_domain_entryegress::with_python_runtime_hostsegress::EgressPolicyegress::PendingSettingDestinationegress::TcpGrantegress::ANY_PUBLIC_HOSTegress::DEFAULT_MAX_REDIRECTSegress::FETCH_DEFAULT_PORTSegress::HOST_USER_AGENT_URLegress::PYODIDE_EGRESS_HOSTSerror::Errorerror::Resultfmt::format_manifestid::validate_plugin_idlogo::embedded_logo_api_pathlogo::logo_content_typelogo::validate_logologo::LogoKindlogo::LOGO_EXTENSIONSlogo::MAX_EMBEDDED_LOGO_BYTESsetting_network::derive_setting_destinationsetting_network::DestinationScopesetting_network::SettingDestinationsetting_network::SettingDestinationErrorwebhooks::is_valid_webhook_namewebhooks::validate_webhookswebhooks::HmacSignaturewebhooks::SignatureEncodingwebhooks::WebhookManifestwebhooks::WebhookSignaturewebhooks::DEFAULT_WEBHOOK_MAX_BODY_BYTESwebhooks::DEFAULT_WEBHOOK_RATE_PER_MINUTEwebhooks::DEFAULT_WEBHOOK_RETENTION_SECSwebhooks::MAX_WEBHOOKSwebhooks::MAX_WEBHOOK_BODY_BYTESwebhooks::MAX_WEBHOOK_HEADERSwebhooks::MAX_WEBHOOK_RATE_PER_MINUTEwebhooks::MAX_WEBHOOK_RETENTION_SECSwebhooks::WEBHOOKS_BINDINGworkerd_contract::apply_author_compatibility_dateworkerd_contract::module_load_keyworkerd_contract::validate_author_compatibility_dateworkerd_contract::validate_author_compatibility_flagsworkerd_contract::validate_module_declarationsworkerd_contract::workerd_module_is_embeddedworkerd_contract::AppliedCompatibilityDateworkerd_contract::PYTHON_COMPATIBILITY_FLAGSworkerd_contract::WORKERD_PIN_COMPAT_DATEbookclerk_plugin_abi::Entrypointbookclerk_plugin_abi::EventConsumerSpecbookclerk_plugin_abi::PluginCapabilitiestypes::ALL_ENTRYPOINTStypes::REGISTRY_ENTRYPOINTStypes::entrypoint_familytypes::PluginFamilytypes::PluginRuntimeKindtypes::CredentialSharingtypes::MediaManifesttypes::MAX_DOWNLOADS_PER_DAYtypes::MAX_MIN_GAP_SECONDStypes::MAX_COOLDOWN_SECONDStypes::AcquireManifesttypes::IngressManifesttypes::IngressKindtypes::MetadataFilesManifesttypes::MetadataFileDialectManifesttypes::NotifierDestinationtypes::NotifierFormattypes::MAX_NOTIFIER_ADDRESS_FIELDStypes::MAX_NOTIFICATION_TYPEStypes::NotifierManifesttypes::NotifierAddressFieldtypes::NotificationsManifesttypes::NotificationTypeManifesttypes::AiManifesttypes::KNOWN_NOTIFICATION_HOSTStypes::SMTP_PORTStypes::reaches_notification_hosttypes::NetworkModetypes::TcpCapabilitytypes::NetworkCapabilitiestypes::MAX_OWN_USER_AGENT_REASON_CHARStypes::MAX_OWN_USER_AGENT_HOSTStypes::OwnUserAgenttypes::MAX_DATABASE_BINDINGStypes::MAX_DATABASE_BINDING_NAME_LENtypes::is_valid_database_binding_nametypes::BindingCapabilitiestypes::DatabaseBindingManifesttypes::NamedBindingtypes::KvNamespaceManifesttypes::DEFAULT_KV_MAX_VALUE_BYTEStypes::MAX_KV_VALUE_BYTEStypes::DEFAULT_KV_MAX_KEYStypes::MAX_KV_KEYStypes::DEFAULT_SECRETS_BINDINGtypes::DEFAULT_WORK_FS_BINDINGtypes::DEFAULT_OAUTH_BINDINGtypes::DEFAULT_SOCKETS_BINDINGtypes::NOTIFY_BINDINGtypes::AI_BINDINGtypes::DEFAULT_KV_BINDINGtypes::DEFAULT_EVENTS_BINDINGtypes::CONFIG_BINDINGtypes::NETWORK_BINDINGtypes::MAX_CRON_TRIGGERStypes::TriggersManifesttypes::CapabilitiesManifesttypes::EventConsumertypes::EventProducertypes::EventsManifesttypes::HOST_EVENT_TYPEStypes::is_host_event_typetypes::MAX_QUEUE_NAME_LENtypes::RESERVED_QUEUE_PREFIXEStypes::DEFAULT_QUEUE_MAX_BATCH_SIZEtypes::MAX_QUEUE_BATCH_SIZEtypes::DEFAULT_QUEUE_MAX_BATCH_TIMEOUT_SECStypes::MAX_QUEUE_BATCH_TIMEOUT_SECStypes::DEFAULT_QUEUE_MAX_RETRIEStypes::MAX_QUEUE_RETRIEStypes::MAX_QUEUE_RETRY_DELAY_SECStypes::MIN_MESSAGE_RETENTION_SECStypes::MAX_MESSAGE_RETENTION_SECStypes::is_valid_queue_nametypes::is_reserved_queue_nametypes::QueuesManifesttypes::QueueProducertypes::QueueConsumertypes::WorkerdRuntimeManifesttypes::WorkerdLimitstypes::EffectiveWorkerdLimitstypes::ModuleSpectypes::PluginManifesttypes::OidcManifesttypes::OidcClientTomltypes::JailNetworkNeed
address: Address-space policy independent of hostname matching.cron: Five-field cron schedules for[triggers] crons(Workersscheduled).egress: Shared host/egress allowlist policy (workerd JS bridge + native mediator).error: Manifest parse and semantic-validation errors.fmt: Canonicalplugin.tomlformatting for SDKfmt/fmt --check.id: Display-alias grammar shared by manifest parse, host registry, and SDKs.logo: Plugin logo validation: remotehttp(s)URL or relative image path.setting_network: Network destinations named by plugin settings.types:plugin.tomltypes: manifest root and nested capability / workerd tables.webhooks:[[webhooks]]: inbound HTTP endpoints the host serves for a plugin.workerd_contract: Author compatibility date, flag allowlist, and module-extension rules.
pub fn parse(text: &str) -> Result<PluginManifest>
Parses and validates a plugin.toml document.
Equivalent to [PluginManifest::parse]: deserializes TOML then runs
PluginManifest::validate.
text- Full contents of aplugin.tomlfile (UTF-8).
A validated PluginManifest.
Returns Error::TomlDe on malformed TOML, or Error::Message when
semantic validation fails (id grammar, runtime requirements, network
domains, logo, and so on).
use bookclerk_plugin_manifest::parse;
let m = parse(r#"
api_version = 3
id = "sqlite"
runtime = "native"
command = "./bookclerk-plugin-database-sqlite"
entrypoints = ["databaseAdapter"]
[capabilities.network]
mode = "deny"
"#).unwrap();
assert_eq!(m.primary_family().as_str(), "database");
pub const PLUGIN_TOML_SCHEMA_JSON: &str = "{\n \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n \"$id\": \"https://bookclerk.dev/schemas/plugin-toml.json\",\n \"title\": \"BookclerkPluginToml\",\n \"description\": \"Install descriptor for a Bookclerk plugin (plugin.toml), api_version = 3. Keys use TOML/snake_case. There is no plugin `kind`; handler family is derived from entrypoints and triggers. The `id` is a display/CLI alias, not a globally unique security identity. Durable identity is the host-computed provenance-qualified PluginKey. capabilities.network.domains is workerd-only (hostname allowlist for isolate fetch()). Native guests omit domains and declare capabilities.network.tcp for mediated connect(); ambient AF_INET is denied.\",\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"required\": [\"api_version\", \"id\", \"capabilities\"],\n \"properties\": {\n \"api_version\": { \"type\": \"integer\", \"enum\": [3] },\n \"id\": {\n \"type\": \"string\",\n \"minLength\": 2,\n \"maxLength\": 32,\n \"pattern\": \"^[a-z0-9]+(?:_[a-z0-9]+)*$\",\n \"description\": \"Display / CLI alias. Not globally unique and not a privilege. Lowercase letters, digits, and single underscores only (2\u{2013}32 chars); no leading/trailing or doubled `_`. When two installs share an alias, address them with a provenance-qualified PluginKey.\"\n },\n \"name\": { \"type\": \"string\" },\n \"version\": { \"type\": \"string\" },\n \"logo\": {\n \"type\": \"string\",\n \"description\": \"Optional Settings/UI logo: https:// or http:// URL (browser loads directly), or a relative image path under the plugin install root (host serves via GET /api/plugins/{id}/logo when the alias is unambiguous). Embedded paths must not contain \'..\' and must end with .png/.jpg/.jpeg/.gif/.webp/.svg/.ico.\"\n },\n \"runtime\": {\n \"type\": \"string\",\n \"enum\": [\"native\", \"workerd\"],\n \"default\": \"native\"\n },\n \"command\": { \"type\": \"string\", \"minLength\": 1 },\n \"args\": {\n \"type\": \"array\",\n \"items\": { \"type\": \"string\" }\n },\n \"entrypoints\": {\n \"type\": \"array\",\n \"description\": \"Named capabilities this plugin exports from PluginWorker.open.\",\n \"items\": {\n \"type\": \"string\",\n \"enum\": [\"storefront\", \"storage\", \"databaseAdapter\", \"remoteLibrary\", \"cli\", \"oidc\", \"metadata\", \"covers\", \"metadataFiles\", \"notifier\", \"ingress\", \"ai\"]\n }\n },\n \"media\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"description\": \"Work kinds and edition carriers the plugin works with. Required, with non-empty works and lists, for a plugin exporting the storefront or metadata entrypoint; forbidden for every other plugin. describe() must declare the same kinds.\",\n \"properties\": {\n \"works\": {\n \"type\": \"array\",\n \"description\": \"Work kinds the plugin reports.\",\n \"items\": { \"type\": \"string\", \"enum\": [\"book\", \"podcast\"] }\n },\n \"lists\": {\n \"type\": \"array\",\n \"description\": \"Edition carriers the plugin reports in scans, catalog search and metadata records.\",\n \"items\": { \"type\": \"string\", \"enum\": [\"audio\", \"ebook\", \"print\"] }\n },\n \"fetches\": {\n \"type\": \"array\",\n \"description\": \"Edition carriers fetchTitle can deliver; a subset of lists. Storefronts only.\",\n \"items\": { \"type\": \"string\", \"enum\": [\"audio\", \"ebook\", \"print\"] }\n }\n }\n },\n \"metadata_files\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"required\": [\"dialects\"],\n \"description\": \"Metadata file dialects (sidecars such as metadata.json, OPF, NFO, CUE) the plugin reads and writes. Required, with at least one dialect, for a plugin exporting the metadataFiles entrypoint; forbidden for every other plugin.\",\n \"properties\": {\n \"dialects\": {\n \"type\": \"array\",\n \"minItems\": 1,\n \"items\": { \"$ref\": \"#/$defs/MetadataFileDialect\" }\n }\n }\n },\n \"notifier\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"required\": [\"destinations\"],\n \"description\": \"What a notifier sends to and in which formats. Required for a plugin exporting the notifier entrypoint; forbidden for every other plugin.\",\n \"properties\": {\n \"destinations\": {\n \"type\": \"array\",\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"description\": \"Destination kinds: channel (one shared target the operator sets up) and personal (a patron\'s own address).\",\n \"items\": { \"type\": \"string\", \"enum\": [\"channel\", \"personal\"] }\n },\n \"account_mail\": {\n \"type\": \"boolean\",\n \"description\": \"Whether the plugin can carry account mail (invites, password resets, recovery). Needs a required, non-secret email address field. Defaults to false.\"\n },\n \"formats\": {\n \"type\": \"array\",\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"contains\": { \"const\": \"text\" },\n \"description\": \"Body formats the service shows; must include text. Defaults to [\\\"text\\\"].\",\n \"items\": { \"type\": \"string\", \"enum\": [\"text\", \"markdown\", \"html\"] }\n },\n \"address_fields\": {\n \"type\": \"array\",\n \"maxItems\": 16,\n \"description\": \"Fields of a personal address; required exactly when destinations names personal, with at least one required field.\",\n \"items\": { \"$ref\": \"#/$defs/NotifierAddressField\" }\n }\n }\n },\n \"notifications\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"description\": \"Notification types the plugin raises through env.NOTIFY. Declaring any grants the NOTIFY binding.\",\n \"properties\": {\n \"types\": {\n \"type\": \"array\",\n \"maxItems\": 64,\n \"items\": { \"$ref\": \"#/$defs/NotificationType\" }\n }\n }\n },\n \"ingress\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"required\": [\"kind\"],\n \"description\": \"How an ingress plugin serves the library publicly. Required for a plugin exporting the ingress entrypoint; forbidden for every other plugin.\",\n \"properties\": {\n \"kind\": {\n \"type\": \"string\",\n \"enum\": [\"relay\", \"direct\"],\n \"description\": \"relay: the provider relays each request to the plugin, which hands it to the library through ORIGIN. direct: the public address points at the daemon; the plugin only keeps it current.\"\n }\n }\n },\n \"ai\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"description\": \"Model tasks the plugin serves on its ai entrypoint and the tasks it calls through env.AI.\",\n \"properties\": {\n \"serves\": {\n \"type\": \"array\",\n \"uniqueItems\": true,\n \"description\": \"Tasks the plugin\'s models perform. Required, with at least one task, for a plugin exporting the ai entrypoint; forbidden for every other plugin.\",\n \"items\": { \"$ref\": \"#/$defs/AiTask\" }\n },\n \"calls\": {\n \"type\": \"array\",\n \"uniqueItems\": true,\n \"description\": \"Tasks the plugin runs through env.AI. Declaring any asks the operator for the AI binding.\",\n \"items\": { \"$ref\": \"#/$defs/AiTask\" }\n }\n }\n },\n \"workerd\": { \"$ref\": \"#/$defs/WorkerdRuntime\" },\n \"modules\": {\n \"type\": \"array\",\n \"items\": { \"$ref\": \"#/$defs/ModuleSpec\" }\n },\n \"triggers\": { \"$ref\": \"#/$defs/Triggers\" },\n \"events\": { \"$ref\": \"#/$defs/Events\" },\n \"databases\": {\n \"type\": \"array\",\n \"description\": \"Named plugin-owned database bindings (Workers-style).\",\n \"maxItems\": 8,\n \"items\": { \"$ref\": \"#/$defs/DatabaseBinding\" }\n },\n \"vars\": {\n \"type\": \"object\",\n \"description\": \"Operator config binding (`CONFIG`). Declares that the guest receives CONFIG; values come from [[settings]] defaults and the plugin instance document. An empty table is the usual form.\"\n },\n \"settings\": {\n \"type\": \"array\",\n \"description\": \"Operator settings schema ([[settings]]): keys an instance document may set, their types, enum values, and defaults. The host validates documents against it and renders it in Settings. Non-secret entries require [vars]; type = \\\"secret\\\" entries require [secrets].\",\n \"maxItems\": 32,\n \"items\": { \"$ref\": \"#/$defs/SettingSpec\" }\n },\n \"secrets\": { \"$ref\": \"#/$defs/NamedBinding\" },\n \"kv_namespaces\": {\n \"type\": \"array\",\n \"description\": \"Durable KV bindings (default name KV) served from the library database: Workers KVNamespace-shaped get/put/delete/list with expiration and metadata, scoped to the plugin and the row\'s namespace. Distinct from [[databases]].\",\n \"items\": { \"$ref\": \"#/$defs/KvNamespace\" }\n },\n \"queues\": { \"$ref\": \"#/$defs/Queues\" },\n \"work_fs\": { \"$ref\": \"#/$defs/NamedBinding\" },\n \"oauth\": { \"$ref\": \"#/$defs/NamedBinding\" },\n \"capabilities\": { \"$ref\": \"#/$defs/Capabilities\" },\n \"cli\": { \"$ref\": \"#/$defs/CliSchema\" },\n \"oidc\": { \"$ref\": \"#/$defs/OidcManifest\" }\n },\n \"allOf\": [\n {\n \"if\": {\n \"properties\": { \"runtime\": { \"const\": \"workerd\" } },\n \"required\": [\"runtime\"]\n },\n \"then\": { \"required\": [\"workerd\"] }\n },\n {\n \"if\": {\n \"anyOf\": [\n { \"properties\": { \"runtime\": { \"const\": \"native\" } } },\n { \"not\": { \"required\": [\"runtime\"] } }\n ]\n },\n \"then\": {\n \"required\": [\"command\"],\n \"properties\": {\n \"capabilities\": {\n \"properties\": {\n \"network\": {\n \"properties\": {\n \"domains\": false\n }\n }\n }\n }\n }\n }\n },\n {\n \"if\": {\n \"properties\": {\n \"runtime\": { \"const\": \"workerd\" },\n \"capabilities\": {\n \"properties\": {\n \"network\": {\n \"properties\": { \"mode\": { \"const\": \"outbound\" } },\n \"required\": [\"mode\"]\n }\n },\n \"required\": [\"network\"]\n }\n },\n \"required\": [\"runtime\", \"capabilities\"]\n },\n \"then\": {\n \"properties\": {\n \"capabilities\": {\n \"properties\": {\n \"network\": {\n \"required\": [\"domains\"],\n \"properties\": {\n \"domains\": {\n \"type\": \"array\",\n \"minItems\": 1,\n \"items\": { \"type\": \"string\", \"minLength\": 1 }\n }\n }\n }\n }\n }\n }\n }\n },\n {\n \"if\": {\n \"properties\": {\n \"entrypoints\": {\n \"anyOf\": [{ \"contains\": { \"const\": \"storefront\" } }, { \"contains\": { \"const\": \"metadata\" } }]\n }\n },\n \"required\": [\"entrypoints\"]\n },\n \"then\": {\n \"required\": [\"media\"],\n \"properties\": {\n \"media\": {\n \"required\": [\"works\", \"lists\"],\n \"properties\": { \"works\": { \"minItems\": 1 }, \"lists\": { \"minItems\": 1 } }\n }\n }\n },\n \"else\": { \"properties\": { \"media\": false } }\n },\n {\n \"if\": {\n \"properties\": { \"entrypoints\": { \"contains\": { \"const\": \"metadataFiles\" } } },\n \"required\": [\"entrypoints\"]\n },\n \"then\": { \"required\": [\"metadata_files\"] },\n \"else\": { \"properties\": { \"metadata_files\": false } }\n },\n {\n \"if\": {\n \"properties\": { \"entrypoints\": { \"contains\": { \"const\": \"notifier\" } } },\n \"required\": [\"entrypoints\"]\n },\n \"then\": { \"required\": [\"notifier\"] },\n \"else\": { \"properties\": { \"notifier\": false } }\n },\n {\n \"if\": {\n \"properties\": { \"entrypoints\": { \"contains\": { \"const\": \"ingress\" } } },\n \"required\": [\"entrypoints\"]\n },\n \"then\": { \"required\": [\"ingress\"] },\n \"else\": { \"properties\": { \"ingress\": false } }\n },\n {\n \"if\": {\n \"properties\": { \"entrypoints\": { \"contains\": { \"const\": \"ai\" } } },\n \"required\": [\"entrypoints\"]\n },\n \"then\": {\n \"required\": [\"ai\"],\n \"properties\": { \"ai\": { \"required\": [\"serves\"], \"properties\": { \"serves\": { \"minItems\": 1 } } } }\n },\n \"else\": { \"properties\": { \"ai\": { \"properties\": { \"serves\": { \"maxItems\": 0 } } } } }\n }\n ],\n \"$defs\": {\n \"AiTask\": {\n \"type\": \"string\",\n \"enum\": [\"textEmbeddings\"],\n \"description\": \"What a model does: textEmbeddings turns each text into one vector.\"\n },\n \"NotifierAddressField\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"required\": [\"key\", \"label\"],\n \"description\": \"One field of a patron\'s personal address, such as an email address or a chat id.\",\n \"properties\": {\n \"key\": {\n \"type\": \"string\",\n \"pattern\": \"^[a-z][a-z0-9_]{0,63}$\",\n \"description\": \"Key in the address document; unique within the plugin.\"\n },\n \"label\": { \"type\": \"string\", \"minLength\": 1, \"description\": \"Label shown to the patron.\" },\n \"required\": { \"type\": \"boolean\", \"description\": \"Whether the patron must fill it in. Defaults to false.\" },\n \"secret\": {\n \"type\": \"boolean\",\n \"description\": \"Whether the value is a secret (a personal token): sealed at rest and never shown again. Defaults to false.\"\n }\n }\n },\n \"NotificationType\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"required\": [\"id\", \"audience\", \"severity\", \"title\"],\n \"description\": \"One notification type the plugin raises; the host names it <plugin>:<id>.\",\n \"properties\": {\n \"id\": {\n \"type\": \"string\",\n \"pattern\": \"^[a-z][a-z0-9_]{0,63}$\",\n \"description\": \"Type id, unique within the plugin.\"\n },\n \"audience\": {\n \"type\": \"string\",\n \"enum\": [\"operational\", \"patron\"],\n \"description\": \"operational goes to administrators\' channels; patron goes to the one patron a raise names. account is reserved to Bookclerk.\"\n },\n \"severity\": { \"type\": \"string\", \"enum\": [\"info\", \"warning\", \"critical\"] },\n \"title\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"maxLength\": 256,\n \"description\": \"One-line name shown in notification settings.\"\n }\n }\n },\n \"MetadataFileDialect\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"required\": [\"id\", \"name\", \"fields\"],\n \"anyOf\": [\n { \"required\": [\"file_names\"], \"properties\": { \"file_names\": { \"minItems\": 1 } } },\n { \"required\": [\"suffixes\"], \"properties\": { \"suffixes\": { \"minItems\": 1 } } }\n ],\n \"if\": { \"required\": [\"fields\"], \"properties\": { \"fields\": { \"contains\": { \"const\": \"credits\" } } } },\n \"then\": { \"required\": [\"credit_roles\"], \"properties\": { \"credit_roles\": { \"minItems\": 1 } } },\n \"else\": { \"properties\": { \"credit_roles\": { \"maxItems\": 0 } } },\n \"description\": \"One metadata file format. The host routes a file by exact name first, then by the longest matching suffix, both compared without ASCII case.\",\n \"properties\": {\n \"id\": {\n \"type\": \"string\",\n \"pattern\": \"^[a-z][a-z0-9_]{0,63}$\",\n \"description\": \"Dialect id, unique within the plugin; passed back in parse and render.\"\n },\n \"name\": { \"type\": \"string\", \"minLength\": 1, \"description\": \"Name shown in settings and on a book\'s files list.\" },\n \"file_names\": {\n \"type\": \"array\",\n \"description\": \"Exact file names the dialect reads (metadata.json).\",\n \"items\": { \"type\": \"string\", \"minLength\": 1 }\n },\n \"suffixes\": {\n \"type\": \"array\",\n \"description\": \"File name endings the dialect reads (.opf, .metadata.json); each starts with a dot.\",\n \"items\": { \"type\": \"string\", \"pattern\": \"^\\\\..+\" }\n },\n \"fields\": {\n \"type\": \"array\",\n \"minItems\": 1,\n \"description\": \"Fields the format carries.\",\n \"items\": { \"type\": \"string\", \"enum\": [\"title\", \"subtitle\", \"description\", \"publisher\", \"publishedAt\", \"language\", \"genres\", \"tags\", \"abridgement\", \"expressionKind\", \"identifiers\", \"credits\", \"series\", \"chapters\", \"duration\"] }\n },\n \"credit_roles\": {\n \"type\": \"array\",\n \"description\": \"Credit roles the format carries; required exactly when fields names credits.\",\n \"items\": { \"type\": \"string\", \"enum\": [\"author\", \"narrator\", \"translator\", \"editor\", \"illustrator\", \"publisher\", \"host\", \"cast\", \"adaptor\"] }\n },\n \"writes\": { \"type\": \"boolean\", \"description\": \"Whether the dialect also writes files (render). Defaults to false.\" }\n }\n },\n \"Capabilities\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"required\": [\"network\"],\n \"properties\": {\n \"network\": { \"$ref\": \"#/$defs/NetworkCapabilities\" }\n }\n },\n \"NetworkCapabilities\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"required\": [\"mode\"],\n \"properties\": {\n \"mode\": { \"type\": \"string\", \"enum\": [\"deny\", \"outbound\"] },\n \"domains\": {\n \"type\": \"array\",\n \"description\": \"Workerd-only: initial-request host allowlist for isolate egress. Forbidden on runtime=native. The operator may add destinations beyond this list; the guest cannot.\",\n \"items\": { \"type\": \"string\", \"minLength\": 1 }\n },\n \"tcp\": {\n \"type\": \"array\",\n \"description\": \"Raw TCP connect grants (host + ports). Fetch domain grants do not imply TCP.\",\n \"items\": { \"$ref\": \"#/$defs/TcpCapability\" }\n },\n \"allow_undeclared_public_redirects\": {\n \"type\": \"boolean\",\n \"description\": \"When true, fetch redirects may target undeclared public hosts. Address-space policy still applies.\"\n },\n \"address_cidrs\": {\n \"type\": \"array\",\n \"description\": \"Explicit CIDR grants beyond the public Internet. No blanket private=true.\",\n \"items\": { \"type\": \"string\", \"minLength\": 1 }\n },\n \"own_user_agent\": { \"$ref\": \"#/$defs/OwnUserAgent\" }\n },\n \"if\": { \"properties\": { \"mode\": { \"const\": \"deny\" } } },\n \"then\": { \"not\": { \"required\": [\"own_user_agent\"] } }\n },\n \"OwnUserAgent\": {\n \"type\": \"object\",\n \"description\": \"Hosts that receive the plugin\'s own User-Agent instead of the host\'s bookclerk/<version> agent. Shown on the consent form; the operator may refuse.\",\n \"additionalProperties\": false,\n \"required\": [\"hosts\", \"reason\"],\n \"properties\": {\n \"hosts\": {\n \"type\": \"array\",\n \"description\": \"Exact hosts or *. wildcards (never *).\",\n \"minItems\": 1,\n \"maxItems\": 32,\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"pattern\": \"^(\\\\*\\\\.)?[^*\\\\s,/:%@?#\\\\\\\\]+$\"\n }\n },\n \"reason\": {\n \"type\": \"string\",\n \"description\": \"One line for the operator on why these hosts need the plugin\'s own agent, such as the app API contract it follows.\",\n \"minLength\": 1,\n \"maxLength\": 300,\n \"pattern\": \"^[^\\\\r\\\\n]+$\"\n }\n }\n },\n \"TcpCapability\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"required\": [\"host\", \"ports\"],\n \"properties\": {\n \"host\": { \"type\": \"string\", \"minLength\": 1 },\n \"ports\": {\n \"type\": \"array\",\n \"items\": { \"type\": \"integer\", \"minimum\": 1, \"maximum\": 65535 },\n \"minItems\": 1\n }\n }\n },\n \"Triggers\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"properties\": {\n \"crons\": {\n \"type\": \"array\",\n \"description\": \"Five-field UTC cron schedules (minute hour day-of-month month day-of-week) for the default entrypoint\'s scheduled(controller) handler, as in Workers. Values, ranges, lists, */step and JAN-DEC / SUN-SAT names; no L, W, # or @macros. At most 8, no duplicates.\",\n \"maxItems\": 8,\n \"uniqueItems\": true,\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 9,\n \"maxLength\": 128,\n \"pattern\": \"^\\\\s*\\\\S+(\\\\s+\\\\S+){4}\\\\s*$\"\n }\n },\n \"jobs\": {\n \"type\": \"array\",\n \"items\": { \"type\": \"string\", \"minLength\": 1 }\n }\n }\n },\n \"Events\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"properties\": {\n \"consumers\": {\n \"type\": \"array\",\n \"items\": { \"$ref\": \"#/$defs/EventConsumer\" }\n },\n \"producers\": {\n \"type\": \"array\",\n \"items\": { \"$ref\": \"#/$defs/EventProducer\" }\n }\n }\n },\n \"EventConsumer\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"required\": [\"type\"],\n \"properties\": {\n \"type\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"pattern\": \"^[a-z][a-z0-9_]*$\"\n },\n \"schema_versions\": {\n \"type\": \"array\",\n \"items\": { \"type\": \"integer\", \"minimum\": 1 },\n \"minItems\": 1\n },\n \"supports_suspend\": { \"type\": \"boolean\", \"default\": false },\n \"resource_class\": { \"type\": \"string\", \"enum\": [\"network\"], \"default\": \"network\" },\n \"filter\": { \"type\": \"object\" },\n \"max_retries\": { \"type\": \"integer\", \"minimum\": 0 },\n \"message_retention_period\": { \"type\": \"integer\", \"minimum\": 60, \"maximum\": 1209600 }\n }\n },\n \"EventProducer\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"required\": [\"type\"],\n \"properties\": {\n \"type\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"pattern\": \"^[a-z][a-z0-9_]*$\"\n },\n \"binding\": { \"type\": \"string\", \"minLength\": 1 }\n }\n },\n \"Queues\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"description\": \"Workers Queues: producers are `env` send bindings, consumers are `queue(batch)` triggers. Queue names are `[a-z0-9][a-z0-9._-]*` (at most 63 chars); the `core.` and `host.` prefixes are reserved for the host.\",\n \"properties\": {\n \"producers\": { \"type\": \"array\", \"items\": { \"$ref\": \"#/$defs/QueueProducer\" } },\n \"consumers\": { \"type\": \"array\", \"items\": { \"$ref\": \"#/$defs/QueueConsumer\" } }\n }\n },\n \"QueueProducer\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"required\": [\"queue\", \"binding\"],\n \"properties\": {\n \"queue\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"maxLength\": 63,\n \"pattern\": \"^[a-z0-9][a-z0-9._-]*$\"\n },\n \"binding\": { \"type\": \"string\", \"minLength\": 1, \"pattern\": \"^[A-Z][A-Z0-9_]*$\" }\n }\n },\n \"QueueConsumer\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"required\": [\"queue\"],\n \"properties\": {\n \"queue\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"maxLength\": 63,\n \"pattern\": \"^[a-z0-9][a-z0-9._-]*$\"\n },\n \"max_batch_size\": { \"type\": \"integer\", \"minimum\": 1, \"maximum\": 100, \"default\": 10 },\n \"max_batch_timeout\": { \"type\": \"integer\", \"minimum\": 0, \"maximum\": 60, \"default\": 5 },\n \"max_retries\": { \"type\": \"integer\", \"minimum\": 0, \"maximum\": 100, \"default\": 3 },\n \"dead_letter_queue\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"maxLength\": 63,\n \"pattern\": \"^[a-z0-9][a-z0-9._-]*$\"\n },\n \"retry_delay\": { \"type\": \"integer\", \"minimum\": 0, \"maximum\": 43200, \"default\": 0 },\n \"max_concurrency\": { \"type\": \"integer\", \"minimum\": 1 },\n \"message_retention_period\": { \"type\": \"integer\", \"minimum\": 60, \"maximum\": 1209600 }\n }\n },\n \"SettingSpec\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"required\": [\"key\", \"type\"],\n \"properties\": {\n \"key\": {\n \"type\": \"string\",\n \"pattern\": \"^[a-z][a-z0-9_]{0,63}$\",\n \"description\": \"Setting key, unique within the plugin; the CONFIG / SECRETS property name.\"\n },\n \"label\": { \"type\": \"string\", \"description\": \"Operator-facing label; defaults to the key.\" },\n \"type\": {\n \"type\": \"string\",\n \"enum\": [\"string\", \"bool\", \"integer\", \"enum\", \"secret\"],\n \"description\": \"Value type. `secret` values are sealed by the host and delivered in SECRETS, never stored in the instance document.\"\n },\n \"values\": {\n \"type\": \"array\",\n \"maxItems\": 64,\n \"description\": \"Allowed values for type = \\\"enum\\\"; forbidden otherwise.\",\n \"items\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"required\": [\"id\"],\n \"properties\": {\n \"id\": { \"type\": \"string\", \"minLength\": 1, \"maxLength\": 1024 },\n \"label\": { \"type\": \"string\" }\n }\n }\n },\n \"default\": {\n \"type\": [\"string\", \"boolean\", \"integer\"],\n \"description\": \"Default applied when the instance document omits the key. Not allowed for secrets.\"\n },\n \"required\": { \"type\": \"boolean\", \"default\": false },\n \"description\": { \"type\": \"string\" }\n }\n },\n \"DatabaseBinding\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"required\": [\"binding\"],\n \"properties\": {\n \"binding\": {\n \"type\": \"string\",\n \"pattern\": \"^[A-Z][A-Z0-9_]*$\",\n \"maxLength\": 32\n }\n }\n },\n \"NamedBinding\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"properties\": {\n \"binding\": { \"type\": \"string\", \"minLength\": 1 }\n }\n },\n \"KvNamespace\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"properties\": {\n \"binding\": { \"type\": \"string\", \"minLength\": 1 },\n \"namespace\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"maxLength\": 63,\n \"pattern\": \"^[a-z0-9][a-z0-9._-]*$\"\n },\n \"max_value_bytes\": { \"type\": \"integer\", \"minimum\": 1, \"maximum\": 1048576, \"default\": 65536 },\n \"max_keys\": { \"type\": \"integer\", \"minimum\": 1, \"maximum\": 1000000, \"default\": 10000 }\n }\n },\n \"WorkerdRuntime\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"required\": [\"compatibility_date\", \"main_module\"],\n \"properties\": {\n \"compatibility_date\": {\n \"type\": \"string\",\n \"minLength\": 10,\n \"maxLength\": 10,\n \"pattern\": \"^[0-9]{4}-[0-9]{2}-[0-9]{2}$\",\n \"description\": \"Calendar YYYY-MM-DD. A date newer than the pinned workerd compatibility date 2026-11-13 warns and falls back to that pin when the isolate loads. The pattern checks shape only; checkers reject impossible days such as 2026-02-31.\"\n },\n \"compatibility_flags\": {\n \"type\": \"array\",\n \"description\": \"Exact allowlist: python_workers and disable_python_external_sdk. Both are required together when the guest is Python and forbidden otherwise. The host does not append missing flags.\",\n \"items\": {\n \"type\": \"string\",\n \"enum\": [\"python_workers\", \"disable_python_external_sdk\"]\n }\n },\n \"main_module\": { \"type\": \"string\", \"minLength\": 1 },\n \"modules_dir\": { \"type\": \"string\", \"default\": \"modules\" },\n \"entrypoint\": { \"type\": \"string\", \"default\": \"default\" },\n \"limits\": { \"$ref\": \"#/$defs/WorkerdLimits\" }\n }\n },\n \"WorkerdLimits\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"properties\": {\n \"cpu_ms\": { \"type\": \"integer\", \"minimum\": 0 },\n \"subrequests\": { \"type\": \"integer\", \"minimum\": 0 }\n }\n },\n \"ModuleSpec\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"required\": [\"name\"],\n \"properties\": {\n \"name\": { \"type\": \"string\" },\n \"path\": {\n \"type\": \"string\",\n \"description\": \"Source file relative to the plugin root. When path is omitted or empty, name is the modules-directory source.\"\n },\n \"type\": { \"type\": \"string\", \"default\": \"js\" }\n }\n },\n \"CliSchema\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"properties\": {\n \"commands\": {\n \"type\": \"array\",\n \"items\": { \"$ref\": \"#/$defs/CliCommandSpec\" }\n }\n }\n },\n \"CliCommandSpec\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"required\": [\"name\"],\n \"properties\": {\n \"name\": { \"type\": \"string\" },\n \"about\": { \"type\": \"string\" },\n \"args\": {\n \"type\": \"array\",\n \"items\": { \"$ref\": \"#/$defs/CliArgSpec\" }\n }\n }\n },\n \"CliArgSpec\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"required\": [\"name\"],\n \"properties\": {\n \"name\": { \"type\": \"string\" },\n \"long\": { \"type\": \"string\" },\n \"short\": { \"type\": \"string\", \"maxLength\": 1 },\n \"kind\": {\n \"type\": \"string\",\n \"enum\": [\"string\", \"bool\", \"int\", \"path\"],\n \"default\": \"string\"\n },\n \"required\": { \"type\": \"boolean\" },\n \"default\": { \"type\": \"string\" },\n \"about\": { \"type\": \"string\" },\n \"positional\": { \"type\": \"boolean\" }\n }\n },\n \"OidcManifest\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"properties\": {\n \"clients\": {\n \"type\": \"array\",\n \"items\": { \"$ref\": \"#/$defs/OidcClient\" }\n }\n }\n },\n \"OidcClient\": {\n \"type\": \"object\",\n \"additionalProperties\": false,\n \"required\": [\"client_id\", \"callback_path\", \"origin_config_key\"],\n \"properties\": {\n \"client_id\": { \"type\": \"string\", \"minLength\": 1 },\n \"display_name\": { \"type\": \"string\" },\n \"callback_path\": { \"type\": \"string\", \"pattern\": \"^/\" },\n \"public_client\": { \"type\": \"boolean\", \"default\": true },\n \"default_scopes\": {\n \"type\": \"array\",\n \"items\": { \"type\": \"string\" }\n },\n \"issue_refresh_token\": { \"type\": \"boolean\", \"default\": true },\n \"origin_config_key\": { \"type\": \"string\", \"minLength\": 1 }\n }\n }\n }\n}\n";
Embedded JSON Schema text for authoring tools (check in TS/Python SDKs).
Identical on disk to schema/plugin-toml.json. Prefer this constant over
reading the file when packaging tools as a single crate artifact.
Generated from crates/bookclerk-plugin-manifest at main · View as Markdown