1
//! Wire pieces for subscriptions.
2
//!
3
//! r[impl jetstream.subscription.overview]
4
//! A subscription is a streaming response: one request, many responses
5
//! sharing its tag, terminated explicitly. This module carries the three
6
//! things that shape needs on the wire and nothing else — the terminator,
7
//! cancellation, and the endpoint identifier. The client and server
8
//! plumbing that uses them lands separately.
9

            
10
use jetstream_wireformat::{Data, JetStreamWireFormat, WireFormat};
11

            
12
/// r[impl jetstream.subscription.compat]
13
/// The terminator, and cancellation, take **global** message ids in the
14
/// space below `MESSAGE_ID_START`, exactly as `RJETSTREAMERROR` already
15
/// does. That is what keeps `102 + 2 * index` intact: a streaming method
16
/// costs no extra per-method id, so `r[jetstream.rpc.swift.message-ids]`
17
/// and `r[jetstream.rpc.ts.message-ids]` do not change and no protocol is
18
/// re-generated for its unary methods.
19
///
20
/// 5, 6, 7 and 11 are taken by the error frames; 100 and 101 by version.
21
/// `RERROR` is the last of those: it sat at 107, overlapping the
22
/// generated response id for method index 2, until it moved down here to
23
/// join its siblings.
24
pub const RDONE: u8 = 8;
25

            
26
/// r[impl jetstream.subscription.cancel]
27
pub const TCANCEL: u8 = 9;
28
/// r[impl jetstream.subscription.cancel]
29
pub const RCANCEL: u8 = TCANCEL + 1;
30

            
31
/// r[impl jetstream.subscription.cancel]
32
/// Cancellation bears a **fresh** tag and names its target in the
33
/// payload, which is the shape 9P's `Tflush` uses and the one this
34
/// specification adopted after an earlier draft got the mechanics
35
/// backwards. Sending it under the subscription's own tag would put two
36
/// calls under one correlation key while that tag is still in flight.
37
#[derive(Debug, Clone, PartialEq, Eq, JetStreamWireFormat)]
38
pub struct Tcancel {
39
    /// The tag of the subscription being cancelled.
40
    pub oldtag: u16,
41
    /// r[impl jetstream.subscription.identity]
42
    /// Zero when the cancellation travels on the subscription's own lane,
43
    /// where `oldtag` is unambiguous. Otherwise the binding identifier,
44
    /// because tags are allocated per lane and a concurrent subscription
45
    /// elsewhere on the session may hold the same number.
46
    ///
47
    /// Zero is **reserved** and never a real binding, which is what makes
48
    /// the sentinel sound. Prefer [`Tcancel::on_lane`] and
49
    /// [`Tcancel::off_lane`] over writing this field: the specification
50
    /// used to recommend a counter starting at zero, so the first
51
    /// subscription of a session got a binding indistinguishable from
52
    /// "no binding" — and a receiver then resolved `oldtag` against the
53
    /// wrong lane.
54
    pub binding: u64,
55
}
56

            
57
impl Tcancel {
58
    /// Cancel a subscription on the lane this cancellation travels.
59
    /// `oldtag` is unambiguous there, so no binding is named.
60
    pub fn on_lane(oldtag: u16) -> Self {
61
        Tcancel { oldtag, binding: 0 }
62
    }
63

            
64
    /// Cancel a subscription living on some *other* lane of the session,
65
    /// naming it by its binding identifier.
66
    ///
67
    /// # Panics
68
    ///
69
    /// If `binding` is zero, which is reserved for the on-lane case.
70
    /// A caller reaching this has allocated bindings from a counter
71
    /// starting at zero — the allocation `r[jetstream.subscription.identity]`
72
    /// now forbids for exactly this reason.
73
    pub fn off_lane(oldtag: u16, binding: u64) -> Self {
74
        assert_ne!(
75
            binding, 0,
76
            "binding identifier zero is reserved for the on-lane case; \
77
             allocate bindings from one"
78
        );
79
        Tcancel { oldtag, binding }
80
    }
81

            
82
    /// The binding this names, or `None` when it is on the subscription's
83
    /// own lane.
84
    pub fn target_binding(&self) -> Option<u64> {
85
        (self.binding != 0).then_some(self.binding)
86
    }
87
}
88

            
89
/// r[impl jetstream.subscription.cancel]
90
/// The acknowledgement, which `r[jetstream.subscription.cancel]` requires
91
/// to arrive on the subscription's own lane after every item already
92
/// emitted there — that ordering is what makes the tag safe to reuse.
93
#[derive(Debug, Clone, PartialEq, Eq, JetStreamWireFormat)]
94
pub struct Rcancel {
95
    /// The tag that has now stopped emitting.
96
    pub oldtag: u16,
97
}
98

            
99
/// r[impl jetstream.lane.addressing]
100
/// The endpoint a subscription addresses within a peer — the room, the
101
/// object, the cell. An opaque byte string: codegen emits the client that
102
/// carries it and cannot know an application's naming, so any structure
103
/// is the application's to impose and no implementation's to interpret.
104
#[derive(Debug, Clone, PartialEq, Eq, JetStreamWireFormat)]
105
pub struct Endpoint(pub Data);
106

            
107
impl Endpoint {
108
    /// The endpoint naming nothing in particular: a peer that hosts one
109
    /// thing, which is every protocol written before this existed.
110
    pub fn root() -> Self {
111
        Endpoint(Data(Vec::new()))
112
    }
113

            
114
    pub fn as_bytes(&self) -> &[u8] {
115
        &self.0 .0
116
    }
117
}
118

            
119
impl From<&str> for Endpoint {
120
    fn from(name: &str) -> Self {
121
        Endpoint(Data(name.as_bytes().to_vec()))
122
    }
123
}
124

            
125
/// r[impl jetstream.subscription.termination]
126
/// A terminator that carries a typed value names the method it ends.
127
///
128
/// `RDONE` is one **global** message id, which is what keeps
129
/// `102 + 2 * index` intact for every other method — but a protocol with
130
/// two subscription methods then has two terminal types sharing one id,
131
/// and a decoder handed the type byte alone cannot tell which to decode.
132
/// The tag would disambiguate it, and a decoder does not see the tag.
133
///
134
/// So the payload names its method: the message id of the *request* that
135
/// opened the subscription, which is unique per method by construction.
136
/// One byte, and the two rules stop contradicting each other.
137
#[derive(Debug, Clone, PartialEq, Eq)]
138
pub struct Terminator<D> {
139
    /// The message id of the request that opened this subscription.
140
    pub method: u8,
141
    pub value: D,
142
}
143

            
144
impl<D: WireFormat> WireFormat for Terminator<D> {
145
    fn byte_size(&self) -> u32 {
146
        1 + self.value.byte_size()
147
    }
148

            
149
    fn encode<W: std::io::Write>(&self, w: &mut W) -> std::io::Result<()> {
150
        self.method.encode(w)?;
151
        self.value.encode(w)
152
    }
153

            
154
    fn decode<R: std::io::Read>(r: &mut R) -> std::io::Result<Self> {
155
        let method = u8::decode(r)?;
156
        Ok(Terminator {
157
            method,
158
            value: D::decode(r)?,
159
        })
160
    }
161
}
162

            
163
/// r[impl jetstream.subscription.surface.terminal-value]
164
/// r[impl jetstream.subscription.surface.composition]
165
/// What a subscription yields. The end is a **value in the sequence**,
166
/// not the absence of one.
167
///
168
/// Both rules need this and neither is satisfiable without it: a `Stream`
169
/// ends with `None`, which has nowhere to put a result, and `select_all`
170
/// drops a finished stream silently, so a merged subscription would
171
/// deliver every item and no terminator.
172
#[derive(Debug, Clone, PartialEq, Eq)]
173
pub enum Item<T, D> {
174
    /// One item of the sequence.
175
    Next(T),
176
    /// The end, and what it ended with.
177
    Done(D),
178
}
179

            
180
impl<T, D> Item<T, D> {
181
    pub fn is_done(&self) -> bool {
182
        matches!(self, Item::Done(_))
183
    }
184

            
185
    pub fn into_next(self) -> Option<T> {
186
        match self {
187
            Item::Next(t) => Some(t),
188
            Item::Done(_) => None,
189
        }
190
    }
191

            
192
    pub fn into_done(self) -> Option<D> {
193
        match self {
194
            Item::Next(_) => None,
195
            Item::Done(d) => Some(d),
196
        }
197
    }
198
}
199

            
200
/// r[impl jetstream.subscription.surface]
201
/// The caller's end of a subscription, in the types the caller declared.
202
///
203
/// A `Stream` of `Item<T, D>`, so consuming one is consuming a stream —
204
/// and dropping one cancels it, because dropping the `RpcStream` inside
205
/// does. Nothing in the type says whether the subscription got a lane of
206
/// its own or a tag on a shared one, per
207
/// `r[jetstream.subscription.realisation.opaque]`.
208
pub struct Subscription<T, D> {
209
    source: Source<T, D>,
210
    /// Cancels the fallback token handed to a producer that was polled
211
    /// without a dispatcher, when this subscription is dropped.
212
    ///
213
    /// r[impl jetstream.subscription.surface.cancellation]
214
    /// Without it, a producer served in process — polled directly rather
215
    /// than through `serve` — held a token nothing would ever cancel, so
216
    /// dropping the subscription woke nothing. For `producing`, whose
217
    /// body runs in a spawned task, that task then outlived the receiver
218
    /// it was sending to: the exact "the work carries on with nowhere to
219
    /// deliver" that cancellation exists to prevent, in the one case
220
    /// where no dispatcher is around to notice.
221
    fallback: Option<tokio_util::sync::DropGuard>,
222
}
223

            
224
/// Where a subscription's items come from.
225
///
226
/// r[impl jetstream.subscription.surface.producer]
227
/// A subscription is one type on both sides of the call, because one
228
/// trait describes both — and the two sides need different things. A
229
/// caller needs a sequence. A producer needs cancellation, which the
230
/// trait's signature has nowhere to put: `fn events(&self, ctx, from)
231
/// -> Subscription<Event, Closed>` names no token, and adding one would
232
/// put a parameter in the caller's signature that means nothing to a
233
/// caller.
234
///
235
/// So a producer's subscription is a function *awaiting* its token, and
236
/// the dispatcher supplies it when it serves the call. Polled without
237
/// one — in a test, or in process — it gets a token nothing cancels,
238
/// which is the truth of that situation.
239
enum Source<T, D> {
240
    /// Opening: the request is not on the wire yet.
241
    ///
242
    /// r[impl jetstream.subscription.surface.rust]
243
    /// A subscription opens on first poll, which is what lets the
244
    /// method be the plain `fn` the surface calls for. It also means
245
    /// "subscribe, then act, then read" is a race — nothing reached the
246
    /// service. [`Subscription::establish`] is the way to say "now",
247
    /// and it exists because writing the usage kept tripping over its
248
    /// absence.
249
    Opening(
250
        std::pin::Pin<
251
            Box<dyn std::future::Future<Output = Opened<T, D>> + Send>,
252
        >,
253
    ),
254
    Open(ItemStream<T, D>),
255
    Awaiting(Box<dyn FnOnce(CancellationToken) -> ItemStream<T, D> + Send>),
256
    /// Momentarily empty while the one above is being run. A variant
257
    /// rather than an `Option` so replacing it needs no bound on `T`.
258
    Taken,
259
}
260

            
261
/// The boxed sequence a `Subscription` reads: items, then the end.
262
pub type ItemStream<T, D> = std::pin::Pin<
263
    Box<dyn futures::Stream<Item = jetstream_error::Result<Item<T, D>>> + Send>,
