socle 2.4.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
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

//! End-to-end integration tests — spin up a real `ServiceBootstrap` server on a
//! random port, hit it with `reqwest`, assert responses.

use axum::{Router, routing::get};
use socle::{BootstrapCtx, ServiceBootstrap, assert_span, testing::TestClient};
use tokio::sync::oneshot;

// ── helpers ───────────────────────────────────────────────────────────────────

/// Bind on a random port, spawn the service in the background, return a
/// `TestClient` pre-pointed at the bound address and a shutdown sender.
/// Dropping the sender stops the server.
async fn spawn_service(
    build: impl FnOnce(ServiceBootstrap) -> ServiceBootstrap,
) -> (TestClient, oneshot::Sender<()>) {
    let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
        .await
        .expect("bind");
    let addr = listener.local_addr().expect("local_addr");
    let (tx, rx) = oneshot::channel::<()>();

    let svc = build(ServiceBootstrap::new("test-service"));
    tokio::spawn(async move {
        svc.serve_with_shutdown(listener, async {
            rx.await.ok();
        })
        .await
        .ok();
    });

    // Give the Tokio task a moment to start accepting connections.
    tokio::time::sleep(std::time::Duration::from_millis(20)).await;

    (TestClient::new(format!("http://{addr}")), tx)
}

// ── health endpoint ───────────────────────────────────────────────────────────

#[tokio::test]
async fn health_liveness_returns_200() {
    let (client, _stop) = spawn_service(|s| s.with_router(|_: &BootstrapCtx| Router::new())).await;

    let resp = client.get("/health/live").await;
    assert_eq!(resp.status(), 200);
}

#[tokio::test]
async fn health_readiness_returns_200_when_no_checks_registered() {
    let (client, _stop) = spawn_service(|s| s.with_router(|_: &BootstrapCtx| Router::new())).await;

    let resp = client.get("/health/ready").await;
    assert_eq!(resp.status(), 200);
}

// ── user routes ───────────────────────────────────────────────────────────────

#[tokio::test]
async fn user_route_is_reachable() {
    let (client, _stop) = spawn_service(|s| {
        s.with_router(|_: &BootstrapCtx| Router::new().route("/hello", get(|| async { "world" })))
    })
    .await;

    let resp = client.get("/hello").await;
    assert_eq!(resp.status(), 200);
    assert_eq!(resp.text().await.unwrap(), "world");
}

// ── 404 fallback ──────────────────────────────────────────────────────────────

#[tokio::test]
async fn unknown_route_returns_404_problem_json() {
    let (client, _stop) = spawn_service(|s| s.with_router(|_: &BootstrapCtx| Router::new())).await;

    let resp = client.get("/does-not-exist").await;
    assert_eq!(resp.status(), 404);

    let ct = resp
        .headers()
        .get("content-type")
        .and_then(|v| v.to_str().ok())
        .unwrap_or("");
    assert!(
        ct.contains("application/problem+json"),
        "expected problem+json, got {ct}"
    );
}

// ── rate limiting ─────────────────────────────────────────────────────────────

#[cfg(feature = "ratelimit-memory")]
#[tokio::test]
async fn rate_limit_blocks_after_limit_exceeded() {
    use socle::RateLimitBackend;

    let (client, _stop) = spawn_service(|s| {
        s.with_rate_limit(RateLimitBackend {
            limit: 2,
            window_secs: 60,
        })
        .with_router(|_: &BootstrapCtx| Router::new().route("/", get(|| async { "ok" })))
    })
    .await;

    assert_eq!(client.get("/").await.status(), 200);
    assert_eq!(client.get("/").await.status(), 200);
    assert_eq!(client.get("/").await.status(), 429);
}

// ── span capture ──────────────────────────────────────────────────────────────

#[tokio::test]
async fn span_capture_records_closed_span() {
    use socle::testing::trace::init_capture_tracing;

    let exporter = init_capture_tracing();
    exporter.drain(); // clear any spans from prior tests

    tracing::info_span!("test_op").in_scope(|| {});

    let spans = exporter.spans();
    assert_span!(spans, name = "test_op");
}

#[tokio::test]
async fn capture_exporter_drain_empties_buffer() {
    use socle::testing::trace::init_capture_tracing;

    let exporter = init_capture_tracing();
    exporter.drain();

    tracing::info_span!("drain_op").in_scope(|| {});

    let drained = exporter.drain();
    assert!(drained.iter().any(|s| s.name == "drain_op"));
    assert!(exporter.spans().is_empty());
}

#[tokio::test]
async fn test_app_builder_serves_and_shuts_down() {
    use axum::http::StatusCode;
    use socle::testing::{TestApp, TestClient};

    let router = Router::new().route("/ping", get(|| async { StatusCode::OK }));
    let app = TestApp::builder().router(router).build().await;

    let client: TestClient = app.client();
    let resp = client.get("/ping").await;
    assert_eq!(resp.status(), 200);

    app.shutdown().await;
}