datagrout-conduit 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61761ad0b8b189c1e4f13c4b552fc22811f4658f3144b84a336c42ed21477224
-  data.tar.gz: 1417cb0c91e1740bc1bb9db884b1df57e00966a7ec7076d2f28c8ba8f205b5b0
+  metadata.gz: 27d8af58b9252394051bb3c764f30bc19b5062664a3bac0295e5bd7aa4e8df94
+  data.tar.gz: 4f6c526fe03897d6666d2b0c76c61651dc9bc71e1eaa269f55f35e321a34671f
 SHA512:
-  metadata.gz: 0a23d1ea87b87d76d82b7ec546f590a90f1682ce23d701ff3e0b7e248f1eba8adcb6f374499ba16cb5ce97e1d2e7778f2e294979c98881af843d3c12ad748e30
-  data.tar.gz: 529763eb59b00754846a84198d6d5d0037a7e0360e0482c119fe0fcafae939b4b7a563f112b215e6bc1f9e1ae7a96c221d5e3274e736be53c8b549ec0c4a2ed8
+  metadata.gz: bba7f383d85b62c05fff950f527047c830b82842536a31151988d87414c5da597a1b67160f507753a8c43c5cd41f0e9cf463a1bdd93ab0bb898165da7a1afc18
+  data.tar.gz: a8c3fec760966850b04ec6c5e9b0c4af46f967b87a9627130bb6bb18cf84157bd1fa0da90486cc64ff01e97c03d815e153e7e1bccd77579f6b93a5775b75df6f

data/README.md

@@ -9,13 +9,13 @@ Connect to remote MCP and JSONRPC servers, invoke tools, discover capabilities w
 Add to your Gemfile:
 
 ```ruby
-gem "datagrout-conduit", "~> 0.1"
+gem "datagrout-conduit", "~> 0.4.0"
 ```
 
 Or install directly:
 
 ```sh
-gem install datagrout-conduit
+gem install datagrout-conduit -v 0.4.0
 ```
 
 ## Quick Start
@@ -168,7 +168,49 @@ client = DatagroutConduit::Client.new(
 )
 ```
 
-Both transports send JSON-RPC 2.0 requests via HTTP POST. MCP uses the MCP Streamable HTTP framing. Both configure Faraday SSL with mTLS client certificates when an identity is present.
+### WebSocket (`datagrout-jsonrpc.v1`)
+
+```ruby
+client = DatagroutConduit::Client.new(
+  url: "wss://gateway.datagrout.ai/servers/{uuid}/ws",
+  auth: { bearer: "your-token" },
+  transport: :websocket
+)
+client.connect
+```
+
+Bidirectional push over a single `wss://` connection using `websocket-driver ~> 0.7` (the library underlying Rails ActionCable — no EventMachine dependency). A background `Thread` runs the read loop; shared state is protected by a `Mutex`.
+
+#### Push subscriptions
+
+```ruby
+# Subscribe — returns a Subscription with recv + each (Enumerable)
+sub = client.subscribe("agents.my-agent-id.events")
+
+# Block on the next event
+event = sub.recv(timeout: 30)
+puts "#{event.event}: #{event.data.inspect}"
+
+# Or iterate until the subscription is closed
+sub.each do |event|
+  puts "#{event.event}: #{event.data.inspect}"
+end
+
+# Unsubscribe when done
+client.unsubscribe(sub)
+```
+
+Supported topics:
+
+| Topic | Fires when |
+|-------|-----------|
+| `agents.<agent_id>.events` | Agent lifecycle events (plan started, IC completed, grounding failed, …) |
+| `tools.<tool_name>.results` | A specific tool call completes |
+| `tasks.<task_id>.*` | Long-running background task transitions |
+| `flows.<flow_id>.*` | `flow.into` progress and completion |
+| `governor.<server_uuid>` | Governor percept events (file change, schedule, webhook) |
+
+**Reconnection**: after a disconnect, `send_request` and `subscribe` raise `DatagroutConduit::NotInitializedError`. Call `client.connect` again and re-subscribe — subscriptions do not survive reconnects in v0.4.
 
 ## Standard MCP Methods
 

data/lib/datagrout_conduit/client.rb

@@ -13,6 +13,23 @@ module DatagroutConduit
 
     attr_reader :transport, :server_info, :use_intelligent_interface
 
