imagegen_bridge_core/
provider.rs

1//! Provider extension interface.
2
3use std::{pin::Pin, time::Instant};
4
5use async_trait::async_trait;
6use futures_core::Stream;
7use tokio::sync::mpsc;
8use tokio_util::sync::CancellationToken;
9
10use crate::{
11    BridgeError, ImageRequest, ImageResponse, ProviderCapabilities, ProviderDescriptor,
12    ProviderEvent, SessionMetadata,
13};
14
15/// Stream returned by providers that expose incremental progress.
16pub type ProviderEventStream =
17    Pin<Box<dyn Stream<Item = Result<ProviderEvent, BridgeError>> + Send + 'static>>;
18
19/// Runtime metadata and cancellation propagated into a provider call.
20#[derive(Debug, Clone)]
21pub struct ProviderContext {
22    /// Safe bridge request ID.
23    pub request_id: String,
24    /// Absolute request deadline.
25    pub deadline: Instant,
26    /// Cooperative cancellation signal.
27    pub cancellation: CancellationToken,
28    /// Optional bounded event sink supplied by the shared runtime.
29    pub events: Option<mpsc::Sender<ProviderEvent>>,
30}
31
32/// Provider-neutral image backend.
33#[async_trait]
34pub trait ImageProvider: Send + Sync {
35    /// Returns stable provider identity.
36    fn descriptor(&self) -> ProviderDescriptor;
37
38    /// Returns current capabilities for an optional model.
39    async fn capabilities(&self, model: Option<&str>) -> Result<ProviderCapabilities, BridgeError>;
40
41    /// Executes one normalized request without exposing incremental events.
42    async fn execute(
43        &self,
44        request: ImageRequest,
45        context: ProviderContext,
46    ) -> Result<ImageResponse, BridgeError>;
47
48    /// Starts a request with incremental events when supported.
49    async fn execute_stream(
50        &self,
51        _request: ImageRequest,
52        _context: ProviderContext,
53    ) -> Result<ProviderEventStream, BridgeError> {
54        Err(BridgeError::new(
55            crate::ErrorCode::UnsupportedCapability,
56            "provider does not support streaming image events",
57        ))
58    }
59
60    /// Performs a non-generating auth/readiness check.
61    async fn check_ready(&self) -> Result<(), BridgeError>;
62
63    /// Looks up caller-visible persistent session metadata when supported.
64    async fn get_session(&self, _key: &str) -> Result<SessionMetadata, BridgeError> {
65        Err(BridgeError::new(
66            crate::ErrorCode::UnsupportedCapability,
67            "provider does not expose persistent sessions",
68        ))
69    }
70
71    /// Deletes a persistent session binding when supported.
72    async fn delete_session(&self, _key: &str) -> Result<(), BridgeError> {
73        Err(BridgeError::new(
74            crate::ErrorCode::UnsupportedCapability,
75            "provider does not expose persistent sessions",
76        ))
77    }
78
79    /// Returns the number of supervised provider process restarts when exposed.
80    ///
81    /// Implementations must return only a monotonic low-cardinality counter.
82    fn restart_count(&self) -> Option<u64> {
83        None
84    }
85
86    /// Releases provider resources during graceful shutdown.
87    async fn shutdown(&self) -> Result<(), BridgeError> {
88        Ok(())
89    }
90}
imagegen_bridge_core/provider.rs

imagegen_bridge_core/
provider.rs
