chats 0.1.1

data/lib/chats.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/inflections"
+require "global_id"
+
+require_relative "chats/version"
+require_relative "chats/errors"
+require_relative "chats/configuration"
+require_relative "chats/macros"
+
+require_relative "chats/engine" if defined?(::Rails::Engine)
+
+# == Chats
+#
+# A drop-in, real-time messaging engine for Rails: DMs, group chats, reactions,
+# attachments, read receipts — Hotwire-native, polymorphic, adapter-driven.
+#
+# The public surface is intentionally tiny:
+#
+#   Chats.configure { |config| ... }   # one block, in an initializer
+#   acts_as_messager                   # on any model that can converse
+#   acts_as_chat_subject               # on any model conversations can be about
+#
+#   user.chat_with(other)              # find-or-create a direct conversation
+#   user.message!(other, "hello!")     # ...and say something in one line
+#
+# Everything else (controllers, views, broadcasts) ships with the engine and
+# is overridable the Devise way (`rails g chats:views`).
+module Chats
+  class << self
+    # --- Configuration --------------------------------------------------------
+
+    def config
+      @config ||= Configuration.new
+    end
+
+    alias configuration config
+
+    def configure
+      yield config if block_given?
+      config.validate!
+      config
+    end
+
+    # Reset all global state. Used by the test suite to keep examples isolated;
+    # also handy in a console when experimenting with configuration.
+    def reset!
+      @config = Configuration.new
+      @messager_classes = nil
+      @subject_classes = nil
+      self
+    end
+
+    # --- Registries -----------------------------------------------------------
+    #
+    # `acts_as_messager` / `acts_as_chat_subject` self-register the calling
+    # class here. We store class NAMES (strings), not Class objects, so the
+    # registry survives Zeitwerk code reloading in development (a reloaded
+    # class is a brand-new object; its name is stable).
+
+    def register_messager(klass)
+      messager_class_names << klass.name if klass.name
+    end
+
+    def register_chat_subject(klass)
+      subject_class_names << klass.name if klass.name
+    end
+
+    def messager_class_names
+      @messager_class_names ||= Set.new
+    end
+
+    def subject_class_names
+      @subject_class_names ||= Set.new
+    end
+
+    # Whether +klass+ (a Class or class name) is a registered messager.
+    # Ancestor-aware so an STI subclass of a messager is accepted too.
+    def messager_class?(klass)
+      registered_class?(messager_class_names, klass)
+    end
+
+    def chat_subject_class?(klass)
+      registered_class?(subject_class_names, klass)
+    end
+
+    # --- Ecosystem seams ------------------------------------------------------
+
+    # The single source of truth for "who can't talk to whom". Wraps the
+    # host-provided `config.blocked_messager_ids` proc (no-op by default, or
+    # `Moderate.blocked_ids_for(user)` when the moderate gem is wired in) and
+    # always returns something usable in a `WHERE id IN (...)` — an Array of
+    # ids or an AR relation selecting ids.
+    def blocked_ids_for(messager)
+      return [] if messager.nil?
+
+      config.blocked_messager_ids.call(messager) || []
+    end
+
+    # True when +a+ and +b+ can't message each other (either one blocked the
+    # other — blocking is enforced bidirectionally, like every serious
+    # messaging product). Only meaningful between messagers of the same class
+    # (a User blocks a User); cross-class pairs are never considered blocked.
+    def blocked_between?(a, b)
+      return false if a.nil? || b.nil?
+      return false unless a.class.base_class == b.class.base_class
+
+      blocked_ids = blocked_ids_for(a)
+      if blocked_ids.respond_to?(:exists?)
+        # An AR relation: resolve with one indexed query instead of loading ids.
+        blocked_ids.exists?(b.id)
+      else
+        blocked_ids.include?(b.id)
+      end
+    end
+
+    # Host policy on top of (never instead of) block enforcement. The blocked
+    # check is hardcoded in the models so a host overriding `can_message`
+    # cannot accidentally disable Trust & Safety guarantees.
+    def can_message?(sender, recipient)
+      return false if blocked_between?(sender, recipient)
+
+      config.can_message.call(sender, recipient)
+    end
+
+    # Fire a domain event through the host's notifier hook (no-op by default).
+    # Events (see Chats::Configuration#notifier):
+    #   :message_created      message:      (every persisted, non-system message)
+    #   :participant_added    participant:  (someone added to a group)
+    #
+    # Hosts typically point this at a Noticed notifier or a mailer job:
+    #   config.notifier = ->(event, **payload) {
+    #     NewMessageNotifier.with(**payload).deliver if event == :message_created
+    #   }
+    def notify(event, **payload)
+      config.notifier.call(event, **payload)
+    rescue StandardError => e
+      # A broken notifier must never break message delivery itself — the
+      # message is already committed; notifications are best-effort fan-out.
+      # Same error-isolation philosophy as pricing_plans' lifecycle callbacks.
+      logger&.error("[chats] notifier raised on #{event}: #{e.class}: #{e.message}")
+      nil
+    end
+
+    # --- Display helpers (used by the bundled views) --------------------------
+
+    def display_name_for(messager)
+      return "" if messager.nil?
+
+      config.messager_display_name.call(messager).to_s
+    end
+
+    def avatar_for(messager)
+      return nil if messager.nil?
+
+      config.messager_avatar.call(messager)
+    end
+
+    # --- Internals ------------------------------------------------------------
+
+    def logger
+      defined?(::Rails) ? ::Rails.logger : nil
+    end
+
+    # A stable, URL-safe, non-guessy key for a messager, used in DOM data
+    # attributes (the Stimulus thread controller compares it to decide
+    # own-vs-other bubble alignment) and in direct-conversation keys.
+    # GlobalID params are opaque-ish (Base64) and already encode class + id.
+    def messager_key(messager)
+      messager.to_global_id.to_param
+    end
+
+    private
+
+    def registered_class?(registry, klass)
+      klass = klass.class unless klass.is_a?(Class) || klass.is_a?(String)
+      name = klass.is_a?(String) ? klass : klass.name
+      return true if registry.include?(name)
+
+      # Ancestor-aware fallback: accept subclasses of registered classes
+      # (e.g. an STI `Admin < User` when `User` is the registered messager).
+      constant = klass.is_a?(String) ? name.safe_constantize : klass
+      return false unless constant.respond_to?(:ancestors)
+
+      constant.ancestors.any? { |ancestor| registry.include?(ancestor.name) }
+    end
+  end
+end

