rs-zero 0.2.6

Rust-first microservice framework inspired by go-zero engineering practices
Documentation 
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

use std::{collections::BTreeMap, fmt, net::SocketAddr, str::FromStr};

use serde::{Deserialize, Serialize};

use crate::discovery::{DiscoveryError, DiscoveryResult};

/// Network endpoint for a service instance.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
pub struct InstanceEndpoint {
    host: String,
    port: u16,
}

impl InstanceEndpoint {
    /// Creates an endpoint from a host and port.
    pub fn new(host: impl Into<String>, port: u16) -> DiscoveryResult<Self> {
        let host = host.into();
        if host.trim().is_empty() {
            return Err(DiscoveryError::InvalidEndpoint { endpoint: host });
        }
        Ok(Self { host, port })
    }

    /// Returns the endpoint host.
    pub fn host(&self) -> &str {
        &self.host
    }

    /// Returns the endpoint port.
    pub fn port(&self) -> u16 {
        self.port
    }

    /// Returns a `host:port` string.
    pub fn authority(&self) -> String {
        format!("{}:{}", self.host, self.port)
    }

    /// Converts a socket address into an endpoint.
    pub fn from_socket_addr(addr: SocketAddr) -> Self {
        Self {
            host: addr.ip().to_string(),
            port: addr.port(),
        }
    }
}

impl fmt::Display for InstanceEndpoint {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(formatter, "{}:{}", self.host, self.port)
    }
}

impl FromStr for InstanceEndpoint {
    type Err = DiscoveryError;

    fn from_str(value: &str) -> Result<Self, Self::Err> {
        let (host, port) =
            value
                .rsplit_once(':')
                .ok_or_else(|| DiscoveryError::InvalidEndpoint {
                    endpoint: value.to_string(),
                })?;
        let port = port.parse().map_err(|_| DiscoveryError::InvalidEndpoint {
            endpoint: value.to_string(),
        })?;
        Self::new(host, port)
    }
}

/// A discoverable service instance.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ServiceInstance {
    /// Service name used by discovery clients.
    pub service: String,
    /// Stable instance id inside a service.
    pub id: String,
    /// Network endpoint.
    pub endpoint: InstanceEndpoint,
    /// Free-form metadata for adapters and clients.
    pub metadata: BTreeMap<String, String>,
    /// Whether this instance is considered healthy.
    pub healthy: bool,
    /// Relative weight used by selectors.
    pub weight: u32,
}

impl ServiceInstance {
    /// Creates a healthy service instance with weight `1`.
    pub fn new(
        service: impl Into<String>,
        id: impl Into<String>,
        endpoint: InstanceEndpoint,
    ) -> Self {
        Self {
            service: service.into(),
            id: id.into(),
            endpoint,
            metadata: BTreeMap::new(),
            healthy: true,
            weight: 1,
        }
    }

    /// Adds metadata and returns the updated instance.
    pub fn with_metadata(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
        self.metadata.insert(key.into(), value.into());
        self
    }

    /// Sets the health flag and returns the updated instance.
    pub fn with_health(mut self, healthy: bool) -> Self {
        self.healthy = healthy;
        self
    }

    /// Sets the selector weight. Zero is normalized to one.
    pub fn with_weight(mut self, weight: u32) -> Self {
        self.weight = weight.max(1);
        self
    }
}

#[cfg(test)]
mod tests {
    use super::{InstanceEndpoint, ServiceInstance};

    #[test]
    fn endpoint_parses_authority() {
        let endpoint: InstanceEndpoint = "127.0.0.1:8080".parse().expect("endpoint");
        assert_eq!(endpoint.host(), "127.0.0.1");
        assert_eq!(endpoint.port(), 8080);
        assert_eq!(endpoint.authority(), "127.0.0.1:8080");
    }

    #[test]
    fn service_instance_defaults_are_healthy() {
        let endpoint = InstanceEndpoint::new("localhost", 9000).expect("endpoint");
        let instance = ServiceInstance::new("user", "user-1", endpoint).with_weight(0);
        assert!(instance.healthy);
        assert_eq!(instance.weight, 1);
    }
}