Trait HandlerPlugin 

pub trait HandlerPlugin: Send {
    // Required methods
    fn push_scope(&mut self);
    fn pop_scope(&mut self);
    fn on_binding_start(
        &mut self,
        name: &str,
        raw: bool,
        writer: &mut dyn ResponseWriter,
    ) -> Result<()>;
    fn on_binding_end(
        &mut self,
        name: &str,
        raw: bool,
        writer: &mut dyn ResponseWriter,
    ) -> Result<()>;
    fn on_repeat_item_start(
        &mut self,
        index: usize,
        writer: &mut dyn ResponseWriter,
    ) -> Result<()>;
    fn on_repeat_item_end(
        &mut self,
        index: usize,
        writer: &mut dyn ResponseWriter,
    ) -> Result<()>;
    fn on_element_data(
        &mut self,
        data: &[u8],
        writer: &mut dyn ResponseWriter,
    ) -> Result<()>;

    // Provided methods
    fn on_for_start(
        &mut self,
        name: &str,
        writer: &mut dyn ResponseWriter,
    ) -> Result<()> { ... }
    fn on_for_end(
        &mut self,
        name: &str,
        writer: &mut dyn ResponseWriter,
    ) -> Result<()> { ... }
    fn on_if_start(
        &mut self,
        name: &str,
        writer: &mut dyn ResponseWriter,
    ) -> Result<()> { ... }
    fn on_if_end(
        &mut self,
        name: &str,
        writer: &mut dyn ResponseWriter,
    ) -> Result<()> { ... }
    fn write_route_component_state(
        &self,
        _state: &Value,
        _writer: &mut dyn ResponseWriter,
    ) -> Result<()> { ... }
    fn emit_templates(
        &self,
        protocol: &WebUIProtocol,
        components: &[String],
        _nonce: Option<&str>,
        writer: &mut dyn ResponseWriter,
    ) -> Result<()> { ... }
    fn collect_template_payloads<'a>(
        &self,
        _protocol: &'a WebUIProtocol,
        _components: &[String],
    ) -> Option<Vec<WebUiTemplatePayload<'a>>> { ... }
    fn emit_templates_slice(
        &self,
        protocol: &WebUIProtocol,
        tags: &[&str],
        _nonce: Option<&str>,
        writer: &mut dyn ResponseWriter,
    ) -> Result<()> { ... }
    fn collect_template_payloads_slice<'a>(
        &self,
        _protocol: &'a WebUIProtocol,
        _tags: &[&str],
    ) -> Option<Vec<WebUiTemplatePayload<'a>>> { ... }
    fn emit_bootstrap_extension_payloads(
        &self,
        _payloads: &[WebUiTemplatePayload<'_>],
        _nonce: Option<&str>,
        _writer: &mut dyn ResponseWriter,
    ) -> Result<()> { ... }
    fn emit_bootstrap_extension(
        &self,
        _context: BootstrapExtensionContext<'_>,
        _writer: &mut dyn ResponseWriter,
    ) -> Result<()> { ... }
}

A handler plugin that can inject additional content during rendering.

Plugins receive callbacks at key points in the rendering lifecycle:

• Scope management: push_scope / pop_scope for component and loop boundaries
• Binding lifecycle: binding hooks around escaped and raw signals
• For-loop lifecycle: on_for_start / on_for_end around for-loop blocks
• If-condition lifecycle: on_if_start / on_if_end around if-condition blocks
• Repeat items: on_repeat_item_start / on_repeat_item_end per for-loop item
• Element data: on_element_data for parser-produced hydration metadata
• Route state: write_route_component_state for framework-specific opening-tag attributes

WebUI does not interpret what plugins write — it just calls the hooks. Each framework defines its own marker format.

Threading

Plugins must be Send because the same handler can create an owned StreamingSession. That session parks its live per-render plugin between calls and may move to another host thread. Rust cannot safely add Send after a factory result has been erased to Box<dyn HandlerPlugin>, so the guarantee is established here.

Plugins do not need to be Sync. Every render receives a fresh instance, and WebUI never invokes one instance concurrently. Sendable interior mutability such as Cell and RefCell remains supported; thread-affine state such as Rc must be replaced with owned data, Arc, or another sendable handle.

Required Methods

fn push_scope(&mut self)

Enter a new scope (component or for-loop item boundary). Typically resets per-scope counters.

fn pop_scope(&mut self)

Exit the current scope, restoring the parent scope state.

fn on_binding_start( &mut self, name: &str, raw: bool, writer: &mut dyn ResponseWriter, ) -> Result<()>

