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;