rskit-version 0.2.0-alpha.1

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
76

//! 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"));
    }
}