semiont 0.7.2

Semiont's Rust SDK: the protocol's types, the transport contract and a client of the bus over it, and what a client needs to name its principals and hold its roles, as protocol/specs/ states it.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
//! A client of a knowledge base's bus, over any `Transport`: emit, observe,
//! and request.
//!
//! A request (protocol/contract/TRANSPORT-CONTRACT.md ยง Requests) is one emit
//! carrying a correlation id of this client's making on its envelope, answered
//! on its operation's result or failure channel (the registry's `operations`).
//! It is not sent before the stream that carries its reply is open; its id is
//! tracked until it settles, so a reply published while the stream was down
//! is sent again; and it settles once, with the response, with a failure
//! under this vocabulary's code, or as a timeout. A caller abandons a request
//! by dropping its future: what was sent stays sent, the reply stops being
//! tracked, and one that comes anyway reaches nobody.
//!
//! Every method comes twice. By type (`emit`, `frames`, `request`), the
//! channel is a type of `crate::channels` and the payload is that channel's
//! own, so a wrong payload for a channel does not compile:
//!
//! ```
//! # use semiont::bus::Bus;
//! # use semiont::channels::BeckonFocus;
//! # use semiont::transport::Envelope;
//! # use semiont::types::BeckonFocusEvent;
//! # async fn focus(bus: &Bus, event: BeckonFocusEvent) {
//! let _ = bus.emit::<BeckonFocus>(&event, Envelope::default()).await;
//! # }
//! ```
//!
//! ```compile_fail
//! # use semiont::bus::Bus;
//! # use semiont::channels::JobCreate;
//! # use semiont::transport::Envelope;
//! # use semiont::types::BeckonFocusEvent;
//! # async fn focus(bus: &Bus, event: BeckonFocusEvent) {
//! let _ = bus.emit::<JobCreate>(&event, Envelope::default()).await;
//! # }
//! ```
//!
//! By name (`emit_on`, `frames_on`, `request_of`), the channel is the
//! registry's name and the payload a JSON object: for what relays frames it
//! does not read, or is told its channels at run time.

use crate::channels::{Channel, Request, Scoped, Unscoped, payload_shape, payload_stamps};
use crate::errors::{
    BusRequestError, BusRequestErrorCode, SemiontError, TransportError, TransportErrorCode,
};
use crate::required::{Fault, fault_of};
use crate::transport::{
    ConnectionState, Envelope, Frame, FrameRefusal, Frames, Lagged, ResourceHold, TraceCarrier,
    Transport,
};
use crate::types::ResourceId;
use futures_core::Stream;
use serde::{Deserialize, Serialize};
use serde_json::{Map, Value};
use std::fmt;
use std::marker::PhantomData;
use std::pin::Pin;
use std::sync::Arc;
use std::task::{Context, Poll};
use std::time::Duration;
use tokio::time::Instant;

/// A registry operation: the request, and the channels its reply and failure come on.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Operation {
    pub request: &'static str,
    pub result: &'static str,
    pub failure: &'static str,
}

impl Operation {
    /// The operation `R` is the request of.
    pub(crate) const fn of<R: Request>() -> Operation {
        Operation {
            request: R::NAME,
            result: <R::Result as Channel>::NAME,
            failure: <R::Failure as Channel>::NAME,
        }
    }
}

include!(concat!(env!("OUT_DIR"), "/operations.rs"));

/// The operation `request` is the request of, as the registry declares it.
pub fn operation(request: &str) -> Option<&'static Operation> {
    OPERATIONS.iter().find(|op| op.request == request)
}

/// What the reply to `request` states beside its `response`: properties of the
/// request, which a gateway states again in its reply. Nothing, for most.
pub fn reply_names(request: &str) -> &'static [&'static str] {
    REPLY_NAMES
        .iter()
        .find(|(asked, _)| *asked == request)
        .map_or(&[][..], |(_, named)| *named)
}

/// The result and failure channels of every operation among `channels`, each
/// once: what a client that awaits only those operations names as its global
/// channels. A channel that is no operation's request contributes nothing.
pub fn reply_channels_for(channels: &[&str]) -> Vec<&'static str> {
    let mut replies = Vec::new();
    for op in channels.iter().filter_map(|channel| operation(channel)) {
        for reply in [op.result, op.failure] {
            if !replies.contains(&reply) {
                replies.push(reply);
            }
        }
    }
    replies
}

/// A payload as the bus carries it: a JSON object.
pub fn payload_of(payload: &impl Serialize) -> Result<Map<String, Value>, TransportError> {
    match serde_json::to_value(payload) {
        Ok(Value::Object(fields)) => Ok(fields),
        Ok(other) => Err(TransportError::without_response(
            format!("a payload is a JSON object, not {other}"),
            TransportErrorCode::Error,
        )),
        Err(error) => Err(TransportError::without_response(
            format!("a payload that does not serialize: {error}"),
            TransportErrorCode::Error,
        )),
    }
}

