crates/kernel/ents-gate/src/error.rs
error.rshistorycomment on this file
| 1 | //! The gate's infrastructure error type. |
| 2 | //! |
| 3 | //! An [`Error`] is never a verdict: it means the gate could not *reach* a |
| 4 | //! judgment (a store read failed, an object is missing or undecodable), |
| 5 | //! as opposed to [`crate::Refusal`], which is the judgment "no". Callers |
| 6 | //! at the mandatory call site (`gate.mandatory-hosted`) must treat an |
| 7 | //! `Error` exactly like a failing verdict — abort the write — because a |
| 8 | //! gate that cannot read its policy must fail closed; advisory call sites |
| 9 | //! should surface it as "could not evaluate", not as "refused". |
| 10 | |
| 11 | use gix_hash::ObjectId; |
| 12 | |
| 13 | /// Everything that can prevent the gate from reaching a verdict. |
| 14 | #[derive(Debug, thiserror::Error)] |
| 15 | pub enum Error { |
| 16 | /// The ref store's read half failed. Retry or surface; the proposed |
| 17 | /// update was neither admitted nor refused. |
| 18 | #[error("ref store read failed: {0}")] |
| 19 | Refs(#[from] gix_ref_store::Error), |
| 20 | |
| 21 | /// The object store failed while looking up `oid`. |
| 22 | #[error("object lookup failed for {oid}: {source}")] |
| 23 | Object { |
| 24 | /// The object being looked up. |
| 25 | oid: ObjectId, |
| 26 | /// The underlying object-store error. |
| 27 | #[source] |
| 28 | source: gix_object::find::Error, |
| 29 | }, |
| 30 | |
| 31 | /// `oid` is not present in the object store. At the hosted call site |
| 32 | /// this means the push's objects were not ingested before the gate |
| 33 | /// ran; at pre-flight it usually means an unfetched object. |
| 34 | #[error("object {oid} is missing from the object store")] |
| 35 | Missing { |
| 36 | /// The absent object. |
| 37 | oid: ObjectId, |
| 38 | }, |
| 39 | |
| 40 | /// `oid` exists but could not be decoded as the object kind the gate |
| 41 | /// needed (a commit, or a commit's timestamp field). |
| 42 | #[error("object {oid} could not be decoded: {detail}")] |
| 43 | Decode { |
| 44 | /// The undecodable object. |
| 45 | oid: ObjectId, |
| 46 | /// What failed, human-readable. |
| 47 | detail: String, |
| 48 | }, |
| 49 | |
| 50 | /// A policy entity's typed tree (a member, or `refs/meta/config`) |
| 51 | /// could not be deserialized. The gate fails closed on this rather |
| 52 | /// than treating unreadable policy as absent policy. |
| 53 | #[error("policy entity at {oid} is unreadable: {source}")] |
| 54 | Entity { |
| 55 | /// The tree (or commit) whose entity failed to load. |
| 56 | oid: ObjectId, |
| 57 | /// The typed-tree deserialization error. |
| 58 | #[source] |
| 59 | source: facet_git_tree::Error, |
| 60 | }, |
| 61 | } |
| 62 | |
| 63 | /// The `Result` alias every fallible `ents-gate` operation returns. |
| 64 | pub type Result<T> = std::result::Result<T, Error>; |