opcda_bridge/
error.rs

1//! The error type returned by every [`crate::Client`] method.
2
3/// Errors that can occur while talking to an opcda-bridge gateway.
4///
5/// The transport variants use `#[error(transparent)]`: `Display` and `source()`
6/// forward straight through to the wrapped `tonic` error with no added
7/// prefix or extra chain link. This matters because `opcda-bridge-client`'s
8/// CLI commands convert this type into an `anyhow::Error` with a bare `?`
9/// (the same way they converted a raw `tonic::Status`/
10/// `tonic::transport::Error` before this crate existed); transparency keeps
11/// that conversion rendering byte-for-byte the same error text the CLI
12/// printed before this crate existed, which is part of this crate's
13/// contract with its CLI consumer and is pinned down by
14/// `test_error_rpc_anyhow_debug_matches_bare_status` and
15/// `client::tests::test_connect_failure_anyhow_debug_matches_bare_transport_error`.
16///
17/// A dedicated `thiserror` enum (rather than reusing `anyhow::Error` here
18/// the way `opcda-bridge-client`'s own commands do) still lets a downstream
19/// consumer that does *not* want an `anyhow` dependency match on
20/// [`Error::Connect`] / [`Error::Rpc`] directly. [`Error::Protocol`] reports
21/// malformed or internally inconsistent responses from an incompatible gateway.
22#[derive(Debug, thiserror::Error)]
23pub enum Error {
24    /// Failed to establish the gRPC channel to the gateway (e.g. connection
25    /// refused, DNS failure, invalid address).
26    #[error(transparent)]
27    Connect(#[from] tonic::transport::Error),
28    /// The gateway returned a gRPC error for a `GetCapabilities`/`Browse`/
29    /// `CloseBrowseSession`/`Search`/`ListServers`/`Read`/`Write` call, or
30    /// for a search response-stream item.
31    #[error(transparent)]
32    Rpc(#[from] tonic::Status),
33    /// The connected gateway predates a required RPC.
34    #[error(
35        "gateway does not support {operation}; upgrade the gateway and client to compatible protocol versions"
36    )]
37    IncompatibleGateway { operation: &'static str },
38    /// The gateway returned a response that violates the negotiated protocol.
39    #[error("protocol error: {0}")]
40    Protocol(String),
41}
42
43/// A `Result` alias using [`Error`], mirroring the ergonomics of
44/// `anyhow::Result` (`opcda_bridge::Result<T>`) for a crate that
45/// intentionally does not depend on `anyhow` itself.
46pub type Result<T> = std::result::Result<T, Error>;
47
48#[cfg(test)]
49mod tests {
50    use super::*;
51
52    #[test]
53    fn test_error_rpc_display_is_transparent() {
54        let status = tonic::Status::internal("boom");
55        let expected = status.to_string();
56        let err: Error = status.into();
57        assert_eq!(err.to_string(), expected);
58    }
59
60    #[test]
61    fn test_error_rpc_matches_variant() {
62        let status = tonic::Status::not_found("missing");
63        let err: Error = status.into();
64        assert!(matches!(err, Error::Rpc(_)));
65    }
66
67    #[test]
68    fn test_error_rpc_debug_matches_variant_and_status() {
69        let status = tonic::Status::internal("boom");
70        let err: Error = status.clone().into();
71        assert_eq!(format!("{err:?}"), format!("Rpc({status:?})"));
72    }
73
74    #[test]
75    fn test_error_rpc_anyhow_debug_matches_bare_status() {
76        // `opcda-bridge-client`'s commands convert this crate's `Error` into
77        // `anyhow::Error` via a bare `?`; this must render identically to
78        // today's direct `tonic::Status` -> `anyhow::Error` conversion, or
79        // the CLI's printed error text would silently change.
80        let status = tonic::Status::internal("boom");
81        let bare = anyhow::Error::from(status.clone());
82        let wrapped = anyhow::Error::from(Error::from(status));
83        assert_eq!(format!("{bare:?}"), format!("{wrapped:?}"));
84        assert_eq!(bare.to_string(), wrapped.to_string());
85    }
86
87    #[test]
88    fn test_protocol_error_is_actionable() {
89        let err = Error::Protocol("unknown browse node kind".into());
90        assert_eq!(err.to_string(), "protocol error: unknown browse node kind");
91    }
92
93    #[test]
94    fn test_incompatible_gateway_error_is_actionable() {
95        let err = Error::IncompatibleGateway {
96            operation: "paged browse",
97        };
98        assert!(err.to_string().contains("upgrade the gateway and client"));
99    }
100
101    // `Error::Connect`'s transparency (both the plain and anyhow-wrapped
102    // rendering) is exercised in `client::tests`, since a real
103    // `tonic::transport::Error` can only be produced by an actual failed
104    // connection attempt, not constructed directly.
105}
opcda_bridge/error.rs

opcda_bridge/
error.rs