#[derive(Clone)]
pub struct Bus {
    transport: Arc<dyn Transport>,
}

impl Bus {
    pub fn new(transport: Arc<dyn Transport>) -> Bus {
        Bus { transport }
    }

    /// Send one frame on the channel named `channel`.
    pub async fn emit_on(
        &self,
        channel: &str,
        payload: Map<String, Value>,
        envelope: Envelope,
    ) -> Result<Option<u64>, TransportError> {
        self.transport.emit(channel, payload, envelope).await
    }

    /// The frames delivered on the channel named `channel` from now on.
    pub fn frames_on(&self, channel: &str) -> Result<Frames, BusRequestError> {
        self.transport.frames(channel)
    }

    /// Send `payload` as the request of `operation` and wait up to `within`
    /// for its reply: the reply's `response`, or `None` when it carries none.
    pub async fn request_of(
        &self,
        operation: &Operation,
        payload: Map<String, Value>,
        within: Duration,
    ) -> Result<Option<Value>, SemiontError> {
        let mut result = self.result_of(operation, payload, within).await?;
        Ok(result.payload.remove("response"))
    }

    /// A request, as far as its result: the frame that answers it on its
    /// operation's result channel. A failure is the request's error, and one
    /// that is not its channel's is refused.
    async fn result_of(
        &self,
        operation: &Operation,
        payload: Map<String, Value>,
        within: Duration,
    ) -> Result<Frame, SemiontError> {
        let deadline = Instant::now() + within;
        for channel in [operation.result, operation.failure] {
            if !self.transport.is_subscribed(channel) {
                return Err(BusRequestError::new(
                    BusRequestErrorCode::Unsubscribed,
                    format!(
                        "Transport is not subscribed to reply channel {channel}: a reply to {} can never arrive. Add this operation's reply channels to the transport's channels.",
                        operation.request
                    ),
                )
                .into());
            }
        }
        let timed_out = || {
            BusRequestError::new(
                BusRequestErrorCode::Timeout,
                format!(
                    "Bus request timed out after {}ms on {}",
                    within.as_millis(),
                    operation.result
                ),
            )
        };

        // No request before its reply can arrive: wait, inside the request's
        // own deadline, for the stream to be open. Only `Open` delivers; a
        // closed bus fails at once rather than burning the deadline.
        let closed_before_emit = || {
            BusRequestError::new(
                BusRequestErrorCode::Closed,
                format!("Bus closed before emit on {}", operation.request),
            )
        };
        let mut state = self.transport.state();
        loop {
            match *state.borrow_and_update() {
                ConnectionState::Open => break,
                ConnectionState::Closed => return Err(closed_before_emit().into()),
                _ => {}
            }
            tokio::select! {
                changed = state.changed() => {
                    if changed.is_err() {
                        return Err(closed_before_emit().into());
                    }
                }
                () = tokio::time::sleep_until(deadline) => return Err(timed_out().into()),
            }
        }

        // Tracked before the emit, so a stream opened while the emit is in
        // flight already names the reply.
        let correlation_id = uuid::Uuid::new_v4().to_string();
        let mut pending = self
            .transport
            .track_reply(&correlation_id, &[operation.result, operation.failure]);
        let envelope = Envelope {
            correlation_id: Some(correlation_id),
            scope: None,
        };
        self.transport
            .emit(operation.request, payload, envelope)
            .await?;

        let reply = tokio::select! {
            biased;
            reply = pending.frame() => reply,
            () = tokio::time::sleep_until(deadline) => return Err(timed_out().into()),
        };
        let reply = match reply {
            Some(Ok(reply)) => reply,
            Some(Err(refusal)) => {
                return Err(TransportError::without_response(
                    refusal.to_string(),
                    TransportErrorCode::Error,
                )
                .into());
            }
            None => {
                return Err(BusRequestError::new(
                    BusRequestErrorCode::Closed,
                    format!("Bus closed before a reply on {}", operation.result),
                )
                .into());
            }
        };
        if reply.channel == operation.result {
            return Ok(reply);
        }
        Err(answered(operation.failure, reply.payload))
    }
}

/// What a request reads of a failure its table passed: its words, and its
/// code as a text, which the table holds to no list.
#[derive(Deserialize)]
struct Failure {
    message: String,
    code: Option<String>,
}

