Skip to main content

fetchium_core/plugin/
traits.rs

1//! Plugin trait definitions for all 6 plugin types (PRD §29).
2
3use crate::error::FetchiumError;
4use async_trait::async_trait;
5
6/// Plugin type classification.
7#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
8#[serde(rename_all = "snake_case")]
9pub enum PluginType {
10    Backend,
11    Extractor,
12    Ranker,
13    Formatter,
14    Validator,
15    AiProvider,
16}
17
18impl std::fmt::Display for PluginType {
19    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
20        match self {
21            PluginType::Backend => write!(f, "backend"),
22            PluginType::Extractor => write!(f, "extractor"),
23            PluginType::Ranker => write!(f, "ranker"),
24            PluginType::Formatter => write!(f, "formatter"),
25            PluginType::Validator => write!(f, "validator"),
26            PluginType::AiProvider => write!(f, "ai_provider"),
27        }
28    }
29}
30
31/// Base trait every plugin must implement.
32pub trait Plugin: Send + Sync {
33    fn name(&self) -> &str;
34    fn version(&self) -> &str;
35    fn plugin_type(&self) -> PluginType;
36    fn description(&self) -> &str {
37        ""
38    }
39    fn init(&mut self, config: &serde_json::Value) -> Result<(), FetchiumError>;
40    fn shutdown(&mut self) -> Result<(), FetchiumError>;
41}
42
43/// Backend plugin: provides a search data source.
44#[async_trait]
45pub trait BackendPlugin: Plugin {
46    async fn search(
47        &self,
48        query: &str,
49        max_results: usize,
50    ) -> Result<Vec<crate::types::ResultItem>, FetchiumError>;
51    fn supported_features(&self) -> BackendFeatures {
52        BackendFeatures::default()
53    }
54}
55
56/// Features a backend plugin supports.
57#[derive(Debug, Default, Clone)]
58pub struct BackendFeatures {
59    pub supports_date_filter: bool,
60    pub supports_language_filter: bool,
61    pub max_results_per_query: usize,
62}
63
64/// Extractor plugin: custom content extraction strategy.
65#[async_trait]
66pub trait ExtractorPlugin: Plugin {
67    async fn extract(
68        &self,
69        url: &str,
70        raw_html: &str,
71    ) -> Result<crate::extract::ExtractedContent, FetchiumError>;
72    fn supported_content_types(&self) -> Vec<String>;
73}
74
75/// Ranker plugin: custom ranking algorithm.
76pub trait RankerPlugin: Plugin {
77    fn rank(
78        &self,
79        query: &str,
80        results: &mut Vec<crate::types::ResultItem>,
81    ) -> Result<(), FetchiumError>;
82}
83
84/// Formatter plugin: custom output format.
85pub trait FormatterPlugin: Plugin {
86    fn format(&self, result: &crate::types::SearchResult) -> Result<String, FetchiumError>;
87    fn file_extension(&self) -> &str;
88    fn mime_type(&self) -> &str;
89}
90
91/// Validator plugin: custom content validation.
92pub trait ValidatorPlugin: Plugin {
93    /// Returns confidence score in [0.0, 1.0].
94    fn validate(&self, text: &str, url: &str) -> Result<f64, FetchiumError>;
95}
96
97/// AI provider plugin: custom model backend.
98#[async_trait]
99pub trait AiProviderPlugin: Plugin {
100    async fn complete(&self, prompt: &str, max_tokens: u32) -> Result<String, FetchiumError>;
101    fn available_models(&self) -> Vec<String>;
102}