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
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
//! The transport contract (protocol/contract/TRANSPORT-CONTRACT.md): what a
//! client needs of whatever carries the bus, the bytes and the gateway's own
//! answers. Three traits, each usable as a trait object, so a client holds
//! them without naming what carries them:
//!
//! - `Transport`: the bus. An emit out, frames in, the connection's state,
//!   the failures it met, the resource scopes it holds and the replies it
//!   awaits.
//! - `ContentTransport`: bytes, which never ride the bus, a resource's
//!   description and its anchored text.
//! - `GatewayOperations`: what a gateway answers for itself. A transport with
//!   no gateway behind it does not implement it.
//!
//! Two kinds of thing are observed here, and they behave differently for a
//! reader that falls behind. An **event stream** (`Frames`, `Failures`) is a
//! sequence: a reader is given every item, and one that fell too far behind
//! is told how many it missed (`Lagged`), never left with a silent gap. A
//! **state** (`state()`) is what is true now: a reader always holds the
//! current value, and may see a run of changes as the latest one.

use crate::errors::{BusRequestError, BusRequestErrorCode, TransportError};
use crate::event_bus::EventBus;
use crate::locked;
use crate::required::{Fault, fault_of, schema};
use crate::types::{
    AnchoredTextAnswer, CreateResourceResponse, GetAnnotationsResponse, GetResourceResponse,
    HealthResponse, MediaTokenResponse, ProtectedResourceMetadata, StatusResponse, UserResponse,
};
use crate::types::{AnnotationId, JobId};
use crate::types::{BusFrame, ResourceId, Schema};
use bytes::Bytes;
use futures_core::Stream;
use serde::{Deserialize, Deserializer, Serialize, Serializer, de};
use serde_json::{Map, Value};
use std::collections::HashMap;
use std::fmt;
use std::future::{Future, IntoFuture};
use std::pin::Pin;
use std::sync::{Arc, Mutex};
use std::task::{Context, Poll};
use tokio::sync::{broadcast, mpsc, oneshot, watch};
use tokio_stream::wrappers::BroadcastStream;
use tokio_stream::wrappers::errors::BroadcastStreamRecvError;

/// A future a trait object can return.
pub type BoxFuture<'a, T> = Pin<Box<dyn Future<Output = T> + Send + 'a>>;

/// How many items of one event stream a reader may fall behind before it
/// misses some.
pub const STREAM_BACKLOG: usize = 1024;

// ── The connection ──────────────────────────────────────────────────────

/// Whether the bus can deliver, as a transport reports it.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum ConnectionState {
    /// Before the transport has started its stream.
    Initial,
    /// A connect is in flight and no stream is live.
    Connecting,
    /// A stream is live. Left only when the stream drops: a transport that
    /// changes what its stream carries without missing anything stays open,
    /// so `Open` reached again always means something may have been missed.
    Open,
    /// The stream dropped, or a connect failed with none live; retrying.
    Reconnecting,
    /// Has been reconnecting for longer than `DEGRADED_THRESHOLD`.
    Degraded,
    /// Not attempting: there is no credential, or the one there is was
    /// refused. Ends when a different credential appears.
    Unauthenticated,
    /// The transport was closed. Terminal.
    Closed,
}

impl ConnectionState {
    pub const fn as_str(self) -> &'static str {
        match self {
            ConnectionState::Initial => "initial",
            ConnectionState::Connecting => "connecting",
            ConnectionState::Open => "open",
            ConnectionState::Reconnecting => "reconnecting",
            ConnectionState::Degraded => "degraded",
            ConnectionState::Unauthenticated => "unauthenticated",
            ConnectionState::Closed => "closed",
        }
    }
}

// ── Frames ──────────────────────────────────────────────────────────────

/// The routing facts beside a payload, never inside it: the correlation id
/// that pairs a reply with its request, and the resource scope of a
/// resource-bound broadcast.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct Envelope {
    pub correlation_id: Option<String>,
    pub scope: Option<ResourceId>,
}

/// The W3C trace context a frame was sent under.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TraceCarrier {
    pub traceparent: String,
    pub tracestate: Option<String>,
}

