turbo_chat 0.1.0

data/lib/chat_gem/moderation.rb

@@ -0,0 +1,194 @@
+module ChatGem
+  module Moderation
+    class AuthorizationError < StandardError; end
+    class InvalidActionError < StandardError; end
+
+    class << self
+      def mute_member!(actor:, membership:)
+        updated_membership = authorize_and_update_membership!(
+          actor: actor,
+          membership: membership,
+          action: :can_mute_member?,
+          attributes: { muted: true }
+        )
+
+        emit_moderation_event("chat_gem.moderation.member_muted", actor: actor, membership: updated_membership)
+        updated_membership
+      end
+
+      def unmute_member!(actor:, membership:)
+        updated_membership = authorize_and_update_membership!(
+          actor: actor,
+          membership: membership,
+          action: :can_mute_member?,
+          attributes: { muted: false }
+        )
+
+        emit_moderation_event("chat_gem.moderation.member_unmuted", actor: actor, membership: updated_membership)
+        updated_membership
+      end
+
+      def timeout_member!(actor:, membership:, until_time:)
+        authorize_member_action!(actor: actor, membership: membership, action: :can_timeout_member?)
+        raise InvalidActionError, "timeout must be in the future" if until_time.nil? || until_time <= Time.current
+
+        membership.update!(timed_out_until: until_time)
+        emit_moderation_event(
+          "chat_gem.moderation.member_timed_out",
+          actor: actor,
+          membership: membership,
+          extra: { timed_out_until: membership.timed_out_until }
+        )
+        membership
+      end
+
+      def clear_timeout!(actor:, membership:)
+        updated_membership = authorize_and_update_membership!(
+          actor: actor,
+          membership: membership,
+          action: :can_timeout_member?,
+          attributes: { timed_out_until: nil }
+        )
+
+        emit_moderation_event("chat_gem.moderation.member_timeout_cleared", actor: actor, membership: updated_membership)
+        updated_membership
+      end
+
+      def ban_member!(actor:, membership:)
+        updated_membership = authorize_and_update_membership!(
+          actor: actor,
+          membership: membership,
+          action: :can_ban_member?,
+          attributes: {
+            removed_at: Time.current,
+            muted: false,
+            timed_out_until: nil
+          }
+        )
+
+        emit_moderation_event("chat_gem.moderation.member_banned", actor: actor, membership: updated_membership)
+        updated_membership
+      end
+
+      def delete_message!(actor:, message:)
+        permission = permission_for(actor, message.chat)
+        authorize_permission!(permission.can_delete_message?(message), "Not allowed to delete message")
+
+        payload = moderation_message_payload(message)
+        message.destroy!
+        emit_moderation_event("chat_gem.moderation.message_deleted", actor: actor, payload: payload)
+        true
+      end
+
+      def close_chat!(actor:, chat:)
+        authorize_chat_action!(actor: actor, chat: chat, gate: :can_close_chat?, error_message: "Not allowed to close chat")
+        chat.close!
+        emit_moderation_event("chat_gem.moderation.chat_closed", actor: actor, payload: moderation_chat_payload(chat))
+        chat
+      end
+
+      def reopen_chat!(actor:, chat:)
+        authorize_chat_action!(actor: actor, chat: chat, gate: :can_reopen_chat?, error_message: "Not allowed to reopen chat")
+        chat.reopen!
+        emit_moderation_event("chat_gem.moderation.chat_reopened", actor: actor, payload: moderation_chat_payload(chat))
+        chat
+      end
+
+      private
+
+      def authorize_member_action!(actor:, membership:, action:)
+        raise InvalidActionError, "membership is required" if membership.nil?
+
+        permission = permission_for(actor, membership.chat)
+        return if permission.public_send(action, membership)
+
+        raise AuthorizationError, "Not allowed to #{action.to_s.delete_prefix('can_').delete_suffix('?').tr('_', ' ')}"
+      end
+
+      def authorize_and_update_membership!(actor:, membership:, action:, attributes:)
+        authorize_member_action!(actor: actor, membership: membership, action: action)
+        membership.update!(attributes)
+        membership
+      end
+
+      def authorize_chat_action!(actor:, chat:, gate:, error_message:)
+        permission = permission_for(actor, chat)
+        authorize_permission!(permission.public_send(gate), error_message)
+      end
+
+      def authorize_permission!(allowed, error_message)
+        raise AuthorizationError, error_message unless allowed
+      end
+
+      def permission_for(actor, chat)
+        ChatGem.configuration.permission_adapter.new(actor, chat)
+      end
+
+      def emit_moderation_event(name, actor:, membership: nil, payload: nil, extra: {})
+        return unless moderation_events_enabled?
+        return unless defined?(ActiveSupport::Notifications)
+
+        base_payload =
+          if payload.present?
+            payload
+          else
+            moderation_membership_payload(membership)
+          end
+
+        ActiveSupport::Notifications.instrument(
+          name,
+          base_payload.merge(actor_payload(actor)).merge(extra)
+        )
+      end
+
+      def moderation_events_enabled?
+        config = ChatGem.configuration
+        return false unless config.respond_to?(:emit_moderation_events)
+
+        ActiveModel::Type::Boolean.new.cast(config.emit_moderation_events)
+      rescue StandardError
+        false
+      end
+
+      def moderation_membership_payload(membership)
+        return {} if membership.nil?
+
+        {
+          chat_id: membership.chat_id,
+          membership_id: membership.id,
+          participant_type: membership.participant_type,
+          participant_id: membership.participant_id
+        }
+      end
+
+      def moderation_message_payload(message)
+        return {} if message.nil?
+
+        {
+          chat_id: message.chat_id,
+          message_id: message.id,
+          participant_type: message.participant_type,
+          participant_id: message.participant_id
+        }
+      end
+
+      def moderation_chat_payload(chat)
+        return {} if chat.nil?
+
+        {
+          chat_id: chat.id,
+          closed_at: chat.closed_at
+        }
+      end
+
+      def actor_payload(actor)
+        return { actor_type: nil, actor_id: nil } if actor.nil?
+
+        {
+          actor_type: actor.class.base_class.name,
+          actor_id: actor.id
+        }
+      end
+    end
+  end
+end

