Struct TransportError

Source

pub struct TransportError { /* private fields */ }

Expand description

Why a request got no (complete) response.

Implementations§

Source §

impl TransportError

Source

pub fn new(kind: TransportErrorKind, message: impl Into<String>) -> Self

Create an error.

Source

pub fn authored(self) -> Self

Mark the message as written by the transport’s own code, with no text from a foreign error, the request, or the response in it, so into_error keeps it as the authored message.

The same contract as allama::Error::authored: never call it on a message that embeds an HTTP client’s error text, which can contain the request URL.

Source

pub fn with_source(self, source: impl Error + Send + Sync + 'static) -> Self

Attach the underlying error. into_error and into_stream_error keep it as the portable error’s source, so a caller can downcast it (a TLS failure from a DNS one). Its text is printed wherever the error’s chain is, so attach only errors whose Display holds no secret, such as a URL with a key in its query.

Source

pub fn kind(&self) -> TransportErrorKind

What went wrong.

Source

pub fn into_error(self) -> Error

The portable error for a failure before or while receiving a unary response: allama::Error::Timeout, allama::Error::InvalidRequest, or allama::Error::Transport.

The constructor message is an authored description of the kind. The transport’s own text is the upstream message: an HTTP client’s error can contain the request URL, and some APIs put the key in the query string, so it stays out of the redacted ErrorLog. A message marked authored is the constructor message instead.

use allama_http::{TransportError, TransportErrorKind};

let err = TransportError::new(
    TransportErrorKind::Connect,
    "error sending request for url (https://api.example.com/v1?key=SECRET)",
)
.into_error();
assert_eq!(err.as_log().to_string(), r#"kind=transport message="the request got no response""#);
assert!(err.to_string().contains("api.example.com"));

Source

pub fn into_stream_error(self) -> Error

The portable error for a failure while reading a streamed response, after it started: allama::Error::Timeout for a timeout (a stream timeout stays a timeout, so retry policies treat it as one), and a StreamErrorKind::Transport stream error, which is retryable, for anything else.

As in into_error, the constructor message is authored and the transport’s own text is the upstream message, unless the message is marked authored. SseError::into_error maps a failed body read with it.

use allama::{Error, StreamErrorKind};
use allama_http::{TransportError, TransportErrorKind};

let err = TransportError::new(TransportErrorKind::Body, "connection reset by peer")
    .into_stream_error();
assert!(matches!(err, Error::Stream { kind: StreamErrorKind::Transport, .. }));
assert!(err.is_retryable());
assert_eq!(err.upstream_message(), Some("connection reset by peer"));

let err = TransportError::new(TransportErrorKind::Timeout, "idle for 30s").into_stream_error();
assert!(matches!(err, Error::Timeout { .. }));