/// A frame as a transport delivers it: its envelope, its payload, and the
/// trace it was sent under, when it carried one. The payload carries no
/// routing and no trace.
#[derive(Debug, Clone, PartialEq)]
pub struct Frame {
    pub channel: String,
    pub payload: Map<String, Value>,
    pub correlation_id: Option<String>,
    pub scope: Option<ResourceId>,
    pub trace: Option<TraceCarrier>,
}

/// Why a value is refused at a member, as every SDK finds a value's first
/// fault (packages/codegen/schemas/required-shapes.mjs).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FrameRefusalReason {
    /// The value does not carry the member, or the member holds null where it
    /// may not.
    Lacks,
    /// The member is not what its schema allows (of another kind, another
    /// value, form or size), or is one a closed object does not name.
    Malformed,
}

impl FrameRefusalReason {
    const EVERY: [FrameRefusalReason; 2] =
        [FrameRefusalReason::Lacks, FrameRefusalReason::Malformed];

    /// The reason as every SDK spells it.
    pub const fn as_str(self) -> &'static str {
        match self {
            FrameRefusalReason::Lacks => "lacks",
            FrameRefusalReason::Malformed => "malformed",
        }
    }
}

impl Serialize for FrameRefusalReason {
    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        serializer.serialize_str(self.as_str())
    }
}

impl<'de> Deserialize<'de> for FrameRefusalReason {
    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        let spelled = String::deserialize(deserializer)?;
        FrameRefusalReason::EVERY
            .into_iter()
            .find(|reason| reason.as_str() == spelled)
            .ok_or_else(|| de::Error::custom(format!("no refusal's reason is spelled {spelled:?}")))
    }
}

/// What a transport delivers in place of a frame BusFrame does not allow,
/// to the readers it names: those of its channel, in its scope. It names the
/// frame's first fault by its way from the frame (`member`: `payload`,
/// `correlationId`, or a member BusFrame does not name), and carries the
/// frame's payload as it came, when it carried one, and its correlation id,
/// when it carried one BusFrame allows. A typed read gives one, too, for a
/// frame whose payload is not its channel's.
///
/// Said as "a frame on" the channel " is not that channel's: " and the fault.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FrameRefusal {
    pub channel: String,
    pub member: String,
    pub reason: FrameRefusalReason,
    pub payload: Option<Value>,
    pub scope: Option<ResourceId>,
    pub correlation_id: Option<String>,
}

impl fmt::Display for FrameRefusal {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let fault = Fault {
            member: self.member.clone(),
            reason: self.reason,
        };
        write!(
            f,
            "a frame on {} is not that channel's: {fault}",
            self.channel
        )
    }
}

impl FrameRefusal {
    /// The refusal of `frame`, which names its readers on `channel` in
    /// `scope`, for its first fault as BusFrame; `None` when the table of
    /// what BusFrame requires finds none.
    pub fn of(frame: &Value, channel: String, scope: Option<ResourceId>) -> Option<FrameRefusal> {
        let fault = fault_of(schema(BusFrame::NAME), frame)?;
        Some(FrameRefusal {
            channel,
            member: fault.member,
            reason: fault.reason,
            payload: frame.get("payload").cloned(),
            scope,
            correlation_id: correlation_in(frame),
        })
    }
}

/// The correlation id `frame` carries, when it carries one BusFrame allows,
/// whatever else is wrong with it.
fn correlation_in(frame: &Value) -> Option<String> {
    let id = frame.get("correlationId")?;
    let Some((_, allowed)) = schema(BusFrame::NAME)
        .members
        .iter()
        .find(|(name, _)| *name == "correlationId")
    else {
        panic!("BusFrame names no correlationId");
    };
    match fault_of(allowed, id) {
        None => id.as_str().map(str::to_owned),
        Some(_) => None,
    }
}

/// A reader of an event stream fell behind and missed this many items. On a
/// channel that carries events of the record this is a gap: an unknown set
/// of events was missed, and what was built from them is read again.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Lagged(pub u64);

impl fmt::Display for Lagged {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "a reader fell behind and missed {} items", self.0)
    }
}

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

/// An event stream over a broadcast: every item sent after it was taken, in
/// order, a `Lagged` in place of the ones a slow reader missed, and its end
/// when the sender is gone.
pub struct Events<T> {
    inner: BroadcastStream<T>,
}

