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
//! A client's own bus: frames published and observed inside one process. A
//! client constructs one and hands it to its transport (`bridge_into`), which
//! publishes into it every frame it delivers; what the client's own parts
//! say to each other goes through it too.
//!
//! A frame is published globally or into one resource's scope, and a view
//! sees one or the other: the global view of a channel does not see a frame
//! published into a scope, and a scope's view sees only its own.
//!
//! A view of one channel gives its frames in the order they were published.
//! Two views give no order between them, so a reader of several channels
//! that needs what was said in the order it was said takes one view of them
//! all (`frames_among`).
//!
//! By type (`publish`, `stream`), the channel is a type of `crate::channels`
//! and the payload is that channel's own, as on `crate::bus::Bus`.

use crate::bus::{Typed, payload_of};
use crate::channels::Channel;
use crate::errors::TransportError;
use crate::transport::{Broadcast, Envelope, Events, Frame, FrameRefusal, Lagged, STREAM_BACKLOG};
use crate::types::ResourceId;
use futures_core::Stream;
use serde_json::{Map, Value};
use std::collections::HashMap;
use std::pin::Pin;
use std::sync::{Arc, Mutex, MutexGuard};
use std::task::{Context, Poll};
use tokio::sync::broadcast;

/// A view's key: the channel, and the scope it sees.
type View = (String, Option<ResourceId>);

struct Channels {
    frames: HashMap<String, Broadcast>,
    /// The views of several channels at once, each with the channels it sees.
    among: Vec<(Vec<String>, Broadcast)>,
    /// How many readers each view has: what `emit` reports.
    observers: HashMap<View, usize>,
}

struct Inner {
    /// `None` once destroyed.
    channels: Mutex<Option<Channels>>,
}

impl Inner {
    fn channels(&self) -> MutexGuard<'_, Option<Channels>> {
        self.channels
            .lock()
            .unwrap_or_else(|poisoned| poisoned.into_inner())
    }

    /// Publish a frame, or the refusal of one, into the view its channel and
    /// scope name. How many readers that view had.
    fn deliver(&self, carried: Result<Frame, FrameRefusal>) -> usize {
        let (channel, scope) = match &carried {
            Ok(frame) => (&frame.channel, &frame.scope),
            Err(refusal) => (&refusal.channel, &refusal.scope),
        };
        let mut channels = self.channels();
        let Some(channels) = channels.as_mut() else {
            return 0;
        };
        let observers = channels
            .observers
            .get(&(channel.clone(), scope.clone()))
            .copied()
            .unwrap_or(0);
        for (seen, sender) in &channels.among {
            if seen.iter().any(|one| one == channel) {
                let _ = sender.send(carried.clone());
            }
        }
        if let Some(sender) = channels.frames.get(channel) {
            let _ = sender.send(carried);
        }
        observers
    }

    fn frames(self: &Arc<Self>, channel: &str, scope: Option<ResourceId>) -> BusFrames {
        let views = vec![(channel.to_owned(), scope.clone())];
        let mut channels = self.channels();
        let events = match channels.as_mut() {
            Some(channels) => {
                *channels.observers.entry(views[0].clone()).or_insert(0) += 1;
                Events::new(
                    channels
                        .frames
                        .entry(channel.to_owned())
                        .or_insert_with(|| broadcast::channel(STREAM_BACKLOG).0)
                        .subscribe(),
                )
            }
            None => Events::new(broadcast::channel(1).1),
        };
        BusFrames {
            bus: self.clone(),
            views,
            scope,
            events,
        }
    }

    fn frames_among(self: &Arc<Self>, among: &[&str]) -> BusFrames {
        let seen: Vec<String> = among.iter().map(|channel| (*channel).to_owned()).collect();
        let views: Vec<View> = seen.iter().map(|channel| (channel.clone(), None)).collect();
        let mut channels = self.channels();
        let events = match channels.as_mut() {
            Some(channels) => {
                for view in &views {
                    *channels.observers.entry(view.clone()).or_insert(0) += 1;
                }
                // A view nobody reads any more is let go here, where the
                // next one is made.
                channels
                    .among
                    .retain(|(_, sender)| sender.receiver_count() > 0);
                let (sender, receiver) = broadcast::channel(STREAM_BACKLOG);
                channels.among.push((seen, sender));
                Events::new(receiver)
            }
            None => Events::new(broadcast::channel(1).1),
        };
        BusFrames {
            bus: self.clone(),
            views,
            scope: None,
            events,
        }
    }
}

