omq-rfc-zstd 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 141f24afe8fac939ca1518c76d62bc45d8d15d456fa415be3c8dc5343af33447
-  data.tar.gz: 2e16e4ce5413d0b181e2b293d8b9b5203133bb114527726936c466464754e8dd
+  metadata.gz: b2d6625572903ff642e267adb23e6a654eb791a8badb614dcbdf1fdcd90698d6
+  data.tar.gz: 5dc1db0f6a9e4622496df5759af9e2d409a0e002f4dd554cb41ed376774370b8
 SHA512:
-  metadata.gz: d181d5b3e6c463537599491667287603479d3928b9d2f4991e7c4e48b1ded8e15a730e3a825a059cdf384ded81b5f83e094093d9424341126e103ab3049a3723
-  data.tar.gz: efd7e9cb3caa37d11ed5cdb6ec374f3f85efd32ce2cfc0525552840d9dce92a0460302e8a315d73ae4b7a5bf34ce597296cf1f60a2d0083e750887635bf633f6
+  metadata.gz: be57dd892580e4173561769f624e3aa21759b8d42309f0aecd0c1a64c0abf5ae725718e66589938549a43c8df7664c4bb0fd4c2c7c7d6a643c4591139eeba0c5
+  data.tar.gz: 20998b4e1ff50da873096ee0c4c9b95fe5f144b42f01af0bffb40c00034ed2732862885c12837fb9fbf7674de5214db48787c7a75880743ab835adac36581e39

data/README.md

@@ -20,7 +20,7 @@ See [RFC.md](RFC.md) for the full specification.
 - **Backwards compatible**: a peer that does not advertise compression is served plaintext. libzmq and other ZMTP 3.1 peers remain interoperable.
 - **Small-message friendly**: an optional shared dictionary makes compression useful even for messages in the dozens-to-hundreds-of-bytes range. Without a dictionary, the sender skips compression for frames below 512 B.
 - **Pay-per-frame**: the sender MAY skip compression on a per-frame basis. Short or incompressible frames are sent plaintext.
-- **Zero-config option**: `dict:auto` trains a dictionary from the first 1000 messages (or 100 KiB, whichever hits first) and ships it via the `DICT` command frame.
+- **Zero-config option**: `dict:auto` trains a dictionary from the first 1000 messages (or 100 KiB, whichever hits first) and ships it via the `ZDICT` command frame.
 
 ## Non-goals
 
@@ -38,18 +38,18 @@ require "omq/rfc/zstd"
 
 # 1. No dictionary — opportunistic compression for frames ≥ 512 B
 push = OMQ::PUSH.new
-push.compression = OMQ::RFC::Zstd::Compression.none
+push.compression = OMQ::Compression::Zstd.none
 push.connect("tcp://127.0.0.1:5555")
 
 # 2. Caller-supplied dictionary, agreed out of band
 dict = File.binread("schema.dict")
-push.compression = OMQ::RFC::Zstd::Compression.with_dictionary(dict)
+push.compression = OMQ::Compression::Zstd.with_dictionary(dict)
 
 # 3. Caller-supplied dictionary, sent over the wire once via DICT command
-push.compression = OMQ::RFC::Zstd::Compression.with_dictionary(dict, inline: true)
+push.compression = OMQ::Compression::Zstd.with_dictionary(dict, inline: true)
 
 # 4. Auto-trained dictionary — zero config
