Skip to main content

qubit_spi/service/
service_provider.rs

1// =============================================================================
2//    Copyright (c) 2026 Haixing Hu.
3//
4//    SPDX-License-Identifier: Apache-2.0
5//
6//    Licensed under the Apache License, Version 2.0.
7// =============================================================================
8//! Provider contract for pluggable service implementations.
9
10use crate::SyncServiceSpec;
11use crate::error::ProviderFailure;
12
13/// Factory contract for one pluggable service implementation.
14///
15/// This trait contains only service-creation behavior. Implement
16/// [`crate::ProviderDefinition`] when the provider also needs to be registered
17/// with identity and selection metadata. Implement this trait when an
18/// application needs to provide one selectable backend for a
19/// [`SyncServiceSpec`]
20/// family. Registry fallback applies only to errors returned while these
21/// creation methods run. Once a service output is returned successfully,
22/// errors from later operations on that output do not trigger another
23/// provider attempt.
24///
25/// Each creation invokes a factory, but the factory may reuse an existing
26/// resource or return a shared handle. No fresh underlying allocation is
27/// promised.
28///
29/// # Type Parameters
30///
31/// * `S` - Synchronous service family created by this provider.
32///
33/// # Examples
34///
35/// ```rust
36/// use qubit_spi::{ServiceSpec, SyncServiceSpec};
37/// struct Spec;
38/// impl ServiceSpec for Spec {
39///     type Config = String;
40///     type Error = std::io::Error;
41/// }
42/// impl SyncServiceSpec for Spec { type Output = String; }
43/// use qubit_spi::{ProviderDescriptor, ProviderId, ProviderMetadata, ServiceProvider};
44/// use qubit_spi::error::ProviderFailure;
45/// struct Echo;
46/// impl ProviderMetadata for Echo {
47///     fn descriptor(&self) -> ProviderDescriptor {
48///         ProviderDescriptor::new(ProviderId::new("echo").expect("valid static ID"))
49///     }
50/// }
51/// impl ServiceProvider<Spec> for Echo {
52///     fn create_configured(&self, config: &String) -> Result<String, ProviderFailure<std::io::Error>> {
53///         Ok(config.clone())
54///     }
55/// }
56/// assert_eq!("explicit", Echo.create_configured(&"explicit".to_owned())?);
57/// assert_eq!("", Echo.create()?);
58/// # Ok::<(), Box<dyn std::error::Error>>(())
59/// ```
60pub trait ServiceProvider<S>: Send + Sync + 'static
61where
62    S: SyncServiceSpec,
63{
64    /// Creates one service output with the configuration default.
65    ///
66    /// # Returns
67    ///
68    /// The `S::Output` value created from `S::Config::default()`.
69    ///
70    /// # Errors
71    ///
72    /// Returns [`ProviderFailure`] when the provider cannot create the
73    /// service from the default configuration. The failure retains the
74    /// provider's domain error for registry diagnostics.
75    ///
76    /// # Panics
77    ///
78    /// Panics if `S::Config::default()` or [`Self::create_configured`] panics.
79    fn create(&self) -> Result<S::Output, ProviderFailure<S::Error>>
80    where
81        S::Config: Default,
82    {
83        self.create_configured(&S::Config::default())
84    }
85
86    /// Creates one service output from the supplied configuration.
87    ///
88    /// # Parameters
89    ///
90    /// * `config` - Service-family configuration declared by `S`.
91    ///
92    /// # Returns
93    ///
94    /// The `S::Output` value created from `config`.
95    ///
96    /// # Errors
97    ///
98    /// Returns [`ProviderFailure`] when this provider cannot create the
99    /// requested service. The failure retains the provider's domain error;
100    /// registry resolvers aggregate it with provider identity and fallback
101    /// termination diagnostics.
102    ///
103    /// # Panics
104    ///
105    /// May panic if the provider implementation panics while creating the
106    /// requested service.
107    fn create_configured(&self, config: &S::Config) -> Result<S::Output, ProviderFailure<S::Error>>;
108}