smplkit 3.0.134 → 3.0.135

data/lib/smplkit/event_stream.rb

@@ -0,0 +1,453 @@
+# frozen_string_literal: true
+
+require "json"
+require "async"
+require "async/http/client"
+require "async/http/endpoint"
+
+module Smplkit
+  # Manages the single live-updates event stream to the app service.
+  #
+  # A single +EventStream+ instance is shared across all product modules
+  # (config, flags, logging) within one +Smplkit::Client+. Product modules
+  # register listeners for specific event names; the shared stream dispatches
+  # incoming events to the appropriate listeners. Modules also register
+  # refetch callbacks, invoked after every successful *re*connect so their
+  # caches recover anything the server published while the stream was down.
+  #
+  # The stream runs on a dedicated SDK-owned thread that hosts the +Async+
+  # reactor and the underlying +async-http+ I/O. Public methods are
+  # thread-safe and non-blocking.
+  #
+  # Wire protocol — Server-Sent Events (SSE) over plain HTTPS:
+  #
+  #   - +GET <app_base_url>/api/v1/events+ with +Accept: text/event-stream+
+  #     and +Authorization: Bearer <api_key>+.
+  #   - A 200 response with a +text/event-stream+ content type is a
+  #     successful connect; auth failure is a plain HTTP 401.
+  #   - Each SSE frame carries the event name in the +event:+ field and a
+  #     JSON object in +data:+ (+{"id": "<key>"}+ for single-resource
+  #     events, +{}+ for bulk refreshes and the initial +connected+ event).
+  #   - The server emits a +: keepalive+ comment frame every 30 seconds when
+  #     idle; any received bytes count as liveness. Reads that stall past
+  #     +READ_TIMEOUT+ seconds tear the connection down for a reconnect.
+  #   - The server's +retry:+ field seeds the reconnect backoff base.
+  #
+  # On disconnect the reactor reconnects with exponential backoff (base
+  # delay doubling up to +MAX_BACKOFF+ seconds), resetting to the base on
+  # every successful connect. +stop+ closes the stream from the outer
+  # thread; the reader exits and the daemon thread terminates.
+  class EventStream
+    # Seconds without any bytes from the server (events or keepalive
+    # comments) before the connection is considered dead — two missed
+    # 30-second server keepalives.
+    READ_TIMEOUT = 45
+
+    # Ceiling for the exponential reconnect backoff, in seconds.
+    MAX_BACKOFF = 60
+
+    # Initial reconnect backoff base, in seconds, used until the server
+    # supplies its own via the SSE +retry:+ field.
+    DEFAULT_RETRY = 1.0
+
+    # Sent on the stream request — the platform WAF rejects requests that
+    # carry no User-Agent. There is no caller-supplied header surface on the
+    # event stream, so the SDK default always applies.
+    USER_AGENT = Smplkit.user_agent.freeze
+
+    # Incremental parser for a +text/event-stream+ byte stream.
+    #
+    # Feed it raw chunks as they arrive; it returns the events completed by
+    # each chunk. Implements the SSE wire format: +\n+, +\r\n+, and +\r+
+    # line terminators (including a CRLF split across chunks), a leading
+    # UTF-8 BOM, comment lines (leading +:+), field values split across
+    # chunk boundaries, multiple +data:+ lines joined with +\n+, and the
+    # numeric +retry:+ field. Unknown fields are ignored.
+    class Parser
+      # One complete SSE event: +name+ is the event name (from the +event:+
+      # field, defaulting to +"message"+), +data+ the joined data payload.
+      Event = Struct.new(:name, :data, keyword_init: true)
+
+      UTF8_BOM = String.new("\xEF\xBB\xBF", encoding: Encoding::BINARY).freeze
+
+      # Milliseconds from the most recent valid +retry:+ field, or +nil+.
+      attr_reader :retry_ms
+
+      def initialize
+        @buffer = String.new(encoding: Encoding::BINARY)
+        @bom_pending = true
+        @event_type = ""
+        @data_lines = []
+        @retry_ms = nil
+      end
+
+      # Consume one chunk of the stream. Returns the (possibly empty) array
+      # of +Event+s completed by this chunk.
+      def feed(chunk)
+        @buffer << chunk.dup.force_encoding(Encoding::BINARY)
+        strip_bom if @bom_pending
+        events = []
+        while (line = next_line)
+          handle_line(line, events)
+        end
+        events
+      end
+
+      private
+
+      # Drop a UTF-8 BOM at the very start of the stream. The BOM is three
+      # bytes and may itself arrive split across chunks, so stay pending
+      # while the buffer is still a strict prefix of it.
+      def strip_bom
+        if @buffer.bytesize >= UTF8_BOM.bytesize
+          @buffer = @buffer.byteslice(UTF8_BOM.bytesize..) if @buffer.start_with?(UTF8_BOM)
+          @bom_pending = false
+        elsif !UTF8_BOM.start_with?(@buffer)
+          @bom_pending = false
+        end
+      end
+
+      # Extract the next complete line (terminator: +\n+, +\r\n+, or bare
+      # +\r+), or +nil+ if the buffer holds none. A CR as the final buffered
+      # byte is held back — it may be the first half of a CRLF whose LF is
+      # still in flight. Line splitting happens on the raw bytes (0x0A/0x0D
+      # never appear inside a UTF-8 multi-byte sequence); the completed line
+      # is re-tagged UTF-8.
+      def next_line
+        cr = @buffer.index("\r")
+        lf = @buffer.index("\n")
+        return nil if cr.nil? && lf.nil?
+
+        if cr && (lf.nil? || cr < lf)
+          return nil if cr == @buffer.bytesize - 1
+
+          line = @buffer.byteslice(0, cr)
+          skip = @buffer.getbyte(cr + 1) == 0x0A ? 2 : 1
+          @buffer = @buffer.byteslice(cr + skip, @buffer.bytesize - cr - skip)
+        else
+          line = @buffer.byteslice(0, lf)
+          @buffer = @buffer.byteslice(lf + 1, @buffer.bytesize - lf - 1)
+        end
+        line.force_encoding(Encoding::UTF_8)
+      end
+
+      # A blank line dispatches the accumulated event; a leading +:+ marks a
+      # comment (the server's keepalive frame) — ignored here, since mere
+      # receipt of its bytes already counted as liveness at the read layer.
+      def handle_line(line, events)
+        if line.empty?
+          flush_pending(events)
+        elsif !line.start_with?(":")
+          apply_field(*split_field(line))
+        end
+      end
+
+      # Split +"field: value"+ on the first colon, stripping at most one
+      # leading space from the value. A line with no colon is a field with
+      # an empty value.
+      def split_field(line)
+        sep = line.index(":")
+        return [line, ""] if sep.nil?
+
+        value = line[(sep + 1)..]
+        value = value[1..] if value.start_with?(" ")
+        [line[0...sep], value]
+      end
+
+      # +id:+ is deliberately ignored along with unknown fields — the SDK
+      # never resumes with +Last-Event-ID+.
+      def apply_field(field, value)
+        case field
+        when "event"
+          @event_type = value
+        when "data"
+          @data_lines << value
+        when "retry"
+          @retry_ms = Integer(value, 10) if value.match?(/\A\d+\z/)
+        end
+      end
+
+      # Blank line: emit the accumulated event. Per the SSE spec an event
+      # with an empty data buffer is discarded (the event type still
+      # resets); multiple +data:+ lines join with +\n+.
+      def flush_pending(events)
+        unless @data_lines.empty?
+          name = @event_type.empty? ? "message" : @event_type
+          events << Event.new(name: name, data: @data_lines.join("\n"))
+        end
+        @event_type = ""
+        @data_lines = []
+      end
+    end
+
+    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] = [] }
+      @refetch_callbacks = []
+      @listeners_lock = Mutex.new
+      @connection_status = "disconnected"
+      @closed = false
+      @stream_thread = nil
+      @client = nil
+      @response = nil
+      @connection_lock = Mutex.new
+      @retry_base = DEFAULT_RETRY
+      @attempt = 0
+      @ever_connected = false
+    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
+
+    # Register a refetch callback, invoked (with no arguments) after every
+    # successful *re*connect — never on the initial connect. Product modules
+    # use this to run their bulk-refresh path so caches recover events
+    # missed while the stream was down.
+    def on_reconnect(callback = nil, &block)
+      cb = callback || block
+      @listeners_lock.synchronize { @refetch_callbacks << cb }
+      cb
+    end
+
+    def off_reconnect(callback)
+      @listeners_lock.synchronize { @refetch_callbacks.delete(callback) }
+    end
+
+    # Dispatch +payload+ to every listener registered for +event_name+.
+    # Event names nothing subscribed to dispatch to zero listeners — unknown
+    # events are ignored by construction. Listener exceptions are caught and
+    # logged; one bad listener never blocks the rest.
+    def dispatch(event_name, payload)
+      callbacks = @listeners_lock.synchronize { @listeners[event_name].dup }
+      callbacks.each do |cb|
+        cb.call(payload)
+      rescue StandardError => e
+        Smplkit.debug("events", "listener for #{event_name} raised: #{e.class}: #{e.message}")
+      end
+    end
+
+    # ----- Connection status ----------------------------------------
+
+    attr_reader :connection_status
+
+    # ----- Lifecycle ------------------------------------------------
+
+    def start
+      return if @stream_thread&.alive?
+
+      Smplkit.debug("events", "starting shared event stream background thread")
+      @closed = false
+      @connection_status = "connecting"
+      @stream_thread = Thread.new { run_reactor }
+      @stream_thread.name = "smplkit-events" if @stream_thread.respond_to?(:name=)
+    end
+
+    def stop
+      Smplkit.debug("events", "stopping shared event stream")
+      @closed = true
+      close_active_connection
+      thread = @stream_thread
+      @stream_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_events_url
+      url = @app_base_url.dup
+      url = "https://#{url}" unless url.start_with?("https://", "http://")
+      "#{url.chomp("/")}/api/v1/events"
+    end
+
+    # ----- Inbound event handling (extracted for tests) -------------
+
+    # Process one parsed SSE event the way the live read loop does: parse
+    # the JSON payload and dispatch it to the listeners registered for the
+    # event name.
+    #
+    # Returns +:dispatched+ or +:unparseable+ for the caller to log/observe;
+    # the live read loop ignores the return value.
+    def handle_event(event_name, data)
+      payload =
+        begin
+          JSON.parse(data)
+        rescue JSON::ParserError
+          nil
+        end
+      unless payload.is_a?(Hash)
+        Smplkit.debug("events", "ignoring #{event_name.inspect} event with non-object payload")
+        return :unparseable
+      end
+
+      dispatch(event_name, payload)
+      :dispatched
+    end
+
+    private
+
+    def run_reactor
+      Sync do |task|
+        stream_main(task)
+      end
+    rescue StandardError => e
+      Smplkit.debug("events", "event stream thread exited unexpectedly: #{e.class}: #{e.message}")
+    end
+
+    # Connect/read/reconnect forever until +stop+. Every pass either ends
+    # with a clean server EOF or an exception (connect failure, read error,
+    # liveness timeout) — both funnel into the same backoff + retry.
+    def stream_main(task)
+      until @closed
+        begin
+          connect_and_stream(task)
+        rescue StandardError => e
+          return if @closed
+
+          Smplkit.debug("events", "stream error (url: #{build_events_url}): #{e.class}: #{e.message}")
+        end
+        return if @closed
+
+        @connection_status = "reconnecting"
+        delay = next_backoff_delay
+        Smplkit.debug("events", "reconnecting in #{delay}s")
+        task.sleep(delay)
+      end
+    end
+
+    # One connection lifetime: open the request, verify the SSE handshake,
+    # then read frames until EOF/error. The response and client are always
+    # torn down on the way out.
+    def connect_and_stream(task)
+      @connection_status = "connecting"
+      Smplkit.debug("events", "connecting to #{build_events_url}")
+      endpoint = Async::HTTP::Endpoint.parse(build_events_url)
+      client = Async::HTTP::Client.new(endpoint)
+      @connection_lock.synchronize { @client = client }
+      response = nil
+      begin
+        response = client.get(endpoint.path, request_headers)
+        @connection_lock.synchronize { @response = response }
+        verify_response!(response)
+        mark_connected
+        read_loop(task, response.body)
+      ensure
+        mark_disconnected
+        close_quietly(response)
+        close_quietly(client)
+        @connection_lock.synchronize do
+          @response = nil
+          @client = nil
+        end
+      end
+    end
+
+    def request_headers
+      [
+        ["accept", "text/event-stream"],
+        ["authorization", "Bearer #{@api_key}"],
+        ["user-agent", USER_AGENT]
+      ]
+    end
+
+    # A successful connect is exactly: HTTP 200 with a text/event-stream
+    # content type. Anything else (401 on bad auth, proxies serving HTML,
+    # ...) tears down and backs off.
+    def verify_response!(response)
+      status = response.status
+      content_type = response.headers["content-type"].to_s
+      return if status == 200 && content_type.start_with?("text/event-stream")
+
+      raise ConnectionError, "event stream connect failed: HTTP #{status} " \
+                             "(content-type: #{content_type.inspect})"
+    end
+
+    def mark_connected
+      reconnected = @ever_connected
+      @ever_connected = true
+      @attempt = 0
+      @connection_status = "connected"
+      @metrics&.record_gauge("platform.event_connections", 1, unit: "connections")
+      Smplkit.debug("events", reconnected ? "event stream reconnected" : "event stream connected")
+      run_refetch_callbacks if reconnected
+    end
+
+    # Leaving the connected state (only): flip the gauge and status. A
+    # connect attempt that never completed the handshake records nothing.
+    def mark_disconnected
+      return unless @connection_status == "connected"
+
+      @connection_status = "reconnecting"
+      @metrics&.record_gauge("platform.event_connections", 0, unit: "connections")
+    end
+
+    def run_refetch_callbacks
+      callbacks = @listeners_lock.synchronize { @refetch_callbacks.dup }
+      callbacks.each do |cb|
+        cb.call
+      rescue StandardError => e
+        Smplkit.debug("events", "refetch callback raised: #{e.class}: #{e.message}")
+      end
+    end
+
+    # Read chunks until EOF, feeding the SSE parser and dispatching the
+    # events it completes. Each read is individually wrapped in the liveness
+    # timeout, so any received bytes — including keepalive comment frames —
+    # reset the clock.
+    def read_loop(task, body)
+      parser = Parser.new
+      until @closed
+        chunk = task.with_timeout(READ_TIMEOUT) { body.read }
+        break if chunk.nil?
+
+        process_chunk(parser, chunk)
+      end
+    end
+
+    def process_chunk(parser, chunk)
+      parser.feed(chunk).each { |event| handle_event(event.name, event.data) }
+      @retry_base = parser.retry_ms / 1000.0 unless parser.retry_ms.nil?
+    end
+
+    # Exponential backoff: base, 2x, 4x, ... capped at MAX_BACKOFF. The
+    # base comes from the server's +retry:+ field (DEFAULT_RETRY until one
+    # arrives); +mark_connected+ resets the exponent on every successful
+    # connect. No jitter.
+    def next_backoff_delay
+      delay = [@retry_base * (2**@attempt), MAX_BACKOFF].min
+      @attempt += 1 if delay < MAX_BACKOFF
+      delay
+    end
+
+    def close_active_connection
+      response, client = @connection_lock.synchronize do
+        pair = [@response, @client]
+        @response = nil
+        @client = nil
+        pair
+      end
+      close_quietly(response)
+      close_quietly(client)
+    end
+
+    def close_quietly(resource)
+      resource&.close
+    rescue StandardError => e
+      Smplkit.debug("events", "close raised: #{e.class}: #{e.message}")
+    end
+  end
+end

