1
use std::{pin::pin, str::FromStr};
2

            
3
use futures::{Sink, Stream};
4
use jetstream_wireformat::WireFormat;
5
use tokio_util::{
6
    bytes::{self, Buf, BufMut},
7
    codec::{Decoder, Encoder},
8
};
9

            
10
use crate::{
11
    context::{Context, Contextual},
12
    Error, Frame, Framer, Protocol, Version,
13
};
14

            
15
pub struct ServerCodec<P: Protocol> {
16
    _phantom: std::marker::PhantomData<P>,
17
}
18

            
19
impl<P: Protocol> ServerCodec<P> {
20
349
    pub fn new() -> Self {
21
349
        Self {
22
349
            _phantom: std::marker::PhantomData,
23
349
        }
24
349
    }
25
}
26

            
27
impl<P: Protocol> Default for ServerCodec<P> {
28
2
    fn default() -> Self {
29
2
        Self::new()
30
2
    }
31
}
32

            
33
pub trait ServiceTransport<P: Protocol>:
34
    Sink<Frame<P::Response>, Error = P::Error>
35
    + Stream<Item = Result<Frame<P::Request>, P::Error>>
36
    + Send
37
    + Sync
38
    + Unpin
39
{
40
    fn context(&self) -> Context;
41
}
42

            
43
impl<P: Protocol, T> ServiceTransport<P> for T
44
where
45
    T: Sink<Frame<P::Response>, Error = P::Error>
46
        + Stream<Item = Result<Frame<P::Request>, P::Error>>
47
        + Send
48
        + Sync
49
        + Unpin,
50
    T: Contextual,
51
{
52
283
    fn context(&self) -> Context {
53
283
        <Self as Contextual>::context(self)
54
283
    }
55
}
56

            
57
impl<P> Decoder for ServerCodec<P>
58
where
59
    P: Protocol,
60
{
61
    type Error = Error;
62
    type Item = Frame<P::Request>;
63

            
64
1738
    fn decode(
65
1738
        &mut self,
66
1738
        src: &mut bytes::BytesMut,
67
1738
    ) -> Result<Option<Self::Item>, Self::Error> {
68
        // check to see if you have at least 4 bytes to figure out the size
69
1738
        if src.len() < 4 {
70
848
            src.reserve(4);
71
848
            return Ok(None);
72
890
        }
73
890
        let Some(mut bytz) = src.get(..4) else {
74
            return Ok(None);
75
        };
76

            
77
890
        let byte_size: u32 = WireFormat::decode(&mut bytz)?;
78
890
        if src.len() < byte_size as usize {
79
            src.reserve(byte_size as usize);
80
            return Ok(None);
81
890
        }
82

            
83
890
        let frame = Frame::<P::Request>::decode(&mut src.reader())?;
84
890
        Ok(Some(frame))
85
1738
    }
86
}
87

            
88
impl<P> Encoder<Frame<P::Response>> for ServerCodec<P>
89
where
90
    P: Protocol,
