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
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
pub use k8s_openapi::apimachinery::pkg::apis::meta::v1::ObjectMeta;
use k8s_openapi::{
    api::core::v1::ObjectReference,
    apimachinery::pkg::apis::meta::v1::{ManagedFieldsEntry, OwnerReference, Time},
};

use std::{borrow::Cow, collections::BTreeMap};

pub use k8s_openapi::{ClusterResourceScope, NamespaceResourceScope, ResourceScope, SubResourceScope};

/// Indicates that a [`Resource`] is of an indeterminate dynamic scope.
pub struct DynamicResourceScope {}
impl ResourceScope for DynamicResourceScope {}

/// An accessor trait for a kubernetes Resource.
///
/// This is for a subset of Kubernetes type that do not end in `List`.
/// These types, using [`ObjectMeta`], SHOULD all have required properties:
/// - `.metadata`
/// - `.metadata.name`
///
/// And these optional properties:
/// - `.metadata.namespace`
/// - `.metadata.resource_version`
///
/// This avoids a bunch of the unnecessary unwrap mechanics for apps.
pub trait Resource {
    /// Type information for types that do not know their resource information at compile time.
    ///
    /// Types that know their metadata at compile time should select `DynamicType = ()`.
    /// Types that require some information at runtime should select `DynamicType`
    /// as type of this information.
    ///
    /// See [`DynamicObject`](crate::dynamic::DynamicObject) for a valid implementation of non-k8s-openapi resources.
    type DynamicType: Send + Sync + 'static;
    /// Type information for the api scope of the resource when known at compile time
    ///
    /// Types from k8s_openapi come with an explicit k8s_openapi::ResourceScope
    /// Dynamic types should select `Scope = DynamicResourceScope`
    type Scope;

    /// Returns kind of this object
    fn kind(dt: &Self::DynamicType) -> Cow<'_, str>;
    /// Returns group of this object
    fn group(dt: &Self::DynamicType) -> Cow<'_, str>;
    /// Returns version of this object
    fn version(dt: &Self::DynamicType) -> Cow<'_, str>;
    /// Returns apiVersion of this object
    fn api_version(dt: &Self::DynamicType) -> Cow<'_, str> {
        api_version_from_group_version(Self::group(dt), Self::version(dt))
    }
    /// Returns the plural name of the kind
    ///
    /// This is known as the resource in apimachinery, we rename it for disambiguation.
    fn plural(dt: &Self::DynamicType) -> Cow<'_, str>;

    /// Creates a url path for http requests for this resource
    fn url_path(dt: &Self::DynamicType, namespace: Option<&str>) -> String {
        let n = if let Some(ns) = namespace {
            format!("namespaces/{ns}/")
        } else {
            "".into()
        };
        let group = Self::group(dt);
        let api_version = Self::api_version(dt);
        let plural = Self::plural(dt);
        format!(
            "/{group}/{api_version}/{namespaces}{plural}",
            group = if group.is_empty() { "api" } else { "apis" },
            api_version = api_version,
            namespaces = n,
            plural = plural
        )
    }

    /// Metadata that all persisted resources must have
    fn meta(&self) -> &ObjectMeta;
    /// Metadata that all persisted resources must have
    fn meta_mut(&mut self) -> &mut ObjectMeta;

    /// Generates an object reference for the resource
    fn object_ref(&self, dt: &Self::DynamicType) -> ObjectReference {
        let meta = self.meta();
        ObjectReference {
            name: meta.name.clone(),
            namespace: meta.namespace.clone(),
            uid: meta.uid.clone(),
            api_version: Some(Self::api_version(dt).to_string()),
            kind: Some(Self::kind(dt).to_string()),
            ..Default::default()
        }
    }

    /// Generates a controller owner reference pointing to this resource
    ///
    /// Note: this returns an `Option`, but for objects populated from the apiserver,
    /// this Option can be safely unwrapped.
    ///
    /// ```
    /// use k8s_openapi::api::core::v1::ConfigMap;
    /// use k8s_openapi::api::core::v1::Pod;
    /// use k8s_openapi::apimachinery::pkg::apis::meta::v1::ObjectMeta;
    /// use kube_core::Resource;
    ///
    /// let p = Pod::default();
    /// let controller_ref = p.controller_owner_ref(&());
    /// let cm = ConfigMap {
    ///     metadata: ObjectMeta {
    ///         name: Some("pod-configmap".to_string()),
    ///         owner_references: Some(controller_ref.into_iter().collect()),
    ///         ..ObjectMeta::default()
    ///     },
    ///     ..Default::default()
    /// };
    /// ```
    fn controller_owner_ref(&self, dt: &Self::DynamicType) -> Option<OwnerReference> {
        Some(OwnerReference {
            controller: Some(true),
            ..self.owner_ref(dt)?
        })
    }

    /// Generates an owner reference pointing to this resource
    ///
    /// Note: this returns an `Option`, but for objects populated from the apiserver,
    /// this Option can be safely unwrapped.
    ///
    /// ```
    /// use k8s_openapi::api::core::v1::ConfigMap;
    /// use k8s_openapi::api::core::v1::Pod;
    /// use k8s_openapi::apimachinery::pkg::apis::meta::v1::ObjectMeta;
    /// use kube_core::Resource;
    ///
    /// let p = Pod::default();
    /// let owner_ref = p.owner_ref(&());
    /// let cm = ConfigMap {
    ///     metadata: ObjectMeta {
    ///         name: Some("pod-configmap".to_string()),
    ///         owner_references: Some(owner_ref.into_iter().collect()),
    ///         ..ObjectMeta::default()
    ///     },
    ///     ..Default::default()
    /// };
    /// ```
    fn owner_ref(&self, dt: &Self::DynamicType) -> Option<OwnerReference> {
        let meta = self.meta();
        Some(OwnerReference {
            api_version: Self::api_version(dt).to_string(),
            kind: Self::kind(dt).to_string(),
            name: meta.name.clone()?,
            uid: meta.uid.clone()?,
            ..OwnerReference::default()
        })
    }
}