data/lib/generators/chats/install_generator.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rails/generators/active_record"
+
+module Chats
+  module Generators
+    # `rails generate chats:install` — copies the adaptive migration (uuid or
+    # bigint keys, adapter-aware JSON columns) and the annotated initializer,
+    # then prints the remaining setup steps.
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+      desc "Install chats migrations and initializer"
+
+      def self.next_migration_number(dir)
+        ActiveRecord::Generators::Base.next_migration_number(dir)
+      end
+
+      def create_migration_file
+        migration_template "create_chats_tables.rb.erb", File.join(db_migrate_path, "create_chats_tables.rb")
+      end
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/chats.rb"
+      end
+
+      def display_post_install_message
+        say "\n💬 The `chats` gem has been installed.", :green
+        say "\nTo complete the setup:"
+
+        say "  1. Run 'rails db:migrate' to create the chats tables."
+        say "     ⚠️  You must run migrations before starting your app!", :yellow
+
+        say "  2. Make your users conversational:"
+        say "       class User < ApplicationRecord"
+        say "         acts_as_messager"
+        say "       end"
+
+        say "  3. Mount the inbox wherever you want it to live:"
+        say "       # config/routes.rb"
+        say "       mount Chats::Engine => \"/messages\""
+
+        say "  4. (Optional) Attach conversations to your domain:"
+        say "       class Ride < ApplicationRecord"
+        say "         acts_as_chat_subject"
+        say "       end"
+        say "       user.chat_with(driver, about: ride)"
+
+        say "\nYou now have real-time DMs: inbox, threads, reactions, read receipts. 🚀"
+        say "Pure Hotwire — works out of the box with importmaps + the default Stimulus setup.\n", :green
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::STRING.to_f}]"
+      end
+    end
+  end
+end

