Skip to main content

jev_client/
transport.rs

1//! The seam between callers and the network.
2
3use std::future::Future;
4use std::sync::Arc;
5use std::time::Duration;
6
7use crate::error::Error;
8use crate::models::ModelList;
9use crate::request::Request;
10use crate::response::Response;
11
12/// Something that can carry requests to the TypeSafe API.
13///
14/// Code that needs the API depends on this trait rather than on
15/// [`HttpTransport`](crate::HttpTransport), so it can be tested with an in-memory fake that
16/// returns canned [`Reply`] values and never touches a socket.
17///
18/// The methods return `Send` futures, so a transport can be shared across the tasks of a
19/// multi-threaded runtime. An implementation may simply write `async fn`. `&T` and `Arc<T>` are
20/// transports whenever `T` is, which is how concurrent work shares one connection pool.
21pub trait Transport: Send + Sync {
22    /// Evaluates a request: `POST /v1/systemone`.
23    fn evaluate(
24        &self,
25        request: &Request,
26    ) -> impl Future<Output = Result<Reply<Response>, Error>> + Send;
27
28    /// Lists the model names the account can use: `GET /v1/models`.
29    fn list_models(&self) -> impl Future<Output = Result<Reply<ModelList>, Error>> + Send;
30}
31
32impl<T: Transport + ?Sized> Transport for &T {
33    fn evaluate(
34        &self,
35        request: &Request,
36    ) -> impl Future<Output = Result<Reply<Response>, Error>> + Send {
37        (**self).evaluate(request)
38    }
39
40    fn list_models(&self) -> impl Future<Output = Result<Reply<ModelList>, Error>> + Send {
41        (**self).list_models()
42    }
43}
44
45impl<T: Transport + ?Sized> Transport for Arc<T> {
46    fn evaluate(
47        &self,
48        request: &Request,
49    ) -> impl Future<Output = Result<Reply<Response>, Error>> + Send {
50        (**self).evaluate(request)
51    }
52
53    fn list_models(&self) -> impl Future<Output = Result<Reply<ModelList>, Error>> + Send {
54        (**self).list_models()
55    }
56}
57
58/// A successful answer from the API: the parsed body, and facts about the exchange.
59#[derive(Clone, Debug, PartialEq)]
60#[non_exhaustive]
61pub struct Reply<T> {
62    /// The parsed response body.
63    pub body: T,
64    /// Facts about the exchange that are not part of the body.
65    pub meta: ReplyMeta,
66    /// The response body as the server sent it, when the transport kept it.
67    ///
68    /// `body` is the typed view, which drops fields this crate does not know. A caller that must
69    /// pass the API's answer on untouched reads it from here. [`HttpTransport`](crate::HttpTransport)
70    /// always fills it in; a fake transport usually does not.
71    ///
72    /// The one change made to it: a server that echoes the API key back gets `[REDACTED]` in its
73    /// place, because the key must not reach anything a caller prints.
74    pub raw_body: Option<String>,
75}
76
77impl<T> Reply<T> {
78    /// A reply, as a fake transport or a test would build one. It has no raw body.
79    #[must_use]
80    pub const fn new(body: T, meta: ReplyMeta) -> Self {
81        Self {
82            body,
83            meta,
84            raw_body: None,
85        }
86    }
87
88    /// Attaches the response body as it was received.
89    #[must_use]
90    pub fn with_raw_body(mut self, raw_body: impl Into<String>) -> Self {
91        self.raw_body = Some(raw_body.into());
92        self
93    }
94}
95
96/// Facts about one exchange with the API.
97#[derive(Clone, Debug, Default, PartialEq, Eq)]
98#[non_exhaustive]
99pub struct ReplyMeta {
100    /// The `x-typesafe-request-id` response header: the id to quote when asking TypeSafe about a
101    /// request. `None` when the server did not send one.
102    pub request_id: Option<String>,
103    /// Wall-clock time from the first attempt to the parsed response, including any retries and
104    /// the waits between them.
105    pub latency: Duration,
106    /// How many attempts were made, including the first. `1` means no retries.
107    pub attempts: u32,
108}
109
110impl ReplyMeta {
111    /// Metadata with the given values.
112    #[must_use]
113    pub const fn new(request_id: Option<String>, latency: Duration, attempts: u32) -> Self {
114        Self {
115            request_id,
116            latency,
117            attempts,
118        }
119    }
120}
121
122#[cfg(test)]
123mod tests {
124    use std::future::{Future, ready};
125    use std::sync::Arc;
126    use std::time::Duration;
127
128    use indexmap::IndexMap;
129
130    use super::{Reply, ReplyMeta, Transport};
131    use crate::{Error, ModelCard, ModelList, Request, Response, Usage};
132
133    /// The kind of in-memory fake the trait exists to allow.
134    struct Canned;
135
136    impl Transport for Canned {
137        fn evaluate(
138            &self,
139            request: &Request,
140        ) -> impl Future<Output = Result<Reply<Response>, Error>> + Send {
141            let body = Response::new(request.model.clone(), IndexMap::new(), Usage::new(1, 0));
142            let meta = ReplyMeta::new(Some("req_fake".into()), Duration::ZERO, 1);
143            ready(Ok(Reply::new(body, meta)))
144        }
145
146        fn list_models(&self) -> impl Future<Output = Result<Reply<ModelList>, Error>> + Send {
147            let models = ModelList::new(vec![ModelCard::new("jev-latest")]);
148            ready(Ok(Reply::new(models, ReplyMeta::default())))
149        }
150    }
151
152    async fn model_names(transport: impl Transport) -> Vec<String> {
153        let reply = transport.list_models().await.unwrap();
154        reply
155            .body
156            .models
157            .into_iter()
158            .map(|model| model.name)
159            .collect()
160    }
161
162    /// Compiles only if the futures are `Send`, which a multi-threaded runtime requires.
163    fn assert_send<T: Send>(value: T) -> T {
164        value
165    }
166
167    #[tokio::test]
168    async fn a_fake_a_reference_and_an_arc_are_all_transports() {
169        let shared = Arc::new(Canned);
170
171        assert_eq!(model_names(Canned).await, ["jev-latest"]);
172        assert_eq!(model_names(&Canned).await, ["jev-latest"]);
173        assert_eq!(model_names(Arc::clone(&shared)).await, ["jev-latest"]);
174
175        let request = Request::new("s", "jev-1.13.0");
176        let reply = assert_send(shared.evaluate(&request)).await.unwrap();
177        assert_eq!(reply.body.model, "jev-1.13.0");
178        assert_eq!(reply.meta.request_id.as_deref(), Some("req_fake"));
179    }
180}