-push.compression = OMQ::RFC::Zstd::Compression.auto
+push.compression = OMQ::Compression::Zstd.auto
 ```
 
 The default level is **3**. Pass `level:` to override (negative levels enable

data/lib/omq/{rfc → compression}/zstd/codec.rb

@@ -4,7 +4,7 @@ require "rzstd"
 require_relative "constants"
 
 module OMQ
-  module RFC
+  module Compression
     module Zstd
       # Pure-function frame-body codec. Implements the sender/receiver rules
       # from RFC sections 6.4 and 6.5. Stateless: all state (dictionary,
@@ -18,7 +18,7 @@ module OMQ
         # message-frame body.
         #
         # @param plaintext [String] frame payload as supplied by the user
-        # @param compression [OMQ::RFC::Zstd::Compression] the negotiated
+        # @param compression [OMQ::Compression::Zstd::Compression] the negotiated
         #   send-direction compression object, or nil if no profile is active
         # @return [String] frame body bytes (always binary)
         def encode_part(plaintext, compression)
@@ -51,7 +51,7 @@ module OMQ
         # or raises before any decoder allocation.
         #
         # @param body [String] wire frame body bytes
-        # @param compression [OMQ::RFC::Zstd::Compression] the negotiated
+        # @param compression [OMQ::Compression::Zstd::Compression] the negotiated
         #   recv-direction compression object, or nil if no profile is active
         # @param budget_remaining [Integer, nil] remaining decompressed-byte
         #   budget for this multipart message; nil disables the cap
@@ -89,9 +89,11 @@ module OMQ
         def enforce_budget!(size, budget_remaining)
           return if budget_remaining.nil?
           return if size <= budget_remaining
+
           raise DecompressedSizeExceedsMaxError,
-                "ZMTP-Zstd: decompressed message size exceeds maximum"
+            "ZMTP-Zstd: decompressed message size exceeds maximum"
         end
+
       end
     end
   end

data/lib/omq/{rfc/zstd/compression.rb → compression/zstd/compressor.rb}

@@ -7,10 +7,29 @@ require_relative "constants"
 require "thread"
 
 module OMQ
-  module RFC
+  module Compression
     module Zstd
+
+      def self.none(level: DEFAULT_LEVEL, passive: false)
+        Compressor.new mode: :none, dictionary: nil, level: level, passive: passive
+      end
+
+
+      def self.with_dictionary(bytes, inline: false, level: DEFAULT_LEVEL, passive: false)
+        Compressor.new mode: inline ? :dict_inline : :dict_static,
+          dictionary: bytes,
+          level:      level,
+          passive:    passive
+      end
+
+
+      def self.auto(level: DEFAULT_LEVEL, passive: false)
+        Compressor.new mode: :dict_auto, dictionary: nil, level: level, passive: passive
+      end
+
+
       # User-facing configuration object. Assigned to an OMQ socket via
-      # `socket.compression = OMQ::RFC::Zstd::Compression.new(...)`.
+      # `socket.compression = OMQ::Compression::Zstd.none/auto/with_dictionary(...)`.
       # Encapsulates the negotiated profile, the dictionaries (per
       # direction), the compression level, and the cached SHA-1 hash
       # used in the READY property.
@@ -38,25 +57,9 @@ module OMQ
       #                 (whichever comes first), installs it into the send
       #                 slot, and ships it via ZDICT. The recv slot is
       #                 populated when the peer's ZDICT arrives.
-      class Compression
+      class Compressor
         attr_reader :sentinel, :profile, :level, :mode, :send_dict_bytes
 
-        def self.none(level: DEFAULT_LEVEL, passive: false)
-          new(mode: :none, dictionary: nil, level: level, passive: passive)
-        end
-
-        def self.with_dictionary(bytes, inline: false, level: DEFAULT_LEVEL, passive: false)
-          new(
-            mode: inline ? :dict_inline : :dict_static,
-            dictionary: bytes,
-            level: level,
-            passive: passive,
-          )
-        end
-
-        def self.auto(level: DEFAULT_LEVEL, passive: false)
-          new(mode: :dict_auto, dictionary: nil, level: level, passive: passive)
-        end
 
         # When +passive: true+, the socket advertises the profile and
         # decodes incoming compressed frames, but never compresses
@@ -99,14 +102,17 @@ module OMQ
           end
         end
 
+
         def has_send_dictionary?
           !@send_dictionary.nil?
         end
 
+
         def has_recv_dictionary?
           !@recv_dictionary.nil?
         end
 
+
         # True if this side was configured as a passive sender
         # (RFC Sec. 6.4 "Passive senders"): advertise the profile and
         # decompress incoming frames, but never compress outgoing
@@ -117,11 +123,13 @@ module OMQ
           @passive == true
         end
 
+
         def min_compress_bytes
           return Float::INFINITY if passive?
           has_send_dictionary? ? MIN_COMPRESS_BYTES_DICT : MIN_COMPRESS_BYTES_NO_DICT
         end
 
+
         def compress(plaintext)
           if @send_dictionary
             @send_dictionary.compress(plaintext)
@@ -130,6 +138,7 @@ module OMQ
           end
         end
 
+
         # Bounded single-shot decompression. The `max_output_size:` cap is
         # enforced inside the Rust extension: the frame's Frame_Content_Size
         # header is read first, and MissingContentSizeError /
@@ -143,6 +152,7 @@ module OMQ
           end
         end
 
+
         # Match this compression's advertised profile against a peer's
         # X-Compression property value (comma-separated profile list).
         # Returns the matched profile string, or nil for no match.
@@ -152,6 +162,7 @@ module OMQ
           peer_profiles.include?(@profile) ? @profile : nil
         end
 
+
         # Install a dictionary into the send slot. Used internally by
         # auto-mode after training: the trained dict is installed here
         # and the bytes stashed for shipping via ZDICT.
@@ -160,8 +171,9 @@ module OMQ
           @send_dictionary = RZstd::Dictionary.new(@send_dict_bytes, level: @level)
         end
 
+
         # Install a dictionary into the recv slot. Called by the
-        # CompressionConnection wrapper when a ZDICT command frame
+        # Connection wrapper when a ZDICT command frame
         # arrives from the peer.
         def install_recv_dictionary(bytes)
           @recv_dictionary = RZstd::Dictionary.new(bytes.b, level: @level)
@@ -214,8 +226,10 @@ module OMQ
           end
         end
 
+
         private
 
+
         def maybe_train!
           return unless @samples_count >= AUTO_DICT_SAMPLE_COUNT ||
                         @samples_bytes >= AUTO_DICT_SAMPLE_BYTES
@@ -232,6 +246,7 @@ module OMQ
             @samples       = nil
           end
         end
+
       end
     end
   end

data/lib/omq/{rfc → compression}/zstd/connection.rb

@@ -6,8 +6,9 @@ require_relative "codec"
 require_relative "constants"
 
 module OMQ
-  module RFC
+  module Compression
     module Zstd
+
       # Wraps a Protocol::ZMTP::Connection to transparently apply the
       # ZMTP-Zstd sender/receiver rules (RFC sections 6.4 and 6.5) at
       # the frame-body level.
@@ -25,7 +26,9 @@ module OMQ
       # different profile or dictionary), so the fan-out optimization
       # in +OMQ::Routing::FanOut+ falls back to per-connection
       # +write_message+.
-      class CompressionConnection < SimpleDelegator
+      #
+      class Connection < SimpleDelegator
+
         # Mixed-in so +is_a?+ against Protocol::ZMTP::Connection still
         # matches the wrapped instance.
         module TransparentDelegator
@@ -35,12 +38,14 @@ module OMQ
           alias_method :kind_of?, :is_a?
         end
 
+
         include TransparentDelegator
 
+
         # @param conn [Protocol::ZMTP::Connection] underlying connection
-        # @param send_compression [OMQ::RFC::Zstd::Compression, nil]
+        # @param send_compression [OMQ::Compression::Zstd::Compressor, nil]
         #   compression object used on outgoing parts; nil = no-op
-        # @param recv_compression [OMQ::RFC::Zstd::Compression, nil]
+        # @param recv_compression [OMQ::Compression::Zstd::Compressor, nil]
         #   compression object used on incoming parts; nil = no-op
         # @param max_message_size [Integer, nil]
         def initialize(conn, send_compression:, recv_compression:, max_message_size: nil, engine: nil)
@@ -56,7 +61,7 @@ module OMQ
           # Cached once: is the send side an auto-training compression
           # that still needs samples? Flipped false the moment training
           # completes, so #encode_parts drops the per-message branch.
-          @auto_sampling = send_compression.is_a?(Compression) && send_compression.auto?
+          @auto_sampling = send_compression.is_a?(Compressor) && send_compression.auto?
         end
 
 
@@ -120,20 +125,27 @@ module OMQ
         end
 
 
-        # Sends the DICT command frame if the send-side compression has
+        # Sends the ZDICT command frame if the send-side compression has
         # an inline dictionary to ship. Called by EngineExt right after
         # the wrapper is constructed, before the recv pump starts.
         def send_initial_dict!
           return if @dict_sent
           return unless @send_compression
+
           # RFC Sec. 6.4: a passive sender MUST NOT emit a ZDICT frame.
-          return if @send_compression.respond_to?(:passive?) && @send_compression.passive?
+          if @send_compression.respond_to?(:passive?) && @send_compression.passive?
+            return
+          end
+
           bytes = @send_compression.send_dict_bytes
           return unless bytes
+
           if bytes.bytesize > DICT_FRAME_MAX_SIZE
             raise Error, "ZMTP-Zstd: dictionary exceeds DICT_FRAME_MAX_SIZE (#{bytes.bytesize} > #{DICT_FRAME_MAX_SIZE})"
           end
+
           __getobj__.send_command(Protocol::ZMTP::Codec::Command.new("ZDICT", bytes))
+
           @dict_sent = true
           @engine&.emit_verbose_monitor_event(:zdict_sent, size: bytes.bytesize)
         end
@@ -143,6 +155,7 @@ module OMQ
 
         def handle_command_frame(frame)
           cmd = Protocol::ZMTP::Codec::Command.from_body(frame.body)
+
           case cmd.name
           when "ZDICT"
             install_received_dict(cmd.data)
@@ -152,9 +165,11 @@ module OMQ
 
         def install_received_dict(bytes)
           return unless @recv_compression
+
           if bytes.bytesize > DICT_FRAME_MAX_SIZE
             raise Error, "ZMTP-Zstd: received DICT exceeds DICT_FRAME_MAX_SIZE"
           end
+
           @recv_compression.install_recv_dictionary(bytes)
           @engine&.emit_verbose_monitor_event(:zdict_received, size: bytes.bytesize)
         end
@@ -194,6 +209,7 @@ module OMQ
             plaintext
           end
         end
+
       end
     end
   end

data/lib/omq/{rfc → compression}/zstd/constants.rb

@@ -3,7 +3,7 @@
 require "protocol/zmtp"
 
 module OMQ
-  module RFC
+  module Compression
     module Zstd
       SENTINEL_UNCOMPRESSED = "\x00\x00\x00\x00".b.freeze
       SENTINEL_ZSTD_FRAME   = "\x28\xB5\x2F\xFD".b.freeze

data/lib/omq/{rfc → compression}/zstd/engine_ext.rb

@@ -5,14 +5,16 @@ require_relative "connection"
 require_relative "constants"
 
 module OMQ
-  module RFC
+  module Compression
     module Zstd
+
       # Prepended onto OMQ::Engine to install a compression-aware
       # connection wrapper. The wrapper is installed unconditionally
       # at engine init time and inspects +options.compression+ on each
       # call -- the user typically sets +socket.compression =+ AFTER
       # the engine has been constructed, so the closure must look up
       # the compression object lazily.
+      #
       module EngineExt
         def initialize(socket_type, options)
           super
@@ -21,7 +23,7 @@ module OMQ
             next conn unless compression
             next conn unless matched_profile(conn, compression)
 
-            wrapper = CompressionConnection.new(
+            wrapper = Connection.new(
               conn,
               send_compression: compression,
               recv_compression: compression,
@@ -33,17 +35,20 @@ module OMQ
           end
         end
 
+
         private
 
+
         def matched_profile(conn, compression)
           props = conn.peer_properties
           return nil unless props
           peer_value = props[PROPERTY_NAME]
           compression.match(peer_value)
         end
+
       end
     end
   end
 end
 
-OMQ::Engine.prepend(OMQ::RFC::Zstd::EngineExt)
+OMQ::Engine.prepend(OMQ::Compression::Zstd::EngineExt)

data/lib/omq/{rfc → compression}/zstd/options_ext.rb

@@ -4,15 +4,20 @@ require "omq"
 require_relative "constants"
 
 module OMQ
-  module RFC
+  module Compression
     module Zstd
+
       # Prepended onto OMQ::Options to add a +compression+ attribute.
-      # Mirrors the pattern used by omq-transport-tls for +tls_context+.
       #
       # Setting +compression+ also publishes the profile string on the
       # mechanism's metadata so the ZMTP READY command advertises
       # +X-Compression+ to the peer during handshake.
+      #
       module OptionsExt
+
+        attr_reader :compression
+
+
         def initialize(**kwargs)
           super
           @compression = nil
@@ -33,11 +38,9 @@ module OMQ
           mech.metadata[PROPERTY_NAME] = value.profile
         end
 
-
-        attr_reader :compression
       end
     end
   end
 end
 
-OMQ::Options.prepend(OMQ::RFC::Zstd::OptionsExt)
+OMQ::Options.prepend(OMQ::Compression::Zstd::OptionsExt)

data/lib/omq/{rfc → compression}/zstd/version.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 module OMQ
-  module RFC
+  module Compression
     module Zstd
-      VERSION = "0.1.2"
+      VERSION = "0.2.0"
     end
   end
 end

data/lib/omq/compression/zstd.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "zstd/version"
+require_relative "zstd/constants"
+require_relative "zstd/codec"
+require_relative "zstd/compressor"
+require_relative "zstd/options_ext"
+require_relative "zstd/socket_ext"
+require_relative "zstd/connection"
+require_relative "zstd/engine_ext"

data/lib/omq/rfc/zstd.rb

@@ -1,10 +1,3 @@
 # frozen_string_literal: true
 
-require_relative "zstd/version"
-require_relative "zstd/constants"
-require_relative "zstd/codec"
-require_relative "zstd/compression"
-require_relative "zstd/options_ext"
-require_relative "zstd/socket_ext"
-require_relative "zstd/connection"
-require_relative "zstd/engine_ext"
+require_relative "../compression/zstd"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omq-rfc-zstd
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Patrik Wenger
@@ -62,15 +62,16 @@ files:
 - LICENSE
 - README.md
 - RFC.md
+- lib/omq/compression/zstd.rb
+- lib/omq/compression/zstd/codec.rb
+- lib/omq/compression/zstd/compressor.rb
+- lib/omq/compression/zstd/connection.rb
+- lib/omq/compression/zstd/constants.rb
+- lib/omq/compression/zstd/engine_ext.rb
+- lib/omq/compression/zstd/options_ext.rb
+- lib/omq/compression/zstd/socket_ext.rb
+- lib/omq/compression/zstd/version.rb
 - lib/omq/rfc/zstd.rb
-- lib/omq/rfc/zstd/codec.rb
-- lib/omq/rfc/zstd/compression.rb
-- lib/omq/rfc/zstd/connection.rb
-- lib/omq/rfc/zstd/constants.rb
-- lib/omq/rfc/zstd/engine_ext.rb
-- lib/omq/rfc/zstd/options_ext.rb
-- lib/omq/rfc/zstd/socket_ext.rb
-- lib/omq/rfc/zstd/version.rb
 homepage: https://github.com/paddor/omq-rfc-zstd
 licenses:
 - ISC