smplkit 3.0.133 → 3.0.135

data/lib/smplkit/jobs/models.rb

@@ -4,8 +4,8 @@ module Smplkit
   # Smpl Jobs surface — exposed through +client.jobs.*+.
   #
   # Unlike Config/Flags/Logging, Jobs has no live "phone-home" agent — no
-  # environment registration, no WebSocket — so its entire surface lives on a
-  # single client. A {Job} is an active record: build it with
+  # environment registration, no event stream — so its entire surface lives on
+  # a single client. A {Job} is an active record: build it with
   # +client.jobs.new_recurring_job(...)+ / +new_manual_job(...)+ /
   # +schedule(...)+, set fields, and call {Job#save} (create when new,
   # full-replace update when it already exists) or {Job#delete}. Runs are

data/lib/smplkit/logging/client.rb

@@ -20,19 +20,19 @@
 # * *Live surface* — directly on the client. +register_adapter+ is a PRE-install
 #   configuration call (allowed before +install+). +install+ opens the live
 #   connection (monkey-patches the app's logging framework, discovers loggers,
-#   fetches + applies levels, opens the shared WebSocket). +on_change+ /
+#   fetches + applies levels, opens the shared event stream). +on_change+ /
 #   +refresh+ require +install+ first; calling them earlier raises
 #   +NotInstalledError+.
 #
 # The client supports two construction shapes:
 #
 # * *Wired* into +Smplkit::Client+ — borrows the parent's logging transport for
-#   both runtime fetch and CRUD and the parent's shared WebSocket for the live
-#   channel. This is the common path.
+#   both runtime fetch and CRUD and the parent's shared event stream for the
+#   live channel. This is the common path.
 # * *Standalone* — +LoggingClient.new(api_key: ..., base_url: ..., ...)+ builds
-#   and owns its own logging transport and an app transport (the WebSocket
-#   gateway lives on the app service), and on +install+ opens and owns its own
-#   WebSocket. +close+ tears down only the owned transports and owned WebSocket.
+#   and owns its own logging transport and an app transport (the event stream
+#   lives on the app service), and on +install+ opens and owns its own event
+#   stream. +close+ tears down only the owned transports and owned event stream.
 module Smplkit
   module Logging
     NOT_INSTALLED_MESSAGE = "Smpl Logging live operations require install() first — this opens a live " \
@@ -45,10 +45,9 @@ module Smplkit
     # client takes after it has already resolved them); otherwise the management
     # config resolver fills in whatever is missing (+~/.smplkit+ / env vars /
     # defaults). +environment+/+service+ resolve the same way (constructor
