Skip to main content

ferryman_core/
error.rs

1//! The error type returned by every fallible `ferryman-core` function.
2
3use std::path::PathBuf;
4
5/// Why a config, upstream, breaker or CIDR list was rejected.
6///
7/// Match on the variant to react by category; `Display` gives the
8/// human-readable message (it names the route prefix and upstream where one
9/// is involved). Variants may be added in minor releases.
10#[derive(Debug, thiserror::Error)]
11#[non_exhaustive]
12pub enum Error {
13    /// The config file could not be read.
14    #[error("reading config file {}", path.display())]
15    ReadConfig {
16        path: PathBuf,
17        #[source]
18        source: std::io::Error,
19    },
20    /// The config file is not valid TOML for the schema.
21    ///
22    /// `path` is `None` when parsed from a string or table
23    /// ([`ConfigToml::from_str`](crate::ConfigToml), `from_table`).
24    #[error("parsing config{}", match path { Some(p) => format!(" file {}", p.display()), None => String::new() })]
25    Toml {
26        path: Option<PathBuf>,
27        #[source]
28        source: toml::de::Error,
29    },
30    /// A top-level key is out of range. `reason` is e.g. `must be >= 1`.
31    #[error("{key} {reason}")]
32    InvalidConfig { key: &'static str, reason: String },
33    /// A route prefix does not start with `/`.
34    #[error("route prefix {prefix:?} must start with '/'")]
35    InvalidPrefix { prefix: String },
36    /// A route prefix is not in normalised form (unreserved characters
37    /// unescaped, uppercase hex, no `//`, ASCII only), so it could never match,
38    /// or contains `;`, `\`, `%2F` or `%5C` (every request would be rejected).
39    #[error("route prefix {prefix:?} is not normalised; write it as {normal:?}")]
40    NonCanonicalPrefix { prefix: String, normal: String },
41    /// Two routes share a prefix.
42    #[error("duplicate route prefix {prefix:?}")]
43    DuplicatePrefix { prefix: String },
44    /// A route's upstream URI is unusable (bad URI, scheme, host, path...).
45    #[error("route {route:?}: {reason}")]
46    InvalidUpstream {
47        route: String,
48        upstream: String,
49        reason: String,
50        #[source]
51        source: Option<http::uri::InvalidUri>,
52    },
53    /// A route's `cooldown_secs` is out of range.
54    #[error("route {route:?}: cooldown_secs {reason}")]
55    InvalidCooldown { route: String, reason: String },
56    /// Routes sharing one upstream (one breaker) disagree on the cooldown.
57    #[error(
58        "route {route:?}: upstream {upstream} is shared with another route but has a \
59         different cooldown ({cooldown_secs}s vs {other_secs}s); routes to one upstream share one breaker"
60    )]
61    ConflictingCooldown {
62        route: String,
63        upstream: String,
64        cooldown_secs: u64,
65        other_secs: u64,
66    },
67    /// A route's `health_path` is not an absolute path without query or fragment.
68    #[error("route {route:?}: health_path {path:?} must start with '/' and contain no '?' or '#'")]
69    InvalidHealthPath { route: String, path: String },
70    /// Routes sharing one upstream (one breaker) disagree on a health setting.
71    #[error(
72        "route {route:?}: upstream {upstream} is shared with another route but has a \
73         different {setting} ({value} vs {other}); routes to one upstream share one health check"
74    )]
75    ConflictingHealth {
76        route: String,
77        upstream: String,
78        /// `"health_path"` or `"health_disabled"`.
79        setting: &'static str,
80        value: String,
81        other: String,
82    },
83    /// A `trusted_proxies` entry is not a valid CIDR or address.
84    #[error("trusted_proxies entry {entry:?}: {reason}")]
85    InvalidCidr { entry: String, reason: String },
86    /// `BreakerConfig` failed validation (`Breaker::new`, `Upstream::new`).
87    /// `upstream` is the `host:port` name when raised by `Upstream::new`.
88    #[error("{reason}{}", upstream.as_ref().map(|u| format!(" (upstream {u})")).unwrap_or_default())]
89    InvalidBreakerConfig {
90        reason: String,
91        upstream: Option<String>,
92    },
93}
94
95const _: fn() = || {
96    fn assert<T: std::error::Error + Send + Sync + 'static>() {}
97    assert::<Error>();
98};