bookclerk_plugin_abi::settings_schema

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

Last updated View as Markdown

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.

Structs

SettingValueSpec

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 to id.

Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize

SettingSpec

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 to key.
  • kind: Value type.
  • values: Allowed values for SettingKind::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 a SettingKind::Table setting, in display order; empty otherwise. Each column is a scalar entry: its key names the record field, required means every row must have a value (from the row or the column default), 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-level SettingKind::String setting may declare it.
  • default_port: Port used when a Self::network value names none: required for a bare tcp host, and replaces 443 for a bare fetch host. Allowed only with network; 1-65535.

SettingSpec::label_or_key

pub fn label_or_key(&self) -> &str

Label for UI, falling back to the key.

SettingSpec::is_secret

pub fn is_secret(&self) -> bool

True for SettingKind::Secret.

SettingSpec::check_value

pub fn check_value(&self, value: &Value) -> Result<(), String>

Checks value against this entry's kind.

Errors

Returns a message naming the key when the value does not fit.

SettingSpec::column

pub fn column(&self, key: &str) -> Option<&SettingSpec>

Column entry for key of a table setting.

SettingSpec::normalize_value

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

SettingsSchema

pub struct SettingsSchema {
    pub settings: Vec<SettingSpec>,
}

The ordered [[settings]] list of one plugin.

Fields

  • settings: Entries in declaration order.

SettingsSchema::new

pub fn new(settings: Vec<SettingSpec>) -> Self

Wraps a declared list without validating it.

SettingsSchema::validate

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.

Errors

Returns a message describing the first failed rule.

SettingsSchema::get

pub fn get(&self, key: &str) -> Option<&SettingSpec>

Entry for key.

SettingsSchema::is_empty

pub fn is_empty(&self) -> bool

True when no entries are declared.

SettingsSchema::config_entries

pub fn config_entries(&self) -> impl Iterator<Item = &SettingSpec>

Non-secret entries, in order.

SettingsSchema::secret_entries

pub fn secret_entries(&self) -> impl Iterator<Item = &SettingSpec>

Secret entries, in order.

SettingsSchema::defaults

pub fn defaults(&self) -> BTreeMap<String, Value>

Defaults for non-secret entries that declare one.

SettingsSchema::config_options

pub fn config_options(&self) -> Vec<ConfigOption>

describe().configOptions projection: every non-secret entry, with enum values listed and other kinds as free-form.

SettingsSchema::check_setting

pub fn check_setting(&self, key: &str, value: &Value) -> Result<(), String>

Checks one document setting against the schema.

Errors

Unknown keys, secrets given as plain values, and type mismatches are rejected with a message naming the key.

SettingsSchema::check_secret_key

pub fn check_secret_key(&self, key: &str) -> Result<(), String>

Checks one secret ref key against the schema.

Errors

Returns a message when key is not a declared secret.

SettingsSchema::required_secret_keys

pub fn required_secret_keys(&self) -> impl Iterator<Item = &str>

Keys of secret entries marked required.

SettingsSchema::effective_config

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

EffectiveConfig

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 as CONFIG.
  • 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

Enums

SettingKind

pub enum SettingKind {
    String,
    Bool,
    Integer,
    Enum,
    Secret,
    Table,
}

Value type of one setting.

Variants

  • String: Free-form UTF-8 string (at most MAX_SETTING_STRING_BYTES).
  • Bool: Boolean.
  • Integer: Signed 64-bit integer.
  • Enum: One of the declared SettingSpec::values ids.
  • Secret: Sealed secret: delivered in SECRETS, never stored in a document.
  • Table: Rows of records: a JSON array of objects whose keys are the declared SettingSpec::columns (at most MAX_TABLE_ROWS rows). A row may leave out a column that is not required, so adding a column keeps existing rows valid.

SettingKind::as_str

pub fn as_str(self) -> &'static str

Wire / UI name (string, bool, integer, enum, secret, table).

SettingKind::is_scalar

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

SettingNetwork

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 bare host[:port] means https://. Grants a fetch to that host and port.
  • Tcp: A host:port the plugin opens a raw TCP socket to (db.home.lan:5432); a bare host takes SettingSpec::default_port. Grants TCP to that host and port.

SettingNetwork::as_str

pub fn as_str(self) -> &'static str

Wire / manifest name (fetch, tcp).

Implements: Clone, Copy, Debug, Deserialize<'de>, Eq, Hash, Ord, PartialEq, PartialOrd, Serialize

Functions

is_valid_setting_key

pub fn is_valid_setting_key(key: &str) -> bool

Grammar for setting keys and secret names: ^[a-z][a-z0-9_]{0,63}$.

Constants

SETTINGS_SCHEMA_VERSION

pub const SETTINGS_SCHEMA_VERSION: u32 = 1;

Schema revision of SettingsSchema as pinned in the database.

MAX_SETTINGS

pub const MAX_SETTINGS: usize = 32;

Maximum [[settings]] entries one manifest may declare.

MAX_SETTING_VALUES

pub const MAX_SETTING_VALUES: usize = 64;

Maximum enum values one setting may declare.

MAX_SETTING_STRING_BYTES

pub const MAX_SETTING_STRING_BYTES: usize = 1024;

Maximum UTF-8 size of one string setting value.

MAX_TABLE_COLUMNS

pub const MAX_TABLE_COLUMNS: usize = 16;

Maximum columns one SettingKind::Table setting may declare.

MAX_TABLE_ROWS

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