chat_sdk 1.0.1 → 1.2.0

data/lib/chat_sdk/chat.rb

@@ -2,13 +2,15 @@
 
 module ChatSDK
   class Chat
-    attr_reader :config, :state
+    attr_reader :config, :state, :history
 
     def initialize(user_name:, adapters:, state:, **options)
       @config = Config.new(user_name: user_name, adapters: adapters, state: state, **options)
       @state = state
       @adapters = adapters
+      @adapters.each_value { |adapter| adapter.set_state(state) if adapter.respond_to?(:set_state) }
       @registry = EventRegistry.new
+      @history = History.new(self)
       @webhooks = {}
       @dispatcher = Dispatcher.new(chat: self, config: @config, state: @state, registry: @registry)
 
@@ -25,13 +27,26 @@ module ChatSDK
     end
 
     def on_new_message(pattern = nil, &block)
-      @registry.register(:mention, matcher: pattern, &block)
+      unless pattern.nil? || pattern.is_a?(Regexp)
+        raise ChatSDK::ConfigurationError, "on_new_message pattern must be a Regexp or nil"
+      end
+      raise ChatSDK::ConfigurationError, "on_new_message requires a block" unless block
+
+      @registry.register(:new_message, matcher: pattern, &block)
     end
 
     def on_direct_message(&block)
       @registry.register(:direct_message, &block)
     end
 
+    def on_message_updated(&block)
+      @registry.register(:message_updated, &block)
+    end
+
+    def on_message_deleted(&block)
+      @registry.register(:message_deleted, &block)
+    end
+
     def on_reaction(emojis = nil, &block)
       @registry.register(:reaction, matcher: emojis, &block)
     end
@@ -44,6 +59,14 @@ module ChatSDK
       @registry.register(:slash_command, matcher: command, &block)
     end
 
+    def on_installed(&block)
+      @registry.register(:installed, &block)
+    end
+
+    def on_uninstalled(&block)
+      @registry.register(:uninstalled, &block)
+    end
+
     # Adapter access
     def adapter(name)
       @adapters.fetch(name) { raise ChatSDK::ConfigurationError, "Unknown adapter: #{name}" }
@@ -61,6 +84,11 @@ module ChatSDK
       Channel.new(id: channel_id, adapter: adp, chat: self)
     end
 
+    def thread(id, channel_id:, adapter_name: nil)
+      adp = adapter_name ? adapter(adapter_name) : @adapters.values.first
+      Thread.new(id: id, channel_id: channel_id, adapter: adp, chat: self)
+    end
+
     # Webhook endpoints (Rack apps)
     def webhooks
       @webhook_accessor ||= WebhookAccessor.new(self, @adapters)
@@ -72,6 +100,11 @@ module ChatSDK
       @dispatcher.dispatch(event, adapter: adp, adapter_name: adapter_name)
     end
 
+    # Deprecated compatibility alias for Vercel Chat SDK's former API.
+    def transcripts
+      history.user
+    end
+
     private
   end
 

data/lib/chat_sdk/config.rb

@@ -6,12 +6,16 @@ module ChatSDK
       dedupe_ttl: 600,
       streaming_update_interval: 0.5,
       on_lock_conflict: :drop,
+      concurrency: nil,
+      lock_scope: :thread,
       handler_executor: :inline,
+      history: {},
       log_level: :info
     }.freeze
 
     attr_reader :user_name, :adapters, :state, :on_lock_conflict,
-      :dedupe_ttl, :streaming_update_interval, :handler_executor, :log_level
+      :dedupe_ttl, :streaming_update_interval, :handler_executor, :log_level,
+      :history_user, :concurrency
 
     def initialize(user_name:, adapters:, state:, **options)
       raise ConfigurationError, "user_name is required" if user_name.nil? || user_name.empty?
@@ -23,9 +27,17 @@ module ChatSDK
       @state = state
       merged = DEFAULTS.merge(options)
       @on_lock_conflict = merged[:on_lock_conflict]
+      @concurrency = normalize_concurrency(merged[:concurrency], lock_scope: merged[:lock_scope])
       @dedupe_ttl = merged[:dedupe_ttl]
       @streaming_update_interval = merged[:streaming_update_interval]
       @handler_executor = merged[:handler_executor]
