nng 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '059fd5f5fe9ba741fbbbfc57ead871921b2ead9eb5fb5f9ddce30b99cbcb8e8f'
-  data.tar.gz: 6cfb7d0644296c8d2c99f50c7626717139d40a24a59e70c87bb81a29a9db6845
+  metadata.gz: e49576e9e33fb3e2a0bc98702bdd42c8055aed72390b67cb2378fe428ec1c3f9
+  data.tar.gz: d2f7a9e2a8d50eb8bed827f7a5ec1dfbcddc96a7cb9a7d74761b1c4309a9f9ee
 SHA512:
-  metadata.gz: be9d6c590d943a1396cbe3e3c3cb7b6086d52633fe4cf23e03c7c8664d051c6d8183bea23cfb7daf4121df2cbb86589600f4756b6f3c859bd93c946820a33d85
-  data.tar.gz: 4417ea199f3eb0bd1130cd92c375986b5e27ab72c2a68c1cfb7204740fdb3274882e3910bebf99c2b983f4bd803b3e3476e401ea8c57faa12415a3a093f3c7c9
+  metadata.gz: 9925501abf685c5aec0b4f25b7d274635805dfe4597d34ce0caaaad7355a0a88556632060f265754af5a7f8f3015428adce090acabf47fd2fc6240082380ee4d
+  data.tar.gz: c0741f1c0e049eeefc1c4c2c9b26c57305a42cd2136b6665521e20d2fed99ab7e27a2b2c9359f8c65fb2adc5cd0d37a8313c321d7a3dee7cc7e28248305a9ffd

data/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+## 1.0.0
+
+### Breaking changes
+
+- Rewritten C extension from scratch
+- `raw` argument changed from positional bool to keyword (`raw: true`)
+
+### Added
+
+- **TLS transport** — `tls+tcp://` URLs with `cert:`, `key:`, `ca:`, `verify:`, `server_name:` kwargs on `#listen` and `#dial`
+- **Mutual TLS** — server-side client certificate verification
+- **`NNG::Pipe`** — lightweight pipe introspection via `Message#pipe`
+  - `#tls_verified?` — whether peer certificate was verified
+  - `#tls_peer_cn` — peer certificate common name
+  - `#id` — pipe identifier
+- **`NNG::Device`** — transparent message forwarding between sockets
+- **Pipe event notifications** — `Socket::Base#on_pipe_event` yields `:connect`/`:disconnect` events with `NNG::Pipe`
+- **Runtime statistics** — `NNG.stats` and `NNG.stats_for(socket)` return NNG stat snapshots as nested Hashes
+- **`Sub0#subscribe` / `Sub0#unsubscribe`** — add/remove topic subscriptions at runtime
+- `Socket::Base#forward(msg)` — send an existing message preserving its header, enabling stateless raw mode proxying
+- `Socket::Base#raw?` — check whether a socket was opened in raw mode
+- `Sub0.new(prefix:)` — subscribe to a topic prefix at construction time
+- Socket option accessors:
+  - `name` / `name=` — socket name
+  - `urls` — list of listen/dial URLs
+  - `recv_buffer` / `recv_buffer=` — receive buffer size
+  - `send_buffer` / `send_buffer=` — send buffer size
+  - `recv_max_size` / `recv_max_size=` — max receive message size
+  - `recv_timeout` / `recv_timeout=` — receive timeout (ms)
+  - `send_timeout` / `send_timeout=` — send timeout (ms)
+  - `reconnect_time` / `reconnect_time=` — reconnect interval as a `Range` of seconds
+  - `protocol_name` / `peer_name` — read-only protocol info
+- Generic option accessors: `get_opt_int`, `set_opt_int`, `get_opt_ms`, `set_opt_ms`, `get_opt_size`, `set_opt_size`, `get_opt_string`, `set_opt_string`
+- `wait_readable` / `wait_writable` default to the socket's recv/send timeout
+- `receive` / `send` raise `Timeout::Error` on timeout
+- `NNG.nng_version` — returns nng library version as a 3-element array
+- Message manipulation: `#body`, `#body_clear`, `#body_append`, `#header`, `#header=`, `#dup`, `#consumed?`
+- pkg-config support in `extconf.rb` with fallback to system library path
+- ZGuide messaging pattern examples (pipeline, lazy pirate, pub/sub, heartbeat, LVC, bstar, clone)
+- Comprehensive specs for all protocols, TLS, raw mode, timeouts, memory management, and socket options
+- Benchmarks for throughput and latency (inproc/IPC/TCP, async/threads)
+
+## 0.1.0
+
+- Initial release with pair0/pair1, req0/rep0, pub0/sub0, push0/pull0, bus0, surveyor0/respondent0
+- C extension using nng FFI bindings