data/lib/smplkit/flags/client.rb

@@ -18,18 +18,18 @@ require "digest"
 #   +json_flag+) whose +.get+ evaluates against the cached definitions, plus
 #   +refresh+ / +stats+ / +on_change+. The first live call transparently flushes
 #   discovery, fetches all flag definitions into the local cache, and opens the
-#   live-updates WebSocket — no explicit install step.
+#   live-updates event stream — no explicit install step.
 #
 # The client supports two construction shapes:
 #
 # * *Wired* into +Smplkit::Client+ — borrows the parent's flags transport for
-#   both runtime fetch and CRUD, the parent's shared WebSocket for the live
+#   both runtime fetch and CRUD, the parent's shared event stream for the live
 #   channel, and +client.platform.contexts+ for evaluation-context
 #   registration. This is the common path.
 # * *Standalone* — +FlagsClient.new(api_key: ..., base_url: ..., ...)+ builds
 #   and owns its own flags transport and a contexts client (against its own app
-#   transport), and on first live use opens and owns its own WebSocket. +close+
-#   tears down only the owned transports and owned WebSocket.
+#   transport), and on first live use opens and owns its own event stream.
+#   +close+ tears down only the owned transports and owned event stream.
 module Smplkit
   module Flags
     # Describes a flag definition change. Frozen — fields are set at construction.