data/lib/generators/chats/templates/create_chats_tables.rb.erb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+class CreateChatsTables < ActiveRecord::Migration<%= migration_version %>
+  def change
+    primary_key_type, foreign_key_type = primary_and_foreign_key_types
+
+    # ---------------------------------------------------------------------------
+    # chats_conversations
+    #
+    # A direct (1:1) or group thread, optionally *about* a polymorphic host
+    # record (subject: a ride, an order, a listing…). `last_message_at` /
+    # `last_message_id` / `messages_count` are denormalized so the inbox is a
+    # single indexed ORDER BY with no MAX() subqueries.
+    # ---------------------------------------------------------------------------
+    create_table :chats_conversations, id: primary_key_type do |t|
+      t.string :kind, null: false, default: "direct"
+      t.string :title
+
+      # What the conversation is about (optional). `index: false` because we
+      # declare the polymorphic index explicitly below with a stable name;
+      # without it, `t.references` would ALSO auto-create one and the two
+      # would collide ("index ... already exists") when the migration runs.
+      t.references :subject, polymorphic: true, type: foreign_key_type, null: true, index: false
+
+      # Deterministic identity for direct threads ("sorted pair of messager
+      # keys [+ subject]"). The UNIQUE index is what makes concurrent
+      # find-or-create race-safe (create_or_find_by! resolves collisions
+      # through it). NULL for groups — multiple NULLs are allowed in unique
+      # indexes on every supported adapter.
+      t.string :direct_key
+
+      # Inbox denormalization. last_message_id has NO foreign key on purpose:
+      # a circular conversations<->messages FK pair makes row deletion
+      # order-dependent (you couldn't delete either row first). The column is
+      # best-effort bookkeeping, healed by the model when messages vanish.
+      t.datetime :last_message_at
+      t.column :last_message_id, foreign_key_type
+      t.integer :messages_count, null: false, default: 0
+
+      t.timestamps
+    end
+
+    add_index :chats_conversations, [ :subject_type, :subject_id ], name: "index_chats_conversations_on_subject"
+    add_index :chats_conversations, :direct_key, unique: true, name: "index_chats_conversations_on_direct_key"
+    add_index :chats_conversations, :last_message_at, name: "index_chats_conversations_on_last_message_at"
+
+    # ---------------------------------------------------------------------------
+    # chats_participants
+    #
+    # A messager's seat in a conversation, holding ALL per-member state:
+    # role, read horizon (last_read_at — there is deliberately no per-message
+    # receipts table; see Chats::Participant), mute, soft-leave, and the
+    # debounced-notification bookkeeping (last_notified_at).
+    # ---------------------------------------------------------------------------
+    create_table :chats_participants, id: primary_key_type do |t|
+      t.references :conversation, null: false, type: foreign_key_type,
+                                  foreign_key: { to_table: :chats_conversations }, index: false
+      t.references :messager, polymorphic: true, null: false, type: foreign_key_type, index: false
+
+      t.string :role, null: false, default: "member"
+      t.datetime :last_read_at
+      t.datetime :muted_at
+      t.datetime :left_at
+      t.datetime :last_notified_at
+
+      t.timestamps
+    end
+
+    # One seat per messager per conversation — also the lock that makes
+    # concurrent add_participant! idempotent.
+    add_index :chats_participants, [ :conversation_id, :messager_type, :messager_id ],
+              unique: true, name: "index_chats_participants_uniqueness"
+    # The inbox entry point: "all of MY participations" (then join
+    # conversations ordered by last_message_at).
+    add_index :chats_participants, [ :messager_type, :messager_id ], name: "index_chats_participants_on_messager"
+
+    # ---------------------------------------------------------------------------
+    # chats_messages
+    #
+    # kind: "text" (human, has sender) | "system" (posted by the host app —
+    # "Your ride was cancelled" — no sender). Soft deletion keeps a tombstone
+    # (deleted_at set, body cleared) for thread continuity + T&S evidence.
+    # sender is nullable: system messages have none, and destroyed messager
+    # accounts nullify theirs (history survives account deletion).
+    # ---------------------------------------------------------------------------
+    create_table :chats_messages, id: primary_key_type do |t|
+      t.references :conversation, null: false, type: foreign_key_type,
+                                  foreign_key: { to_table: :chats_conversations }, index: false
+      t.references :sender, polymorphic: true, null: true, type: foreign_key_type, index: false
+
+      t.string :kind, null: false, default: "text"
+      t.text :body
+      t.references :reply_to, type: foreign_key_type, null: true,
+                              foreign_key: { to_table: :chats_messages }, index: false
+      t.datetime :edited_at
+      t.datetime :deleted_at
+      t.send(json_column_type, :metadata, default: json_column_default)
+
+      t.timestamps
+    end
+
+    # THE hot path: a conversation's message page, keyset-paginated on
+    # (created_at, id) — see Chats::Message.before_message.
+    add_index :chats_messages, [ :conversation_id, :created_at, :id ], name: "index_chats_messages_on_conversation_and_created_at"
+    add_index :chats_messages, [ :sender_type, :sender_id ], name: "index_chats_messages_on_sender"
+    add_index :chats_messages, :reply_to_id, name: "index_chats_messages_on_reply_to_id"
+
+    # ---------------------------------------------------------------------------
+    # chats_reactions
+    #
+    # Emoji reactions; the unique index makes tap-to-toggle race-safe.
+    # ---------------------------------------------------------------------------
+    create_table :chats_reactions, id: primary_key_type do |t|
+      t.references :message, null: false, type: foreign_key_type,
+                             foreign_key: { to_table: :chats_messages }, index: false
+      t.references :reactor, polymorphic: true, null: false, type: foreign_key_type, index: false
+      t.string :emoji, null: false
+
+      t.timestamps
+    end
+
+    add_index :chats_reactions, [ :message_id, :reactor_type, :reactor_id, :emoji ],
+              unique: true, name: "index_chats_reactions_uniqueness"
+
+    # NOTE: value-list vocabularies (kind, role) are validated in the MODELS
+    # (frozen constants + inclusion validations), NOT by DB check constraints —
+    # so the gem can grow its taxonomy without shipping a migration to widen a
+    # CHECK. Same rationale as the rest of the gem ecosystem (moderate, …).
+  end
+
+  private
+
+  # Honor the host's configured primary key type (uuid vs bigint). Reads the
+  # same setting `rails g model` uses, so an app generated with
+  # `config.generators { |g| g.orm :active_record, primary_key_type: :uuid }`
+  # gets uuid chats tables and uuid foreign keys, automatically.
+  def primary_and_foreign_key_types
+    config = Rails.configuration.generators
+    setting = config.options[config.orm][:primary_key_type]
+    primary_key_type = setting || :primary_key
+    foreign_key_type = setting || :bigint
+    [primary_key_type, foreign_key_type]
+  end
+
+  def json_column_type
+    return :jsonb if connection.adapter_name.downcase.include?("postgresql")
+
+    :json
+  end
+
+  # MySQL 8+ doesn't allow default values on JSON columns.
+  # Returns an empty-hash default for SQLite/PostgreSQL, nil for MySQL.
+  # The model handles nil metadata gracefully (attribute default {}).
+  def json_column_default
+    return nil if connection.adapter_name.downcase.include?("mysql")
+
+    {}
+  end
+end

