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}