protocol-zmtp 0.7.1 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e17c453960d40efb63134468319f184e1751a1812a42e72b4b10de4f10c08f7a
-  data.tar.gz: 3aa77f8983e7b737bc9c896d4ff7b0a476805e51d1bd2668d4399c4547beb2ca
+  metadata.gz: 81270e34092271f0e0aaceed0ce882885751def59b75716872d074952e4d6b41
+  data.tar.gz: ccbf823376d70d8654384b99c1bb30b270dc9493cd432c524a3caab175eaa364
 SHA512:
-  metadata.gz: c325ce9ad10043d55875304bf4267f5ef7ab286945126620fe43f0ec5eeedb228804ed1c6bb97a6dc135adc017124add12b56a1475bfb1ff37d74a0dc7536abc
-  data.tar.gz: 1cdd5b8fd5abb3471c6e4147850b7e5d20c5bc47cec6fb4233c7e38845f8e5b8df2fd73463e618a128d07316c184facf678fa718674b8ba6e1cb70e9390310d5
+  metadata.gz: f148b0ac01768320f35f2edf7ac67f3d51ad3e5daa4a9c9dafccb57168e8e9f616f6f27425c00b82edcd7e0af898188ae37ea3a78f404a786bdd9a94c01cb675
+  data.tar.gz: bdab4d4b763394ea1f11aec4503a74d68f499671c93851adc96c2e34bcd7134de837b71941119a1aa029a0966c4ed4cfea8def3f5140244e50f9c2a9b3b0355d

data/lib/protocol/zmtp/codec/command.rb

@@ -130,9 +130,9 @@ module Protocol
         # @param ttl [Numeric] time-to-live in seconds (sent as deciseconds)
         # @param context [String] optional context bytes (up to 16 bytes)
         # @return [Command]
-        def self.ping(ttl: 0, context: "".b)
+        def self.ping(ttl: 0, context: EMPTY_BINARY)
           ttl_ds = (ttl * 10).to_i
-          new("PING", [ttl_ds].pack("n") + context.b)
+          new("PING", [ttl_ds].pack("n") + (context.encoding == Encoding::BINARY ? context : context.b))
         end
 
 
@@ -140,8 +140,8 @@ module Protocol
         #
         # @param context [String] context bytes echoed from the PING
         # @return [Command]
-        def self.pong(context: "".b)
-          new("PONG", context.b)
+        def self.pong(context: EMPTY_BINARY)
+          new("PONG", context.encoding == Encoding::BINARY ? context : context.b)
         end
 
 
@@ -150,7 +150,7 @@ module Protocol
         # @return [Array(Numeric, String)] [ttl_seconds, context_bytes]
         def ping_ttl_and_context
           ttl_ds  = @data.unpack1("n")
-          context = @data.bytesize > 2 ? @data.byteslice(2..) : "".b
+          context = @data.bytesize > 2 ? @data.byteslice(2..) : EMPTY_BINARY
           [ttl_ds / 10.0, context]
         end
 

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

@@ -31,21 +31,28 @@ module Protocol
         # @return [String] frame body (binary)
         attr_reader :body
 
+
         # @param body [String] frame body
         # @param more [Boolean] more frames follow
         # @param command [Boolean] this is a command frame
         def initialize(body, more: false, command: false)
-          @body    = body.b
+          @body    = body.encoding == Encoding::BINARY ? body : body.b
           @more    = more
           @command = command
         end
 
 
         # @return [Boolean] true if more frames follow in this message
-        def more?    = @more
+        def more?
+          @more
+        end
+
 
         # @return [Boolean] true if this is a command frame
-        def command? = @command
+        def command?
+          @command
+        end
+
 
         # Encodes to wire bytes.
         #
@@ -57,9 +64,11 @@ module Protocol
           flags |= FLAGS_COMMAND if @command
 
           if size > SHORT_MAX
