qubit_spi/
provider_registry_error.rs

1/*******************************************************************************
2 *
3 *    Copyright (c) 2026 Haixing Hu.
4 *
5 *    SPDX-License-Identifier: Apache-2.0
6 *
7 *    Licensed under the Apache License, Version 2.0.
8 *
9 ******************************************************************************/
10//! Error type for provider registration and selection.
11
12use thiserror::Error;
13
14use crate::{
15    ProviderFailure,
16    ProviderName,
17};
18
19/// Error returned by provider registries.
20#[derive(Debug, Clone, Error)]
21pub enum ProviderRegistryError {
22    /// A provider id, alias, or selector is empty after trimming.
23    #[error("provider name must not be empty")]
24    EmptyProviderName,
25    /// A provider name contains unsupported characters.
26    #[error("invalid provider name '{name}': {reason}")]
27    InvalidProviderName {
28        /// Invalid provider name after trimming.
29        name: String,
30        /// Human-readable validation failure reason.
31        reason: String,
32    },
33    /// A provider id or alias conflicts with an already registered name.
34    #[error("duplicate provider name: {name}")]
35    DuplicateProviderName {
36        /// Conflicting provider name.
37        name: ProviderName,
38    },
39    /// No registered provider matches the requested selector.
40    #[error("unknown provider: {name}")]
41    UnknownProvider {
42        /// Requested provider selector.
43        name: ProviderName,
44    },
45    /// The selected provider is not available in the current environment.
46    #[error("provider '{name}' is unavailable: {}", .source.reason())]
47    ProviderUnavailable {
48        /// Requested provider selector.
49        name: ProviderName,
50        /// Provider-level unavailability error.
51        #[source]
52        source: crate::ProviderCreateError,
53    },
54    /// The selected provider failed while creating a service.
55    #[error("provider '{name}' failed to create service: {}", .source.reason())]
56    ProviderCreate {
57        /// Requested provider selector.
58        name: ProviderName,
59        /// Provider-level creation error.
60        #[source]
61        source: crate::ProviderCreateError,
62    },
63    /// All configured provider candidates failed.
64    #[error(
65        "no available provider; candidate failures: {}",
66        format_provider_failures(.failures)
67    )]
68    NoAvailableProvider {
69        /// Candidate failures in the order they were tried.
70        failures: Vec<ProviderFailure>,
71    },
72    /// No providers are registered.
73    #[error("provider registry is empty")]
74    EmptyRegistry,
75}
76
77/// Formats ordered fallback candidate failures.
78///
79/// # Parameters
80/// - `failures`: Candidate failures in the order they were tried.
81///
82/// # Returns
83/// Candidate failure messages joined by `; `.
84fn format_provider_failures(failures: &[ProviderFailure]) -> String {
85    failures
86        .iter()
87        .map(ToString::to_string)
88        .collect::<Vec<_>>()
89        .join("; ")
90}
qubit_spi/provider_registry_error.rs

qubit_spi/
provider_registry_error.rs