+      history = merged[:history] || {}
+      user_history = history[:user] || history["user"] || {}
+      @history_user = {
+        identity: user_history[:identity] || user_history["identity"] || merged[:identity],
+        retention: user_history.fetch(:retention, user_history.fetch("retention", 30 * 24 * 3600)),
+        max_per_user: user_history.fetch(:max_per_user, user_history.fetch("max_per_user", 200))
+      }
       @log_level = merged[:log_level]
 
       validate_lock_conflict!
@@ -37,5 +49,40 @@ module ChatSDK
       return if %i[drop force].include?(@on_lock_conflict) || @on_lock_conflict.respond_to?(:call)
       raise ConfigurationError, "on_lock_conflict must be :drop, :force, or a callable"
     end
+
+    def normalize_concurrency(value, lock_scope:)
+      supplied = if value.nil?
+        {}
+      elsif value.is_a?(Hash)
+        value
+      else
+        {strategy: value}
+      end
+      supplied = supplied.transform_keys(&:to_sym)
+      supplied[:debounce] = supplied.delete(:debounce_ms).to_f / 1000 if supplied.key?(:debounce_ms)
+      supplied[:queue_entry_ttl] = supplied.delete(:queue_entry_ttl_ms).to_f / 1000 if supplied.key?(:queue_entry_ttl_ms)
+      supplied[:max_lock_lifetime] = supplied.delete(:max_lock_lifetime_ms).to_f / 1000 if supplied.key?(:max_lock_lifetime_ms)
+      supplied[:lock_ttl] = supplied.delete(:lock_ttl_ms).to_f / 1000 if supplied.key?(:lock_ttl_ms)
+      config = {
+        strategy: :drop,
+        max_queue_size: 10,
+        on_queue_full: :drop_oldest,
+        queue_entry_ttl: 90,
+        debounce: 1.5,
+        lock_ttl: 30,
+        max_lock_lifetime: 600,
+        max_concurrent: nil,
+        lock_scope: lock_scope
+      }.merge(supplied)
+      config[:strategy] = config[:strategy].to_sym
+      config[:on_queue_full] = config[:on_queue_full].to_s.tr("-", "_").to_sym
+      unless %i[drop force queue burst debounce concurrent].include?(config[:strategy])
+        raise ConfigurationError, "concurrency strategy must be :drop, :queue, :burst, :debounce, or :concurrent"
+      end
+      if config[:max_concurrent] && config[:max_concurrent].to_i < 1
+        raise ConfigurationError, "max_concurrent must be at least 1"
+      end
+      config
+    end
   end
 end

data/lib/chat_sdk/dispatcher.rb

@@ -1,40 +1,167 @@
 # frozen_string_literal: true
 
+require "securerandom"
+require "time"
+
 module ChatSDK
   class Dispatcher
+    LockHeartbeat = Struct.new(:thread, :mutex, :condition, :stop, :ownership_lost) do
+      def ownership_lost?
+        mutex.synchronize { ownership_lost }
+      end
+    end
+
     def initialize(chat:, config:, state:, registry:)
       @chat = chat
       @config = config
       @state = state
       @registry = registry
+      @slot_mutex = Mutex.new
+      @slot_condition = ConditionVariable.new
+      @active_slots = Hash.new(0)
     end
 
     def dispatch(event, adapter:, adapter_name:)
       ChatSDK::Instrumentation.instrument("dispatch.chat_sdk", adapter: adapter_name, event_type: event.type) do
-        return unless dedupe(event, adapter_name)
+        if %i[message_updated message_deleted].include?(event.type)
+          return execute_event(event, build_thread(event, adapter))
+        end
+
+        concurrency_scope = adapter.concurrency_scope(event)
+        return unless dedupe(event, adapter_name, concurrency_scope)
 
         thread = build_thread(event, adapter)
-        thread_key = thread_key_for(event, adapter_name)
+        thread_key = thread_key_for(event, adapter_name, concurrency_scope)
+        strategy = @config.concurrency[:strategy]
 
-        return unless acquire_lock(thread_key, event)
+        if strategy == :concurrent
+          return with_concurrent_slot(thread_key) { execute_event(event, thread) }
+        end
 
-        begin
-          handlers = @registry.handlers_for(event)
-          handlers.each { |handler| execute_handler(handler, event, thread) }
-        ensure
-          release_lock(thread_key)
+        owner = "#{Process.pid}:#{::Thread.current.object_id}:#{SecureRandom.uuid}"
+        if %i[queue burst debounce].include?(strategy)
+          dispatch_queued(event, adapter, thread_key, owner, strategy)
+        else
+          dispatch_locked(event, thread, thread_key, owner, strategy)
         end
       end
     end
 
     private
 
