PluginSet

A PluginSet holds the plugins a program uses, with the capabilities each was granted. It checks them against the browser about to start, orders them, and calls their hooks; seleniumbase-rs calls the set, so a program usually only builds one and hands it to a launch builder (Host). It is seleniumbase_rs_plugin::PluginSet, defined in crates/seleniumbase-rs-plugin/src/lib.rs; the run order comes from order.rs.

PluginSet#

struct seleniumbase_rs_plugin::PluginSet

#[derive(Clone, Default)]pub struct PluginSet { /* private: the plugins with their grants, and strict */ }impl fmt::Debug for PluginSet { /* prints the names in run order and `strict` */ }

The plugins a program uses, in the order their hooks run. An error from before_launch, on_browser or on_page_created stops there and is returned: a plugin that did not run must not leave a browser without what it adds. Cloning a set clones Arcs: the plugins themselves are shared.

PluginSet::new#

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

PluginSet::strict#

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

A strict set accepts an undeclared plugin when you add it, and refuses it at the check with PluginError::Undeclared. The command line, the MCP server, Registry::plugin_set and plugin_host::build_with use strict sets.

PluginSet::with#

pub fn with(self, plugin: impl Plugin) -> Result<Self>

Grants the plugin what it declares, except Critical capabilities:

A plugin that requires a Critical capability therefore fails the check (it is required but not granted) unless it is added with with_trusted or with_grants.

PluginSet::with_shared#

pub fn with_shared(self, plugin: Arc<dyn Plugin>) -> Result<Self>

PluginSet::with_trusted#

pub fn with_trusted(self, plugin: impl Plugin, trusted: &[Capability]) -> Result<Self>

The way to run a plugin that requires raw:cdp, raw:switches, host.process, cdp:Target or cdp:Browser. A set built from names never grants those, so such a plugin is added in code.

PluginSet::with_grants#

pub fn with_grants(self, plugin: impl Plugin, grants: CapabilitySet) -> Result<Self>

The default grants do not apply: a declared plugin gets only grants, and an undeclared one does not get the legacy set unless grants holds it.

PluginSet::with_grants_shared#

pub fn with_grants_shared(self, plugin: Arc<dyn Plugin>, grants: CapabilitySet) -> Result<Self>

PluginSet::is_empty#

#[must_use]pub fn is_empty(&self) -> bool

PluginSet::for_launch#

#[must_use]pub fn for_launch(&self) -> Self

Both engines call it before every launch and every attach, and use the result for every later hook of that browser, so pooled browsers launched from one set do not share a plugin’s state.

PluginSet::names#

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

PluginSet::check#

pub fn check(&self, context: &LaunchContext) -> Result<()>

check_with(context, &HostInfo::cdp()): the check on a host that supports every capability.

PluginSet::check_with#

pub fn check_with(&self, context: &LaunchContext, host: &HostInfo) -> Result<()>

The checks, in this order:

1. The run order resolves: every requires and dependencies name is in the set (MissingDependency), no plugin conflicts with another that is present (Conflict), and the edges have no cycle (Cycle).
2. Then, for each plugin in run order:
   1. a strict set refuses it when it declares no metadata (Undeclared);
   2. its requirements and packages (Requirement, with one of these reasons): it needs a browser with a window, not a headless one (HEADFUL), it only works with a browser the program starts, not one it attaches to (LAUNCH_ONLY), it needs a Chromium-based browser (CHROMIUM_ONLY), one of its packages says neither `only_on` nor `everywhere` ;
   3. each capability in its metadata’s capabilities: the host supports it (Unsupported), and the set granted it (Capability, it is required but not granted). Capabilities in optional are never checked.

The engines call it before before_launch and again after it; an attach is checked once. The WebDriver engine passes HostInfo::webdriver(family), except that a set holding an undeclared plugin is checked as for Chromium; see Limits.

PluginSet::audit#

#[must_use]pub fn audit(&self) -> Vec<AuditRow>

granted says whether the plugin’s grants cover the capability, and enforcement is the capability’s enforcement for a native plugin. An undeclared plugin’s rows are the legacy set, with category: None.

PluginSet::before_launch#

pub async fn before_launch(&self, launch: &mut LaunchSettings) -> Result<()>

Lets every plugin change the start-up settings, in run order, and checks each plugin’s change right after its hook:

A field is sealed by the first plugin that changes it while its metadata holds the matching seal (Seals::PROXY, Seals::WEBRTC, Seals::HEADLESS); a later plugin may set the same value again, not another one. See Seals.

PluginSet::on_browser#

pub async fn on_browser(&self, browser: &dyn BrowserHandle) -> Result<()>

Tells every plugin, in run order, that the browser runs.

PluginSet::on_page_created#

pub async fn on_page_created(&self, page: &dyn PageHandle) -> Result<()>

Plugin by plugin, in run order: adds the plugin’s packages with page.add_init_script(&package.init_script()), then calls its on_page_created. A package that says neither only_on nor everywhere is skipped here; the check has already refused it.

PluginSet::on_close#

pub async fn on_close(&self) -> Vec<PluginError>

Tells every plugin, in run order, that the browser is about to close. Every plugin runs even when one fails; the caller logs the failures.

AuditRow#

struct non_exhaustive seleniumbase_rs_plugin::AuditRow

#[derive(Clone, Debug, PartialEq)]#[non_exhaustive]pub struct AuditRow {    pub plugin: String,    pub category: Option<Category>,    pub capability: Capability,    pub risk: Risk,    pub granted: bool,    pub enforcement: Enforcement,}

One row of PluginSet::audit.

Run order#

Every method that runs hooks, and names and audit, goes through the plugins in one order, resolved from:

1. The phase of each plugin: Last for a plugin with Requirements::RUN_LAST; otherwise its metadata’s phase; otherwise its category’s default phase; otherwise Normal. Phases run in the order Prepare, Normal, Enforce, Observe, Last (Phase).
2. The edges: each name in requires or dependencies runs before the plugin (and must be present); each present plugin named in after runs before it; each present plugin named in before runs after it. An after or before naming an absent plugin is ignored. Edges win over phases: a Prepare plugin that runs after a Normal one comes after it.
3. The insertion order, among plugins that are ready at the same time and share a phase.

The resolver is Kahn’s algorithm, always taking the ready plugin with the lowest phase, then the lowest insertion index. So a set of plugins that declare nothing runs in the order they were added, with the RUN_LAST ones at the end. When the order cannot be resolved (a missing requires, a conflict or a cycle), names and the hook runners fall back to insertion order with the RUN_LAST plugins at the end; check reports the error.