data/lib/chat_gem/permission.rb

@@ -0,0 +1,193 @@
+module ChatGem
+  class Permission
+    ROLE_MENTION_TOKEN_PATTERN = /\A@[A-Z][A-Z0-9_]{0,31}\z/.freeze
+    MEMBER_MENTION_TOKEN_PATTERN = /\A@[a-z0-9_]{1,32}\z/i.freeze
+
+    attr_reader :participant, :chat
+
+    def initialize(participant, chat = nil)
+      @participant = participant
+      @chat = chat
+    end
+
+    def can_view_chat?
+      return false unless participant_present?
+      return true unless chat_present?
+      return false unless actor_membership_active?
+
+      role_permission?(:view_chat)
+    end
+
+    def can_create_chat?
+      participant_present?
+    end
+
+    def can_post_message?
+      return false unless can_view_chat?
+      return false unless role_permission?(:post_message)
+      return false if chat_closed?
+      return false if actor_membership_muted?
+      return false if actor_membership_timed_out?
+
+      true
+    end
+
+    def can_mute_member?(target_membership = nil)
+      can_moderate_member?(:mute_member, target_membership)
+    end
+
+    def can_timeout_member?(target_membership = nil)
+      can_moderate_member?(:timeout_member, target_membership)
+    end
+
+    def can_ban_member?(target_membership = nil)
+      can_moderate_member?(:ban_member, target_membership)
+    end
+
+    def can_invite_member?
+      can_view_chat? && role_permission?(:invite_member)
+    end
+
+    def can_delete_message?(message = nil)
+      return false unless can_view_chat?
+      return false unless role_permission?(:delete_message)
+      return true if message.nil?
+      return false unless message_in_chat?(message)
+
+      target_membership = membership_for(message.participant)
+      can_act_on_target_membership?(target_membership)
+    end
+
+    def can_edit_message?(message = nil)
+      return false unless can_post_message?
+      return true if message.nil?
+      return false unless message_in_chat?(message)
+
+      participant_type, participant_id = actor_identity
+      return false if participant_type.blank? || participant_id.blank?
+
+      message.participant_type.to_s == participant_type &&
+        message.participant_id.to_s == participant_id.to_s
+    end
+
+    def can_close_chat?
+      can_view_chat? && role_permission?(:close_chat)
+    end
+
+    def can_reopen_chat?
+      can_view_chat? && role_permission?(:reopen_chat)
+    end
+
+    def can_mention_members?
+      can_view_chat? && role_permission?(:mention_member)
+    end
+
+    def can_mention_all?
+      can_view_chat? && role_permission?(:mention_all)
+    end
+
+    def can_mention_roles?
+      can_view_chat? && role_permission?(:mention_role)
+    end
+
+    def can_mention_token?(token)
+      mention = token.to_s.strip
+      return false if mention.blank?
+      return false unless mention.start_with?("@")
+
+      return can_mention_all? if mention.casecmp("@all").zero?
+      return can_mention_roles? if ROLE_MENTION_TOKEN_PATTERN.match?(mention)
+      return can_mention_members? if MEMBER_MENTION_TOKEN_PATTERN.match?(mention)
+
+      false
+    end
+
+    private
+
+    def can_moderate_member?(permission, target_membership)
+      return false unless can_view_chat?
+      return false unless role_permission?(permission)
+      return true if target_membership.nil?
+      return false unless membership_in_chat?(target_membership)
+      return false unless target_membership.active?
+
+      can_act_on_target_membership?(target_membership)
+    end
+
+    def can_act_on_target_membership?(target_membership)
+      return true if target_membership.nil?
+      return false unless actor_membership_active?
+      return false if target_membership.participant == participant
+
+      actor_rank > target_role_rank(target_membership)
+    end
+
+    def membership_for(target_participant)
+      return nil unless chat_present?
+      return nil if target_participant.nil?
+
+      chat.chat_memberships.active.find_by(participant: target_participant)
+    end
+
+    def role_permission?(permission)
+      role_permissions.include?(permission.to_sym)
+    end
+
+    def role_permissions
+      actor_membership&.effective_role_permissions || []
+    end
+
+    def actor_rank
+      actor_membership&.effective_role_rank || -1
+    end
+
+    def target_role_rank(target_membership)
+      target_membership&.effective_role_rank || -1
+    end
+
+    def actor_membership
+      return nil unless chat_present?
+      return nil unless participant_present?
+
+      chat.chat_memberships.active.find_by(participant: participant)
+    end
+
+    def participant_present?
+      !participant.nil?
+    end
+
+    def chat_present?
+      !chat.nil?
+    end
+
+    def actor_identity
+      participant_type = participant.class.base_class.name
+      participant_id = participant.id
+      [participant_type, participant_id]
+    end
+
+    def actor_membership_active?
+      actor_membership&.active?
+    end
+
+    def actor_membership_muted?
+      actor_membership&.muted?
+    end
+
+    def actor_membership_timed_out?
+      actor_membership&.timed_out_until&.future?
+    end
+
+    def chat_closed?
+      chat&.closed?
+    end
+
+    def message_in_chat?(message)
+      message.chat_id == chat&.id
+    end
+
+    def membership_in_chat?(target_membership)
+      target_membership.chat_id == chat&.id
+    end
+  end
+end

