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    ResponseMetadata, ResponseStorageSanitizer, ResponseWriter, TransportRequest,
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    /// The core response writer rejected fixture output.
116    ResponseWriterRejected,
117}
118
119impl_static_error!(MockError,
120    Self::Exhausted => "mock transport has no expected exchange remaining",
121    Self::MethodMismatch => "mock request method differs from expectation",
122    Self::TargetMismatch => "mock request target differs from expectation",
123    Self::BodyMismatch => "mock request body differs from expectation",
124    Self::HeadersMismatch => "mock request headers differ from expectation",
125    Self::ResponseBufferTooSmall => "mock response buffer is too small",
126    Self::CursorOverflow => "mock transport cursor overflowed",
127    Self::ConcurrentRequest => "mock transport cursor changed concurrently",
128    Self::InvalidFixtureMetadata => "mock fixture metadata is invalid",
129    Self::ResponseWriterRejected => "mock response writer rejected output",
130);
131
132/// Ordered no-allocation mock implementation of [`BlockingTransport`].
133pub struct MockTransport<'a> {
134    exchanges: &'a [MockExchange<'a>],
135    cursor: AtomicUsize,
136    endpoint: Option<EndpointIdentity<'a>>,
137}
138
139impl<'a> MockTransport<'a> {
140    /// Creates a mock over an ordered exchange slice.
141    #[must_use]
142    pub const fn new(exchanges: &'a [MockExchange<'a>]) -> Self {
143        Self {
144            exchanges,
145            cursor: AtomicUsize::new(0),
146            endpoint: None,
147        }
148    }
149
150    /// Binds the mock permanently to one normalized endpoint identity.
151    #[must_use]
152    pub const fn with_endpoint(mut self, endpoint: EndpointIdentity<'a>) -> Self {
153        self.endpoint = Some(endpoint);
154        self
155    }
156
157    /// Returns the number of exchanges not yet consumed.
158    #[must_use]
159    pub fn remaining(&self) -> usize {
160        self.exchanges
161            .len()
162            .saturating_sub(self.cursor.load(Ordering::Acquire))
163    }
164
165    /// Reports whether every expected exchange was consumed.
166    #[must_use]
167    pub fn is_complete(&self) -> bool {
168        self.remaining() == 0
169    }
170
171    fn send_inner(
172        &self,
173        request: TransportRequest<'_>,
174        response: &mut ResponseWriter<'_>,
175    ) -> Result<(), MockError> {
176        if response.is_committed() {
177            return Err(MockError::ResponseWriterRejected);
178        }
179        let cursor = self.cursor.load(Ordering::Acquire);
180        let exchange = self.exchanges.get(cursor).ok_or(MockError::Exhausted)?;
181        if request.method() != exchange.request.method() {
182            return Err(MockError::MethodMismatch);
183        }
184        if request.target() != exchange.request.target() {
185            return Err(MockError::TargetMismatch);
186        }
187        if request.body() != exchange.request.body() {
188            return Err(MockError::BodyMismatch);
189        }
190        if !request_headers_match(request.headers(), exchange.request.headers()) {
191            return Err(MockError::HeadersMismatch);
192        }
193        let next_cursor = cursor.checked_add(1).ok_or(MockError::CursorOverflow)?;
194        let content_type = exchange
195            .response
196            .content_type()
197            .map(ResponseContentType::new)
198            .transpose()
199            .map_err(|_| MockError::InvalidFixtureMetadata)?;
200        let rate_limit = exchange
201            .response
202            .rate_limit()
203            .map(|value| value.into_rate_limit())
204            .transpose()
205            .map_err(|_| MockError::InvalidFixtureMetadata)?;
206        let mut response_headers = exchange.response.headers();
207        if let Some(value) = exchange.response.content_type() {
208            response_headers
209                .try_push("content-type", value.as_bytes(), HeaderSensitivity::Public)
210                .map_err(|_| MockError::InvalidFixtureMetadata)?;
211        }
212        if let Some(value) = rate_limit {
213            push_rate_limit_headers(&mut response_headers, value)
214                .map_err(|_| MockError::InvalidFixtureMetadata)?;
215        }
216        let body_len = exchange
217            .response
218            .body()
219            .write_to(
220                response
221                    .body_mut()
222                    .map_err(|_| MockError::ResponseWriterRejected)?,
223            )
224            .map_err(|error| match error {
225                FixtureBodyError::OutputTooSmall | FixtureBodyError::TooLarge => {
226                    MockError::ResponseBufferTooSmall
227                }
228            })?;
229        let metadata = ResponseMetadata::EMPTY.with_headers(response_headers);
230        let metadata = content_type.map_or(metadata, |value| metadata.with_content_type(value));
231        let metadata = rate_limit.map_or(metadata, |value| metadata.with_rate_limit(value));
232        self.cursor
233            .compare_exchange(cursor, next_cursor, Ordering::AcqRel, Ordering::Acquire)
234            .map_err(|_| MockError::ConcurrentRequest)?;
235        response
236            .commit(exchange.response.status(), body_len, metadata)
237            .map_err(|_| MockError::ResponseWriterRejected)
238    }
239}
240
241fn request_headers_match(actual: RequestHeaders<'_>, expected: RequestHeaders<'_>) -> bool {
242    let actual = actual.as_slice();
243    let expected = expected.as_slice();
244    actual.len() == expected.len()
245        && actual.iter().zip(expected).all(|(actual, expected)| {
246            actual.name() == expected.name()
247                && actual.value().as_str().as_bytes() == expected.value().as_str().as_bytes()
248                && actual.sensitivity() == expected.sensitivity()
249        })
250}
251
252fn push_rate_limit_headers(
253    headers: &mut ResponseHeaders,
254    rate_limit: cloud_sdk::rate_limit::RateLimit,
255) -> Result<(), ()> {
256    let mut storage = [0_u8; 20];
257    for (name, value) in [
258        ("ratelimit-limit", rate_limit.limit()),
259        ("ratelimit-remaining", rate_limit.remaining()),
260        ("ratelimit-reset", rate_limit.reset_epoch_seconds()),
261    ] {
262        let text = write_decimal(value, &mut storage).ok_or(())?;
263        headers
264            .try_push(name, text.as_bytes(), HeaderSensitivity::Public)
265            .map_err(|_| ())?;
266    }
267    Ok(())
268}
269
270fn write_decimal(value: u64, output: &mut [u8; 20]) -> Option<&str> {
271    let mut value = value;
272    let mut cursor = output.len();
273    loop {
274        cursor = cursor.checked_sub(1)?;
275        let digit = u8::try_from(value % 10).ok()?;
276        *output.get_mut(cursor)? = b'0'.checked_add(digit)?;
277        value /= 10;
278        if value == 0 {
279            break;
280        }
281    }
282    core::str::from_utf8(output.get(cursor..)?).ok()
283}
284
285impl BlockingTransport for MockTransport<'_> {
286    type Error = MockError;
287
288    fn send(
289        &self,
290        request: TransportRequest<'_>,
291        response: &mut ResponseWriter<'_>,
292    ) -> Result<(), Self::Error> {
293        self.send_inner(request, response)
294    }
295}
296
297impl AsyncTransport for MockTransport<'_> {
298    type Error = MockError;
299
300    async fn send<'transport, 'request, 'writer>(
301        &'transport self,
302        request: TransportRequest<'request>,
303        response: &'writer mut ResponseWriter<'_>,
304    ) -> Result<(), Self::Error>
305    where
306        'transport: 'writer,
307        'request: 'writer,
308    {
309        self.send_inner(request, response)
310    }
311}
312
313impl ResponseStorageSanitizer for MockTransport<'_> {
314    fn sanitize_response_storage(&self, response_storage: &mut [u8]) {
315        response_storage.fill(0);
316    }
317}
318
319impl BoundTransport for MockTransport<'_> {
320    fn endpoint_identity(&self) -> Result<EndpointIdentity<'_>, EndpointIdentityError> {
321        self.endpoint.ok_or(EndpointIdentityError::UnboundTransport)
322    }
323}
324
325impl fmt::Debug for MockTransport<'_> {
326    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
327        formatter
328            .debug_struct("MockTransport")
329            .field("remaining", &self.remaining())
330            .finish_non_exhaustive()
331    }
332}
cloud_sdk_testkit/mock.rs

cloud_sdk_testkit/
mock.rs