/// The frames of one view: a channel's, or several channels', globally or in
/// one scope; and the refusals published there in place of frames.
pub struct BusFrames {
    bus: Arc<Inner>,
    /// What it reads, for the count `emit` reports.
    views: Vec<View>,
    scope: Option<ResourceId>,
    events: Events<Result<Frame, FrameRefusal>>,
}

impl BusFrames {
    pub async fn next(&mut self) -> Option<Result<Result<Frame, FrameRefusal>, Lagged>> {
        std::future::poll_fn(|cx| Pin::new(&mut *self).poll_next(cx)).await
    }
}

impl Stream for BusFrames {
    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.events).poll_next(cx) {
                Poll::Ready(Some(Ok(Ok(frame)))) if frame.scope != self.scope => continue,
                Poll::Ready(Some(Ok(Err(refusal)))) if refusal.scope != self.scope => continue,
                other => return other,
            }
        }
    }
}

impl Drop for BusFrames {
    fn drop(&mut self) {
        let mut channels = self.bus.channels();
        let Some(channels) = channels.as_mut() else {
            return;
        };
        for view in &self.views {
            if let Some(count) = channels.observers.get_mut(view) {
                *count = count.saturating_sub(1);
                if *count == 0 {
                    channels.observers.remove(view);
                }
            }
        }
    }
}

/// A client's own bus.
#[derive(Clone)]
pub struct EventBus {
    inner: Arc<Inner>,
}

impl Default for EventBus {
    fn default() -> EventBus {
        EventBus {
            inner: Arc::new(Inner {
                channels: Mutex::new(Some(Channels {
                    frames: HashMap::new(),
                    among: Vec::new(),
                    observers: HashMap::new(),
                })),
            }),
        }
    }
}

impl EventBus {
    pub fn new() -> EventBus {
        EventBus::default()
    }

    /// Publish a frame: globally, or into `envelope.scope`. How many readers
    /// its view had when it was published. A destroyed bus publishes nothing.
    pub fn emit(&self, channel: &str, payload: Map<String, Value>, envelope: Envelope) -> usize {
        self.inner.deliver(Ok(Frame {
            channel: channel.to_owned(),
            payload,
            correlation_id: envelope.correlation_id,
            scope: envelope.scope,
            trace: None,
        }))
    }

    /// Publish the refusal of a frame in its place, into the view its
    /// channel and scope name: what a transport bridged into this bus does
    /// with each frame it refuses that names its readers. How many readers
    /// that view had.
    pub fn emit_refusal(&self, refusal: FrameRefusal) -> usize {
        self.inner.deliver(Err(refusal))
    }

    /// The frames published globally on `channel` from now on. A frame
    /// published into a resource's scope is not among them.
    pub fn frames(&self, channel: &str) -> BusFrames {
        self.inner.frames(channel, None)
    }

    /// The frames published globally on any of `channels` from now on, in
    /// the order they were published.
    pub fn frames_among(&self, channels: &[&str]) -> BusFrames {
        self.inner.frames_among(channels)
    }

    /// Publish one frame of the channel `C`, globally or into
    /// `envelope.scope`. How many readers its view had.
    pub fn publish<C: Channel>(
        &self,
        payload: &C::Payload,
        envelope: Envelope,
    ) -> Result<usize, TransportError> {
        Ok(self.emit(C::NAME, payload_of(payload)?, envelope))
    }

