Skip to main content

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}