@@ -37,7 +37,7 @@ module Smplkit
     # @!attribute [r] id
     #   @return [String] id of the flag whose definition changed.
     # @!attribute [r] source
-    #   @return [String] origin of the change (e.g. +"websocket"+ for a live
+    #   @return [String] origin of the change (e.g. +"push"+ for a live
     #     update or +"manual"+ for a refresh).
     # @!attribute [r] deleted
     #   @return [Boolean] whether the change was a deletion of the flag.
@@ -148,7 +148,7 @@ module Smplkit
     # defaults). +environment+/+service+ resolve the same way (constructor
     # argument wins). The app transport backs the standalone contexts client
     # (evaluation-context registration); the app base URL is returned so a
-    # standalone client can open its own WebSocket against the event gateway.
+    # standalone client can open its own event stream against the app service.
     #
     # @api private
     def self.flags_transport(api_key:, base_url:, profile:, base_domain:, scheme:,
@@ -186,8 +186,8 @@ module Smplkit
     # is pure CRUD. The live surface (+boolean_flag+ / +string_flag+ /
     # +number_flag+ / +json_flag+ / +refresh+ / +stats+ / +on_change+) connects
     # lazily on first use — the first call flushes discovery, fetches all flag
-    # definitions into the local cache, and opens the live-updates WebSocket. No
-    # explicit install step is required.
+    # definitions into the local cache, and opens the live-updates event
+    # stream. No explicit install step is required.
     class FlagsClient
       # @param api_key [String, nil] API key. When omitted, resolved from
       #   +SMPLKIT_API_KEY+ or +~/.smplkit+.
@@ -207,8 +207,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+): the first live call opens a shared socket and flag changes
+      # @param streaming [Boolean] Live updates over the event stream (default
+      #   +true+): the first live call opens a shared stream and flag changes
       #   stream in. Set +false+ for the stateless read-through surface: the
       #   first live call still fetches all flag definitions once (blocking),
       #   evaluation stays local, +refresh+ re-fetches on demand, and NO socket