-            FLAG_BYTES[flags | FLAGS_LONG] + [size].pack("Q>") + @body
+            buf = String.new(capacity: 9 + size, encoding: Encoding::BINARY)
+            buf << FLAG_BYTES[flags | FLAGS_LONG] << [size].pack("Q>") << @body
           else
-            FLAG_BYTES[flags] + FLAG_BYTES[size] + @body
+            buf = String.new(capacity: 2 + size, encoding: Encoding::BINARY)
+            buf << FLAG_BYTES[flags] << FLAG_BYTES[size] << @body
           end
         end
 
@@ -72,14 +81,29 @@ module Protocol
         # @return [String] frozen binary wire representation
         #
         def self.encode_message(parts)
-          buf  = String.new(encoding: Encoding::BINARY)
+          if parts.size == 1
+            s = parts[0].bytesize
+            wire_size = s > SHORT_MAX ? 9 + s : 2 + s
+          else
+            wire_size = 0
+            j = 0
+            while j < parts.size
+              s = parts[j].bytesize
+              wire_size += s > SHORT_MAX ? 9 + s : 2 + s
+              j += 1
+            end
+          end
+
+          buf  = String.new(capacity: wire_size, encoding: Encoding::BINARY)
           last = parts.size - 1
           i    = 0
+
           while i < parts.size
             body  = parts[i]
             body  = body.b unless body.encoding == Encoding::BINARY
             size  = body.bytesize
             flags = i < last ? FLAGS_MORE : 0
+
             if size > SHORT_MAX
               buf << FLAG_BYTES[flags | FLAGS_LONG] << [size].pack("Q>") << body
             else
@@ -87,6 +111,7 @@ module Protocol
             end
             i += 1
           end
+
           buf.freeze
         end
 
@@ -137,6 +162,7 @@ module Protocol
             (rest.getbyte(4) << 16) | (rest.getbyte(5) << 8)  |
              rest.getbyte(6)
         end
+
       end
     end
   end

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

@@ -18,6 +18,11 @@ module Protocol
       #
       module Greeting
         SIZE             = 64
+        # Bytes 0..10 cover the 10-byte signature plus the major-version
+        # byte at offset 10. ZMTP 2.0 peers only send an 11-byte signature
+        # phase (their full greeting is shorter than 64), so we must
+        # sniff the major version before committing to reading 64 bytes.
+        SIGNATURE_SIZE   = 11
         SIGNATURE_START  = 0xFF
         SIGNATURE_END    = 0x7F
         VERSION_MAJOR    = 3
@@ -41,6 +46,32 @@ module Protocol
         end
 
 
+        # Reads and decodes a ZMTP 3.x greeting from +io+, sniffing the
+        # major version after the first 11 bytes so a ZMTP 2.0 peer
+        # (which would never send the full 64 bytes) is detected and
+        # rejected without blocking forever on +read_exactly+.
+        #
+        # @param io [#read_exactly]
+        # @return [Hash] { major:, minor:, mechanism:, as_server: }
+        # @raise [Error] on invalid signature or unsupported version
+        #
+        def self.read_from(io)
+          sig   = io.read_exactly(SIGNATURE_SIZE).b
+          major = sig.getbyte(10)
+
+          unless sig.getbyte(0) == SIGNATURE_START && sig.getbyte(9) == SIGNATURE_END
+            raise Error, "invalid greeting signature"
+          end
+
+          unless major >= 3
+            raise Error, "unsupported ZMTP revision 0x%02x (ZMTP/%d.x); need revision >= 3" %
+                         [major, major == 1 ? 2 : major]
+          end
+
+          decode(sig + io.read_exactly(SIZE - SIGNATURE_SIZE))
+        end
+
+
         # Decodes a ZMTP greeting.
         #
         # @param data [String] 64-byte binary greeting
@@ -59,7 +90,7 @@ module Protocol
           minor = data.getbyte(11)
 
           unless major >= 3
