omq-rfc-clientserver 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: edfb06638148a82d92d092597322eecb30579a4ed9b89c8bfefdaa27517b14e0
+  data.tar.gz: 37576d85bc15c93d9c5d2afc8d77ea667c71dadfcfda1939f389046f75c08483
+SHA512:
+  metadata.gz: 7c9782da703f80dbec0bb6a502057995af1a69569b2996406ed2108c5be1feb6cfe6fa86ddfc48e59ba9a595c04ec478a215aa2bcc8ad73209634231cf2adc73
+  data.tar.gz: c914053a277da5aba36981fedd821b5830fdb4b03a338c0cf2e033d0f515c8abe007d9f13d9d596d28097397879d8449d654a17484cdd1268f07609132abdd4d

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::CLIENT and OMQ::SERVER
+
+[![CI](https://github.com/paddor/omq-rfc-clientserver/actions/workflows/ci.yml/badge.svg)](https://github.com/paddor/omq-rfc-clientserver/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/omq-rfc-clientserver?color=e9573f)](https://rubygems.org/gems/omq-rfc-clientserver)
+[![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)
+
+CLIENT and SERVER socket types ([RFC 41](https://rfc.zeromq.org/spec/41/))
+for [OMQ](https://github.com/paddor/omq).
+
+Single-frame, asynchronous request-reply. SERVER routes by 4-byte
+connection ID; CLIENT round-robins.
+
+## Usage
+
+```ruby
+require "omq"
+require "omq/rfc/clientserver"
+
+server = OMQ::SERVER.bind("tcp://127.0.0.1:5555")
+client = OMQ::CLIENT.connect("tcp://127.0.0.1:5555")
+
+client << "hello"
+msg, routing_id = server.receive_with_routing_id
+server.send_to(routing_id, msg.upcase)
+reply = client.receive  # => "HELLO"
+```
+
+## Installation
+
+```ruby
+gem "omq-rfc-clientserver"
+```
+
+Requires `omq >= 0.12`.
+
+## License
+
+[ISC](LICENSE)

data/lib/omq/client_server.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module OMQ
+  # Asynchronous client socket for the CLIENT/SERVER pattern (ZeroMQ RFC 41).
+  #
+  # Round-robins outgoing messages across connected SERVER peers.
+  class CLIENT < Socket
+    include Readable
+    include Writable
+    include SingleFrame
+
+    # Creates a new CLIENT 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(:CLIENT, linger: linger, backend: backend)
+      _attach(endpoints, default: :connect)
+    end
+  end
+
+
+  # Asynchronous server socket for the CLIENT/SERVER pattern (ZeroMQ RFC 41).
+  #
+  # Assigns a 4-byte routing ID to each connected CLIENT and supports
+  # directed replies via #send_to.
+  class SERVER < Socket
+    include Readable
+    include Writable
+    include SingleFrame
+
+    # Creates a new SERVER socket.
+    #
+    # @param endpoints [String, Array<String>, nil] endpoint(s) to bind 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(:SERVER, linger: linger, backend: backend)
+      _attach(endpoints, default: :bind)
+    end
+
+
+    # Sends a message to a specific peer by routing ID.
+    #
+    # @param routing_id [String] 4-byte routing ID
+    # @param message [String] message body
+    # @return [self]
+    #
+    def send_to(routing_id, message)
+      parts = [routing_id.b.freeze, message.b.freeze]
+      with_timeout(@options.write_timeout) { @engine.enqueue_send(parts) }
+      self
+    end
+  end
+end

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

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module OMQ
+  module RFC
+    # CLIENT/SERVER socket types extension (ZeroMQ RFC 41).
+    module ClientServer
+      VERSION = "0.1.0"
+    end
+  end
+end

data/lib/omq/rfc/clientserver.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# OMQ CLIENT/SERVER socket types (ZeroMQ RFC 41).
+#
+# Usage:
+#   require "omq/rfc/clientserver"
+#
+#   server = OMQ::SERVER.bind("tcp://127.0.0.1:5555")
+#   client = OMQ::CLIENT.connect("tcp://127.0.0.1:5555")
+
+require "omq"
+
+require_relative "clientserver/version"
+require_relative "../single_frame"
+require_relative "../routing/client"
+require_relative "../routing/server"
+require_relative "../client_server"
+
+OMQ::Routing.register(:CLIENT, OMQ::Routing::Client)
+OMQ::Routing.register(:SERVER, OMQ::Routing::Server)

data/lib/omq/routing/client.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module OMQ
+  module Routing
+    # CLIENT socket routing: round-robin send, fair-queue receive.
+    #
+    # Same as DEALER — no envelope manipulation.
+    #
+    class Client
+      include RoundRobin
+      include FairRecv
+
+      # @param engine [Engine]
+      #
+      def initialize(engine)
+        @engine     = engine
+        @recv_queue = FairQueue.new
+        @tasks      = []
+        init_round_robin(engine)
+      end
+
+
+      # @return [FairQueue]
+      #
+      attr_reader :recv_queue
+
+      # @param connection [Connection]
+      #
+      def connection_added(connection)
+        @connections << connection
+        add_fair_recv_connection(connection)
+        add_round_robin_send_connection(connection)
+      end
+
+
+      # @param connection [Connection]
+      #
+      def connection_removed(connection)
+        @connections.delete(connection)
+        @recv_queue.remove_queue(connection)
+        remove_round_robin_send_connection(connection)
+      end
+
+
+      # @param parts [Array<String>]
+      #
+      def enqueue(parts)
+        enqueue_round_robin(parts)
+      end
+
+
+      # Stops all background tasks.
+      def stop
+        @tasks.each(&:stop)
+        @tasks.clear
+      end
+    end
+  end
+end

data/lib/omq/routing/server.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module OMQ
+  module Routing
+    # SERVER socket routing: identity-based routing with auto-generated
+    # 4-byte routing IDs.
+    #
+    # Prepends routing ID on receive. Strips routing ID on send and
+    # routes to the identified connection.
+    #
+    class Server
+      include FairRecv
+
+      # @param engine [Engine]
+      #
+      def initialize(engine)
+        @engine                     = engine
+        @recv_queue                 = FairQueue.new
+        @connections_by_routing_id  = {}
+        @routing_id_by_connection   = {}
+        @conn_queues                = {}
+        @conn_send_tasks            = {}
+        @tasks                      = []
+      end
+
+
+      # @return [FairQueue]
+      #
+      attr_reader :recv_queue
+
+      # @param connection [Connection]
+      #
+      def connection_added(connection)
+        routing_id = SecureRandom.bytes(4)
+        @connections_by_routing_id[routing_id] = connection
+        @routing_id_by_connection[connection]  = routing_id
+
+        add_fair_recv_connection(connection) { |msg| [routing_id, *msg] }
+
+        q = Routing.build_queue(@engine.options.send_hwm, :block)
+        @conn_queues[connection] = q
+        @conn_send_tasks[connection] = ConnSendPump.start(@engine, connection, q, @tasks)
+      end
+
+
+      # @param connection [Connection]
+      #
+      def connection_removed(connection)
+        routing_id = @routing_id_by_connection.delete(connection)
+        @connections_by_routing_id.delete(routing_id) if routing_id
+        @recv_queue.remove_queue(connection)
+        @conn_queues.delete(connection)
+        @conn_send_tasks.delete(connection)&.stop
+      end
+
+
+      # @param parts [Array<String>]
+      #
+      def enqueue(parts)
+        routing_id = parts.first
+        conn = @connections_by_routing_id[routing_id]
+        return unless conn
+        @conn_queues[conn]&.enqueue(parts[1..])
+      end
+
+
+      # Stops all background tasks (send pumps).
+      def stop
+        @tasks.each(&:stop)
+        @tasks.clear
+      end
+
+
+      # True when all per-connection send queues are empty.
+      #
+      def send_queues_drained?
+        @conn_queues.values.all?(&:empty?)
+      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,63 @@
+--- !ruby/object:Gem::Specification
+name: omq-rfc-clientserver
+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: CLIENT and SERVER socket types implementing ZeroMQ RFC 41 for the OMQ
+  pure-Ruby ZeroMQ library.
+email:
+- paddor@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/omq/client_server.rb
+- lib/omq/rfc/clientserver.rb
+- lib/omq/rfc/clientserver/version.rb
+- lib/omq/routing/client.rb
+- lib/omq/routing/server.rb
+- lib/omq/single_frame.rb
+homepage: https://github.com/paddor/omq-rfc41-clientserver
+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 CLIENT/SERVER socket types (RFC 41) for OMQ
+test_files: []