    /// The frames published globally on the channel `C` from now on, each
    /// with its payload decoded.
    pub fn stream<C: Channel>(&self) -> Typed<C, BusFrames> {
        Typed::of(self.frames(C::NAME))
    }

    /// This bus, seen from one resource's scope.
    pub fn scope(&self, resource_id: &ResourceId) -> ScopedEventBus {
        ScopedEventBus {
            inner: self.inner.clone(),
            scope: resource_id.clone(),
        }
    }

    /// The channels somebody is reading now, in name order.
    pub fn observed_channels(&self) -> Vec<String> {
        let mut observed: Vec<String> = self
            .inner
            .channels()
            .as_ref()
            .map(|channels| channels.observers.keys().map(|(c, _)| c.clone()).collect())
            .unwrap_or_default();
        observed.sort();
        observed.dedup();
        observed
    }

    /// End every view, and every one taken later. Destroying twice is
    /// destroying once.
    pub fn destroy(&self) {
        *self.inner.channels() = None;
    }

    pub fn destroyed(&self) -> bool {
        self.inner.channels().is_none()
    }
}

/// A bus seen from one resource's scope: what is published through it goes
/// into that scope, and its views see only that scope's frames.
#[derive(Clone)]
pub struct ScopedEventBus {
    inner: Arc<Inner>,
    scope: ResourceId,
}

impl ScopedEventBus {
    /// Publish into this scope, with `correlation_id` when the frame is a
    /// reply or a request.
    pub fn emit(
        &self,
        channel: &str,
        payload: Map<String, Value>,
        correlation_id: Option<String>,
    ) -> usize {
        self.inner.deliver(Ok(Frame {
            channel: channel.to_owned(),
            payload,
            correlation_id,
            scope: Some(self.scope.clone()),
            trace: None,
        }))
    }

