summaryrefslogtreecommitdiff
path: root/src
diff options
context:
space:
mode:
authorAlex Auvolat <alex@adnab.me>2023-02-02 15:47:20 +0100
committerAlex Auvolat <alex@adnab.me>2023-02-02 15:47:20 +0100
commitd0f40c02b9b74e6e6b852036865ad2b0c0e9370c (patch)
treecbaea0947e0bc3c6979c6015fd5166ffdfa626ac /src
parentdb1d4411a904bec2d1c2a1c4735ad09cc7f98632 (diff)
downloaddf-consul-d0f40c02b9b74e6e6b852036865ad2b0c0e9370c.tar.gz
df-consul-d0f40c02b9b74e6e6b852036865ad2b0c0e9370c.zip
Documentate
Diffstat (limited to 'src')
-rw-r--r--src/catalog.rs76
-rw-r--r--src/lib.rs19
-rw-r--r--src/locking.rs25
-rw-r--r--src/with_index.rs9
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());
diff --git a/src/lib.rs b/src/lib.rs
index 6326fa0..c320936 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -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,