-    def dedupe(event, adapter_name)
+    def dispatch_locked(event, thread, thread_key, owner, strategy)
+      acquired = acquire_lock(thread_key, event, owner, force: strategy == :force)
+      return unless acquired
+
+      heartbeat = start_lock_heartbeat(thread_key, owner)
+      execute_event(event, thread)
+    ensure
+      stop_lock_heartbeat(heartbeat)
+      release_lock(thread_key, owner) if acquired
+    end
+
+    def dispatch_queued(event, adapter, thread_key, owner, strategy)
+      queue_key = "chat_sdk:queue:#{thread_key}"
+      acquired = acquire_lock(thread_key, event, owner, apply_conflict_policy: false)
+      pre_enqueued = false
+
+      unless acquired
+        enqueue(queue_key, event)
+        pre_enqueued = true
+        acquired = acquire_lock(thread_key, event, owner, apply_conflict_policy: false)
+        return unless acquired
+      end
+
+      heartbeat = start_lock_heartbeat(thread_key, owner)
+      if strategy == :queue
+        execute_event(event, build_thread(event, adapter)) unless pre_enqueued
+      else
+        enqueue(queue_key, event) unless pre_enqueued
+        sleep(@config.concurrency[:debounce].to_f) if strategy == :burst
+      end
+
+      if strategy == :debounce
+        debounce_loop(queue_key, adapter, heartbeat)
+      else
+        drain_loop(queue_key, adapter, strategy, heartbeat)
+      end
+    ensure
+      stop_lock_heartbeat(heartbeat)
+      release_lock(thread_key, owner) if acquired
+    end
+
+    def drain_loop(queue_key, adapter, strategy, heartbeat)
+      loop do
+        break if heartbeat&.ownership_lost?
+
+        entries = fresh_entries(@state.drain_queue(queue_key))
+        break if entries.empty?
+
+        events = entries.map { |entry| EventSerializer.load(entry.fetch("event")) }
+        current = events.last
+        skipped = if strategy == :debounce
+          []
+        else
+          events[0...-1].filter_map { |queued| queued.message if queued.respond_to?(:message) }
+        end
+        context = {skipped: skipped, total_since_last_handler: skipped.length + 1}
+        execute_event(current, build_thread(current, adapter), context: context)
+        ::Thread.pass
+      end
+    end
+
+    def debounce_loop(queue_key, adapter, heartbeat)
+      skipped = []
+      loop do
+        sleep(@config.concurrency[:debounce].to_f)
+        break if heartbeat&.ownership_lost?
+
+        entries = fresh_entries(@state.drain_queue(queue_key))
+        break if entries.empty?
+
+        events = entries.map { |entry| EventSerializer.load(entry.fetch("event")) }
+        latest = events.last
+        skipped.concat(events[0...-1].filter_map { |queued| queued.message if queued.respond_to?(:message) })
+
+        if @state.queue_depth(queue_key).positive?
+          skipped << latest.message if latest.respond_to?(:message)
+          next
+        end
+
+        relevant = skipped.select do |message|
+          message.thread_id == latest.thread_id
+        end
+        context = {skipped: relevant, total_since_last_handler: relevant.length + 1}
+        execute_event(latest, build_thread(latest, adapter), context: context)
+        skipped.clear
+      end
+    end
+
+    def enqueue(queue_key, event)
+      entry = {"event" => EventSerializer.dump(event), "enqueued_at" => Time.now.iso8601}
+      @state.enqueue(
+        queue_key,
+        entry,
+        max_size: @config.concurrency[:max_queue_size],
+        drop: @config.concurrency[:on_queue_full]
+      )
+    end
+
+    def fresh_entries(entries)
+      cutoff = Time.now - @config.concurrency[:queue_entry_ttl].to_f
+      entries.select do |entry|
+        Time.iso8601(entry.fetch("enqueued_at")) >= cutoff
+      rescue ArgumentError, KeyError
+        false
+      end
+    end
+
+    def dedupe(event, adapter_name, concurrency_scope)
       event_id = extract_event_id(event)
       return true unless event_id
 
       is_new = @state.set_if_absent(
-        "chat_sdk:dedupe:#{adapter_name}:#{event_id}",
+        dedupe_key(adapter_name, concurrency_scope, event_id),
         true,
         ttl: @config.dedupe_ttl
       )
