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
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
//! gRPC **semantics** for a gateway — not a gRPC transport.
//!
//! This module provides the vocabulary needed to map between HTTP and gRPC at a
//! boundary: the canonical status codes, and `grpc-timeout` header parsing so a
//! deadline propagated by a gRPC client can be honoured.
//!
//! It does **not** provide a transport. There is no codegen, no `.proto`
//! handling, no service trait, no channel, and no client — `tonic` and `prost`
//! appear nowhere in the workspace. Nothing here can speak gRPC to anything.
//!
//! The module and its feature were called `grpc`, which implied otherwise at
//! the point of `cargo add` — before anyone reads a caveat. See
//! [ADR 0007](https://github.com/ManirajKatuwal/krab-pub/blob/main/docs/adr/0007-grpc-feature-disposition.md).
//!
//! A real transport is not foreclosed; it is simply a separate piece of work
//! with its own ADR.
use std::time::Duration;
/// gRPC status codes as defined by the wire protocol.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u16)]
pub enum GrpcStatusCode {
/// Success.
Ok = 0,
/// The operation was cancelled, typically by the caller.
Cancelled = 1,
/// An unknown error; also what [`GrpcStatusCode::from_u16`] returns for an
/// out-of-range value.
Unknown = 2,
/// The client supplied an invalid argument, whatever the system state.
InvalidArgument = 3,
/// The deadline expired before the operation completed.
DeadlineExceeded = 4,
/// A requested entity was not found.
NotFound = 5,
/// The entity the client tried to create already exists.
AlreadyExists = 6,
/// The caller is identified but not permitted to do this.
PermissionDenied = 7,
/// A resource, such as a quota or rate limit, is exhausted.
ResourceExhausted = 8,
/// The system is not in the state the operation requires.
FailedPrecondition = 9,
/// The operation was aborted, typically by a concurrency conflict.
Aborted = 10,
/// The operation was attempted past a valid range.
OutOfRange = 11,
/// The operation is not implemented or not supported.
Unimplemented = 12,
/// An internal invariant was broken.
Internal = 13,
/// The service is currently unavailable; usually transient and retryable.
Unavailable = 14,
/// Unrecoverable data loss or corruption.
DataLoss = 15,
/// The request lacks valid authentication credentials.
Unauthenticated = 16,
}
impl GrpcStatusCode {
/// The code with numeric value `value`; any value above 16 maps to
/// [`GrpcStatusCode::Unknown`].
pub fn from_u16(value: u16) -> Self {
match value {
0 => Self::Ok,
1 => Self::Cancelled,
2 => Self::Unknown,
3 => Self::InvalidArgument,
4 => Self::DeadlineExceeded,
5 => Self::NotFound,
6 => Self::AlreadyExists,
7 => Self::PermissionDenied,
8 => Self::ResourceExhausted,
9 => Self::FailedPrecondition,
10 => Self::Aborted,
11 => Self::OutOfRange,
12 => Self::Unimplemented,
13 => Self::Internal,
14 => Self::Unavailable,
15 => Self::DataLoss,
16 => Self::Unauthenticated,
_ => Self::Unknown,
}
}
}
/// A gRPC call outcome: the status code and its message (the `grpc-status`
/// and `grpc-message` trailers).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct GrpcStatus {
/// The status code.
pub code: GrpcStatusCode,
/// Developer-facing description; empty on success.
pub message: String,
}
impl GrpcStatus {
/// [`GrpcStatusCode::Ok`] with an empty message.
pub fn ok() -> Self {
Self {
code: GrpcStatusCode::Ok,
message: String::new(),
}
}
/// A status with `code` and `message`. Does not check that `code` is an
/// error code.
pub fn error(code: GrpcStatusCode, message: impl Into<String>) -> Self {
Self {
code,
message: message.into(),
}
}
}
/// Validate an HTTP content type for gRPC requests.
pub fn is_grpc_content_type(value: &str) -> bool {
let value = value.trim().to_ascii_lowercase();
value == "application/grpc" || value.starts_with("application/grpc+")
}
/// Parse the `grpc-timeout` header value.
///
/// Supported units:
/// - `H` hours
/// - `M` minutes
/// - `S` seconds
/// - `m` milliseconds
/// - `u` microseconds
/// - `n` nanoseconds
pub fn parse_grpc_timeout(value: &str) -> Option<Duration> {
let value = value.trim();
if value.len() < 2 {
return None;
}
let (num_part, unit_part) = value.split_at(value.len() - 1);
let amount = num_part.parse::<u64>().ok()?;
let unit = unit_part.chars().next()?;
match unit {
'H' => Some(Duration::from_secs(amount.saturating_mul(60 * 60))),
'M' => Some(Duration::from_secs(amount.saturating_mul(60))),
'S' => Some(Duration::from_secs(amount)),
'm' => Some(Duration::from_millis(amount)),
'u' => Some(Duration::from_micros(amount)),
'n' => Some(Duration::from_nanos(amount)),
_ => None,
}
}
/// Format a `grpc-timeout` header value from a duration.
///
/// Uses milliseconds by default to keep precision while remaining readable.
pub fn format_grpc_timeout(duration: Duration) -> String {
format!("{}m", duration.as_millis())
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn grpc_content_type_validation_accepts_expected_values() {
assert!(is_grpc_content_type("application/grpc"));
assert!(is_grpc_content_type("application/grpc+proto"));
assert!(is_grpc_content_type("application/grpc+json"));
assert!(!is_grpc_content_type("application/json"));
}
#[test]
fn grpc_timeout_parsing_supports_all_units() {
assert_eq!(parse_grpc_timeout("1H"), Some(Duration::from_secs(3600)));
assert_eq!(parse_grpc_timeout("2M"), Some(Duration::from_secs(120)));
assert_eq!(parse_grpc_timeout("3S"), Some(Duration::from_secs(3)));
assert_eq!(parse_grpc_timeout("4m"), Some(Duration::from_millis(4)));
assert_eq!(parse_grpc_timeout("5u"), Some(Duration::from_micros(5)));
assert_eq!(parse_grpc_timeout("6n"), Some(Duration::from_nanos(6)));
}
#[test]
fn grpc_timeout_parsing_rejects_invalid_values() {
assert_eq!(parse_grpc_timeout(""), None);
assert_eq!(parse_grpc_timeout("x"), None);
assert_eq!(parse_grpc_timeout("10Q"), None);
}
#[test]
fn grpc_timeout_formatter_uses_milliseconds() {
assert_eq!(format_grpc_timeout(Duration::from_millis(250)), "250m");
}
#[test]
fn status_code_round_trip_handles_unknown_values() {
assert_eq!(GrpcStatusCode::from_u16(0), GrpcStatusCode::Ok);
assert_eq!(
GrpcStatusCode::from_u16(16),
GrpcStatusCode::Unauthenticated
);
assert_eq!(GrpcStatusCode::from_u16(999), GrpcStatusCode::Unknown);
}
}