264
>;
265

            
266
/// Keep a cancellation guard alive for exactly as long as the stream it
267
/// belongs to.
268
///
269
/// r[impl jetstream.subscription.surface.cancellation]
270
/// A guard cancels when it drops, so where it lives decides when the
271
/// producer stops. Left on a `Subscription` that is being taken apart,
272
/// it fires while the stream it protects is still about to be read;
273
/// folded into that stream's own state, it lasts precisely as long as
274
/// something is reading.
275
fn carrying<T, D>(
276
    items: ItemStream<T, D>,
277
    guard: Option<tokio_util::sync::DropGuard>,
278
) -> ItemStream<T, D>
279
where
280
    T: Send + 'static,
281
    D: Send + 'static,
282
{
283
    let Some(guard) = guard else {
284
        return items;
285
    };
286
    Box::pin(futures::stream::unfold(
287
        (items, guard),
288
        |(mut items, guard)| async move {
289
            use futures::StreamExt as _;
290
            let item = items.next().await?;
291
            Some((item, (items, guard)))
292
        },
293
    ))
294
}
295

            
296
/// End a served sequence when the dispatcher cancels it.
297
///
298
/// r[impl jetstream.subscription.cancel]
299
/// The dispatcher's token is how a cancellation reaches the work, and a
300
/// sequence that never observes it is a subscription that cannot be
301
/// cancelled: the stream never ends, so `Out::Ended` never fires, so the
302
/// tag is never released and the cancellation is never acknowledged.
303
///
304
/// Ending the stream is the signal, not a shortcut. `server::run` treats
305
/// an end without a terminator as exactly this — a cancelled
306
/// subscription — and answers the caller with `cancelled_terminator`.
307
/// The truncation is what a cancelled subscription is supposed to look
308
/// like.
309
///
310
/// Stopping the *work* is the drop that follows: `Served::poll_next`
311
/// clears its inner stream the moment it ends, which drops whatever this
312
/// wraps — a nested `RpcStream`, or a guard from `carrying` — and that
313
/// drop is what cancels upstream. A sequence that has already finished
314
/// is unaffected, because it has already yielded its last item.
315
fn until_cancelled<T, D>(
316
    items: ItemStream<T, D>,
317
    cancel: CancellationToken,
318
) -> ItemStream<T, D>
319
where
320
    T: Send + 'static,