impl<T: Clone + Send + 'static> Events<T> {
    pub fn new(receiver: broadcast::Receiver<T>) -> Events<T> {
        Events {
            inner: BroadcastStream::new(receiver),
        }
    }

    /// The next item; `None` when the stream has ended.
    pub async fn next(&mut self) -> Option<Result<T, Lagged>> {
        std::future::poll_fn(|cx| Pin::new(&mut *self).poll_next(cx)).await
    }
}

impl<T: Clone + Send + 'static> Stream for Events<T> {
    type Item = Result<T, Lagged>;

    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
        Pin::new(&mut self.inner).poll_next(cx).map(|item| {
            item.map(|received| {
                received.map_err(|BroadcastStreamRecvError::Lagged(missed)| Lagged(missed))
            })
        })
    }
}

/// The frames delivered on one channel, and in place of each frame refused
/// that names its readers there, its refusal.
pub type Frames = Events<Result<Frame, FrameRefusal>>;
/// The failures a transport met: what a server refused, what the gateway
/// never answered, and each line its stream carried that names no reader.
/// Each is reported here as it is returned to its caller.
pub type Failures = Events<TransportError>;

/// The sender of one channel's broadcast: its frames, and the refusals
/// delivered in their place.
pub(crate) type Broadcast = broadcast::Sender<Result<Frame, FrameRefusal>>;

/// The frames of every channel anybody listens to, a broadcast per channel:
/// a reader of one channel falls behind only on that channel's traffic. What
/// a transport delivers goes through one of these.
pub struct FrameHub {
    /// `None` once closed.
    channels: Mutex<Option<HashMap<String, Broadcast>>>,
}

impl Default for FrameHub {
    fn default() -> FrameHub {
        FrameHub {
            channels: Mutex::new(Some(HashMap::new())),
        }
    }
}

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

    /// The frames delivered on `channel` from now on. Of a closed hub, a
    /// stream that has ended.
    pub fn frames(&self, channel: &str) -> Frames {
        match locked(&self.channels).as_mut() {
            Some(channels) => Events::new(
                channels
                    .entry(channel.to_owned())
                    .or_insert_with(|| broadcast::channel(STREAM_BACKLOG).0)
                    .subscribe(),
            ),
            None => Events::new(broadcast::channel(1).1),
        }
    }

    /// Deliver a frame, or the refusal of one, to its channel's readers; how
    /// many there were.
    pub fn deliver(&self, carried: Result<Frame, FrameRefusal>) -> usize {
        let channel = match &carried {
            Ok(frame) => &frame.channel,
            Err(refusal) => &refusal.channel,
        };
        let mut channels = locked(&self.channels);
        let Some(channels) = channels.as_mut() else {
            return 0;
        };
        let Some(sender) = channels.get(channel) else {
            return 0;
        };
        if sender.receiver_count() == 0 {
            channels.remove(channel);
            return 0;
        }
        sender.send(carried).unwrap_or(0)
    }

    /// End every stream taken from this hub, and every one taken later.
    pub fn close(&self) {
        *locked(&self.channels) = None;
    }
}

// ── Replies ─────────────────────────────────────────────────────────────

struct Awaited {
    channels: Vec<String>,
    reply: oneshot::Sender<Result<Frame, FrameRefusal>>,
}

/// The replies a transport's requests still await. A reply is routed here by
/// its correlation id to the one request that awaits it, on a channel of its
/// own, so no amount of other traffic can cost a request its reply; and the
/// ids here are what a wire transport names when it opens a stream, so a
/// reply published while the stream was down is sent again.
pub struct ReplyRouter {
    /// `None` once closed.
    awaited: Mutex<Option<HashMap<String, Awaited>>>,
}

impl ReplyRouter {
    pub fn new() -> Arc<ReplyRouter> {
        Arc::new(ReplyRouter {
            awaited: Mutex::new(Some(HashMap::new())),
        })
    }

