ocp_host/error.rs
1//! `HostError` — the one typed error the host runtime raises
2//! (`02-architecture.md` §1.5 "fail loud"). Everything a fan-out or a single
3//! provider exchange can go wrong with is a named variant here; nothing in
4//! the hot path panics. `ocp-host` owns its own error type rather than
5//! borrowing `stella`'s so the crate stays industry-facing and dependency-
6//! light (`02-architecture.md` §2 — depends only on `ocp-types` + transport
7//! crates).
8
9use ocp_types::DataFlow;
10
11/// Anything the host runtime can surface while talking to a provider.
12#[derive(Debug, thiserror::Error)]
13pub enum HostError {
14 /// The provider speaks an incompatible protocol family
15 /// (`06-context-protocol.md` §3). Reported the instant the handshake ack
16 /// arrives — never a hang (task deliverable 1).
17 #[error(
18 "protocol version mismatch: host speaks {host}, provider {provider} speaks {provider_version}"
19 )]
20 VersionMismatch {
21 host: String,
22 provider: String,
23 provider_version: String,
24 },
25
26 /// A line/body could not be encoded to or decoded from the wire envelope
27 /// (`06-context-protocol.md` §3.1). A malformed provider message is a
28 /// clean error, never a host crash (task deliverable 5).
29 #[error("wire encode/decode error: {0}")]
30 Wire(String),
31
32 /// The underlying transport (stdio pipe or HTTP) failed.
33 #[error("transport error talking to provider {id}: {message}")]
34 Transport { id: String, message: String },
35
36 /// The provider's child process closed its stream mid-exchange — it
37 /// crashed. Isolated to this provider; never poisons a `query_all`
38 /// (task deliverable 5).
39 #[error("provider {id} crashed or closed its stream mid-exchange")]
40 ProviderCrashed { id: String },
41
42 /// The provider took longer than the host's per-provider budget.
43 #[error("provider {id} timed out after {timeout_ms}ms")]
44 Timeout { id: String, timeout_ms: u64 },
45
46 /// The provider reported an error over the wire (an `error` envelope).
47 #[error("provider {id} reported an error: {message}")]
48 Provider { id: String, message: String },
49
50 /// The provider declares `egress` and has no recorded consent, so the
51 /// host refuses to transmit a query to it (`06-context-protocol.md`
52 /// §3.5 — a host MUST NOT auto-enable egress providers). The query
53 /// payload never left the host.
54 #[error(
55 "provider {id} declares egress and requires one-time consent naming what leaves before it can be queried"
56 )]
57 ConsentRequired { id: String, data_flow: DataFlow },
58
59 /// A message of the wrong kind arrived where the protocol expected a
60 /// specific envelope (e.g. a `frames` reply to a `query`).
61 #[error("expected a `{expected}` envelope from provider {id}, got `{got}`")]
62 UnexpectedEnvelope {
63 id: String,
64 expected: String,
65 got: String,
66 },
67
68 /// No provider is registered under the given id.
69 #[error("no provider registered with id `{0}`")]
70 UnknownProvider(String),
71
72 /// Spawning the provider child process failed.
73 #[error("failed to spawn provider process: {0}")]
74 Spawn(String),
75}