    /// The frames published into this scope on `channel` from now on.
    pub fn frames(&self, channel: &str) -> BusFrames {
        self.inner.frames(channel, Some(self.scope.clone()))
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::transport::FrameRefusalReason;
    use serde_json::json;

    fn payload(n: u64) -> Map<String, Value> {
        json!({ "n": n }).as_object().cloned().unwrap_or_default()
    }

    /// A sample focus: it names its resource, as every focus does.
    fn focus(n: u64) -> Map<String, Value> {
        let mut focus = payload(n);
        focus.insert("resourceId".to_owned(), json!("res-1"));
        focus
    }

    #[tokio::test]
    async fn a_global_view_does_not_see_a_scope_and_a_scope_sees_only_its_own() {
        let bus = EventBus::new();
        let mut global = bus.frames("mark:added");
        let mut one = bus.scope(&"res-1".parse().unwrap()).frames("mark:added");
        let mut other = bus.scope(&"res-2".parse().unwrap()).frames("mark:added");

        assert_eq!(bus.emit("mark:added", payload(1), Envelope::default()), 1);
        assert_eq!(
            bus.scope(&"res-1".parse().unwrap())
                .emit("mark:added", payload(2), None),
            1
        );
        assert_eq!(
            bus.scope(&"res-3".parse().unwrap())
                .emit("mark:added", payload(3), None),
            0
        );
        bus.destroy();

        let seen = |frames: Vec<Frame>| -> Vec<Value> {
            frames.into_iter().map(|f| f.payload["n"].clone()).collect()
        };
        let mut drained = Vec::new();
        while let Some(Ok(Ok(frame))) = global.next().await {
            drained.push(frame);
        }
        assert_eq!(seen(drained), [json!(1)]);
        let mut drained = Vec::new();
        while let Some(Ok(Ok(frame))) = one.next().await {
            drained.push(frame);
        }
        assert_eq!(seen(drained), [json!(2)]);
        assert_eq!(other.next().await, None);
    }

    #[tokio::test]
    async fn the_count_follows_the_readers() {
        let bus = EventBus::new();
        assert_eq!(bus.emit("beckon:focus", focus(1), Envelope::default()), 0);
        let first = bus.frames("beckon:focus");
        let second = bus.frames("beckon:focus");
        assert_eq!(bus.emit("beckon:focus", focus(2), Envelope::default()), 2);
        assert_eq!(bus.observed_channels(), ["beckon:focus"]);
        drop(first);
        drop(second);
        assert_eq!(bus.emit("beckon:focus", focus(3), Envelope::default()), 0);
        assert!(bus.observed_channels().is_empty());
    }

    #[tokio::test]
    async fn a_view_of_several_channels_gives_them_in_the_order_they_were_published() {
        let bus = EventBus::new();
        let mut both = bus.frames_among(&["mark:requested", "mark:submit"]);
        assert_eq!(bus.observed_channels(), ["mark:requested", "mark:submit"]);

        for n in 0..6 {
            let channel = if n % 2 == 0 {
                "mark:requested"
            } else {
                "mark:submit"
            };
            assert_eq!(bus.emit(channel, payload(n), Envelope::default()), 1);
        }
        bus.emit("mark:create-error", payload(9), Envelope::default());
        bus.scope(&"res-1".parse().unwrap())
            .emit("mark:requested", payload(9), None);
        drop(bus.frames_among(&["mark:requested"]));
        bus.destroy();

        let mut seen = Vec::new();
        while let Some(Ok(Ok(frame))) = both.next().await {
            seen.push((frame.channel, frame.payload["n"].clone()));
        }
        let said = |channel: &str, n: u64| (channel.to_owned(), json!(n));
        assert_eq!(
            seen,
            [
                said("mark:requested", 0),
                said("mark:submit", 1),
                said("mark:requested", 2),
                said("mark:submit", 3),
                said("mark:requested", 4),
                said("mark:submit", 5),
            ]
        );
    }

    #[tokio::test]
    async fn a_view_of_several_channels_is_counted_on_each_until_it_is_dropped() {
        let bus = EventBus::new();
        let both = bus.frames_among(&["beckon:hover", "browse:click"]);
        assert_eq!(bus.emit("beckon:hover", payload(1), Envelope::default()), 1);
        assert_eq!(bus.emit("browse:click", payload(2), Envelope::default()), 1);
        drop(both);
        assert_eq!(bus.emit("beckon:hover", payload(3), Envelope::default()), 0);
        assert!(bus.observed_channels().is_empty());
    }

    #[tokio::test]
    async fn a_destroyed_bus_is_inert() {
        let bus = EventBus::new();
        bus.destroy();
        bus.destroy();
        assert!(bus.destroyed());
        assert_eq!(bus.emit("beckon:focus", focus(1), Envelope::default()), 0);
        assert_eq!(bus.frames("beckon:focus").next().await, None);
        assert_eq!(bus.frames_among(&["beckon:focus"]).next().await, None);
    }

    #[tokio::test]
    async fn a_refusal_is_published_into_the_view_its_channel_and_scope_name() {
        let bus = EventBus::new();
        let resource: ResourceId = "res-1".parse().unwrap();
        let mut global = bus.frames("beckon:focus");
        let mut scoped = bus.scope(&resource).frames("beckon:focus");
        let mut among = bus.frames_among(&["beckon:focus"]);
        let refusal = |scope: Option<ResourceId>| FrameRefusal {
            channel: "beckon:focus".to_owned(),
            member: "correlationId".to_owned(),
            reason: FrameRefusalReason::Malformed,
            payload: Some(Value::Object(focus(1))),
            scope,
            correlation_id: None,
        };

        assert_eq!(bus.emit_refusal(refusal(None)), 2);
        assert_eq!(bus.emit_refusal(refusal(Some(resource.clone()))), 1);
        bus.destroy();

        assert_eq!(global.next().await, Some(Ok(Err(refusal(None)))));
        assert_eq!(global.next().await, None);
        assert_eq!(among.next().await, Some(Ok(Err(refusal(None)))));
        assert_eq!(among.next().await, None);
        assert_eq!(scoped.next().await, Some(Ok(Err(refusal(Some(resource))))));
        assert_eq!(scoped.next().await, None);
    }
}