cloud_sdk_testkit/
mock.rs

1//! Deterministic no-allocation mock transport.
2
3use core::fmt;
4use core::sync::atomic::{AtomicUsize, Ordering};
5
6use cloud_sdk::Method;
7use cloud_sdk::transport::{
8    AsyncTransport, BlockingTransport, BoundTransport, EndpointIdentity, EndpointIdentityError,
9    HeaderSensitivity, RequestHeaders, RequestTarget, ResponseContentType, ResponseHeaders,
10    ResponseStorageSanitizer, TransportRequest, TransportResponse,
11};
12
13use crate::{FixtureBodyError, ResponseFixture};
14
15/// Expected request fields for one mock exchange.
16#[derive(Clone, Copy)]
17pub struct ExpectedRequest<'a> {
18    method: Method,
19    target: RequestTarget<'a>,
20    body: &'a [u8],
21    headers: RequestHeaders<'a>,
22}
23
24impl<'a> ExpectedRequest<'a> {
25    /// Creates a bodyless expected request.
26    #[must_use]
27    pub const fn new(method: Method, target: RequestTarget<'a>) -> Self {
28        Self {
29            method,
30            target,
31            body: &[],
32            headers: RequestHeaders::EMPTY,
33        }
34    }
35
36    /// Adds the exact expected request body.
37    #[must_use]
38    pub const fn with_body(mut self, body: &'a [u8]) -> Self {
39        self.body = body;
40        self
41    }
42
43    /// Adds the exact expected ordered request headers.
44    #[must_use]
45    pub const fn with_headers(mut self, headers: RequestHeaders<'a>) -> Self {
46        self.headers = headers;
47        self
48    }
49
50    const fn method(self) -> Method {
51        self.method
52    }
53
54    const fn target(self) -> RequestTarget<'a> {
55        self.target
56    }
57
58    const fn body(self) -> &'a [u8] {
59        self.body
60    }
61
62    const fn headers(self) -> RequestHeaders<'a> {
63        self.headers
64    }
65}
66
67impl fmt::Debug for ExpectedRequest<'_> {
68    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
69        formatter
70            .debug_struct("ExpectedRequest")
71            .field("method", &self.method)
72            .field("target", &"[redacted]")
73            .field("body", &"[redacted]")
74            .field("headers", &self.headers)
75            .finish()
76    }
77}
78
79/// One expected request and deterministic response.
80#[derive(Clone, Copy, Debug)]
81pub struct MockExchange<'a> {
82    request: ExpectedRequest<'a>,
83    response: ResponseFixture<'a>,
84}
85
86impl<'a> MockExchange<'a> {
87    /// Creates one mock exchange.
88    #[must_use]
89    pub const fn new(request: ExpectedRequest<'a>, response: ResponseFixture<'a>) -> Self {
90        Self { request, response }
91    }
92}
93
94/// Deterministic mock transport failure.
95#[derive(Clone, Copy, Debug, Eq, PartialEq)]
96pub enum MockError {
97    /// No expected exchange remains.
98    Exhausted,
99    /// HTTP method differs from the next expectation.
100    MethodMismatch,
101    /// Request target differs from the next expectation.
102    TargetMismatch,
103    /// Request body differs from the next expectation.
104    BodyMismatch,
105    /// Request headers differ from the next expectation.
106    HeadersMismatch,
107    /// Caller response buffer cannot hold the complete fixture body.
108    ResponseBufferTooSmall,
109    /// Internal cursor arithmetic failed closed.
110    CursorOverflow,
111    /// Another request changed the ordered cursor during this exchange.
112    ConcurrentRequest,
113    /// Fixture metadata could not be represented by the core transport.
114    InvalidFixtureMetadata,
115}
116
117impl_static_error!(MockError,
118    Self::Exhausted => "mock transport has no expected exchange remaining",
119    Self::MethodMismatch => "mock request method differs from expectation",
120    Self::TargetMismatch => "mock request target differs from expectation",
121    Self::BodyMismatch => "mock request body differs from expectation",
122    Self::HeadersMismatch => "mock request headers differ from expectation",
123    Self::ResponseBufferTooSmall => "mock response buffer is too small",
124    Self::CursorOverflow => "mock transport cursor overflowed",
125    Self::ConcurrentRequest => "mock transport cursor changed concurrently",
126    Self::InvalidFixtureMetadata => "mock fixture metadata is invalid",
127);
128
129/// Ordered no-allocation mock implementation of [`BlockingTransport`].
130pub struct MockTransport<'a> {
131    exchanges: &'a [MockExchange<'a>],
132    cursor: AtomicUsize,
133    endpoint: Option<EndpointIdentity<'a>>,
134}
135
136impl<'a> MockTransport<'a> {
137    /// Creates a mock over an ordered exchange slice.
138    #[must_use]
139    pub const fn new(exchanges: &'a [MockExchange<'a>]) -> Self {
140        Self {
141            exchanges,
142            cursor: AtomicUsize::new(0),
143            endpoint: None,
144        }
145    }
146
147    /// Binds the mock permanently to one normalized endpoint identity.
148    #[must_use]
149    pub const fn with_endpoint(mut self, endpoint: EndpointIdentity<'a>) -> Self {
150        self.endpoint = Some(endpoint);
151        self
152    }
153
154    /// Returns the number of exchanges not yet consumed.
155    #[must_use]
156    pub fn remaining(&self) -> usize {
157        self.exchanges
158            .len()
159            .saturating_sub(self.cursor.load(Ordering::Acquire))
160    }
161
162    /// Reports whether every expected exchange was consumed.
163    #[must_use]
164    pub fn is_complete(&self) -> bool {
165        self.remaining() == 0
166    }
167
168    fn send_inner<'buffer>(
169        &self,
170        request: TransportRequest<'_>,
171        response_body: &'buffer mut [u8],
172    ) -> Result<TransportResponse<'buffer>, MockError> {
173        let cursor = self.cursor.load(Ordering::Acquire);
174        let exchange = self.exchanges.get(cursor).ok_or(MockError::Exhausted)?;
175        if request.method() != exchange.request.method() {
176            return Err(MockError::MethodMismatch);
177        }
178        if request.target() != exchange.request.target() {
179            return Err(MockError::TargetMismatch);
180        }
181        if request.body() != exchange.request.body() {
182            return Err(MockError::BodyMismatch);
183        }
184        if !request_headers_match(request.headers(), exchange.request.headers()) {
185            return Err(MockError::HeadersMismatch);
186        }
187        let next_cursor = cursor.checked_add(1).ok_or(MockError::CursorOverflow)?;
188        let content_type = exchange
189            .response
190            .content_type()
191            .map(ResponseContentType::new)
192            .transpose()
193            .map_err(|_| MockError::InvalidFixtureMetadata)?;
194        let rate_limit = exchange
195            .response
196            .rate_limit()
197            .map(|value| value.into_rate_limit())
198            .transpose()
199            .map_err(|_| MockError::InvalidFixtureMetadata)?;
200        let mut response_headers = exchange.response.headers();
201        if let Some(value) = exchange.response.content_type() {
202            response_headers
203                .try_push("content-type", value.as_bytes(), HeaderSensitivity::Public)
204                .map_err(|_| MockError::InvalidFixtureMetadata)?;
205        }
206        if let Some(value) = rate_limit {
207            push_rate_limit_headers(&mut response_headers, value)
208                .map_err(|_| MockError::InvalidFixtureMetadata)?;
209        }
210        let body_len =
211            exchange
212                .response
213                .body()
214                .write_to(response_body)
215                .map_err(|error| match error {
216                    FixtureBodyError::OutputTooSmall | FixtureBodyError::TooLarge => {
217                        MockError::ResponseBufferTooSmall
218                    }
219                })?;
220        let initialized = response_body
221            .get(..body_len)
222            .ok_or(MockError::ResponseBufferTooSmall)?;
223        let response = TransportResponse::new(exchange.response.status(), initialized)
224            .with_headers(response_headers);
225        let response = content_type.map_or(response, |value| response.with_content_type(value));
226        let response = rate_limit.map_or(response, |value| response.with_rate_limit(value));
227        self.cursor
228            .compare_exchange(cursor, next_cursor, Ordering::AcqRel, Ordering::Acquire)
229            .map_err(|_| MockError::ConcurrentRequest)?;
230        Ok(response)
231    }
232}
233
234fn request_headers_match(actual: RequestHeaders<'_>, expected: RequestHeaders<'_>) -> bool {
235    let actual = actual.as_slice();
236    let expected = expected.as_slice();
237    actual.len() == expected.len()
238        && actual.iter().zip(expected).all(|(actual, expected)| {
239            actual.name() == expected.name()
240                && actual.value().as_str().as_bytes() == expected.value().as_str().as_bytes()
241                && actual.sensitivity() == expected.sensitivity()
242        })
243}
244
245fn push_rate_limit_headers(
246    headers: &mut ResponseHeaders,
247    rate_limit: cloud_sdk::rate_limit::RateLimit,
248) -> Result<(), ()> {
249    let mut storage = [0_u8; 20];
250    for (name, value) in [
251        ("ratelimit-limit", rate_limit.limit()),
252        ("ratelimit-remaining", rate_limit.remaining()),
253        ("ratelimit-reset", rate_limit.reset_epoch_seconds()),
254    ] {
255        let text = write_decimal(value, &mut storage).ok_or(())?;
256        headers
257            .try_push(name, text.as_bytes(), HeaderSensitivity::Public)
258            .map_err(|_| ())?;
259    }
260    Ok(())
261}
262
263fn write_decimal(value: u64, output: &mut [u8; 20]) -> Option<&str> {
264    let mut value = value;
265    let mut cursor = output.len();
266    loop {
267        cursor = cursor.checked_sub(1)?;
268        let digit = u8::try_from(value % 10).ok()?;
269        *output.get_mut(cursor)? = b'0'.checked_add(digit)?;
270        value /= 10;
271        if value == 0 {
272            break;
273        }
274    }
275    core::str::from_utf8(output.get(cursor..)?).ok()
276}
277
278impl BlockingTransport for MockTransport<'_> {
279    type Error = MockError;
280
281    fn send<'buffer>(
282        &self,
283        request: TransportRequest<'_>,
284        response_body: &'buffer mut [u8],
285    ) -> Result<TransportResponse<'buffer>, Self::Error> {
286        self.send_inner(request, response_body)
287    }
288}
289
290impl AsyncTransport for MockTransport<'_> {
291    type Error = MockError;
292
293    async fn send<'transport, 'request, 'buffer>(
294        &'transport self,
295        request: TransportRequest<'request>,
296        response_body: &'buffer mut [u8],
297    ) -> Result<TransportResponse<'buffer>, Self::Error>
298    where
299        'request: 'transport,
300        'buffer: 'transport,
301    {
302        self.send_inner(request, response_body)
303    }
304}
305
306impl ResponseStorageSanitizer for MockTransport<'_> {
307    fn sanitize_response_storage(&self, response_storage: &mut [u8]) {
308        response_storage.fill(0);
309    }
310}
311
312impl BoundTransport for MockTransport<'_> {
313    fn endpoint_identity(&self) -> Result<EndpointIdentity<'_>, EndpointIdentityError> {
314        self.endpoint.ok_or(EndpointIdentityError::UnboundTransport)
315    }
316}
317
318impl fmt::Debug for MockTransport<'_> {
319    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
320        formatter
321            .debug_struct("MockTransport")
322            .field("remaining", &self.remaining())
323            .finish_non_exhaustive()
324    }
325}
cloud_sdk_testkit/mock.rs

cloud_sdk_testkit/
mock.rs