data/lib/chat_gem/signals.rb

@@ -0,0 +1,26 @@
+module ChatGem
+  module Signals
+    module_function
+
+    def start!(chat:, participant:, signal_type: :typing)
+      ChatGem::ChatMessage.replace_signal!(chat: chat, participant: participant, signal_type: signal_type)
+    end
+
+    def replace!(chat:, participant:, signal_type: :typing)
+      ChatGem::ChatMessage.replace_signal!(chat: chat, participant: participant, signal_type: signal_type)
+    end
+
+    def clear!(chat:, participant:)
+      ChatGem::ChatMessage.clear_signals!(chat: chat, participant: participant)
+    end
+
+    def with(chat:, participant:, signal_type: :typing, &block)
+      ChatGem::ChatMessage.with_signal(
+        chat: chat,
+        participant: participant,
+        signal_type: signal_type,
+        &block
+      )
+    end
+  end
+end

data/lib/chat_gem/version.rb

@@ -0,0 +1,3 @@
+module ChatGem
+  VERSION = "0.1.0"
+end

data/lib/chat_gem.rb

@@ -0,0 +1,24 @@
+require "chat_gem/version"
+require "turbo-rails"
+require "chat_gem/configuration"
+require "chat_gem/model_extensions/chat_participant"
+require "chat_gem/permission"
+require "chat_gem/moderation"
+require "chat_gem/signals"
+require "chat_gem/engine"
+
+module ChatGem
+  class << self
+    def configuration
+      @configuration ||= ChatGem::Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+  end
+
+  def self.table_name_prefix
+    "chat_gem_"
+  end
+end

