Struct TailtriageController 

pub struct TailtriageController { /* private fields */ }

Long-lived live-capture controller for arm/disarm workflows.

Implementations

impl TailtriageController

pub fn builder(service_name: impl Into<String>) -> TailtriageControllerBuilder

Creates a builder for controller-level scaffolding.

pub fn load_config_from_path( path: impl AsRef<Path>, ) -> Result<LoadedControllerConfig, ConfigLoadError>

Loads controller TOML config from path without mutating controller state.

This helper parses and returns the activation template that would be applied on reload/build.

Errors

Returns ConfigLoadError when reading or parsing the TOML file fails.

pub fn status(&self) -> TailtriageControllerStatus

Returns a status snapshot of controller lifecycle and template state.

pub fn reload_template(&self, next_template: TailtriageControllerTemplate)

Replaces the template used to create the next activation generation.

This compatibility helper validates next_template and then applies it.

Panics

Panics when template validation fails. Prefer TailtriageController::try_reload_template to handle validation errors explicitly.

pub fn try_reload_template( &self, next_template: TailtriageControllerTemplate, ) -> Result<(), ReloadTemplateError>

Replaces the template used to create the next activation generation.

Unlike TailtriageController::reload_template, this method returns validation errors instead of panicking.

Validation matches the build-time checks done by TailtriageController::enable.

Errors

Returns ReloadTemplateError when service_name is blank or when building a run with this template would fail.

pub fn reload_config(&self) -> Result<(), ReloadConfigError>

Reloads controller config from the configured template file path.

Reload only updates the template for future activations. Any active generation keeps the activation config it started with.

Errors

Returns ReloadConfigError when the controller has no config_path or when loading/parsing/validating the TOML file fails.

pub fn enable(&self) -> Result<ActiveGenerationState, EnableError>

Arms capture by creating a fresh active generation with a bounded run.

Errors

Returns EnableError::AlreadyActive when another generation is already active.

Returns EnableError::Build when constructing the generation run fails.

Returns EnableError::MissingTokioRuntimeForSampler when runtime sampler template startup is enabled but enable() is called outside an active Tokio runtime.

Returns EnableError::StartRuntimeSampler when runtime sampler startup is enabled but sampler initialization fails (for example, when config sets interval_ms = 0).

pub fn disable(&self) -> Result<DisableOutcome, DisableError>

Disarms capture for the active generation.

This stops new request admissions immediately. If no admitted captured requests remain in flight, disarm finalizes immediately. Otherwise the generation is marked closing and finalization happens after the admitted captured requests drain.

Errors

Returns DisableError::Finalize when final artifact writing fails.

pub fn begin_request_with( &self, route: impl Into<String>, options: RequestOptions, ) -> ControllerStartedRequest

Begins one request through the controller.

When an active generation is still admitting requests, the returned tokens are bound to that generation.

When controller capture is disabled (or an active generation is closing), this returns inert/no-op request tokens.

Inert handles preserve explicit metadata from RequestOptions (request_id and kind). When request_id is omitted, the controller assigns a local fallback ID in inert-{N} form for predictable non-empty metadata.

pub fn begin_request( &self, route: impl Into<String>, ) -> ControllerStartedRequest

Convenience helper using default request options.

pub fn try_begin_request_with( &self, route: impl Into<String>, options: RequestOptions, ) -> Option<ControllerStartedRequest>

Tries to begin a captured request when an active generation is still admitting requests.

The returned handle and completion are generation-bound at admission time. They remain attached to that admitted generation even if the controller is disabled and re-enabled before completion finishes.

Returns None when controller is disabled or when active generation is closing.

Prefer TailtriageController::begin_request_with for the primary non-branching API.

pub fn try_begin_request( &self, route: impl Into<String>, ) -> Option<ControllerStartedRequest>

Compatibility helper using default request options.

Prefer TailtriageController::begin_request for the primary non-branching API.

pub fn shutdown(&self) -> Result<(), ShutdownError>

Finalizes controller state for process shutdown.

Shutdown makes lifecycle behavior explicit: it immediately stops new admissions and writes any active generation artifact, even if unfinished requests remain. That behavior matches tailtriage_core::Tailtriage::shutdown.

Errors

Returns ShutdownError::Finalize if artifact writing fails.

Trait Implementations

impl Clone for TailtriageController

fn clone(&self) -> TailtriageController

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TailtriageController

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.