rskit-version 0.2.0-alpha.3

Build-time version and git metadata for rskit
Documentation 
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

//! Schema-version compatibility gating.
//!
//! A small,
//! general-purpose helper for versioned documents (config files, manifests, on-disk formats) that declare a `schema` field
//! and must reject any version the current code does not understand.
//! This is distinct from [`crate::semver`] (which parses semantic-version strings):
//! a schema version is typically a small monotonic integer,
//! so the gate is generic over any `Copy + Eq + Display` value.

use std::fmt::Display;

use rskit_errors::{AppError, AppResult};

/// Return the configured schema version, or the supported default when absent,
/// rejecting any value the current code does not support.
///
/// `field` names the schema field for error reporting.
/// A `None` `configured` value defaults to `supported`.
/// A `configured` value that differs from `supported` is a typed [`AppError::invalid_input`] —
/// the caller cannot safely interpret a document written for a different schema version.
///
/// # Errors
///
/// Returns [`AppError::invalid_input`] when `configured` is present and not equal to `supported`.
///
/// # Examples
///
/// ```
/// use rskit_version::schema::supported_schema;
///
/// // Absent value defaults to the supported version.
/// assert_eq!(supported_schema("schema", None, 1).unwrap(), 1);
/// // A matching value is accepted.
/// assert_eq!(supported_schema("schema", Some(1), 1).unwrap(), 1);
/// // A mismatching value is rejected.
/// assert!(supported_schema("schema", Some(2), 1).is_err());
/// ```
pub fn supported_schema<T>(field: &str, configured: Option<T>, supported: T) -> AppResult<T>
where
    T: Copy + Eq + Display,
{
    let schema = configured.unwrap_or(supported);
    if schema != supported {
        return Err(AppError::invalid_input(
            field,
            format!("unsupported schema {schema}; supported schema is {supported}"),
        ));
    }
    Ok(schema)
}

#[cfg(test)]
mod tests {
    use rskit_errors::ErrorCode;

    use super::supported_schema;

    #[test]
    fn defaults_absent_value() {
        assert_eq!(supported_schema("schema", None, 1).unwrap(), 1);
    }

    #[test]
    fn accepts_supported_value() {
        assert_eq!(supported_schema("schema", Some(1), 1).unwrap(), 1);
    }

    #[test]
    fn rejects_unsupported_value() {
        let error = supported_schema("schema", Some(2), 1).unwrap_err();

        assert_eq!(error.code(), ErrorCode::InvalidInput);
        assert!(error.message().contains("unsupported schema 2"));
    }
}