data/lib/generators/chat_gem/install/install_generator.rb

@@ -0,0 +1,18 @@
+require "rails/generators/base"
+
+module ChatGem
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+      desc "Installs ChatGem initializer and copies engine migrations"
+
+      def copy_initializer
+        template "chat_gem.rb", "config/initializers/chat_gem.rb"
+      end
+
+      def install_migrations
+        rake "railties:install:migrations FROM=chat_gem"
+      end
+    end
+  end
+end

data/lib/generators/chat_gem/install/templates/chat_gem.rb

@@ -0,0 +1,36 @@
+ChatGem.configure do |config|
+  config.permission_adapter = ChatGem::Permission
+  config.max_chat_participants = 10
+  config.max_message_length = 1000
+  config.message_history_limit = 200
+  config.enable_mentions = true
+  config.mention_filter_exclude_self = true
+  config.mention_filter_hide_roles = true
+  config.enable_emoji_aliases = true
+  config.emoji_aliases = ChatGem::Configuration::DEFAULT_EMOJI_ALIASES.dup
+  config.blocked_words = []
+  config.blocked_words_action = :reject
+  config.mention_mark_hex_color = nil
+  config.mention_highlight_hex_color = nil
+  config.own_message_hex_color = nil
+  config.other_message_hex_color = nil
+  config.role_message_hex_colors = {}
+  config.show_timestamp = true
+  config.show_role = false
+  config.active_chat_window = 5.minutes
+  config.emit_typing_events = false
+  config.emit_message_events = false
+  config.emit_mention_events = false
+  config.emit_invitation_events = false
+  config.emit_chat_lifecycle_events = false
+  config.emit_moderation_events = false
+  config.emit_blocked_words_events = false
+  config.show_self_signals = false
+  config.replace_signals_on_message_submit = false
+  config.message_css_class_resolver = nil
+  config.render_message_html = false
+  config.message_html_tags = %w[a b br code em i li ol p pre strong ul]
+  config.message_html_attributes = %w[href target rel class]
+  config.timestamp_formatter = ->(timestamp, _chat_message) { I18n.l(timestamp.in_time_zone, format: :long) }
+  config.role_formatter = ->(role, _chat_message) { role.to_s.humanize }
+end

data/lib/generators/turbo_chat/install/install_generator.rb

@@ -0,0 +1,18 @@
+require "rails/generators/base"
+
+module TurboChat
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+      desc "Installs TurboChat initializer and copies engine migrations"
+
+      def copy_initializer
+        template "turbo_chat.rb", "config/initializers/turbo_chat.rb"
+      end
+
+      def install_migrations
+        rake "railties:install:migrations FROM=chat_gem"
+      end
+    end
+  end
+end

data/lib/generators/turbo_chat/install/templates/turbo_chat.rb