-    # argument wins). The app transport is needed for the WebSocket gateway,
-    # which lives on the app service (like flags); the app base URL is returned
-    # so a standalone client can open its own WebSocket against the event
-    # gateway.
+    # argument wins). The app transport is needed because the event stream
+    # lives on the app service (like flags); the app base URL is returned so a
+    # standalone client can open its own event stream against the app service.
     #
     # @api private
     def self.logging_transport(api_key:, base_url:, profile:, base_domain:, scheme:,
@@ -97,7 +96,7 @@ module Smplkit
     #     +"INFO"+, +"DEBUG"+) — the same value the resolution algorithm returns.
     # @!attribute [rw] source
     #   @return [String] Short string identifying the trigger — typically
-    #     +"websocket"+ or +"manual"+ (a +refresh+ call).
+    #     +"push"+ (a live update) or +"manual"+ (a +refresh+ call).
     LoggerChangeEvent = Struct.new(:id, :level, :source, keyword_init: true) do
       def ==(other)
         other.is_a?(LoggerChangeEvent) &&
@@ -457,8 +456,8 @@ module Smplkit
       # @param debug [Boolean, nil] Enable SDK debug logging.
       # @param extra_headers [Hash{String => String}, nil] Extra headers
       #   attached to every request.
-      # @param streaming [Boolean] Live updates over WebSocket (default
-      #   +true+): +install+ opens a shared socket and server-side level
+      # @param streaming [Boolean] Live updates over the event stream (default
+      #   +true+): +install+ opens a shared stream and server-side level
       #   changes stream in. Set +false+ for the stateless apply-once surface:
       #   +install+ still loads adapters, flushes discovery, and applies the
       #   server's levels — all blocking — but NO socket or background thread
@@ -514,8 +513,8 @@ module Smplkit
         @key_listeners = Hash.new { |h, k| h[k] = [] }
         @adapters = []
         @explicit_adapters = false
-        @ws_manager = nil
-        @owns_ws = false
+        @event_stream = nil
+        @owns_stream = false
         @lock = Mutex.new
       end
 
@@ -545,12 +544,12 @@ module Smplkit
         @adapters.dup
       end
 
-      # --- Live surface: install (gate) + transport / WebSocket helpers ---
+      # --- Live surface: install (gate) + transport / event stream helpers ---
 
       # Hook smplkit into the application's logging machinery.
       #
       # Loads adapters, scans existing loggers, applies levels from the smplkit
-      # server, and wires WebSocket handlers for live updates. This IS the
+      # server, and wires event stream handlers for live updates. This IS the
       # explicit consent gate — +on_change+ / +refresh+ require it first.
       #
       # Idempotent — safe to call multiple times.
@@ -600,12 +599,15 @@ module Smplkit
                         "(logging: #{@logging_http&.config&.host}): #{e.class}: #{e.message}")
         end
 
-        # 7. Register WebSocket event handlers for real-time level updates.
-        # In stateless mode (+streaming: false+) no socket is ever created —
-        # level changes then arrive only via +refresh+.
+        # 7. Register event stream handlers for real-time level updates, plus
+        # the bulk-refresh path as the stream's reconnect refetch so a stream
+        # outage ends with a full re-sync. In stateless mode
+        # (+streaming: false+) no stream is ever created — level changes then
+        # arrive only via +refresh+.
         if @streaming
-          @ws_manager = ensure_ws
-          ws_handlers.each { |event, handler| @ws_manager.on(event, &handler) }
+          @event_stream = ensure_event_stream
+          stream_handlers.each { |event, handler| @event_stream.on(event, &handler) }
+          @event_stream.on_reconnect(refetch_callback)
         end
 
         @connected = true
@@ -643,9 +645,9 @@ module Smplkit
 
       # Release resources — only those this client owns.
       #
-      # Uninstalls the adapter hooks, unsubscribes from the WebSocket, and tears
-      # down the owned WebSocket (standalone install). A wired client borrows the
-      # parent's transport and WebSocket and closes neither.
+      # Uninstalls the adapter hooks, unsubscribes from the event stream, and
+      # tears down the owned event stream (standalone install). A wired client
+      # borrows the parent's transport and event stream and closes neither.
       def close
         Smplkit.debug("lifecycle", "LoggingClient.close() called")
         @adapters.each do |adapter|
@@ -653,13 +655,14 @@ module Smplkit
         rescue StandardError => e
           Smplkit.debug("logging", "adapter #{adapter.name} uninstall_hook failed: #{e.class}: #{e.message}")
         end
-        if @ws_manager
-          ws_handlers.each { |event, handler| @ws_manager.off(event, handler) }
-          if @owns_ws
-            @ws_manager.stop
-            @owns_ws = false
+        if @event_stream
+          stream_handlers.each { |event, handler| @event_stream.off(event, handler) }
+          @event_stream.off_reconnect(refetch_callback)
+          if @owns_stream
+            @event_stream.stop
+            @owns_stream = false
           end
-          @ws_manager = nil
+          @event_stream = nil
         end
         @connected = false
       end
@@ -674,7 +677,7 @@ module Smplkit
       #
       # Mirrors Ruby's +File.open+ block form: the client is closed
       # automatically when the block returns or raises, so a standalone client's
-      # owned transports and WebSocket are always torn down.
+      # owned transports and event stream are always torn down.
       #
       #   Smplkit::LoggingClient.open(environment: "production") do |logging|
       #     logging.loggers.new("sqlalchemy.engine").save
