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

//! > Note that this library is in the very early stages of development!
//! > Anything and everything may change!
//!
//! # zedmq
//!
//! ## A Lightweight, Safe, pure-Rust ØMQ/ZMTP library implementation
//!
//! ## Index
//!
//! * [Brief](#brief)
//! * [Examples](#examples)
//!
//! ### Brief
//!
//! _Zedmq_ is a native implementation of ØMQ in Rust focusing on:
//!
//! * being as lightweight as possible.
//! * being completely safe.
//! * providing a simple, blocking, obvious API.
//!
//! This library is lazy and blocking, no work is done unless a call to a
//! `recv` or `send` is made. There is no "background" thread or task accepting
//! new connections or performing reconnections on the users behalf
//! consequently there is no shared state or synchronization being performed.
//!
//! #### Caveats
//!
//! Currently this library only supports connecting sockets
//! over TCP, no binding behaviour is available.
//!
//! Also only a few socket types have been implemented: REQ, REP, PULL, PUSH,
//! and SUB (PUB is being worked on).
//!
//! #### `Frame<'_>` and `FrameBuf`
//!
//! This library also exposes the underlying ZMQ concept of a frame.
//! Additionally a distinction is made with the `Frame` and `FrameBuf` types
//! for optimization purposes.
//!
//! Conceptually a `Frame<'_>` is equivelent to `&'_ [u8]` or `&'_ str` and
//! the `FrameBuf` equivelent is `Vec<u8>` or `String`. This distinction is
//! made in an attempt to make "zero copy" or "zero heap" practice easier.
//!
//! #### `REQ` and `REP`
//!
//! The design of `REQ` and `REP` sockets are symetrical and rendered safe
//! through the use of the type system.
//!
//! A `Req` socket only has `.connect` and `.send` methods, `.send` of which
//! consumes the socket and returns a `ReqPending` socket which only has a `.recv`
//! method which in turn returns a multipart message and `Req` socket tuple.
//!
//! Same goes for the `Rep` socket except that `Rep` has `.recv` and
//! `RepPending` has `.send`.
//!
//! This done on purpose, its value is that there are no accidental footguns
//! involved with accidentially `.send`ing when you are only allowed to `.recv`
//! or vice versa. Plus it removes the cost of runtime checking.
//!
//! ### Examples
//!
//! ```rust,no_run
//! use zedmq::prelude::*;
//!
//! fn main() -> std::io::Result<()> {
//!     let mut socket: Pull = zedmq::connect("tcp", "127.0.0.1:5678")?;
//!
//!     while let Ok(message) = socket.recv() {
//!         dbg!(message);
//!     }
//!
//!     Ok(())
//! }
//! ```

#![forbid(unsafe_code)]
#![warn(missing_docs)]

/// The currently supported ZMQ version.
pub const ZMQ_VERSION: (u8, u8, u8) = (3, 1, 0);

pub(crate) mod codec;
mod socket_type;
pub(crate) mod stream;

pub use socket_type::{
    pull_t::Pull,
    push_t::Push,
    rep_t::{Rep, RepPending},
    req_t::{Req, ReqPending},
    sub_t::Sub,
};

mod sealed {
    pub trait SocketType {
        fn name() -> &'static str;
    }

    macro_rules! impl_socket_type {
        [$( ($name:ident, $st:literal) ),+] => {
            $(
                impl SocketType for $crate::$name { fn name() -> &'static str { $st } }
            )+
        }
    }

    impl_socket_type![
        (Pull, "PULL"),
        (Push, "PUSH"),
        (Sub, "SUB"),
        (Req, "REQ"),
        (Rep, "REP")
    ];
}

use sealed::SocketType;
use socket_type::Socket;
use stream::Stream;

/// Start a ZMQ socket with the specified `transport` to the specified `address`.
pub fn connect<S>(transport: &str, address: &str) -> std::io::Result<S>
where
    S: SocketType + Socket + From<Stream>,
{
    assert_eq!(transport, "tcp", "Only TCP is supported.");

    let name = <S as SocketType>::name();
    let stream = Stream::connected(name, address);

    Ok(stream.into())
}

/// Bind a ZMQ socket with the specified `transport` to the specified `address`.
pub fn bind<S>(_transport: &str, _address: &str) -> std::io::Result<S>
where
    S: SocketType + Socket + From<Stream>,
{
    unimplemented!();
}

/// The library prelude, containing all the stuff you probably want.
pub mod prelude {
    pub use super::*;
}