trql_client/
transport.rs

1//! The transport seam: one request document in, one reply document out.
2
3use serde_json::Value;
4use trust_tasks_rs::TrustTask;
5
6use crate::error::TrqlError;
7
8/// Which wire a [`TrqlTransport`] speaks.
9///
10/// Kept as an explicit tag (never inferred from endpoint shape — a TSP VID is
11/// a DID too) so callers and logs can always name the protocol in use.
12#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
13pub enum TransportKind {
14    /// `POST /trust-tasks` per the `trust-tasks-https` binding.
15    Https,
16    /// The `trust-tasks-didcomm` envelope over an ATM mediator.
17    Didcomm,
18    /// The `trust-tasks-tsp` envelope in a TSP `Direct` message.
19    Tsp,
20}
21
22impl std::fmt::Display for TransportKind {
23    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
24        match self {
25            Self::Https => write!(f, "https"),
26            Self::Didcomm => write!(f, "didcomm"),
27            Self::Tsp => write!(f, "tsp"),
28        }
29    }
30}
31
32/// A pipe that carries one Trust Task request and returns the peer's reply
33/// document — either the `#response` success document or a `trust-task-error`
34/// document. Interpretation of the reply (correlation, error mapping, payload
35/// typing) belongs to [`crate::TrqlClient`], so bindings cannot diverge on
36/// semantics.
37///
38/// Contract for implementations:
39///
40/// * The request's `recipient` is the destination party; transports that
41///   route by DID read it from there.
42/// * Every exchange has a finite wait: a peer that never answers is a
43///   [`TrqlError::Timeout`], never a hang.
44/// * A reply body that is not a Trust Task document is a
45///   [`TrqlError::Contract`] (2xx / delivered) or [`TrqlError::Transport`]
46///   (error status with a non-Trust-Task body) — never silently dropped.
47#[async_trait::async_trait]
48pub trait TrqlTransport: Send + Sync {
49    /// The protocol this transport speaks.
50    fn kind(&self) -> TransportKind;
51
52    /// Send `request` to its `recipient` and return the peer's reply document.
53    async fn exchange(&self, request: TrustTask<Value>) -> Result<TrustTask<Value>, TrqlError>;
54}
trql_client/transport.rs

trql_client/
transport.rs