@@ -701,10 +704,10 @@ module Smplkit
 
       # Memoized event → handler map so +install+ registers and +close+
       # unsubscribes the exact same callback objects. They are stored as procs
-      # (not bound methods) because +SharedWebSocket#off+ removes by object
+      # (not bound methods) because +EventStream#off+ removes by object
       # identity, and +on(event, &proc)+ stores the very proc passed here.
-      def ws_handlers
-        @ws_handlers ||= {
+      def stream_handlers
+        @stream_handlers ||= {
           "logger_changed" => proc { |data| handle_logger_changed(data) },
           "logger_deleted" => proc { |data| handle_logger_deleted(data) },
           "group_changed" => proc { |data| handle_group_changed(data) },
@@ -713,17 +716,24 @@ module Smplkit
         }
       end
 
-      def ensure_ws
-        return @parent._ensure_ws unless @parent.nil?
+      # Memoized reconnect refetch — the same bulk-refresh path the
+      # +loggers_changed+ handler runs, registered with the stream on
+      # +install+ and deregistered (by object identity) on +close+.
+      def refetch_callback
+        @refetch_callback ||= proc { handle_loggers_changed({}) }
+      end
+
+      def ensure_event_stream
+        return @parent._ensure_event_stream unless @parent.nil?
 
-        if @ws_manager.nil?
-          @ws_manager = SharedWebSocket.new(
+        if @event_stream.nil?
+          @event_stream = EventStream.new(
             app_base_url: @app_base_url, api_key: @standalone_api_key, metrics: @metrics
           )
-          @ws_manager.start
-          @owns_ws = true
+          @event_stream.start
+          @owns_stream = true
         end
-        @ws_manager
+        @event_stream
       end
 
       # --- Internal ---
@@ -777,8 +787,8 @@ module Smplkit
       # path).
       #
       # Silent — does not fire change-listener events. Use
-      # +fetch_and_apply_deltas+ from the WS / refresh paths to get per-logger
-      # fanout.
+      # +fetch_and_apply_deltas+ from the push / refresh paths to get
+      # per-logger fanout.
       def fetch_and_apply(trigger: "unknown")
         fetch_cache(trigger)
         apply_levels
@@ -858,58 +868,58 @@ module Smplkit
         end
       end
 
-      # --- Internal: event handlers (called by SharedWebSocket) ---
+      # --- Internal: event handlers (called by EventStream) ---
 
       def handle_logger_changed(data)
         key = data["id"] || ""
-        Smplkit.debug("websocket", "logger_changed: fetching logger #{key.inspect}")
+        Smplkit.debug("events", "logger_changed: fetching logger #{key.inspect}")
         pre = snapshot_effective_levels
         begin
           entry_id, entry = @loggers.get_logger_entry(key)
           @loggers_cache[entry_id || key] = entry
         rescue StandardError => e
-          Smplkit.debug("websocket", "failed to fetch logger #{key.inspect} after WS event: #{e.class}: #{e.message}")
+          Smplkit.debug("events", "failed to fetch logger #{key.inspect} after push event: #{e.class}: #{e.message}")
           return
         end
-        apply_deltas_and_fire(pre, "websocket")
+        apply_deltas_and_fire(pre, "push")
       end
 
       def handle_logger_deleted(data)
         key = data["id"] || ""
-        Smplkit.debug("websocket", "logger_deleted: removing logger #{key.inspect}")
+        Smplkit.debug("events", "logger_deleted: removing logger #{key.inspect}")
         pre = snapshot_effective_levels
         @loggers_cache.delete(key)
-        apply_deltas_and_fire(pre, "websocket")
+        apply_deltas_and_fire(pre, "push")
       end
 
       def handle_group_changed(data)
         key = data["id"] || ""
-        Smplkit.debug("websocket", "group_changed: fetching group #{key.inspect}")
+        Smplkit.debug("events", "group_changed: fetching group #{key.inspect}")
         pre = snapshot_effective_levels
         begin
           entry_id, entry = @log_groups.get_group_entry(key)
           @groups_cache[entry_id || key] = entry
         rescue StandardError => e
-          Smplkit.debug("websocket",
-                        "failed to fetch log group #{key.inspect} after WS event: #{e.class}: #{e.message}")
+          Smplkit.debug("events",
+                        "failed to fetch log group #{key.inspect} after push event: #{e.class}: #{e.message}")
           return
         end
-        apply_deltas_and_fire(pre, "websocket")
+        apply_deltas_and_fire(pre, "push")
       end
 
       def handle_group_deleted(data)
         key = data["id"] || ""
-        Smplkit.debug("websocket", "group_deleted: removing group #{key.inspect}")
+        Smplkit.debug("events", "group_deleted: removing group #{key.inspect}")
         pre = snapshot_effective_levels
         @groups_cache.delete(key)
-        apply_deltas_and_fire(pre, "websocket")
+        apply_deltas_and_fire(pre, "push")
       end
 
       def handle_loggers_changed(_data)
-        Smplkit.debug("websocket", "loggers_changed: full re-fetch")
-        fetch_and_apply_deltas(trigger: "loggers_changed WS event", source: "websocket")
+        Smplkit.debug("events", "loggers_changed: full re-fetch")
+        fetch_and_apply_deltas(trigger: "loggers_changed event", source: "push")
       rescue StandardError => e
-        Smplkit.debug("websocket",
+        Smplkit.debug("events",
                       "failed to re-fetch/apply logging levels after loggers_changed event: #{e.class}: #{e.message}")
       end
     end

data/lib/smplkit/transport.rb

@@ -65,7 +65,7 @@ module Smplkit
     #
     # Construction is side-effect-free: each transport connects lazily on its
     # first call. +app_url+ is carried alongside so the account settings client
-    # and the WebSocket can reach the app service. +close+ tears down the
+    # and the event stream can reach the app service. +close+ tears down the
     # underlying Faraday connection pools.
     #
     # @api private

data/lib/smplkit/version.rb

@@ -26,8 +26,8 @@ module Smplkit
     spec ? spec.version.to_s : VERSION
   end
 
-  # The default User-Agent stamped on every outbound request (HTTP and the
-  # WebSocket handshake) when the caller has not supplied their own.
+  # The default User-Agent stamped on every outbound request (including the
+  # live-updates event stream) when the caller has not supplied their own.
   #
   # The platform sits behind a WAF that rejects requests carrying no
   # User-Agent, and an SDK-identifying value keeps support/telemetry able to

data/lib/smplkit.rb

@@ -43,7 +43,7 @@ require_relative "smplkit/log_level"
 require_relative "smplkit/context"
 require_relative "smplkit/config_resolution"
 require_relative "smplkit/metrics"
-require_relative "smplkit/ws"
+require_relative "smplkit/event_stream"
 
 # Internal foundation shared by every product client.
 require_relative "smplkit/buffers"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: smplkit
 version: !ruby/object:Gem::Version
-  version: 3.0.133
+  version: 3.0.135
 platform: ruby
 authors:
 - Smpl Solutions LLC
@@ -49,26 +49,6 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '1'
-- !ruby/object:Gem::Dependency
-  name: async-websocket
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0.26'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '1'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0.26'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '1'
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
   requirement: !ruby/object:Gem::Requirement
@@ -787,6 +767,13 @@ files:
 - lib/smplkit/_generated/jobs/lib/smplkit_jobs_client/models/run_resource.rb
 - lib/smplkit/_generated/jobs/lib/smplkit_jobs_client/models/run_response.rb
 - lib/smplkit/_generated/jobs/lib/smplkit_jobs_client/models/run_retry.rb
+- lib/smplkit/_generated/jobs/lib/smplkit_jobs_client/models/run_stat.rb
+- lib/smplkit/_generated/jobs/lib/smplkit_jobs_client/models/run_stat_bucket.rb
+- lib/smplkit/_generated/jobs/lib/smplkit_jobs_client/models/run_stat_failure.rb
+- lib/smplkit/_generated/jobs/lib/smplkit_jobs_client/models/run_stat_next_scheduled.rb
+- lib/smplkit/_generated/jobs/lib/smplkit_jobs_client/models/run_stat_resource.rb
+- lib/smplkit/_generated/jobs/lib/smplkit_jobs_client/models/run_stat_tally.rb
+- lib/smplkit/_generated/jobs/lib/smplkit_jobs_client/models/run_stats_response.rb
 - lib/smplkit/_generated/jobs/lib/smplkit_jobs_client/models/usage.rb
 - lib/smplkit/_generated/jobs/lib/smplkit_jobs_client/models/usage_resource.rb
 - lib/smplkit/_generated/jobs/lib/smplkit_jobs_client/models/usage_response.rb
@@ -822,6 +809,13 @@ files:
 - lib/smplkit/_generated/jobs/spec/models/run_response_spec.rb
 - lib/smplkit/_generated/jobs/spec/models/run_retry_spec.rb
 - lib/smplkit/_generated/jobs/spec/models/run_spec.rb
+- lib/smplkit/_generated/jobs/spec/models/run_stat_bucket_spec.rb
+- lib/smplkit/_generated/jobs/spec/models/run_stat_failure_spec.rb
+- lib/smplkit/_generated/jobs/spec/models/run_stat_next_scheduled_spec.rb
+- lib/smplkit/_generated/jobs/spec/models/run_stat_resource_spec.rb
+- lib/smplkit/_generated/jobs/spec/models/run_stat_spec.rb
+- lib/smplkit/_generated/jobs/spec/models/run_stat_tally_spec.rb
+- lib/smplkit/_generated/jobs/spec/models/run_stats_response_spec.rb
 - lib/smplkit/_generated/jobs/spec/models/usage_resource_spec.rb
 - lib/smplkit/_generated/jobs/spec/models/usage_response_spec.rb
 - lib/smplkit/_generated/jobs/spec/models/usage_spec.rb
@@ -919,6 +913,7 @@ files:
 - lib/smplkit/context.rb
 - lib/smplkit/debug.rb
 - lib/smplkit/errors.rb
+- lib/smplkit/event_stream.rb
 - lib/smplkit/flags/client.rb
 - lib/smplkit/flags/helpers.rb
 - lib/smplkit/flags/models.rb
@@ -946,7 +941,6 @@ files:
 - lib/smplkit/railtie.rb
 - lib/smplkit/transport.rb
 - lib/smplkit/version.rb
-- lib/smplkit/ws.rb
 - sig/smplkit.rbs
 - sig/smplkit/config.rbs
 - sig/smplkit/flags.rbs

data/lib/smplkit/ws.rb

@@ -1,268 +0,0 @@
-# frozen_string_literal: true
-
-require "json"
-require "async"
-require "async/http/endpoint"
-require "async/http/protocol/http1"
-require "async/websocket/client"
-require "concurrent"
-
-module Smplkit
-  # Manages a single WebSocket connection to the app service event gateway.
-  #
-  # A single +SharedWebSocket+ instance is shared across all product modules
-  # (config, flags, logging) within one +Smplkit::Client+. Product modules
-  # register listeners for specific event types; the shared connection
-  # dispatches incoming events to the appropriate listeners.
-  #
-  # The connection runs on a dedicated SDK-owned thread that hosts the
-  # +Async+ reactor and the underlying +async-websocket+ I/O. Public
-  # methods are thread-safe and non-blocking.
-  #
-  # Gateway protocol:
-  #
-  #   - Connect to +wss://app.<base_domain>/api/ws/v1/events?api_key={key}+
-  #   - Receive +{"type": "connected"}+ on success
-  #   - Receive events: +{"event": "config_changed", ...}+, etc.
-  #   - No subscribe message — the API key determines the account
-  #   - Heartbeat: server sends +"ping"+ (text), client responds with +"pong"+
-  #
-  # On disconnect the reactor reconnects with exponential backoff
-  # (1, 2, 4, 8, 16, 32, 60 seconds, then capped). +stop+ closes the
-  # connection from the outer thread; the reader exits and the daemon
-  # thread terminates.
-  class SharedWebSocket
-    BACKOFF_SCHEDULE = [1, 2, 4, 8, 16, 32, 60].freeze
-
-    # Sent on the WebSocket upgrade request — the platform WAF rejects
-    # handshakes that carry no User-Agent. There is no caller-supplied
-    # header surface on the WebSocket, so the SDK default always applies.
-    USER_AGENT = Smplkit.user_agent.freeze
-
-    def initialize(app_base_url:, api_key:, metrics: nil)
-      @app_base_url = app_base_url
-      @api_key = api_key
-      @metrics = metrics
-      @listeners = Hash.new { |h, k| h[k] = [] }
-      @listeners_lock = Mutex.new
-      @connection_status = "disconnected"
-      @closed = false
-      @ws_thread = nil
-      @connection = nil
-      @connection_lock = Mutex.new
-    end
-
-    # ----- Listener registration ------------------------------------
-
-    def on(event_name, &callback)
-      @listeners_lock.synchronize { @listeners[event_name] << callback }
-    end
-
-    def off(event_name, callback)
-      @listeners_lock.synchronize { @listeners[event_name].delete(callback) }
-    end
-
-    # Dispatch +data+ to every listener registered for +event_name+.
-    # Listener exceptions are caught and logged; one bad listener never
-    # blocks the rest.
-    def dispatch(event_name, data)
-      callbacks = @listeners_lock.synchronize { @listeners[event_name].dup }
-      callbacks.each do |cb|
-        cb.call(data)
-      rescue StandardError => e
-        Smplkit.debug("websocket", "listener for #{event_name} raised: #{e.class}: #{e.message}")
-      end
-    end
-
-    # ----- Connection status ----------------------------------------
-
-    attr_reader :connection_status
-
-    # ----- Lifecycle ------------------------------------------------
-
-    def start
-      return if @ws_thread&.alive?
-
-      Smplkit.debug("websocket", "starting shared WebSocket background thread")
-      @closed = false
-      @connection_status = "connecting"
-      @ws_thread = Thread.new { run_reactor }
-      @ws_thread.name = "smplkit-shared-ws" if @ws_thread.respond_to?(:name=)
-    end
-
-    def stop
-      Smplkit.debug("websocket", "stopping shared WebSocket")
-      @closed = true
-      close_active_connection
-      thread = @ws_thread
-      @ws_thread = nil
-      if thread
-        thread.join(2.0)
-        thread.kill if thread.alive?
-      end
-      # Set authoritatively after the thread is dead so a racing connect
-      # call (which also sets "connecting") cannot clobber this value.
-      @connection_status = "disconnected"
-    end
-
-    # ----- URL builder ----------------------------------------------
-
-    def build_ws_url
-      url = @app_base_url.dup
-      ws_url =
-        if url.start_with?("https://")
-          "wss://#{url[("https://".length)..]}"
-        elsif url.start_with?("http://")
-          "ws://#{url[("http://".length)..]}"
-        else
-          "wss://#{url}"
-        end
-      ws_url = ws_url.chomp("/")
-      "#{ws_url}/api/ws/v1/events?api_key=#{@api_key}"
-    end
-
-    # ----- Inbound message handling (extracted for tests) -----------
-
-    # Process a single inbound text frame the way the live reactor does:
-    # +"ping"+ → call +send_pong+ with +"pong"+; otherwise parse JSON and,
-    # if a +"event"+ key is present, dispatch to listeners.
-    #
-    # Returns one of +:ping+, +:event+, +:no_event+, +:unparseable+ for the
-    # caller to log/observe; the live reactor ignores the return value.
-    def handle_inbound(text, send_pong:)
-      if text == "ping"
-        send_pong.call("pong")
-        return :ping
-      end
-
-      data =
-        begin
-          JSON.parse(text)
-        rescue JSON::ParserError
-          return :unparseable
-        end
-
-      event = data["event"]
-      if event
-        dispatch(event, data)
-        :event
-      else
-        :no_event
-      end
-    end
-
-    private
-
-    def run_reactor
-      Sync do |task|
-        ws_main(task)
-      end
-    rescue StandardError => e
-      Smplkit.debug("websocket", "shared WebSocket thread exited unexpectedly: #{e.class}: #{e.message}")
-    end
-
-    def ws_main(task)
-      connect(task)
-    rescue StandardError => e
-      return if @closed
-
-      Smplkit.debug(
-        "websocket",
-        "connection failed on startup (url: #{safe_url}): #{e.class}: #{e.message}"
-      )
-      reconnect(task)
-    end
-
-    def connect(task)
-      return if @closed
-
-      url = build_ws_url
-      @connection_status = "connecting"
-      Smplkit.debug("websocket", "connecting to #{safe_url}")
-
-      # Force HTTP/1.1 for the WebSocket upgrade. async-http defaults to
-      # HTTP/2 on TLS endpoints, but the smplkit event gateway speaks the
-      # classic RFC 6455 upgrade over HTTP/1.1, not the HTTP/2-tunneled
-      # variant from RFC 8441 — without this override the upgrade returns
-      # a Protocol::HTTP2::StreamError before any frame is exchanged.
-      endpoint = Async::HTTP::Endpoint.parse(url, protocol: Async::HTTP::Protocol::HTTP1)
-      headers = { "user-agent" => USER_AGENT }
-      connection = Async::WebSocket::Client.connect(endpoint, headers: headers)
-      @connection_lock.synchronize { @connection = connection }
-      Smplkit.debug("websocket", "WebSocket connected, waiting for confirmation")
-
-      raw = connection.read
-      data = JSON.parse(message_to_string(raw))
-      if data["type"] == "error"
-        err = data["message"]
-        Smplkit.debug("websocket", "connection error from server: #{err.inspect}")
-        raise "Connection error: #{err}"
-      end
-
-      @connection_status = "connected"
-      @metrics&.record_gauge("platform.websocket_connections", 1, unit: "connections")
-      receive_loop(task, connection)
-    end
-
-    def receive_loop(task, connection)
-      until @closed
-        message = connection.read
-        break if message.nil?
-
-        text = message_to_string(message)
-        handle_inbound(text, send_pong: ->(reply) { connection.write(reply) })
-      end
-    rescue StandardError => e
-      return if @closed
-
-      Smplkit.debug("websocket", "receive loop error: #{e.class}: #{e.message}")
-      @connection_status = "reconnecting"
-      @metrics&.record_gauge("platform.websocket_connections", 0, unit: "connections")
-      reconnect(task)
-    end
-
-    def reconnect(task)
-      attempt = 0
-      until @closed
-        delay = BACKOFF_SCHEDULE[[attempt, BACKOFF_SCHEDULE.length - 1].min]
-        Smplkit.debug("websocket", "reconnecting in #{delay}s (attempt #{attempt + 1})")
-        task.sleep(delay)
-        return if @closed
-
-        begin
-          connect(task)
-          return
-        rescue StandardError => e
-          Smplkit.debug("websocket", "reconnect attempt #{attempt + 1} failed: #{e.class}: #{e.message}")
-          attempt += 1
-        end
-      end
-    end
-
-    def message_to_string(message)
-      return message if message.is_a?(String)
-      return message.to_str if message.respond_to?(:to_str)
-
-      message.to_s
-    end
-
-    def close_active_connection
-      conn = @connection_lock.synchronize do
-        c = @connection
-        @connection = nil
-        c
-      end
-      return unless conn
-
-      begin
-        conn.close
-      rescue StandardError => e
-        Smplkit.debug("websocket", "close raised: #{e.class}: #{e.message}")
-      end
-    end
-
-    def safe_url
-      build_ws_url.split("?", 2).first
-    end
-  end
-end