321
    D: Send + 'static,
322
{
323
    use futures::StreamExt as _;
324
    Box::pin(items.take_until(cancel.cancelled_owned()))
325
}
326

            
327
/// What opening a subscription yields: the sequence, and whatever has to
328
/// stay alive to cancel its producer.
329
///
330
/// r[impl jetstream.subscription.surface.cancellation]
331
/// The guard travels *out* of the opening future because it has to
332
/// outlive it. Opening runs inside a boxed future that cannot reach the
333
/// subscription the caller holds, so a token created in there had no
334
/// owner: dropping the subscription woke nothing, and a `producing`
335
/// task went on sending to a receiver that was gone. Handing the guard
336
/// back is what puts it where the drop can reach it.
337
type Opened<T, D> = (ItemStream<T, D>, Option<tokio_util::sync::DropGuard>);
338

            
339
impl<T, D> Subscription<T, D>
340
where
341
    T: Send + 'static,
342
    D: Send + 'static,
343
{
344
    /// Build one from the frames of a streaming call. `decode` is the
345
    /// generated protocol's: only it knows which response variant is an
346
    /// item and which is the terminator.
347
    /// `decode` returns `None` for a frame that ends the subscription
348
    /// **without** an item — the terminator of a subscription cut
349
    /// short, which frees the tag and carries no result, because a
350
    /// producer stopped by cancellation never produced one. Fabricating
351
    /// a default there would report a result that did not happen.
352
628
    pub fn from_frames<P, F>(stream: crate::RpcStream<P>, decode: F) -> Self
353
628
    where
354
628
        P: crate::Protocol + 'static,
355
628
        P::Response: 'static,
356
628
        F: FnMut(
357
628
                crate::Frame<P::Response>,
358
628
            ) -> jetstream_error::Result<Option<Item<T, D>>>
359
628
            + Send
360
628
            + 'static,
361
    {
362
        use futures::StreamExt;
363
        // r[impl jetstream.subscription.surface.termination]
364
        // An ending is the last thing the subscription says. Mapping
365
        // each frame and leaving the stream running let a failure be
366
        // followed by more items, or even by a normal terminator — so a
367
        // subscriber could be told its subscription had failed and then
368
        // go on hearing from it. Through `merge` that is starker still:
369
        // an input reported as failed keeps speaking under the same key.
370
        Subscription {
371
628
            fallback: None,
372
628
            source: Source::Open(Box::pin(futures::stream::unfold(
373
628
                (stream, decode, false),
374
624
                move |(mut stream, mut decode, finished)| async move {
375
624
                    if finished {
376
2
                        return None;
377
622
                    }
378
622
                    let decoded = match stream.next().await? {
379
449
                        Ok(frame) => decode(frame),
380
1
                        Err(e) => Err(e),
381
                    };
382
450
                    match decoded {
383
                        // The decoder says this frame ends the sequence
384
                        // without being an item of it.
385
                        Ok(None) => None,
386
                        Ok(Some(item)) => {
387
448
                            let finished = matches!(item, Item::Done(_));
388
448
                            Some((Ok(item), (stream, decode, finished)))
389
                        }
390
                        // And a failure is an ending too, which the
391
                        // plain `map` never made it.
392
2
                        Err(e) => Some((Err(e), (stream, decode, true))),
393
                    }
394
1076
                },
395
            ))),
396
        }
397
628
    }
398

            
399
    /// Build one that opens when it is first polled.
400
    ///
401
    /// r[impl jetstream.subscription.surface.rust]
402
    /// Opening a subscription needs a tag and a request on the wire,
403
    /// both of which are asynchronous — and the surface the
404
    /// specification shows is not: `fn events(&self, ..) ->
405
    /// Subscription<Event, Closed>`. Deferring the open to the first
406
    /// poll is what reconciles them, and it is what a stream does
407
    /// anyway: nothing happens until something reads.
408
814
    pub fn opening<F>(open: F) -> Self
409
814
    where
410
814
        F: std::future::Future<Output = Self> + Send + 'static,
411
    {
412
        Subscription {
413
814
            fallback: None,
414
814
            source: Source::Opening(Box::pin(async move {
415
629
                let mut opened = open.await;
416
                // Taken out rather than matched on, so `opened` stays
417
                // whole until its guard has been claimed below. Letting
418
                // it drop here would fire that guard and cancel the very
419
                // producer this is about to return.
420
                let source =
421
629
                    std::mem::replace(&mut opened.source, Source::Taken);
422
629
                match source {
423
628
                    Source::Open(items) => (items, opened.fallback.take()),
424
                    // r[impl jetstream.subscription.surface.cancellation]
425
                    // An opener that hands back a producer's
426
                    // subscription is the polled case one step removed:
427
                    // the producer needs a token, and something has to
428
                    // own the cancelling end of it. This used to make a
429
                    // token and drop the only handle to it, so a
430
                    // `producing` task spawned through `opening` could
431
                    // outlive its subscriber with nothing to stop it.
432
                    Source::Awaiting(produce) => {
433
1
                        let cancel = CancellationToken::new();
434
1
                        let guard = cancel.clone().drop_guard();
435
1
                        (produce(cancel), Some(guard))
436
                    }
437
                    // Nested: the inner future has already done this and
438
                    // carries its own guard out.
439
                    Source::Opening(inner) => inner.await,
440
                    Source::Taken => {
441
                        unreachable!("only set while being replaced")
442
                    }
443
                }
444
629
            })),
445
        }
446
814
    }
447

            
448
    /// Put the request on the wire now, rather than at the first read.
449
    ///
450
    /// r[impl jetstream.subscription.surface.rust]
451
    /// Opening lazily is what keeps the method signature a plain `fn`,
452
    /// and it makes "subscribe, then act, then read" a race: the act
453
    /// happens before the subscription exists. Awaiting this first
454
    /// removes that race **on one lane**, where
455
    /// `r[jetstream.lane.delivery-order]` then orders the request ahead
456
    /// of whatever follows it.
457
    ///
458
    /// It does **not** order a subscription against a call on a
459
    /// *different* lane — `r[jetstream.lane.no-cross-lane-order]` — and
460
    /// nothing can. A subscription that must not miss anything says
461
    /// where to start, and its producer replays from there; that is
462
    /// what the cursor in `r[jetstream.subscription.resume]` is for.
463
    /// Cancel-safe: the opening future stays *in* the subscription while
464
    /// it is awaited.
465
    ///
466
    /// It used to be moved out and `Source::Taken` left in its place, so
467
    /// dropping this future — a timeout, a losing `select!` branch —
468
    /// dropped the only opening future with it and left the subscription
469
    /// permanently `Taken`: a second `establish()` did nothing at all,
470
    /// and the next poll hit an `unreachable!`. Awaiting in place means
471
    /// an abandoned establishment leaves the subscription exactly as it
472
    /// was, ready to be established or polled again.
473
544
    pub async fn establish(&mut self) {
474
544
        if let Source::Opening(open) = &mut self.source {
475
544
            let (items, guard) = open.as_mut().await;
476
544
            self.source = Source::Open(items);
477
            // Only when opening produced one: a subscription that opened
478
            // onto a dispatcher-served stream has nothing to cancel here,
479
            // and must not lose a guard it already held.
480
544
            if guard.is_some() {
481
1
                self.fallback = guard;
482
543
            }
483
        }
484
544
    }
485

            
486
    /// r[impl jetstream.subscription.surface.producer]
487
    /// Build the producer's side: a subscription that is handed its
488
    /// cancellation when the dispatcher serves it.
489
350
    pub fn served<F, S>(produce: F) -> Self
490
350
    where
491
350
        F: FnOnce(CancellationToken) -> S + Send + 'static,
492
350
        S: futures::Stream<Item = jetstream_error::Result<Item<T, D>>>
493
350
            + Send
494
350
            + 'static,
495
    {
496
        Subscription {
497
350
            fallback: None,
498
350
            source: Source::Awaiting(Box::new(move |cancel| {
499
350
                Box::pin(produce(cancel))
500
350
            })),
501
        }
502
350
    }
503

            
504
    /// r[impl jetstream.subscription.surface.producer]
505
    /// The ergonomic producer: a task holding a [`Producer`], which can
506
    /// send *and* learn that its subscriber has gone.
507
    ///
508
    /// `r[jetstream.subscription.detached.state]` is the reason this
509
    /// takes a closure rather than a sender: what the closure captures
510
    /// is the producer's whole state, and a handler that can only be
511
    /// written as "hold this sender" cannot be evicted and resumed.
512
349
    pub fn producing<F, Fut>(capacity: usize, produce: F) -> Self
513
349
    where
514
349
        F: FnOnce(Producer<T, D>) -> Fut + Send + 'static,
515
349
        Fut: std::future::Future<Output = ()> + Send + 'static,
516
    {
517
349
        Subscription::served(move |cancel| {
518
349
            let (producer, items) = channel::<T, D>(capacity, cancel);
519
349
            tokio::spawn(produce(producer));
520
            // Already `Result`: the channel carries the producer's
521
            // failures, so wrapping every item in `Ok` here would be
522
            // asserting the one thing it cannot know.
523
349
            items
524
349
        })
525
349
    }
526

            
527
    /// Take the item sequence, giving the producer its cancellation.
528
    ///
529
    /// r[impl jetstream.subscription.cancel]
530
    /// This is the dispatcher's call, and it is where cancellation
531
    /// reaches the work. A subscription that is already a sequence — a
532
    /// caller's — ignores the token, which is right: nothing on that
533
    /// side produces.
534
348
    pub fn serve(self, cancel: CancellationToken) -> ItemStream<T, D> {
535
        // Taken apart rather than matched through, because the guard is
536
        // as much a part of this subscription as its source. Matching on
537
        // `self.source` alone leaves the rest of `self` to be dropped
538
        // when `serve` returns — and if it holds a guard, that cancels
539
        // the producer whose stream is being handed back.
540
348
        let Subscription { source, fallback } = self;
541
348
        match source {
542
            // r[impl jetstream.subscription.surface.cancellation]
543
            // Already a sequence, but not necessarily someone else's: a
544
            // subscription that opened onto its own producer — through
545
            // `establish` or a poll — carries the guard for it, and that
546
            // guard has to reach the returned stream.
547
            //
548
            // The token reaches it too. This arm used to ignore it, on
549
            // the reasoning that a caller's stream has nothing to cancel
550
            // — true only while the sequence is someone else's. A
551
            // service that proxies or delegates a subscription serves
552
            // one backed by real work, and there the token is the only
553
            // thing that can stop it.
554
            Source::Open(items) => {
555
                until_cancelled(carrying(items, fallback), cancel)
556
            }
557
348
            Source::Awaiting(produce) => produce(cancel),
558
            // A caller's subscription served as a producer's: it opens
559
            // itself, and may hand back a guard of its own for a
560
            // producer nested inside it.
561
            //
562
            // Cancellable for the same reason, and from the same point:
563
            // the token ends the flattened sequence, whether the
564
            // cancellation arrives while it is still opening or once it
565
            // is running.
566
            Source::Opening(open) => {
567
                use futures::StreamExt as _;
568
                until_cancelled(
569
                    Box::pin(
570
                        futures::stream::once(open)
571
                            .flat_map(|(items, guard)| carrying(items, guard)),
572
                    ),
573
                    cancel,
574
                )
575
            }
576
            Source::Taken => unreachable!("only set while being replaced"),
577
        }
578
348
    }
579

            
580
    /// Build one from any stream of already-decoded items — the shape a
581
    /// test, an in-process implementation, or a replay uses.
582
    pub fn from_items<S>(items: S) -> Self
583
    where
584
        S: futures::Stream<Item = jetstream_error::Result<Item<T, D>>>
585
            + Send
586
            + 'static,
587
    {
588
        Subscription {
589
            fallback: None,
590
            source: Source::Open(Box::pin(items)),
591
        }
592
    }
593

            
594
    /// r[impl jetstream.subscription.surface.composition]
595
    /// Tag this subscription so a merge can say which one spoke. The
596
    /// terminator survives the merge on its own — it is an `Item` — but
597
    /// *which* subscription ended does not, and that is the other half
598
    /// of what the rule requires.
599
2
    pub fn labelled<K>(self, key: K) -> Labelled<K, T, D>
600
2
    where
601
2
        K: Clone,
602
    {
603
2
        Labelled { key, inner: self }
604
2
    }
605
}
606

            
607
impl<T, D> futures::Stream for Subscription<T, D> {
608
    type Item = jetstream_error::Result<Item<T, D>>;
609

            
610
1553
    fn poll_next(
611
1553
        mut self: std::pin::Pin<&mut Self>,
612
1553
        cx: &mut std::task::Context<'_>,
613
1553
    ) -> std::task::Poll<Option<Self::Item>> {
614
        // r[impl jetstream.subscription.surface.cancellation]
615
        // A producer polled without a dispatcher still gets a token that
616
        // something owns — the guard below, or the one opening hands
617
        // back here. Both paths reach a producer, so both have to.
618
1553
        if let Source::Opening(open) = &mut self.source {
619
85
            match open.as_mut().poll(cx) {
620
                std::task::Poll::Ready((items, guard)) => {
621
85
                    self.source = Source::Open(items);
622
85
                    if guard.is_some() {
623
                        self.fallback = guard;
624
85
                    }
625
                }
626
                std::task::Poll::Pending => return std::task::Poll::Pending,
627
            }
628
1468
        }
629
1553
        if let Source::Awaiting(_) = self.source {
630
            let Source::Awaiting(produce) =
631
1
                std::mem::replace(&mut self.source, Source::Taken)
632
            else {
633
                unreachable!("checked immediately above")
634
            };
635
            // No dispatcher, so nothing else owns a token — but the
636
            // producer still has to learn when this subscription goes,
637
            // or a `producing` task outlives the receiver it is sending
638
            // to. The guard cancels it on drop.
639
1
            let cancel = CancellationToken::new();
640
1
            self.fallback = Some(cancel.clone().drop_guard());
641
1
            self.source = Source::Open(produce(cancel));
642
1552
        }
643
1553
        match &mut self.source {
644
1553
            Source::Open(items) => items.as_mut().poll_next(cx),
645
            _ => unreachable!("replaced above"),
646
        }
647
1553
    }
648
}
649

            
650
/// A subscription that says which one it is. `Unpin`, so it goes
651
/// straight into `select_all`.
652
pub struct Labelled<K, T, D> {
653
    key: K,
654
    inner: Subscription<T, D>,
655
}
656

            
657
impl<K: Clone + Unpin, T, D> futures::Stream for Labelled<K, T, D> {
658
    /// The key accompanies the failure as well as the item.
659
    ///
660
    /// r[impl jetstream.subscription.surface.composition]
661
    /// This used to yield a bare `Err`, which throws away the one thing
662
    /// `Labelled` exists to keep. In a fan-in over several rooms, a
663
    /// transport failure, a decode failure or a producer failure ends
664
    /// one input and the caller could not tell which — so it could
665
    /// neither retry that room nor report it, which is the same loss the
666
    /// rule forbids for the *successful* end.
667
    type Item = (K, jetstream_error::Result<Item<T, D>>);
668

            
669
10
    fn poll_next(
670
10
        self: std::pin::Pin<&mut Self>,
671
10
        cx: &mut std::task::Context<'_>,
672
10
    ) -> std::task::Poll<Option<Self::Item>> {
673
        use std::task::Poll;
674
10
        let this = self.get_mut();
675
10
        let key = this.key.clone();
676
10
        match std::pin::Pin::new(&mut this.inner).poll_next(cx) {
677
6
            Poll::Ready(Some(result)) => Poll::Ready(Some((key, result))),
678
2
            Poll::Ready(None) => Poll::Ready(None),
679
2
            Poll::Pending => Poll::Pending,
680
        }
681
10
    }
682
}
683

            
684
/// r[impl jetstream.subscription.surface.composition]
685
/// Merge many subscriptions without losing which one ended, or with
686
/// what. Fan-in — use case 2 — and a terminal value — use case 4 — are
687
/// each easy alone; this is the combination the document listed
688
/// separately and never checked.
689
1
pub fn merge<K, T, D, I>(
690
1
    subscriptions: I,
691
1
) -> futures::stream::SelectAll<Labelled<K, T, D>>
692
1
where
693
1
    K: Clone + Unpin,