91
{
92
    type Error = Error;
93

            
94
6229
    fn encode(
95
6229
        &mut self,
96
6229
        item: Frame<P::Response>,
97
6229
        dst: &mut bytes::BytesMut,
98
6229
    ) -> Result<(), Self::Error> {
99
6229
        item.encode(&mut dst.writer())?;
100
6229
        Ok(())
101
6229
    }
102
}
103

            
104
#[trait_variant::make(Send + Sync + Sized)]
105
pub trait Server: Protocol + Send + Sync {
106
    /// Negotiate the protocol version to use.
107
    fn version(client_version: Version) -> jetstream_error::Result<Version> {
108
        // By default, accept any version that matches the major version of the server's protocol version.
109
        let server_version =
110
            Version::from_str(Self::VERSION).unwrap_or_else(|_| {
111
                panic!(
112
                    "Invalid version format for JetStream protocol: {}",
113
                    Self::VERSION
114
                )
115
            });
116
        match (client_version, server_version) {
117
            (Version::V9P2000L, Version::V9P2000L) => Ok(Version::V9P2000L),
118
            (Version::V9P2000, Version::V9P2000) => Ok(Version::V9P2000),
119
            (
120
                Version::JetStream {
121
                    name: client_name,
122
                    version: client_version,
123
                },
124
                Version::JetStream {
125
                    name: server_name,
126
                    version: server_version,
127
                },
128
            ) => {
129
                // compare versions of client and server and send the lowest version
130
                if client_name != server_name {
131
                    return Err(Error::new(format!(
132
                        "Incompatible protocol names: client={}, server={}",
133
                        client_name, server_name
134
                    )));
135
                }
136
                Ok(Version::JetStream {
137
                    name: server_name,
138
                    version: client_version.min(server_version),
139
                })
140
            }
141
            _ => Err(Error::new("Incompatible protocols".to_string())),
142
        }
143
    }
144
    /// The main RPC method that handles incoming requests and produces responses.
145
    async fn rpc(
146
        &mut self,
147
        context: Context,
148
        frame: Frame<Self::Request>,
149
    ) -> Result<Frame<Self::Response>, Self::Error>;
150

            
151
    /// r[impl jetstream.subscription.surface.declared]
152
    /// Whether a request of this message type opens a subscription. The
153
    /// declaration is the protocol's, not the call site's, so the
154
    /// dispatcher can route before it moves the frame.
155
    ///
156
    /// Defaults to "no streaming methods", which is every protocol
157
    /// written before this existed.
158
2
    fn is_streaming(_message_type: u8) -> bool {
159
2
        false
160
2
    }
161

            
162
    /// r[impl jetstream.subscription.dispatch.declared]
163
    /// r[impl jetstream.subscription.cancel]
164
    /// Whether this request is a cancellation, and which subscription it
165
    /// names. Cancellation travels as an ordinary request under a fresh
166
    /// tag, so the dispatcher has to be told how to recognise one — the
167
    /// message id is global, but decoding the payload is the protocol's.
168
    ///
169
    /// Defaulted to "this protocol has no cancellation", which is
170
    /// correct for every protocol without subscriptions.
171
2
    fn cancel_target(_frame: &Frame<Self::Request>) -> Option<u16> {
172
2
        None
173
2
    }
174

            
175
    /// r[impl jetstream.subscription.dispatch.declared]
176
    /// r[impl jetstream.subscription.cancel]
177
    /// The acknowledgement for a cancelled subscription, sent under the
178
    /// *cancellation's* tag once the subscription has stopped emitting.
179
    fn cancel_ack(_oldtag: u16) -> Option<Self::Response> {
180
        None
181
    }
182

            
183
    /// r[impl jetstream.subscription.dispatch.terminator]
184
    /// r[impl jetstream.subscription.termination]
185
    /// The terminator for a subscription that was cut short. A producer
186
    /// stopped by cancellation returns from its stream without saying
187
    /// anything, and a subscription that ends with no terminator leaves
188
    /// the caller's tag in flight for the life of the lane — see
189
    /// `r[jetstream.subscription.identity]` for why it cannot simply be
190
    /// released. The dispatcher supplies one, and the protocol says what
191
    /// value it has.
192
    ///
193
    /// r[impl jetstream.subscription.termination.discriminant]
194
    /// `method` is the message type of the request that opened the
195
    /// subscription. A protocol with one streaming method can ignore it;
196
    /// one with two cannot, because the terminator's payload names its
197
    /// method and only the request says which method this was.
198
    fn cancelled_terminator(_method: u8) -> Option<Self::Response> {
199
        None
200
    }
201

            
202
    /// r[impl jetstream.subscription.overview]
203
    /// Serve a subscription: one request, many responses.
204
    ///
205
    /// r[impl jetstream.subscription.cancel]
206
    /// `cancel` is how the producer learns the subscriber has gone.
207
    /// Releasing only the delivery obligation is not enough — an
208
    /// inference or a build must be able to stop, not merely stop being
209
    /// listened to — so this is a parameter rather than something the
210
    /// dispatcher keeps to itself.
211
    ///
212
    /// Failures travel as items, per `r[jetstream.subscription.termination]`,
213
    /// which is also why the end can carry a value.
214
    ///
215
    /// r[impl jetstream.subscription.compat.rpc-layer]
216
    /// Defaulted, so every existing `Server` implementation compiles
217
    /// untouched: the breakage this change carries is on the client,
218
    /// where `RpcCall` resolves to one frame.
219
    async fn rpc_stream(
220
        &mut self,
221
        context: Context,
222
        frame: Frame<Self::Request>,
223
        cancel: tokio_util::sync::CancellationToken,
224
    ) -> ResponseStream<Self>
225
    where
226
        // The served stream is boxed and owned, so what it carries must
227
        // outlive the call that made it. Every real protocol's messages
228
        // are owned values, so this costs nothing but has to be said —
229
        // the same bound `Datagrams` needs, for the same reason.
230
        Self::Response: 'static,
231
        Self::Error: 'static,
232
    {
233
        let _ = (context, frame, cancel);
234
        // A bare async block, not a normal body: `#[trait_variant::make]`
235
        // rewrites `async fn` into `fn -> impl Future`, so the body must
236
        // *be* the future. The two natural spellings fail with errors
237
        // that point elsewhere entirely. An *implementation* of this
238
        // method writes an ordinary body, since the macro rewrites the
239
        // trait and not its impls.
240
        async move { Box::pin(futures::stream::empty()) as ResponseStream<Self> }
241
    }
242
}
243

            
244
/// The items a served subscription yields.
245
pub type ResponseStream<P> = std::pin::Pin<
246
    Box<
