omq-websocket 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 06c0113988693375d1e80176cc6e481dbac6146c2d2c703fe45740ee6a4f07cc
+  data.tar.gz: 756f09161db08b511cf091195ac1912ad4c4575b6fdd937e60eb0cef1ae04a28
+SHA512:
+  metadata.gz: 5ba7f7dd4c079836aa56c5ce3e7e10e116d175725ee8ec8deda03d9ab8404220e63b4a1b82384f1d09b902d84f5fc11bdf3d2c35980193a6b378d35a93e7104e
+  data.tar.gz: 7ae4da9f5b6ffd222741a4bbf16ce2cc8eeece79085fb71341acbb2bc14a1816b15a3e1923a007ef99cbcc5c57afdb7115b7847b81d224ac38c0e27a8831349d

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## Unreleased
+
+## 0.1.0 - 2026-07-23
+
+- Initial release. Adds `ws://` and `wss://` transports to OMQ
+  implementing ZeroMQ RFC 45 (ZWS 2.0). Both schemes register on
+  `require "omq/transport/websocket"`.
+- Subprotocols: `ZWS2.0` (no mechanism, identity-as-first-message)
+  and `ZWS2.0/NULL` (NULL handshake via 0x02 command frames).
+- Built on `async-websocket` for the WebSocket upgrade and
+  `async-http` for the listener.
+- ZWS framing: one ZeroMQ frame per WebSocket binary message,
+  prefixed with a single FLAG byte (0x00 last, 0x01 more, 0x02
+  command). No ZMTP/3.1 greeting.
+- `wss://` is plain TLS-then-WebSocket via an `OpenSSL::SSL::SSLContext`
+  passed through `tls_context:` on the socket.
+- Release source is now the `zeromq/omq.rb` monorepo.
+- Requires `omq ~> 0.28` and `protocol-zmtp ~> 0.10`.

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,72 @@
+# OMQ::Transport::WebSocket
+
+[![CI](https://github.com/zeromq/omq.rb/actions/workflows/ci.yml/badge.svg)](https://github.com/zeromq/omq.rb/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/omq-websocket?color=e9573f)](https://rubygems.org/gems/omq-websocket)
+[![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)
+
+ZeroMQ-over-WebSocket transport for [OMQ](https://github.com/zeromq/omq.rb).
+Implements [ZeroMQ RFC 45](https://rfc.zeromq.org/spec/45/) (ZWS 2.0).
+
+Adds `ws://` and `wss://` schemes to OMQ. Both register at
+`require` time. No other OMQ code change required.
+
+## Install
+
+```ruby
+gem "omq",           "~> 0.28"
+gem "omq-websocket", "~> 0.1"
+```
+
+## Use
+
+```ruby
+require "omq"
+require "omq/websocket"
+
+# Server
+pull = OMQ::PULL.new
+pull.bind("ws://127.0.0.1:5555")
+
+# Client
+push = OMQ::PUSH.connect("ws://127.0.0.1:5555")
+push.send("hello")
+```
+
+### TLS (`wss://`)
+
+```ruby
+ctx = OpenSSL::SSL::SSLContext.new
+ctx.cert = OpenSSL::X509::Certificate.new(File.read("cert.pem"))
+ctx.key  = OpenSSL::PKey::RSA.new(File.read("key.pem"))
+
+pull = OMQ::PULL.new
+pull.tls_context = ctx
+pull.bind("wss://127.0.0.1:5556")
+```
+
+### Mechanism
+
+By default the client offers `ZWS2.0/NULL` then `ZWS2.0`. The server
+picks the first one it accepts. Override via:
+
+```ruby
+sock.ws_subprotocols = %w[ZWS2.0]   # force no-mechanism
+```
+
+### Path
+
+Defaults to `/`. Override via `sock.ws_path = "/zeromq"`. Listener
+returns 404 for any other path.
+
+## Wire protocol
+
+Per RFC 45, each ZeroMQ frame maps to one WebSocket binary message:
+a single FLAG byte (`0x00` final, `0x01` more, `0x02` command)
+followed by the frame body. No 64-byte ZMTP greeting. Mechanism
+negotiation happens via `Sec-WebSocket-Protocol` during the HTTP
+upgrade. See `lib/omq/transport/websocket/codec.rb`.
+
+## License
+
+ISC.

data/lib/omq/transport/websocket/codec.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "protocol/zmtp"
+
+module OMQ
+  module Transport
+    module WebSocket
+      # ZWS 2.0 wire codec (RFC 45). One ZeroMQ frame per WebSocket
+      # binary message, prefixed with a single FLAG byte:
+      #
+      #   0x00  final data frame   (no MORE)
+      #   0x01  intermediate data frame (MORE)
+      #   0x02  command frame      (READY/PING/PONG/SUBSCRIBE/...)
+      #
+      # No length prefix — the WebSocket message length IS the frame
+      # length. No greeting; mechanism is negotiated via
+      # Sec-WebSocket-Protocol during the HTTP upgrade.
+      module Codec
+
+        FLAG_LAST    = 0x00
+        FLAG_MORE    = 0x01
+        FLAG_COMMAND = 0x02
+
+        EMPTY_BINARY = "".b.freeze
+
+
+        # Encodes a frame body with the appropriate FLAG byte prefix.
+        #
+        # @param body [String] frame payload (binary)
+        # @param more [Boolean] more frames follow in this message
+        # @param command [Boolean] command frame (PING/PONG/READY/...)
+        # @return [String] WS binary message bytes (BINARY encoding)
+        #
+        def self.encode(body, more: false, command: false)
+          flag    = command ? FLAG_COMMAND : (more ? FLAG_MORE : FLAG_LAST)
+          payload = body.encoding == Encoding::BINARY ? body : body.b
+          out     = String.new(capacity: payload.bytesize + 1, encoding: Encoding::BINARY)
+
+          out << flag.chr(Encoding::BINARY)
+          out << payload
+          out
+        end
+
+
+        # Decodes a WS binary message into [flag_byte, body_slice].
+        #
+        # @param bytes [String] WS binary message bytes
+        # @return [Array(Integer, String)]
+        # @raise [Protocol::ZMTP::Error] on empty message
+        #
+        def self.decode(bytes)
+          raise Protocol::ZMTP::Error, "ZWS frame is empty" if bytes.empty?
+
+          flag = bytes.getbyte(0)
+          body = bytes.byteslice(1, bytes.bytesize - 1) || EMPTY_BINARY
+          [flag, body]
+        end
+
+      end
+    end
+  end
+end

data/lib/omq/transport/websocket/connection.rb

@@ -0,0 +1,322 @@
+# frozen_string_literal: true
+
+require "protocol/zmtp"
+require "async/clock"
+
+module OMQ
+  module Transport
+    module WebSocket
+      # Quacks like Protocol::ZMTP::Connection but speaks ZWS 2.0 over
+      # an Async::WebSocket::Connection (or any object that responds to
+      # +#read+, +#send_binary+, +#flush+, +#close+, +#protocol+).
+      #
+      # The HTTP/WS upgrade is already complete by the time this is
+      # constructed — the Engine instantiates this class via
+      # OMQ::Transport::WebSocket.connection_class once
+      # +handle_accepted+ / +handle_connected+ delivers the ws_conn.
+      #
+      # No ZMTP/3.1 greeting. The mechanism (NULL or no-mechanism) is
+      # determined from the negotiated Sec-WebSocket-Protocol. Identity
+      # is exchanged either via a READY command (NULL) or as the first
+      # data message (no-mechanism), per RFC 45.
+      class Connection
+
+        attr_reader :peer_socket_type
+        attr_reader :peer_identity
+        attr_reader :peer_public_key
+        attr_reader :peer_properties
+        attr_reader :peer_major
+        attr_reader :peer_minor
+        attr_reader :last_received_at
+        attr_reader :ws
+
+
+        # @param ws [#read, #send_binary, #flush, #close, #protocol] WebSocket connection
+        # @param socket_type [String] our socket type (e.g. "REQ")
+        # @param identity [String] our identity
+        # @param as_server [Boolean] true on accepted side
+        # @param mechanism [Object, nil] ignored — ZWS uses the negotiated subprotocol instead
+        # @param max_message_size [Integer, nil] max frame body size
+        # @param opts [Hash] extra READY properties (NULL handshake only)
+        #
+        def initialize(ws, socket_type:, identity: "", as_server: false,
+                       mechanism: nil, max_message_size: nil, **opts)
+          @ws               = ws
+          @socket_type      = socket_type.to_s
+          @identity         = identity || ""
+          @as_server        = as_server
+          @max_message_size = max_message_size
+          @metadata         = opts.empty? ? nil : opts.transform_keys(&:to_s)
+
+          @peer_socket_type = nil
+          @peer_identity    = nil
+          @peer_public_key  = nil
+          @peer_properties  = nil
+
+          # Advertise ZMTP 3.1 to upper layers so SUBSCRIBE/CANCEL always
+          # go via send_command (the ZWS form per RFC 45) rather than the
+          # legacy in-band byte-prefix form.
+          @peer_major       = 3
+          @peer_minor       = 1
+
+          @last_received_at = nil
+          @mutex            = Mutex.new
+          @closed           = false
+        end
+
+
+        def encrypted?
+          false
+        end
+
+
+        def curve?
+          false
+        end
+
+
+        # Performs the ZWS 2.0 mechanism handshake. Branches on the
+        # subprotocol negotiated during the HTTP upgrade.
+        #
+        # @return [void]
+        # @raise [Protocol::ZMTP::Error] on protocol violation, unsupported
+        #   subprotocol, or incompatible peer socket type
+        #
+        def handshake!
+          case @ws.protocol
+          when "ZWS2.0/NULL"
+            handshake_null!
+            validate_peer_compatibility!
+          when "ZWS2.0", nil
+            handshake_no_mechanism!
+            # No socket-type validation possible without READY exchange.
+          else
+            raise Protocol::ZMTP::Error, "unsupported ZWS subprotocol: #{@ws.protocol.inspect}"
+          end
+        end
+
+
+        def send_message(parts)
+          @mutex.synchronize do
+            write_frames(parts)
+            @ws.flush
+          end
+        end
+
+
+        def write_message(parts)
+          @mutex.synchronize do
+            write_frames(parts)
+          end
+        end
+
+
+        def write_messages(messages)
+          @mutex.synchronize do
+            messages.each { |parts| write_frames(parts) }
+          end
+        end
+
+
+        def flush
+          @mutex.synchronize do
+            @ws.flush
+          end
+        end
+
+
+        def send_command(command)
+          @mutex.synchronize do
+            @ws.send_binary(Codec.encode(command.to_body, command: true))
+            @ws.flush
+          end
+        end
+
+
+        # Reads a multi-frame message. Auto-handles PING/PONG and yields
+        # any other command frames to the caller block (matching
+        # Protocol::ZMTP::Connection#receive_message semantics).
+        #
+        # @return [Array<String>] frame bodies
+        # @raise [EOFError] on peer close
+        #
+        def receive_message
+          frames = []
+
+          loop do
+            frame = read_frame
+
+            if frame.command?
+              yield frame if block_given?
+              next
+            end
+
+            frames << frame.body
+            break unless frame.more?
+          end
+
+          frames
+        end
+
+
+        # Reads one ZWS frame. Auto-handles PING (replies PONG) and
+        # discards PONG. Returns a Protocol::ZMTP::Codec::Frame so
+        # upstream code (Subscription.parse, fan_out subscription
+        # listeners) sees the same shape as ZMTP/3.1.
+        #
+        # @return [Protocol::ZMTP::Codec::Frame]
+        # @raise [EOFError] on peer close
+        #
+        def read_frame
+          loop do
+            message = @ws.read
+            unless message
+              close
+              raise EOFError, "ZWS connection closed"
+            end
+
+            bytes = message.buffer
+            bytes = bytes.b if bytes.encoding != Encoding::BINARY
+            flag, body = Codec.decode(bytes)
+
+            if @max_message_size && body.bytesize > @max_message_size
+              raise Protocol::ZMTP::Error,
+                    "ZWS frame exceeds max_message_size (#{body.bytesize} > #{@max_message_size})"
+            end
+
+            command = (flag & Codec::FLAG_COMMAND) != 0
+            more    = !command && (flag & Codec::FLAG_MORE) != 0
+            frame   = Protocol::ZMTP::Codec::Frame.new(body, more: more, command: command)
+
+            touch_heartbeat
+
+            if frame.command?
+              cmd = Protocol::ZMTP::Codec::Command.from_body(frame.body)
+              case cmd.name
+              when "PING"
+                _ttl, context = cmd.ping_ttl_and_context
+                send_command(Protocol::ZMTP::Codec::Command.pong(context: context))
+                next
+              when "PONG"
+                next
+              end
+            end
+
+            return frame
+          end
+        end
+
+
+        def touch_heartbeat
+          @last_received_at = Async::Clock.now
+        end
+
+
+        def heartbeat_expired?(timeout)
+          return false unless @last_received_at
+          (Async::Clock.now - @last_received_at) > timeout
+        end
+
+
+        def close
+          return if @closed
+          @closed = true
+          @ws.close
+        rescue IOError, ::Protocol::WebSocket::ClosedError
+          # already closed
+        end
+
+
+        def closed?
+          @closed
+        end
+
+
+        private
+
+
+        def write_frames(parts)
+          last = parts.size - 1
+
+          parts.each_with_index do |part, i|
+            @ws.send_binary(Codec.encode(part, more: i < last))
+          end
+        end
+
+
+        def handshake_null!
+          ready = Protocol::ZMTP::Codec::Command.ready(
+            socket_type: @socket_type,
+            identity:    @identity,
+            metadata:    @metadata,
+          )
+          send_command(ready)
+
+          frame = read_command_frame!
+          cmd   = Protocol::ZMTP::Codec::Command.from_body(frame.body)
+
+          unless cmd.name == "READY"
+            raise Protocol::ZMTP::Error, "expected READY, got #{cmd.name}"
+          end
+
+          props             = cmd.properties
+          @peer_properties  = props
+          @peer_socket_type = props["Socket-Type"]
+          @peer_identity    = props["Identity"] || Codec::EMPTY_BINARY
+
+          unless @peer_socket_type
+            raise Protocol::ZMTP::Error, "peer READY missing Socket-Type"
+          end
+        end
+
+
+        def handshake_no_mechanism!
+          @mutex.synchronize do
+            @ws.send_binary(Codec.encode(@identity || Codec::EMPTY_BINARY))
+            @ws.flush
+          end
+
+          message = @ws.read
+          unless message
+            raise Protocol::ZMTP::Error, "ZWS peer closed before sending identity"
+          end
+
+          bytes = message.buffer
+          bytes = bytes.b if bytes.encoding != Encoding::BINARY
+          _flag, body    = Codec.decode(bytes)
+          @peer_identity = body
+
+          touch_heartbeat
+        end
+
+
+        def read_command_frame!
+          loop do
+            message = @ws.read
+            unless message
+              raise Protocol::ZMTP::Error, "ZWS peer closed during handshake"
+            end
+
+            bytes = message.buffer
+            bytes = bytes.b if bytes.encoding != Encoding::BINARY
+            flag, body = Codec.decode(bytes)
+
+            next if (flag & Codec::FLAG_COMMAND) == 0
+
+            touch_heartbeat
+            return Protocol::ZMTP::Codec::Frame.new(body, command: true)
+          end
+        end
+
+
+        def validate_peer_compatibility!
+          unless Protocol::ZMTP::VALID_PEERS[@socket_type.to_sym]&.include?(@peer_socket_type.to_sym)
+            raise Protocol::ZMTP::Error,
+                  "incompatible socket types: #{@socket_type} cannot connect to #{@peer_socket_type}"
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/omq/transport/websocket/options_ext.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module OMQ
+  module Transport
+    module WebSocket
+      # Prepended onto OMQ::Options at require time.
+      # Adds the per-socket knobs needed by ws:// and wss://.
+      module OptionsExt
+
+        DEFAULT_SUBPROTOCOLS = %w[ZWS2.0/NULL ZWS2.0].freeze
+        DEFAULT_PATH         = "/"
+
+
+        attr_accessor :tls_context
+        attr_accessor :ws_subprotocols
+        attr_accessor :ws_path
+
+
+        def initialize(*, **)
+          super
+          @tls_context     = nil
+          @ws_subprotocols = DEFAULT_SUBPROTOCOLS
+          @ws_path         = DEFAULT_PATH
+        end
+
+      end
+    end
+  end
+end

data/lib/omq/transport/websocket/transport.rb

@@ -0,0 +1,280 @@
+# frozen_string_literal: true
+
+require "uri"
+require "async"
+require "async/promise"
+require "async/http/endpoint"
+require "async/http/server"
+require "async/http/protocol/http1"
+require "async/websocket/client"
+require "async/websocket/adapters/http"
+require "protocol/http/response"
+
+module OMQ
+  module Transport
+    # ZeroMQ-over-WebSocket transport (ZWS 2.0, RFC 45). Registered
+    # for both +ws://+ and +wss://+ schemes. The only difference
+    # between the two is whether the underlying HTTP endpoint carries
+    # an SSL context (supplied via +socket.tls_context=+).
+    module WebSocket
+
+      class << self
+
+        # Engine reads this in ConnectionLifecycle#handshake! to
+        # construct the per-connection codec/handshake driver.
+        # ZWS framing differs from ZMTP/3.1, so we substitute our own
+        # Connection class instead of Protocol::ZMTP::Connection.
+        #
+        # @return [Class]
+        #
+        def connection_class
+          OMQ::Transport::WebSocket::Connection
+        end
+
+
+        # Creates a bound WebSocket listener.
+        #
+        # @param endpoint [String] e.g. "ws://127.0.0.1:5555/" or "wss://host:443/zmq"
+        # @param engine [Engine]
+        # @return [Listener]
+        # @raise [Error] if wss:// is used without a tls_context
+        #
+        def listener(endpoint, engine, **)
+          scheme = endpoint[/\A([a-z]+):\/\//, 1]
+          tls    = engine.options.tls_context
+
+          if scheme == "wss" && tls.nil?
+            raise Error, "wss:// bind requires options.tls_context"
+          end
+
+          subprotocols  = engine.options.ws_subprotocols
+          path          = engine.options.ws_path
+          http_endpoint = parse_http_endpoint(endpoint, tls)
+          bound         = http_endpoint.bound
+          actual_port   = bound.sockets.first.to_io.local_address.ip_port
+          host          = http_endpoint.hostname
+          host_part     = host.include?(":") ? "[#{host}]" : host
+          shown         = "#{scheme}://#{host_part}:#{actual_port}#{path}"
+
+          Listener.new(
+            shown_endpoint: shown,
+            bound:          bound,
+            http_endpoint:  http_endpoint,
+            subprotocols:   subprotocols,
+            match_path:     path,
+            engine:         engine,
+            port:           actual_port,
+          )
+        end
+
+
+        # Creates a WebSocket dialer.
+        #
+        # @param endpoint [String]
+        # @param engine [Engine]
+        # @return [Dialer]
+        #
+        def dialer(endpoint, engine, **)
+          Dialer.new(endpoint, engine)
+        end
+
+
+        # Verifies that the endpoint URI is well-formed for HTTP/WS.
+        #
+        # @param endpoint [String]
+        # @raise [ArgumentError]
+        #
+        def validate_endpoint!(endpoint)
+          uri = URI.parse(endpoint)
+          raise ArgumentError, "missing host: #{endpoint.inspect}" unless uri.hostname
+          raise ArgumentError, "missing port: #{endpoint.inspect}" unless uri.port
+        end
+
+
+        # Parses +endpoint+ into an Async::HTTP::Endpoint, attaching the
+        # SSL context when present (TLS for wss://).
+        #
+        # @param endpoint [String]
+        # @param tls_context [OpenSSL::SSL::SSLContext, nil]
+        # @return [Async::HTTP::Endpoint]
+        #
+        def parse_http_endpoint(endpoint, tls_context)
+          if tls_context
+            ::Async::HTTP::Endpoint.parse(endpoint, ssl_context: tls_context)
+          else
+            ::Async::HTTP::Endpoint.parse(endpoint)
+          end
+        end
+
+      end
+
+
+      # Outgoing connection factory. Stateful so reconnect can call
+      # +#connect+ again without redoing endpoint parsing.
+      class Dialer
+
+        attr_reader :endpoint
+
+
+        def initialize(endpoint, engine)
+          @endpoint = endpoint
+          @engine   = engine
+        end
+
+
+        # Establishes the WebSocket upgrade and hands the resulting
+        # Async::WebSocket::Connection to the engine. The engine builds
+        # the OMQ::Transport::WebSocket::Connection on top via the
+        # transport's +connection_class+ hook and runs the ZWS
+        # handshake.
+        #
+        # @return [void]
+        #
+        def connect
+          tls           = @engine.options.tls_context
+          subprotocols  = @engine.options.ws_subprotocols
+          http_endpoint = WebSocket.parse_http_endpoint(@endpoint, tls)
+          ws_conn       = ::Async::WebSocket::Client.connect(
+            http_endpoint,
+            protocols: subprotocols,
+          )
+
+          @engine.handle_connected(ws_conn, endpoint: @endpoint)
+        end
+
+      end
+
+
+      # Bound WebSocket listener. Wraps an Async::HTTP::Server bound on
+      # the requested host/port. Each accepted HTTP request is matched
+      # against +ws_path+ and upgraded via
+      # Async::WebSocket::Adapters::HTTP.open. The adapter block stays
+      # alive (via AcceptedConnection#wait_for_close) until the engine
+      # closes the connection — otherwise Adapters::HTTP.open would
+      # tear the WebSocket down the moment the block exits.
+      class Listener
+
+        attr_reader :endpoint
+        attr_reader :port
+
+
+        def initialize(shown_endpoint:, bound:, http_endpoint:, subprotocols:, match_path:, engine:, port:)
+          @endpoint      = shown_endpoint
+          @bound         = bound
+          @http_endpoint = http_endpoint
+          @subprotocols  = subprotocols
+          @match_path    = match_path
+          @engine        = engine
+          @port          = port
+          @task          = nil
+        end
+
+
+        def start_accept_loops(parent_task, &on_accepted)
+          @task = parent_task.async(transient: true, annotation: "ws accept #{@endpoint}") do |task|
+            server = ::Async::HTTP::Server.new(
+              ->(request) { handle_request(request, on_accepted) },
+              @bound,
+              protocol: ::Async::HTTP::Protocol::HTTP1,
+              scheme:   @http_endpoint.secure? ? "https" : "http",
+            )
+
+            @bound.accept(&server.method(:accept))
+
+            # +accept+ fires per-socket accept fibers and returns. Wait
+            # on them so the +ensure+ doesn't close +@bound+ out from
+            # under a live accept.
+            task.children.each(&:wait)
+          rescue ::Async::Stop
+            # socket barrier stopped — clean cancel
+          ensure
+            @bound.close rescue nil
+          end
+        end
+
+
+        def stop
+          @task&.stop
+          @bound.close rescue nil
+        end
+
+
+        private
+
+
+        def handle_request(request, on_accepted)
+          return not_found if @match_path && request.path != @match_path
+
+          ::Async::WebSocket::Adapters::HTTP.open(request, protocols: @subprotocols) do |ws_conn|
+            accepted = AcceptedConnection.new(ws_conn)
+            on_accepted.call(accepted)
+            accepted.wait_for_close
+          end or not_found
+        end
+
+
+        def not_found
+          ::Protocol::HTTP::Response[404, {}, []]
+        end
+
+      end
+
+
+      # Server-side wrapper around an Async::WebSocket::Connection.
+      # Delegates the WS interface used by Connection (+read+,
+      # +send_binary+, +flush+, +protocol+) and adds +wait_for_close+
+      # so the Adapters::HTTP.open fiber can block until the engine
+      # closes the connection.
+      #
+      # +close+ only resolves the promise — the actual WebSocket close
+      # is performed by Adapters::HTTP.open's ensure block once
+      # +wait_for_close+ returns. Calling +@ws.close+ here too would
+      # double-close and (on Ruby 3.3) deadlock when the peer has
+      # already closed.
+      class AcceptedConnection
+
+        def initialize(ws)
+          @ws             = ws
+          @closed_promise = ::Async::Promise.new
+        end
+
+
+        def protocol
+          @ws.protocol
+        end
+
+
+        def read
+          @ws.read
+        end
+
+
+        def send_binary(buffer, **opts)
+          @ws.send_binary(buffer, **opts)
+        end
+
+
+        def flush
+          @ws.flush
+        end
+
+
+        def close
+          @closed_promise.resolve(true)
+        end
+
+
+        def closed?
+          @closed_promise.resolved?
+        end
+
+
+        def wait_for_close
+          @closed_promise.wait
+        end
+
+      end
+
+    end
+  end
+end

data/lib/omq/transport/websocket/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module OMQ
+  module Transport
+    module WebSocket
+      VERSION = "0.1.0"
+    end
+  end
+end

data/lib/omq/transport/websocket.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "omq"
+require "async"
+require "async/http"
+require "async/http/endpoint"
+require "async/http/server"
+require "async/websocket"
+require "async/websocket/client"
+require "async/websocket/adapters/http"
+
+require_relative "websocket/version"
+require_relative "websocket/options_ext"
+require_relative "websocket/codec"
+require_relative "websocket/connection"
+require_relative "websocket/transport"
+
+module OMQ
+  module Transport
+    module WebSocket
+
+      # Raised on configuration errors specific to this transport
+      # (e.g. wss:// without tls_context, malformed subprotocol).
+      #
+      class Error < RuntimeError
+      end
+
+    end
+  end
+end
+
+OMQ::Engine.transports["ws"]  = OMQ::Transport::WebSocket
+OMQ::Engine.transports["wss"] = OMQ::Transport::WebSocket
+
+OMQ::Options.prepend(OMQ::Transport::WebSocket::OptionsExt)
+
+OMQ::Socket.def_delegators :@options,
+  :tls_context, :tls_context=,
+  :ws_subprotocols, :ws_subprotocols=,
+  :ws_path, :ws_path=
+
+# OpenSSL::SSL::SSLError already covers wss:// peer aborts after
+# upgrade; add it idempotently in case omq-rfc-tls hasn't been loaded.
+require "openssl"
+unless OMQ::CONNECTION_LOST.include?(OpenSSL::SSL::SSLError)
+  OMQ::CONNECTION_LOST << OpenSSL::SSL::SSLError
+end

data/lib/omq/websocket.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "transport/websocket"

metadata

@@ -0,0 +1,122 @@
+--- !ruby/object:Gem::Specification
+name: omq-websocket
+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.28'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.28'
+- !ruby/object:Gem::Dependency
+  name: protocol-zmtp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+- !ruby/object:Gem::Dependency
+  name: async
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.38'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.38'
+- !ruby/object:Gem::Dependency
+  name: async-http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.94'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.94'
+- !ruby/object:Gem::Dependency
+  name: async-websocket
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.30'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.30'
+description: Adds ws:// and wss:// transports to OMQ, implementing ZeroMQ RFC 45 (ZWS
+  2.0). Built on async-websocket. Registers both schemes on require; no OMQ core changes
+  required beyond the .connection_class hook (omq >= 0.27).
+email:
+- paddor@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/omq/transport/websocket.rb
+- lib/omq/transport/websocket/codec.rb
+- lib/omq/transport/websocket/connection.rb
+- lib/omq/transport/websocket/options_ext.rb
+- lib/omq/transport/websocket/transport.rb
+- lib/omq/transport/websocket/version.rb
+- lib/omq/websocket.rb
+homepage: https://github.com/zeromq/omq.rb/tree/main/gems/omq-websocket
+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.16
+specification_version: 4
+summary: ZeroMQ-over-WebSocket transport for OMQ (ws:// and wss://)
+test_files: []