datagrout-conduit 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61761ad0b8b189c1e4f13c4b552fc22811f4658f3144b84a336c42ed21477224
-  data.tar.gz: 1417cb0c91e1740bc1bb9db884b1df57e00966a7ec7076d2f28c8ba8f205b5b0
+  metadata.gz: d3a08c2cb30deefe712f0083b473838a1ec6b578c1b7decbcc53ac14aca4cffb
+  data.tar.gz: ea88b13e4a5998164c4dfaa1b71d448e5d498b694b8de312449a8c82d4daf555
 SHA512:
-  metadata.gz: 0a23d1ea87b87d76d82b7ec546f590a90f1682ce23d701ff3e0b7e248f1eba8adcb6f374499ba16cb5ce97e1d2e7778f2e294979c98881af843d3c12ad748e30
-  data.tar.gz: 529763eb59b00754846a84198d6d5d0037a7e0360e0482c119fe0fcafae939b4b7a563f112b215e6bc1f9e1ae7a96c221d5e3274e736be53c8b549ec0c4a2ed8
+  metadata.gz: 70c40acb181dcc382395c454e769e26fede6798a32dc2dab7797ffaf66b1936dd0e89cf767f2f9f16a5e668ad1ceff9dfd3d2a22d03db34bcb146ab1eef78ba6
+  data.tar.gz: 3c2cf29896ae08b63876e60e8807ccb7ea85118fdb5d422aaf9b94e4ef3aa76345786b42bb0406f1c8df1b938d3755cf78a84fd3bf9728f5ecc4fd54a6c7b737

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.5.0"
 ```
 
 Or install directly:
 
 ```sh
-gem install datagrout-conduit
+gem install datagrout-conduit -v 0.5.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,14 +13,33 @@ 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)
+                   use_intelligent_interface: nil, max_retries: 3, logger: nil,
+                   identity_auto: false, disable_mtls: false)
       @url = url
       @auth = auth
       @transport_mode = transport
       @identity = identity
       @identity_dir = identity_dir
-      @disable_mtls = disable_mtls
+      @identity_auto = identity_auto
+      @disable_mtls = disable_mtls  # deprecated, kept for backward compat
       @max_retries = max_retries
       @initialized = false
       @server_info = nil
@@ -87,6 +106,38 @@ module DatagroutConduit
       bootstrap_identity(url: url, auth_token: token, name: name, identity_dir: identity_dir)
     end
 
+    # Bootstrap by performing the autonomous DG onramp flow.
+    #
+    # The all-in-one flow: onramp (no prior credentials required) →
+    # OAuth token exchange → mTLS identity registration and persistence.
+    #
+    # On subsequent runs the saved mTLS identity is auto-discovered and
+    # no credentials are needed.
+    #
+    # @param opts [DatagroutConduit::Onramp::OnrampOptions]
+    # @param url [String, nil] MCP server URL; required when +opts.mcp_url+ is absent
+    # @param name [String] human-readable identity label
+    # @param identity_dir [String, nil] custom identity storage directory
+    # @return [Client] unconnected client; call +#connect+ before use
+    def self.bootstrap_onramp(opts:, url: nil, name: "conduit-client", identity_dir: nil)
+      dir = identity_dir || Registration.default_identity_dir || File.join(Dir.home, ".conduit")
+
+      # Fast path: existing valid identity.
+      identity = Identity.try_discover(override_dir: dir)
+      if identity && !identity.needs_rotation?
+        raise ArgumentError, "'url' must be provided when an existing identity is reused" if url.nil?
+        return new(url: url, identity: identity)
+      end
+
+      # Slow path: full onramp flow.
+      creds, token = Onramp.register_and_exchange(opts)
+
+      mcp_url = creds.mcp_url || url
+      raise ArgumentError, "'url' must be provided when mcp_url is absent from onramp response" if mcp_url.nil?
+
+      bootstrap_identity(url: mcp_url, auth_token: token, name: name, identity_dir: identity_dir)
+    end
+
     def connect
       @transport.connect
 
@@ -389,15 +440,19 @@ 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
 
     def resolve_identity!
       return if @identity
-      return if @disable_mtls
-      return unless @is_dg
+      return unless @identity_auto
 
       @identity = Identity.try_discover(override_dir: @identity_dir)
     end

data/lib/datagrout_conduit/identity.rb

@@ -67,31 +67,30 @@ module DatagroutConduit
     # Walk the auto-discovery chain and return the first identity found,
     # or nil if nothing is available.
     def self.try_discover(override_dir: nil)
-      # 1. Override directory
+      # When an explicit directory is given, scope search to that dir only.
       if override_dir
-        id = try_load_from_dir(override_dir)
-        return id if id
+        return try_load_from_dir(override_dir)
       end
 
-      # 2. Environment variables (individual cert/key PEMs)
+      # 1. Environment variables (individual cert/key PEMs)
       id = from_env
       return id if id
 
-      # 3. CONDUIT_IDENTITY_DIR env var
+      # 2. CONDUIT_IDENTITY_DIR env var
       identity_dir = ENV["CONDUIT_IDENTITY_DIR"]
       if identity_dir && !identity_dir.empty?
         id = try_load_from_dir(identity_dir)
         return id if id
       end
 
-      # 4. ~/.conduit/
+      # 3. ~/.conduit/
       home = ENV["HOME"] || ENV["USERPROFILE"]
       if home
         id = try_load_from_dir(File.join(home, ".conduit"))
         return id if id
       end
 
-      # 5. .conduit/ relative to cwd
+      # 4. .conduit/ relative to cwd
       id = try_load_from_dir(File.join(Dir.pwd, ".conduit"))
       return id if id
 