-            raise Error, "unsupported ZMTP version #{major}.#{minor} (need >= 3.0)"
+            raise Error, "unsupported ZMTP revision 0x%02x (need revision >= 3)" % major
           end
 
           mechanism = data.byteslice(MECHANISM_OFFSET, MECHANISM_LENGTH).delete("\x00")

data/lib/protocol/zmtp/codec/subscription.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Protocol
+  module ZMTP
+    module Codec
+
+      # ZMTP subscription encoding.
+      #
+      # Two wire formats exist and both are in active use:
+      #
+      # * **Message form (ZMTP 3.0 legacy, RFC 23).** A regular data
+      #   frame whose body is `\x01` + prefix (subscribe) or `\x00` +
+      #   prefix (cancel). libzmq, JeroMQ, pyzmq, CZMQ, NetMQ all send
+      #   subscriptions in this form by default, and all accept it.
+      #
+      # * **Command form (ZMTP 3.1, RFC 37).** A COMMAND-flagged frame
+      #   whose body is a Command named "SUBSCRIBE" or "CANCEL" with
+      #   the prefix as the command data.
+      #
+      # Interop requires sending the message form (understood by every
+      # ZMTP 3.0+ peer) and accepting both forms on the receiving side.
+      #
+      module Subscription
+        FLAG_SUBSCRIBE = "\x01".b.freeze
+        FLAG_CANCEL    = "\x00".b.freeze
+
+        module_function
+
+        # Builds the body of a subscription message in the legacy
+        # message form.
+        #
+        # @param prefix [String] topic prefix
+        # @param cancel [Boolean] true to build an unsubscribe
+        # @return [String] binary frame body
+        def body(prefix, cancel: false)
+          flag = cancel ? FLAG_CANCEL : FLAG_SUBSCRIBE
+          flag + (prefix.encoding == Encoding::BINARY ? prefix : prefix.b)
+        end
+
+
+        # Attempts to parse a frame as a subscription. Accepts both the
+        # legacy message form and the ZMTP 3.1 command form.
+        #
+        # @param frame [Frame]
+        # @return [Array(Symbol, String), nil] `[:subscribe, prefix]`,
+        #   `[:cancel, prefix]`, or `nil` if the frame is not a
+        #   subscription
+        def parse(frame)
+          if frame.command?
+            cmd = Command.from_body(frame.body)
+            case cmd.name
+            when "SUBSCRIBE" then [:subscribe, cmd.data]
+            when "CANCEL"    then [:cancel, cmd.data]
+            end
+          else
+            body = frame.body
+            return nil if body.empty?
+
+            prefix = body.byteslice(1..) || "".b
+            case body.getbyte(0)
+            when 0x01 then [:subscribe, prefix]
+            when 0x00 then [:cancel, prefix]
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/protocol/zmtp/codec.rb

@@ -11,3 +11,4 @@ end
 require_relative "codec/greeting"
 require_relative "codec/frame"
 require_relative "codec/command"
+require_relative "codec/subscription"

data/lib/protocol/zmtp/connection.rb

@@ -15,25 +15,41 @@ module Protocol
       # @return [String] peer's socket type (from READY handshake)
       attr_reader :peer_socket_type
 
+
       # @return [String] peer's identity (from READY handshake)
       attr_reader :peer_identity
 
+
       # @return [Integer] peer's QoS level (from READY handshake, 0 if absent)
       attr_reader :peer_qos
 
+
       # @return [String] peer's supported hash algorithms in preference order
       attr_reader :peer_qos_hash
 
+
       # @return [Hash{String => String}, nil] full peer READY property hash
       #   (set after a successful handshake; nil before)
       attr_reader :peer_properties
 
+
+      # @return [Integer, nil] peer ZMTP major version (from greeting)
+      attr_reader :peer_major
+
+
+      # @return [Integer, nil] peer ZMTP minor version (from greeting);
+      #   0 for ZMTP 3.0 peers, 1 for ZMTP 3.1+
+      attr_reader :peer_minor
+
+
       # @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
 