@@ -263,13 +263,13 @@ module Smplkit
         # Live-surface state.
         @flag_store = {}
         @connected = false
-        @ws_subscribed = false
+        @stream_subscribed = false
         @cache = ResolutionCache.new
         @handles = {}
         @global_listeners = []
         @key_listeners = Hash.new { |h, k| h[k] = [] }
-        @ws_manager = nil
-        @owns_ws = false
+        @event_stream = nil
+        @owns_stream = false
         @lock = Mutex.new
       end
 
@@ -566,16 +566,16 @@ module Smplkit
 
       # Release resources — only those this client owns.
       #
-      # Tears down the owned WebSocket (standalone install). A wired client
-      # borrows the parent's transport, WebSocket, and contexts client and
+      # Tears down the owned event stream (standalone install). A wired client
+      # borrows the parent's transport, event stream, and contexts client and
       # closes none of them.
       #
       # @return [void]
       def close
-        if @owns_ws && @ws_manager
-          @ws_manager.stop
-          @ws_manager = nil
-          @owns_ws = false
+        if @owns_stream && @event_stream
+          @event_stream.stop
+          @event_stream = nil
+          @owns_stream = false
         end
         # Owned flags/app transports (standalone construction) release their
         # Faraday connections on GC; there is no explicit shutdown to call.