    /// Await the reply to `correlation_id` on one of `reply_channels`, until
    /// the returned `PendingReply` is dropped.
    pub fn track(self: &Arc<Self>, correlation_id: &str, reply_channels: &[&str]) -> PendingReply {
        let (reply, receiver) = oneshot::channel();
        if let Some(awaited) = locked(&self.awaited).as_mut() {
            awaited.insert(
                correlation_id.to_owned(),
                Awaited {
                    channels: reply_channels.iter().map(|c| (*c).to_owned()).collect(),
                    reply,
                },
            );
        }
        PendingReply {
            router: self.clone(),
            correlation_id: correlation_id.to_owned(),
            receiver,
        }
    }

    /// Hand a frame, or the refusal of one, to the request that awaits it,
    /// if one does: the one its correlation id names, on a channel of its
    /// reply's.
    pub fn route(&self, carried: Result<&Frame, &FrameRefusal>) {
        let (correlation_id, channel) = match carried {
            Ok(frame) => (&frame.correlation_id, &frame.channel),
            Err(refusal) => (&refusal.correlation_id, &refusal.channel),
        };
        let Some(correlation_id) = correlation_id else {
            return;
        };
        let mut awaited = locked(&self.awaited);
        let Some(awaited) = awaited.as_mut() else {
            return;
        };
        if awaited
            .get(correlation_id)
            .is_some_and(|a| a.channels.contains(channel))
            && let Some(request) = awaited.remove(correlation_id)
        {
            let _ = request
                .reply
                .send(carried.cloned().map_err(FrameRefusal::clone));
        }
    }

    /// The correlation ids still awaited, in name order.
    pub fn awaited(&self) -> Vec<String> {
        let mut ids: Vec<String> = locked(&self.awaited)
            .as_ref()
            .map(|awaited| awaited.keys().cloned().collect())
            .unwrap_or_default();
        ids.sort();
        ids
    }

    /// End every wait: each request still pending learns no reply will come.
    pub fn close(&self) {
        *locked(&self.awaited) = None;
    }
}

/// A reply a request awaits. Dropping it stops the wait: the transport names
/// the reply no more, and one that comes anyway reaches nobody.
pub struct PendingReply {
    router: Arc<ReplyRouter>,
    correlation_id: String,
    receiver: oneshot::Receiver<Result<Frame, FrameRefusal>>,
}

impl PendingReply {
    /// The reply, or the refusal of the frame that carried it; `None` when
    /// the transport closed before either came.
    pub async fn frame(&mut self) -> Option<Result<Frame, FrameRefusal>> {
        (&mut self.receiver).await.ok()
    }
}

impl Drop for PendingReply {
    fn drop(&mut self) {
        if let Some(awaited) = locked(&self.router.awaited).as_mut() {
            awaited.remove(&self.correlation_id);
        }
    }
}

// ── Scopes ──────────────────────────────────────────────────────────────

/// One hold on a resource's scope (`Transport::subscribe_to_resource`),
/// let go when it is dropped.
pub struct ResourceHold {
    release: Option<Box<dyn FnOnce() + Send + Sync>>,
}

impl ResourceHold {
    pub fn new(release: impl FnOnce() + Send + Sync + 'static) -> ResourceHold {
        ResourceHold {
            release: Some(Box::new(release)),
        }
    }
}

impl Drop for ResourceHold {
    fn drop(&mut self) {
        if let Some(release) = self.release.take() {
            release();
        }
    }
}

// ── Transport ───────────────────────────────────────────────────────────