/// Helper function that creates the `apiVersion` field from the group and version strings.
pub fn api_version_from_group_version<'a>(group: Cow<'a, str>, version: Cow<'a, str>) -> Cow<'a, str> {
    if group.is_empty() {
        return version;
    }

    let mut output = group;
    output.to_mut().push('/');
    output.to_mut().push_str(&version);
    output
}

/// Implement accessor trait for any ObjectMeta-using Kubernetes Resource
impl<K, S> Resource for K
where
    K: k8s_openapi::Metadata<Ty = ObjectMeta>,
    K: k8s_openapi::Resource<Scope = S>,
{
    type DynamicType = ();
    type Scope = S;

    fn kind(_: &()) -> Cow<'_, str> {
        K::KIND.into()
    }

    fn group(_: &()) -> Cow<'_, str> {
        K::GROUP.into()
    }

    fn version(_: &()) -> Cow<'_, str> {
        K::VERSION.into()
    }

    fn api_version(_: &()) -> Cow<'_, str> {
        K::API_VERSION.into()
    }

    fn plural(_: &()) -> Cow<'_, str> {
        K::URL_PATH_SEGMENT.into()
    }

    fn meta(&self) -> &ObjectMeta {
        self.metadata()
    }

    fn meta_mut(&mut self) -> &mut ObjectMeta {
        self.metadata_mut()
    }
}

/// Helper methods for resources.
pub trait ResourceExt: Resource {
    /// Returns the name of the resource, panicking if it is unset
    ///
    /// Only use this function if you know that name is set; for example when
    /// the resource was received from the apiserver (post-admission),
    /// or if you constructed the resource with the name.
    ///
    /// At admission, `.metadata.generateName` can be set instead of name
    /// and in those cases this function can panic.
    ///
    /// Prefer using `.meta().name` or [`name_any`](ResourceExt::name_any)
    /// for the more general cases.
    fn name_unchecked(&self) -> String;

    /// Returns the most useful name identifier available
    ///
    /// This is tries `name`, then `generateName`, and falls back on an empty string when neither is set.
    /// Generally you always have one of the two unless you are creating the object locally.
    ///
    /// This is intended to provide something quick and simple for standard logging purposes.
    /// For more precise use cases, prefer doing your own defaulting.
    /// For true uniqueness, prefer [`uid`](ResourceExt::uid).
    fn name_any(&self) -> String;