@@ -0,0 +1,36 @@
+TurboChat.configure do |config|
+  config.permission_adapter = TurboChat::Permission
+  config.max_chat_participants = 10
+  config.max_message_length = 1000
+  config.message_history_limit = 200
+  config.enable_mentions = true
+  config.mention_filter_exclude_self = true
+  config.mention_filter_hide_roles = true
+  config.enable_emoji_aliases = true
+  config.emoji_aliases = TurboChat::Configuration::DEFAULT_EMOJI_ALIASES.dup
+  config.blocked_words = []
+  config.blocked_words_action = :reject
+  config.mention_mark_hex_color = nil
+  config.mention_highlight_hex_color = nil
+  config.own_message_hex_color = nil
+  config.other_message_hex_color = nil
+  config.role_message_hex_colors = {}
+  config.show_timestamp = true
+  config.show_role = false
+  config.active_chat_window = 5.minutes
+  config.emit_typing_events = false
+  config.emit_message_events = false
+  config.emit_mention_events = false
+  config.emit_invitation_events = false
+  config.emit_chat_lifecycle_events = false
+  config.emit_moderation_events = false
+  config.emit_blocked_words_events = false
+  config.show_self_signals = false
+  config.replace_signals_on_message_submit = false
+  config.message_css_class_resolver = nil
+  config.render_message_html = false
+  config.message_html_tags = %w[a b br code em i li ol p pre strong ul]
+  config.message_html_attributes = %w[href target rel class]
+  config.timestamp_formatter = ->(timestamp, _chat_message) { I18n.l(timestamp.in_time_zone, format: :long) }
+  config.role_formatter = ->(role, _chat_message) { role.to_s.humanize }
+end

data/lib/tasks/chat_gem_tasks.rake

@@ -0,0 +1 @@
+# Add engine-specific tasks here.

data/lib/tasks/turbo_chat_tasks.rake

@@ -0,0 +1,10 @@
+namespace :turbo_chat do
+  namespace :install do
+    desc "Install TurboChat migrations (alias for chat_gem:install:migrations)"
+    task :migrations do
+      task = Rake::Task["chat_gem:install:migrations"]
+      task.reenable
+      task.invoke
+    end
+  end
+end

data/lib/turbo_chat/version.rb

@@ -0,0 +1,5 @@
+require_relative "../chat_gem/version"
+
+module TurboChat
+  VERSION = ChatGem::VERSION
+end

data/lib/turbo_chat.rb

@@ -0,0 +1,24 @@
+require_relative "chat_gem"
+require_relative "turbo_chat/version"
+
+module TurboChat
+  class << self
+    def configuration
+      ChatGem.configuration
+    end
+
+    def configure(&block)
+      ChatGem.configure(&block)
+    end
+
+    def table_name_prefix
+      ChatGem.table_name_prefix
+    end
+
+    def const_missing(name)
+      return ChatGem.const_get(name) if ChatGem.const_defined?(name)
+
+      super
+    end
+  end
+end

data/turbo_chat.gemspec

@@ -0,0 +1,31 @@
+require_relative "lib/turbo_chat/version"
+
+Gem::Specification.new do |spec|
+  spec.name        = "turbo_chat"
+  spec.version     = TurboChat::VERSION
+  spec.authors     = ["Alexander Haumer"]
+  spec.homepage    = "https://github.com/Haumer/ruby_llm_chat"
+  spec.summary     = "Lightweight mountable chat engine for Rails"
+  spec.description = "A mountable Rails engine with chats, messages, memberships, and Turbo Stream updates."
+  spec.license     = "MIT"
+
+  spec.files = Dir.chdir(__dir__) do
+    Dir[
+      "{app,config,db,lib}/**/*",
+      "MIT-LICENSE",
+      "README.md",
+      "turbo_chat.gemspec"
+    ]
+  end
+
+  spec.required_ruby_version = ">= 3.1"
+
+  spec.add_dependency "rails", ">= 7.0", "< 8.0"
+  spec.add_dependency "turbo-rails", ">= 1.4", "< 3.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "#{spec.homepage}/tree/main"
+  spec.metadata["bug_tracker_uri"] = "#{spec.homepage}/issues"
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/README.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+end