bookclerk_plugin_manifest

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

Last updated View as Markdown

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.

Audience

  • Host / launcher authors — parse manifests at discovery, build EgressPolicy for isolate injection, map network + OAuth bindings to jail policy via PluginManifest::jail_network_need.
  • Plugin authors / SDK tools — validate and pretty-print plugin.toml without pulling host dependencies.

Modules

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.

Examples

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).

Re-exports

Modules

  • address: Address-space policy independent of hostname matching.
  • cron: Five-field cron schedules for [triggers] crons (Workers scheduled).
  • egress: Shared host/egress allowlist policy (workerd JS bridge + native mediator).
  • error: Manifest parse and semantic-validation errors.
  • fmt: Canonical plugin.toml formatting for SDK fmt / fmt --check.
  • id: Display-alias grammar shared by manifest parse, host registry, and SDKs.
  • logo: Plugin logo validation: remote http(s) URL or relative image path.
  • setting_network: Network destinations named by plugin settings.
  • types: plugin.toml types: 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.

Functions

parse

pub fn parse(text: &str) -> Result<PluginManifest>

Parses and validates a plugin.toml document.

Equivalent to [PluginManifest::parse]: deserializes TOML then runs PluginManifest::validate.

Arguments

  • text - Full contents of a plugin.toml file (UTF-8).

Returns

A validated PluginManifest.

Errors

Returns Error::TomlDe on malformed TOML, or Error::Message when semantic validation fails (id grammar, runtime requirements, network domains, logo, and so on).

Examples

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");

Constants

PLUGIN_TOML_SCHEMA_JSON

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