Skip to main content

ifc_resource/
error.rs

1//! Structured failures for resource projections, queries, and authoring.
2
3use ifc_model::EntityId;
4
5/// Result of a resource projection, query, or authoring call, carrying
6/// [`ResourceError`] on failure.
7pub type ResourceResult<T> = Result<T, ResourceError>;
8
9/// Why a resource projection, query, or authoring call could not be
10/// completed.
11#[derive(Debug, Clone, PartialEq, Eq)]
12#[non_exhaustive]
13pub enum ResourceError {
14    /// The model header declares no `FILE_SCHEMA` token.
15    MissingSchema,
16    /// The header declares more than one schema, so the profile is ambiguous.
17    AmbiguousSchema {
18        /// Every schema token found in the header.
19        tokens: Vec<String>,
20    },
21    /// The declared schema is not one this operation supports: reads cover
22    /// IFC2X3 TC1, IFC4 ADD2 TC1 and IFC4X3 ADD2; authoring covers IFC4 ADD2
23    /// TC1 and IFC4X3 ADD2.
24    UnsupportedSchema {
25        /// The rejected schema token.
26        token: String,
27    },
28    /// The view's release does not declare what an accessor reads, in the
29    /// form it reads it.
30    ///
31    /// IFC2X3 TC1 declares no `IfcResourceTime` and no resource types, and
32    /// its `IfcConstructionResource` carries no `LongDescription`, `Usage`,
33    /// `BaseCosts` or `PredefinedType`; its `BaseQuantity` is an
34    /// `IfcMeasureWithUnit` rather than an `IfcPhysicalQuantity`. Asking for
35    /// one of those under IFC2X3 is this refusal, never `None`, so "the
36    /// release cannot hold it" stays distinct from "the file left it unset".
37    /// The IFC2X3-only accessors refuse the same way under IFC4 and IFC4X3.
38    NotInSchema {
39        /// The bound release's schema name, e.g. `IFC2X3`.
40        schema: String,
41        /// The entity that was read, when the request named one.
42        entity: Option<EntityId>,
43        /// The entity type lacking the attribute, or the entity type the
44        /// release does not declare at all.
45        entity_type: String,
46        /// The attribute, or `None` when the entity type itself is absent.
47        attribute: Option<&'static str>,
48    },
49    /// A requested entity id does not exist in the model.
50    EntityNotFound {
51        /// The missing entity id.
52        id: EntityId,
53    },
54    /// An entity was not the IFC type the caller requested.
55    WrongType {
56        /// The entity that was read.
57        id: EntityId,
58        /// The IFC type the caller expected.
59        expected: &'static str,
60        /// The IFC type actually declared.
61        actual: String,
62    },
63    /// The stored record is shorter than the schema's attribute list, so a
64    /// declared attribute has no slot. (An attribute the release does not
65    /// declare at all is [`ResourceError::NotInSchema`].)
66    MissingAttribute {
67        /// The entity that was read.
68        entity: EntityId,
69        /// Schema name of the absent attribute.
70        attribute: &'static str,
71    },
72    /// An attribute was present but held the wrong kind of value.
73    InvalidValue {
74        /// The entity that was read.
75        entity: EntityId,
76        /// Schema name of the offending attribute.
77        attribute: &'static str,
78        /// What kind of value was expected.
79        expected: &'static str,
80    },
81    /// An enumeration attribute held a value the schema does not declare.
82    InvalidEnumeration {
83        /// The entity that was read, when the value came from an entity
84        /// rather than an authoring draft.
85        entity: Option<EntityId>,
86        /// Schema name of the offending attribute.
87        attribute: &'static str,
88        /// The undeclared value.
89        value: String,
90    },
91    /// An entity reference attribute pointed at an id the model does not
92    /// contain.
93    DanglingReference {
94        /// The entity holding the dangling reference.
95        entity: EntityId,
96        /// Schema name of the offending attribute.
97        attribute: &'static str,
98        /// The id that resolved to nothing.
99        target: EntityId,
100    },
101    /// An entity reference resolved, but the target is not the IFC type the
102    /// slot requires.
103    WrongReferenceType {
104        /// The entity holding the reference.
105        entity: EntityId,
106        /// Schema name of the offending attribute.
107        attribute: &'static str,
108        /// The referenced entity.
109        target: EntityId,
110        /// The IFC type the slot requires.
111        expected: &'static str,
112        /// The IFC type actually declared.
113        actual: String,
114    },
115    /// An aggregate attribute held fewer items than the schema's minimum
116    /// cardinality.
117    InvalidCardinality {
118        /// The entity that was read.
119        entity: EntityId,
120        /// Schema name of the offending attribute.
121        attribute: &'static str,
122        /// The schema's minimum cardinality.
123        minimum: usize,
124        /// The actual number of items found.
125        actual: usize,
126    },
127    /// A `SET` attribute repeated the same reference more than once.
128    DuplicateReference {
129        /// The entity that was read.
130        entity: EntityId,
131        /// Schema name of the offending attribute.
132        attribute: &'static str,
133        /// The repeated reference.
134        target: EntityId,
135    },
136    /// A WHERE rule or other cross-attribute IFC semantic constraint failed.
137    SemanticViolation {
138        /// The entity that violated the rule, when applicable.
139        entity: Option<EntityId>,
140        /// Name of the violated rule.
141        rule: &'static str,
142    },
143    /// A resource composition or nesting traversal revisited an entity.
144    Cycle {
145        /// The entity where the cycle was detected.
146        at: EntityId,
147    },
148    /// A bounded traversal exceeded its depth or node budget.
149    BudgetExceeded {
150        /// The maximum depth allowed.
151        max_depth: usize,
152        /// The maximum number of nodes allowed.
153        max_nodes: usize,
154    },
155    /// A staged authoring draft could not be committed as written.
156    InvalidDraft {
157        /// The IFC entity type being authored.
158        entity_type: &'static str,
159        /// Schema name of the offending attribute.
160        attribute: &'static str,
161        /// What kind of value was expected.
162        expected: &'static str,
163    },
164    /// A supplied `GlobalId` is not a valid 22-character compressed IFC GUID.
165    InvalidGlobalId,
166    /// A transaction commit conflicted with a concurrent revision.
167    TransactionConflict {
168        /// The revision the transaction expected.
169        expected: u64,
170        /// The revision actually current.
171        actual: u64,
172    },
173}
174
175impl std::fmt::Display for ResourceError {
176    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
177        match self {
178            Self::MissingSchema => f.write_str("the model header declares no IFC schema"),
179            Self::AmbiguousSchema { tokens } => {
180                write!(f, "the model declares multiple schemas: {tokens:?}")
181            }
182            Self::UnsupportedSchema { token } => {
183                write!(
184                    f,
185                    "unsupported resource schema `{token}`; reads cover IFC2X3 TC1, IFC4 ADD2 TC1 \
186                     and IFC4X3 ADD2, authoring IFC4 ADD2 TC1 and IFC4X3 ADD2"
187                )
188            }
189            Self::NotInSchema {
190                schema,
191                entity_type,
192                attribute,
193                ..
194            } => match attribute {
195                Some(attribute) => write!(
196                    f,
197                    "{schema} does not declare {entity_type}.{attribute} in the form this \
198                     accessor reads"
199                ),
200                None => write!(f, "{schema} does not declare {entity_type}"),
201            },
202            Self::EntityNotFound { id } => write!(f, "entity {id} does not exist"),
203            Self::WrongType {
204                id,
205                expected,
206                actual,
207            } => {
208                write!(f, "entity {id} is {actual}, expected {expected}")
209            }
210            Self::MissingAttribute { entity, attribute } => {
211                write!(f, "entity {entity} has no `{attribute}` slot")
212            }
213            Self::InvalidValue {
214                entity,
215                attribute,
216                expected,
217            } => {
218                write!(
219                    f,
220                    "entity {entity}.{attribute} is invalid; expected {expected}"
221                )
222            }
223            Self::InvalidEnumeration {
224                entity,
225                attribute,
226                value,
227            } => match entity {
228                Some(entity) => write!(
229                    f,
230                    "entity {entity}.{attribute} has undeclared enumeration `{value}`"
231                ),
232                None => write!(
233                    f,
234                    "resource draft.{attribute} has undeclared enumeration `{value}`"
235                ),
236            },
237            Self::DanglingReference {
238                entity,
239                attribute,
240                target,
241            } => {
242                write!(f, "entity {entity}.{attribute} refers to missing {target}")
243            }
244            Self::WrongReferenceType {
245                entity,
246                attribute,
247                target,
248                expected,
249                actual,
250            } => write!(
251                f,
252                "entity {entity}.{attribute} refers to {target} ({actual}), expected {expected}"
253            ),
254            Self::InvalidCardinality {
255                entity,
256                attribute,
257                minimum,
258                actual,
259            } => write!(
260                f,
261                "entity {entity}.{attribute} has {actual} items; minimum is {minimum}"
262            ),
263            Self::DuplicateReference {
264                entity,
265                attribute,
266                target,
267            } => write!(f, "entity {entity}.{attribute} repeats reference {target}"),
268            Self::SemanticViolation { rule, .. } => {
269                write!(f, "resource semantic rule `{rule}` failed")
270            }
271            Self::Cycle { at } => write!(f, "resource composition cycle revisits {at}"),
272            Self::BudgetExceeded {
273                max_depth,
274                max_nodes,
275            } => write!(
276                f,
277                "resource traversal exceeded depth {max_depth} or node budget {max_nodes}"
278            ),
279            Self::InvalidDraft {
280                entity_type,
281                attribute,
282                expected,
283            } => write!(
284                f,
285                "draft {entity_type}.{attribute} is invalid; expected {expected}"
286            ),
287            Self::InvalidGlobalId => {
288                f.write_str("GlobalId is not a valid 22-character compressed IFC GUID")
289            }
290            Self::TransactionConflict { expected, actual } => write!(
291                f,
292                "resource transaction revision conflict: expected {expected}, actual {actual}"
293            ),
294        }
295    }
296}
297
298impl std::error::Error for ResourceError {}