1
#![doc(
2
    html_logo_url = "https://raw.githubusercontent.com/sevki/jetstream/main/logo/JetStream.png"
3
)]
4
#![doc(
5
    html_favicon_url = "https://raw.githubusercontent.com/sevki/jetstream/main/logo/JetStream.png"
6
)]
7
//! # JetStream Rpc
8
//! Defines Rpc primitives for JetStream.
9
//! Of note is the `Protocol` trait which is meant to be used with the `service` attribute macro.
10
//!
11
//! [`client::ClientTransport`] and [`server::ServiceTransport`] describe
12
//! one ordered frame sequence. [`session`] describes the thing that can
13
//! open another one: a [`session::Session`] is the association with a
14
//! peer, and a *lane* is one sequence obtained from it — which is what
15
//! those two traits already are. See the guide at
16
//! <https://sevki.github.io/jetstream/sessions.html>.
17
#![cfg_attr(docsrs, feature(doc_cfg))]
18

            
19
extern crate tokio_util;
20
mod any_server;
21
mod call;
22
pub mod client;
23
mod constants;
24
pub mod context;
25
mod error;
26
pub mod framer;
27
mod mux;
28
mod router;
29
pub mod server;
30
pub mod session;
31
pub mod subscription;
32
mod tag;
33
mod version;
34
use std::str::FromStr;
35

            
36
pub use any_server::AnyServer;
37
pub use call::*;
38
pub use constants::*;
39
pub use error::*;
40
pub use jetstream_error::IntoError;
41
use jetstream_wireformat::WireFormat;
42
pub use mux::*;
43
pub use router::*;
44
pub use tag::*;
45
pub use tokio_util::codec::{Decoder, Encoder, Framed};
46
pub use version::*;
47

            
48
pub enum Encoding {
49
    JetStream,
50
    Json,
51
    Xml,
52
}
53

            
54
#[derive(Debug, thiserror::Error)]
55
pub enum EncodingError {
56
    #[error("Invalid encoding")]
57
    InvalidEncoding,
58
}
59

            
60
impl FromStr for Encoding {
61
    type Err = EncodingError;
62

            
63
    fn from_str(s: &str) -> Result<Self, Self::Err> {
64
        match s {
65
            MIMETYPE_JSON => Ok(Encoding::Json),
66
            MIMETYPE_XML => Ok(Encoding::Xml),
67
            MIMETYPE_JETSTREAM => Ok(Encoding::JetStream),
68
            _ => Err(EncodingError::InvalidEncoding),
69
        }
70
    }
71
}
72

            
73
pub use constants::HEADER_KEY_JETSTREAM_PROTO;
74
pub use framer::*;
75

            
76
/// A trait representing a message that can be encoded and decoded.
77
#[cfg(native)]
78
pub trait Message: WireFormat + Sync {}
79

            
80
/// A trait representing a message that can be encoded and decoded.
81
/// WebAssembly doesn't fully support Send+Sync, so we don't require those.
82
#[cfg(target_arch = "wasm32")]
83
pub trait Message: WireFormat {}
84

            
85
/// Defines the request and response types for the JetStream protocol.
86
#[trait_variant::make(Send + Sync + Sized)]
87
pub trait Protocol: Send + Sync {
88
    type Request: Framer;
89
    type Response: Framer;
90
    // r[impl jetstream.error.v2.into-error]
91
    type Error: IntoError;
92
    const VERSION: &'static str;
93
    const NAME: &'static str;
94

            
95
    /// r[impl jetstream.subscription.cancel]
96
    /// The cancellation request for a subscription on this lane, if this
97
    /// protocol has subscriptions to cancel.
98
    ///
99
    /// The client needs to *build* a request it cannot name: `Mux` is
100
    /// generic over the protocol, and `subscription::Tcancel` is a
101
    /// payload, not a `Request`. Only the protocol knows how one is
102
    /// carried in its own request type, so it says here.
103
    ///
104
    /// r[impl jetstream.subscription.compat.rpc-layer]
105
    /// Defaulted to `None` — a protocol with no streaming methods has
106
    /// nothing to cancel, and every protocol written before this existed
107
    /// compiles untouched.
108
    ///
109
    /// `binding` is zero on the subscription's own lane, where `oldtag`
110
    /// is unambiguous; see `subscription::Tcancel`.
111
    fn tcancel(_oldtag: u16, _binding: u64) -> Option<Self::Request> {
112
        None
113
    }
114
}
115

            
116
// const _: () = {
117
//     let _: HashMap<String, Box<dyn Protocol>> = HashMap::new();
118

            
119
//     ()
120
// };