cf-gears-api-gateway 0.4.0

API Gateway module
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

use axum::{
    extract::Extension,
    http::StatusCode,
    response::{Html, IntoResponse, Json, Response},
    routing::{MethodRouter, get},
};
use chrono::{SecondsFormat, Utc};
use serde_json::json;
use std::sync::Arc;
use std::time::Duration;
use toolkit::RestHealthcheckRegistry;

/// Per-check timeout (from `ApiGatewayConfig::healthcheck_timeout_ms`), injected as an
/// `Extension`. A newtype avoids colliding with any other `Duration` extension.
#[derive(Clone, Copy)]
pub struct HealthcheckTimeout(pub Duration);

/// Returns a 501 Not Implemented handler for operations without implementations
#[allow(dead_code)]
pub fn placeholder_handler_501() -> MethodRouter {
    get(|| async move {
        (
            StatusCode::NOT_IMPLEMENTED,
            Json(json!({
                "message": "Handler not implemented - will be routed via gRPC in future",
                "timestamp": Utc::now().to_rfc3339_opts(SecondsFormat::Millis, true)
            })),
        )
    })
}

/// `GET /health`: runs all checks, returns JSON with per-component detail. Public (no auth) in
/// every serving mode; the per-component detail is protected by network placement, not auth,
/// and check messages are sanitized. 200 (Healthy/Degraded), 503 (Unhealthy).
pub async fn health_detail(
    Extension(registry): Extension<Arc<RestHealthcheckRegistry>>,
    Extension(timeout): Extension<HealthcheckTimeout>,
) -> Response {
    let report = registry.report(timeout.0).await;
    let status_code = status_for_report(report.is_ready());
    let body = Json(json!({
        "status": report.status,
        "timestamp": Utc::now().to_rfc3339_opts(SecondsFormat::Millis, true),
        "components": report.components,
    }));
    (status_code, body).into_response()
}

/// `GET /readyz`: runs all checks, public, status code only (no detail).
/// 200 (Healthy/Degraded), 503 (Unhealthy).
pub async fn readyz_check(
    Extension(registry): Extension<Arc<RestHealthcheckRegistry>>,
    Extension(timeout): Extension<HealthcheckTimeout>,
) -> StatusCode {
    let report = registry.report(timeout.0).await;
    status_for_report(report.is_ready())
}

fn status_for_report(report_ready: bool) -> StatusCode {
    if report_ready {
        StatusCode::OK
    } else {
        StatusCode::SERVICE_UNAVAILABLE
    }
}

#[cfg(not(feature = "embed_elements"))]
pub fn serve_docs(prefix_path: &str) -> Html<String> {
    let openapi_url = if prefix_path.is_empty() {
        String::from("/openapi.json")
    } else {
        format!("{prefix_path}/openapi.json")
    };
    // External mode: load from CDN @latest
    Html(format!(
        r#"<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8"/>
  <title>API Docs</title>
  <script src="https://unpkg.com/@stoplight/elements@latest/web-components.min.js"></script>
  <link rel="stylesheet" href="https://unpkg.com/@stoplight/elements@latest/styles.min.css">
</head>
<body>
  <elements-api apiDescriptionUrl="{openapi_url}" router="hash" layout="sidebar"></elements-api>
</body>
</html>"#,
    ))
}

#[cfg(feature = "embed_elements")]
pub fn serve_docs(prefix_path: &str) -> Html<String> {
    let (openapi_url, js_url, css_url) = if prefix_path.is_empty() {
        (
            String::from("/openapi.json"),
            String::from("/docs/assets/web-components.min.js"),
            String::from("/docs/assets/styles.min.css"),
        )
    } else {
        (
            format!("{prefix_path}/openapi.json"),
            format!("{prefix_path}/docs/assets/web-components.min.js"),
            format!("{prefix_path}/docs/assets/styles.min.css"),
        )
    };

    // Embedded mode: reference local embedded assets
    Html(format!(
        r#"<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8"/>
  <title>API Docs</title>
  <script src="{js_url}"></script>
  <link rel="stylesheet" href="{css_url}">
</head>
<body>
  <elements-api apiDescriptionUrl="{openapi_url}" router="hash" layout="sidebar"></elements-api>
</body>
</html>"#,
    ))
}