grow-graylog 0.2.0

Rust SDK for Graylog Open by Grow Codes
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
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
// Generated by sdk-kit 0.3.0 — do not edit; change sdk-kit and run "sdk-kit sync"
//! Configuration fields shared by every service config (SPEC §2.2).

use std::fmt;
use std::path::PathBuf;
use std::sync::Arc;
use std::time::Duration;

use url::Url;

use super::env::EnvReader;
use super::error::{Error, Result};
use super::hooks::Hooks;
use super::redact::{redact_headers, redact_url};
use super::retry::RetryPolicy;

/// Default connect timeout (10 s).
pub const DEFAULT_CONNECT_TIMEOUT: Duration = Duration::from_secs(10);
/// Default per-attempt request timeout (30 s).
pub const DEFAULT_REQUEST_TIMEOUT: Duration = Duration::from_secs(30);
/// Default total timeout including retries (120 s).
pub const DEFAULT_TOTAL_TIMEOUT: Duration = Duration::from_secs(120);

/// TLS settings.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct TlsConfig {
    /// PEM file with extra trusted CA certificates.
    pub ca_cert_path: Option<PathBuf>,
    /// PEM text with extra trusted CA certificates.
    pub ca_cert_pem: Option<String>,
    /// PEM client certificate (requires `client_key_path`).
    pub client_cert_path: Option<PathBuf>,
    /// PEM client private key (requires `client_cert_path`).
    pub client_key_path: Option<PathBuf>,
    /// Disables certificate verification (tests only; logs a warning once).
    pub insecure_skip_verify: bool,
}

/// Vendor variable names consulted (in order) after the matching `GROW_<KEY>_*` variable, per
/// common setting. Build it as a constant in the service config:
///
/// ```
/// # use grow_graylog::core::VendorEnv;
/// const VENDOR_ENV: VendorEnv<'static> = VendorEnv {
///     url: &["VENDOR_ADDR"],
///     ca_cert: &["VENDOR_CACERT"],
///     ..VendorEnv::NONE
/// };
/// # assert_eq!(VENDOR_ENV.client_cert, &[] as &[&str]);
/// ```
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct VendorEnv<'a> {
    /// Fallbacks for `GROW_<KEY>_URL`.
    pub url: &'a [&'a str],
    /// Fallbacks for `GROW_<KEY>_CA_CERT` (a PEM file path).
    pub ca_cert: &'a [&'a str],
    /// Fallbacks for `GROW_<KEY>_CLIENT_CERT` (a PEM file path).
    pub client_cert: &'a [&'a str],
    /// Fallbacks for `GROW_<KEY>_CLIENT_KEY` (a PEM file path).
    pub client_key: &'a [&'a str],
    /// Fallbacks for `GROW_<KEY>_INSECURE_SKIP_VERIFY`.
    pub insecure_skip_verify: &'a [&'a str],
    /// Fallbacks for `GROW_<KEY>_PROXY`.
    pub proxy: &'a [&'a str],
}

impl VendorEnv<'static> {
    /// No vendor variables.
    pub const NONE: VendorEnv<'static> = VendorEnv {
        url: &[],
        ca_cert: &[],
        client_cert: &[],
        client_key: &[],
        insecure_skip_verify: &[],
        proxy: &[],
    };
}

impl<'a> VendorEnv<'a> {
    /// Vendor variables for the URL only.
    pub const fn url_only(url: &'a [&'a str]) -> Self {
        VendorEnv {
            url,
            ca_cert: &[],
            client_cert: &[],
            client_key: &[],
            insecure_skip_verify: &[],
            proxy: &[],
        }
    }
}

/// Validated common configuration (immutable).
#[derive(Clone)]
pub struct CommonConfig {
    url: Url,
    connect_timeout: Duration,
    request_timeout: Duration,
    total_timeout: Duration,
    retry: RetryPolicy,
    tls: TlsConfig,
    proxy: Option<String>,
    headers: Vec<(String, String)>,
    user_agent_suffix: Option<String>,
    hooks: Option<Arc<dyn Hooks>>,
}

impl CommonConfig {
    /// A builder with no values set.
    pub fn builder() -> CommonConfigBuilder {
        CommonConfigBuilder::default()
    }
    /// Endpoint base URL.
    pub fn url(&self) -> &Url {
        &self.url
    }
    /// Connection setup timeout.
    pub fn connect_timeout(&self) -> Duration {
        self.connect_timeout
    }
    /// Per-attempt timeout (headers + body).
    pub fn request_timeout(&self) -> Duration {
        self.request_timeout
    }
    /// Whole-call timeout including retries and backoff.
    pub fn total_timeout(&self) -> Duration {
        self.total_timeout
    }
    /// Retry policy.
    pub fn retry(&self) -> &RetryPolicy {
        &self.retry
    }
    /// TLS settings.
    pub fn tls(&self) -> &TlsConfig {
        &self.tls
    }
    /// Explicit proxy URL (environment proxies are ignored).
    pub fn proxy(&self) -> Option<&str> {
        self.proxy.as_deref()
    }
    /// Extra request headers.
    pub fn headers(&self) -> &[(String, String)] {
        &self.headers
    }
    /// Text appended to the standard User-Agent.
    pub fn user_agent_suffix(&self) -> Option<&str> {
        self.user_agent_suffix.as_deref()
    }
    /// Request hooks.
    pub fn hooks(&self) -> Option<&Arc<dyn Hooks>> {
        self.hooks.as_ref()
    }

