diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/catalog.rs | 76 | ||||
| -rw-r--r-- | src/lib.rs | 19 | ||||
| -rw-r--r-- | src/locking.rs | 25 | ||||
| -rw-r--r-- | src/with_index.rs | 9 |
4 files changed, 93 insertions, 36 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()); @@ -1,6 +1,6 @@ -mod catalog; +pub mod catalog; +pub mod locking; mod kv; -mod locking; mod with_index; use std::fs::File; @@ -10,14 +10,23 @@ use anyhow::{bail, Result}; pub use with_index::WithIndex; -pub struct ConsulConfig { +/// Configuration parameters to talk to a Consul server +pub struct Config { + /// HTTP address of the Consul server, with `http://` or `https://` prefix pub addr: String, + /// CA certificate of the Consul CA, when using TLS pub ca_cert: Option<String>, - pub tls_skip_verify: bool, + /// Client certificate for client auth when using TLS pub client_cert: Option<String>, + /// Client key for client auth when using TLS pub client_key: Option<String>, + /// Skip verification of consul server TLS certificates + pub tls_skip_verify: bool, } +/// Client used to talk to a Consul server. +/// All calls to the key/value API are automatically prefixed with an arbitrary string +/// that is constructed at client creation. #[derive(Clone)] pub struct Consul { client: reqwest::Client, @@ -27,7 +36,7 @@ pub struct Consul { } impl Consul { - pub fn new(config: ConsulConfig, kv_prefix: &str) -> Result<Self> { + pub fn new(config: Config, kv_prefix: &str) -> Result<Self> { let client = match (&config.client_cert, &config.client_key) { (Some(client_cert), Some(client_key)) => { let mut client_cert_buf = vec![]; diff --git a/src/locking.rs b/src/locking.rs index 12e9ac0..375d3f4 100644 --- a/src/locking.rs +++ b/src/locking.rs @@ -1,3 +1,8 @@ +//! Contains structures to interact with the locks/sessions API +//! +//! See <https://developer.hashicorp.com/consul/api-docs/session> +//! for the full definition of the API. + use anyhow::Result; use bytes::Bytes; use log::*; @@ -5,37 +10,33 @@ use serde::{Deserialize, Serialize}; use crate::Consul; +/// Session creation request as specified in +/// <https://developer.hashicorp.com/consul/api-docs/session#create-session> #[derive(Serialize, Deserialize, Debug)] -pub struct ConsulSessionRequest { - #[serde(rename = "Name")] +#[serde(rename_all = "PascalCase")] +pub struct SessionRequest { pub name: String, - - #[serde(rename = "Node")] pub node: Option<String>, - - #[serde(rename = "LockDelay")] pub lock_delay: Option<String>, - #[serde(rename = "TTL")] pub ttl: Option<String>, - - #[serde(rename = "Behavior")] pub behavior: Option<String>, } +/// (for internal use, mostly) #[derive(Serialize, Deserialize, Debug)] -pub struct ConsulSessionResponse { +pub struct SessionResponse { #[serde(rename = "ID")] pub id: String, } impl Consul { - pub async fn create_session(&self, req: &ConsulSessionRequest) -> Result<String> { + pub async fn create_session(&self, req: &SessionRequest) -> Result<String> { debug!("create_session {:?}", req); let url = format!("{}/v1/session/create", self.url); let http = self.client.put(&url).json(req).send().await?; - let resp: ConsulSessionResponse = http.json().await?; + let resp: SessionResponse = http.json().await?; Ok(resp.id) } diff --git a/src/with_index.rs b/src/with_index.rs index 90e06be..adce169 100644 --- a/src/with_index.rs +++ b/src/with_index.rs @@ -3,12 +3,16 @@ use std::fmt::{Debug, Display}; use anyhow::{bail, Result}; use reqwest::Response; +/// Wraps the returned value of an [API call with blocking +/// possibility](https://developer.hashicorp.com/consul/api-docs/features/blocking) with the +/// returned Consul index pub struct WithIndex<T> { value: T, index: usize, } impl<T> WithIndex<T> { + /// (for internal use, mostly) pub fn index_from(resp: &Response) -> Result<WithIndexBuilder<T>> { let index = match resp.headers().get("X-Consul-Index") { Some(v) => v.to_str()?.parse::<usize>()?, @@ -20,10 +24,13 @@ impl<T> WithIndex<T> { }) } + /// Returns the inner value, discarding the index pub fn into_inner(self) -> T { self.value } + /// Returns the Consul index, to be used in future calls to the same API endpoint to make them + /// blocking pub fn index(&self) -> usize { self.index } @@ -60,12 +67,14 @@ impl<T: Display> Display for WithIndex<T> { } } +/// (for internal use, mostly) pub struct WithIndexBuilder<T> { _phantom: std::marker::PhantomData<T>, index: usize, } impl<T> WithIndexBuilder<T> { + /// (for internal use, mostly) pub fn value(self, value: T) -> WithIndex<T> { WithIndex { value, |