rama 0.3.0

modular service framework
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

//! This example demonstrates how to use the abortable service
//! to allow one to cancel the transport layer from within the application layer.
//!
//! ```sh
//! cargo run --example http_abort --features=http-full
//! ```
//!
//! # Expected output
//!
//! The server will start and listen on `:62047`. You can use your curl to interact with the service:
//!
//! ```sh
//! curl -v http://127.0.0.1:62047
//! ```
//!
//! abort will drop connection before response received:
//!
//! ```sh
//! curl -v http://127.0.0.1:62047/abort
//! ```

// rama provides everything out of the box to build a complete web service.

#![expect(
    clippy::unwrap_used,
    clippy::expect_used,
    reason = "example/test/bench: panic-on-error and print-for-output are the standard patterns for demos and harnesses"
)]

use rama::{
    Layer,
    extensions::Extensions,
    http::{
        StatusCode,
        headers::exotic::XClacksOverhead,
        layer::{
            error_handling::ErrorHandlerLayer, set_header::SetResponseHeaderLayer,
            trace::TraceLayer,
        },
        server::HttpServer,
        service::web::Router,
    },
    layer::{AbortableLayer, abort::AbortController},
    rt::Executor,
    tcp::server::TcpListener,
    telemetry::tracing::{
        self,
        level_filters::LevelFilter,
        subscriber::{EnvFilter, fmt, layer::SubscriberExt, util::SubscriberInitExt},
    },
};

/// Everything else we need is provided by the standard library, community crates or tokio.
use std::{sync::Arc, time::Duration};

const ADDRESS: &str = "127.0.0.1:62047";

#[tokio::main]
async fn main() {
    tracing::subscriber::registry()
        .with(fmt::layer())
        .with(
            EnvFilter::builder()
                .with_default_directive(LevelFilter::DEBUG.into())
                .from_env_lossy(),
        )
        .init();

    let graceful = rama::graceful::Shutdown::default();

    let router =
        Router::new()
            .with_get("/", StatusCode::OK)
            .with_get("/abort", async |ext: Extensions| {
                ext.get_ref::<AbortController>().unwrap().abort().await;
                StatusCode::INTERNAL_SERVER_ERROR
            });

    let http_middlewares = (
        TraceLayer::new_for_http(),
        SetResponseHeaderLayer::<XClacksOverhead>::if_not_present_default_typed(),
        ErrorHandlerLayer::new(),
    );

    let tcp_svc = AbortableLayer::new().into_layer(
        HttpServer::auto(Executor::graceful(graceful.guard()))
            .service(Arc::new(http_middlewares.into_layer(router))),
    );

    graceful.spawn_task_fn(async |guard| {
        tracing::info!("running service at: {ADDRESS}");
        let exec = Executor::graceful(guard);
        TcpListener::bind_address(ADDRESS, exec)
            .await
            .unwrap()
            .serve(tcp_svc)
            .await;
    });

    graceful
        .shutdown_with_limit(Duration::from_secs(30))
        .await
        .expect("graceful shutdown");
}