@@ -680,29 +680,31 @@ module Smplkit
       end
 
       # ----------------------------------------------------------------
-      # Live surface: lazy connect + transport / WebSocket helpers
+      # Live surface: lazy connect + transport / event stream helpers
       # ----------------------------------------------------------------
 
-      def ensure_ws
-        return @parent._ensure_ws unless @parent.nil?
+      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
 
       # Open the live connection to the running Smpl Flags service.
       #
       # Flushes any buffered discovery declarations, fetches all flag
-      # definitions into the local cache, opens the shared WebSocket, and
+      # definitions into the local cache, opens the shared event stream, and
       # subscribes to +flag_changed+ / +flag_deleted+ / +flags_changed+ events.
-      # In stateless mode (+streaming: false+) no socket is ever created;
-      # +refresh+ re-fetches on demand.
+      # Also registers 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; +refresh+ re-fetches on
+      # demand.
       #
       # Idempotent and internal — every live method calls it on first use, so
       # the live surface auto-connects with no explicit step.
@@ -723,13 +725,14 @@ module Smplkit
         @connected = true
         return unless @streaming
 
-        @ws_manager = ensure_ws
-        return if @ws_subscribed
+        @event_stream = ensure_event_stream
+        return if @stream_subscribed
 
-        @ws_manager.on("flag_changed") { |data| handle_flag_changed(data) }
-        @ws_manager.on("flag_deleted") { |data| handle_flag_deleted(data) }
-        @ws_manager.on("flags_changed") { |data| handle_flags_changed(data) }
-        @ws_subscribed = true
+        @event_stream.on("flag_changed") { |data| handle_flag_changed(data) }
+        @event_stream.on("flag_deleted") { |data| handle_flag_deleted(data) }
+        @event_stream.on("flags_changed") { |data| handle_flags_changed(data) }
+        @event_stream.on_reconnect { handle_flags_changed({}) }
+        @stream_subscribed = true
       end
 
       def do_refresh(_source)
