protocol-sp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b3a9f50418b5ea8885c5e54d7d8245bf47fea17bd6f2f32e5ed84707fec6868a
+  data.tar.gz: 3c9dfd7d357ef8dea0b325c99c5b326a39e25ee4eb292e3a7ec655f80de3c213
+SHA512:
+  metadata.gz: 9964fdb2780489536856044c5686af01b2b63b685589c43c96b9c48929b9e5afc7ee4cba5ea56ab0ccb9b3f0d72909e53ab6d394b08e076aa107d2ca60a3e0f7
+  data.tar.gz: ea786df241e7777e6715bdc97eeb73e52270f238c0e43b45fbd7efd2a533efd3db604eab27156526d6230ca1fa5804fb559d82db19488257ef5e9aae4e94caf4

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0 — 2026-04-09
+
+Initial release.
+
+- `Protocol::SP::Codec::Frame` — length-prefixed framing. SP/TCP uses an 8-byte big-endian length; SP/IPC prepends a 1-byte message type to match nng's wire format.
+- `Protocol::SP::Codec::Greeting` — 8-byte SP/TCP greeting.
+- `Protocol::SP::Protocols` — protocol identifier constants.
+- `Protocol::SP::Connection` — mutex-protected handshake, `#send_message`, `#write_message`, `#write_messages` (batched), `#receive_message`. `framing:` selects `:tcp` or `:ipc`.

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright (c) 2026, Patrik Wenger
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

data/README.md

