socle 2.1.0

Opinionated axum service bootstrap: telemetry, database, rate limiting, and shutdown in one builder
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

//! Telemetry port — initialisation and shutdown abstraction.
//!
//! Implement [`TelemetryProvider`] to plug in a full OTel SDK (e.g.
//! `otel-bootstrap`) without forking [`crate::ServiceBootstrap::serve`].
//!
//! The built-in provider (`BasicTelemetryProvider`) initialises
//! `tracing_subscriber` from `RUST_LOG` and is used when
//! [`crate::ServiceBootstrap::with_telemetry`] is called without an explicit
//! provider.

use std::future::Future;
use std::pin::Pin;

/// Extension point for telemetry initialisation.
///
/// Wrapper crates supply a concrete implementation; socle calls `init` at
/// the start of `serve()` and registers `on_shutdown` as a drain hook after the
/// HTTP server stops.
///
/// ```rust,no_run
/// use std::future::Future;
/// use std::pin::Pin;
/// use socle::ports::telemetry::TelemetryProvider;
/// use socle::Result;
///
/// struct MyOtelProvider;
///
/// impl TelemetryProvider for MyOtelProvider {
///     fn init(&self, service_name: &str) -> Result<()> {
///         // wire up the OTel SDK …
///         Ok(())
///     }
///
///     fn on_shutdown(&self) -> Pin<Box<dyn Future<Output = ()> + Send>> {
///         Box::pin(async {
///             // flush spans and metrics …
///         })
///     }
/// }
/// ```
pub trait TelemetryProvider: Send + Sync + 'static {
    /// Initialise telemetry for `service_name`. Called once before the HTTP
    /// server starts. Return an error to abort startup.
    fn init(&self, service_name: &str) -> crate::error::Result<()>;

    /// Async drain to run after the HTTP server stops (flush spans, metrics,
    /// etc.). Default is a no-op.
    fn on_shutdown(&self) -> Pin<Box<dyn Future<Output = ()> + Send>> {
        Box::pin(async {})
    }
}

/// Built-in provider — initialises `tracing_subscriber` from `RUST_LOG`.
///
/// Used when [`crate::ServiceBootstrap::with_telemetry`] is called without an
/// explicit provider. Override with
/// [`crate::ServiceBootstrap::with_telemetry_provider`] to plug in OTLP.
pub struct BasicTelemetryProvider;

impl TelemetryProvider for BasicTelemetryProvider {
    fn init(&self, _service_name: &str) -> crate::error::Result<()> {
        crate::adapters::observability::telemetry::init_basic_tracing();
        Ok(())
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    struct NoopProvider;

    impl TelemetryProvider for NoopProvider {
        fn init(&self, _: &str) -> crate::error::Result<()> {
            Ok(())
        }
    }

    #[tokio::test]
    async fn basic_provider_init_is_idempotent() {
        let p = BasicTelemetryProvider;
        assert!(p.init("svc").is_ok());
        assert!(p.init("svc").is_ok());
    }

    #[tokio::test]
    async fn default_on_shutdown_completes() {
        let p = NoopProvider;
        p.on_shutdown().await; // must not hang
    }

    #[tokio::test]
    async fn basic_provider_on_shutdown_is_noop() {
        let p = BasicTelemetryProvider;
        p.on_shutdown().await;
    }
}