+
       # @param io [#read_exactly, #write, #flush, #close] transport IO
       # @param socket_type [String] our socket type name (e.g. "REQ")
       # @param identity [String] our identity
@@ -52,6 +68,8 @@ module Protocol
         @peer_qos         = nil
         @peer_qos_hash    = nil
         @peer_properties  = nil
+        @peer_major       = nil
+        @peer_minor       = nil
         @qos              = qos
         @qos_hash         = qos_hash
         @mutex            = Mutex.new
@@ -70,20 +88,20 @@ module Protocol
       # @return [void]
       # @raise [Error] on handshake failure
       def handshake!
-        result = @mechanism.handshake!(
-          @io,
+        result = @mechanism.handshake! @io,
           as_server:   @as_server,
           socket_type: @socket_type,
           identity:    @identity,
           qos:         @qos,
-          qos_hash:    @qos_hash,
-        )
+          qos_hash:    @qos_hash
 
         @peer_socket_type = result[:peer_socket_type]
         @peer_identity    = result[:peer_identity]
         @peer_qos         = result[:peer_qos] || 0
         @peer_qos_hash    = result[:peer_qos_hash] || ""
         @peer_properties  = result[:peer_properties]
+        @peer_major       = result[:peer_major]
+        @peer_minor       = result[:peer_minor]
 
         unless @peer_socket_type
           raise Error, "peer READY missing Socket-Type"
@@ -187,15 +205,19 @@ module Protocol
       # @raise [EOFError] if connection is closed
       def receive_message
         frames = []
+
         loop do
           frame = read_frame
+
           if frame.command?
             yield frame if block_given?
             next
           end
+
           frames << frame.body.freeze
           break unless frame.more?
         end
+
         frames.freeze
       end
 
@@ -233,6 +255,7 @@ module Protocol
             close
             raise
           end
+
           touch_heartbeat
 
           frame = @mechanism.decrypt(frame) if @mechanism.encrypted?
@@ -248,6 +271,7 @@ module Protocol
               next
             end
           end
+
           return frame
         end
       end
@@ -315,9 +339,11 @@ module Protocol
         last      = parts.size - 1
 
         i = 0
+
         while i < parts.size
           part = parts[i]
           more = i < last
+
           if encrypted
             body = part.encoding == Encoding::BINARY ? part : part.b
             @io.write(@mechanism.encrypt(body, more: more))
@@ -325,18 +351,23 @@ module Protocol
             body  = part.encoding == Encoding::BINARY ? part : part.b
             size  = body.bytesize
             flags = more ? Codec::Frame::FLAGS_MORE : 0
+
             buf.clear
+
             if size > Codec::Frame::SHORT_MAX
               [flags | Codec::Frame::FLAGS_LONG, size].pack("CQ>", buffer: buf)
             else
               [flags, size].pack("CC", buffer: buf)
             end
+
             @io.write(buf)
             @io.write(body)
           end
+
           i += 1
         end
       end
+
     end
   end
 end

data/lib/protocol/zmtp/mechanism/curve.rb

@@ -233,10 +233,12 @@ module Protocol
 
           io.write(Codec::Greeting.encode(mechanism: MECHANISM_NAME, as_server: false))
           io.flush
-          peer_greeting = Codec::Greeting.decode(io.read_exactly(Codec::Greeting::SIZE))
+          peer_greeting = Codec::Greeting.read_from(io)
           unless peer_greeting[:mechanism] == MECHANISM_NAME
             raise Error, "expected CURVE mechanism, got #{peer_greeting[:mechanism]}"
           end
+          @peer_major = peer_greeting[:major]
+          @peer_minor = peer_greeting[:minor]
 
 
           # --- HELLO ---
@@ -348,6 +350,8 @@ module Protocol
             peer_qos:         peer_qos,
             peer_qos_hash:    peer_qos_hash,
             peer_properties:  props,