Called before rendering a signal binding.

raw is true when the signal owns a replaceable HTML sibling range.

fn on_binding_end( &mut self, name: &str, raw: bool, writer: &mut dyn ResponseWriter, ) -> Result<()>

Called after rendering a signal binding.

raw is true when the signal owns a replaceable HTML sibling range.

fn on_repeat_item_start( &mut self, index: usize, writer: &mut dyn ResponseWriter, ) -> Result<()>

Called before rendering a repeat item in a for loop.

fn on_repeat_item_end( &mut self, index: usize, writer: &mut dyn ResponseWriter, ) -> Result<()>

Called after rendering a repeat item.

fn on_element_data( &mut self, data: &[u8], writer: &mut dyn ResponseWriter, ) -> Result<()>

Called when parser-produced element metadata is encountered.

Provided Methods

fn on_for_start( &mut self, name: &str, writer: &mut dyn ResponseWriter, ) -> Result<()>

Called before rendering a for-loop block. Defaults to on_binding_start.

fn on_for_end( &mut self, name: &str, writer: &mut dyn ResponseWriter, ) -> Result<()>

Called after rendering a for-loop block. Defaults to on_binding_end.

fn on_if_start( &mut self, name: &str, writer: &mut dyn ResponseWriter, ) -> Result<()>

Called before rendering an if-condition block. Defaults to on_binding_start.

fn on_if_end( &mut self, name: &str, writer: &mut dyn ResponseWriter, ) -> Result<()>

Called after rendering an if-condition block. Defaults to on_binding_end.

fn write_route_component_state( &self, _state: &Value, _writer: &mut dyn ResponseWriter, ) -> Result<()>

Called when emitting a matched route component’s opening tag. Plugins can write framework-specific attributes before the closing >. The default is a no-op.

fn emit_templates( &self, protocol: &WebUIProtocol, components: &[String], _nonce: Option<&str>, writer: &mut dyn ResponseWriter, ) -> Result<()>

Emit component templates collected during SSR. The default emits each template as-is (suitable for FAST <f-template> tags). The WebUI split-payload path uses HandlerPlugin::collect_template_payloads instead.

fn collect_template_payloads<'a>( &self, _protocol: &'a WebUIProtocol, _components: &[String], ) -> Option<Vec<WebUiTemplatePayload<'a>>>

Return split WebUI template payloads for the given components.

The WebUI plugin overrides this so lib.rs can emit JSON metadata in an inert data block and only emit condition closures as executable JS. Returns None when templates are non-WebUI payloads (e.g. FAST <f-template> tags).

fn emit_templates_slice( &self, protocol: &WebUIProtocol, tags: &[&str], _nonce: Option<&str>, writer: &mut dyn ResponseWriter, ) -> Result<()>

Slice-based counterpart to HandlerPlugin::emit_templates.

The streaming checkpoint path captures the exact component tags rendered since the previous checkpoint as a borrowed &[&str], avoiding the owned Vec<String> the ordinary body-end path builds. The default forwards to [emit_component_templates_slice] (verbatim FAST <f-template> emission).

fn collect_template_payloads_slice<'a>( &self, _protocol: &'a WebUIProtocol, _tags: &[&str], ) -> Option<Vec<WebUiTemplatePayload<'a>>>

Slice-based counterpart to HandlerPlugin::collect_template_payloads.

Consumes a borrowed &[&str] of component tags so the streaming path can project per-checkpoint templates without materializing an owned set. The default returns None.

fn emit_bootstrap_extension_payloads( &self, _payloads: &[WebUiTemplatePayload<'_>], _nonce: Option<&str>, _writer: &mut dyn ResponseWriter, ) -> Result<()>

Emit plugin-specific executable SSR bootstrap code for the streaming path, given only the already-collected template payloads.

Unlike HandlerPlugin::emit_bootstrap_extension, this takes no Vec<String> component set — the streaming checkpoint has already projected the exact per-checkpoint payloads. The default is a no-op.

fn emit_bootstrap_extension( &self, _context: BootstrapExtensionContext<'_>, _writer: &mut dyn ResponseWriter, ) -> Result<()>

Emit plugin-specific executable SSR bootstrap code, if needed.

The handler emits shared metadata as inert #webui-data; client packages parse that data lazily. Plugins can still emit executable side-channel data here, such as WebUI framework templateFns closures. The default is a no-op for FAST plugins, which use <f-template> tags.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl HandlerPlugin for FastV2HydrationPlugin

impl HandlerPlugin for FastV3HydrationPlugin

impl HandlerPlugin for WebUIHydrationPlugin