Configuration - SeleniumBase for Rust

A program turns a plugin on by name, with options from the settings file or the command line, through four items of seleniumbase_rs_plugin, defined in crates/seleniumbase-rs-plugin/src/config.rs. A plugin implements Configurable; Descriptor::of describes it; a Registry holds descriptors and builds plugins from PluginSpecs. seleniumbase-rs turns a PluginSelection into specs for you (Selection); how options reach a plugin is in the Options reference.

Configurable#

trait seleniumbase_rs_plugin::Configurable

pub trait Configurable: Plugin + Sized {    const NAME: &'static str;    fn describe() -> Metadata;    fn configure(options: &Value) -> Result<Self>;}

A plugin that can be built from a name and a TOML or JSON options value. It is what Descriptor::of needs, and so what every registry, the settings file, SB_PLUGINS, --plugin and sbrs plugin info need. Its methods are not async.

Configurable::NAME#

const required

const NAME: &'static str;

The name the plugin is enabled by: the key of the registry, of enable and of the options table. Return the same string from Plugin::name; the set detects duplicates and resolves ordering edges by Plugin::name.

Configurable::describe#

fn required

fn describe() -> Metadata;

returnMetadata#

What the plugin declares, without building one. See Metadata.

A Descriptor stores it, so sbrs plugin list, sbrs plugin info and the check of what a project’s settings file may turn on read it. Return it from Plugin::metadata too, adding only what depends on the options (as crx adds the files it reads); the set checks what Plugin::metadata returns.

Configurable::configure#

fn required

fn configure(options: &Value) -> Result<Self>;

options&serde_json::Valuerequired#

The plugin’s options: Value::Null when none were given; otherwise usually a Value::Object, such as the [plugins.NAME] table of the settings file converted to JSON, with each --plugin-opt NAME.KEY=VALUE setting one key.

returnResult<Self>#

The plugin, or PluginError::Config when an option is wrong.

Refuse a key you do not know, so a typo does not turn a setting off without a word. With serde, #[serde(default, deny_unknown_fields)] on an options struct does that.

Descriptor#

struct seleniumbase_rs_plugin::Descriptor

#[derive(Clone, Debug)]pub struct Descriptor { /* private: name, metadata, build */ }

One plugin a registry can build: its name, what it declares, and a function that builds it from options. The only way to make one is Descriptor::of.

Descriptor::of#

#[must_use]pub fn of<P: Configurable>() -> Self

Ptype parameter: Configurablerequired#

The plugin type.

returnDescriptor#

P::NAME, P::describe() (called once, now), and a builder that calls P::configure and puts the plugin in an Arc.

Descriptor::name#

#[must_use]pub fn name(&self) -> &'static str

return&'static str#

P::NAME.

Descriptor::metadata#

#[must_use]pub fn metadata(&self) -> &Metadata

return&Metadata#

What P::describe() returned.

PluginSpec#

struct seleniumbase_rs_plugin::PluginSpec

#[derive(Clone, Debug, PartialEq)]pub struct PluginSpec {    pub name: String,    pub options: Value,}

A plugin to enable: its name and options.

nameStringrequired#

The plugin’s name, as Configurable::NAME spells it.

optionsserde_json::Value#

Its options; Value::Null for none.

Default: "Value::Null"

PluginSpec::new#

#[must_use]pub fn new(name: impl Into<String>) -> Self

nameimpl Into<String>required#

The plugin’s name.

returnPluginSpec#

A spec with no options (Value::Null).

PluginSpec::options#

#[must_use]pub fn options(mut self, options: Value) -> Self

optionsserde_json::Valuerequired#

The options, usually json!(...). They replace earlier ones.

returnPluginSpec#

The spec with these options.

Registry#

struct seleniumbase_rs_plugin::Registry

#[derive(Clone, Debug, Default)]pub struct Registry { /* private: descriptors, in the order added */ }

The plugins a program can enable by name. seleniumbase-rs’s plugin_host::builtin_registry() is the registry of the built-in plugins whose cargo feature is on, in the order shield, block-resources, crx (Host).

Registry::new#

#[must_use]pub fn new() -> Self

returnRegistry#

An empty registry.

Registry::with#

#[must_use]pub fn with(mut self, descriptor: Descriptor) -> Self

descriptorDescriptorrequired#

The plugin to add, usually Descriptor::of::<P>().

returnRegistry#

The registry with the descriptor at the end. One with the same name is removed first, so a later descriptor replaces an earlier one and takes the last place.

Registry::names#

#[must_use]pub fn names(&self) -> Vec<&'static str>

returnVec<&'static str>#

The known names, in the order added.

Registry::get#

#[must_use]pub fn get(&self, name: &str) -> Option<&Descriptor>

name&strrequired#

A plugin name.

returnOption<&Descriptor>#

The descriptor called name, or None.

Registry::build#

pub fn build(&self, spec: &PluginSpec) -> Result<Arc<dyn Plugin>>

spec&PluginSpecrequired#

The name and options.

returnResult<Arc<dyn Plugin>>#

The plugin. PluginError::Config for an unknown name (no plugin named `NAME` (known: a, b)), or whatever configure returns for wrong options.

Registry::plugin_set#

pub fn plugin_set(&self, specs: &[PluginSpec]) -> Result<PluginSet>

specs&[PluginSpec]required#

The plugins to enable, in insertion order.

returnResult<PluginSet>#

A strict set of the plugins the specs name, or the first build or duplicate-name error.

Each plugin is granted the capabilities and optional of its Plugin::metadata, without the Critical ones, so a plugin built from a name never holds raw:*, host.process, cdp:Target or cdp:Browser. A program that uses seleniumbase-rs usually calls plugin_host::build_with instead, which does the same from a PluginSelection and reports a mistake as SeleniumBaseError::Plugin with the plugin’s name.