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 {}