    /// The namespace the resource is in
    fn namespace(&self) -> Option<String>;
    /// The resource version
    fn resource_version(&self) -> Option<String>;
    /// Unique ID (if you delete resource and then create a new
    /// resource with the same name, it will have different ID)
    fn uid(&self) -> Option<String>;
    /// Returns the creation timestamp
    ///
    /// This is guaranteed to exist on resources received by the apiserver.
    fn creation_timestamp(&self) -> Option<Time>;
    /// Returns resource labels
    fn labels(&self) -> &BTreeMap<String, String>;
    /// Provides mutable access to the labels
    fn labels_mut(&mut self) -> &mut BTreeMap<String, String>;
    /// Returns resource annotations
    fn annotations(&self) -> &BTreeMap<String, String>;
    /// Provider mutable access to the annotations
    fn annotations_mut(&mut self) -> &mut BTreeMap<String, String>;
    /// Returns resource owner references
    fn owner_references(&self) -> &[OwnerReference];
    /// Provides mutable access to the owner references
    fn owner_references_mut(&mut self) -> &mut Vec<OwnerReference>;
    /// Returns resource finalizers
    fn finalizers(&self) -> &[String];
    /// Provides mutable access to the finalizers
    fn finalizers_mut(&mut self) -> &mut Vec<String>;
    /// Returns managed fields
    fn managed_fields(&self) -> &[ManagedFieldsEntry];
    /// Provides mutable access to managed fields
    fn managed_fields_mut(&mut self) -> &mut Vec<ManagedFieldsEntry>;
}

static EMPTY_MAP: BTreeMap<String, String> = BTreeMap::new();

impl<K: Resource> ResourceExt for K {
    fn name_unchecked(&self) -> String {
        self.meta().name.clone().expect(".metadata.name missing")
    }

    fn name_any(&self) -> String {
        self.meta()
            .name
            .clone()
            .or_else(|| self.meta().generate_name.clone())
            .unwrap_or_default()
    }

    fn namespace(&self) -> Option<String> {
        self.meta().namespace.clone()
    }

    fn resource_version(&self) -> Option<String> {
        self.meta().resource_version.clone()
    }

    fn uid(&self) -> Option<String> {
        self.meta().uid.clone()
    }

    fn creation_timestamp(&self) -> Option<Time> {
        self.meta().creation_timestamp.clone()
    }

    fn labels(&self) -> &BTreeMap<String, String> {
        self.meta().labels.as_ref().unwrap_or(&EMPTY_MAP)
    }

    fn labels_mut(&mut self) -> &mut BTreeMap<String, String> {
        self.meta_mut().labels.get_or_insert_with(BTreeMap::new)
    }

    fn annotations(&self) -> &BTreeMap<String, String> {
        self.meta().annotations.as_ref().unwrap_or(&EMPTY_MAP)
    }

    fn annotations_mut(&mut self) -> &mut BTreeMap<String, String> {
        self.meta_mut().annotations.get_or_insert_with(BTreeMap::new)
    }

    fn owner_references(&self) -> &[OwnerReference] {
        self.meta().owner_references.as_deref().unwrap_or_default()
    }

    fn owner_references_mut(&mut self) -> &mut Vec<OwnerReference> {
        self.meta_mut().owner_references.get_or_insert_with(Vec::new)
    }

    fn finalizers(&self) -> &[String] {
        self.meta().finalizers.as_deref().unwrap_or_default()
    }

    fn finalizers_mut(&mut self) -> &mut Vec<String> {
        self.meta_mut().finalizers.get_or_insert_with(Vec::new)
    }

    fn managed_fields(&self) -> &[ManagedFieldsEntry] {
        self.meta().managed_fields.as_deref().unwrap_or_default()
    }

    fn managed_fields_mut(&mut self) -> &mut Vec<ManagedFieldsEntry> {
        self.meta_mut().managed_fields.get_or_insert_with(Vec::new)
    }
}