jmap_types/
error.rs

1//! RFC 8620 §3.6 JMAP method-level error type ([`JmapError`]).
2
3use crate::Id;
4use serde::{Deserialize, Serialize};
5use thiserror::Error;
6
7/// JMAP method-level error, serializable for inclusion in `methodResponses`.
8///
9/// See RFC 8620 §3.6.2 for the standard error type strings.
10/// The JSON key is `"type"` (not `"error_type"`) per RFC 8620.
11#[derive(Debug, Clone, PartialEq, Eq, Error, Serialize, Deserialize)]
12#[error("{error_type}")]
13#[non_exhaustive]
14pub struct JmapError {
15    /// Error type string per RFC 8620 §3.6.2.
16    #[serde(rename = "type")]
17    pub error_type: String,
18    /// Human-readable description. Omitted from JSON when `None`.
19    #[serde(skip_serializing_if = "Option::is_none")]
20    pub description: Option<String>,
21    /// The id of the existing record. Only set for `"alreadyExists"` (RFC 8620 §5.4 MUST).
22    #[serde(rename = "existingId", skip_serializing_if = "Option::is_none")]
23    pub existing_id: Option<Id>,
24    /// Maximum `maxChanges` value the server will accept. Only set for `"tooManyChanges"` (RFC 8620 §9.6.1 MUST).
25    #[serde(skip_serializing_if = "Option::is_none")]
26    pub limit: Option<u64>,
27}
28
29impl JmapError {
30    /// RFC 8620 §3.6.2 — "invalidArguments"
31    pub fn invalid_arguments(desc: impl Into<String>) -> Self {
32        Self {
33            error_type: "invalidArguments".into(),
34            description: Some(desc.into()),
35            existing_id: None,
36            limit: None,
37        }
38    }
39
40    /// RFC 8620 §3.6.2 — "forbidden"
41    pub fn forbidden() -> Self {
42        Self {
43            error_type: "forbidden".into(),
44            description: None,
45            existing_id: None,
46            limit: None,
47        }
48    }
49
50    /// RFC 8620 §5.3 — "notFound"
51    pub fn not_found() -> Self {
52        Self {
53            error_type: "notFound".into(),
54            description: None,
55            existing_id: None,
56            limit: None,
57        }
58    }
59
60    /// RFC 8620 §5.1 — "accountNotFound"
61    pub fn account_not_found() -> Self {
62        Self {
63            error_type: "accountNotFound".into(),
64            description: None,
65            existing_id: None,
66            limit: None,
67        }
68    }
69
70    /// RFC 8620 §5.1 — "accountNotSupportedByMethod"
71    pub fn account_not_supported_by_method() -> Self {
72        Self {
73            error_type: "accountNotSupportedByMethod".into(),
74            description: None,
75            existing_id: None,
76            limit: None,
77        }
78    }
79
80    /// RFC 8620 §5.1 — "accountReadOnly"
81    pub fn account_read_only() -> Self {
82        Self {
83            error_type: "accountReadOnly".into(),
84            description: None,
85            existing_id: None,
86            limit: None,
87        }
88    }
89
90    /// RFC 8620 §3.6.2 — "serverUnavailable"
91    pub fn server_unavailable() -> Self {
92        Self {
93            error_type: "serverUnavailable".into(),
94            description: None,
95            existing_id: None,
96            limit: None,
97        }
98    }
99
100    /// RFC 8620 §3.6.2 — "serverFail"
101    pub fn server_fail(desc: impl Into<String>) -> Self {
102        Self {
103            error_type: "serverFail".into(),
104            description: Some(desc.into()),
105            existing_id: None,
106            limit: None,
107        }
108    }
109
110    /// RFC 8620 §3.6.2 — "serverPartialFail"
111    pub fn server_partial_fail() -> Self {
112        Self {
113            error_type: "serverPartialFail".into(),
114            description: None,
115            existing_id: None,
116            limit: None,
117        }
118    }
119
120    /// RFC 8620 §3.6.2 — "unknownMethod"
121    pub fn unknown_method() -> Self {
122        Self {
123            error_type: "unknownMethod".into(),
124            description: None,
125            existing_id: None,
126            limit: None,
127        }
128    }
129
130    /// RFC 8620 §3.6.2 — "invalidResultReference"
131    pub fn invalid_result_reference() -> Self {
132        Self {
133            error_type: "invalidResultReference".into(),
134            description: None,
135            existing_id: None,
136            limit: None,
137        }
138    }
139
140    /// RFC 8620 §5.2 and §5.6 — "cannotCalculateChanges"
141    pub fn cannot_calculate_changes() -> Self {
142        Self {
143            error_type: "cannotCalculateChanges".into(),
144            description: None,
145            existing_id: None,
146            limit: None,
147        }
148    }
149
150    /// RFC 8620 §5.3 — "stateMismatch"
151    pub fn state_mismatch() -> Self {
152        Self {
153            error_type: "stateMismatch".into(),
154            description: None,
155            existing_id: None,
156            limit: None,
157        }
158    }
159
160    /// RFC 8620 §5.3 — "tooLarge"
161    pub fn too_large() -> Self {
162        Self {
163            error_type: "tooLarge".into(),
164            description: None,
165            existing_id: None,
166            limit: None,
167        }
168    }
169
170    /// RFC 8620 §5.1 and §5.3 — "requestTooLarge"
171    pub fn request_too_large() -> Self {
172        Self {
173            error_type: "requestTooLarge".into(),
174            description: None,
175            existing_id: None,
176            limit: None,
177        }
178    }
179
180    /// RFC 8620 §5.3 — "overQuota"
181    pub fn over_quota() -> Self {
182        Self {
183            error_type: "overQuota".into(),
184            description: None,
185            existing_id: None,
186            limit: None,
187        }
188    }
189
190    /// RFC 8620 §5.3 — "rateLimit"
191    pub fn rate_limit() -> Self {
192        Self {
193            error_type: "rateLimit".into(),
194            description: None,
195            existing_id: None,
196            limit: None,
197        }
198    }
199
200    /// RFC 8620 §5.3 — "invalidPatch"
201    pub fn invalid_patch() -> Self {
202        Self {
203            error_type: "invalidPatch".into(),
204            description: None,
205            existing_id: None,
206            limit: None,
207        }
208    }
209
210    /// RFC 8620 §5.3 — "willDestroy"
211    pub fn will_destroy() -> Self {
212        Self {
213            error_type: "willDestroy".into(),
214            description: None,
215            existing_id: None,
216            limit: None,
217        }
218    }
219
220    /// RFC 8620 §5.3 — "invalidProperties"
221    pub fn invalid_properties() -> Self {
222        Self {
223            error_type: "invalidProperties".into(),
224            description: None,
225            existing_id: None,
226            limit: None,
227        }
228    }
229
230    /// RFC 8620 §5.3 — "singleton"
231    pub fn singleton() -> Self {
232        Self {
233            error_type: "singleton".into(),
234            description: None,
235            existing_id: None,
236            limit: None,
237        }
238    }
239
240    /// RFC 8620 §5.5 — "unsupportedFilter"
241    pub fn unsupported_filter() -> Self {
242        Self {
243            error_type: "unsupportedFilter".into(),
244            description: None,
245            existing_id: None,
246            limit: None,
247        }
248    }
249
250    /// RFC 8620 §5.5 — "anchorNotFound"
251    pub fn anchor_not_found() -> Self {
252        Self {
253            error_type: "anchorNotFound".into(),
254            description: None,
255            existing_id: None,
256            limit: None,
257        }
258    }
259
260    /// RFC 8620 §5.4 — "alreadyExists"
261    ///
262    /// `existing_id` is the id of the record that already exists in the target account.
263    /// Per RFC 8620 §5.4, this field MUST be present on the SetError object.
264    pub fn already_exists(existing_id: Id) -> Self {
265        Self {
266            error_type: "alreadyExists".into(),
267            description: None,
268            existing_id: Some(existing_id),
269            limit: None,
270        }
271    }
272
273    /// RFC 8620 §5.4 — "fromAccountNotFound"
274    pub fn from_account_not_found() -> Self {
275        Self {
276            error_type: "fromAccountNotFound".into(),
277            description: None,
278            existing_id: None,
279            limit: None,
280        }
281    }
282
283    /// RFC 8620 §5.4 — "fromAccountNotSupportedByMethod"
284    pub fn from_account_not_supported_by_method() -> Self {
285        Self {
286            error_type: "fromAccountNotSupportedByMethod".into(),
287            description: None,
288            existing_id: None,
289            limit: None,
290        }
291    }
292
293    /// RFC 8620 §5.5 — "unsupportedSort"
294    pub fn unsupported_sort() -> Self {
295        Self {
296            error_type: "unsupportedSort".into(),
297            description: None,
298            existing_id: None,
299            limit: None,
300        }
301    }
302
303    /// RFC 8620 §5.6 — "tooManyChanges"
304    pub fn too_many_changes() -> Self {
305        Self {
306            error_type: "tooManyChanges".into(),
307            description: None,
308            existing_id: None,
309            limit: None,
310        }
311    }
312
313    /// Returns a `tooManyChanges` error with the server's limit included.
314    ///
315    /// Per RFC 8620 §9.6.1, the `limit` field MUST be present so the client
316    /// knows the maximum `maxChanges` value to use on retry.
317    pub fn too_many_changes_with_limit(limit: u64) -> Self {
318        Self {
319            error_type: "tooManyChanges".into(),
320            description: None,
321            existing_id: None,
322            limit: Some(limit),
323        }
324    }
325
326    /// RFC 8620 §3.6.1 — "notJSON" (request-level error)
327    ///
328    /// The request body was not valid JSON or did not have `application/json` content type.
329    pub fn not_json() -> Self {
330        Self {
331            error_type: "notJSON".into(),
332            description: None,
333            existing_id: None,
334            limit: None,
335        }
336    }
337
338    /// RFC 8620 §3.6.1 — "notRequest" (request-level error)
339    ///
340    /// The request parsed as JSON but did not match the JMAP Request object shape.
341    pub fn not_request() -> Self {
342        Self {
343            error_type: "notRequest".into(),
344            description: None,
345            existing_id: None,
346            limit: None,
347        }
348    }
349
350    /// RFC 8620 §3.6.1 — "limit" (request-level error)
351    ///
352    /// The request was rejected because it would exceed a capability limit such as
353    /// `maxCallsInRequest` or `maxSizeRequest`.
354    ///
355    /// `limit_name` is the name of the exceeded limit (e.g. `"maxCallsInRequest"`).
356    /// The HTTP layer MUST forward this name as the `"limit"` property in the
357    /// RFC 7807 Problem Details response body.  The name is stored in
358    /// [`description`][JmapError::description] for that purpose.
359    ///
360    /// **Invariant**: always construct limit errors with this function, never by
361    /// setting `error_type = "limit"` and `description` manually.  The HTTP
362    /// response layer (`jmap-server::RequestError`) reads `description` to
363    /// populate the RFC-required `"limit"` field; a missing description produces
364    /// an invalid response.
365    pub fn limit(limit_name: impl Into<String>) -> Self {
366        Self {
367            error_type: "limit".into(),
368            description: Some(limit_name.into()),
369            existing_id: None,
370            limit: None,
371        }
372    }
373
374    /// RFC 8620 §3.6.1 — "unknownCapability" (request-level error)
375    ///
376    /// The request used a capability URI not recognized by this server.
377    ///
378    /// Always prefer [`unknown_capability_with_detail`][Self::unknown_capability_with_detail],
379    /// which includes the failing URI so clients can act on it.
380    #[deprecated(
381        note = "always use unknown_capability_with_detail to include the URI in the error"
382    )]
383    pub fn unknown_capability() -> Self {
384        Self {
385            error_type: "unknownCapability".into(),
386            description: None,
387            existing_id: None,
388            limit: None,
389        }
390    }
391
392    /// "unknownCapability" with the failing URI surfaced to the client.
393    ///
394    /// Always use this instead of [`unknown_capability()`][Self::unknown_capability].
395    ///
396    /// The URI is stored in [`description`][JmapError::description].  The HTTP layer
397    /// (`jmap-server::RequestError`) reads `description` to populate the `"detail"` field
398    /// in the RFC 7807 problem-details response body — the same mechanism used by
399    /// [`limit()`][Self::limit] for its limit-name payload.
400    ///
401    /// **Invariant**: always construct unknownCapability errors that carry a URI with this
402    /// function, never by setting `description` manually.  A missing or incorrect description
403    /// means the client never learns which capability it requested that the server does not
404    /// support.
405    pub fn unknown_capability_with_detail(uri: impl Into<String>) -> Self {
406        Self {
407            error_type: "unknownCapability".into(),
408            description: Some(uri.into()),
409            existing_id: None,
410            limit: None,
411        }
412    }
413
414    /// Create a `JmapError` with a custom or extension error type string.
415    ///
416    /// Use this when propagating a server error whose `type` value is not one of
417    /// the RFC 8620 standard types, or in tests that need to construct an
418    /// arbitrary `JmapError` value.
419    pub fn custom(error_type: impl Into<String>) -> Self {
420        Self {
421            error_type: error_type.into(),
422            description: None,
423            existing_id: None,
424            limit: None,
425        }
426    }
427}
428
429#[cfg(test)]
430mod tests {
431    use super::*;
432
433    // Independent oracle: RFC 8620 §3.6.2 and §5.x specify these exact type strings.
434
435    #[test]
436    fn invalid_arguments_serializes_type_and_description() {
437        let e = JmapError::invalid_arguments("ids field is required");
438        let json = serde_json::to_string(&e).unwrap();
439        assert!(
440            json.contains("\"type\""),
441            "must use 'type' key per RFC 8620"
442        );
443        assert!(json.contains("\"invalidArguments\""));
444        assert!(json.contains("\"description\""));
445        assert!(json.contains("ids field is required"));
446    }
447
448    #[test]
449    fn forbidden_omits_description() {
450        let e = JmapError::forbidden();
451        let json = serde_json::to_string(&e).unwrap();
452        assert!(json.contains("\"forbidden\""));
453        assert!(
454            !json.contains("\"description\""),
455            "None description must be omitted"
456        );
457    }
458
459    #[test]
460    fn not_found_type_string() {
461        let e = JmapError::not_found();
462        let json = serde_json::to_string(&e).unwrap();
463        assert!(json.contains("\"notFound\""));
464        assert!(!json.contains("\"description\""));
465    }
466
467    #[test]
468    fn account_not_found_type_string() {
469        let e = JmapError::account_not_found();
470        let json = serde_json::to_string(&e).unwrap();
471        assert!(json.contains("\"accountNotFound\""));
472        assert!(!json.contains("\"description\""));
473    }
474
475    #[test]
476    fn account_not_supported_by_method_type_string() {
477        let e = JmapError::account_not_supported_by_method();
478        let json = serde_json::to_string(&e).unwrap();
479        assert!(json.contains("\"accountNotSupportedByMethod\""));
480    }
481
482    #[test]
483    fn account_read_only_type_string() {
484        let e = JmapError::account_read_only();
485        let json = serde_json::to_string(&e).unwrap();
486        assert!(json.contains("\"accountReadOnly\""));
487    }
488
489    #[test]
490    fn server_unavailable_type_string() {
491        let e = JmapError::server_unavailable();
492        let json = serde_json::to_string(&e).unwrap();
493        assert!(json.contains("\"serverUnavailable\""));
494    }
495
496    #[test]
497    fn server_fail_includes_description() {
498        let e = JmapError::server_fail("internal error");
499        let json = serde_json::to_string(&e).unwrap();
500        assert!(json.contains("\"serverFail\""));
501        assert!(json.contains("internal error"));
502    }
503
504    #[test]
505    fn server_partial_fail_type_string() {
506        let e = JmapError::server_partial_fail();
507        let json = serde_json::to_string(&e).unwrap();
508        assert!(json.contains("\"serverPartialFail\""));
509    }
510
511    #[test]
512    fn unknown_method_type_string() {
513        let e = JmapError::unknown_method();
514        let json = serde_json::to_string(&e).unwrap();
515        assert!(json.contains("\"unknownMethod\""));
516    }
517
518    #[test]
519    fn invalid_result_reference_type_string() {
520        let e = JmapError::invalid_result_reference();
521        let json = serde_json::to_string(&e).unwrap();
522        assert!(json.contains("\"invalidResultReference\""));
523    }
524
525    #[test]
526    fn cannot_calculate_changes_type_string() {
527        let e = JmapError::cannot_calculate_changes();
528        let json = serde_json::to_string(&e).unwrap();
529        assert!(json.contains("\"cannotCalculateChanges\""));
530    }
531
532    #[test]
533    fn state_mismatch_type_string() {
534        let e = JmapError::state_mismatch();
535        let json = serde_json::to_string(&e).unwrap();
536        assert!(json.contains("\"stateMismatch\""));
537    }
538
539    #[test]
540    fn too_large_type_string() {
541        let e = JmapError::too_large();
542        let json = serde_json::to_string(&e).unwrap();
543        assert!(json.contains("\"tooLarge\""));
544    }
545
546    #[test]
547    fn request_too_large_type_string() {
548        let e = JmapError::request_too_large();
549        let json = serde_json::to_string(&e).unwrap();
550        assert!(json.contains("\"requestTooLarge\""));
551        assert!(!json.contains("\"description\""));
552    }
553
554    #[test]
555    fn over_quota_type_string() {
556        let e = JmapError::over_quota();
557        let json = serde_json::to_string(&e).unwrap();
558        assert!(json.contains("\"overQuota\""));
559    }
560
561    #[test]
562    fn rate_limit_type_string() {
563        let e = JmapError::rate_limit();
564        let json = serde_json::to_string(&e).unwrap();
565        assert!(json.contains("\"rateLimit\""));
566    }
567
568    #[test]
569    fn invalid_patch_type_string() {
570        let e = JmapError::invalid_patch();
571        let json = serde_json::to_string(&e).unwrap();
572        assert!(json.contains("\"invalidPatch\""));
573    }
574
575    #[test]
576    fn will_destroy_type_string() {
577        let e = JmapError::will_destroy();
578        let json = serde_json::to_string(&e).unwrap();
579        assert!(json.contains("\"willDestroy\""));
580    }
581
582    #[test]
583    fn invalid_properties_type_string() {
584        let e = JmapError::invalid_properties();
585        let json = serde_json::to_string(&e).unwrap();
586        assert!(json.contains("\"invalidProperties\""));
587    }
588
589    #[test]
590    fn singleton_type_string() {
591        let e = JmapError::singleton();
592        let json = serde_json::to_string(&e).unwrap();
593        assert!(json.contains("\"singleton\""));
594    }
595
596    #[test]
597    fn unsupported_filter_type_string() {
598        let e = JmapError::unsupported_filter();
599        let json = serde_json::to_string(&e).unwrap();
600        assert!(json.contains("\"unsupportedFilter\""));
601    }
602
603    #[test]
604    fn anchor_not_found_type_string() {
605        let e = JmapError::anchor_not_found();
606        let json = serde_json::to_string(&e).unwrap();
607        assert!(json.contains("\"anchorNotFound\""));
608    }
609
610    // Oracle: RFC 8620 §5.4 — alreadyExists MUST include existingId of type Id.
611    #[test]
612    fn already_exists_includes_existing_id() {
613        let e = JmapError::already_exists(Id::from("abc123"));
614        let json = serde_json::to_string(&e).unwrap();
615        assert!(json.contains("\"alreadyExists\""));
616        assert!(json.contains("\"existingId\""));
617        assert!(json.contains("\"abc123\""));
618        assert!(!json.contains("\"description\""));
619    }
620
621    #[test]
622    fn from_account_not_found_type_string() {
623        let e = JmapError::from_account_not_found();
624        let json = serde_json::to_string(&e).unwrap();
625        assert!(json.contains("\"fromAccountNotFound\""));
626        assert!(!json.contains("\"description\""));
627    }
628
629    #[test]
630    fn from_account_not_supported_by_method_type_string() {
631        let e = JmapError::from_account_not_supported_by_method();
632        let json = serde_json::to_string(&e).unwrap();
633        assert!(json.contains("\"fromAccountNotSupportedByMethod\""));
634        assert!(!json.contains("\"description\""));
635    }
636
637    #[test]
638    fn unsupported_sort_type_string() {
639        let e = JmapError::unsupported_sort();
640        let json = serde_json::to_string(&e).unwrap();
641        assert!(json.contains("\"unsupportedSort\""));
642        assert!(!json.contains("\"description\""));
643    }
644
645    #[test]
646    fn too_many_changes_type_string() {
647        let e = JmapError::too_many_changes();
648        let json = serde_json::to_string(&e).unwrap();
649        assert!(json.contains("\"tooManyChanges\""));
650        assert!(!json.contains("\"description\""));
651    }
652
653    #[test]
654    fn too_many_changes_with_limit_serializes_limit_field() {
655        let err = JmapError::too_many_changes_with_limit(100);
656        let v = serde_json::to_value(&err).unwrap();
657        assert_eq!(v["type"], "tooManyChanges");
658        assert_eq!(v["limit"], 100u64);
659        assert!(v.get("description").is_none());
660    }
661
662    #[test]
663    fn too_many_changes_without_limit_has_no_limit_field() {
664        let err = JmapError::too_many_changes();
665        let v = serde_json::to_value(&err).unwrap();
666        assert_eq!(v["type"], "tooManyChanges");
667        assert!(v.get("limit").is_none());
668    }
669
670    #[test]
671    fn not_json_type_string() {
672        let e = JmapError::not_json();
673        let json = serde_json::to_string(&e).unwrap();
674        assert!(json.contains("\"notJSON\""));
675        assert!(!json.contains("\"description\""));
676    }
677
678    #[test]
679    fn not_request_type_string() {
680        let e = JmapError::not_request();
681        let json = serde_json::to_string(&e).unwrap();
682        assert!(json.contains("\"notRequest\""));
683        assert!(!json.contains("\"description\""));
684    }
685
686    #[test]
687    fn limit_includes_limit_name_in_description() {
688        // Oracle: the limit name is stored in description so the HTTP layer
689        // can forward it as the "limit" field in RFC 7807 Problem Details.
690        let e = JmapError::limit("maxCallsInRequest");
691        let json = serde_json::to_string(&e).unwrap();
692        assert!(json.contains("\"limit\""));
693        assert!(json.contains("\"maxCallsInRequest\""));
694    }
695
696    #[allow(deprecated)]
697    #[test]
698    fn unknown_capability_type_string() {
699        let e = JmapError::unknown_capability();
700        let json = serde_json::to_string(&e).unwrap();
701        assert!(json.contains("\"unknownCapability\""));
702        assert!(!json.contains("\"description\""));
703    }
704
705    // Oracle: RFC 8620 §3.6.1 — unknownCapability with detail includes the URI.
706    #[test]
707    fn unknown_capability_with_detail_includes_uri() {
708        let e = JmapError::unknown_capability_with_detail("urn:example:unknown");
709        assert_eq!(e.error_type, "unknownCapability");
710        assert_eq!(e.description.as_deref(), Some("urn:example:unknown"));
711    }
712
713    #[test]
714    fn custom_error_type_round_trips() {
715        let e = JmapError::custom("urn:example:customError");
716        assert_eq!(e.error_type, "urn:example:customError");
717        let json = serde_json::to_string(&e).unwrap();
718        assert!(json.contains("\"urn:example:customError\""));
719        let restored: JmapError = serde_json::from_str(&json).unwrap();
720        assert_eq!(restored.error_type, "urn:example:customError");
721    }
722
723    #[test]
724    fn round_trip_deserialize() {
725        // Verify the "type" rename survives a JSON round-trip.
726        let original = JmapError::invalid_arguments("test");
727        let json = serde_json::to_string(&original).unwrap();
728        let restored: JmapError = serde_json::from_str(&json).unwrap();
729        assert_eq!(restored.error_type, "invalidArguments");
730        assert_eq!(restored.description.as_deref(), Some("test"));
731    }
732
733    // Oracle: RFC 8620 §3.4.1 fixture — methodResponses[3] is ["error", {"type":"unknownMethod"}, "c3"]
734    #[test]
735    fn fixture_response_contains_unknown_method_error() {
736        let raw = include_str!("../tests/fixtures/rfc8620-response.json");
737        let v: serde_json::Value = serde_json::from_str(raw).expect("parse fixture");
738        let inv = &v["methodResponses"][3];
739        assert_eq!(inv[0], "error");
740        assert_eq!(inv[1]["type"], "unknownMethod");
741        assert_eq!(inv[2], "c3");
742    }
743}
jmap_types/error.rs

jmap_types/
error.rs
