Skip to main content

rig_core/
driver.rs

1//! Calls a model. A [`Model`] pairs a [`Wire`] (what to send and how to read
2//! the reply) with a [`Transport`] (how the payload travels). Its `stream`
3//! yields any operation's events as a [`Streamed`], and its `call` is that
4//! stream, finished: one decoder, one fold and one response constructor for
5//! both.
6//!
7//! ```no_run
8//! use rig_core::completion::CompletionRequest;
9//! use rig_core::driver::Model;
10//! use rig_core::providers::openai::{self, OpenAIConfig};
11//!
12//! # async fn example(http: rig_core::http_client::DynHttpClient) -> Result<(), Box<dyn std::error::Error>> {
13//! let model = OpenAIConfig::from_env()?.connect(http).responses(openai::GPT_5_2);
14//! let response = model.call(CompletionRequest::new("Hello")).await?;
15//! # let _ = response;
16//! # Ok(())
17//! # }
18//! ```
19
20use std::future::Future;
21use std::pin::Pin;
22use std::sync::{Arc, Mutex};
23use std::task::{Context, Poll};
24use std::time::Duration;
25
26use futures::StreamExt;
27use tracing::Instrument;
28
29use crate::error::ProviderError;
30use crate::lock;
31use crate::streaming::{Item, Streamed};
32use crate::wasm_compat::{WasmBoxedFuture, WasmBoxedStream, WasmCompatSend, WasmCompatSync};
33use crate::wire::document::Reassemble;
34use crate::wire::{
35    Call, Capabilities, Decoder, Descriptor, Flow, Mode, Operation, Out, Request, Response, Shared,
36    Wire, WireEvent,
37};
38
39mod dyn_model;
40pub(crate) mod http_transport;
41mod local;
42
43pub use dyn_model::DynModel;
44pub use local::{Local, Step};
45
46/// An endpoint of one provider: a wire bound to a transport.
47///
48/// The pair holds no invariant, so both halves are public. To share one
49/// transport across models, clone it; to send a model's requests another
50/// way, replace its transport. The transport defaults to the erased HTTP
51/// client, so a model on the default transport is `Model<W>`.
52#[derive(Clone, Debug, PartialEq)]
53pub struct Model<W, T = crate::http_client::DynHttpClient> {
54    /// What to send and how to read the reply.
55    pub wire: W,
56    /// How the payload travels.
57    pub transport: T,
58    /// What preparing the last request leaves for the next.
59    prepared: crate::wire::Prepared,
60    /// How long a streamed reply may send no frame before it fails.
61    idle_timeout: Option<Duration>,
62}
63
64/// How long a streamed reply may send no frame, from when it was sent to its
65/// first frame or between two, before it fails as
66/// [`ProviderError::Stalled`]: five minutes. Only a frame restarts it: any
67/// event the wire reads, a provider's ping event included. Bytes that are no
68/// frame, such as an event stream's comments, never do. A model that thinks
69/// at length is cut only if its provider sends no event for that long.
70pub const STREAM_IDLE_TIMEOUT: Duration = Duration::from_secs(300);
71
72impl<W: Default, T: Default> Default for Model<W, T> {
73    fn default() -> Self {
74        Self::new(W::default(), T::default())
75    }
76}
77
78impl<W, T> Model<W, T> {
79    /// Pair `wire` with the `transport` that sends it. A streamed reply
80    /// that sends no frame for [`STREAM_IDLE_TIMEOUT`] fails.
81    pub fn new(wire: W, transport: T) -> Self {
82        Self {
83            wire,
84            transport,
85            prepared: crate::wire::Prepared::default(),
86            idle_timeout: Some(STREAM_IDLE_TIMEOUT),
87        }
88    }
89
90    /// This model with a streamed reply failing as
91    /// [`ProviderError::Stalled`] once it sends no frame for `timeout`, from
92    /// when it was sent to its first frame or between two, whatever other
93    /// bytes arrive; `None`, or a timeout longer than a browser's timer
94    /// takes (about 24.8 days), waits indefinitely. A unary reply is never
95    /// timed: it sends nothing until it is whole.
96    pub fn with_idle_timeout(mut self, timeout: Option<Duration>) -> Self {
97        self.idle_timeout = timeout;
98        self
99    }
100}
101
102impl<W, T> Model<W, T>
103where
104    W: Wire<Op = crate::operation::Completion>,
105    T: Transport<W>,
106{
107    /// Every option of `request` this model would refuse, found by preparing
108    /// and encoding it as [`Self::call`] does, with nothing sent. It lists
109    /// the refusals of the model's catalog entry
110    /// ([`ModelSpec::refusals`](crate::catalog::ModelSpec::refusals)) and
111    /// those of the wire and its route, all of them rather than the first.
112    /// The request's [`OnUnsupported`](crate::completion::OnUnsupported)
113    /// policy does not change what is listed, but a request whose
114    /// [`GenerationOptions`](crate::completion::GenerationOptions) are
115    /// default is not checked against the catalog, as when it is sent.
116    ///
117    /// The request's messages are not read: its system prompt and a
118    /// stand-in prompt take their place, so a check costs the same for any
119    /// history. A refusal that depends on what the messages hold, such as
120    /// Bedrock's of a cache checkpoint after a reasoning turn, is reported
121    /// when the request is sent.
122    ///
123    /// # Errors
124    ///
125    /// [`CheckError::Unsupported`](crate::completion::CheckError::Unsupported)
126    /// with every refusal, or
127    /// [`CheckError::Invalid`](crate::completion::CheckError::Invalid) when the request cannot be built for another
128    /// reason.
129    pub fn check(
130        &self,
131        request: &crate::completion::CompletionRequest,
132    ) -> Result<(), crate::completion::CheckError> {
133        check_with(request, |request| self.dry_run(request))
134    }
135}
136
137/// The answer of `run`, a dry run of `request` without its messages, for
138/// [`Model::check`]. The run goes on past each refusal as under
139/// [`OnUnsupported::Ignore`](crate::completion::OnUnsupported::Ignore), so
140/// it meets every one; a request whose options are default stays default,
141/// so it is not checked against the catalog, as when it is sent.
142pub(crate) fn check_with(
143    request: &crate::completion::CompletionRequest,
144    run: impl FnOnce(crate::completion::CompletionRequest) -> Result<(), ProviderError>,
145) -> Result<(), crate::completion::CheckError> {
146    use crate::completion::{CheckError, OnUnsupported};
147    let mut request = without_messages(request);
148    if !request.options.is_default() {
149        request.options.on_unsupported = Some(OnUnsupported::Ignore);
150    }
151    match crate::completion::options::collect_refusals(|| run(request)) {
152        (Err(error), _) => Err(CheckError::Invalid(error)),
153        (Ok(()), refusals) if refusals.is_empty() => Ok(()),
154        (Ok(()), refusals) => Err(CheckError::Unsupported(refusals)),
155    }
156}
157
158/// `request` with its leading system prompt and a stand-in prompt as its
159/// messages, everything else as it is: what [`check_with`] dry-runs.
160pub(crate) fn without_messages(
161    request: &crate::completion::CompletionRequest,
162) -> crate::completion::CompletionRequest {
163    use crate::completion::{CompletionRequest, Message};
164    let CompletionRequest {
165        model,
166        chat_history,
167        documents,
168        tools,
169        temperature,
170        max_tokens,
171        tool_choice,
172        additional_params,
173        output_schema,
174        record_telemetry_content,
175        accept_unknown_finish_reasons,
176        foreign_reasoning,
177        options,
178        provider_options,
179        cache_points,
180    } = request;
181    let system = chat_history
182        .first()
183        .filter(|message| matches!(&***message, Message::System { .. }));
184    CompletionRequest {
185        model: model.clone(),
186        chat_history: system
187            .cloned()
188            .into_iter()
189            .chain([std::sync::Arc::new(Message::user("check"))])
190            .collect(),
191        documents: documents.clone(),
192        tools: tools.clone(),
193        temperature: *temperature,
194        max_tokens: *max_tokens,
195        tool_choice: tool_choice.clone(),
196        additional_params: additional_params.clone(),
197        output_schema: output_schema.clone(),
198        record_telemetry_content: *record_telemetry_content,
199        accept_unknown_finish_reasons: *accept_unknown_finish_reasons,
200        foreign_reasoning: *foreign_reasoning,
201        options: options.clone(),
202        provider_options: provider_options.clone(),
203        cache_points: cache_points.clone(),
204    }
205}
206
207/// Sends a wire's payloads and delivers its replies' frames.
208///
209/// HTTP clients ([`HttpClientExt`](crate::http_client::HttpClientExt)) are
210/// transports for every wire that encodes [`Encoded`](crate::wire::Encoded)
211/// requests and reads [`WireFrame`](crate::wire::WireFrame)s. A local
212/// runtime, a proxy or a mock is a transport for the wires it serves.
213pub trait Transport<W: Wire>: Clone + WasmCompatSend + WasmCompatSync + 'static {
214    /// Open the reply to one payload. Nothing is sent until the opening is
215    /// first polled. A payload the transport cannot send in the exchange's
216    /// mode fails the opening; a failure after the reply opened is its last
217    /// frame.
218    fn send(&self, payload: W::Payload, exchange: Exchange) -> Opening<W::Frame>;
219}
220
221/// What the driver tells a transport about one send.
222#[derive(Clone)]
223pub struct Exchange {
224    /// How the reply is read.
225    pub mode: Mode,
226    /// What the HTTP transport puts in the request's extensions, such as
227    /// the [`Serving`](crate::serve::Serving) of a dispatched effect.
228    pub(crate) extensions: http::Extensions,
229}
230
231/// What a caller adds to one send besides the request: the HTTP request's
232/// extensions.
233#[derive(Default)]
234pub(crate) struct Sending {
235    pub(crate) extensions: http::Extensions,
236}
237
238/// One reply, opened when first polled.
239pub struct Opening<F> {
240    open: WasmBoxedFuture<'static, Result<Opened<F>, ProviderError>>,
241}
242
243impl<F: WasmCompatSend + 'static> Opening<F> {
244    /// The reply `open` opens.
245    pub fn new(
246        open: impl Future<Output = Result<Opened<F>, ProviderError>> + WasmCompatSend + 'static,
247    ) -> Self {
248        Self {
249            open: Box::pin(open),
250        }
251    }
252
253    /// A reply that is already open.
254    pub fn ready(opened: Opened<F>) -> Self {
255        Self::new(std::future::ready(Ok(opened)))
256    }
257
258    /// A reply that failed to open with `error`.
259    pub fn failed(error: ProviderError) -> Self {
260        Self::new(std::future::ready(Err(error)))
261    }
262}
263
264impl<F> Future for Opening<F> {
265    type Output = Result<Opened<F>, ProviderError>;
266
267    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
268        self.open.as_mut().poll(cx)
269    }
270}
271
272/// One reply a transport opened: its frames, and the facts the transport
273/// owns.
274pub struct Opened<F> {
275    pub(crate) frames: WasmBoxedStream<'static, Result<F, ProviderError>>,
276    pub(crate) request_id: Option<String>,
277    pub(crate) status: Option<http::StatusCode>,
278    pub(crate) headers: Option<http::HeaderMap>,
279    pub(crate) route: Option<String>,
280    pub(crate) document: Option<serde_json::Value>,
281}
282
283impl<F: WasmCompatSend + 'static> Opened<F> {
284    /// A reply of `frames`, in order. A transport failure is the last item.
285    pub fn new(
286        frames: impl futures::Stream<Item = Result<F, ProviderError>> + WasmCompatSend + 'static,
287    ) -> Self {
288        Self {
289            frames: Box::pin(frames),
290            request_id: None,
291            status: None,
292            headers: None,
293            route: None,
294            document: None,
295        }
296    }
297
298    /// A reply that failed with `error` before any frame.
299    pub fn failed(error: ProviderError) -> Self {
300        Self::new(futures::stream::once(async move { Err(error) }))
301    }
302
303    /// The provider's transport request id, when the reply carried one. An
304    /// empty id is no id.
305    pub fn with_request_id(mut self, request_id: Option<String>) -> Self {
306        self.request_id = crate::provider_response::reported(request_id);
307        self
308    }
309
310    /// The reply's HTTP status and headers, which enrich its unary failure.
311    pub fn with_http(mut self, status: http::StatusCode, headers: http::HeaderMap) -> Self {
312        self.status = Some(status);
313        self.headers = Some(headers);
314        self
315    }
316
317    /// The concrete request path, which a listing's failure names.
318    pub fn with_route(mut self, route: impl Into<String>) -> Self {
319        self.route = Some(route.into());
320        self
321    }
322
323    /// The whole reply as one document: the response's `raw`. A reply
324    /// with one is not fed to the wire's reassembler.
325    pub fn with_document(mut self, document: serde_json::Value) -> Self {
326        self.document = Some(document);
327        self
328    }
329
330    /// The same reply, its frames passed through `frames`: what a transport
331    /// that wraps another uses to watch or rewrite a reply in flight.
332    pub fn map_frames<S>(
333        mut self,
334        frames: impl FnOnce(WasmBoxedStream<'static, Result<F, ProviderError>>) -> S,
335    ) -> Self
336    where
337        S: futures::Stream<Item = Result<F, ProviderError>> + WasmCompatSend + 'static,
338    {
339        self.frames = Box::pin(frames(self.frames));
340        self
341    }
342}
343
344impl<W, T> Model<W, T>
345where
346    W: Wire,
347    T: Transport<W>,
348{
349    /// The wire's provider descriptor name (`"anthropic"`).
350    pub fn name(&self) -> &str {
351        self.wire.describe().name
352    }
353
354    /// The model id the wire addresses, when the operation addresses one.
355    pub fn id(&self) -> Option<&str> {
356        self.wire.describe().model
357    }
358
359    /// What a runtime accounts for about this model, such as an embedding
360    /// model's width.
361    pub fn capabilities(&self) -> Capabilities {
362        self.wire.describe().capabilities
363    }
364
365    /// Send `request` and fold the whole reply into the operation's
366    /// response: [`Self::stream`] of a unary reply, finished. A completion
367    /// takes a prompt, a conversation or a
368    /// [`CompletionRequest`](crate::completion::CompletionRequest).
369    pub fn call(
370        &self,
371        request: impl Into<Request<W>>,
372    ) -> impl Future<Output = Result<Response<W>, ProviderError>> + WasmCompatSend + 'static {
373        self.finished(request.into(), Sending::default())
374    }
375
376    /// The call opens when first polled, so its span is created under the
377    /// caller's instrumented context.
378    fn finished(
379        &self,
380        request: Request<W>,
381        sending: Sending,
382    ) -> impl Future<Output = Result<Response<W>, ProviderError>> + WasmCompatSend + 'static {
383        let model = self.clone();
384        async move { model.open(request, Mode::Unary, sending)?.finish().await }
385    }
386
387    /// Open a streamed reply. Encoding errors return here; every later
388    /// failure arrives in-band, as the stream's last item. Nothing is sent
389    /// until the stream is first polled.
390    pub fn stream(&self, request: impl Into<Request<W>>) -> Result<Streamed<W::Op>, ProviderError> {
391        self.open(request.into(), Mode::Streaming, Sending::default())
392    }
393
394    /// [`Self::call`], with a failure paired with the request path of the
395    /// reply that failed, for an operation whose errors name their route.
396    pub(crate) async fn call_routed(
397        &self,
398        request: Request<W>,
399    ) -> Result<Response<W>, (ProviderError, String)> {
400        self.open(request, Mode::Unary, Sending::default())
401            .map_err(|error| (error, String::new()))?
402            .finish_routed()
403            .await
404    }
405
406    /// `request` prepared and encoded as [`Self::call`] would, with nothing
407    /// sent.
408    pub(crate) fn dry_run(&self, request: Request<W>) -> Result<(), ProviderError> {
409        let describe = Descriptor {
410            prepared: Some(&self.prepared),
411            ..self.wire.describe()
412        };
413        let request = <W::Op as Operation>::prepare(request, &describe)?;
414        self.wire.encode(request, Mode::Unary)?;
415        Ok(())
416    }
417
418    /// The one entry to the driver: the operation's fold for the reply,
419    /// the encoded payload, and the transport's reply, in `mode`. A request
420    /// the operation rejects fails here, before it is encoded.
421    pub(crate) fn open(
422        &self,
423        request: Request<W>,
424        mode: Mode,
425        sending: Sending,
426    ) -> Result<Streamed<W::Op>, ProviderError> {
427        let describe = Descriptor {
428            prepared: Some(&self.prepared),
429            ..self.wire.describe()
430        };
431        let request = <W::Op as Operation>::prepare(request, &describe)?;
432        let provider = describe.name.to_owned();
433        let mut call = Call::new(&describe, mode);
434        let fold = <W::Op as Operation>::fold(&request, &mut call);
435        let span = call.span;
436        let payload = self.wire.encode(request, mode)?;
437        let exchange = Exchange {
438            mode,
439            extensions: sending.extensions,
440        };
441        let opening = self.transport.send(payload, exchange);
442        let shared = Arc::new(Mutex::new(Shared::new(fold)));
443        // Only a streamed reply sends as it goes, so only it can stall.
444        let idle = match mode {
445            Mode::Streaming => self.idle_timeout,
446            Mode::Unary => None,
447        };
448        let reading = read(
449            self.wire.clone(),
450            opening,
451            Arc::clone(&shared),
452            span.clone(),
453            (mode, idle),
454        );
455        Ok(Streamed::new(reading, shared, span, provider))
456    }
457}
458
459/// Read one reply: open it, classify each frame, decode it into the reply's
460/// writer, and stop at the provider's end. The stream yields once per frame
461/// read, so its items reach the consumer frame by frame. When the transport
462/// reported no whole document, the wire's reassembler sees every known
463/// event before the decoder decodes it, and what it rebuilds is the reply's
464/// `raw` however the reply ends.
465///
466/// The reply's `'id` brand is the borrow of its shared state inside this
467/// stream: the decoder and every part handle it holds are tied to it, and
468/// none can leave.
469fn read<W: Wire>(
470    wire: W,
471    opening: Opening<W::Frame>,
472    shared: Arc<Mutex<Shared<W::Op>>>,
473    span: tracing::Span,
474    (mode, idle): (Mode, Option<Duration>),
475) -> WasmBoxedStream<'static, ()> {
476    let decoding = span.clone();
477    let reading = async_stream::stream! {
478        let reply: &Mutex<Shared<W::Op>> = &shared;
479        // Timed from the send and restarted only by a frame, so opening the
480        // reply and its first frame share one wait.
481        let mut last_frame = web_time::Instant::now();
482        // A unary call sends under the call's span; a stream reads under it.
483        let opened = match mode {
484            Mode::Unary => opening.instrument(span.clone()).await,
485            Mode::Streaming => idle_within(idle, last_frame, opening)
486                .await
487                .and_then(|opened| opened),
488        };
489        let Opened {
490            mut frames,
491            request_id,
492            status,
493            headers,
494            route,
495            document,
496        } = match opened {
497            Ok(opened) => opened,
498            Err(error) => {
499                fail(reply, error);
500                return;
501            }
502        };
503        record_request_id(&span, request_id.as_deref());
504        let mut reassembler = document.is_none().then(|| wire.reassembler());
505        {
506            let mut state = lock(reply);
507            state.request_id.clone_from(&request_id);
508            state.document = document;
509            state.route = route.unwrap_or_default();
510        }
511        let enrich = |error: ProviderError| match mode {
512            // A unary reply's failure carries what the transport reported.
513            Mode::Unary => error
514                .with_provider_status(status)
515                .with_provider_request_id(request_id.clone())
516                .with_response_headers(headers.clone()),
517            Mode::Streaming => error,
518        };
519        let mut decoder = wire.decoder();
520        loop {
521            let next = match idle_within(idle, last_frame, frames.next()).await {
522                Ok(next) => {
523                    last_frame = web_time::Instant::now();
524                    next
525                }
526                Err(stalled) => {
527                    record(reply, reassembler.map(|document| document.finish()));
528                    fail(reply, stalled);
529                    return;
530                }
531            };
532            let flow = match next {
533                Some(Ok(frame)) => step(&mut decoder, reassembler.as_mut(), reply, frame),
534                Some(Err(error)) => {
535                    record(reply, reassembler.map(|document| document.finish()));
536                    fail(reply, error);
537                    return;
538                }
539                None => eof(&mut decoder, reply),
540            };
541            match flow {
542                Ok(Flow::More) => yield (),
543                Ok(Flow::Ended(_)) => break,
544                Err(error) => {
545                    record(reply, reassembler.map(|document| document.finish()));
546                    fail(reply, enrich(error));
547                    return;
548                }
549            }
550        }
551        record(reply, reassembler.map(|document| document.finish()));
552        {
553            let state = lock(reply);
554            if let Some(document) = state.raw.as_ref().or(state.document.as_ref()) {
555                crate::providers::internal::trace_json(
556                    crate::providers::internal::LogTarget::Completions,
557                    "reply",
558                    document,
559                );
560            }
561        }
562        yield ();
563    };
564    let mut reading: WasmBoxedStream<'static, ()> = Box::pin(reading);
565    match mode {
566        // A stream decodes under the call's span.
567        Mode::Streaming => Box::pin(futures::stream::poll_fn(move |cx| {
568            let _decoding = decoding.enter();
569            reading.as_mut().poll_next(cx)
570        })),
571        Mode::Unary => reading,
572    }
573}
574
575/// The longest wait a browser's timer takes, about 24.8 days; past it, the
576/// timer fires at once. A longer idle timeout waits indefinitely.
577const LONGEST_TIMER: Duration = Duration::from_millis(2_147_483_647);
578
579/// `next` awaited until `idle` has passed since `since`, or for as long as
580/// it takes without `idle`: past it, the reply stalled. Timed from `since`,
581/// not from this wait, so a reader that paused between frames does not move
582/// the stall; a frame already in hand still comes.
583pub(crate) async fn idle_within<F: Future>(
584    idle: Option<Duration>,
585    since: web_time::Instant,
586    next: F,
587) -> Result<F::Output, ProviderError> {
588    let Some(idle) = idle.filter(|idle| *idle <= LONGEST_TIMER) else {
589        return Ok(next.await);
590    };
591    crate::wasm_compat::timeout(idle.saturating_sub(since.elapsed()), next)
592        .await
593        .map_err(|_| ProviderError::Stalled(idle))
594}
595
596/// A reply decoded from frames already in hand: its items, then its
597/// response or the error that ended it.
598pub(crate) struct Decoded<Op: Operation> {
599    /// Read only by relays and tests; a websocket session needs the outcome.
600    #[cfg(any(test, feature = "test-utils"))]
601    pub(crate) items: Vec<Result<crate::streaming::Item<Op::Event>, ProviderError>>,
602    pub(crate) outcome: Result<Op::Response, ProviderError>,
603}
604
605/// What the driver does with a classified frame: a known event is decoded,
606/// an unmodeled payload is warned about and delivered (aggregation never
607/// folds it into the answer), and a corrupt frame is the error that ends
608/// the reply.
609pub(crate) fn triage<E>(event: WireEvent<E>) -> Result<Item<E>, ProviderError> {
610    match event {
611        WireEvent::Known(event) => Ok(Item::Event(event)),
612        WireEvent::Unknown { event_type, value } => {
613            warn_unmodeled(&event_type, &value);
614            Ok(Item::Unknown(value))
615        }
616        WireEvent::Corrupt(error) => Err(ProviderError::from(error)),
617    }
618}
619
620/// Classify one frame and decode it into `reply`, handing a known event to
621/// `reassembler` first.
622pub(crate) fn step<'id, Op, F, D, R>(
623    decoder: &mut D,
624    reassembler: Option<&mut R>,
625    reply: &'id Mutex<Shared<Op>>,
626    frame: F,
627) -> Result<Flow, ProviderError>
628where
629    Op: Operation,
630    D: Decoder<'id, Op, F>,
631    R: Reassemble<D::Event>,
632{
633    match triage(decoder.classify(frame))? {
634        Item::Event(event) => {
635            if let Some(reassembler) = reassembler {
636                reassembler.absorb(&event);
637            }
638            decoder.decode(event, Out::new(reply))
639        }
640        Item::Unknown(value) => {
641            Out::new(reply).unknown(value);
642            Ok(Flow::More)
643        }
644    }
645}
646
647/// The frames ran out: a decoder that saw the provider's end ends the reply
648/// here; otherwise it is [`ProviderError::Truncated`].
649fn eof<'id, Op, F, D>(decoder: &mut D, reply: &'id Mutex<Shared<Op>>) -> Result<Flow, ProviderError>
650where
651    Op: Operation,
652    D: Decoder<'id, Op, F>,
653{
654    match decoder.eof(Out::new(reply)) {
655        Ok(Flow::More) => Err(ProviderError::Truncated),
656        step => step,
657    }
658}
659
660/// Feed frames already in hand through `reassembler` and `decoder` into
661/// `reply`, as [`read`] does: the reply ends at the provider's end, or the
662/// decoder decides at EOF, and what the reassembler rebuilt is recorded.
663pub(crate) fn feed<'id, Op, F, D, R>(
664    decoder: &mut D,
665    mut reassembler: Option<R>,
666    reply: &'id Mutex<Shared<Op>>,
667    frames: impl IntoIterator<Item = F>,
668) -> Result<(), ProviderError>
669where
670    Op: Operation,
671    D: Decoder<'id, Op, F>,
672    R: Reassemble<D::Event>,
673{
674    let feed_frames = || {
675        for frame in frames {
676            if let Flow::Ended(_) = step(decoder, reassembler.as_mut(), reply, frame)? {
677                return Ok(());
678            }
679        }
680        eof(decoder, reply).map(drop)
681    };
682    let fed = feed_frames();
683    record(reply, reassembler.map(|document| document.finish()));
684    fed
685}
686
687/// Record `document`, what a reassembler rebuilt, as the reply's `raw`. A
688/// `Null` document records nothing.
689pub(crate) fn record<Op: Operation>(
690    reply: &Mutex<Shared<Op>>,
691    document: Option<serde_json::Value>,
692) {
693    if let Some(document) = document.filter(|document| !document.is_null()) {
694        lock(reply).raw = Some(document);
695    }
696}
697
698/// Fold a fed reply as a stream does: its items, then its response, or the
699/// error that ended it. `reply.raw` stands unless it is null, when the
700/// decoder's record does.
701pub(crate) fn settle<Op: Operation>(
702    shared: Mutex<Shared<Op>>,
703    fed: Result<(), ProviderError>,
704    reply: crate::wire::Reply,
705) -> Decoded<Op> {
706    let mut shared = shared
707        .into_inner()
708        .unwrap_or_else(std::sync::PoisonError::into_inner);
709    if let Err(error) = fed {
710        shared.items.push_back(Err(error));
711    }
712    shared.document = Some(reply.raw).filter(|raw| !raw.is_null());
713    shared.request_id = reply.provider_request_id;
714    let mut items = Vec::new();
715    while let Some(item) = shared.take() {
716        let failed = item.is_err();
717        items.push(item);
718        if failed {
719            break;
720        }
721    }
722    let outcome = match items.last() {
723        Some(Err(error)) => Err(error.clone()),
724        _ => shared.conclude(&reply.provider),
725    };
726    #[cfg(any(test, feature = "test-utils"))]
727    if let Err(error) = &outcome
728        && !matches!(items.last(), Some(Err(_)))
729    {
730        items.push(Err(error.clone()));
731    }
732    Decoded {
733        #[cfg(any(test, feature = "test-utils"))]
734        items,
735        outcome,
736    }
737}
738
739/// [`decode_reply`](crate::wire::decode_reply), with `raw` the reply's
740/// whole document as a transport reports it (`Null` for none, so the
741/// reassembler's stands), for tests that state what the transport read.
742pub(crate) fn decode_reply<W: Wire>(
743    wire: &W,
744    request: &Request<W>,
745    mode: Mode,
746    frames: impl IntoIterator<Item = W::Frame>,
747    raw: serde_json::Value,
748) -> Result<Response<W>, ProviderError> {
749    let describe = wire.describe();
750    let fold = <W::Op as Operation>::fold(request, &mut Call::new(&describe, mode));
751    let shared = Mutex::new(Shared::new(fold));
752    let fed = feed(
753        &mut wire.decoder(),
754        Some(wire.reassembler()),
755        &shared,
756        frames,
757    );
758    let reply = crate::wire::Reply {
759        provider: describe.name.to_owned(),
760        raw,
761        provider_request_id: None,
762    };
763    settle(shared, fed, reply).outcome
764}
765
766/// A completion reply decoded from frames already in hand, as a handler
767/// relays it: its items, then the response, or the error that ended it.
768#[cfg(any(test, feature = "test-utils"))]
769pub(crate) fn relay_frames<W>(
770    wire: &W,
771    frames: impl IntoIterator<Item = W::Frame>,
772) -> crate::streaming::StreamEvents
773where
774    W: Wire<Op = crate::operation::Completion>,
775{
776    use crate::error::ErrorReport;
777    use crate::streaming::Relayed;
778
779    let provider = wire.describe().name.to_owned();
780    let shared = Mutex::new(Shared::new(crate::operation::ReplyFold::relayed(
781        provider.clone(),
782    )));
783    let fed = feed(
784        &mut wire.decoder(),
785        Some(wire.reassembler()),
786        &shared,
787        frames,
788    );
789    let decoded = settle(
790        shared,
791        fed,
792        crate::wire::Reply {
793            provider,
794            raw: serde_json::Value::Null,
795            provider_request_id: None,
796        },
797    );
798    let origin = decoded
799        .outcome
800        .as_ref()
801        .map(|response| response.origin.clone())
802        .ok();
803    let relayed: Vec<Result<Relayed, ErrorReport>> = origin
804        .map(|origin| Ok(Relayed::Origin(origin)))
805        .into_iter()
806        .chain(decoded.items.into_iter().map(|item| match item {
807            Ok(item) => Ok(Relayed::Item(item)),
808            Err(error) => Err(ErrorReport::from(&error)),
809        }))
810        // An error that ended the reply is already its last item.
811        .chain(
812            decoded
813                .outcome
814                .ok()
815                .map(|response| Ok(Relayed::Done(Arc::new(response)))),
816        )
817        .collect();
818    Box::pin(futures::stream::iter(relayed))
819}
820
821#[cfg(test)]
822impl Decoded<crate::operation::Completion> {
823    /// The events the reply yielded, without unmodeled payloads.
824    pub(crate) fn events(&self) -> Vec<&crate::streaming::StreamEvent> {
825        self.items
826            .iter()
827            .filter_map(|item| match item {
828                Ok(crate::streaming::Item::Event(event)) => Some(event),
829                _ => None,
830            })
831            .collect()
832    }
833
834    /// What each part ended with, in the order the parts ended.
835    pub(crate) fn ended(&self) -> Vec<crate::message::AssistantContent> {
836        self.events()
837            .into_iter()
838            .filter_map(|event| match event {
839                crate::streaming::StreamEvent::End { content, .. } => Some(content.clone()),
840                _ => None,
841            })
842            .collect()
843    }
844}
845
846/// Decode typed `events` through `decoder` as one completion reply from
847/// `provider`, then EOF: a decoder's test harness, without frames.
848#[cfg(test)]
849macro_rules! decode_events {
850    ($decoder:expr, $provider:expr, $events:expr) => {
851        $crate::driver::decode_with(
852            $crate::operation::ReplyFold::relayed($provider),
853            $provider,
854            |reply| {
855                let mut decoder = $decoder;
856                for event in $events {
857                    if let $crate::wire::Flow::Ended(_) =
858                        $crate::wire::Decoder::decode(&mut decoder, event, reply.out())?
859                    {
860                        return Ok(());
861                    }
862                }
863                match $crate::wire::Decoder::eof(&mut decoder, reply.out())? {
864                    $crate::wire::Flow::Ended(_) => Ok(()),
865                    $crate::wire::Flow::More => Err($crate::error::ProviderError::Truncated),
866                }
867            },
868        )
869    };
870}
871#[cfg(test)]
872pub(crate) use decode_events;
873
874/// Decode `frames` through `decoder`, classifier included, as one
875/// completion reply from `provider`: what the driver does with frames it
876/// read. A reassembler, when given, sees each known event first and its
877/// document is the reply's `raw`.
878#[cfg(test)]
879macro_rules! feed_frames {
880    ($decoder:expr, $provider:expr, $frames:expr) => {
881        $crate::driver::decode_with(
882            $crate::operation::ReplyFold::relayed($provider),
883            $provider,
884            |reply| {
885                let mut decoder = $decoder;
886                reply.feed(
887                    &mut decoder,
888                    None::<$crate::wire::document::Unreassembled>,
889                    $frames,
890                )
891            },
892        )
893    };
894    ($decoder:expr, $reassembler:expr, $provider:expr, $frames:expr) => {
895        $crate::driver::decode_with(
896            $crate::operation::ReplyFold::relayed($provider),
897            $provider,
898            |reply| {
899                let mut decoder = $decoder;
900                reply.feed(&mut decoder, Some($reassembler), $frames)
901            },
902        )
903    };
904}
905#[cfg(test)]
906pub(crate) use feed_frames;
907
908/// One reply's writer, for a test that drives a decoder by hand.
909#[cfg(test)]
910pub(crate) struct Replying<'id, Op: Operation>(&'id Mutex<Shared<Op>>);
911
912#[cfg(test)]
913impl<'id, Op: Operation> Replying<'id, Op> {
914    /// A writer for the next event.
915    pub(crate) fn out(&self) -> Out<'id, Op> {
916        Out::new(self.0)
917    }
918
919    /// Feed frames through `reassembler` and `decoder`, as the driver does.
920    pub(crate) fn feed<F, D: Decoder<'id, Op, F>, R: Reassemble<D::Event>>(
921        &self,
922        decoder: &mut D,
923        reassembler: Option<R>,
924        frames: impl IntoIterator<Item = F>,
925    ) -> Result<(), ProviderError> {
926        feed(decoder, reassembler, self.0, frames)
927    }
928}
929
930/// Drive one reply by hand: `run` decodes into it until the reply ends, or
931/// fails with what ended it, and the reply folds into `fold` as a stream
932/// would.
933#[cfg(test)]
934pub(crate) fn decode_with<Op: Operation>(
935    fold: Op::Fold,
936    provider: &str,
937    run: impl for<'id> FnOnce(Replying<'id, Op>) -> Result<(), ProviderError>,
938) -> Decoded<Op> {
939    let shared = Mutex::new(Shared::new(fold));
940    let fed = run(Replying(&shared));
941    settle(
942        shared,
943        fed,
944        crate::wire::Reply {
945            provider: provider.to_owned(),
946            raw: serde_json::Value::Null,
947            provider_request_id: None,
948        },
949    )
950}
951
952/// The reply failed: the error is its last item.
953fn fail<Op: Operation>(reply: &Mutex<Shared<Op>>, error: ProviderError) {
954    lock(reply).items.push_back(Err(error));
955}
956
957/// Read pages until one names no cursor, names the cursor it was asked
958/// with, or [`MAX_CONTINUATION_PAGES`] were read. `page` reads the page at a
959/// cursor (`None` for the first) and returns it with the next cursor.
960pub(crate) async fn follow_cursors<P, Fut>(
961    provider: &str,
962    operation: &str,
963    mut page: impl FnMut(Option<String>) -> Fut,
964) -> Result<Vec<P>, ProviderError>
965where
966    Fut: Future<Output = Result<(P, Option<String>), ProviderError>>,
967{
968    let mut pages = Vec::new();
969    let mut cursor = None;
970    loop {
971        let (read, next) = page(cursor.clone()).await?;
972        pages.push(read);
973        // Warn only when an offered page is refused: normal exhaustion is
974        // not truncation, while repeated or cycling cursors need a bound.
975        let Some(next) = next else { break };
976        if cursor.as_deref() == Some(next.as_str()) {
977            // The next request would be identical to the one just answered,
978            // so the page would repeat forever.
979            tracing::warn!(
980                provider,
981                operation,
982                pages = pages.len(),
983                "listing repeated its pagination cursor; returning the pages fetched so far"
984            );
985            break;
986        }
987        if pages.len() >= MAX_CONTINUATION_PAGES {
988            tracing::warn!(
989                provider,
990                operation,
991                pages = pages.len(),
992                "listing hit its page ceiling with a cursor still advancing; returning the pages \
993                 fetched so far"
994            );
995            break;
996        }
997        cursor = Some(next);
998    }
999    Ok(pages)
1000}
1001
1002/// Logs an unmodeled payload's kind and serialized size, never its content.
1003/// Callers must supply a structural kind label without sensitive data.
1004pub fn warn_unmodeled(kind: &str, payload: &impl serde::Serialize) {
1005    tracing::warn!(
1006        kind,
1007        payload_bytes = crate::json_utils::json_len(payload),
1008        "skipping unmodeled wire payload"
1009    );
1010}
1011
1012/// Page count after which a listing's cursors are ignored, preventing
1013/// infinite cursor cycles.
1014const MAX_CONTINUATION_PAGES: usize = 1000;
1015
1016/// Record the transport request id on the call's span, success or failure.
1017pub(crate) fn record_request_id(span: &tracing::Span, request_id: Option<&str>) {
1018    if let Some(request_id) = request_id
1019        && !span.is_disabled()
1020    {
1021        span.record(crate::telemetry::PROVIDER_REQUEST_ID_FIELD, request_id);
1022    }
1023}
1024
1025#[cfg(test)]
1026pub(crate) mod tests;