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, 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(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        {
207            let response_headers = response
208                .headers_mut()
209                .map_err(|_| MockError::ResponseWriterRejected)?;
210            if let Some(source) = exchange.response.headers() {
211                for header in source.iter() {
212                    response_headers
213                        .try_push(header.name(), header.value(), header.sensitivity())
214                        .map_err(|_| MockError::InvalidFixtureMetadata)?;
215                }
216            }
217            if let Some(value) = exchange.response.content_type() {
218                response_headers
219                    .try_push("content-type", value.as_bytes(), HeaderSensitivity::Public)
220                    .map_err(|_| MockError::InvalidFixtureMetadata)?;
221            }
222            if let Some(value) = rate_limit {
223                push_rate_limit_headers(response_headers, value)
224                    .map_err(|_| MockError::InvalidFixtureMetadata)?;
225            }
226        }
227        let body_len = exchange
228            .response
229            .body()
230            .write_to(
231                response
232                    .body_mut()
233                    .map_err(|_| MockError::ResponseWriterRejected)?,
234            )
235            .map_err(|error| match error {
236                FixtureBodyError::OutputTooSmall | FixtureBodyError::TooLarge => {
237                    MockError::ResponseBufferTooSmall
238                }
239            })?;
240        let mut metadata = ResponseMetadata::EMPTY;
241        if let Some(value) = rate_limit {
242            metadata = metadata.with_rate_limit(value);
243        }
244        self.cursor
245            .compare_exchange(cursor, next_cursor, Ordering::AcqRel, Ordering::Acquire)
246            .map_err(|_| MockError::ConcurrentRequest)?;
247        response
248            .commit(exchange.response.status(), body_len, metadata)
249            .map_err(|_| MockError::ResponseWriterRejected)
250    }
251}
252
253fn request_headers_match(actual: RequestHeaders<'_>, expected: RequestHeaders<'_>) -> bool {
254    let actual = actual.as_slice();
255    let expected = expected.as_slice();
256    actual.len() == expected.len()
257        && actual.iter().zip(expected).all(|(actual, expected)| {
258            actual.name() == expected.name()
259                && actual.value().as_str().as_bytes() == expected.value().as_str().as_bytes()
260                && actual.sensitivity() == expected.sensitivity()
261        })
262}
263
264fn push_rate_limit_headers(
265    headers: &mut ResponseHeaders,
266    rate_limit: cloud_sdk::rate_limit::RateLimit,
267) -> Result<(), ()> {
268    let mut storage = [0_u8; 20];
269    for (name, value) in [
270        ("ratelimit-limit", rate_limit.limit()),
271        ("ratelimit-remaining", rate_limit.remaining()),
272        ("ratelimit-reset", rate_limit.reset_epoch_seconds()),
273    ] {
274        let text = write_decimal(value, &mut storage).ok_or(())?;
275        headers
276            .try_push(name, text.as_bytes(), HeaderSensitivity::Public)
277            .map_err(|_| ())?;
278    }
279    Ok(())
280}
281
282fn write_decimal(value: u64, output: &mut [u8; 20]) -> Option<&str> {
283    let mut value = value;
284    let mut cursor = output.len();
285    loop {
286        cursor = cursor.checked_sub(1)?;
287        let digit = u8::try_from(value % 10).ok()?;
288        *output.get_mut(cursor)? = b'0'.checked_add(digit)?;
289        value /= 10;
290        if value == 0 {
291            break;
292        }
293    }
294    core::str::from_utf8(output.get(cursor..)?).ok()
295}
296
297impl BlockingTransport for MockTransport<'_> {
298    type Error = MockError;
299
300    fn send(
301        &self,
302        request: TransportRequest<'_>,
303        response: &mut ResponseWriter<'_>,
304    ) -> Result<(), Self::Error> {
305        self.send_inner(request, response)
306    }
307}
308
309impl AsyncTransport for MockTransport<'_> {
310    type Error = MockError;
311
312    async fn send<'transport, 'request, 'writer>(
313        &'transport self,
314        request: TransportRequest<'request>,
315        response: &'writer mut ResponseWriter<'_>,
316    ) -> Result<(), Self::Error>
317    where
318        'transport: 'writer,
319        'request: 'writer,
320    {
321        self.send_inner(request, response)
322    }
323}
324
325impl BoundTransport for MockTransport<'_> {
326    fn endpoint_identity(&self) -> Result<EndpointIdentity<'_>, EndpointIdentityError> {
327        self.endpoint.ok_or(EndpointIdentityError::UnboundTransport)
328    }
329}
330
331impl fmt::Debug for MockTransport<'_> {
332    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
333        formatter
334            .debug_struct("MockTransport")
335            .field("remaining", &self.remaining())
336            .finish_non_exhaustive()
337    }
338}
cloud_sdk_testkit/mock.rs

cloud_sdk_testkit/
mock.rs
