client_ext for Client::get and Client::list

examples/Cargo.toml

@@ -16,8 +16,8 @@ release = false
 [features]
 default = ["rustls-tls", "kubederive", "ws", "latest", "socks5", "runtime", "refresh"]
 kubederive = ["kube/derive"]
-openssl-tls = ["kube/client", "kube/openssl-tls"]
-rustls-tls = ["kube/client", "kube/rustls-tls"]
+openssl-tls = ["kube/client", "kube/openssl-tls", "kube/unstable-client"]
+rustls-tls = ["kube/client", "kube/rustls-tls", "kube/unstable-client"]
 runtime = ["kube/runtime", "kube/unstable-runtime"]
 socks5 = ["kube/socks5"]
 refresh = ["kube/oauth", "kube/oidc"]

examples/node_watcher.rs

@@ -2,16 +2,15 @@ use futures::{pin_mut, TryStreamExt};
 use k8s_openapi::api::core::v1::{Event, Node};
 use kube::{
     api::{Api, ListParams, ResourceExt},
+    client::{scope, Client},
     runtime::{watcher, WatchStreamExt},
-    Client,
 };
 use tracing::*;
 
 #[tokio::main]
 async fn main() -> anyhow::Result<()> {
     tracing_subscriber::fmt::init();
     let client = Client::try_default().await?;
-    let events: Api<Event> = Api::all(client.clone());
     let nodes: Api<Node> = Api::all(client.clone());
 
     let use_watchlist = std::env::var("WATCHLIST").map(|s| s == "1").unwrap_or(false);
@@ -25,13 +24,13 @@ async fn main() -> anyhow::Result<()> {
 
     pin_mut!(obs);
     while let Some(n) = obs.try_next().await? {
-        check_for_node_failures(&events, n).await?;
+        check_for_node_failures(&client, n).await?;
     }
     Ok(())
 }
 
 // A simple node problem detector
-async fn check_for_node_failures(events: &Api<Event>, o: Node) -> anyhow::Result<()> {
+async fn check_for_node_failures(client: &Client, o: Node) -> anyhow::Result<()> {
     let name = o.name_any();
     // Nodes often modify a lot - only print broken nodes
     if let Some(true) = o.spec.unwrap().unschedulable {
@@ -52,7 +51,7 @@ async fn check_for_node_failures(events: &Api<Event>, o: Node) -> anyhow::Result
         // Find events related to this node
         let opts =
             ListParams::default().fields(&format!("involvedObject.kind=Node,involvedObject.name={name}"));
-        let evlist = events.list(&opts).await?;
+        let evlist = client.list::<Event>(&opts, &scope::Cluster).await?;
         for e in evlist {
             warn!("Node event: {:?}", serde_json::to_string_pretty(&e)?);
         }

kube-client/Cargo.toml

@@ -28,12 +28,13 @@ jsonpatch = ["kube-core/jsonpatch"]
 admission = ["kube-core/admission"]
 config = ["__non_core", "pem", "home"]
 socks5 = ["hyper-socks2"]
+unstable-client = []
 
 # private feature sets; do not use
 __non_core = ["tracing", "serde_yaml", "base64"]
 
 [package.metadata.docs.rs]
-features = ["client", "rustls-tls", "openssl-tls", "ws", "oauth", "oidc", "jsonpatch", "admission", "k8s-openapi/latest", "socks5"]
+features = ["client", "rustls-tls", "openssl-tls", "ws", "oauth", "oidc", "jsonpatch", "admission", "k8s-openapi/latest", "socks5", "unstable-client"]
 # Define the configuration attribute `docsrs`. Used to enable `doc_cfg` feature.
 rustdoc-args = ["--cfg", "docsrs"]
 

kube-client/src/client/client_ext.rs

@@ -0,0 +1,259 @@
+use crate::{Client, Error, Result};
+use k8s_openapi::api::core::v1::Namespace as k8sNs;
+use kube_core::{
+    object::ObjectList,
+    params::{GetParams, ListParams},
+    request::Request,
+    ClusterResourceScope, DynamicResourceScope, NamespaceResourceScope, Resource,
+};
+use serde::{de::DeserializeOwned, Serialize};
+use std::fmt::Debug;
+
+/// A marker trait to indicate cluster-wide operations are available
+trait ClusterScope {}
+/// A marker trait to indicate namespace-scoped operations are available
+trait NamespaceScope {}
+
+// k8s_openapi scopes get implementations for free
+impl ClusterScope for ClusterResourceScope {}
+impl NamespaceScope for NamespaceResourceScope {}
+// our DynamicResourceScope can masquerade as either
+impl NamespaceScope for DynamicResourceScope {}
+impl ClusterScope for DynamicResourceScope {}
+
+/// How to get the url for a collection
+///
+/// Pick one of `kube::client::Cluster` or `kube::client::Namespace`.
+pub trait CollectionUrl<K> {
+    fn url_path(&self) -> String;
+}
+
+/// How to get the url for an object
+///
+/// Pick one of `kube::client::Cluster` or `kube::client::Namespace`.
+pub trait ObjectUrl<K> {
+    fn url_path(&self) -> String;
+}
+
+/// Marker type for cluster level queries
+pub struct Cluster;
+/// Namespace newtype for namespace level queries
+///
+/// You can create this directly, or convert `From` a `String` / `&str`, or `TryFrom` an `k8s_openapi::api::core::v1::Namespace`
+pub struct Namespace(String);
+
+/// Scopes for `unstable-client` [`Client#impl-Client`] extension methods
+pub mod scope {
+    pub use super::{Cluster, Namespace};
+}
+
+// All objects can be listed cluster-wide
+impl<K> CollectionUrl<K> for Cluster
+where
+    K: Resource,
+    K::DynamicType: Default,
+{
+    fn url_path(&self) -> String {
+        K::url_path(&K::DynamicType::default(), None)
+    }
+}
+
+// Only cluster-scoped objects can be named globally
+impl<K> ObjectUrl<K> for Cluster
+where
+    K: Resource,
+    K::DynamicType: Default,
+    K::Scope: ClusterScope,
+{
+    fn url_path(&self) -> String {
+        K::url_path(&K::DynamicType::default(), None)
+    }
+}
+
+// Only namespaced objects can be accessed via namespace
+impl<K> CollectionUrl<K> for Namespace
+where
+    K: Resource,
+    K::DynamicType: Default,
+    K::Scope: NamespaceScope,
+{
+    fn url_path(&self) -> String {
+        K::url_path(&K::DynamicType::default(), Some(&self.0))
+    }
+}
+
+impl<K> ObjectUrl<K> for Namespace
+where
+    K: Resource,
+    K::DynamicType: Default,
+    K::Scope: NamespaceScope,
+{
+    fn url_path(&self) -> String {
+        K::url_path(&K::DynamicType::default(), Some(&self.0))
+    }
+}
+
+// can be created from a complete native object
+impl TryFrom<&k8sNs> for Namespace {
+    type Error = NamespaceError;
+
+    fn try_from(ns: &k8sNs) -> Result<Namespace, Self::Error> {
+        if let Some(n) = &ns.meta().name {
+            Ok(Namespace(n.to_owned()))
+        } else {
+            Err(NamespaceError::MissingName)
+        }
+    }
+}
+// and from literals + owned strings
+impl From<&str> for Namespace {
+    fn from(ns: &str) -> Namespace {
+        Namespace(ns.to_owned())
+    }
+}
+impl From<String> for Namespace {
+    fn from(ns: String) -> Namespace {
+        Namespace(ns)
+    }
+}
+
+#[derive(thiserror::Error, Debug)]
+/// Failures to infer a namespace
+pub enum NamespaceError {
+    /// MissingName
+    #[error("Missing Namespace Name")]
+    MissingName,
+}
+
+/// Generic client extensions for the `unstable-client` feature
+///
+/// These methods allow users to query across a wide-array of resources without needing
+/// to explicitly create an [`Api`](crate::Api) for each one of them.
+///
+/// ## Usage
+/// 1. Create a [`Client`]
+/// 2. Specify the [`scope`] you are querying at via [`Cluster`] or [`Namespace`] as args
+/// 3. Specify the resource type you are using for serialization (e.g. a top level k8s-openapi type)
+///
+/// ## Example
+///
+/// ```no_run
+/// # use k8s_openapi::api::core::v1::Pod;
+/// # use k8s_openapi::api::core::v1::Service;
+/// # use kube::client::scope::{Cluster, Namespace};
+/// # use kube::{ResourceExt, api::ListParams};
+/// # async fn wrapper() -> Result<(), Box<dyn std::error::Error>> {
+/// # let client: kube::Client = todo!();
+/// let lp = ListParams::default();
+/// // List at Cluster level for Pod resource:
+/// for pod in client.list::<Pod>(&lp, &Cluster).await? {
+///     println!("Found pod {} in {}", pod.name_any(), pod.namespace().unwrap());
+/// }
+/// // Namespaced Get for Service resource:
+/// let svc = client.get::<Service>("kubernetes", &Namespace::from("default")).await?;
+/// assert_eq!(svc.name_unchecked(), "kubernetes");
+/// # Ok(())
+/// # }
+/// ```
+impl Client {
+    /// Get a single instance of a `Resource` implementing type `K` at the specified scope.
+    ///
+    /// ```no_run
+    /// # use k8s_openapi::api::rbac::v1::ClusterRole;
+    /// # use k8s_openapi::api::core::v1::Service;
+    /// # use kube::client::scope::{Cluster, Namespace};
+    /// # use kube::{ResourceExt, api::GetParams};
+    /// # async fn wrapper() -> Result<(), Box<dyn std::error::Error>> {
+    /// # let client: kube::Client = todo!();
+    /// let cr = client.get::<ClusterRole>("cluster-admin", &Cluster).await?;
+    /// assert_eq!(cr.name_unchecked(), "cluster-admin");
+    /// let svc = client.get::<Service>("kubernetes", &Namespace::from("default")).await?;
+    /// assert_eq!(svc.name_unchecked(), "kubernetes");
+    /// # Ok(())
+    /// # }
+    /// ```
+    pub async fn get<K>(&self, name: &str, scope: &impl ObjectUrl<K>) -> Result<K>
+    where
+        K: Resource + Serialize + DeserializeOwned + Clone + Debug,
+        <K as Resource>::DynamicType: Default,
+    {
+        let mut req = Request::new(scope.url_path())
+            .get(name, &GetParams::default())
+            .map_err(Error::BuildRequest)?;
+        req.extensions_mut().insert("get");
+        self.request::<K>(req).await
+    }
+
+    /// List instances of a `Resource` implementing type `K` at the specified scope.
+    ///
+    /// ```no_run
+    /// # use k8s_openapi::api::core::v1::Pod;
+    /// # use k8s_openapi::api::core::v1::Service;
+    /// # use kube::client::scope::{Cluster, Namespace};
+    /// # use kube::{ResourceExt, api::ListParams};
+    /// # async fn wrapper() -> Result<(), Box<dyn std::error::Error>> {
+    /// # let client: kube::Client = todo!();
+    /// let lp = ListParams::default();
+    /// for pod in client.list::<Pod>(&lp, &Cluster).await? {
+    ///     println!("Found pod {} in {}", pod.name_any(), pod.namespace().unwrap());
+    /// }
+    /// for svc in client.list::<Service>(&lp, &Namespace::from("default")).await? {
+    ///     println!("Found service {}", svc.name_any());
+    /// }
+    /// # Ok(())
+    /// # }
+    /// ```
+    pub async fn list<K>(&self, lp: &ListParams, scope: &impl CollectionUrl<K>) -> Result<ObjectList<K>>
+    where
+        K: Resource + Serialize + DeserializeOwned + Clone + Debug,
+        <K as Resource>::DynamicType: Default,
+    {
+        let mut req = Request::new(scope.url_path())
+            .list(lp)
+            .map_err(Error::BuildRequest)?;
+        req.extensions_mut().insert("list");
+        self.request::<ObjectList<K>>(req).await
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use super::{
+        scope::{Cluster, Namespace},
+        Client, ListParams,
+    };
+    use kube_core::ResourceExt;
+
+    #[tokio::test]
+    #[ignore = "needs cluster (will list/get namespaces, pods, jobs, svcs, clusterroles)"]
+    async fn client_ext_list_get_pods_svcs() -> Result<(), Box<dyn std::error::Error>> {
+        use k8s_openapi::api::{
+            batch::v1::Job,
+            core::v1::{Namespace as k8sNs, Pod, Service},
+            rbac::v1::ClusterRole,
+        };
+
+        let client = Client::try_default().await?;
+        let lp = ListParams::default();
+        // cluster-scoped list
+        for ns in client.list::<k8sNs>(&lp, &Cluster).await? {
+            // namespaced list
+            for p in client.list::<Pod>(&lp, &Namespace::try_from(&ns)?).await? {
+                println!("Found pod {} in {}", p.name_any(), ns.name_any());
+            }
+        }
+        // across-namespace list
+        for j in client.list::<Job>(&lp, &Cluster).await? {
+            println!("Found job {} in {}", j.name_any(), j.namespace().unwrap());
+        }
+        // namespaced get
+        let default: Namespace = "default".into();
+        let svc = client.get::<Service>("kubernetes", &default).await?;
+        assert_eq!(svc.name_unchecked(), "kubernetes");
+        // global get
+        let ca = client.get::<ClusterRole>("cluster-admin", &Cluster).await?;
+        assert_eq!(ca.name_unchecked(), "cluster-admin");
+
+        Ok(())
+    }
+}

kube-client/src/client/mod.rs

@@ -31,6 +31,12 @@ mod body;
 mod builder;
 // Add `into_stream()` to `http::Body`
 use body::BodyStreamExt;
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable-client")))]
+#[cfg(feature = "unstable-client")]
+mod client_ext;
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable-client")))]
+#[cfg(feature = "unstable-client")]
+pub use client_ext::scope;
 mod config_ext;
 pub use auth::Error as AuthError;
 pub use config_ext::ConfigExt;
@@ -69,6 +75,11 @@ pub struct Client {
     default_ns: String,
 }
 
+/// Constructors and low-level api interfaces.
+///
+/// Most users only need [`Client::try_default`] or [`Client::new`] from this block.
+///
+/// The many various lower level interfaces here are for more advanced use-cases with specific requirements.
 impl Client {
     /// Create a [`Client`] using a custom `Service` stack.
     ///
@@ -123,6 +134,14 @@ impl Client {
     ///
     /// Will fail if neither configuration could be loaded.
     ///
+    /// ```rust
+    /// # async fn doc() -> Result<(), Box<dyn std::error::Error>> {
+    /// # use kube::Client;
+    /// let client = Client::try_default().await?;
+    /// # Ok(())
+    /// # }
+    /// ```
+    ///
     /// If you already have a [`Config`] then use [`Client::try_from`](Self::try_from)
     /// instead.
     pub async fn try_default() -> Result<Self> {
@@ -460,7 +479,9 @@ fn handle_api_errors(text: &str, s: StatusCode) -> Result<()> {
 impl TryFrom<Config> for Client {
     type Error = Error;
 
-    /// Builds a default [`Client`] from a [`Config`], see [`ClientBuilder`] if more customization is required
+    /// Builds a default [`Client`] from a [`Config`].
+    ///
+    /// See [`ClientBuilder`] or [`Client::new`] if more customization is required
     fn try_from(config: Config) -> Result<Self> {
         Ok(ClientBuilder::try_from(config)?.build())
     }

kube-client/src/config/mod.rs

@@ -122,7 +122,7 @@ pub enum LoadDataError {
 /// Prefer [`Config::infer`] unless you have particular issues, and avoid manually managing
 /// the data in this struct unless you have particular needs. It exists to be consumed by the [`Client`][crate::Client].
 ///
-/// If you are looking to parse the kubeconfig found in a user's home directory see [`Kubeconfig`](crate::config::Kubeconfig).
+/// If you are looking to parse the kubeconfig found in a user's home directory see [`Kubeconfig`].
 #[cfg_attr(docsrs, doc(cfg(feature = "config")))]
 #[derive(Debug, Clone)]
 pub struct Config {