694
1
    T: Send + 'static,
695
1
    D: Send + 'static,
696
1
    I: IntoIterator<Item = (K, Subscription<T, D>)>,
697
{
698
1
    futures::stream::select_all(
699
2
        subscriptions.into_iter().map(|(k, s)| s.labelled(k)),
700
    )
701
1
}
702

            
703
/// The producer stopped because its subscriber did.
704
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
705
pub struct Cancelled;
706

            
707
impl std::fmt::Display for Cancelled {
708
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
709
        f.write_str("the subscription was cancelled")
710
    }
711
}
712

            
713
impl std::error::Error for Cancelled {}
714

            
715
/// The signal a producer watches. Re-exported so a producer need not
716
/// depend on `tokio-util` to write against this surface.
717
pub use tokio_util::sync::CancellationToken;
718

            
719
/// r[impl jetstream.subscription.surface.producer]
720
/// The producer's end. It can send, and it can **learn** — which is the
721
/// half a bare `Sender` cannot do, and the reason a producer loop written
722
/// against one compiles, runs, and keeps inferring long after the
723
/// subscriber has gone.
724
///
725
/// Cancellation is offered all three ways the rule allows: a signal to
726
/// await, a flag to test, and a send that fails once cancelled. A loop
727
/// that checks none of them still stops at its next `send`.
728
pub struct Producer<T, D> {
729
    tx: tokio::sync::mpsc::Sender<jetstream_error::Result<Item<T, D>>>,
730
    cancel: tokio_util::sync::CancellationToken,
731
}
732

            
733
impl<T, D> Producer<T, D> {
734
    /// Emit one item. Fails once the subscriber has gone, so a loop that
735
    /// watches nothing else still terminates.
736
5988
    pub async fn send(&self, item: T) -> Result<(), Cancelled> {
737
5988
        tokio::select! {
738
            biased;
739
5988
            _ = self.cancel.cancelled() => Err(Cancelled),
740
5988
            sent = self.tx.send(Ok(Item::Next(item))) => {
741
5752
                sent.map_err(|_| Cancelled)
742
            }
743
        }
744
5931
    }
745

            
746
    /// r[impl jetstream.subscription.termination]
747
    /// End the subscription, carrying the result. Consuming `self` is
748
    /// the point: a producer that has finished cannot emit again.
749
2
    pub async fn finish(self, done: D) {
750
2
        let _ = self.tx.send(Ok(Item::Done(done))).await;
751
2
    }
752

            
753
    /// r[impl jetstream.subscription.surface.termination]
754
    /// End the subscription because the work failed.
755
    ///
756
    /// Without this a producer had no way to say so. Returning early —
757
    /// the `?` in any ordinary producer loop — drops the `Producer`,
758
    /// which closes the channel, which the dispatcher reads as a
759
    /// subscription that simply stopped: it then supplies the terminator
760
    /// the caller is owed, and the subscriber receives a normal typed
761
    /// ending carrying a *fabricated* result. A failure reported as
762
    /// success is the one outcome the surface must never produce, so the
763
    /// channel carries failures and this is how one is sent.
764
    ///
765
    /// Dropping without calling either this or `finish` remains the
766
    /// cancelled case, which is what the dispatcher's synthetic
767
    /// terminator is for.
768
    pub async fn fail(self, error: jetstream_error::Error) {
769
        let _ = self.tx.send(Err(error)).await;
770
    }
771

            
772
    pub fn is_cancelled(&self) -> bool {
773
        self.cancel.is_cancelled()
774
    }
775

            
776
    /// Resolves when the subscriber goes away — the shape a producer
777
    /// that is waiting on something else selects over.
778
23
    pub async fn cancelled(&self) {
779
23
        self.cancel.cancelled().await
780
6
    }
781

            
782
    /// The token itself, for a producer that hands cancellation onward
783
    /// to the work rather than watching it here.
784
    pub fn cancellation(&self) -> tokio_util::sync::CancellationToken {
785
        self.cancel.clone()
786
    }
787
}
788

            
789
/// The served side of a subscription: what the producer writes into.
790
pub struct Items<T, D> {
791
    rx: tokio::sync::mpsc::Receiver<jetstream_error::Result<Item<T, D>>>,
792
}
793

            
794
impl<T, D> futures::Stream for Items<T, D> {
795
    type Item = jetstream_error::Result<Item<T, D>>;
796

            
797
11528
    fn poll_next(
798
11528
        mut self: std::pin::Pin<&mut Self>,
799
11528
        cx: &mut std::task::Context<'_>,
800
11528
    ) -> std::task::Poll<Option<Self::Item>> {
801
11528
        self.rx.poll_recv(cx)
802
11528
    }
803
}
804

            
805
impl<T, D> Items<T, D>
806
where
807
    T: Send + 'static,