    /// A builder with every value of this config set explicitly (change some, then
    /// [`build`](CommonConfigBuilder::build) again; environment variables no longer apply).
    pub fn to_builder(&self) -> CommonConfigBuilder {
        CommonConfigBuilder {
            url: Some(self.url.as_str().to_owned()),
            connect_timeout: Some(self.connect_timeout),
            request_timeout: Some(self.request_timeout),
            total_timeout: Some(self.total_timeout),
            retry: Some(self.retry.clone()),
            max_retries: None,
            tls: self.tls.clone(),
            insecure_skip_verify: Some(self.tls.insecure_skip_verify),
            proxy: self.proxy.clone(),
            headers: self.headers.clone(),
            user_agent_suffix: self.user_agent_suffix.clone(),
            hooks: self.hooks.clone(),
        }
    }
}

impl fmt::Debug for CommonConfig {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("CommonConfig")
            .field("url", &redact_url(self.url.as_str()))
            .field("connect_timeout", &self.connect_timeout)
            .field("request_timeout", &self.request_timeout)
            .field("total_timeout", &self.total_timeout)
            .field("retry", &self.retry)
            .field("tls", &self.tls)
            .field("proxy", &self.proxy.as_deref().map(redact_url))
            .field(
                "headers",
                &redact_headers(self.headers.iter().map(|(k, v)| (k, v))),
            )
            .field("user_agent_suffix", &self.user_agent_suffix)
            .field("hooks", &self.hooks.as_ref().map(|_| "Hooks"))
            .finish()
    }
}

/// Builder for [`CommonConfig`]. Explicit values win over environment variables.
#[derive(Clone, Default)]
pub struct CommonConfigBuilder {
    url: Option<String>,
    connect_timeout: Option<Duration>,
    request_timeout: Option<Duration>,
    total_timeout: Option<Duration>,
    retry: Option<RetryPolicy>,
    max_retries: Option<u32>,
    tls: TlsConfig,
    insecure_skip_verify: Option<bool>,
    proxy: Option<String>,
    headers: Vec<(String, String)>,
    user_agent_suffix: Option<String>,
    hooks: Option<Arc<dyn Hooks>>,
}

impl fmt::Debug for CommonConfigBuilder {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("CommonConfigBuilder")
            .field("url", &self.url.as_deref().map(redact_url))
            .finish_non_exhaustive()
    }
}

impl CommonConfigBuilder {
    /// Sets the endpoint base URL.
    pub fn url(mut self, url: impl Into<String>) -> Self {
        self.url = Some(url.into());
        self
    }
    /// Sets the connect timeout.
    pub fn connect_timeout(mut self, timeout: Duration) -> Self {
        self.connect_timeout = Some(timeout);
        self
    }
    /// Sets the per-attempt timeout.
    pub fn request_timeout(mut self, timeout: Duration) -> Self {
        self.request_timeout = Some(timeout);
        self
    }
    /// Sets the total timeout.
    pub fn total_timeout(mut self, timeout: Duration) -> Self {
        self.total_timeout = Some(timeout);
        self
    }
    /// Sets the retry policy.
    pub fn retry(mut self, retry: RetryPolicy) -> Self {
        self.retry = Some(retry);
        self
    }
    /// Sets `retry.max_retries` only.
    pub fn max_retries(mut self, max_retries: u32) -> Self {
        self.max_retries = Some(max_retries);
        self
    }
    /// Sets the TLS settings.
    pub fn tls(mut self, tls: TlsConfig) -> Self {
        if tls.insecure_skip_verify {
            self.insecure_skip_verify = Some(true);
        }
        self.tls = tls;
        self
    }
    /// Sets the CA certificate file.
    pub fn ca_cert_path(mut self, path: impl Into<PathBuf>) -> Self {
        self.tls.ca_cert_path = Some(path.into());
        self
    }
    /// Sets the CA certificate PEM text.
    pub fn ca_cert_pem(mut self, pem: impl Into<String>) -> Self {
        self.tls.ca_cert_pem = Some(pem.into());
        self
    }
    /// Sets the client certificate and key files.
    pub fn client_cert(mut self, cert: impl Into<PathBuf>, key: impl Into<PathBuf>) -> Self {
        self.tls.client_cert_path = Some(cert.into());
        self.tls.client_key_path = Some(key.into());
        self
    }
    /// Disables certificate verification (tests only).
    pub fn insecure_skip_verify(mut self, skip: bool) -> Self {
        self.insecure_skip_verify = Some(skip);
        self
    }
    /// Sets the proxy URL.
    pub fn proxy(mut self, proxy: impl Into<String>) -> Self {
        self.proxy = Some(proxy.into());
        self
    }
    /// Adds an extra request header.
    pub fn header(mut self, name: impl Into<String>, value: impl Into<String>) -> Self {
        self.headers.push((name.into(), value.into()));
        self
    }
    /// Sets the User-Agent suffix.
    pub fn user_agent_suffix(mut self, suffix: impl Into<String>) -> Self {
        self.user_agent_suffix = Some(suffix.into());
        self
    }
    /// Sets the hooks.
    pub fn hooks(mut self, hooks: Arc<dyn Hooks>) -> Self {
        self.hooks = Some(hooks);
        self
    }

