Documentate

1 files changed, 57 insertions, 19 deletions

diff --git a/src/catalog.rs b/src/catalog.rs
index 952e99e..0f0ecf5 100644
--- a/src/catalog.rs
+++ b/src/catalog.rs
@@ -1,3 +1,8 @@
+//! Contains structures to interact with the catalog API
+//!
+//! See <https://developer.hashicorp.com/consul/api-docs/catalog>
+//! for the full definition of the API.
+
 use std::collections::HashMap;
 use std::fmt::Write;
 use std::sync::Arc;
@@ -14,35 +19,44 @@ use tokio::sync::watch;
 
 use crate::{Consul, WithIndex};
 
+/// Node summary, as specified in response to "list nodes" API calls in 
+/// <https://developer.hashicorp.com/consul/api-docs/catalog#list-nodes>
 #[derive(Serialize, Deserialize, Debug, Clone)]
 #[serde(rename_all = "PascalCase")]
-pub struct ConsulNode {
+pub struct Node {
     pub node: String,
     pub address: String,
     pub meta: HashMap<String, String>,
 }
 
+/// One of the services returned in a CatalogNode
 #[derive(Serialize, Deserialize, Debug, Clone)]
 #[serde(rename_all = "PascalCase")]
-pub struct ConsulService {
+pub struct Service {
     pub service: String,
     pub address: String,
     pub port: u16,
     pub tags: Vec<String>,
 }
 
+/// Full node info, as specified in response to "retrieve map of services for a node" API call in
+/// <https://developer.hashicorp.com/consul/api-docs/catalog#retrieve-map-of-services-for-a-node>
 #[derive(Serialize, Deserialize, Debug)]
 #[serde(rename_all = "PascalCase")]
-pub struct ConsulCatalogNode {
-    pub node: ConsulNode,
-    pub services: HashMap<String, ConsulService>,
+pub struct CatalogNode {
+    pub node: Node,
+    pub services: HashMap<String, Service>,
 }
 
-pub type ConsulServiceList = HashMap<String, Vec<String>>;
+/// Concise service list, as specified in response to "list services" API call in
+/// <https://developer.hashicorp.com/consul/api-docs/catalog#list-services>
+pub type ServiceList = HashMap<String, Vec<String>>;
 
+/// Node serving a service, as specified in response to "list nodes for a service" API call in
+/// <https://developer.hashicorp.com/consul/api-docs/catalog#list-nodes-for-service>
 #[derive(Serialize, Deserialize, Debug)]
 #[serde(rename_all = "PascalCase")]
-pub struct ConsulServiceNode {
+pub struct ServiceNode {
     pub node: String,
     pub address: String,
     pub node_meta: HashMap<String, String>,
@@ -52,17 +66,21 @@ pub struct ConsulServiceNode {
     pub service_port: u16,
 }
 
+/// Node serving a service with health info,
+/// as specified in response to "list service instances for a service" health API call in
+/// <https://developer.hashicorp.com/consul/api-docs/health#list-service-instances-for-service>
 #[derive(Serialize, Deserialize, Debug, Clone)]
 #[serde(rename_all = "PascalCase")]
-pub struct ConsulHealthServiceNode {
-    pub node: ConsulNode,
-    pub service: ConsulService,
-    pub checks: Vec<ConsulHealthCheck>,
+pub struct HealthServiceNode {
+    pub node: Node,
+    pub service: Service,
+    pub checks: Vec<HealthCheck>,
 }
 
+/// A health check as returned in HealthServiceNode
 #[derive(Serialize, Deserialize, Debug, Clone)]
 #[serde(rename_all = "PascalCase")]
-pub struct ConsulHealthCheck {
+pub struct HealthCheck {
     pub node: String,
     #[serde(rename = "CheckID")]
     pub check_id: String,
@@ -73,42 +91,56 @@ pub struct ConsulHealthCheck {
     pub type_: String,
 }
 
-pub type AllServiceHealth = HashMap<String, Arc<[ConsulHealthServiceNode]>>;
+/// Map containing all services and their associated nodes, with health checks,
+/// returned by `watch_all_service_health`
+pub type AllServiceHealth = HashMap<String, Arc<[HealthServiceNode]>>;
 
 impl Consul {
+    /// The "list nodes" API call of the Catalog API
+    ///
+    /// <https://developer.hashicorp.com/consul/api-docs/catalog#list-nodes>
     pub async fn catalog_node_list(
         &self,
         last_index: Option<usize>,
-    ) -> Result<WithIndex<Vec<ConsulNode>>> {
+    ) -> Result<WithIndex<Vec<Node>>> {
         self.get_with_index(format!("{}/v1/catalog/nodes", self.url), last_index)
             .await
     }
 
+    /// The "retrieve map of services for a node" API call of the Catalog API
+    ///
+    /// <https://developer.hashicorp.com/consul/api-docs/catalog#retrieve-map-of-services-for-a-node>
     pub async fn catalog_node(
         &self,
         host: &str,
         last_index: Option<usize>,
-    ) -> Result<WithIndex<Option<ConsulCatalogNode>>> {
+    ) -> Result<WithIndex<Option<CatalogNode>>> {
         self.get_with_index(format!("{}/v1/catalog/node/{}", self.url, host), last_index)
             .await
     }
 
+    /// The "list services" API call of the Catalog api
+    ///
+    /// <https://developer.hashicorp.com/consul/api-docs/catalog#list-services>
     pub async fn catalog_service_list(
         &self,
         last_index: Option<usize>,
-    ) -> Result<WithIndex<ConsulServiceList>> {
-        self.get_with_index::<ConsulServiceList>(
+    ) -> Result<WithIndex<ServiceList>> {
+        self.get_with_index::<ServiceList>(
             format!("{}/v1/catalog/services", self.url),
             last_index,
         )
         .await
     }
 
+    /// The "list nodes for a service" API call of the Catalog api
+    ///
+    /// <https://developer.hashicorp.com/consul/api-docs/catalog#list-nodes-for-service>
     pub async fn catalog_service_nodes(
         &self,
         service: &str,
         last_index: Option<usize>,
-    ) -> Result<WithIndex<Vec<ConsulServiceNode>>> {
+    ) -> Result<WithIndex<Vec<ServiceNode>>> {
         self.get_with_index(
             format!("{}/v1/catalog/service/{}", self.url, service),
             last_index,
@@ -116,11 +148,14 @@ impl Consul {
         .await
     }
 
+    /// The "list service instances for a service" API call of the Health api
+    ///
+    /// <https://developer.hashicorp.com/consul/api-docs/health#list-service-instances-for-service>
     pub async fn health_service_instances(
         &self,
         service: &str,
         last_index: Option<usize>,
-    ) -> Result<WithIndex<Vec<ConsulHealthServiceNode>>> {
+    ) -> Result<WithIndex<Vec<HealthServiceNode>>> {
         self.get_with_index(
             format!("{}/v1/health/service/{}", self.url, service),
             last_index,
@@ -128,6 +163,9 @@ impl Consul {
         .await
     }
 
+    /// Launches a background task that watches all services and the nodes that serve them,
+    /// and make that info available in a tokio watch channel.
+    /// The worker terminates when the channel is dropped.
     pub fn watch_all_service_health(&self) -> watch::Receiver<AllServiceHealth> {
         let (tx, rx) = watch::channel(HashMap::new());