/// The bus, over whatever carries it.
pub trait Transport: Send + Sync + 'static {
    /// What the transport speaks to: an origin over HTTP, an opaque name for
    /// one with no wire.
    fn base_url(&self) -> &str;

    /// Send one frame. Resolves when it has been accepted, with the number of
    /// subscribers it reached, or with `None` when there is no count: an
    /// absent count is never a zero.
    fn emit<'a>(
        &'a self,
        channel: &'a str,
        payload: Map<String, Value>,
        envelope: Envelope,
    ) -> BoxFuture<'a, Result<Option<u64>, TransportError>>;

    /// The frames delivered on `channel` from now on, and the refusal of each
    /// frame refused that names its readers there. Refused, as
    /// `bus.unsubscribed`, for a channel this transport can never deliver.
    fn frames(&self, channel: &str) -> Result<Frames, BusRequestError>;

    /// Whether the transport's stream delivers `channel` globally: whether a
    /// reply published there can reach this client.
    fn is_subscribed(&self, channel: &str) -> bool;

    /// Take one hold on a resource's scope. The scope is on the stream from
    /// its first hold to its last release; holds are counted per resource.
    fn subscribe_to_resource(&self, resource_id: &ResourceId) -> ResourceHold;

    /// The connection's state: the current value, and each change after it.
    fn state(&self) -> watch::Receiver<ConnectionState>;

    /// The failures the transport meets, from now on, and each line its
    /// stream carried that names no reader. A listener taken as soon as the
    /// transport is made hears every one, from its first request.
    fn failures(&self) -> Failures;

    /// Await the reply to `correlation_id` on one of `reply_channels`. A
    /// request calls this before it emits, so its reply cannot arrive
    /// unawaited.
    fn track_reply(&self, correlation_id: &str, reply_channels: &[&str]) -> PendingReply;

    /// Publish into `bus` every frame this transport delivers, and the
    /// refusal of every frame it refuses that names its readers. The bus is
    /// its client's: a transport never constructs or replaces one.
    fn bridge_into(&self, bus: Arc<EventBus>);

    /// Stop: the state becomes `Closed`, every stream ends, and every request
    /// still pending fails as closed. Closing twice is closing once.
    fn close(&self) -> BoxFuture<'_, ()>;
}

/// The refusal a transport gives for a channel it can never deliver.
pub fn unsubscribed(channel: &str) -> BusRequestError {
    BusRequestError::new(
        BusRequestErrorCode::Unsubscribed,
        format!(
            "Transport is not subscribed to {channel}: a frame on it can never arrive on this connection. Add the channel to this client's channels."
        ),
    )
}

// ── Content ─────────────────────────────────────────────────────────────

/// An upload: the bytes, and each field the resource is created with.
#[derive(Debug, Clone, PartialEq)]
pub struct PutBinaryRequest {
    pub name: String,
    pub bytes: Bytes,
    /// The media type of the bytes.
    pub format: String,
    pub storage_uri: String,
    pub entity_types: Vec<String>,
    pub language: Option<String>,
    pub source_annotation_id: Option<AnnotationId>,
    pub source_resource_id: Option<ResourceId>,
    pub generation_prompt: Option<String>,
    /// The agent or agents that generated it, as the schema's `Agent`.
    pub generator: Option<Value>,
    /// The job this resource fulfils, when a worker is creating it.
    pub job_id: Option<JobId>,
    pub is_draft: Option<bool>,
    /// A clone's provenance: with it, the resource is created as a clone.
    pub clone_token: Option<String>,
    /// Of a clone: archive the source once the clone exists.
    pub archive_original: Option<bool>,
}

impl PutBinaryRequest {
    /// An upload of `bytes`, of the media type `format`, as the resource
    /// `name` kept at `storage_uri`: what every upload states, and nothing
    /// else.
    pub fn new(
        name: impl Into<String>,
        bytes: Bytes,
        format: impl Into<String>,
        storage_uri: impl Into<String>,
    ) -> Self {
        Self {
            name: name.into(),
            bytes,
            format: format.into(),
            storage_uri: storage_uri.into(),
            entity_types: Vec::new(),
            language: None,
            source_annotation_id: None,
            source_resource_id: None,
            generation_prompt: None,
            generator: None,
            job_id: None,
            is_draft: None,
            clone_token: None,
            archive_original: None,
        }
    }
}

/// How much of an upload has been sent.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct UploadProgress {
    pub bytes_uploaded: u64,
    /// The size of the whole request body.
    pub total_bytes: u64,
}

/// An upload in flight. As a stream it gives its progress, and ends when the
/// upload has; awaited, it gives the id of the resource created. Dropped, it
/// is cancelled: nothing more is sent.
pub struct Upload {
    progress: mpsc::UnboundedReceiver<UploadProgress>,
    sending: Option<BoxFuture<'static, Result<CreateResourceResponse, TransportError>>>,
    outcome: Option<Result<CreateResourceResponse, TransportError>>,
}

impl Upload {
    /// An upload `sending` performs, reporting its progress to the sender
    /// `progress` is the other end of.
    pub fn new(
        progress: mpsc::UnboundedReceiver<UploadProgress>,
        sending: BoxFuture<'static, Result<CreateResourceResponse, TransportError>>,
    ) -> Upload {
        Upload {
            progress,
            sending: Some(sending),
            outcome: None,
        }
    }