/// The failure a request was answered with on `channel`, its operation's
/// failure channel: under the code its own code becomes, in its own words. A
/// failure with a fault as its channel's is refused, as a result with one is.
fn answered(channel: &str, failure: Map<String, Value>) -> SemiontError {
    let fault = match held_to(channel, failure.clone()) {
        Err(fault) => fault,
        Ok(declared) => match serde_json::from_value::<Failure>(declared) {
            Ok(read) => {
                return BusRequestError {
                    code: BusRequestErrorCode::of_wire(read.code.as_deref()),
                    message: read.message,
                    failure: Some(failure),
                }
                .into();
            }
            Err(_) => Fault::undecoded(),
        },
    };
    TransportError::without_response(
        format!("a payload on {channel} is not that channel's: {fault}"),
        TransportErrorCode::Error,
    )
    .into()
}

// โ”€โ”€ By type โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€

/// A frame of the channel `C`, its payload decoded.
pub struct Delivered<C: Channel> {
    pub payload: C::Payload,
    pub correlation_id: Option<String>,
    pub scope: Option<ResourceId>,
    /// The DID of whoever emitted it, as the gateway stamped it.
    pub user_id: Option<String>,
    pub trace: Option<TraceCarrier>,
}

/// Why a typed stream could not give its next frame.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum StreamError {
    /// The reader fell behind and missed this many frames.
    Lagged(u64),
    /// A frame arrived that is not the channel's: one the transport refused,
    /// or one whose payload is not the channel's, its first fault named
    /// within `payload`.
    Refused(Box<FrameRefusal>),
}

impl fmt::Display for StreamError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            StreamError::Lagged(missed) => Lagged(*missed).fmt(f),
            StreamError::Refused(refusal) => refusal.fmt(f),
        }
    }
}

impl std::error::Error for StreamError {}

/// A payload held to the channel `channel`. A gateway's stamps its type does
/// not declare are the bus's, not the payload's, and are left out. A payload
/// with a fault as the channel's is refused, for the fault.
pub(crate) fn held_to(channel: &str, mut payload: Map<String, Value>) -> Result<Value, Fault> {
    let stamps = payload_stamps(channel);
    payload.retain(|key, _| !key.starts_with('_') || stamps.contains(&key.as_str()));
    let payload = Value::Object(payload);
    match fault_of(payload_shape(channel), &payload) {
        Some(fault) => Err(fault),
        None => Ok(payload),
    }
}

/// A payload as the channel `C` types it: held to the channel (`held_to`),
/// and refused as malformed where serde refuses what has no fault the table
/// states.
pub(crate) fn decoded<C: Channel>(payload: Map<String, Value>) -> Result<C::Payload, Fault> {
    serde_json::from_value(held_to(C::NAME, payload)?).map_err(|_| Fault::undecoded())
}

/// A frame of the channel `C`, its payload decoded; or, refused, what
/// `refused` makes of its payload's fault and the frame as it came.
fn delivered<C: Channel, E>(
    frame: Frame,
    refused: impl FnOnce(Fault, Frame) -> E,
) -> Result<Delivered<C>, E> {
    let payload = match decoded::<C>(frame.payload.clone()) {
        Ok(payload) => payload,
        Err(fault) => return Err(refused(fault, frame)),
    };
    let user_id = frame
        .payload
        .get("_userId")
        .and_then(Value::as_str)
        .map(str::to_owned);
    Ok(Delivered {
        payload,
        correlation_id: frame.correlation_id,
        scope: frame.scope,
        user_id,
        trace: frame.trace,
    })
}

/// The refusal a typed read gives of `frame`, whose payload is not its
/// channel's for `fault`: the fault named within `payload`, and the payload
/// as it came.
fn not_the_channels(fault: Fault, frame: Frame) -> FrameRefusal {
    let Fault { member, reason } = fault.within("payload");
    FrameRefusal {
        channel: frame.channel,
        member,
        reason,
        payload: Some(Value::Object(frame.payload)),
        scope: frame.scope,
        correlation_id: frame.correlation_id,
    }
}

/// The frames of the channel `C`, each with its payload decoded, out of the
/// frames `F` gives: a transport's (`Frames`), or a client's own bus's
/// (`crate::event_bus::BusFrames`).
pub struct Typed<C: Channel, F = Frames> {
    frames: F,
    channel: PhantomData<fn() -> C>,
}

impl<C: Channel, F> Typed<C, F> {
    pub(crate) fn of(frames: F) -> Typed<C, F> {
        Typed {
            frames,
            channel: PhantomData,
        }
    }
}

impl<C: Channel, F: Stream<Item = Result<Result<Frame, FrameRefusal>, Lagged>> + Unpin>
    Typed<C, F>
{
    /// The next frame; `None` when the stream has ended.
    pub async fn next(&mut self) -> Option<Result<Delivered<C>, StreamError>> {
        std::future::poll_fn(|cx| Pin::new(&mut *self).poll_next(cx)).await
    }
}