data/lib/generators/chats/templates/initializer.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+Chats.configure do |config|
+  # ==========================================================================
+  # WHO CONVERSES?
+  # ==========================================================================
+  #
+  # The model that opens conversations and sends messages — the one with
+  # `acts_as_messager`. Participants are polymorphic, so OTHER models with
+  # `acts_as_messager` can join conversations too; this names the primary one
+  # the engine's controllers resolve against. Stored as a string and resolved
+  # lazily, so it works no matter when your app boots.
+  #
+  # Default: "User"
+  config.messager_class = "User"
+
+  # ==========================================================================
+  # CONTROLLER INTEGRATION
+  # ==========================================================================
+  #
+  # The engine inherits from your controller, so your layout, helpers, locale
+  # switching, and auth all apply to the chat screens automatically.
+  #
+  # config.parent_controller = "::ApplicationController"
+  #
+  # How the engine finds the current messager and requires login. The
+  # defaults work with Devise out of the box.
+  #
+  # config.current_messager_method = :current_user
+  # config.authenticate_method = :authenticate_user!
+  #
+  # Render the chat screens with a specific layout (nil inherits whatever
+  # your parent controller uses):
+  #
+  # config.layout = "application"
+
+  # ==========================================================================
+  # FEATURES — everything on by default; switch off what you don't want
+  # ==========================================================================
+  #
+  # config.groups = true              # group conversations (3+ people)
+  # config.reactions = true           # emoji reactions on messages
+  # config.read_receipts = true       # "Seen" + unread tracking
+  # config.typing_indicators = true   # live "X is typing…"
+  # config.editing = true             # senders can edit their messages
+  # config.deletion = :soft           # :soft (tombstone) | :hard | false
+  # config.attachments = :images      # false | :images | :any (ActiveStorage)
+  # config.search = true              # inbox search box
+
+  # ==========================================================================
+  # LIMITS
+  # ==========================================================================
+  #
+  # config.messages_per_page = 30
+  # config.max_message_length = 5_000
+  # config.max_group_size = 32
+  # config.max_attachment_size = 10.megabytes
+  # config.max_attachments_per_message = 4
+  #
+  # Per-sender send throttle (enforced with Rails 8's controller rate_limit;
+  # a no-op on Rails 7.x). Set to nil to disable.
+  #
+  # config.send_rate_limit = { to: 60, within: 1.minute }
+  #
+  # Encrypt message bodies at rest (ActiveRecord Encryption; requires
+  # `bin/rails db:encryption:init`). Body search degrades when enabled.
+  #
+  # config.encrypt_messages = false
+
+  # ==========================================================================
+  # POLICIES — who may talk to whom
+  # ==========================================================================
+  #
+  # Runs ON TOP of block enforcement (a blocked pair can never talk, no
+  # matter what this returns). Default: anyone can message anyone — scope it
+  # to your domain, e.g. "only people who share an accepted ride":
+  #
+  # config.can_message = ->(sender, recipient) {
+  #   sender.shares_a_ride_with?(recipient)
+  # }
+  #
+  # config.can_create_group = ->(creator) { creator.admin? }
+
+  # ==========================================================================
+  # TRUST & SAFETY — snap onto the `moderate` gem (or anything else)
+  # ==========================================================================
+  #
+  # One line wires bidirectional block enforcement into conversation
+  # creation, message sends, inbox visibility, and unread counts:
+  #
+  # config.blocked_messager_ids = ->(user) { Moderate.blocked_ids_for(user) }
+  #
+  # To also make messages reportable and filtered, declare it where you
+  # configure moderate (an after-boot hook so model macros apply on reload):
+  #
+  # Rails.application.config.to_prepare do
+  #   Chats::Message.has_reportable_content :body
+  #   Chats::Message.moderates :body, mode: :flag   # never block mid-conversation
+  # end
+  #
+  # …and register the filter policy in config/initializers/moderate.rb:
+  #
+  # config.filter "Chats::Message", :body, mode: :flag
+
+  # ==========================================================================
+  # NOTIFICATIONS — one hook, fan out anywhere
+  # ==========================================================================
+  #
+  # Called on notification-worthy domain moments. Keep it fast (enqueue jobs,
+  # don't do work inline). Events:
+  #
+  #   :message_created    message:      every persisted human message
+  #   :participant_added  participant:  someone added to a group
+  #
+  # With Noticed:
+  #   config.notifier = ->(event, **payload) {
+  #     NewMessageNotifier.with(**payload).deliver if event == :message_created
+  #   }
+  #
+  # With a plain debounced-email job (see Chats::Participant#should_notify?
+  # for the "only email once until they come back" etiquette helper):
+  #   config.notifier = ->(event, message:, **) {
+  #     ChatsUnreadEmailJob.set(wait: 10.minutes).perform_later(message) if event == :message_created
+  #   }
+
+  # ==========================================================================
+  # DISPLAY — how messagers appear in the bundled views
+  # ==========================================================================
+  #
+  # config.messager_display_name = ->(messager) { messager.display_name }
+  #
+  # Return anything image_tag accepts (URL, ActiveStorage attachment or
+  # variant), or nil for an initials placeholder:
+  #
+  # config.messager_avatar = ->(messager) {
+  #   messager.avatar.attached? ? messager.avatar.variant(:thumb) : nil
+  # }
+end