    fn drive(&mut self, cx: &mut Context<'_>) {
        if let Some(sending) = self.sending.as_mut()
            && let Poll::Ready(outcome) = sending.as_mut().poll(cx)
        {
            self.outcome = Some(outcome);
            self.sending = None;
        }
    }
}

impl Stream for Upload {
    type Item = UploadProgress;

    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
        self.drive(cx);
        match self.progress.poll_recv(cx) {
            Poll::Ready(Some(progress)) => Poll::Ready(Some(progress)),
            Poll::Ready(None) => Poll::Ready(None),
            // What `sending` reported before it finished has been given, and
            // it will report no more.
            Poll::Pending if self.sending.is_none() => Poll::Ready(None),
            Poll::Pending => Poll::Pending,
        }
    }
}

impl IntoFuture for Upload {
    type Output = Result<CreateResourceResponse, TransportError>;
    type IntoFuture = BoxFuture<'static, Self::Output>;

    fn into_future(mut self) -> Self::IntoFuture {
        Box::pin(async move {
            std::future::poll_fn(|cx| {
                self.drive(cx);
                match self.outcome.take() {
                    Some(outcome) => Poll::Ready(outcome),
                    None => Poll::Pending,
                }
            })
            .await
        })
    }
}

/// A resource's bytes, with their media type.
#[derive(Debug, Clone, PartialEq)]
pub struct Content {
    pub bytes: Bytes,
    pub content_type: String,
}

/// A resource's bytes as they arrive, with their media type.
pub struct ContentStream {
    pub bytes: Pin<Box<dyn Stream<Item = Result<Bytes, TransportError>> + Send>>,
    pub content_type: String,
}

/// Bytes, which never ride the bus, a resource's description as linked data,
/// its annotations and its anchored text.
pub trait ContentTransport: Send + Sync + 'static {
    /// Upload `request`'s bytes as a new resource.
    fn put_binary(&self, request: PutBinaryRequest) -> Upload;

    /// A resource's bytes, unchanged, with their media type.
    fn get_binary<'a>(
        &'a self,
        resource_id: &'a ResourceId,
    ) -> BoxFuture<'a, Result<Content, TransportError>>;

    /// The same, as a stream.
    fn get_binary_stream<'a>(
        &'a self,
        resource_id: &'a ResourceId,
    ) -> BoxFuture<'a, Result<ContentStream, TransportError>>;

    /// A resource's description: itself and its annotations, as linked data.
    fn get_resource_graph<'a>(
        &'a self,
        resource_id: &'a ResourceId,
    ) -> BoxFuture<'a, Result<GetResourceResponse, TransportError>>;

    /// A resource's annotations, with the persons they mention named, and how
    /// many there are.
    fn get_annotations<'a>(
        &'a self,
        resource_id: &'a ResourceId,
    ) -> BoxFuture<'a, Result<GetAnnotationsResponse, TransportError>>;

    /// A resource's anchored text: the text read from its content with where
    /// each run of it is on a page, a stored decline, or why there is none.
    fn get_anchored_text<'a>(
        &'a self,
        resource_id: &'a ResourceId,
    ) -> BoxFuture<'a, Result<AnchoredTextAnswer, TransportError>>;
}

// ── The gateway's own operations ────────────────────────────────────────

/// What a gateway answers for itself.
pub trait GatewayOperations: Send + Sync + 'static {
    fn get_current_user(&self) -> BoxFuture<'_, Result<UserResponse, TransportError>>;

    /// A token that lets a browser fetch one resource's bytes.
    fn get_media_token<'a>(
        &'a self,
        resource_id: &'a ResourceId,
    ) -> BoxFuture<'a, Result<MediaTokenResponse, TransportError>>;

    /// Which issuer the knowledge base trusts (RFC 9728). Public: read before
    /// any token exists.
    fn get_protected_resource_metadata(
        &self,
    ) -> BoxFuture<'_, Result<ProtectedResourceMetadata, TransportError>>;

    fn health_check(&self) -> BoxFuture<'_, Result<HealthResponse, TransportError>>;

    fn get_status(&self) -> BoxFuture<'_, Result<StatusResponse, TransportError>>;
}

