monoloop_connector/
instance.rs

1//! Connector instance identity, factory, and matched Connector/SessionAdapter pair.
2
3use crate::session::SessionAdapter;
4use crate::traits::Connector;
5use monoloop_contracts::IdentityError;
6use std::fmt;
7use std::sync::Arc;
8use thiserror::Error;
9use uuid::Uuid;
10
11/// Identity of one constructed Connector instance (one per Channel at runtime).
12#[derive(Clone, Debug, PartialEq, Eq, Hash)]
13pub struct ConnectorInstanceId(String);
14
15impl ConnectorInstanceId {
16    /// Fallible constructor.
17    pub fn try_new(value: impl Into<String>) -> Result<Self, IdentityError> {
18        let s = value.into();
19        monoloop_contracts::validate_identity_string(&s)?;
20        Ok(Self(s))
21    }
22
23    /// Allocate a random instance id.
24    pub fn generate() -> Self {
25        Self(Uuid::new_v4().to_string())
26    }
27
28    /// Borrow the underlying string.
29    pub fn as_str(&self) -> &str {
30        &self.0
31    }
32}
33
34impl fmt::Display for ConnectorInstanceId {
35    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
36        f.write_str(&self.0)
37    }
38}
39
40/// One matched Connector plus optional SessionAdapter for a Channel.
41pub struct ConnectorInstance {
42    /// Instance identity used as session-attachment owner.
43    pub instance_id: ConnectorInstanceId,
44    /// Transport connector.
45    pub connector: Arc<dyn Connector>,
46    /// Present for external-agent Channels; `None` for direct LLM.
47    pub sessions: Option<Arc<dyn SessionAdapter>>,
48}
49
50impl ConnectorInstance {
51    /// Construct an instance with the given parts.
52    pub fn new(
53        instance_id: ConnectorInstanceId,
54        connector: Arc<dyn Connector>,
55        sessions: Option<Arc<dyn SessionAdapter>>,
56    ) -> Self {
57        Self {
58            instance_id,
59            connector,
60            sessions,
61        }
62    }
63}
64
65/// Factory that produces matched Connector/SessionAdapter instances.
66pub trait ConnectorFactory: Send + Sync {
67    /// Create one instance (called once per Channel at runtime startup).
68    fn create(&self) -> Result<ConnectorInstance, ConnectorBuildError>;
69}
70
71/// Failure constructing a Connector instance.
72#[derive(Clone, Debug, Error, PartialEq, Eq)]
73pub enum ConnectorBuildError {
74    /// Configuration invalid.
75    #[error("connector configuration invalid: {0}")]
76    ConfigurationInvalid(&'static str),
77    /// Resource unavailable.
78    #[error("connector resource unavailable: {0}")]
79    ResourceUnavailable(&'static str),
80    /// Internal invariant.
81    #[error("connector build invariant failed: {0}")]
82    InvariantFailed(&'static str),
83}
monoloop_connector/instance.rs

monoloop_connector/
instance.rs