+    # Subscribe to a server-push topic over a WebSocket transport.
+    # Returns a {DatagroutConduit::Transport::Ws::Subscription}.
+    # Raises RuntimeError when transport is not :websocket.
+    def subscribe(topic)
+      raise "subscribe() requires transport: :websocket" unless @transport.is_a?(Transport::Ws)
+
+      @transport.subscribe(topic)
+    end
+
+    # Cancel a push subscription.
+    # Accepts a Subscription object or a subscription ID string.
+    def unsubscribe(subscription)
+      raise "unsubscribe() requires transport: :websocket" unless @transport.is_a?(Transport::Ws)
+
+      @transport.unsubscribe(subscription)
+    end
+
     def initialize(url:, auth: {}, transport: :mcp, identity: nil, identity_dir: nil,
                    use_intelligent_interface: nil, max_retries: 3, logger: nil, disable_mtls: false)
       @url = url
@@ -389,8 +406,13 @@ module DatagroutConduit
         # transport, transparently rewrite the path to the DG JSONRPC endpoint.
         rpc_url = @url.end_with?("/mcp") ? @url.sub(%r{/mcp$}, "/rpc") : @url
         Transport::JsonRpc.new(url: rpc_url, auth: @auth, identity: @identity)
+      when :websocket, "websocket"
+        ws_url = @url
+                   .sub(/\Ahttps:\/\//, "wss://")
+                   .sub(/\Ahttp:\/\//, "ws://")
+        Transport::Ws.new(url: ws_url, auth: @auth, identity: @identity)
       else
-        raise ConfigError, "Unknown transport: #{@transport_mode}. Use :mcp or :jsonrpc."
+        raise ConfigError, "Unknown transport: #{@transport_mode}. Use :mcp, :jsonrpc, or :websocket."
       end
     end
 

data/lib/datagrout_conduit/transport/ws.rb

@@ -0,0 +1,478 @@
+# frozen_string_literal: true
+
+require "websocket/driver"
+require "socket"
+require "openssl"
+require "uri"
+require "thread"
+require "json"
+require "securerandom"
+require "base64"
+require "timeout"
+
+module DatagroutConduit
+  module Transport
+    # WebSocket transport for datagrout-jsonrpc.v1.
+    #
+    # Manages a single wss:// connection with concurrent JSON-RPC request
+    # multiplexing and server-push subscriptions. Uses a background thread
+    # for frame reading; callers block on Thread::Queue for responses.
+    #
+    # Usage:
+    #   ws = DatagroutConduit::Transport::Ws.new(
+    #     url: "wss://gateway.datagrout.ai/servers/<uuid>/ws",
+    #     auth: { bearer: "token" }
+    #   )
+    #   ws.connect
+    #   result = ws.send_request("tools/list")
+    #   sub    = ws.subscribe("agents.my-agent.events")
+    #   event  = sub.recv
+    #   ws.unsubscribe(sub)
+    #   ws.disconnect
+    class Ws
+      SUBPROTOCOL = "datagrout-jsonrpc.v1"
+
+      # ── Subscription ─────────────────────────────────────────────────────────
+
+      # Per-subscription event stream delivered via a thread-safe Queue.
+      # Call recv to block until the next event, or iterate with each.
+      class Subscription
+        attr_reader :sub_id, :topic
+
+        def initialize(sub_id, topic)
+          @sub_id = sub_id
+          @topic  = topic
+          @queue  = ::Thread::Queue.new
+          @closed = false
+        end
+
+        # Block until the next event arrives.
+        # Returns nil and raises StopIteration on close when iterating via each.
+        # @param timeout [Numeric, nil] optional timeout in seconds; returns nil on expiry
+        def recv(timeout: nil)
+          event =
+            if timeout
+              Timeout.timeout(timeout) { @queue.pop }
+            else
+              @queue.pop
+            end
+
+          raise StopIteration if event.nil?
+
+          event
+        rescue Timeout::Error
+          nil
+        end
+
+        # Iterate over events until the subscription is closed.
+        def each(&block)
+          loop do
+            event = @queue.pop
+            break if event.nil?
+            block.call(event)
+          end
+        end
+
+        include Enumerable
+
+        def closed?
+          @closed
+        end
+
+        # @api private
+        def _enqueue(event)
+          @queue.push(event) unless @closed
+        end
+
+        # @api private
+        def _close
+          return if @closed
+
+          @closed = true
+          @queue.push(nil)
+        end
+      end
+
+      # Value object for a push notification delivered to a subscription.
+      SubscriptionEvent = Struct.new(:subscription, :event, :data, keyword_init: true)
+
+      # ── Construction ─────────────────────────────────────────────────────────
+
+      def initialize(url:, auth: {}, identity: nil)
+        @url      = url
+        @auth     = normalize_auth(auth)
+        @identity = identity
+        @mutex    = Mutex.new
+        @write_mutex = Mutex.new
+
+        @pending           = {}  # id => RequestFuture
+        @pending_subscribe = {}  # id => { topic:, future: }
+        @subscriptions     = {}  # sub_id => [Subscription, ...]
+        @next_id           = 0
+
+        @io          = nil
+        @driver      = nil
+        @read_thread = nil
+        @connected   = false
+      end
+
+      # ── Public API ────────────────────────────────────────────────────────────
+
+      # Establish the WebSocket connection.
+      # Blocks until the server-side handshake completes (up to 10 s).
+      def connect
+        uri = URI.parse(@url)
+        @io = open_socket(uri)
+
+        adapter = SocketAdapter.new(@url, @io)
+        @driver = WebSocket::Driver.client(adapter, protocols: [SUBPROTOCOL])
+
+        build_upgrade_headers.each { |k, v| @driver.set_header(k, v) }
+
+        handshake_q = ::Thread::Queue.new
+
+        @driver.on(:open)    { handshake_q.push(nil) unless @connected }
+        @driver.on(:message) { |e| handle_message(e.data) }
+        @driver.on(:close)   { handle_disconnect }
+        @driver.on(:error)   { |e| handshake_q.push(e.message) unless @connected }
+
+        @driver.start
+        @read_thread = Thread.new { read_loop }
+        @read_thread.abort_on_exception = false
+        @read_thread.name = "conduit-ws-reader"
+
+        err = Timeout.timeout(10) { handshake_q.pop }
+        raise ConnectionError, "WebSocket handshake failed: #{err}" if err
+
+        @connected = true
+        self
+      rescue Timeout::Error
+        cleanup_socket
+        raise ConnectionError, "WebSocket connection timed out"
+      rescue ConnectionError
+        raise
+      rescue => e
+        cleanup_socket
+        raise ConnectionError, "WebSocket connect error: #{e.message}"
+      end
+
+      # Close the connection and fail all pending requests.
+      def disconnect
+        @mutex.synchronize { @connected = false }
+        fail_all_pending(:disconnected)
+        cleanup_socket
+        self
+      end
+
+      def connected?
+        @connected
+      end
+
+      # Send a JSON-RPC request and block until the response arrives.
+      # Pass id: nil to fire a notification (no response expected).
+      # Returns the result value, or raises McpError on RPC-level error.
+      def send_request(method, params = nil, id: :auto)
+        ensure_connected!
+
+        # id: nil means fire-and-forget notification (no id field, no response wait)
+        if id.nil?
+          frame = { "jsonrpc" => "2.0", "method" => method }
+          frame["params"] = params if params
+          write_frame(frame)
+          return { "result" => {} }
+        end
+
+        req_id = mint_id
+        future = RequestFuture.new
+        @mutex.synchronize { @pending[req_id] = future }
+
+        write_frame(build_request(req_id, method, params))
+
+        result, value = future.wait
+        if result == :ok
+          { "result" => value }
+        else
+          raise McpError.new(code: -1, message: value.to_s, data: nil)
+        end
+      end
+
+      # Subscribe to a dotted-namespace topic.
+      # Returns a Subscription that delivers events via recv / each.
+      def subscribe(topic)
+        ensure_connected!
+
+        req_id = mint_id
+        future = RequestFuture.new
+        @mutex.synchronize { @pending_subscribe[req_id] = { topic: topic, future: future } }
+
+        write_frame(build_request(req_id, "subscribe", { "topic" => topic }))
+
+        result, value = future.wait
+        if result == :ok
+          sub_id = value.is_a?(Hash) ? (value["subscription"] || req_id) : req_id
+          sub = Subscription.new(sub_id, topic)
+          @mutex.synchronize do
+            @subscriptions[sub_id] ||= []
+            @subscriptions[sub_id] << sub
+          end
+          sub
+        else
+          raise McpError.new(code: -1, message: value.to_s, data: nil)
+        end
+      end
+
+      # Cancel a push subscription locally and notify the server.
+      # Accepts a Subscription object or a subscription ID string.
+      def unsubscribe(subscription)
+        sub_id = subscription.is_a?(Subscription) ? subscription.sub_id : subscription.to_s
+
+        subs = @mutex.synchronize { @subscriptions.delete(sub_id) || [] }
+        subs.each(&:_close)
+
+        if @connected
+          req_id = mint_id
+          write_frame(build_request(req_id, "unsubscribe", { "subscription" => sub_id }))
+        end
+
+        :ok
+      end
+
+      private
+
+      # ── Socket adapter for websocket-driver ──────────────────────────────────
+
+      class SocketAdapter
+        attr_reader :url
+
+        def initialize(url, io)
+          @url = url
+          @io  = io
+        end
+
+        def write(data)
+          @io.write(data)
+          data.bytesize
+        end
+      end
+
+      # ── Request future ────────────────────────────────────────────────────────
+
+      class RequestFuture
+        def initialize
+          @queue = ::Thread::Queue.new
+        end
+
+        def wait(timeout: 30)
+          Timeout.timeout(timeout) { @queue.pop }
+        rescue Timeout::Error
+          [:error, "Request timed out after #{timeout}s"]
+        end
+
+        def resolve(value)
+          @queue.push([:ok, value])
+        end
+
+        def reject(reason)
+          @queue.push([:error, reason])
+        end
+      end
+
+      # ── Socket creation ───────────────────────────────────────────────────────
+
+      def open_socket(uri)
+        host = uri.host
+        port = uri.port || (uri.scheme == "wss" ? 443 : 80)
+
+        tcp = TCPSocket.new(host, port)
+        tcp.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1)
+
+        if uri.scheme == "wss"
+          ctx = build_ssl_context
+          ssl = OpenSSL::SSL::SSLSocket.new(tcp, ctx)
+          ssl.hostname = host
+          ssl.sync_close = true
+          ssl.connect
+          ssl
+        else
+          tcp
+        end
+      end
+
+      def build_ssl_context
+        ctx = OpenSSL::SSL::SSLContext.new
+        ctx.set_params(verify_mode: OpenSSL::SSL::VERIFY_PEER)
+
+        if @identity
+          ctx.cert = @identity.openssl_cert
+          ctx.key  = @identity.openssl_key
+          if @identity.ca_pem
+            store = OpenSSL::X509::Store.new
+            store.add_cert(@identity.openssl_ca)
+            ctx.cert_store = store
+          end
+        end
+
+        ctx
+      end
+
+      # ── Upgrade headers ───────────────────────────────────────────────────────
+
+      def build_upgrade_headers
+        headers = {}
+
+        case @auth[:type]
+        when :bearer
+          headers["Authorization"] = "Bearer #{@auth[:token]}"
+        when :api_key
+          headers["X-API-Key"] = @auth[:key]
+        when :basic
+          encoded = Base64.strict_encode64("#{@auth[:username]}:#{@auth[:password]}")
+          headers["Authorization"] = "Basic #{encoded}"
+        when :oauth
+          token = @auth[:provider].get_token
+          headers["Authorization"] = "Bearer #{token}"
+        end
+
+        headers
+      end
+
+      # ── Read loop ─────────────────────────────────────────────────────────────
+
+      def read_loop
+        loop do
+          data = @io.readpartial(4096)
+          @driver.parse(data)
+        rescue EOFError, IOError, Errno::ECONNRESET, Errno::EPIPE
+          handle_disconnect
+          break
+        rescue StandardError
+          handle_disconnect
+          break
+        end
+      end
+
+      # ── Message routing ───────────────────────────────────────────────────────
+
+      def handle_message(raw)
+        msg = JSON.parse(raw)
+
+        str_id = msg["id"]&.to_s
+
+        if str_id && (entry = @mutex.synchronize { @pending_subscribe.delete(str_id) })
+          future = entry[:future]
+          if msg["error"]
+            future.reject(msg.dig("error", "message") || "Subscribe failed")
+          else
+            future.resolve(msg["result"] || {})
+          end
+
+        elsif str_id && (future = @mutex.synchronize { @pending.delete(str_id) })
+          if msg["error"]
+            future.reject(msg.dig("error", "message") || "RPC error")
+          else
+            future.resolve(msg["result"])
+          end
+
+        elsif msg["method"] == "notification"
+          route_notification(msg["params"] || {})
+        end
+      rescue JSON::ParserError
+        # Silently discard malformed frames
+      end
+
+      def route_notification(params)
+        sub_id = params["subscription"]
+        return unless sub_id.is_a?(String)
+
+        subs = @mutex.synchronize { @subscriptions[sub_id] }
+        return unless subs
+
+        event = SubscriptionEvent.new(
+          subscription: sub_id,
+          event: params["event"] || "",
+          data: params["data"]
+        )
+
+        subs.each { |sub| sub._enqueue(event) }
+      end
+
+      def handle_disconnect
+        was_connected = @mutex.synchronize do
+          old = @connected
+          @connected = false
+          old
+        end
+
+        fail_all_pending(:disconnected) if was_connected
+      end
+
+      def fail_all_pending(reason)
+        pending, pending_sub, subs = @mutex.synchronize do
+          p  = @pending.dup
+          ps = @pending_subscribe.dup
+          s  = @subscriptions.dup
+          @pending.clear
+          @pending_subscribe.clear
+          @subscriptions.clear
+          [p, ps, s]
+        end
+
+        pending.each_value     { |f| f.reject(reason) }
+        pending_sub.each_value { |entry| entry[:future].reject(reason) }
+        subs.each_value        { |list| list.each(&:_close) }
+      end
+
+      def cleanup_socket
+        @write_mutex.synchronize do
+          @driver = nil
+        end
+        @read_thread&.kill
+        @read_thread = nil
+        @io&.close rescue nil
+        @io = nil
+      end
+
+      # ── Helpers ───────────────────────────────────────────────────────────────
+
+      def ensure_connected!
+        raise NotInitializedError, "WebSocket not connected. Call connect() first." unless @connected
+      end
+
+      def mint_id
+        @mutex.synchronize do
+          @next_id += 1
+          "ws-#{@next_id}"
+        end
+      end
+
+      def build_request(id, method, params)
+        body = { "jsonrpc" => "2.0", "id" => id, "method" => method }
+        body["params"] = params if params
+        body
+      end
+
+      def write_frame(data)
+        json = JSON.generate(data)
+        @write_mutex.synchronize { @driver&.text(json) }
+      end
+
+      def normalize_auth(auth)
+        return { type: :none } if auth.nil? || auth.empty?
+
+        auth = auth.transform_keys(&:to_sym) if auth.is_a?(Hash)
+
+        if auth[:bearer]
+          { type: :bearer, token: auth[:bearer] }
+        elsif auth[:api_key]
+          { type: :api_key, key: auth[:api_key] }
+        elsif auth[:basic]
+          { type: :basic, username: auth[:basic][:username], password: auth[:basic][:password] }
+        elsif auth[:oauth] || auth[:provider]
+          { type: :oauth, provider: auth[:oauth] || auth[:provider] }
+        else
+          { type: :none }
+        end
+      end
+    end
+  end
+end

data/lib/datagrout_conduit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DatagroutConduit
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/datagrout_conduit.rb

@@ -11,6 +11,7 @@ require_relative "datagrout_conduit/registration"
 require_relative "datagrout_conduit/transport/base"
 require_relative "datagrout_conduit/transport/mcp"
 require_relative "datagrout_conduit/transport/jsonrpc"
+require_relative "datagrout_conduit/transport/ws"
 require_relative "datagrout_conduit/namespaces/prism"
 require_relative "datagrout_conduit/namespaces/logic"
 require_relative "datagrout_conduit/namespaces/warden"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: datagrout-conduit
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - DataGrout
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-23 00:00:00.000000000 Z
+date: 2026-05-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -52,6 +52,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: websocket-driver
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -119,6 +133,7 @@ files:
 - lib/datagrout_conduit/transport/base.rb
 - lib/datagrout_conduit/transport/jsonrpc.rb
 - lib/datagrout_conduit/transport/mcp.rb
+- lib/datagrout_conduit/transport/ws.rb
 - lib/datagrout_conduit/types.rb
 - lib/datagrout_conduit/version.rb
 homepage: https://github.com/DataGrout/conduit-sdk