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
204
205
206
207
208
209
210
211
212
213
#[cfg(feature = "http-client-cookies")]
use crate::api::http::cookies::CookieRequestContext;
use crate::api::http::http_request_method::HttpRequestMethod;
use crate::api::http::http_response::HttpResponseResult;
use crate::api::http::retry::RetryPolicy;
use async_trait::async_trait;
use bytes::Bytes;
use http::HeaderMap;
/// Request object consumed by an HTTP client.
///
/// Implementations own callback state and are moved to the callback lane after the final
/// attempt. `get_req_data` must return the same body for every attempt when retries are enabled.
///
/// Requests may own application context as fields or capture it in their callbacks.
/// The SDK only requires `Send + 'static`; request implementations may own
/// `FnOnce + Send` callbacks that are not `Sync`, `Clone`, or `Debug`.
#[async_trait]
pub trait HttpRequestTrait: Send + 'static {
/// Return the request target relative to the client's configured base URL.
///
/// The worker reads this value for each attempt. Absolute or cross-origin
/// targets fail validation after admission and are delivered through the
/// terminal callback; they are not returned as an admission rejection.
fn get_path(&self) -> String;
/// Return the HTTP method for this request.
///
/// Invalid extension tokens fail validation after admission, before transport
/// starts. The terminal callback receives `InvalidInput` at `RequestBuild`.
fn get_method(&self) -> HttpRequestMethod;
/// Return a textual request body for legacy request implementations.
///
/// The default is an empty body. Implementations that need arbitrary bytes
/// should override [`Self::get_req_body`] instead; if both are overridden,
/// the byte-oriented method is authoritative.
fn get_req_data(&self) -> String {
String::new()
}
/// Return the owned bytes sent as the request body.
///
/// This method is called once for each attempt. A retry policy may call it
/// again, so a retryable request must return equivalent replayable data.
fn get_req_body(&self) -> Bytes {
Bytes::from(self.get_req_data())
}
/// Report whether this request has a body even when its byte representation is empty.
///
/// The default is `false` and does not call a body provider. Requests with
/// non-empty bytes are recognized from [`Self::get_req_body`]; override
/// this method only for an explicit empty body that still needs a body
/// framing header.
fn has_req_body(&self) -> bool {
false
}
/// Return request headers to merge over the client's common headers.
///
/// Hop-by-hop headers are rejected during configuration/dispatch. The
/// default returns an empty map.
fn headers(&self) -> HeaderMap {
HeaderMap::new()
}
/// Return SameSite context for this logical request.
#[cfg(feature = "http-client-cookies")]
fn cookie_context(&self) -> CookieRequestContext {
CookieRequestContext::default()
}
/// Return the retry policy requested by this request.
///
/// A policy with no retries allows the client default to remain in effect
/// when using [`crate::api::http::HttpClient::send`]; explicit options can always override it.
/// `send` and `send_wait` evaluate this provider before admission, on the
/// caller's thread or submitting future. A provider panic unwinds there;
/// ownership recovery is guaranteed for returned errors, not for panics.
fn retry_policy(&self) -> RetryPolicy {
RetryPolicy::no_retry()
}
/// Observe response headers on the callback lane. The default implementation is a no-op.
/// The callback may inspect the headers but cannot mutate worker state or
/// replace the eventual response. Only fully buffered `Ok` responses invoke
/// this hook. Body failures expose received headers through
/// [`crate::api::error::NetError::http_response_head`] in the terminal callback.
fn on_response_headers(&self, _headers: &HeaderMap) {}
/// Consume this request with the final result.
///
/// Once submission succeeds, the callback is invoked exactly once after the
/// final attempt, whether the operation succeeded, exhausted its retry budget, was cancelled, or
/// failed before a response was available. It runs on the callback lane and
/// receives ownership of the request object and response/error result.
/// Rejected submissions return the original request in `EnqueueError` and
/// do not invoke this callback. Abnormal worker termination and callback
/// panics are reported by the request handle's completion state.
async fn deal_with_response(self: Box<Self>, result: HttpResponseResult);
}
// Forward all providers, including byte bodies and feature-gated metadata. The
// consuming callback removes exactly one box layer, so nested boxes work too.
#[async_trait]
impl<T> HttpRequestTrait for Box<T>
where
T: HttpRequestTrait + ?Sized,
{
fn get_path(&self) -> String {
(**self).get_path()
}
fn get_method(&self) -> HttpRequestMethod {
(**self).get_method()
}
fn get_req_data(&self) -> String {
(**self).get_req_data()
}
fn get_req_body(&self) -> Bytes {
(**self).get_req_body()
}
fn has_req_body(&self) -> bool {
(**self).has_req_body()
}
fn headers(&self) -> HeaderMap {
(**self).headers()
}
#[cfg(feature = "http-client-cookies")]
fn cookie_context(&self) -> CookieRequestContext {
(**self).cookie_context()
}
fn retry_policy(&self) -> RetryPolicy {
(**self).retry_policy()
}
fn on_response_headers(&self, headers: &HeaderMap) {
(**self).on_response_headers(headers);
}
async fn deal_with_response(self: Box<Self>, result: HttpResponseResult) {
(*self).deal_with_response(result).await;
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::api::http::http_response::HttpResponse;
use http::StatusCode;
type TestResult = Result<(), Box<dyn std::error::Error + Send + Sync>>;
fn check(condition: bool, message: &str) -> TestResult {
if condition {
Ok(())
} else {
Err(std::io::Error::other(message).into())
}
}
struct EmptyRequest;
#[async_trait]
impl HttpRequestTrait for EmptyRequest {
fn get_path(&self) -> String {
"/health".to_owned()
}
fn get_method(&self) -> HttpRequestMethod {
HttpRequestMethod::GET
}
async fn deal_with_response(self: Box<Self>, result: HttpResponseResult) {
let _ = result;
}
}
#[test]
fn defaults_keep_request_contract_replay_safe_and_header_free() -> TestResult {
let request = EmptyRequest;
check(request.get_path() == "/health", "path contract changed")?;
check(
request.get_method() == HttpRequestMethod::GET,
"method contract changed",
)?;
check(
request.get_req_data().is_empty(),
"default body must be empty",
)?;
check(
request.headers().is_empty(),
"default headers must be empty",
)?;
check(
request.retry_policy().max_retries() == 0,
"default requests must not retry",
)
}
#[tokio::test]
async fn callback_receives_owned_result_contract() -> TestResult {
let response = HttpResponse::new(
StatusCode::NO_CONTENT,
HeaderMap::new(),
bytes::Bytes::new(),
1,
crate::api::http::http_response::HttpRequestId(1),
);
Box::new(EmptyRequest)
.deal_with_response(Ok(response))
.await;
Ok(())
}
}