data/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2021 Adib Saad, Patrik Wenger
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,308 @@
+# rbnng
+
+[![CI](https://github.com/paddor/rbnng/actions/workflows/ci.yml/badge.svg)](https://github.com/paddor/rbnng/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/nng?color=e9573f)](https://rubygems.org/gems/nng)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![TLS](https://img.shields.io/badge/TLS-supported-2ea44f?logo=letsencrypt&logoColor=white)](#tls)
+[![Ruby](https://img.shields.io/badge/Ruby-%3E%3D%203.2-CC342D?logo=ruby&logoColor=white)](https://www.ruby-lang.org)
+
+Fast, native Ruby bindings for [nng](https://nng.nanomsg.org/) — a lightweight, broker-less messaging library for building distributed systems.
+
+> **47k+ msg/s** inproc throughput | **57 µs** fiber roundtrip latency | TLS built-in
+
+---
+
+## Highlights
+
+- **All scalability protocols** — req/rep, pub/sub, push/pull, pair, survey, bus
+- **Native C extension** — no FFI overhead, GVL released during blocking I/O, thread-safe
+- **Async-first** — first-class [async](https://github.com/socketry/async) fiber support
+- **Zero-copy forwarding** — `#forward` transfers message ownership without copying
+- **Raw mode** — bypass the protocol state machine for scalable proxies
+- **TLS transport** — `tls+tcp://` with mTLS, certificate pinning, and peer introspection
+- **Nonblock-first optimization** — tries `NNG_FLAG_NONBLOCK` before releasing the GVL for up to 26% higher throughput
+
+## Install
+
+Install nng on your system:
+
+```sh
+# macOS
+brew install nng
+
+# Debian/Ubuntu
+apt install libnng-dev
+
+# Arch
+pacman -S nng
+```
+
+Then add the gem:
+
+```sh
+gem install nng
+# or in Gemfile
+gem 'nng'
+```
+
+<details>
+<summary>TLS support (optional)</summary>
+
+Install mbedTLS to enable the `tls+tcp://` transport:
+
+```sh
+# macOS
+brew install mbedtls
+
+# Debian/Ubuntu
+apt install libmbedtls-dev
+
+# Arch
+pacman -S mbedtls
+```
+
+</details>
+
+## Quick Start
+
+### Request / Reply
+
+```ruby
+require 'nng'
+require 'async'
+
+Sync do |task|
+  rep = NNG::Socket::Rep0.new
+  rep.listen('tcp://127.0.0.1:5555')
+
+  req = NNG::Socket::Req0.new
+  req.dial('tcp://127.0.0.1:5555')
+
+  task.async do
+    msg = rep.receive
+    rep.send("re: #{msg.body}")
+  end
+
+  req.send('hello')
+  reply = req.receive
+  puts reply.body  # => "re: hello"
+end
+```
+
+### Pub / Sub
+
+```ruby
+Sync do |task|
+  pub = NNG::Socket::Pub0.new
+  pub.listen('ipc:///tmp/pubsub.sock')
+
+  all = NNG::Socket::Sub0.new
+  all.dial('ipc:///tmp/pubsub.sock')
+
+  weather = NNG::Socket::Sub0.new(prefix: 'weather.')
+  weather.dial('ipc:///tmp/pubsub.sock')
+
+  sleep 0.01  # allow connections to establish
+
+  task.async do
+    pub.send('weather.rain')
+    pub.send('sports.goal')
+  end
+
+  puts all.receive.body      # => "weather.rain"
+  puts weather.receive.body  # => "weather.rain"
+  puts all.receive.body      # => "sports.goal"
+  # weather never receives "sports.goal"
+end
+```
+
+### Push / Pull (Pipeline)
+
+```ruby
+Sync do |task|
+  pull = NNG::Socket::Pull0.new
+  pull.listen('inproc://pipeline')
+
+  push = NNG::Socket::Push0.new
+  push.dial('inproc://pipeline')
+
+  task.async { push.send('work item') }
+  puts pull.receive.body  # => "work item"
+end
+```
+
+### Raw Mode Proxy
+
+Raw mode sockets bypass the protocol state machine, enabling stateless message forwarding:
+
+```ruby
+Sync do |task|
+  backend = NNG::Socket::Rep0.new
+  backend.listen('inproc://backend')
+
+  proxy_fe = NNG::Socket::Rep0.new(raw: true)
+  proxy_fe.listen('inproc://frontend')
+
+  proxy_be = NNG::Socket::Req0.new(raw: true)
+  proxy_be.dial('inproc://backend')
+
+  client = NNG::Socket::Req0.new
+  client.dial('inproc://frontend')
+
+  task.async do
+    msg = backend.receive
+    backend.send("processed: #{msg.body}")
+  end
+
+  task.async do
+    msg = proxy_fe.receive
+    proxy_be.forward(msg)
+    reply = proxy_be.receive
+    proxy_fe.forward(reply)
+  end
+
+  client.send('job')
+  puts client.receive.body  # => "processed: job"
+end
+```
+
+### TLS
+
+Any socket type works over TLS — just use `tls+tcp://`. The [localhost](https://github.com/socketry/localhost) gem provides self-signed credentials for development:
+
+```ruby
+require 'localhost'
+
+authority = Localhost::Authority.fetch
+
+Sync do |task|
+  rep = NNG::Socket::Rep0.new
+  rep.listen('tls+tcp://127.0.0.1:5556',
+             cert: authority.certificate, key: authority.key)
+
+  req = NNG::Socket::Req0.new
+  req.dial('tls+tcp://127.0.0.1:5556',
+           ca: authority.issuer.certificate, server_name: 'localhost')
+
+  task.async do
+    msg = rep.receive
+    rep.send("secure: #{msg.body}")
+  end
+
+  req.send('hello')
+  reply = req.receive
+  puts reply.body             # => "secure: hello"
+  puts reply.pipe.tls_peer_cn # => "localhost"
+end
+```
+
+<details>
+<summary>TLS option reference</summary>
+
+**`#listen`**
+| Option | Description |
+|--------|-------------|
+| `cert:` | Server certificate (PEM string, `OpenSSL::X509::Certificate`, or `Pathname`) |
+| `key:` | Private key (PEM string, `OpenSSL::PKey`, or `Pathname`) |
+| `ca:` | CA certificate for client verification (mutual TLS) |
+| `verify:` | Require client certificates (`false` by default) |
+
+**`#dial`**
+| Option | Description |
+|--------|-------------|
+| `ca:` | CA certificate to verify the server |
+| `cert:` / `key:` | Client certificate (for mutual TLS) |
+| `server_name:` | Expected server CN/SAN (defaults to host from URL) |
+| `verify: false` | Skip server certificate verification |
+
+</details>
+
+### Pipe Introspection
+
+Received messages carry a pipe reference for connection-level metadata:
+
+```ruby
+msg = rep.receive
+pipe = msg.pipe
+
+pipe.tls_verified?  # => true
+pipe.tls_peer_cn    # => "localhost"
+pipe.id             # => 1
+```
+
+## Socket Options
+
+```ruby
+sock = NNG::Socket::Req0.new
+sock.name = 'my-socket'
+sock.recv_timeout = 1.0           # seconds (default: nil = infinite)
+sock.send_timeout = 1.0           # seconds (default: nil = infinite)
+sock.recv_buffer = 128            # message count (default: protocol-specific)
+sock.send_buffer = 128            # message count (default: protocol-specific)
+sock.recv_max_size = 1_048_576    # bytes (default: 0 = no limit)
+sock.reconnect_time = 0.1..30.0  # seconds min..max (default: 1.0..0.0)
+
+sock.raw?                         # => false
+sock.protocol_name                # => "req"
+sock.urls                         # => ["tcp://127.0.0.1:5555"]
+```
+
+## Protocols
+
+| Protocol | Class | Direction |
+|----------|-------|-----------|
+| Pair v0 | `Pair0` | bidirectional |
+| Pair v1 | `Pair1` | bidirectional |
+| Request | `Req0` | send + receive |
+| Reply | `Rep0` | receive + send |
+| Publish | `Pub0` | send only |
+| Subscribe | `Sub0` | receive only |
+| Push | `Push0` | send only |
+| Pull | `Pull0` | receive only |
+| Survey | `Surveyor0` | send + receive |
+| Respond | `Respondent0` | receive + send |
+| Bus | `Bus0` | bidirectional |
+
+All classes live under `NNG::Socket::` and support `raw: true` for raw mode.
+
+## Transports
+
+| Transport | URL scheme | Notes |
+|-----------|-----------|-------|
+| In-process | `inproc://` | Fastest, same process only |
+| IPC | `ipc://` | Unix domain sockets |
+| Abstract | `abstract://` | Linux abstract namespace (no filesystem path) |
+| TCP | `tcp://` | TCP/IP |
+| TLS | `tls+tcp://` | TCP + TLS encryption (requires mbedTLS) |
+
+## Performance
+
+Benchmarked with benchmark-ips on Linux x86_64 (NNG 1.10.0, Ruby 4.0.1 +YJIT):
+
+#### Throughput (push/pull)
+
+| | inproc | abstract | ipc | tcp |
+|---|--------|----------|-----|-----|
+| **Async** | 47.3k/s | 14.3k/s | 13.3k/s | 8.4k/s |
+| **Threads** | 41.7k/s | 15.4k/s | 16.6k/s | 10.1k/s |
+
+#### Latency (req/rep roundtrip)
+
+| | inproc | abstract | ipc | tcp |
+|---|--------|----------|-----|-----|
+| **Async** | 57 µs | 180 µs | 155 µs | 204 µs |
+| **Threads** | 106 µs | 118 µs | 134 µs | 151 µs |
+
+Async fibers deliver 1.9x lower inproc latency thanks to cheap context switching. See [`bench/`](bench/) for full results and scripts.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake compile
+bundle exec rake test
+```
+
+## License
+
+[MIT](LICENSE)

data/ext/rbnng/device.c

@@ -0,0 +1,43 @@
+#include "rbnng.h"
+
+typedef struct {
+    nng_socket s1;
+    nng_socket s2;
+    int        rv;
+} device_args_t;
+
+static void *
+device_without_gvl(void *arg)
+{
+    device_args_t *a = arg;
+    a->rv = nng_device(a->s1, a->s2);
+    return NULL;
+}
+
+static VALUE
+device_start(VALUE self, VALUE sock1, VALUE sock2)
+{
+    rbnng_socket_t *s1, *s2;
+    TypedData_Get_Struct(sock1, rbnng_socket_t, &rbnng_socket_type, s1);
+    TypedData_Get_Struct(sock2, rbnng_socket_t, &rbnng_socket_type, s2);
+
+    if (!s1->initialized || !s2->initialized)
+        rb_raise(rb_eRuntimeError, "socket not initialized");
+
+    device_args_t args;
+    args.s1 = s1->socket;
+    args.s2 = s2->socket;
+
+    rb_thread_call_without_gvl(device_without_gvl, &args, RUBY_UBF_IO, NULL);
+
+    if (args.rv != 0)
+        raise_nng_error(args.rv);
+    return Qnil;
+}
+
+void
+rbnng_device_init(VALUE nng_module)
+{
+    VALUE mod = rb_define_module_under(nng_module, "Device");
+    rb_define_singleton_method(mod, "start", device_start, 2);
+}