@@ -0,0 +1,26 @@
+# protocol-sp
+
+[![CI](https://github.com/paddor/protocol-sp/actions/workflows/ci.yml/badge.svg)](https://github.com/paddor/protocol-sp/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/protocol-sp?color=e9573f)](https://rubygems.org/gems/protocol-sp)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](LICENSE)
+[![Ruby](https://img.shields.io/badge/Ruby-%3E%3D%203.3-CC342D?logo=ruby&logoColor=white)](https://www.ruby-lang.org)
+
+Pure Ruby codec and connection for the [Scalability Protocols](https://nanomsg.org/documentation-zeromq.html) (SP) wire format used by [nanomsg](https://nanomsg.org) and [nng](https://nng.nanomsg.org). Zero runtime dependencies. Sister gem to [protocol-zmtp](https://github.com/paddor/protocol-zmtp).
+
+## What's in the box
+
+- `Protocol::SP::Codec::Frame` — length-prefixed framing. SP/TCP uses an 8-byte big-endian length; SP/IPC prepends a 1-byte message type (0x00 control, 0x01 user) to match nng's wire format.
+- `Protocol::SP::Codec::Greeting` — 8-byte handshake: `00 'S' 'P' 00 <peer-proto:u16-BE> 00 00`.
+- `Protocol::SP::Protocols` — protocol identifier constants (PUSH=0x50, PULL=0x51, PUB=0x20, SUB=0x21, REQ=0x30, REP=0x31, PAIR_V0=0x10, PAIR_V1=0x11, BUS=0x70, SURVEYOR=0x62, RESPONDENT=0x63).
+- `Protocol::SP::Connection` — mutex-protected `#handshake!`, `#send_message`, `#write_message` (no flush), `#write_messages` (batched under a single mutex acquisition), `#receive_message` over any IO-like object. `framing:` selects `:tcp` or `:ipc`.
+
+## Notes
+
+- SP messages are single-frame (no multipart, unlike ZMTP).
+- No security mechanisms in the SP wire protocol — encryption is layered via TLS/WebSocket transports, not the SP framing.
+- No commands at the wire level — protocol-specific control bytes (e.g. REQ request IDs, SUB topics) live inside the message body.
+- Zero-alloc frame headers on the unencrypted hot send path via `Array#pack(buffer:)`.
+
+## Usage
+
+`protocol-sp` is a low-level codec. For a full socket API (PUSH/PULL, REQ/REP, PAIR, transports, reconnect), see [nnq](https://github.com/paddor/nnq).

data/lib/protocol/sp/codec/frame.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Protocol
+  module SP
+    module Codec
+      # SP/TCP frame encode/decode.
+      #
+      # Wire format (per nng `src/sp/transport/tcp/tcp.c`):
+      #   8 bytes  body length, big-endian unsigned 64-bit
+      #   N bytes  body
+      #
+      # SP messages are single-frame — there is no MORE flag and no
+      # multipart concept at the transport level.
+      #
+      class Frame
+        HEADER_SIZE = 8
+
+
+        # @return [String] frame body (binary)
+        attr_reader :body
+
+        # @param body [String] frame body
+        def initialize(body)
+          @body = body.b
+        end
+
+
+        # Encodes to wire bytes.
+        #
+        # @return [String] binary wire representation (length + body)
+        def to_wire
+          [@body.bytesize].pack("Q>") + @body
+        end
+
+
+        # Encodes a body into wire bytes without allocating a Frame.
+        #
+        # @param body [String]
+        # @return [String] frozen binary wire representation
+        def self.encode(body)
+          ([body.bytesize].pack("Q>") + body.b).freeze
+        end
+
+
+        # Reads one frame from an IO-like object.
+        #
+        # @param io [#read_exactly] must support read_exactly(n)
+        # @param max_message_size [Integer, nil] maximum body size, nil = unlimited
+        # @return [Frame]
+        # @raise [Error] on oversized frame
+        # @raise [EOFError] if the connection is closed
+        def self.read_from(io, max_message_size: nil)
+          size = io.read_exactly(HEADER_SIZE).unpack1("Q>")
+
+          if max_message_size && size > max_message_size
+            raise Error, "frame size #{size} exceeds max_message_size #{max_message_size}"
+          end
+
+          body = size > 0 ? io.read_exactly(size) : "".b
+          new(body)
+        end
+      end
+    end
+  end
+end

data/lib/protocol/sp/codec/greeting.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Protocol
+  module SP
+    module Codec
+      # SP/TCP greeting encode/decode.
+      #
+      # The greeting is exactly 8 bytes (per nng `src/sp/transport/tcp/tcp.c`,
+      # `tcptran_pipe_nego_cb` and `tcptran_pipe_send_start`):
+      #
+      #   Offset  Bytes  Field
+      #   0       1      0x00
+      #   1       1      'S' (0x53)
+      #   2       1      'P' (0x50)
+      #   3       1      0x00
+      #   4-5     2      protocol id (u16, big-endian)
+      #   6-7     2      reserved (must be 0x00 0x00)
+      #
+      module Greeting
+        SIZE      = 8
+        SIGNATURE = "\x00SP\x00".b.freeze
+
+
+        # Encodes an SP/TCP greeting.
+        #
+        # @param protocol [Integer] our protocol id (e.g. Protocols::PUSH_V0)
+        # @return [String] 8-byte binary greeting
+        def self.encode(protocol:)
+          SIGNATURE + [protocol].pack("n") + "\x00\x00".b
+        end
+
+
+        # Decodes an SP/TCP greeting.
+        #
+        # @param data [String] 8-byte binary greeting
+        # @return [Integer] peer protocol id
+        # @raise [Error] on invalid greeting
+        def self.decode(data)
+          raise Error, "greeting too short (#{data.bytesize} bytes)" if data.bytesize < SIZE
+
+          data = data.b
+          unless data.byteslice(0, 4) == SIGNATURE
+            raise Error, "invalid SP greeting signature"
+          end
+          unless data.getbyte(6) == 0 && data.getbyte(7) == 0
+            raise Error, "invalid SP greeting reserved bytes"
+          end
+
+          data.byteslice(4, 2).unpack1("n")
+        end
+      end
+    end
+  end
+end

data/lib/protocol/sp/codec.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Protocol
+  module SP
+    module Codec
+    end
+  end
+end
+
+require_relative "codec/frame"
+require_relative "codec/greeting"

data/lib/protocol/sp/connection.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+module Protocol
+  module SP
+    # Manages one SP peer connection over any transport IO.
+    #
+    # The SP wire protocol has no commands, no security mechanisms, and no
+    # multipart messages — `#handshake!` is just an exchange of two 8-byte
+    # greetings, and `#send_message` / `#receive_message` work on single
+    # binary bodies framed by an 8-byte big-endian length.
+    #
+    class Connection
+      # SP/IPC data messages are prefixed with a 1-byte message type.
+      # 0x01 = user message. 0x00 is reserved in nng for control frames
+      # (keepalive) that we don't emit, but we still accept and skip on
+      # read for forward-compatibility with nng peers.
+      IPC_MSG_TYPE = 0x01
+
+
+      # @return [Integer] peer's protocol id (set after handshake)
+      attr_reader :peer_protocol
+
+      # @return [Object] transport IO (#read_exactly, #write, #flush, #close)
+      attr_reader :io
+
+      # @return [Float, nil] monotonic timestamp of last received frame
+      attr_reader :last_received_at
+
+      # @return [Symbol] :tcp or :ipc
+      attr_reader :framing
+
+      # @param io [#read_exactly, #write, #flush, #close] transport IO
+      # @param protocol [Integer] our protocol id (e.g. Protocols::PUSH_V0)
+      # @param max_message_size [Integer, nil] max body size, nil = unlimited
+      # @param framing [Symbol] :tcp (default) uses 8-byte length headers;
+      #   :ipc prepends a 1-byte message-type marker to each frame
+      #   (nng's SP/IPC wire format)
+      def initialize(io, protocol:, max_message_size: nil, framing: :tcp)
+        @io               = io
+        @protocol         = protocol
+        @peer_protocol    = nil
+        @max_message_size = max_message_size
+        @framing          = framing
+        @mutex            = Mutex.new
+        @last_received_at = nil
+        # Reusable scratch buffer for frame headers — written into by
+        # Array#pack(buffer:), then flushed to @io. Capacity 9 covers
+        # both :tcp (8B) and :ipc (1+8B) framings.
+        @header_buf = String.new(capacity: 9, encoding: Encoding::BINARY)
+      end
+
+
+      # Performs the SP/TCP greeting exchange.
+      #
+      # @return [void]
+      # @raise [Error] on greeting mismatch or peer-incompatibility
+      def handshake!
+        @io.write(Codec::Greeting.encode(protocol: @protocol))
+        @io.flush
+
+        peer = Codec::Greeting.decode(@io.read_exactly(Codec::Greeting::SIZE))
+        @peer_protocol = peer
+
+        valid = Protocols::VALID_PEERS[@protocol]
+        unless valid&.include?(peer)
+          raise Error, "incompatible SP protocols: 0x#{@protocol.to_s(16)} cannot speak to 0x#{peer.to_s(16)}"
+        end
+      end
+
+
+      # Sends one message (write + flush).
+      #
+      # @param body [String] message body (single frame)
+      # @return [void]
+      def send_message(body)
+        @mutex.synchronize do
+          write_header_nolock(body.bytesize)
+          @io.write(body)
+          @io.flush
+        end
+      end
+
+
+      # Writes one message to the buffer without flushing.
+      # Call {#flush} after batching writes.
+      #
+      # Two writes — header then body — into the buffered IO; avoids
+      # the per-message intermediate String allocation that
+      # {Codec::Frame.encode} would otherwise produce.
+      #
+      # @param body [String]
+      # @return [void]
+      def write_message(body)
+        @mutex.synchronize do
+          write_header_nolock(body.bytesize)
+          @io.write(body)
+        end
+      end
+
+
+      # Writes a batch of messages to the buffer under a single mutex
+      # acquisition. Used by work-stealing send pumps that dequeue up
+      # to N messages at once — avoids N lock/unlock pairs per batch.
+      # Call {#flush} after to push the buffer to the socket.
+      #
+      # @param bodies [Array<String>]
+      # @return [void]
+      def write_messages(bodies)
+        @mutex.synchronize do
+          i = 0
+          n = bodies.size
+          while i < n
+            body = bodies[i]
+            write_header_nolock(body.bytesize)
+            @io.write(body)
+            i += 1
+          end
+        end
+      end
+
+
+      # Writes the frame header into the already-held @mutex. Hotpath:
+      # keep the branch monomorphic per-connection and avoid fresh pack
+      # allocations by packing into a per-connection scratch buffer.
+      #
+      # @param size [Integer] body size
+      # @return [void]
+      private def write_header_nolock(size)
+        buf = @header_buf
+        buf.clear
+        if @framing == :ipc
+          [IPC_MSG_TYPE, size].pack("CQ>", buffer: buf)
+        else
+          [size].pack("Q>", buffer: buf)
+        end
+        @io.write(buf)
+      end
+
+
+      # Writes pre-encoded wire bytes without flushing. Used for fan-out:
+      # encode once with `Codec::Frame.encode`, write to many connections.
+      #
+      # @param wire_bytes [String]
+      # @return [void]
+      def write_wire(wire_bytes)
+        @mutex.synchronize do
+          @io.write(wire_bytes)
+        end
+      end
+
+
+      # Flushes the write buffer to the underlying IO.
+      #
+      # @return [void]
+      def flush
+        @mutex.synchronize do
+          @io.flush
+        end
+      end
+
+
+      # Receives one message body.
+      #
+      # @return [String] binary body (NOT frozen — let callers freeze if
+      #   they want, the freeze cost shows up in hot loops)
+      # @raise [EOFError] if connection is closed
+      def receive_message
+        if @framing == :ipc
+          loop do
+            # One read_exactly(9) is cheaper than separate 1+8 reads:
+            # halves the io-stream dispatch overhead per message.
+            header     = @io.read_exactly(9)
+            type, size = header.unpack("CQ>")
+            if @max_message_size && size > @max_message_size
+              raise Error, "frame size #{size} exceeds max_message_size #{@max_message_size}"
+            end
+            body = size > 0 ? @io.read_exactly(size) : "".b
+            touch_heartbeat
+            # Skip nng IPC control frames (0x00 — keepalive/etc.); only
+            # deliver user messages (0x01) to the caller.
+            return body if type == IPC_MSG_TYPE
+          end
+        else
+          frame = Codec::Frame.read_from(@io, max_message_size: @max_message_size)
+          touch_heartbeat
+          frame.body
+        end
+      rescue Error
+        close
+        raise
+      end
+
+
+      # Records that a frame was received (for inactivity tracking).
+      #
+      # @return [void]
+      def touch_heartbeat
+        @last_received_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+
+      # Returns true if no frame has been received within +timeout+ seconds.
+      #
+      # @param timeout [Numeric] seconds
+      # @return [Boolean]
+      def heartbeat_expired?(timeout)
+        return false unless @last_received_at
+        (Process.clock_gettime(Process::CLOCK_MONOTONIC) - @last_received_at) > timeout
+      end
+
+
+      # Closes the connection.
+      #
+      # @return [void]
+      def close
+        @io.close
+      rescue IOError
+        # already closed
+      end
+    end
+  end
+end

data/lib/protocol/sp/error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Protocol
+  module SP
+    # Raised on SP protocol violations.
+    class Error < RuntimeError
+    end
+  end
+end

data/lib/protocol/sp/protocols.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Protocol
+  module SP
+    # Wire-level protocol identifiers (16-bit, big-endian on the wire).
+    #
+    # Encoding: `(major << 4) | minor`, matching nng's `NNI_PROTO(major,
+    # minor)` macro in `src/core/protocol.h`. Sourced from
+    # `src/sp/protocol/*/`.
+    #
+    module Protocols
+      PAIR_V0    = 0x10  # (1, 0)
+      PAIR_V1    = 0x11  # (1, 1)
+
+      PUB_V0     = 0x20  # (2, 0)
+      SUB_V0     = 0x21  # (2, 1)
+
+      REQ_V0     = 0x30  # (3, 0)
+      REP_V0     = 0x31  # (3, 1)
+
+      PUSH_V0    = 0x50  # (5, 0)
+      PULL_V0    = 0x51  # (5, 1)
+
+      SURVEYOR_V0   = 0x62 # (6, 2)
+      RESPONDENT_V0 = 0x63 # (6, 3)
+
+      BUS_V0     = 0x70  # (7, 0)
+
+
+      # Compatibility table: which peer ID is acceptable for each self ID.
+      VALID_PEERS = {
+        PAIR_V0       => [PAIR_V0],
+        PAIR_V1       => [PAIR_V1],
+        PUB_V0        => [SUB_V0],
+        SUB_V0        => [PUB_V0],
+        REQ_V0        => [REP_V0],
+        REP_V0        => [REQ_V0],
+        PUSH_V0       => [PULL_V0],
+        PULL_V0       => [PUSH_V0],
+        SURVEYOR_V0   => [RESPONDENT_V0],
+        RESPONDENT_V0 => [SURVEYOR_V0],
+        BUS_V0        => [BUS_V0],
+      }.freeze
+
+
+      NAMES = {
+        PAIR_V0       => "pair",
+        PAIR_V1       => "pair1",
+        PUB_V0        => "pub",
+        SUB_V0        => "sub",
+        REQ_V0        => "req",
+        REP_V0        => "rep",
+        PUSH_V0       => "push",
+        PULL_V0       => "pull",
+        SURVEYOR_V0   => "surveyor",
+        RESPONDENT_V0 => "respondent",
+        BUS_V0        => "bus",
+      }.freeze
+    end
+  end
+end

data/lib/protocol/sp/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Protocol
+  module SP
+    VERSION = "0.1.0"
+  end
+end

data/lib/protocol/sp.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Protocol
+  # Scalability Protocols (nanomsg/nng) wire codec and connection.
+  module SP
+  end
+end
+
+require_relative "sp/version"
+require_relative "sp/error"
+require_relative "sp/protocols"
+require_relative "sp/codec"
+require_relative "sp/connection"

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: protocol-sp
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Patrik Wenger
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Pure Ruby implementation of the Scalability Protocols wire format used
+  by nanomsg and nng. Includes the SP/TCP framing codec, 8-byte greeting, protocol
+  identifiers, and connection management. No runtime dependencies.
+email:
+- paddor@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/protocol/sp.rb
+- lib/protocol/sp/codec.rb
+- lib/protocol/sp/codec/frame.rb
+- lib/protocol/sp/codec/greeting.rb
+- lib/protocol/sp/connection.rb
+- lib/protocol/sp/error.rb
+- lib/protocol/sp/protocols.rb
+- lib/protocol/sp/version.rb
+homepage: https://github.com/paddor/protocol-sp
+licenses:
+- ISC
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Scalability Protocols (nanomsg/nng) wire codec and connection
+test_files: []