#[cfg(test)]
mod tests {
    use super::*;

    fn frame(channel: &str, correlation_id: Option<&str>) -> Frame {
        Frame {
            channel: channel.to_owned(),
            payload: Map::new(),
            correlation_id: correlation_id.map(str::to_owned),
            scope: None,
            trace: None,
        }
    }

    #[tokio::test]
    async fn a_reader_of_one_channel_is_not_lagged_by_another() {
        let hub = FrameHub::new();
        let mut quiet = hub.frames("quiet");
        let _busy = hub.frames("busy");
        for _ in 0..(STREAM_BACKLOG * 3) {
            hub.deliver(Ok(frame("busy", None)));
        }
        hub.deliver(Ok(frame("quiet", None)));
        assert_eq!(quiet.next().await, Some(Ok(Ok(frame("quiet", None)))));
    }

    #[tokio::test]
    async fn a_reader_that_fell_behind_is_told_how_far() {
        let hub = FrameHub::new();
        let mut frames = hub.frames("busy");
        for _ in 0..(STREAM_BACKLOG + 5) {
            hub.deliver(Ok(frame("busy", None)));
        }
        assert_eq!(frames.next().await, Some(Err(Lagged(5))));
        assert!(matches!(frames.next().await, Some(Ok(_))));
    }

    #[tokio::test]
    async fn a_closed_hub_ends_every_stream() {
        let hub = FrameHub::new();
        let mut before = hub.frames("a");
        hub.close();
        assert_eq!(before.next().await, None);
        assert_eq!(hub.frames("a").next().await, None);
    }

    #[tokio::test]
    async fn a_reply_reaches_the_request_that_awaits_it_and_no_other() {
        let router = ReplyRouter::new();
        let mut mine = router.track("cid-1", &["result", "failure"]);
        let mut theirs = router.track("cid-2", &["result", "failure"]);
        assert_eq!(router.awaited(), ["cid-1", "cid-2"]);

        // The same id on a channel that is not its reply's settles nothing.
        router.route(Ok(&frame("progress", Some("cid-1"))));
        router.route(Ok(&frame("result", Some("cid-1"))));
        assert_eq!(mine.frame().await, Some(Ok(frame("result", Some("cid-1")))));
        assert_eq!(router.awaited(), ["cid-2"]);

        router.close();
        assert_eq!(theirs.frame().await, None);
    }

    fn refusal(channel: &str, correlation_id: Option<&str>) -> FrameRefusal {
        FrameRefusal {
            channel: channel.to_owned(),
            member: "addedByALaterGateway".to_owned(),
            reason: FrameRefusalReason::Malformed,
            payload: Some(serde_json::json!({ "response": {} })),
            scope: None,
            correlation_id: correlation_id.map(str::to_owned),
        }
    }

    #[tokio::test]
    async fn a_refused_reply_reaches_the_request_its_correlation_id_names_and_one_naming_none_reaches_none()
     {
        let router = ReplyRouter::new();
        let mut mine = router.track("cid-1", &["result", "failure"]);
        let _theirs = router.track("cid-2", &["result", "failure"]);

        router.route(Err(&refusal("result", None)));
        router.route(Err(&refusal("progress", Some("cid-1"))));
        assert_eq!(router.awaited(), ["cid-1", "cid-2"]);

        router.route(Err(&refusal("result", Some("cid-1"))));
        assert_eq!(
            mine.frame().await,
            Some(Err(refusal("result", Some("cid-1"))))
        );
        assert_eq!(router.awaited(), ["cid-2"]);
    }

    #[tokio::test]
    async fn a_dropped_wait_is_named_no_more() {
        let router = ReplyRouter::new();
        let pending = router.track("cid-1", &["result"]);
        drop(pending);
        assert!(router.awaited().is_empty());
    }

    #[tokio::test]
    async fn a_hold_is_released_once_when_dropped() {
        let released = Arc::new(Mutex::new(0));
        let count = released.clone();
        let hold = ResourceHold::new(move || *locked(&count) += 1);
        drop(hold);
        assert_eq!(*locked(&released), 1);
    }
}