ferrex-model 0.1.2-alpha

Shared data models for the Ferrex media platform
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
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

use std::fmt;

/// Errors produced when constructing strongly-typed subject keys.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SubjectKeyError {
    Empty,
}

impl fmt::Display for SubjectKeyError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            SubjectKeyError::Empty => write!(f, "subject key cannot be empty"),
        }
    }
}

/// Normalized filesystem path key used for scan orchestration and progress
/// tracking (e.g. `folder_path_norm`, `path_norm`).
///
/// This is intentionally a thin wrapper around `String` so:
/// - call sites can't accidentally pass an arbitrary string without opting in
/// - serialization remains compact and ergonomic
#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(transparent))]
#[cfg_attr(
    feature = "rkyv",
    derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize)
)]
#[cfg_attr(feature = "rkyv", rkyv(derive(Debug, PartialEq, Eq, Hash)))]
pub struct NormalizedPathKey(String);

impl NormalizedPathKey {
    pub fn new(value: impl Into<String>) -> Result<Self, SubjectKeyError> {
        let value = value.into();
        if value.is_empty() {
            return Err(SubjectKeyError::Empty);
        }
        Ok(Self(value))
    }

    pub fn as_str(&self) -> &str {
        &self.0
    }

    pub fn into_inner(self) -> String {
        self.0
    }
}

impl fmt::Display for NormalizedPathKey {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(&self.0)
    }
}

/// Opaque stable identifier that isn't necessarily a filesystem path.
#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(transparent))]
#[cfg_attr(
    feature = "rkyv",
    derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize)
)]
#[cfg_attr(feature = "rkyv", rkyv(derive(Debug, PartialEq, Eq, Hash)))]
pub struct OpaqueSubjectKey(String);

impl OpaqueSubjectKey {
    pub fn new(value: impl Into<String>) -> Result<Self, SubjectKeyError> {
        let value = value.into();
        if value.is_empty() {
            return Err(SubjectKeyError::Empty);
        }
        Ok(Self(value))
    }

    pub fn as_str(&self) -> &str {
        &self.0
    }

    pub fn into_inner(self) -> String {
        self.0
    }
}

impl fmt::Display for OpaqueSubjectKey {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(&self.0)
    }
}

/// Typed identifier for "what this event/job is about".
///
/// This replaces stringly-typed `path_key` usage while keeping the payload
/// lightweight and serializable across process boundaries.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(
    feature = "serde",
    serde(tag = "type", content = "value", rename_all = "snake_case")
)]
#[cfg_attr(
    feature = "rkyv",
    derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize)
)]
#[cfg_attr(feature = "rkyv", rkyv(derive(Debug, PartialEq, Eq, Hash)))]
pub enum SubjectKey {
    /// A normalized filesystem path key.
    Path(NormalizedPathKey),
    /// A stable identifier in a different keyspace (e.g. fingerprint hash,
    /// remote provider path, synthetic image key).
    Opaque(OpaqueSubjectKey),
}

impl SubjectKey {
    pub fn path(value: impl Into<String>) -> Result<Self, SubjectKeyError> {
        Ok(Self::Path(NormalizedPathKey::new(value)?))
    }

    pub fn opaque(value: impl Into<String>) -> Result<Self, SubjectKeyError> {
        Ok(Self::Opaque(OpaqueSubjectKey::new(value)?))
    }

    pub fn as_str(&self) -> &str {
        match self {
            SubjectKey::Path(value) => value.as_str(),
            SubjectKey::Opaque(value) => value.as_str(),
        }
    }
}

impl fmt::Display for SubjectKey {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            SubjectKey::Path(value) => write!(f, "path:{value}"),
            SubjectKey::Opaque(value) => write!(f, "opaque:{value}"),
        }
    }
}