    /// Fills every unset field from the environment (`GROW_<KEY>_*`, then `vendor_url_vars`
    /// for the URL). Invalid values raise `CONFIG` naming the variable.
    pub fn apply_env(self, env: &EnvReader, vendor_url_vars: &[&str]) -> Result<Self> {
        self.apply_env_with(env, &VendorEnv::url_only(vendor_url_vars))
    }

    /// Fills every unset field from the environment: `GROW_<KEY>_*` first, then the vendor
    /// variables of `vendor` for that setting. Invalid values raise `CONFIG` naming the variable.
    pub fn apply_env_with(mut self, env: &EnvReader, vendor: &VendorEnv<'_>) -> Result<Self> {
        if self.url.is_none() {
            self.url = env.string("URL", vendor.url);
        }
        if self.connect_timeout.is_none() {
            self.connect_timeout = env.duration("CONNECT_TIMEOUT", &[])?;
        }
        if self.request_timeout.is_none() {
            self.request_timeout = env.duration("REQUEST_TIMEOUT", &[])?;
        }
        if self.total_timeout.is_none() {
            self.total_timeout = env.duration("TOTAL_TIMEOUT", &[])?;
        }
        if self.max_retries.is_none() && self.retry.is_none() {
            if let Some(n) = env.int("MAX_RETRIES", &[])? {
                let n = u32::try_from(n).map_err(|_| {
                    Error::config(format!(
                        "environment variable {}MAX_RETRIES must be >= 0",
                        env.prefix()
                    ))
                })?;
                self.max_retries = Some(n);
            }
        }
        if self.tls.ca_cert_path.is_none() {
            self.tls.ca_cert_path = env.string("CA_CERT", vendor.ca_cert).map(PathBuf::from);
        }
        if self.tls.client_cert_path.is_none() {
            self.tls.client_cert_path = env
                .string("CLIENT_CERT", vendor.client_cert)
                .map(PathBuf::from);
        }
        if self.tls.client_key_path.is_none() {
            self.tls.client_key_path = env
                .string("CLIENT_KEY", vendor.client_key)
                .map(PathBuf::from);
        }
        if self.insecure_skip_verify.is_none() {
            self.insecure_skip_verify =
                env.bool("INSECURE_SKIP_VERIFY", vendor.insecure_skip_verify)?;
        }
        if self.proxy.is_none() {
            self.proxy = env.string("PROXY", vendor.proxy);
        }
        Ok(self)
    }

    /// Validates and builds; `default_url` is used when no URL was given.
    pub fn build(self, default_url: &str) -> Result<CommonConfig> {
        let raw_url = self.url.as_deref().unwrap_or(default_url);
        let url =
            Url::parse(raw_url).map_err(|_| Error::config("url is not a valid absolute URL"))?;
        if !matches!(url.scheme(), "http" | "https") {
            return Err(Error::config("url scheme must be http or https"));
        }
        let mut retry = self.retry.unwrap_or_default();
        if let Some(n) = self.max_retries {
            retry.max_retries = n;
        }
        retry.validate()?;
        let mut tls = self.tls;
        tls.insecure_skip_verify = self.insecure_skip_verify.unwrap_or(false);
        if tls.client_cert_path.is_some() != tls.client_key_path.is_some() {
            return Err(Error::config(
                "client certificate and client key must be given together",
            ));
        }
        if let Some(proxy) = &self.proxy {
            let parsed =
                Url::parse(proxy).map_err(|_| Error::config("proxy is not a valid URL"))?;
            if !matches!(parsed.scheme(), "http" | "https" | "socks5" | "socks5h") {
                return Err(Error::config("proxy scheme must be http or https"));
            }
        }
        let config = CommonConfig {
            url,
            connect_timeout: self.connect_timeout.unwrap_or(DEFAULT_CONNECT_TIMEOUT),
            request_timeout: self.request_timeout.unwrap_or(DEFAULT_REQUEST_TIMEOUT),
            total_timeout: self.total_timeout.unwrap_or(DEFAULT_TOTAL_TIMEOUT),
            retry,
            tls,
            proxy: self.proxy,
            headers: self.headers,
            user_agent_suffix: self.user_agent_suffix,
            hooks: self.hooks,
        };
        for (name, value) in [
            ("connect_timeout", config.connect_timeout),
            ("request_timeout", config.request_timeout),
            ("total_timeout", config.total_timeout),
        ] {
            if value.is_zero() {
                return Err(Error::config(format!("{name} must be positive")));
            }
        }
        Ok(config)
    }
}