impl<C: Channel, F: Stream<Item = Result<Result<Frame, FrameRefusal>, Lagged>> + Unpin> Stream
    for Typed<C, F>
{
    type Item = Result<Delivered<C>, StreamError>;

    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
        Pin::new(&mut self.frames).poll_next(cx).map(|item| {
            item.map(|item| match item {
                Ok(Ok(frame)) => delivered::<C, _>(frame, |fault, frame| {
                    StreamError::Refused(Box::new(not_the_channels(fault, frame)))
                }),
                Ok(Err(refusal)) => Err(StreamError::Refused(Box::new(refusal))),
                Err(Lagged(missed)) => Err(StreamError::Lagged(missed)),
            })
        })
    }
}

/// One resource's frames out of a transport's: those of its scope, and the
/// refusals of its scope's frames, with the hold on that scope that brings
/// them. Dropped, it lets go of the scope.
pub struct ScopedFrames {
    frames: Frames,
    resource: ResourceId,
    _hold: ResourceHold,
}

impl Stream for ScopedFrames {
    type Item = Result<Result<Frame, FrameRefusal>, Lagged>;

    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
        loop {
            match Pin::new(&mut self.frames).poll_next(cx) {
                // A stream carries every scope it holds on the one channel,
                // and another reader may hold another resource's.
                Poll::Ready(Some(Ok(Ok(frame))))
                    if frame.scope.as_ref() != Some(&self.resource) => {}
                Poll::Ready(Some(Ok(Err(refusal))))
                    if refusal.scope.as_ref() != Some(&self.resource) => {}
                other => return other,
            }
        }
    }
}

impl Bus {
    /// Send one frame on the channel `C`.
    pub async fn emit<C: Channel>(
        &self,
        payload: &C::Payload,
        envelope: Envelope,
    ) -> Result<Option<u64>, TransportError> {
        self.emit_on(C::NAME, payload_of(payload)?, envelope).await
    }

    /// The frames delivered on the channel `C` from now on.
    ///
    /// `C` is a channel of no resource's scope. One a resource's scope
    /// carries is read for a resource (`frames_of`), and does not compile
    /// here, where nothing would ever be delivered to it:
    ///
    /// ```compile_fail,E0277
    /// use semiont::bus::Bus;
    /// use semiont::channels::MarkAdded;
    ///
    /// fn read(bus: &Bus) {
    ///     let _ = bus.frames::<MarkAdded>();
    /// }
    /// ```
    pub fn frames<C: Unscoped>(&self) -> Result<Typed<C>, BusRequestError> {
        Ok(Typed::of(self.frames_on(C::NAME)?))
    }

    /// The frames delivered on the channel `C` for `resource` from now on.
    ///
    /// `C` is a channel a resource's scope carries, and reaches only a
    /// client that holds that scope. So the read holds it, from this call
    /// until what it returns is dropped, and is given that resource's frames
    /// and no other's.
    ///
    /// ```
    /// use semiont::bus::Bus;
    /// use semiont::channels::MarkAdded;
    /// use semiont::types::ResourceId;
    ///
    /// async fn follow(bus: &Bus, resource: &ResourceId) {
    ///     let Ok(mut added) = bus.frames_of::<MarkAdded>(resource) else {
    ///         return;
    ///     };
    ///     while let Some(Ok(frame)) = added.next().await {
    ///         println!("{}", frame.payload.id);
    ///     }
    /// }
    /// ```
    pub fn frames_of<C: Scoped>(
        &self,
        resource: &ResourceId,
    ) -> Result<Typed<C, ScopedFrames>, BusRequestError> {
        let frames = self.frames_on(C::NAME)?;
        Ok(Typed::of(ScopedFrames {
            frames,
            resource: resource.clone(),
            _hold: self.transport.subscribe_to_resource(resource),
        }))
    }

    /// Send `payload` as the request of the operation `R` and wait up to
    /// `within` for its result.
    pub async fn request<R: Request>(
        &self,
        payload: &R::Payload,
        within: Duration,
    ) -> Result<<R::Result as Channel>::Payload, SemiontError> {
        Ok(self.result::<R>(payload, within).await?.payload)
    }

    /// A request, as far as the frame that answers it on its result channel:
    /// its payload, and what came beside it, the trace it arrived in among
    /// it. It fails as `request` does. The crate's own: a worker's claim
    /// reads the trace its reply arrived in.
    pub(crate) async fn result<R: Request>(
        &self,
        payload: &R::Payload,
        within: Duration,
    ) -> Result<Delivered<R::Result>, SemiontError> {
        let result = self
            .result_of(&Operation::of::<R>(), payload_of(payload)?, within)
            .await?;
        delivered::<R::Result, _>(result, |fault, _| {
            TransportError::without_response(
                format!(
                    "a payload on {} is not that channel's: {fault}",
                    <R::Result as Channel>::NAME
                ),
                TransportErrorCode::Error,
            )
            .into()
        })
    }
}