@@ -45,41 +172,85 @@ module ChatSDK
     def extract_event_id(event)
       if event.respond_to?(:message) && event.message
         event.message.id
+      elsif event.respond_to?(:message_id) && event.message_id
+        "#{event.type}:#{event.message_id}:#{event.timestamp.to_f}"
       elsif event.respond_to?(:raw) && event.raw.is_a?(Hash)
         event.raw[:event_id] || event.raw["event_id"]
       end
     end
 
-    def thread_key_for(event, adapter_name)
-      channel_id = event.respond_to?(:channel_id) ? event.channel_id : nil
-      thread_id = event.respond_to?(:thread_id) ? event.thread_id : nil
-      "#{adapter_name}:#{channel_id}:#{thread_id}"
+    def dedupe_key(adapter_name, concurrency_scope, event_id)
+      prefix = ["chat_sdk:dedupe", adapter_name]
+      prefix << concurrency_scope if concurrency_scope
+      "#{prefix.join(":")}:#{event_id}"
     end
 
-    def lock_owner
-      @lock_owner ||= "#{Process.pid}:#{::Thread.current.object_id}"
+    def thread_key_for(event, adapter_name, concurrency_scope)
+      channel_id = event.respond_to?(:channel_id) ? event.channel_id : nil
+      thread_id = event.respond_to?(:thread_id) ? event.thread_id : nil
+      lock_scope = @config.concurrency[:lock_scope]
+      scope_id = (lock_scope&.to_sym == :channel) ? channel_id : thread_id
+      [adapter_name, concurrency_scope, channel_id, scope_id].compact.join(":")
     end
 
-    def acquire_lock(thread_key, event)
+    def acquire_lock(thread_key, event, owner, force: false, apply_conflict_policy: true)
       lock_key = "chat_sdk:lock:#{thread_key}"
-      acquired = @state.acquire_lock(lock_key, owner: lock_owner, ttl: 30)
+      acquired = @state.acquire_lock(lock_key, owner: owner, ttl: @config.concurrency[:lock_ttl])
 
-      unless acquired
-        policy = @config.on_lock_conflict
+      if !acquired && apply_conflict_policy
+        policy = force ? :force : @config.on_lock_conflict
         policy = policy.call(thread_key, event) if policy.respond_to?(:call)
-
         if policy == :force
-          @state.force_lock(lock_key, owner: lock_owner, ttl: 30)
+          @state.force_lock(lock_key, owner: owner, ttl: @config.concurrency[:lock_ttl])
           acquired = true
         end
       end
 
-      ChatSDK::Instrumentation.instrument("lock.chat_sdk", key: thread_key, acquired: acquired, policy: acquired ? nil : policy)
+      ChatSDK::Instrumentation.instrument("lock.chat_sdk", key: thread_key, acquired: acquired)
       acquired
     end
 
-    def release_lock(thread_key)
-      @state.release_lock("chat_sdk:lock:#{thread_key}", owner: lock_owner)
+    def release_lock(thread_key, owner)
+      @state.release_lock("chat_sdk:lock:#{thread_key}", owner: owner)
+    end
+
+    def start_lock_heartbeat(thread_key, owner)
+      lock_ttl = @config.concurrency[:lock_ttl].to_f
+      max_lifetime = @config.concurrency[:max_lock_lifetime].to_f
+      mutex = Mutex.new
+      condition = ConditionVariable.new
+      heartbeat = LockHeartbeat.new(mutex: mutex, condition: condition, stop: false, ownership_lost: false)
+      heartbeat.thread = ::Thread.new do
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        interval = [lock_ttl / 3.0, 0.01].max
+        loop do
+          should_stop = mutex.synchronize do
+            condition.wait(mutex, interval) unless heartbeat.stop
+            heartbeat.stop
+          end
+          break if should_stop
+          break if Process.clock_gettime(Process::CLOCK_MONOTONIC) - started >= max_lifetime
+
+          extended = @state.extend_lock("chat_sdk:lock:#{thread_key}", owner: owner, ttl: lock_ttl)
+          unless extended
+            mutex.synchronize { heartbeat.ownership_lost = true }
+            break
+          end
+        rescue NotImplementedError
+          break
+        end
+      end
+      heartbeat
+    end
+
+    def stop_lock_heartbeat(heartbeat)
+      return unless heartbeat
+
+      heartbeat.mutex.synchronize do
+        heartbeat.stop = true
+        heartbeat.condition.signal
+      end
+      heartbeat.thread.join
     end
 
     def build_thread(event, adapter)