data/lib/datagrout_conduit/onramp.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module DatagroutConduit
+  # Autonomous agent self-registration (onramp) for DataGrout.
+  #
+  # The onramp flow lets a machine intelligence register itself with DG
+  # without a human in the loop, using only plain HTTP JSON — no MCP client
+  # required.
+  #
+  # == Flow
+  #
+  # 1. POST to +/onramp+ with agent identity metadata (no auth).
+  # 2. DG returns a short-lived +session_token+ (5 minutes).
+  # 3. POST to +/onramp/complete+ with +Authorization: Bearer <session_token>+.
+  # 4. DG issues provisional +client_id+ + +client_secret+ (restricted scopes).
+  #
+  # == Example
+  #
+  #   opts = DatagroutConduit::Onramp::OnrampOptions.new(
+  #     gateway: "https://app.datagrout.ai",
+  #     agent_name: "my-research-agent",
+  #     agent_type: "claude-sonnet-4-6"
+  #   )
+  #   client = DatagroutConduit::Client.bootstrap_onramp(opts: opts, url: nil)
+  module Onramp
+    # Options for the autonomous agent onramp flow.
+    OnrampOptions = Struct.new(
+      :gateway,
+      :agent_name,
+      :agent_type,
+      :intended_use,
+      :access_code,
+      keyword_init: true
+    )
+
+    # Provisional credentials returned by the DG onramp complete endpoint.
+    #
+    # Store +client_id+ and +client_secret+ securely — the secret is shown
+    # exactly once and cannot be recovered after this point.
+    OnrampCredentials = Struct.new(
+      :client_id,
+      :client_secret,
+      :token_url,
+      :scopes,
+      :expires_in,
+      :rpc_url,
+      :mcp_url,
+      keyword_init: true
+    )
+
+    class OnrampError < StandardError; end
+
+    # Perform the onramp handshake and return provisional OAuth credentials.
+    #
+    # Low-level entry point. Most callers should use
+    # {DatagroutConduit::Client.bootstrap_onramp} instead.
+    #
+    # @param opts [OnrampOptions]
+    # @return [OnrampCredentials]
+    def self.register_only(opts)
+      register(opts)
+    end
+
+    # Perform the full onramp handshake and OAuth token exchange.
+    #
+    # @param opts [OnrampOptions]
+    # @return [Array(OnrampCredentials, String)] credentials and access token
+    def self.register_and_exchange(opts)
+      creds = register(opts)
+      token = exchange_token(creds)
+      [creds, token]
+    end
+
+    # @api private
+    def self.register(opts)
+      base = opts.gateway.chomp("/")
+
+      body = { agent_name: opts.agent_name }
+      body[:agent_type] = opts.agent_type if opts.agent_type
+      body[:intended_use] = opts.intended_use if opts.intended_use
+      body[:access_code] = opts.access_code if opts.access_code
+
+      conn = build_conn
+
+      init_resp = conn.post("#{base}/onramp") do |req|
+        req.headers["Content-Type"] = "application/json"
+        req.body = JSON.generate(body)
+      end
+
+      raise OnrampError, "onramp init rejected (HTTP #{init_resp.status}): #{init_resp.body}" \
+        unless init_resp.success?
+
+      init_data = parse_body(init_resp.body)
+      session_token = init_data["session_token"]
+
+      complete_resp = conn.post("#{base}/onramp/complete") do |req|
+        req.headers["Authorization"] = "Bearer #{session_token}"
+      end
+
+      raise OnrampError, "onramp complete rejected (HTTP #{complete_resp.status}): #{complete_resp.body}" \
+        unless complete_resp.success?
+
+      data = parse_body(complete_resp.body)
+
+      OnrampCredentials.new(
+        client_id: data["client_id"],
+        client_secret: data["client_secret"],
+        token_url: data["token_url"],
+        scopes: data["scopes"] || [],
+        expires_in: data["expires_in"] || 0,
+        rpc_url: data["rpc_url"],
+        mcp_url: data["mcp_url"]
+      )
+    end
+    private_class_method :register
+
+    # @api private
+    def self.exchange_token(creds)
+      conn = Faraday.new do |f|
+        f.request :url_encoded
+        f.response :json, content_type: /\bjson$/
+        f.adapter Faraday.default_adapter
+      end
+
+      resp = conn.post(creds.token_url, {
+        grant_type: "client_credentials",
+        client_id: creds.client_id,
+        client_secret: creds.client_secret
+      })
+
+      raise OnrampError, "token exchange failed (HTTP #{resp.status}): #{resp.body}" \
+        unless resp.success?
+
+      data = parse_body(resp.body)
+      data["access_token"]
+    end
+    private_class_method :exchange_token
+
+    def self.build_conn
+      Faraday.new do |f|
+        f.response :json, content_type: /\bjson$/
+        f.adapter Faraday.default_adapter
+      end
+    end
+    private_class_method :build_conn
+
+    def self.parse_body(body)
+      body.is_a?(String) ? JSON.parse(body) : body
+    end
+    private_class_method :parse_body
+  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.5.0"
 end

data/lib/datagrout_conduit.rb

@@ -8,9 +8,11 @@ require_relative "datagrout_conduit/types"
 require_relative "datagrout_conduit/identity"
 require_relative "datagrout_conduit/oauth"
 require_relative "datagrout_conduit/registration"
+require_relative "datagrout_conduit/onramp"
 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.5.0
 platform: ruby
 authors:
 - DataGrout
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-23 00:00:00.000000000 Z
+date: 2026-05-10 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
@@ -115,10 +129,12 @@ files:
 - lib/datagrout_conduit/namespaces/prism.rb
 - lib/datagrout_conduit/namespaces/warden.rb
 - lib/datagrout_conduit/oauth.rb
+- lib/datagrout_conduit/onramp.rb
 - lib/datagrout_conduit/registration.rb
 - 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