omq-rfc-channel 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2bba37b4550d6b127e512a6eb255418b0fc5282cba216370534ebfc94fb89e84
+  data.tar.gz: d9767604d3992503b74cacadad5d92db8aefa5e303fd7e4d03d557830efa071b
+SHA512:
+  metadata.gz: ae4d13e17a6ee142da473fa81ad50b30503eeb28a67983eeb92020699948bca3178070ee0deeecb1aacbac538c3578b283bcf39e2a7055da237ca6d55da4b0c7
+  data.tar.gz: c03817cbd7cdc8cefb9c1e15e3e46a1c230c425a73678c67ce41b9c5e2100492860dbb81a1c75431093e05a4c26fc9ea2887b8134c0540794627cfa747b702b6

data/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025-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,39 @@
+# OMQ::CHANNEL
+
+[![CI](https://github.com/paddor/omq-rfc-channel/actions/workflows/ci.yml/badge.svg)](https://github.com/paddor/omq-rfc-channel/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/omq-rfc-channel?color=e9573f)](https://rubygems.org/gems/omq-rfc-channel)
+[![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)
+
+CHANNEL socket type ([RFC 52](https://rfc.zeromq.org/spec/52/)) for
+[OMQ](https://github.com/paddor/omq).
+
+Single-frame, bidirectional, exclusive pair. Like PAIR but restricted to
+single-frame messages (draft socket).
+
+## Usage
+
+```ruby
+require "omq"
+require "omq/rfc/channel"
+
+ch1 = OMQ::CHANNEL.bind("tcp://127.0.0.1:5555")
+ch2 = OMQ::CHANNEL.connect("tcp://127.0.0.1:5555")
+
+ch1 << "ping"
+ch2.receive  # => "ping"
+ch2 << "pong"
+ch1.receive  # => "pong"
+```
+
+## Installation
+
+```ruby
+gem "omq-rfc-channel"
+```
+
+Requires `omq >= 0.12`.
+
+## License
+
+[ISC](LICENSE)

data/lib/omq/channel.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module OMQ
+  # Exclusive 1-to-1 bidirectional socket (ZeroMQ RFC 52).
+  #
+  # Allows exactly one peer connection. Both sides can send and receive.
+  class CHANNEL < Socket
+    include Readable
+    include Writable
+    include SingleFrame
+
+    # Creates a new CHANNEL socket.
+    #
+    # @param endpoints [String, Array<String>, nil] endpoint(s) to connect to
+    # @param linger [Integer] linger period in milliseconds
+    # @param backend [Object, nil] optional transport backend
+    def initialize(endpoints = nil, linger: 0, backend: nil)
+      _init_engine(:CHANNEL, linger: linger, backend: backend)
+      _attach(endpoints, default: :connect)
+    end
+  end
+end

data/lib/omq/rfc/channel/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module OMQ
+  module RFC
+    # CHANNEL socket type extension (ZeroMQ RFC 52).
+    module Channel
+      VERSION = "0.1.0"
+    end
+  end
+end

data/lib/omq/rfc/channel.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# OMQ CHANNEL socket type (ZeroMQ RFC 52).
+#
+# Usage:
+#   require "omq/rfc/channel"
+#
+#   a = OMQ::CHANNEL.bind("tcp://127.0.0.1:5555")
+#   b = OMQ::CHANNEL.connect("tcp://127.0.0.1:5555")
+
+require "omq"
+
+require_relative "channel/version"
+require_relative "../single_frame"
+require_relative "../routing/channel"
+require_relative "../channel"
+
+OMQ::Routing.register(:CHANNEL, OMQ::Routing::Channel)

data/lib/omq/routing/channel.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module OMQ
+  module Routing
+    # CHANNEL socket routing: exclusive 1-to-1 bidirectional.
+    #
+    class Channel
+      include FairRecv
+
+      # @param engine [Engine]
+      #
+      def initialize(engine)
+        @engine         = engine
+        @connection     = nil
+        @recv_queue     = FairQueue.new
+        @send_queue     = nil
+        @staging_queue  = Routing.build_queue(@engine.options.send_hwm, :block)
+        @send_pump      = nil
+        @tasks          = []
+      end
+
+
+      # @return [FairQueue]
+      #
+      attr_reader :recv_queue
+
+      # @param connection [Connection]
+      # @raise [RuntimeError] if a connection already exists
+      #
+      def connection_added(connection)
+        raise "CHANNEL allows only one peer" if @connection
+        @connection = connection
+
+        add_fair_recv_connection(connection)
+
+        unless connection.is_a?(Transport::Inproc::DirectPipe)
+          @send_queue = Routing.build_queue(@engine.options.send_hwm, :block)
+          while (msg = @staging_queue.dequeue(timeout: 0))
+            @send_queue.enqueue(msg)
+          end
+          start_send_pump(connection)
+        end
+      end
+
+
+      # @param connection [Connection]
+      #
+      def connection_removed(connection)
+        if @connection == connection
+          @connection = nil
+          @recv_queue.remove_queue(connection)
+          @send_queue = nil
+          @send_pump&.stop
+          @send_pump = nil
+        end
+      end
+
+
+      # @param parts [Array<String>]
+      #
+      def enqueue(parts)
+        conn = @connection
+        if conn.is_a?(Transport::Inproc::DirectPipe) && conn.direct_recv_queue
+          conn.send_message(parts)
+        elsif @send_queue
+          @send_queue.enqueue(parts)
+        else
+          @staging_queue.enqueue(parts)
+        end
+      end
+
+
+      # Stops all background tasks (send pumps).
+      def stop
+        @tasks.each(&:stop)
+        @tasks.clear
+      end
+
+
+      # True when the staging and send queues are empty.
+      #
+      def send_queues_drained?
+        @staging_queue.empty? && (@send_queue.nil? || @send_queue.empty?)
+      end
+
+      private
+
+      def start_send_pump(conn)
+        @send_pump = @engine.spawn_pump_task(annotation: "send pump") do
+          loop do
+            batch = [@send_queue.dequeue]
+            Routing.drain_send_queue(@send_queue, batch)
+            begin
+              batch.each { |parts| conn.write_message(parts) }
+              conn.flush
+            rescue Protocol::ZMTP::Error, *CONNECTION_LOST
+              @engine.connection_lost(conn)
+              break
+            end
+          end
+        end
+        @tasks << @send_pump
+      end
+    end
+  end
+end

data/lib/omq/single_frame.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module OMQ
+  # Mixin that rejects multipart messages.
+  #
+  # All draft socket types (CLIENT, SERVER, RADIO, DISH, SCATTER,
+  # GATHER, PEER, CHANNEL) require single-frame messages for
+  # thread-safe atomic operations.
+  #
+  module SingleFrame
+    # Sends a message, rejecting multipart messages.
+    #
+    # @param message [String, Array<String>] message to send (must be single-frame)
+    # @raise [ArgumentError] if a multipart message is provided
+    # @return [void]
+    def send(message)
+      if message.is_a?(Array) && message.size > 1
+        raise ArgumentError, "#{self.class} does not support multipart messages"
+      end
+      super
+    end
+  end
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: omq-rfc-channel
+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:
+- !ruby/object:Gem::Dependency
+  name: omq
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.12'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.12'
+description: CHANNEL socket type implementing ZeroMQ RFC 52 for the OMQ pure-Ruby
+  ZeroMQ library.
+email:
+- paddor@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/omq/channel.rb
+- lib/omq/rfc/channel.rb
+- lib/omq/rfc/channel/version.rb
+- lib/omq/routing/channel.rb
+- lib/omq/single_frame.rb
+homepage: https://github.com/paddor/omq-rfc-channel
+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: ZMQ CHANNEL socket type (RFC 52) for OMQ
+test_files: []