Trait PipelineStage

Source

pub trait PipelineStage:
    Send
    + Sync
    + Debug {
    type Config: Send + Sync + Debug + ConfigValidator + Default;
    type Result: Send + Sync + Debug + 'static;

    // Required methods
    fn stage_id(&self) -> StageId;
    fn stage_name(&self) -> &str;
    fn process(
        &self,
        context: &mut StageContext,
        data: StageData,
        config: Option<&Self::Config>,
    ) -> Result<StageResult<Self::Result>, OCRError>;

    // Provided methods
    fn dependencies(&self) -> Vec<StageDependency> { ... }
    fn is_enabled(
        &self,
        context: &StageContext,
        config: Option<&Self::Config>,
    ) -> bool { ... }
    fn validate_config(&self, config: &Self::Config) -> Result<(), OCRError> { ... }
    fn default_config(&self) -> Self::Config { ... }
}

Expand description

Trait for extensible pipeline stages.

This trait defines the interface that all pipeline stages must implement to participate in the extensible pipeline system.

§Default Contract

All pipeline stages must implement a default contract to ensure consistency, reliability, and maintainability. This contract eliminates silent failures and ensures all stages provide meaningful defaults and proper validation.

§Contract Requirements:

Mandatory Default Configuration: default_config() must return a valid Self::Config
ConfigValidator Implementation: All config types must implement ConfigValidator
Validation Integration: Stages must use ConfigValidator in validate_config()
Required Traits: Config types must implement ConfigValidator + Default + Clone + Debug + Send + Sync

§Example Implementation:

use oar_ocr::pipeline::stages::{PipelineStage, StageId, StageContext, StageData, StageResult};
use oar_ocr::core::config::{ConfigValidator, ConfigError};
use oar_ocr::core::OCRError;
use serde::{Serialize, Deserialize};

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct MyStageConfig {
    pub threshold: f32,
    pub enabled: bool,
}

impl ConfigValidator for MyStageConfig {
    fn validate(&self) -> Result<(), ConfigError> {
        if !(0.0..=1.0).contains(&self.threshold) {
            return Err(ConfigError::InvalidConfig {
                message: "threshold must be between 0.0 and 1.0".to_string(),
            });
        }
        Ok(())
    }

    fn get_defaults() -> Self {
        Self { threshold: 0.5, enabled: true }
    }
}

#[derive(Debug)]
pub struct MyStage;

impl PipelineStage for MyStage {
    type Config = MyStageConfig;
    type Result = String;

    fn stage_id(&self) -> StageId { StageId::new("my_stage") }
    fn stage_name(&self) -> &str { "My Stage" }

    fn validate_config(&self, config: &Self::Config) -> Result<(), OCRError> {
        config.validate().map_err(|e| OCRError::ConfigError {
            message: format!("MyStageConfig validation failed: {}", e),
        })
    }

    fn default_config(&self) -> Self::Config {
        MyStageConfig::get_defaults()
    }

    fn process(
        &self,
        _context: &mut StageContext,
        _data: StageData,
        config: Option<&Self::Config>,
    ) -> Result<StageResult<Self::Result>, OCRError> {
        let config = config.cloned().unwrap_or_else(|| self.default_config());
        self.validate_config(&config)?;
        // Process with validated configuration...
    }
}