@@ -759,7 +762,7 @@ module Smplkit
       end
 
       # ----------------------------------------------------------------
-      # Internal: event handlers (called by SharedWebSocket)
+      # Internal: event handlers (called by EventStream)
       # ----------------------------------------------------------------
 
       def handle_flag_changed(data)
@@ -770,7 +773,7 @@ module Smplkit
         new_data = fetch_flag_single_data(key)
         @flag_store[key] = new_data
         @cache.clear
-        fire_change_listeners(key, "websocket") if pre != new_data
+        fire_change_listeners(key, "push") if pre != new_data
       end
 
       def handle_flag_deleted(data)
@@ -780,7 +783,7 @@ module Smplkit
         existed = @flag_store.key?(key)
         @flag_store.delete(key)
         @cache.clear
-        fire_change_listeners(key, "websocket", deleted: true) if existed
+        fire_change_listeners(key, "push", deleted: true) if existed
       end
 
       def handle_flags_changed(_data)
@@ -788,7 +791,7 @@ module Smplkit
         begin
           fetch_all_flags
         rescue StandardError => e
-          Smplkit.debug("ws", "flags refresh after flags_changed failed: #{e.message}")
+          Smplkit.debug("flags", "flags refresh after flags_changed failed: #{e.message}")
           return
         end
         @cache.clear
@@ -798,7 +801,7 @@ module Smplkit
         return if changed.empty?
 
         # Global listener fires once.
-        first_event = FlagChangeEvent.new(id: changed.first, source: "websocket")
+        first_event = FlagChangeEvent.new(id: changed.first, source: "push")
         @global_listeners.each do |cb|
           cb.call(first_event)
         rescue StandardError => e
@@ -808,7 +811,7 @@ module Smplkit
         # Per-key listeners fire for each changed key.
         changed.each do |k|
           deleted = pre_store.key?(k) && !post_store.key?(k)
-          event = FlagChangeEvent.new(id: k, source: "websocket", deleted: deleted)
+          event = FlagChangeEvent.new(id: k, source: "push", deleted: deleted)
           @key_listeners[k].each do |cb|
             cb.call(event)
           rescue StandardError => e

data/lib/smplkit/jobs/client.rb

@@ -268,8 +268,8 @@ module Smplkit
     # The Smpl Jobs client — accessed via +client.jobs+.
     #
     # Unlike Config/Flags/Logging, Jobs has no live "phone-home" agent — no
-    # environment registration, no WebSocket — so its entire surface lives on
-    # one client. Defining a job, triggering a run, and reading run history are
+    # environment registration, no event stream — so its entire surface lives
+    # on one client. Defining a job, triggering a run, and reading run history are
     # all plain request/response calls here:
     #
     #   client.jobs.{new_recurring_job,new_manual_job,schedule,get,list,delete,run,usage}