Skip to main content

rig_core/
wire.rs

1//! Operations, provider wires and their decoders. An [`Operation`] names what
2//! goes in, what comes out event by event and what ends a reply, and its
3//! [`Fold`] turns one reply's events and end into the response. A [`Wire`]
4//! describes a provider endpoint as plain data, encodes requests without
5//! transport access, and names a fresh [`Decoder`] for each reply. A decoder
6//! is told nothing about how the reply arrives, so buffered and streamed
7//! replies go through the same decoder and fold.
8//!
9//! ```
10//! use rig_core::wire::WireFrame;
11//!
12//! let frame = WireFrame::Bytes(b"response".to_vec());
13//! assert_eq!(frame.as_str(), "response");
14//! ```
15
16use std::sync::{Arc, Mutex};
17
18use crate::error::{EncodeError, ProviderError};
19use crate::http_client::MultipartForm;
20use crate::wasm_compat::{WasmCompatSend, WasmCompatSync};
21
22pub use crate::http_client::framing::{Framing, WireFrame};
23
24mod citation;
25pub mod document;
26pub(crate) mod secret;
27
28pub use citation::{SpanUnit, WireCitation, WireSpan};
29pub use secret::Secret;
30
31/// The request a wire sends, and how its reply is framed.
32///
33/// Data only: built by [`Wire::encode`] from the wire and the request, and
34/// read by the driver. A wire never touches a socket or a request extension.
35///
36/// `Debug` shows request methods and URI paths, not schemes, authorities,
37/// queries, header values or bodies. Paths are not scrubbed: callers must
38/// still avoid placing sensitive data in them.
39pub struct Encoded {
40    /// The HTTP request.
41    pub request: http::Request<Body>,
42    /// How the reply's bytes split into frames.
43    pub framing: Framing,
44    /// The reply header carrying the provider's transport request id
45    /// (Anthropic `request-id`, OpenAI `x-request-id`), when the provider
46    /// reports one. `None` is "does not report one", never an error.
47    pub request_id_header: Option<&'static str>,
48    /// Whether a streamed reply may omit `Content-Type` (one gateway
49    /// replays Responses bodies without it). A *wrong* content type is
50    /// still rejected.
51    pub relaxed_content_type: bool,
52}
53
54impl Encoded {
55    /// One request whose provider reports no transport request id.
56    pub fn new(request: http::Request<Body>, framing: Framing) -> Self {
57        Self {
58            request,
59            framing,
60            request_id_header: None,
61            relaxed_content_type: false,
62        }
63    }
64
65    /// Name the reply header carrying the provider's transport request id.
66    pub fn with_request_id_header(mut self, header: Option<&'static str>) -> Self {
67        self.request_id_header = header;
68        self
69    }
70
71    /// Accept a streamed reply that names no content type.
72    pub fn with_relaxed_content_type(mut self) -> Self {
73        self.relaxed_content_type = true;
74        self
75    }
76}
77
78/// A request body: bytes, or a multipart form for the upload endpoints.
79///
80/// `Debug` prints the body's shape and size, never its bytes: a request
81/// body carries prompts, documents and uploaded files.
82pub enum Body {
83    /// A serialized body (JSON for every wire in this crate, or empty).
84    Bytes(Vec<u8>),
85    /// A multipart form (audio transcription, image edits).
86    Multipart(MultipartForm),
87}
88
89impl Body {
90    /// An empty body, for a `GET`.
91    pub fn empty() -> Self {
92        Self::Bytes(Vec::new())
93    }
94}
95
96impl std::fmt::Debug for Body {
97    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
98        match self {
99            Self::Bytes(bytes) => write!(f, "Bytes({} bytes)", bytes.len()),
100            Self::Multipart(_) => f.write_str("Multipart"),
101        }
102    }
103}
104
105impl std::fmt::Debug for Encoded {
106    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
107        // Diagnostics omit query, authority, headers and bodies. A caller's
108        // path can still contain sensitive data; it is not scrubbed here.
109        f.debug_struct("Encoded")
110            .field(
111                "request",
112                &(self.request.method(), self.request.uri().path()),
113            )
114            .field("framing", &self.framing)
115            .field("request_id_header", &self.request_id_header)
116            .field("relaxed_content_type", &self.relaxed_content_type)
117            .finish()
118    }
119}
120
121/// Reply mode used by the wire to select request encoding and framing.
122#[derive(Debug, Clone, Copy, PartialEq, Eq)]
123pub enum Mode {
124    /// One whole reply ([`Model::call`](crate::driver::Model::call)).
125    Unary,
126    /// A streamed reply ([`Model::stream`](crate::driver::Model::stream)).
127    Streaming,
128}
129
130/// An operation: what goes in, what comes out event by event, what ends a
131/// reply, and how those fold into one response.
132///
133/// Implemented once per operation, never per provider, so every provider of
134/// an operation is interchangeable behind a [`DynModel`](crate::DynModel).
135pub trait Operation: Sized + 'static {
136    /// The normalized request this operation accepts.
137    type Request: WasmCompatSend + 'static;
138    /// One decoded step of a reply.
139    type Event: WasmCompatSend + 'static;
140    /// What the provider sends when it ends the reply. A fold needs one to
141    /// produce a response, so a reply that stopped early has none.
142    type End: WasmCompatSend + 'static;
143    /// The normalized response the events and the end fold into.
144    type Response: WasmCompatSend + 'static;
145    /// One reply's state: it absorbs the events the consumer sees, then
146    /// folds them with the end into the response.
147    type Fold: Fold<Self> + WasmCompatSend + 'static;
148    /// Who builds the events: [`Free`] for events a decoder writes itself,
149    /// [`Assembled`] for the completion events only the writer's part
150    /// handles build.
151    type Emit: Emit<Self>;
152
153    /// The state for one reply to `request`, before its first frame. The
154    /// call says who answers and in which mode; an operation that records
155    /// telemetry opens its span here and hands it to
156    /// [`Call::instrument`].
157    fn fold(request: &Self::Request, call: &mut Call<'_>) -> Self::Fold;
158
159    /// Shape `request` for the wire `wire` describes, or reject a request
160    /// no provider of this operation can answer. The driver calls it before
161    /// the request is encoded, so a rejected request reaches no wire or
162    /// transport. Passes every request through by default.
163    fn prepare(
164        request: Self::Request,
165        wire: &Descriptor<'_>,
166    ) -> Result<Self::Request, ProviderError> {
167        let _ = wire;
168        Ok(request)
169    }
170}
171
172/// What a model keeps from preparing one request for the next
173/// ([`Descriptor::prepared`]): a completion's history as it was last
174/// adapted, so a history that grew is adapted only from its last turn on. A
175/// model's clones share it.
176#[derive(Clone, Debug, Default)]
177pub struct Prepared(pub(crate) Arc<Mutex<crate::completion::history::Memo>>);
178
179/// What a model kept never makes two models differ.
180impl PartialEq for Prepared {
181    fn eq(&self, _: &Self) -> bool {
182        true
183    }
184}
185
186/// Events a decoder builds and writes with [`Out::event`].
187#[derive(Debug, Clone, Copy, PartialEq, Eq)]
188pub enum Free {}
189
190/// Events only the completion writer's part handles build.
191#[derive(Debug, Clone, Copy, PartialEq, Eq)]
192pub enum Assembled {}
193
194/// Who builds an operation's events: [`Free`] or [`Assembled`]. Sealed.
195pub trait Emit<Op: Operation>: reply::Closing<Op> {}
196
197impl<Op: Operation> reply::Closing<Op> for Free {
198    fn close(_shared: &mut Shared<Op>) {}
199}
200
201impl<Op: Operation> Emit<Op> for Free {}
202
203/// What the driver knows about a call before its first frame.
204pub struct Call<'a> {
205    /// What the wire says about itself.
206    pub wire: &'a Descriptor<'a>,
207    /// How the reply arrives.
208    pub mode: Mode,
209    pub(crate) span: tracing::Span,
210}
211
212impl<'a> Call<'a> {
213    /// A call to the wire `wire` describes, in `mode`, under no span.
214    pub(crate) fn new(wire: &'a Descriptor<'a>, mode: Mode) -> Self {
215        Self {
216            wire,
217            mode,
218            span: tracing::Span::none(),
219        }
220    }
221
222    /// Run the call under `span`: a unary call sends under it and a stream
223    /// decodes under it.
224    pub fn instrument(&mut self, span: tracing::Span) {
225        self.span = span;
226    }
227}
228
229/// One reply's state for an operation.
230///
231/// Each event is [`absorb`](Self::absorb)ed as the consumer takes it, so
232/// the fold never runs ahead of what was delivered. The reply's end is what
233/// [`finish`](Self::finish) needs: without the provider's end there is no
234/// response.
235pub trait Fold<Op: Operation> {
236    /// Absorb one event the consumer is about to see. An error fails the
237    /// reply.
238    fn absorb(&mut self, event: &Op::Event) -> Result<(), ProviderError>;
239
240    /// The response, from the events absorbed, the provider's end and what
241    /// the driver learned about the reply.
242    fn finish(self, end: Op::End, reply: Reply) -> Result<Op::Response, ProviderError>;
243}
244
245/// What the driver learned about a reply beyond its events.
246#[derive(Debug, Clone, PartialEq)]
247pub struct Reply {
248    /// The provider descriptor name, for the response's `provider` field.
249    pub provider: String,
250    /// The reply's provider document (a completion's `raw`): the whole body
251    /// when it is one JSON document, else what the wire's reassembler
252    /// rebuilt or a free-event decoder recorded, else `Null`.
253    pub raw: serde_json::Value,
254    /// The provider's transport request id from the reply headers.
255    pub provider_request_id: Option<String>,
256}
257
258/// Whether a decoder step left the reply open. Only [`Out::end`] makes an
259/// [`Ended`].
260#[derive(Debug)]
261#[must_use]
262pub enum Flow {
263    /// The reply continues.
264    More,
265    /// The provider ended the reply; nothing is read after it.
266    Ended(Ended),
267}
268
269/// Proof that a decoder ended its reply with [`Out::end`].
270#[derive(Debug)]
271pub struct Ended(());
272
273pub(crate) use reply::Shared;
274
275pub(crate) mod reply {
276    use std::collections::VecDeque;
277
278    use super::{Fold, Operation, ProviderError, Reply};
279    use crate::streaming::Item;
280
281    /// One reply's items and end, shared by the driver that writes them and
282    /// the stream that takes them.
283    pub struct Shared<Op: Operation> {
284        pub(crate) fold: Op::Fold,
285        pub(crate) items: VecDeque<Result<Item<Op::Event>, ProviderError>>,
286        pub(crate) end: Option<Op::End>,
287        /// The usage the provider reported before the end that no relay
288        /// has forwarded yet.
289        pub(crate) usage: Option<crate::completion::Usage>,
290        pub(crate) raw: Option<serde_json::Value>,
291        /// The response a relayed reply's origin already folded.
292        pub(crate) response: Option<Op::Response>,
293        /// What the transport reported: the reply's request id, its whole
294        /// document and its request path.
295        pub(crate) request_id: Option<String>,
296        pub(crate) document: Option<serde_json::Value>,
297        pub(crate) route: String,
298    }
299
300    impl<Op: Operation> Shared<Op> {
301        pub(crate) fn new(fold: Op::Fold) -> Self {
302            Self {
303                fold,
304                items: VecDeque::new(),
305                end: None,
306                usage: None,
307                raw: None,
308                response: None,
309                request_id: None,
310                document: None,
311                route: String::new(),
312            }
313        }
314
315        /// Take the next item: an event is absorbed by the fold before it
316        /// leaves, and an error is stamped with the reply's request id.
317        pub(crate) fn take(&mut self) -> Option<Result<Item<Op::Event>, ProviderError>> {
318            Some(match self.items.pop_front()? {
319                Ok(Item::Event(event)) => self.fold.absorb(&event).map(|()| Item::Event(event)),
320                Ok(unknown) => Ok(unknown),
321                // An id an upstream constructor already attached wins: it
322                // saw the reply.
323                Err(error) => Err(error.with_provider_request_id(self.request_id.clone())),
324            })
325        }
326
327        /// What the driver learned about the reply so far, from `provider`.
328        pub(crate) fn reply(&self, provider: &str) -> Reply {
329            reply(
330                provider,
331                self.document.clone().or_else(|| self.raw.clone()),
332                self.request_id.clone(),
333            )
334        }
335
336        /// Fold the absorbed reply with the provider's end into the
337        /// response, or return the response a relay's origin folded. A
338        /// reply the provider did not end is [`ProviderError::Truncated`].
339        pub(crate) fn conclude(self, provider: &str) -> Result<Op::Response, ProviderError> {
340            if let Some(response) = self.response {
341                return Ok(response);
342            }
343            let reply = reply(provider, self.document.or(self.raw), self.request_id);
344            let end = self.end.ok_or(ProviderError::Truncated)?;
345            self.fold.finish(end, reply)
346        }
347    }
348
349    /// The reply from `provider` whose document is `raw`: a whole body, or
350    /// what the wire's reassembler rebuilt of a stream, or what the decoder
351    /// of an operation with free events recorded.
352    fn reply(provider: &str, raw: Option<serde_json::Value>, request_id: Option<String>) -> Reply {
353        Reply {
354            provider: provider.to_owned(),
355            raw: raw.unwrap_or(serde_json::Value::Null),
356            provider_request_id: request_id,
357        }
358    }
359
360    /// What the reply's end closes, after it is recorded.
361    pub trait Closing<Op: Operation> {
362        fn close(shared: &mut Shared<Op>);
363    }
364}
365
366/// What a runtime accounts for about a model. Each field matters to the
367/// operations that name it and is left at its default by the others.
368#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
369pub struct Capabilities {
370    /// What a completion provider composes.
371    pub completion: crate::completion::ProviderCapabilities,
372    /// The most documents one embedding or reranking request takes.
373    pub max_documents: usize,
374    /// The dimensionality of the returned vectors. Zero is unknown.
375    pub ndims: usize,
376    /// The embedding width the caller asked for, when they named one. `None`
377    /// and zero disable the check that replies honour it.
378    pub declared: Option<usize>,
379}
380
381impl Capabilities {
382    /// A completion provider's capabilities.
383    pub const fn completion(completion: crate::completion::ProviderCapabilities) -> Self {
384        Self {
385            completion,
386            ..Self::embedding(0, 0)
387        }
388    }
389
390    /// An embedding model's batch limit and width, with no width declared.
391    pub const fn embedding(max_documents: usize, ndims: usize) -> Self {
392        Self {
393            completion: crate::completion::ProviderCapabilities::new(),
394            max_documents,
395            ndims,
396            declared: None,
397        }
398    }
399
400    /// A reranking model's batch limit.
401    pub const fn rerank(max_documents: usize) -> Self {
402        Self::embedding(max_documents, 0)
403    }
404
405    /// Record the width the caller named, when they named one.
406    pub const fn declaring(mut self, declared: Option<usize>) -> Self {
407        self.declared = declared;
408        self
409    }
410
411    /// Returns [`ProviderError::MismatchedDimensions`] for the first width
412    /// differing from a positive caller declaration. Otherwise succeeds.
413    pub(crate) fn honour_declaration(
414        &self,
415        provider: &str,
416        widths: impl IntoIterator<Item = usize>,
417    ) -> Result<(), ProviderError> {
418        // Zero is rig's sentinel for an unknown width, never a claim about
419        // one: a model absent from every table this build knows resolves to
420        // it, and treating that as a declaration would fail every reply.
421        let Some(requested) = self.declared.filter(|declared| *declared > 0) else {
422            return Ok(());
423        };
424        let Some(returned) = widths.into_iter().find(|width| *width != requested) else {
425            return Ok(());
426        };
427        Err(ProviderError::MismatchedDimensions {
428            provider: provider.to_owned(),
429            requested,
430            returned,
431        })
432    }
433}
434
435/// What a wire says about itself: plain data, read before every call.
436#[derive(Debug, Clone)]
437pub struct Descriptor<'a> {
438    /// The model replay shapes a completion history for. Every completion
439    /// wire names one; other operations leave it `None`.
440    pub replay: Option<&'a dyn crate::completion::ReplayTarget>,
441    /// The provider descriptor name (`"anthropic"`), as records and
442    /// telemetry name it.
443    pub name: &'a str,
444    /// The model id the wire addresses, for telemetry. `None` for
445    /// operations that address no model.
446    pub model: Option<&'a str>,
447    /// What a runtime accounts for.
448    pub capabilities: Capabilities,
449    /// The telemetry operation for a call in each mode, when the endpoint
450    /// has a canonical name of its own (Gemini `generate_content`). The mode
451    /// itself is recorded separately, as `gen_ai.request.stream`.
452    pub telemetry: Option<fn(Mode) -> crate::telemetry::GenAiOperation>,
453    /// The model facts a completion wire encodes with, which its replies are
454    /// priced by. `None` answers from the built-in catalog.
455    pub facts: Option<&'a crate::catalog::ModelFacts>,
456    /// What the model kept from preparing its last request, which the
457    /// driver lends [`Operation::prepare`]; `None` from the wire itself.
458    pub prepared: Option<&'a Prepared>,
459}
460
461impl<'a> Descriptor<'a> {
462    /// A wire named `name`, addressing no model, with default capabilities.
463    pub fn new(name: &'a str) -> Self {
464        Self {
465            replay: None,
466            name,
467            model: None,
468            capabilities: Capabilities::default(),
469            telemetry: None,
470            facts: None,
471            prepared: None,
472        }
473    }
474
475    /// The spec of the model the wire addresses, from its facts under its
476    /// own name: the spec it was connected to, else the catalog's entry.
477    /// `None` for a wire that addresses no model, or a model the catalog
478    /// does not list.
479    pub fn spec(&self) -> Option<&'a crate::catalog::ModelSpec> {
480        let model = self.model?;
481        match self.facts {
482            Some(facts) => facts.for_model(self.name, model),
483            None => crate::catalog::Catalog::builtin()
484                .get_vendor(self.name, model)
485                .map(|resolved| resolved.spec),
486        }
487    }
488
489    /// The model replay shapes a completion history for.
490    pub fn replay(mut self, target: &'a dyn crate::completion::ReplayTarget) -> Self {
491        self.replay = Some(target);
492        self
493    }
494
495    /// The model id the wire addresses, when it addresses one.
496    pub fn model(mut self, model: impl Into<Option<&'a str>>) -> Self {
497        self.model = model.into();
498        self
499    }
500
501    /// What a runtime accounts for.
502    pub fn capabilities(mut self, capabilities: Capabilities) -> Self {
503        self.capabilities = capabilities;
504        self
505    }
506
507    /// The model facts the wire encodes with.
508    pub fn facts(mut self, facts: &'a crate::catalog::ModelFacts) -> Self {
509        self.facts = Some(facts);
510        self
511    }
512
513    /// The endpoint's own telemetry operation for each mode.
514    pub fn telemetry(mut self, telemetry: fn(Mode) -> crate::telemetry::GenAiOperation) -> Self {
515        self.telemetry = Some(telemetry);
516        self
517    }
518}
519
520/// One classified wire frame.
521#[derive(Debug)]
522pub enum WireEvent<T> {
523    /// The frame carries a discriminator this client models and its payload
524    /// decoded fully.
525    Known(T),
526    /// Valid JSON not recognized by this classifier.
527    /// Drivers log structural metadata only and skip interpretation.
528    Unknown {
529        /// The unmodeled discriminator value.
530        event_type: String,
531        /// Full payload for raw passthrough, never warning logs. Debug is redacted.
532        value: crate::streaming::UnknownPayload,
533    },
534    /// Invalid JSON or a recognized frame that failed typed decoding.
535    /// Must not be demoted to `Unknown`.
536    Corrupt(serde_json::Error),
537}
538
539impl<T> WireEvent<T> {
540    /// Map the `Known` payload, preserving the classification.
541    ///
542    /// This is how an adapter layers a pure event-shape mapping on top of a
543    /// classifier without restating the triage: `Unknown` and `Corrupt` pass
544    /// through untouched, so policy stays with the driver.
545    pub fn map<U>(self, f: impl FnOnce(T) -> U) -> WireEvent<U> {
546        match self {
547            Self::Known(event) => WireEvent::Known(f(event)),
548            Self::Unknown { event_type, value } => WireEvent::Unknown { event_type, value },
549            Self::Corrupt(error) => WireEvent::Corrupt(error),
550        }
551    }
552}
553
554/// Where a decoder writes one reply. The `'id` brand ties it to that one
555/// reply: a writer cannot be kept past the decode step that received it.
556///
557/// ```compile_fail
558/// use rig_core::operation::Completion;
559/// use rig_core::wire::Out;
560///
561/// // A writer cannot be stashed to write into the reply later.
562/// struct Stash(Option<Out<'static, Completion>>);
563///
564/// fn keep<'id>(stash: &mut Stash, out: Out<'id, Completion>) {
565///     stash.0 = Some(out);
566/// }
567/// ```
568pub struct Out<'id, Op: Operation> {
569    shared: &'id std::sync::Mutex<Shared<Op>>,
570    brand: std::marker::PhantomData<fn(&'id ()) -> &'id ()>,
571}
572
573impl<'id, Op: Operation> Out<'id, Op> {
574    pub(crate) fn new(shared: &'id std::sync::Mutex<Shared<Op>>) -> Self {
575        Self {
576            shared,
577            brand: std::marker::PhantomData,
578        }
579    }
580
581    pub(crate) fn lock(&self) -> std::sync::MutexGuard<'id, Shared<Op>> {
582        crate::lock(self.shared)
583    }
584
585    /// End the reply with what the provider sent at its end. It consumes the
586    /// writer: nothing is written after the end.
587    pub fn end(self, end: Op::End) -> Flow {
588        let mut shared = self.lock();
589        // Recorded first: what closes the open parts may read how it ended.
590        shared.end = Some(end);
591        <Op::Emit as reply::Closing<Op>>::close(&mut shared);
592        Flow::Ended(Ended(()))
593    }
594
595    /// What the provider reported the reply used so far, before its end,
596    /// such as the input counted as it starts. A relay forwards it as
597    /// [`Relayed::Usage`](crate::streaming::Relayed::Usage); a later report
598    /// replaces it, and the end's usage is the whole.
599    pub fn usage(&mut self, usage: crate::completion::Usage) {
600        self.lock().usage = Some(usage);
601    }
602
603    /// A payload the provider sent that this decoder does not model. It
604    /// reaches the consumer as [`Item::Unknown`](crate::streaming::Item).
605    pub fn unknown(&mut self, payload: crate::streaming::UnknownPayload) {
606        self.lock()
607            .items
608            .push_back(Ok(crate::streaming::Item::Unknown(payload)));
609    }
610}
611
612impl<Op: Operation<Emit = Free>> Out<'_, Op> {
613    /// Record the reply's provider document, the response's `raw`. A whole
614    /// JSON body the transport reported outranks it: a decoder whose reply
615    /// is not one JSON document records it here.
616    ///
617    /// Only an operation whose decoders build their own events has this. A
618    /// completion's `raw` is what its wire's
619    /// [`Reassembler`](Wire::Reassembler) rebuilds, never what a decoder
620    /// writes:
621    ///
622    /// ```compile_fail,E0599
623    /// use rig_core::operation::Completion;
624    /// use rig_core::wire::Out;
625    ///
626    /// fn record(out: &mut Out<'_, Completion>) {
627    ///     out.raw(serde_json::json!({ "response_id": "x" }));
628    /// }
629    /// ```
630    pub fn raw(&mut self, raw: serde_json::Value) {
631        self.lock().raw = Some(raw);
632    }
633
634    /// One event of the reply.
635    ///
636    /// Only an operation whose decoders build their own events has this; a
637    /// completion's events come from its part handles:
638    ///
639    /// ```compile_fail,E0599
640    /// use rig_core::operation::Completion;
641    /// use rig_core::streaming::StreamEvent;
642    /// use rig_core::wire::Out;
643    ///
644    /// fn reinject(out: &mut Out<'_, Completion>, seen: &StreamEvent) {
645    ///     out.event(seen.clone());
646    /// }
647    /// ```
648    ///
649    /// An event rebuilt from its serialized form is no different:
650    ///
651    /// ```compile_fail,E0599
652    /// use rig_core::operation::Completion;
653    /// use rig_core::streaming::StreamRecord;
654    /// use rig_core::wire::Out;
655    ///
656    /// fn rebuild(out: &mut Out<'_, Completion>, recorded: serde_json::Value) {
657    ///     let Ok(transcript) = StreamRecord::parse(recorded) else { return };
658    ///     for event in transcript.events() {
659    ///         out.event(event.clone());
660    ///     }
661    /// }
662    /// ```
663    pub fn event(&mut self, event: Op::Event) {
664        self.lock()
665            .items
666            .push_back(Ok(crate::streaming::Item::Event(event)));
667    }
668}
669
670/// Synchronous state machine for one reply. It classifies frames and
671/// decodes known events into the reply's writer, without transport access
672/// and without being told how the reply arrives. HTTP wires read
673/// [`WireFrame`]s; other transports name their own frame type.
674pub trait Decoder<'id, Op: Operation, Frame = WireFrame> {
675    /// The wire's typed event, produced by this decoder's classifier.
676    type Event;
677
678    /// Decode and classify one frame. A JSON wire MUST delegate to a
679    /// classifier in [`crate::providers::internal::wire`], so the
680    /// decode-then-validate policy is not re-derived per provider.
681    fn classify(&self, frame: Frame) -> WireEvent<Self::Event>;
682
683    /// Write one `Known` event into the reply. An error ends the reply with
684    /// it.
685    fn decode(&mut self, event: Self::Event, out: Out<'id, Op>) -> Result<Flow, ProviderError>;
686
687    /// The frames ran out without an end. A decoder that already saw the
688    /// provider's end, in a form the provider sends before its last frame,
689    /// ends the reply here; otherwise the reply is truncated.
690    fn eof(&mut self, out: Out<'id, Op>) -> Result<Flow, ProviderError> {
691        let _ = out;
692        Err(ProviderError::Truncated)
693    }
694}
695
696/// A provider endpoint: plain data that encodes requests and names a decoder
697/// for each reply.
698///
699/// No transport, no future, no type parameter. Implementations are plain
700/// data (`Clone + PartialEq + Debug + Serialize + Deserialize`, with
701/// credentials held in [`Secret`]), so a host can store one in a scene, a
702/// component, or a config file. `Clone` is a supertrait: the driver clones
703/// the wire into every call's `'static` stream.
704pub trait Wire: Clone + WasmCompatSend + WasmCompatSync + 'static {
705    /// The operation this wire performs.
706    type Op: Operation;
707    /// What [`Self::encode`] produces for the transport to send.
708    type Payload: WasmCompatSend + 'static;
709    /// One unit of a reply, as the transport delivers it.
710    type Frame: WasmCompatSend + 'static;
711    /// The decoder's classified event, which the reassembler reads too.
712    type Event: WasmCompatSend + 'static;
713    /// The decoder for one of its replies, branded with that reply.
714    type Decoder<'id>: Decoder<'id, Self::Op, Self::Frame, Event = Self::Event> + WasmCompatSend;
715    /// What rebuilds a reply's provider document from its events when the
716    /// transport reports no whole document, as for a stream. The driver
717    /// hands it every known event before the decoder decodes it, and
718    /// records what it finishes with as `raw`. A wire whose operation's
719    /// decoders record `raw` themselves names [`document::Unreassembled`];
720    /// a completion wire cannot, because it does not
721    /// [`Serve`](document::Serves) completions.
722    type Reassembler: document::Reassemble<Self::Event> + document::Serves<Self::Op>;
723
724    /// What the wire says about itself.
725    fn describe(&self) -> Descriptor<'_>;
726
727    /// The request to send. Pure: it may read `self`, `request` and `mode`,
728    /// and nothing else. A request that cannot be built is an
729    /// [`EncodeError`], which always reports as a request failure.
730    fn encode(&self, request: Request<Self>, mode: Mode) -> Result<Self::Payload, EncodeError>;
731
732    /// A fresh decoder for one reply.
733    fn decoder<'id>(&self) -> Self::Decoder<'id>;
734
735    /// A fresh reassembler for one reply. A wire that picks its API per
736    /// reply builds the matching one.
737    fn reassembler(&self) -> Self::Reassembler {
738        Self::Reassembler::default()
739    }
740}
741
742/// One reply of `wire` to `request`, decoded from frames already in hand as
743/// a live call in `mode` would decode them: through the wire's decoder,
744/// reassembler and fold, with no transport. A reply that arrives some other
745/// way, such as a batch result's body ([`WireFrame::Bytes`], unary) or a
746/// recorded stream, becomes an ordinary response. `raw` is what the wire's
747/// reassembler rebuilds from the frames, and the request is the one sent,
748/// as [`Wire::encode`] took it.
749///
750/// ```
751/// use rig_core::completion::{CompletionRequest, CompletionResponse};
752/// use rig_core::error::ProviderError;
753/// use rig_core::providers::anthropic::wire::Messages;
754/// use rig_core::wire::{Mode, WireFrame, decode_reply};
755///
756/// /// A batch result's body, as the reply to the `request` it answers.
757/// fn batch_reply(
758///     wire: &Messages,
759///     request: &CompletionRequest,
760///     body: Vec<u8>,
761/// ) -> Result<CompletionResponse, ProviderError> {
762///     decode_reply(wire, request, Mode::Unary, [WireFrame::Bytes(body)])
763/// }
764/// ```
765///
766/// # Errors
767///
768/// What the reply fails with when called live: a frame the decoder rejects,
769/// a provider error in the reply, or [`ProviderError::Truncated`] when the
770/// frames end before the provider ended the reply.
771pub fn decode_reply<W: Wire>(
772    wire: &W,
773    request: &Request<W>,
774    mode: Mode,
775    frames: impl IntoIterator<Item = W::Frame>,
776) -> Result<Response<W>, ProviderError> {
777    crate::driver::decode_reply(wire, request, mode, frames, serde_json::Value::Null)
778}
779
780/// The decoder of a reply that is one JSON document: the document is the
781/// operation's end, and is kept as the reply's `raw`.
782#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
783pub struct Json;
784
785impl<'id, Op> Decoder<'id, Op, WireFrame> for Json
786where
787    Op: Operation<Emit = Free>,
788    Op::End: serde::de::DeserializeOwned,
789{
790    type Event = (Op::End, serde_json::Value);
791
792    fn classify(&self, frame: WireFrame) -> WireEvent<Self::Event> {
793        let document = match serde_json::from_str::<serde_json::Value>(&frame.as_str()) {
794            Ok(document) => document,
795            Err(error) => return WireEvent::Corrupt(error),
796        };
797        match crate::json_utils::from_value::<Op::End>(&document) {
798            Ok(end) => WireEvent::Known((end, document)),
799            Err(error) => WireEvent::Corrupt(error),
800        }
801    }
802
803    fn decode(
804        &mut self,
805        (end, document): Self::Event,
806        mut out: Out<'id, Op>,
807    ) -> Result<Flow, ProviderError> {
808        out.raw(document);
809        Ok(out.end(end))
810    }
811}
812
813/// The decoder of a reply that is one document: `classify` reads the
814/// document, and `end` makes it the operation's end.
815pub struct DocumentDecoder<Op: Operation, Event> {
816    classify: fn(&str) -> WireEvent<Event>,
817    end: fn(Event) -> Result<Op::End, ProviderError>,
818}
819
820impl<Op: Operation, Event> DocumentDecoder<Op, Event> {
821    /// The decoder that reads a reply with `classify` and ends it with `end`.
822    pub fn new(
823        classify: fn(&str) -> WireEvent<Event>,
824        end: fn(Event) -> Result<Op::End, ProviderError>,
825    ) -> Self {
826        Self { classify, end }
827    }
828}
829
830impl<'id, Op: Operation, Event> Decoder<'id, Op> for DocumentDecoder<Op, Event> {
831    type Event = Event;
832
833    fn classify(&self, frame: WireFrame) -> WireEvent<Event> {
834        (self.classify)(&frame.as_str())
835    }
836
837    fn decode(&mut self, event: Event, out: Out<'id, Op>) -> Result<Flow, ProviderError> {
838        Ok(out.end((self.end)(event)?))
839    }
840}
841
842/// A wire's request type.
843pub type Request<W> = <<W as Wire>::Op as Operation>::Request;
844/// A wire's response type.
845pub type Response<W> = <<W as Wire>::Op as Operation>::Response;
846
847#[cfg(test)]
848mod tests;