sozu_command_lib/
lib.rs

1//! Tools and types used to communicate with Sōzu.
2
3#[macro_use]
4extern crate serde;
5
6/// The floor each H2 listener knob must meet — the single list, expanded once
7/// per validator that enforces it (sozu-proxy/sozu#1418).
8///
9/// Expands `$callback!($config, <field>, <minimum>)` once per knob, in a fixed
10/// order, so the five doors into a listener configuration share one list
11/// instead of five copies of it: `ListenerBuilder::validate_h2_thresholds`
12/// (`crate::config`, the config file and `sozu ctl add listener`),
13/// `validate_h2_flood_knobs_http`/`_https` (`crate::state`,
14/// `UpdateHttp(s)Listener`) and `validate_h2_flood_knobs_http_listener`/
15/// `_https_listener` (`crate::state`, a raw protobuf
16/// `Add{Http,Https}Listener`). Each supplies its own one-knob callback because
17/// the error types differ — `ConfigError::H2ThresholdBelowMinimum` names the
18/// listener, `StateError::InvalidValue` names the field — but none supplies
19/// its own list. Adding a knob to one door and forgetting another is what
20/// reopens sozu#1418 one level up; with the list here it is not expressible.
21///
22/// `h2_graceful_shutdown_deadline_seconds` is deliberately absent: `0` there
23/// means "wait forever (no forced close after GOAWAY)".
24macro_rules! for_each_h2_knob_floor {
25    ($callback:ident, $config:ident) => {
26        $callback!($config, h2_max_rst_stream_per_window, 1);
27        $callback!($config, h2_max_ping_per_window, 1);
28        $callback!($config, h2_max_settings_per_window, 1);
29        $callback!($config, h2_max_empty_data_per_window, 1);
30        $callback!($config, h2_max_window_update_stream0_per_window, 1);
31        $callback!($config, h2_max_continuation_frames, 1);
32        $callback!($config, h2_max_glitch_count, 1);
33        $callback!($config, h2_max_rst_stream_lifetime, 1);
34        $callback!($config, h2_max_rst_stream_abusive_lifetime, 1);
35        $callback!($config, h2_max_rst_stream_emitted_lifetime, 1);
36        $callback!($config, h2_max_header_list_size, 1);
37        $callback!($config, h2_max_header_table_size, 1);
38        $callback!($config, h2_max_header_fields, 1);
39        $callback!($config, h2_max_concurrent_streams, 1);
40        // The runtime floor is 2 (`lib/src/protocol/mux/h2.rs`'s `.max(2)`);
41        // anything lower is silently promoted, so refuse it instead.
42        $callback!($config, h2_stream_shrink_ratio, 2);
43    };
44}
45pub(crate) use for_each_h2_knob_floor;
46
47#[macro_use]
48/// custom made logging macros
49pub mod logging;
50/// Custom buffer used for parsing within the Sōzu codebase.
51pub mod buffer;
52/// TLS certificates
53pub mod certificate;
54/// channels used for communication between main process and workers
55pub mod channel;
56/// parse TOML config and generate requests from it
57pub mod config;
58/// listener identity: socket address plus optional network interface
59pub mod listener_key;
60/// parse Requests
61pub mod parser;
62/// Contains Rust types generated by [`prost`](https://docs.rs/prost/latest/prost/)
63/// using the protobuf definition in `command.proto`.
64///
65/// The two main types are `Request` and `Response`.
66///
67/// Because these types were originally defined in Rust, and later adapted for protobuf,
68/// the Rust translation of the protobuf definition looks a bit weird. Instead of having
69/// `Request` being a simple enum with Payload like this:
70///
71/// ```ignore
72/// pub enum Request {
73///     SaveState(String),
74///     LoadState(String),
75///     // ...
76/// }
77/// ```
78///
79/// It is defined with `oneof` in protobuf. and looks like this in Rust:
80///
81/// ```ignore
82/// pub struct Request {
83///     pub request_type: ::core::option::Option<request::RequestType>,
84/// }
85///
86/// pub mod request {
87///     pub enum RequestType {
88///         #[prost(string, tag = "1")]
89///         SaveState(::prost::alloc::string::String),
90///         /// load a state file, given its path
91///         #[prost(string, tag = "2")]
92///         LoadState(::prost::alloc::string::String),
93///     }
94/// }
95/// ```
96///
97/// but can be instantiated this way:
98///
99/// ```ignore
100/// let load_state_request: Request = RequestType::LoadState(path).into();
101/// ```
102///
103/// A bit cumbersome, but it is the only way to benefit from protobuf in Rust.
104pub mod proto;
105/// File descriptor readiness
106pub mod ready;
107/// Helper functions around types received by Sōzu
108pub mod request;
109/// Helper functions around types sent by Sōzu
110pub mod response;
111/// sockets used to pass file descriptors
112pub mod scm_socket;
113/// systemd `sd_notify` integration (READY=1 / STOPPING=1 / etc.)
114pub mod sd_notify;
115/// A representation of Sōzu's state
116pub mod state;
117/// A writer used for logging
118pub mod writer;
119
120/// Used only when returning errors
121#[derive(Debug)]
122pub enum ObjectKind {
123    Backend,
124    Certificate,
125    Cluster,
126    HttpFrontend,
127    HttpsFrontend,
128    HttpListener,
129    HttpsListener,
130    Listener,
131    TcpCluster,
132    TcpListener,
133    TcpFrontend,
134    UdpListener,
135    UdpFrontend,
136}
137
138pub trait AsString {
139    fn as_string_or(&self, default: &'static str) -> String;
140}
141
142impl<T: ToString> AsString for Option<T> {
143    fn as_string_or(&self, default: &'static str) -> String {
144        match self {
145            None => default.to_string(),
146            Some(t) => t.to_string(),
147        }
148    }
149}
150
151pub trait AsStr {
152    fn as_str_or(&self, default: &'static str) -> &str;
153}
154
155impl<T: AsRef<str>> AsStr for Option<T> {
156    fn as_str_or(&self, default: &'static str) -> &str {
157        match self {
158            None => default,
159            Some(s) => s.as_ref(),
160        }
161    }
162}
sozu_command_lib/lib.rs

sozu_command_lib/
lib.rs