+            peer_major:       @peer_major,
+            peer_minor:       @peer_minor,
           }
         end
 
@@ -359,10 +363,12 @@ module Protocol
         def server_handshake!(io, socket_type:, identity:, qos: 0, qos_hash: "")
           io.write(Codec::Greeting.encode(mechanism: MECHANISM_NAME, as_server: true))
           io.flush
-          peer_greeting = Codec::Greeting.decode(io.read_exactly(Codec::Greeting::SIZE))
+          peer_greeting = Codec::Greeting.read_from(io)
           unless peer_greeting[:mechanism] == MECHANISM_NAME
             raise Error, "expected CURVE mechanism, got #{peer_greeting[:mechanism]}"
           end
+          @peer_major = peer_greeting[:major]
+          @peer_minor = peer_greeting[:minor]
 
 
           # --- Read HELLO ---
@@ -514,6 +520,8 @@ module Protocol
             peer_qos:         (props["X-QoS"] || "0").to_i,
             peer_qos_hash:    props["X-QoS-Hash"] || "",
             peer_properties:  props,
+            peer_major:       @peer_major,
+            peer_minor:       @peer_minor,
           }
         end
 

data/lib/protocol/zmtp/mechanism/null.rb

@@ -32,14 +32,13 @@ module Protocol
         # @param as_server [Boolean]
         # @param socket_type [String]
         # @param identity [String]
-        # @return [Hash] { peer_socket_type:, peer_identity:, peer_qos:, peer_qos_hash:, peer_properties: }
+        # @return [Hash] { peer_socket_type:, peer_identity:, peer_qos:, peer_qos_hash:, peer_properties:, peer_major:, peer_minor: }
         # @raise [Error]
         def handshake!(io, as_server:, socket_type:, identity:, qos: 0, qos_hash: "")
           io.write(Codec::Greeting.encode(mechanism: MECHANISM_NAME, as_server: as_server))
           io.flush
 
-          greeting_data = io.read_exactly(Codec::Greeting::SIZE)
-          peer_greeting = Codec::Greeting.decode(greeting_data)
+          peer_greeting = Codec::Greeting.read_from(io)
 
           unless peer_greeting[:mechanism] == MECHANISM_NAME
             raise Error, "unsupported mechanism: #{peer_greeting[:mechanism]}"
@@ -81,6 +80,8 @@ module Protocol
             peer_qos:         peer_qos,
             peer_qos_hash:    peer_qos_hash,
             peer_properties:  props,
+            peer_major:       peer_greeting[:major],
+            peer_minor:       peer_greeting[:minor],
           }
         end
 

data/lib/protocol/zmtp/mechanism/plain.rb

@@ -47,8 +47,7 @@ module Protocol
           io.write(Codec::Greeting.encode(mechanism: MECHANISM_NAME, as_server: as_server))
           io.flush
 
-          greeting_data = io.read_exactly(Codec::Greeting::SIZE)
-          peer_greeting = Codec::Greeting.decode(greeting_data)
+          peer_greeting = Codec::Greeting.read_from(io)
 
           unless peer_greeting[:mechanism] == MECHANISM_NAME
             raise Error, "unsupported mechanism: #{peer_greeting[:mechanism]}"

data/lib/protocol/zmtp/version.rb

@@ -2,6 +2,6 @@
 
 module Protocol
   module ZMTP
-    VERSION = "0.7.1"
+    VERSION = "0.8.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-zmtp
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.8.1
 platform: ruby
 authors:
 - Patrik Wenger
@@ -25,6 +25,7 @@ files:
 - lib/protocol/zmtp/codec/command.rb
 - lib/protocol/zmtp/codec/frame.rb
 - lib/protocol/zmtp/codec/greeting.rb
+- lib/protocol/zmtp/codec/subscription.rb
 - lib/protocol/zmtp/connection.rb
 - lib/protocol/zmtp/error.rb
 - lib/protocol/zmtp/mechanism/curve.rb