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
158
159

mod kind;
mod uri;

pub use self::{kind::*, uri::*};

use std::collections::HashMap;

use schemars::JsonSchema;
use serde::{de::DeserializeOwned, Deserialize, Serialize};
use time::OffsetDateTime;
use uuid::Uuid;

/// Common entity metadata.
///
/// This data is not generic, and is the same for all entity kinds.
#[derive(Serialize, Deserialize, JsonSchema, PartialEq, Eq, Clone, Debug)]
pub struct EntityMeta {
    /// Name of the entity.
    ///
    /// This is only unique within the scope of the entity.
    pub name: String,

    /// Long description.
    ///
    /// Should be either plain text or markdown.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,

    /// Labels are used to organize entities.
    /// They are a set of simple key/value pairs.
    #[serde(default)]
    #[serde(skip_serializing_if = "HashMap::is_empty")]
    pub labels: HashMap<String, String>,

    /// Annotations are used to attach arbitrary metadata to entities.
    /// They can contain arbitrary (json-encodable) data.
    #[serde(default)]
    #[serde(skip_serializing_if = "HashMap::is_empty")]
    pub annotations: HashMap<String, serde_json::Value>,

    #[serde(skip_serializing_if = "Option::is_none")]
    pub parent: Option<String>,
}

impl EntityMeta {
    pub fn new(name: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            description: None,
            labels: Default::default(),
            annotations: Default::default(),
            parent: None,
        }
    }
}

/// An entity with associated data.
#[derive(Serialize, Deserialize, JsonSchema, PartialEq, Eq, Clone, Debug)]
pub struct Entity<D, C = serde_json::Value> {
    /// Common entity metadata.
    pub meta: EntityMeta,
    /// Specification of the entity.
    pub spec: D,
    /// Inline child entity specs.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub children: Option<Vec<C>>,
}

impl<D, C> Entity<D, C>
where
    D: EntityDescriptorConst + serde::Serialize,
    C: serde::Serialize,
{
    /// Convert this type to yaml, injecting the kind into the output.
    // TODO: make this redundant with a custom Serialize impl!
    pub fn to_yaml(&self) -> Result<String, serde_yaml::Error> {
        let mut value = serde_yaml::to_value(self)?;
        value["kind"] = serde_yaml::Value::String(D::KIND.to_string());
        serde_yaml::to_string(&value)
    }
}

/// An entity with associated data, including state.
#[derive(Serialize, Deserialize, JsonSchema, PartialEq, Eq, Clone, Debug)]
pub struct FullEntity<D, S = (), C = serde_json::Value> {
    /// Common entity metadata.
    pub meta: EntityMeta,
    /// Specification of the entity.
    pub spec: D,
    /// Inline child entity specs.
    pub children: Option<Vec<C>>,
    pub state: Option<EntityState<S>>,
}

/// State of an entity.
///
/// Contains a `main` state, which will be managed by the owning service that
/// manages the entity.
///
/// Additional services may inject their own state, which will be found in
/// [`Self::components`].
#[derive(Serialize, Deserialize, JsonSchema, PartialEq, Eq, Clone, Debug)]
pub struct EntityState<S = ()> {
    /// Globally unique UUID.
    pub uid: Uuid,

    /// Version of the entity.
    /// All modifications to metadata or spec will increment this version.
    pub entity_version: u64,

    /// UUID of the parent entity.
    /// This is only set if the entity is a child of another entity.
    pub parent_uid: Option<Uuid>,

    /// Creation timestamp.
    #[serde(deserialize_with = "time::serde::timestamp::deserialize")]
    #[schemars(with = "u64")]
    pub created_at: OffsetDateTime,
    /// Last update timestamp.
    /// Will be set on each metadata or spec change, but not on state changes.
    #[serde(serialize_with = "time::serde::timestamp::serialize")]
    #[schemars(with = "u64")]
    pub updated_at: OffsetDateTime,

    /// The primary state of the entity, managed by the owning service.
    pub main: Option<EntityStateComponent<S>>,

    /// Additional entity states, managed by services other than the entity owners.
    pub components: HashMap<String, EntityStateComponent>,
}

/// Single component of an entities state.
#[derive(Serialize, Deserialize, JsonSchema, PartialEq, Eq, Clone, Debug)]
pub struct EntityStateComponent<T = serde_json::Value> {
    /// Version of this state.
    /// Will be incremented on each change.
    pub state_version: u64,
    /// Update timestamp.
    #[serde(with = "time::serde::timestamp")]
    #[schemars(with = "u64")]
    pub updated_at: OffsetDateTime,
    /// The actual state data.
    pub data: T,
}

/// A marker trait for entity types.
///
/// Should be implementes on the struct representing the entities spec.
pub trait EntityDescriptorConst {
    const NAMESPACE: &'static str;
    const NAME: &'static str;
    const VERSION: &'static str;
    const KIND: &'static str;

    /// Entity specification.
    type Spec: Serialize + DeserializeOwned + JsonSchema + Clone + PartialEq + Eq + std::fmt::Debug;
    /// The main entity state.
    type State: Serialize + DeserializeOwned + JsonSchema + Clone + PartialEq + Eq + std::fmt::Debug;
}