247
        dyn futures::Stream<
248
                Item = Result<
249
                    Frame<<P as Protocol>::Response>,
250
                    <P as Protocol>::Error,
251
                >,
252
            > + Send,
253
    >,
254
>;
255

            
256
/// One served subscription, tagged, and — unlike the stream it wraps —
257
/// able to say that it *ended*.
258
///
259
/// r[impl jetstream.subscription.surface.composition]
260
/// The same erasure the surface rule is about bites the dispatcher:
261
/// `SelectAll` drops a finished stream silently, so a subscription that
262
/// stopped would leave its tag open and its cancellation unacknowledged.
263
/// The end is a value here for exactly the reason it is one for callers.
264
struct Served<P: Protocol> {
265
    tag: u16,
266
    inner: Option<ResponseStream<P>>,
267
}
268

            
269
enum Out<P: Protocol> {
270
    Item(u16, Result<Frame<P::Response>, P::Error>),
271
    Ended(u16),
272
}
273

            
274
impl<P: Protocol> Stream for Served<P> {
275
    type Item = Out<P>;
276

            
277
11718
    fn poll_next(
278
11718
        self: std::pin::Pin<&mut Self>,
279
11718
        cx: &mut std::task::Context<'_>,
280
11718
    ) -> std::task::Poll<Option<Self::Item>> {
281
        use std::task::Poll;
282
11718
        let this = self.get_mut();
283
11718
        let tag = this.tag;
284
11718
        let Some(inner) = this.inner.as_mut() else {
285
186
            return Poll::Ready(None);
286
        };
287
11532
        match inner.as_mut().poll_next(cx) {
288
5522
            Poll::Ready(Some(item)) => Poll::Ready(Some(Out::Item(tag, item))),
289
            Poll::Ready(None) => {
290
186
                this.inner = None;
291
186
                Poll::Ready(Some(Out::Ended(tag)))
292
            }
293
5824
            Poll::Pending => Poll::Pending,
294
        }
295
11718
    }
296
}
297

            
298
/// What the dispatcher remembers about a subscription it is serving.
299
struct Open {
300
    cancel: tokio_util::sync::CancellationToken,
301
    /// The message type of the request that opened it. The terminator
302
    /// the dispatcher may have to supply names its method, and only the
303
    /// request knows which method that was.
304
    method: u8,
305
    /// Set when the producer emitted a terminator of its own, so the
306
    /// dispatcher does not send a second one.
307
    terminated: bool,
308
    /// The tags of the cancellations waiting to be acknowledged. The
309
    /// acknowledgement is owed *after* the last item.
310
    ///
311
    /// r[impl jetstream.subscription.cancel]
312
    /// A list rather than one tag: nothing stops a caller — or the
313
    /// client's own drop path, which queues a cancellation of its own —
314
    /// from sending two before the producer notices the first. Keeping
315
    /// only the latest silently drops the earlier one, and every
316
    /// cancellation is owed an answer; the tag it was sent under stays
317
    /// in flight until it gets one, so the ones forgotten here are
318
    /// control tags leaked for the life of the lane.
319
    ack_to: Vec<u16>,
320
}
321

            
322
283
pub async fn run<T, P>(p: &mut P, transport: T) -> Result<(), P::Error>
323
283
where
324
283
    T: ServiceTransport<P>,
