bookclerk_plugin_abi::settings_schema
Operator-facing plugin settings schema ([[settings]] in plugin.toml).
A plugin declares the keys an operator may set on one of its instances,
their types, and their defaults. The host validates instance documents
against this schema and renders it in Settings; it hard-codes nothing per
plugin. The same struct is the plugin.toml TOML shape and the JSON body
pinned in the library database at enrollment.
| Item | Kind | Summary |
|---|---|---|
SettingValueSpec |
struct | One selectable value of an SettingKind::Enum setting. |
SettingSpec |
struct | One [[settings]] entry. |
SettingsSchema |
struct | The ordered [[settings]] list of one plugin. |
EffectiveConfig |
struct | Result of SettingsSchema::effective_config. |
SettingKind |
enum | Value type of one setting. |
SettingNetwork |
enum | How a string setting's value names a network destination (network in [[settings]]). |
is_valid_setting_key |
function | Grammar for setting keys and secret names: ^a-z{0,63}$. |
SETTINGS_SCHEMA_VERSION |
constant | Schema revision of SettingsSchema as pinned in the database. |
MAX_SETTINGS |
constant | Maximum [[settings]] entries one manifest may declare. |
MAX_SETTING_VALUES |
constant | Maximum enum values one setting may declare. |
MAX_SETTING_STRING_BYTES |
constant | Maximum UTF-8 size of one string setting value. |
MAX_TABLE_COLUMNS |
constant | Maximum columns one SettingKind::Table setting may declare. |
MAX_TABLE_ROWS |
constant | Maximum rows one SettingKind::Table value may hold. |
pub struct SettingValueSpec {
pub id: String,
pub label: String,
}
One selectable value of an SettingKind::Enum setting.
Fields
id: Stored value.label: Operator-facing label; defaults toid.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct SettingSpec {
pub key: String,
pub label: String,
pub kind: SettingKind,
pub values: Vec<SettingValueSpec>,
pub default: Option<Value>,
pub required: bool,
pub description: Option<String>,
pub columns: Vec<SettingSpec>,
pub network: Option<SettingNetwork>,
pub default_port: Option<u16>,
}
One [[settings]] entry.
Fields
key: Setting key (^[a-z][a-z0-9_]{0,63}$), unique within the plugin.label: Operator-facing label; defaults tokey.kind: Value type.values: Allowed values forSettingKind::Enum; empty otherwise.default: Default applied when the instance document omits the key. Not allowed for secrets.required: When true, a spawn without a value (document or default) fails.description: Optional help text.columns: Columns of aSettingKind::Tablesetting, in display order; empty otherwise. Each column is a scalar entry: itskeynames the record field,requiredmeans every row must have a value (from the row or the columndefault), and it declares no columns of its own.network: Whether the value names a network destination the plugin may reach once the operator approves it. Only a top-levelSettingKind::Stringsetting may declare it.default_port: Port used when aSelf::networkvalue names none: required for a baretcphost, and replaces 443 for a barefetchhost. Allowed only withnetwork; 1-65535.
pub fn label_or_key(&self) -> &str
Label for UI, falling back to the key.
pub fn is_secret(&self) -> bool
True for SettingKind::Secret.
pub fn check_value(&self, value: &Value) -> Result<(), String>
Checks value against this entry's kind.
Returns a message naming the key when the value does not fit.
pub fn column(&self, key: &str) -> Option<&SettingSpec>
Column entry for key of a table setting.
pub fn normalize_value(&self, value: &Value) -> Value
A stored value brought to the current declaration: for a table, row fields of columns no longer declared are dropped and missing columns with a default are filled; other kinds come back unchanged.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct SettingsSchema {
pub settings: Vec<SettingSpec>,
}
The ordered [[settings]] list of one plugin.
Fields
settings: Entries in declaration order.
pub fn new(settings: Vec<SettingSpec>) -> Self
Wraps a declared list without validating it.
pub fn validate(&self, config_binding: bool, secrets_binding: bool) -> Result<(), String>
Validates the declaration itself.
config_binding / secrets_binding say whether the manifest declares
[vars] / [secrets]; non-secret entries need the former and secret
entries the latter, because that is how values reach the guest.
Returns a message describing the first failed rule.
pub fn get(&self, key: &str) -> Option<&SettingSpec>
Entry for key.
pub fn is_empty(&self) -> bool
True when no entries are declared.
pub fn config_entries(&self) -> impl Iterator<Item = &SettingSpec>
Non-secret entries, in order.
pub fn secret_entries(&self) -> impl Iterator<Item = &SettingSpec>
Secret entries, in order.
pub fn defaults(&self) -> BTreeMap<String, Value>
Defaults for non-secret entries that declare one.
pub fn config_options(&self) -> Vec<ConfigOption>
describe().configOptions projection: every non-secret entry, with
enum values listed and other kinds as free-form.
pub fn check_setting(&self, key: &str, value: &Value) -> Result<(), String>
Checks one document setting against the schema.
Unknown keys, secrets given as plain values, and type mismatches are rejected with a message naming the key.
pub fn check_secret_key(&self, key: &str) -> Result<(), String>
Checks one secret ref key against the schema.
Returns a message when key is not a declared secret.
pub fn required_secret_keys(&self) -> impl Iterator<Item = &str>
Keys of secret entries marked required.
pub fn effective_config(&self, settings: &BTreeMap<String, Value>) -> EffectiveConfig
Merges settings over the schema defaults and reports missing
required keys.
Keys the schema does not declare are dropped and returned in
dropped; declared keys whose value no longer fits the entry's kind
(a type or enum change after an upgrade) are left out of config and
returned in invalid, so the default applies instead. Table rows are
first brought to the current columns with
SettingSpec::normalize_value, so a removed column does not
invalidate them. A required key
with neither a usable value nor a default is missing.
Implements: Clone, Debug, Default, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct EffectiveConfig {
pub config: BTreeMap<String, Value>,
pub dropped: Vec<String>,
pub invalid: Vec<String>,
pub missing: Vec<String>,
}
Result of SettingsSchema::effective_config.
Fields
config: Values delivered asCONFIG.dropped: Document keys the schema does not declare.invalid: Declared keys whose stored value does not fit the entry's kind.missing: Required keys with neither a usable value nor a default.
Implements: Clone, Debug, Default, Eq, PartialEq
pub enum SettingKind {
String,
Bool,
Integer,
Enum,
Secret,
Table,
}
Value type of one setting.
Variants
String: Free-form UTF-8 string (at mostMAX_SETTING_STRING_BYTES).Bool: Boolean.Integer: Signed 64-bit integer.Enum: One of the declaredSettingSpec::valuesids.Secret: Sealed secret: delivered inSECRETS, never stored in a document.Table: Rows of records: a JSON array of objects whose keys are the declaredSettingSpec::columns(at mostMAX_TABLE_ROWSrows). A row may leave out a column that is not required, so adding a column keeps existing rows valid.
pub fn as_str(self) -> &'static str
Wire / UI name (string, bool, integer, enum, secret,
table).
pub fn is_scalar(self) -> bool
True for the kinds a table column may have: string, bool, integer and enum.
Implements: Clone, Copy, Debug, Deserialize<'de>, Eq, Hash, PartialEq, Serialize
pub enum SettingNetwork {
Fetch,
Tcp,
}
How a string setting's value names a network destination
(network in [[settings]]).
A setting that declares one may widen the plugin's network grant: the host derives the destination from the value an operator saves and lists it on the consent form, and the plugin reaches it only once it is approved.
Variants
Fetch: An HTTP(S) URL the plugin fetches (https://abs.home.lan:13378). A barehost[:port]meanshttps://. Grants a fetch to that host and port.Tcp: Ahost:portthe plugin opens a raw TCP socket to (db.home.lan:5432); a bare host takesSettingSpec::default_port. Grants TCP to that host and port.
pub fn as_str(self) -> &'static str
Wire / manifest name (fetch, tcp).
Implements: Clone, Copy, Debug, Deserialize<'de>, Eq, Hash, Ord, PartialEq, PartialOrd, Serialize
pub fn is_valid_setting_key(key: &str) -> bool
Grammar for setting keys and secret names: ^[a-z][a-z0-9_]{0,63}$.
pub const SETTINGS_SCHEMA_VERSION: u32 = 1;
Schema revision of SettingsSchema as pinned in the database.
pub const MAX_SETTINGS: usize = 32;
Maximum [[settings]] entries one manifest may declare.
pub const MAX_SETTING_VALUES: usize = 64;
Maximum enum values one setting may declare.
pub const MAX_SETTING_STRING_BYTES: usize = 1024;
Maximum UTF-8 size of one string setting value.
pub const MAX_TABLE_COLUMNS: usize = 16;
Maximum columns one SettingKind::Table setting may declare.
pub const MAX_TABLE_ROWS: usize = 64;
Maximum rows one SettingKind::Table value may hold.
Generated from crates/bookclerk-plugin-abi at main · View as Markdown