restful 0.2.0

REST API helpers: validated Axum extractors, response envelopes, pagination, ordering, and field selection
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157

/// Errors that can occur during projection parsing and validation.
#[derive(Debug, serde::Serialize, thiserror::Error)]
pub enum ProjectionError {
    /// The input string was empty.
    #[error("field set must not be empty")]
    Empty,

    /// A token was not a recognized field name.
    #[error("unknown field '{field}'")]
    InvalidField {
        field: String,
        valid_fields: Vec<&'static str>,
    },

    /// Every available field of the named resource was excluded.
    #[error(
        "selection for '{}' excludes all {count} available fields",
        if namespace.is_empty() { "top-level" } else { namespace }
    )]
    AllExcluded { namespace: String, count: usize },

    /// The input was not clear about which fields to include or exclude.
    #[error(
        "selection for '{}' is ambiguous: unclear mix of inclusions and exclusions. \
         Use only inclusions, only exclusions, or '{}all' with exclusions.",
        if namespace.is_empty() { "top-level" } else { namespace },
        if namespace.is_empty() { String::new() } else { format!("{namespace}.") }
    )]
    AmbiguousSelection { namespace: String },

    /// The input combined the `all` keyword with explicit inclusions for the same resource.
    #[error(
        "selection for '{}' uses 'all' together with specific inclusions; \
         with 'all' you may only add exclusions",
        if namespace.is_empty() { "top-level" } else { namespace }
    )]
    AllWithInclusions { namespace: String },

    /// The input did not include any fields for the top-level resource.
    #[error("top-level resource selection is required")]
    TopLevelMissing,
}

// ––– ProjectionErrors –––

/// A collection of [`ProjectionError`]s.
#[derive(Debug, serde::Serialize, thiserror::Error)]
#[error("{}", .0.iter().map(ToString::to_string).collect::<Vec<_>>().join("; "))]
pub struct ProjectionErrors(pub Vec<ProjectionError>);

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn empty_message() {
        assert_eq!(
            ProjectionError::Empty.to_string(),
            "field set must not be empty",
        );
    }

    #[test]
    fn invalid_field_message_uses_qualified_name() {
        let e = ProjectionError::InvalidField {
            field: "address.foo".to_string(),
            valid_fields: vec!["id", "name"],
        };
        assert_eq!(e.to_string(), "unknown field 'address.foo'");
    }

    #[test]
    fn all_excluded_top_level_message_uses_top_level_label() {
        let e = ProjectionError::AllExcluded {
            namespace: String::new(),
            count: 5,
        };
        let msg = e.to_string();
        assert!(msg.contains("'top-level'"), "got: {msg}");
        assert!(msg.contains("5"), "got: {msg}");
    }

    #[test]
    fn all_excluded_nested_message_uses_namespace() {
        let e = ProjectionError::AllExcluded {
            namespace: "country".into(),
            count: 3,
        };
        let msg = e.to_string();
        assert!(msg.contains("'country'"), "got: {msg}");
    }

    #[test]
    fn ambiguous_top_level_message_qualifies_all_unprefixed() {
        let e = ProjectionError::AmbiguousSelection {
            namespace: String::new(),
        };
        let msg = e.to_string();
        assert!(msg.contains("'top-level'"), "got: {msg}");
        assert!(msg.contains("inclusions"), "got: {msg}");
        assert!(msg.contains("exclusions"), "got: {msg}");
        // The hint should reference plain 'all' (no namespace prefix).
        assert!(
            msg.contains("''all''") || msg.contains("'all'"),
            "got: {msg}"
        );
    }

    #[test]
    fn ambiguous_nested_message_qualifies_all_with_namespace_prefix() {
        let e = ProjectionError::AmbiguousSelection {
            namespace: "country".into(),
        };
        let msg = e.to_string();
        assert!(msg.contains("'country'"), "got: {msg}");
        assert!(msg.contains("'country.all'"), "got: {msg}");
    }

    #[test]
    fn all_with_inclusions_message_mentions_all_and_namespace() {
        let e = ProjectionError::AllWithInclusions {
            namespace: "country".into(),
        };
        let msg = e.to_string();
        assert!(msg.contains("'country'"), "got: {msg}");
        assert!(msg.contains("'all'"), "got: {msg}");
        assert!(msg.contains("only add exclusions"), "got: {msg}");
    }

    #[test]
    fn all_with_inclusions_top_level_uses_top_level_label() {
        let e = ProjectionError::AllWithInclusions {
            namespace: String::new(),
        };
        assert!(e.to_string().contains("'top-level'"));
    }

    #[test]
    fn top_level_missing_message() {
        assert_eq!(
            ProjectionError::TopLevelMissing.to_string(),
            "top-level resource selection is required",
        );
    }

    #[test]
    fn projection_errors_collection_joins_with_semicolon() {
        let errs = ProjectionErrors(vec![
            ProjectionError::Empty,
            ProjectionError::TopLevelMissing,
        ]);
        let s = errs.to_string();
        assert!(s.contains("must not be empty"), "got: {s}");
        assert!(s.contains("top-level resource selection"), "got: {s}");
        assert!(s.contains("; "), "got: {s}");
    }
}