@@ -87,17 +258,75 @@ module ChatSDK
       channel_id = event.respond_to?(:channel_id) ? event.channel_id : nil
       return nil unless thread_id && channel_id
 
-      ChatSDK::Thread.new(id: thread_id, channel_id: channel_id, adapter: adapter, chat: @chat)
+      current_message = event.respond_to?(:message) ? event.message : nil
+      ChatSDK::Thread.new(id: thread_id, channel_id: channel_id, adapter: adapter, chat: @chat, current_message: current_message)
+    end
+
+    def execute_event(event, thread, context: nil)
+      if %i[mention subscribed_message direct_message].include?(event.type)
+        route_message_event(event, thread, context)
+        return
+      end
+
+      @registry.handlers_for(event).each do |handler|
+        execute_handler(handler, event, thread, context: context)
+      end
     end
 
-    def execute_handler(handler, event, thread)
+    def route_message_event(event, thread, context)
+      message = event.message
+      dm_handlers = @registry.handlers_for_type(:direct_message, event: event)
+      if event.type == :direct_message && dm_handlers.any?
+        run_handlers(dm_handlers, event, thread, context)
+        return
+      end
+
+      message.is_mention = true if event.type == :direct_message
+
+      if thread&.subscribed?
+        run_handlers(@registry.handlers_for_type(:subscribed_message, event: event), event, thread, context)
+        return
+      end
+
+      if message.is_mention.nil?
+        message.is_mention = if event.type == :mention
+          true
+        else
+          detect_mention(message.text)
+        end
+      end
+
+      if message.is_mention
+        run_handlers(@registry.handlers_for_type(:mention, event: event), event, thread, context)
+        return
+      end
+
+      @registry.handlers_for_type(:new_message, event: event).each do |handler|
+        execute_handler(handler, event, thread, context: context)
+      end
+    end
+
+    def run_handlers(handlers, event, thread, context)
+      handlers.each { |handler| execute_handler(handler, event, thread, context: context) }
+    end
+
+    def detect_mention(text)
+      masked_text = ChatSDK::Format::Mentions.mask_code_spans(text)
+      /(?<![[:word:]])@#{Regexp.escape(@config.user_name)}\b/i.match?(masked_text)
+    end
+
+    def execute_handler(handler, event, thread, context: nil)
       ChatSDK::Instrumentation.instrument("handler.chat_sdk", handler_type: event.type) do
-        case event.type
-        when :mention, :subscribed_message, :direct_message
-          handler.block.call(thread, event.message)
-        when :reaction, :action, :slash_command
-          add_thread_to_event(event, thread)
-          handler.block.call(event)
+        ChatSDK::AI::ConversationScope.with(thread) do
+          case event.type
+          when :mention, :subscribed_message, :direct_message, :new_message
+            handler.block.call(thread, event.message, context)
+          when :message_updated
+            handler.block.call(thread, event.message, event.previous_message)
+          when :reaction, :action, :slash_command, :message_deleted, :installed, :uninstalled
+            add_thread_to_event(event, thread)
+            handler.block.call(event)
+          end
         end
       end
     rescue => e
@@ -108,5 +337,23 @@ module ChatSDK
     def add_thread_to_event(event, thread)
       event.thread = thread if event.respond_to?(:thread=)
     end
+
+    def with_concurrent_slot(key)
+      max = @config.concurrency[:max_concurrent]
+      return yield unless max
+
+      @slot_mutex.synchronize do
+        @slot_condition.wait(@slot_mutex) while @active_slots[key] >= max
+        @active_slots[key] += 1
+      end
+      yield
+    ensure
+      if max
+        @slot_mutex.synchronize do
+          @active_slots[key] -= 1
+          @slot_condition.broadcast
+        end
+      end
+    end
   end
 end

data/lib/chat_sdk/event_registry.rb

@@ -13,13 +13,18 @@ module ChatSDK
     end
 
     def handlers_for(event)
-      @handlers.select { |h| matches?(h, event) }
+      handlers_for_type(event.type, event: event)
+    end
+
+    def handlers_for_type(type, event: nil)
+      @handlers.select do |handler|
+        handler.type == type && (!event || matches?(handler, event))
+      end
     end
 
     private
 
     def matches?(handler, event)
-      return false unless handler.type == event.type
       return true if handler.matcher.nil?
 
       case handler.matcher