smplkit 1.0.9 → 1.0.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c58128ff207d255ca61de78cd05db65a37dce681d7940441db0a10acddd5e7a
-  data.tar.gz: 73500c410292e3a5a6daefa1a75ffaa0b9a61f951e50c9f8f52a1b5a893dd38a
+  metadata.gz: 42f9ef066eeb2612d4c6c4cc042933337e10562047eb41400506466a47ec4e99
+  data.tar.gz: 69d8819176f26b5199f2c508a71d77397106bfabe0ea5b99b071a3e83199dd0d
 SHA512:
-  metadata.gz: 0f55ecc713c6c7171b52469098c6f9b3268d1bf43fe66ec8da85eb1d1a5293cb1f0e801c975cd1db4a9d15c3e509319b382b5f98220beb26d2761e7b78781cc1
-  data.tar.gz: 7c5a33b527b9d042919b62c570ba14578607131386f1bcba9a6ede04f99f0d97ae9288287f99f9bad0bb826f3f12970196e82908fbf56d5e70c43ea0768d75dc
+  metadata.gz: 8f05531a8b81d3aa42895ed48f8e7b1680d9cf9a490c356b5ce4cf311b304d862964cb49e18b72e7e982ce1e351b2f7be2234c0be06be6c58cae3d3566c37c53
+  data.tar.gz: f45d376af397dad147c4ae24100bdfd990766e511ce4a2de10539e3d358375098c413bf46f09c7f8e149d0333aa3c5efdca88baaebdd275ebda03490fff5370c

data/lib/smplkit/ws.rb

@@ -1,42 +1,55 @@
 # frozen_string_literal: true
 
+require "json"
+require "async"
+require "async/http/endpoint"
+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) within one +Smplkit::Client+. Product modules register
-  # listeners for specific event types; the shared connection dispatches
-  # incoming events to the appropriate listeners.
+  # (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; public methods are
-  # thread-safe and non-blocking.
+  # 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 (mirrors the Python reference in +smplkit._ws+):
   #
-  # The app service 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
+  #   - No subscribe message — the API key determines the account
   #   - Heartbeat: server sends +"ping"+ (text), client responds with +"pong"+
   #
-  # NOTE: The actual WebSocket I/O is wired to async-websocket on a worker
-  # thread. The initial Ruby SDK release defers full live-update wiring to a
-  # follow-up because async-websocket interactions need integration testing
-  # against the real platform.
+  # 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
 
+    USER_AGENT = "smplkit-ruby-sdk/#{Smplkit::VERSION}".freeze
+
     def initialize(app_base_url:, api_key:, metrics: nil)
       @app_base_url = app_base_url
       @api_key = api_key
       @metrics = metrics
-      @listeners = Concurrent::Hash.new { |h, k| h[k] = [] }
+      @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
@@ -45,6 +58,9 @@ module Smplkit
       @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|
@@ -54,39 +70,186 @@ module Smplkit
       end
     end
 
+    # ----- Connection status ----------------------------------------
+
     attr_reader :connection_status
 
-    # Marked as connected for in-process testing without a real WS connection.
-    # Production wiring overrides this from the I/O thread once the gateway
-    # confirms the handshake.
-    def mark_connected!
-      @connection_status = "connected"
-    end
+    # ----- Lifecycle ------------------------------------------------
 
     def start
-      Smplkit.debug("websocket", "starting shared WebSocket (Ruby SDK initial release: in-memory only)")
-      # Live wiring is deferred. Behave as if the handshake succeeded so the
-      # rest of the runtime can proceed - listeners still fire for any events
-      # other code dispatches into this instance.
-      mark_connected!
+      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
       @connection_status = "disconnected"
+      close_active_connection
+      thread = @ws_thread
+      @ws_thread = nil
+      return unless thread
+
+      thread.join(2.0)
+      thread.kill if thread.alive?
     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 =
+        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)
+      url = build_ws_url
+      @connection_status = "connecting"
+      Smplkit.debug("websocket", "connecting to #{safe_url}")
+
+      endpoint = Async::HTTP::Endpoint.parse(url)
+      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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: smplkit
 version: !ruby/object:Gem::Version
-  version: 1.0.9
+  version: 1.0.10
 platform: ruby
 authors:
 - Smpl Solutions LLC
@@ -9,6 +9,48 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: async
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.39'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.39'
+- !ruby/object:Gem::Dependency
+  name: async-http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.95'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.95'
+- !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'
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
   requirement: !ruby/object:Gem::Requirement