325
283
    P: Server,
326
283
    P::Response: 'static,
327
283
    P::Error: 'static,
328
283
{
329
    use futures::{SinkExt, StreamExt};
330

            
331
    // The context is the transport's, not the frame's: it describes the
332
    // peer at the other end of this lane, which does not change between
333
    // requests. Reading it once is what lets the transport be split.
334
283
    let context = transport.context();
335

            
336
    // r[impl jetstream.subscription.dispatch.concurrent]
337
    // r[impl jetstream.subscription.definition]
338
    // Split, because a subscription is one call among the lane's others.
339
    // Serving one by looping on its items never polls the transport
340
    // again, so an open subscription — the normal case, a room that
341
    // stays open — took the lane with it: no second request served, and
342
    // no cancellation could arrive, which made the cancellation rule
343
    // unimplementable rather than merely unimplemented.
344
283
    let (mut sink, mut source) = transport.split();
345
    let mut active: futures::stream::SelectAll<Served<P>> =
346
283
        futures::stream::SelectAll::new();
347
    let mut open: std::collections::BTreeMap<u16, Open> =
348
283
        std::collections::BTreeMap::new();
349
283
    let mut a = pin!(p);
350

            
351
    // The reason the loop stopped, so the cleanup below runs on every
352
    // exit rather than only the tidy one.
353
    let outcome: Result<(), P::Error> = 'dispatch: loop {
354
        // r[impl jetstream.subscription.dispatch.concurrent]
355
        // Fair selection, deliberately. This was `biased` with items
356
        // first, on the reasoning that a ready producer should not wait
357
        // behind an inbound request — which is exactly backwards. An
358
        // always-ready producer, and `repeat` is enough, makes the item
359
        // branch ready on every iteration, so the inbound branch is never
360
        // selected and the chatty subscription prevents *its own*
361
        // cancellation from ever being read. That is the failure this
362
        // whole dispatcher exists to remove, reintroduced by an
363
        // optimisation.
364
6722
        tokio::select! {
365
6722
            Some(out) = active.next(), if !active.is_empty() => match out {
366
                Out::Item(tag, item) => {
367
5522
                    let frame = match item {
368
5522
                        Ok(frame) => frame,
369
                        Err(e) => break Err(e),
370
                    };
371
5522
                    if frame.msg.message_type() == crate::subscription::RDONE {
372
2
                        if let Some(o) = open.get_mut(&tag) {
373
2
                            o.terminated = true;
374
                        }
375
5520
                    }
376
5522
                    if let Err(e) = sink.send(frame).await {
377
                        break Err(e);
378
5483
                    }
379
                }
380
                Out::Ended(tag) => {
381
186
                    if let Some(o) = open.remove(&tag) {
382
                        // r[impl jetstream.subscription.dispatch.terminator]
383
186
                        if !o.terminated {
384
184
                            if let Some(msg) = P::cancelled_terminator(o.method) {
385
                                if let Err(e) =
386
184
                                    sink.send(Frame { tag, msg }).await
387
                                {
388
                                    break Err(e);
389
184
                                }
390
                            }
391
2
                        }
392
                        // r[impl jetstream.subscription.cancel]
393
                        // After every item already emitted, which is what
394
                        // makes the tag safe to reuse.
395
186
                        for ack_tag in &o.ack_to {
396
183
                            if let Some(msg) = P::cancel_ack(tag) {
397
183
                                if let Err(e) = sink
398
183
                                    .send(Frame {
399
183
                                        tag: *ack_tag,
400
183
                                        msg,
401
183
                                    })
402
183
                                    .await
403
                                {
404
                                    break 'dispatch Err(e);
405
183
                                }
406
                            }
407
                        }
408
                    }
409
                }
410
            },
411

            
412
6722
            inbound = source.next() => {
413
770
                let Some(Ok(frame)) = inbound else { break Ok(()) };
414

            
415
                // r[impl jetstream.subscription.cancel]
416
770
                if let Some(oldtag) = P::cancel_target(&frame) {
417
184
                    match open.get_mut(&oldtag) {
418
                        Some(o) => {
419
184
                            o.ack_to.push(frame.tag);
420
184
                            o.cancel.cancel();
421
                        }
422
                        // Nothing by that tag: already finished, or never
423
                        // existed. Acknowledge anyway — a cancellation
424
                        // racing a terminator is normal, and the caller
425
                        // is owed an answer either way.
426
                        None => {
427
                            if let Some(msg) = P::cancel_ack(oldtag) {
428
                                if let Err(e) = sink
429
                                    .send(Frame { tag: frame.tag, msg })
430
                                    .await
431
                                {
432
                                    break Err(e);
433
                                }
434
                            }
435
                        }
436
                    }
437
184
                    continue;
438
586
                }
439

            
440
                // r[impl jetstream.subscription.surface.declared]
441
                // Routed on the declared message type, before the frame
442
                // moves.
443
586
                if P::is_streaming(frame.msg.message_type()) {
444
348
                    let tag = frame.tag;
445
348
                    let method = frame.msg.message_type();
446
                    // r[impl jetstream.subscription.cancel]
447
                    // The token the producer watches.
448
348
                    let cancel = tokio_util::sync::CancellationToken::new();
449
                    let inner =
450
348
                        a.rpc_stream(context.clone(), frame, cancel.clone())
451
348
                            .await;
452
348
                    open.insert(
453
348
                        tag,
454
348
                        Open {
455
348
                            cancel,
456
348
                            method,
457
348
                            terminated: false,
458
348
                            ack_to: Vec::new(),
459
348
                        },
460
348
                    );
461
348
                    active.push(Served { tag, inner: Some(inner) });
462
                } else {
463
238
                    let response = match a.rpc(context.clone(), frame).await {
464
238
                        Ok(response) => response,
465
                        Err(e) => break Err(e),
466
                    };
467
238
                    if let Err(e) = sink.send(response).await {
468
                        break Err(e);
469
238
                    }
470
                }
471
            }
472
        }
473
    };
474

            
475
    // r[impl jetstream.subscription.cancel]
476
    // The lane is gone, so every producer on it has lost its subscriber.
477
    // Leaving the tokens uncancelled would leave the work running with
478
    // nowhere to deliver — the very thing cancellation exists to stop.
479
    //
480
    // This runs on *every* exit. It used to sit after a body full of
481
    // `?`, so any stream or sink error returned straight past it: the
482
    // tokens were merely dropped, and a producer holding a clone — a
483
    // detached task, which is the shape `producing` creates — never
484
    // learned its lane had gone.
485
    for (_, o) in open {
486
        o.cancel.cancel();
487
    }
488
    outcome
489
}