808
    D: Send + 'static,
809
{
810
    /// Turn decoded items into the frames a dispatcher serves. `encode`
811
    /// is the generated protocol's, for the same reason `decode` is.
812
    pub fn into_frames<P, F>(
813
        self,
814
        tag: u16,
815
        mut encode: F,
816
    ) -> crate::server::ResponseStream<P>
817
    where
818
        P: crate::Protocol + 'static,
819
        P::Response: 'static,
820
        P::Error: 'static,
821
        F: FnMut(jetstream_error::Result<Item<T, D>>) -> P::Response
822
            + Send
823
            + 'static,
824
    {
825
        use futures::StreamExt;
826
        // `encode` sees the failure too, because only the protocol knows
827
        // how to say "this subscription failed" in its own response
828
        // type. Yielding `Err` here instead would make it a *transport*
829
        // error, which tears down the lane and every other call on it.
830
        Box::pin(self.map(move |item| {
831
            Ok(crate::Frame {
832
                tag,
833
                msg: encode(item),
834
            })
835
        }))
836
    }
837
}
838

            
839
/// r[impl jetstream.subscription.surface.producer]
840
/// The producer/consumer pair for one subscription. `cancel` is the
841
/// dispatcher's token, so cancelling the subscription cancels the work.
842
349
pub fn channel<T, D>(
843
349
    capacity: usize,
844
349
    cancel: tokio_util::sync::CancellationToken,
845
349
) -> (Producer<T, D>, Items<T, D>) {
846
349
    let (tx, rx) = tokio::sync::mpsc::channel(capacity);
847
349
    (Producer { tx, cancel }, Items { rx })
848
349
}
849

            
850
#[cfg(test)]
851
mod tests;