rok-core 0.6.1

Core primitives for the rok ecosystem — errors, crypto, i18n, config, DI, and more
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

use axum::{
    http::StatusCode,
    response::{IntoResponse, Response},
    Json,
};
use serde::Serialize;
use std::collections::HashMap;

/// Pagination metadata for collection responses.
#[derive(Debug, Clone, Serialize)]
pub struct PaginationMeta {
    pub total: i64,
    pub page: i64,
    pub per_page: i64,
    pub last_page: i64,
}

impl PaginationMeta {
    pub fn new(total: i64, page: i64, per_page: i64) -> Self {
        let last_page = if per_page > 0 {
            (total + per_page - 1) / per_page
        } else {
            1
        };
        Self {
            total,
            page,
            per_page,
            last_page,
        }
    }
}

/// Standard API response envelope for the Rok ecosystem.
///
/// Produces consistent JSON shapes:
/// - Success: `{ "data": ... }`
/// - Paginated: `{ "data": [...], "meta": { "total", "page", "perPage", "lastPage" } }`
/// - Created: `{ "data": ..., "meta": { "message": "Resource created" } }`
/// - Error: `{ "error": { "code", "message", "statusCode" } }`
/// - Validation: `{ "error": { "code": "E_VALIDATION_FAILURE", "message", "statusCode": 422, "details": {...} } }`
/// - No Content: empty body, 204 status
pub struct ApiResponse {
    status: StatusCode,
    body: serde_json::Value,
}

impl ApiResponse {
    /// 200 OK with data envelope.
    pub fn ok<T: Serialize>(data: T) -> Self {
        Self {
            status: StatusCode::OK,
            body: serde_json::json!({ "data": data }),
        }
    }

    /// 201 Created with data envelope.
    pub fn created<T: Serialize>(data: T) -> Self {
        Self {
            status: StatusCode::CREATED,
            body: serde_json::json!({
                "data": data,
                "meta": { "message": "Resource created" }
            }),
        }
    }

    /// 204 No Content — empty body.
    pub fn no_content() -> Self {
        Self {
            status: StatusCode::NO_CONTENT,
            body: serde_json::Value::Null,
        }
    }

    /// 200 OK with paginated data.
    pub fn paginated<T: Serialize>(data: Vec<T>, pagination: PaginationMeta) -> Self {
        Self {
            status: StatusCode::OK,
            body: serde_json::json!({
                "data": data,
                "meta": pagination,
            }),
        }
    }

    /// Error response with custom status, code, and message.
    pub fn error(code: &'static str, message: impl Into<String>, status: u16) -> Self {
        let status_code = StatusCode::from_u16(status).unwrap_or(StatusCode::INTERNAL_SERVER_ERROR);
        Self {
            status: status_code,
            body: serde_json::json!({
                "error": {
                    "code": code,
                    "message": message.into(),
                    "statusCode": status,
                }
            }),
        }
    }

    /// 422 Validation error response.
    pub fn validation(message: impl Into<String>, errors: HashMap<String, Vec<String>>) -> Self {
        Self {
            status: StatusCode::UNPROCESSABLE_ENTITY,
            body: serde_json::json!({
                "error": {
                    "code": "E_VALIDATION_FAILURE",
                    "message": message.into(),
                    "statusCode": 422,
                    "details": errors,
                }
            }),
        }
    }

    /// Convert from a `StatusCode` with no body.
    pub fn from_status(status: StatusCode) -> Self {
        Self {
            status,
            body: serde_json::Value::Null,
        }
    }

    /// Access the response status code.
    pub fn status_code(&self) -> StatusCode {
        self.status
    }

    /// Consume and return the inner JSON value (for testing).
    pub fn into_body(self) -> serde_json::Value {
        self.body
    }
}

impl IntoResponse for ApiResponse {
    fn into_response(self) -> Response {
        if self.body.is_null() {
            self.status.into_response()
        } else {
            (self.status, Json(self.body)).into_response()
        }
    }
}