data/lib/generators/chats/views_generator.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Chats
+  module Generators
+    # `rails generate chats:views` — eject the engine's overridable templates
+    # into the HOST app so they can be restyled. This is the Devise move
+    # (`rails g devise:views`), and it works for the same boring Rails reason:
+    # the host app's `app/views` sits AHEAD of any engine's view paths in the
+    # lookup chain, so a file copied to e.g.
+    # `app/views/chats/messages/_message.html.erb` SHADOWS the gem's bundled
+    # default automatically — no config, no registration. Delete your copy
+    # and the gem's default comes back. Upgrade the gem and your ejected
+    # copies are untouched (re-run only if you WANT the new defaults).
+    #
+    # `source_root` points at the engine's own `app/views`, so `directory`
+    # copies the exact templates the engine renders.
+    class ViewsGenerator < Rails::Generators::Base
+      source_root File.expand_path("../../../app/views", __dir__)
+
+      desc "Copy chats' overridable views into your app so you can restyle them."
+
+      # Which groups to eject. Default copies everything renderable.
+      class_option :views,
+                   type: :array,
+                   default: %w[conversations messages shared],
+                   desc: "Which view groups to copy (conversations, messages, shared)"
+
+      def copy_views
+        directory "chats/conversations", "app/views/chats/conversations" if include?("conversations")
+        directory "chats/messages", "app/views/chats/messages" if include?("messages")
+        directory "chats/shared", "app/views/chats/shared" if include?("shared")
+      end
+
+      def show_styling_tip
+        say "\n🎨 Views copied. They render with the gem's bundled chats.css by default;"
+        say "   restyle freely — if your app uses Tailwind, classes you add here are"
+        say "   picked up by your build automatically (the files now live in app/views)."
+      end
+
+      private
+
+      def include?(group)
+        options[:views].map(&:to_s).include?(group)
+      end
+    end
+  end
+end