chats 0.1.1

data/lib/chats/models/message.rb

@@ -0,0 +1,323 @@
+# frozen_string_literal: true
+
+module Chats
+  # A message in a conversation. Two kinds:
+  #
+  #   "text"    a human message from a +sender+ (any acts_as_messager model)
+  #   "system"  posted by the HOST APP via Conversation#post_system_message!
+  #             ("Your ride was cancelled") — no sender, centered rendering
+  #
+  # == Soft deletion ("delete for everyone")
+  #
+  # With `config.deletion = :soft` (the default), deleting clears the body,
+  # purges attachments and stamps +deleted_at+ — the row stays as a tombstone
+  # ("Message deleted") exactly like WhatsApp/Telegram, which keeps thread
+  # continuity AND leaves an auditable trail for Trust & Safety. Note that
+  # moderation evidence is still safe: the moderate gem snapshots reported
+  # content AT REPORT TIME, so removing the body later never destroys the
+  # evidence a moderator needs.
+  #
+  # == Real-time
+  #
+  # All Turbo Stream fan-out lives in Chats::Broadcasts (one place to read
+  # the whole live behavior). Broadcasts run in `after_*_commit` callbacks —
+  # never inside the transaction — and use the `_later` job variants so
+  # rendering never blocks the request.
+  class Message < ApplicationRecord
+    self.table_name = "chats_messages"
+
+    KINDS = %w[text system].freeze
+
+    belongs_to :conversation,
+               class_name: "Chats::Conversation",
+               inverse_of: :messages,
+               counter_cache: :messages_count
+    belongs_to :sender, polymorphic: true, optional: true
+    belongs_to :reply_to, class_name: "Chats::Message", optional: true
+
+    has_many :reactions,
+             class_name: "Chats::Reaction",
+             inverse_of: :message,
+             foreign_key: :message_id,
+             dependent: :destroy
+
+    # Attachments ride on ActiveStorage when the host has it installed.
+    # What's *allowed* (none / images only / anything) is enforced by
+    # validations reading `Chats.config.attachments` — see below.
+    has_many_attached :files if defined?(ActiveStorage)
+
+    # Ruby-side default so metadata is always a Hash even on MySQL, where the
+    # migration can't give JSON columns a DB default (MySQL 8+ limitation —
+    # see the migration template's json_column_default).
+    attribute :metadata, default: -> { {} }
+
+    scope :recent_first, -> { order(created_at: :desc, id: :desc) }
+    scope :oldest_first, -> { order(created_at: :asc, id: :asc) }
+    scope :visible, -> { where(deleted_at: nil) }
+
+    # Keyset (cursor) pagination for infinite scroll-up. OFFSET pagination
+    # drifts when new messages arrive mid-scroll; anchoring on the oldest
+    # loaded message can't skip or duplicate. `(created_at, id)` because
+    # created_at alone isn't unique.
+    scope :before_message, lambda { |message|
+      where(
+        "(chats_messages.created_at < :at) OR (chats_messages.created_at = :at AND chats_messages.id < :id)",
+        at: message.created_at, id: message.id
+      )
+    }
+
+    # Catch-up scopes for ConversationsController#refresh (the stale-thread
+    # recovery path — see the thread controller's refresh trigger). `since`
+    # is the newest `updated_at` the client has rendered:
+    #   created_since — messages that arrived while the tab was asleep
+    #                   (appended);
+    #   updated_since — messages the client HAS rendered that changed since
+    #                   (edits, soft-delete tombstones — replaced in place).
+    # `updated_since` excludes fresh rows so nothing renders twice — a Turbo
+    # append of an existing dom_id would otherwise also MOVE that bubble to
+    # the end (Turbo removes-then-appends on id collision).
+    # Pattern from Basecamp's Campfire (Rooms::RefreshesController):
+    # https://github.com/basecamp/once-campfire
+    scope :created_since, ->(time) { where("chats_messages.created_at > ?", time) }
+    scope :updated_since, lambda { |time|
+      where("chats_messages.updated_at > ?", time).where("chats_messages.created_at <= ?", time)
+    }
+
+    validates :kind, inclusion: { in: KINDS }
+    validates :body, presence: true, if: :system?
+    validate :sender_required_for_text_messages, on: :create
+    validate :body_or_files_required
+    validate :body_must_fit_length_limit
+    validate :sender_must_be_active_participant, on: :create
+    validate :sender_must_not_be_blocked, on: :create
+    validate :files_must_be_allowed
+
+    after_create :register_on_conversation
+    after_create_commit :broadcast_created
+    after_create_commit :notify_host
+    after_update_commit :broadcast_updated
+    after_destroy_commit :broadcast_destroyed
+    after_destroy :heal_conversation_pointers
+
+    def system? = kind == "system"
+    def text? = kind == "text"
+    def deleted? = deleted_at.present?
+    def edited? = edited_at.present?
+
+    def sender_key
+      sender && Chats.messager_key(sender)
+    end
+
+    def sent_by?(messager)
+      sender.present? && sender == messager
+    end
+
+    # The body as the UI should show it (tombstones render a localized
+    # "Message deleted" placeholder straight from the view, not from here —
+    # this just guards against showing stale bodies by accident).
+    def visible_body
+      deleted? ? nil : body
+    end
+
+    # Whether +messager+ has read this message, derived from their read
+    # horizon (see Chats::Participant for why there's no receipts table).
+    def read_by?(messager)
+      participant = conversation.participant_for(messager)
+      participant&.last_read_at.present? && participant.last_read_at >= created_at
+    end
+
+    # Edit the body (sender-only — controllers enforce who; the model
+    # enforces *that* editing is enabled). Stamps +edited_at+ so the UI can
+    # show "edited", and broadcasts the replacement bubble.
+    def edit!(new_body)
+      raise Chats::NotAllowedError, "editing is disabled" unless Chats.config.editing
+      raise Chats::NotAllowedError, "can't edit a deleted message" if deleted?
+
+      update!(body: new_body, edited_at: Time.current)
+    end
+
+    # Delete according to `config.deletion` (see class comment). Returns
+    # false when deletion is disabled.
+    def soft_delete!
+      case Chats.config.deletion
+      when :soft
+        transaction do
+          files.purge_later if respond_to?(:files) && files.attached?
+          update!(body: nil, deleted_at: Time.current)
+        end
+        true
+      when :hard
+        destroy!
+        true
+      else
+        false
+      end
+    end
+
+    def attachments?
+      respond_to?(:files) && files.attached?
+    end
+
+    # --- Moderation contract (duck-typed, zero coupling) ------------------------
+    #
+    # Plain-Ruby methods that make a message a first-class citizen of the
+    # moderate gem the moment the HOST wires it up (see README "Trust &
+    # Safety"): they satisfy Moderate::Reportable's contract (owner, label,
+    # snapshot, removal, visibility) and Moderate::ContentFilterable's field
+    # seams for attachment filtering. Without moderate installed they're
+    # inert and cost nothing.
+
+    def reported_owner
+      sender
+    end
+
+    def moderation_label
+      "Chat message #{id}"
+    end
+
+    def moderation_snapshot(field)
+      body if field.to_s == "body"
+    end
+
+    def removable_reported_field?(field)
+      field.to_s == "body" && body.present? && !deleted?
+    end
+
+    # A moderator removing a reported message body = the soft-delete
+    # tombstone path, so the thread shows "Message deleted" instead of a
+    # hole, and attachments are purged with it.
+    def remove_reported_field!(field)
+      return false unless field.to_s == "body"
+
+      soft_delete!
+    end
+
+    # Only people *in* the conversation may report a message (a message
+    # isn't public content), and you can't report your own.
+    def report_visible_to?(viewer, field: nil)
+      return false if viewer.nil? || sent_by?(viewer)
+
+      conversation.participant?(viewer)
+    end
+
+    def moderation_content_type
+      "message"
+    end
+
+    # Moderate::ContentFilterable seam: when the host declares
+    # `moderates :files, mode: :flag, with: :some_image_adapter`, the default
+    # `public_send(:files)` would hand the adapter an ActiveStorage proxy.
+    # Most image adapters (like a custo ImageReviewAdapter, or an AWS
+    # Rekognition adapter fed via ClassifyJob) don't read the value anyway —
+    # they re-fetch the blob — but we make the value meaningful and
+    # change-detection correct regardless.
+    def moderation_field_value(field)
+      return files if field.to_s == "files" && respond_to?(:files)
+
+      public_send(field)
+    end
+
+    def moderation_field_changed_for_commit?(field)
+      if field.to_s == "files" && respond_to?(:files)
+        # Attachments don't have a column; detect "files changed in this
+        # commit" via the attachment records created in this transaction.
+        files.attachments.any?(&:previously_new_record?)
+      elsif respond_to?(:saved_change_to_attribute?)
+        saved_change_to_attribute?(field)
+      else
+        true
+      end
+    end
+
+    private
+
+    def sender_required_for_text_messages
+      errors.add(:sender, :blank) if text? && sender.nil?
+    end
+
+    def body_or_files_required
+      return if system? || deleted?
+      return if body.present?
+      return if attachments?
+
+      errors.add(:body, :blank)
+    end
+
+    def body_must_fit_length_limit
+      max = Chats.config.max_message_length
+      return if max.nil? || body.nil?
+
+      errors.add(:body, :too_long, count: max) if body.length > max
+    end
+
+    def sender_must_be_active_participant
+      return if system? || sender.nil? || conversation.nil?
+
+      errors.add(:sender, :not_a_participant) unless conversation.participant?(sender)
+    end
+
+    # Block enforcement at the WRITE, not just at conversation creation: a
+    # block placed mid-conversation must stop the very next send. Direct
+    # threads only — see Conversation.excluding_blocked_for for the group
+    # rationale.
+    def sender_must_not_be_blocked
+      return if system? || sender.nil? || conversation.nil? || !conversation.direct?
+
+      other = conversation.other_participants(sender).first&.messager
+      errors.add(:base, :blocked) if other && Chats.blocked_between?(sender, other)
+    end
+
+    def files_must_be_allowed
+      return unless respond_to?(:files)
+      return unless files.attached?
+
+      mode = Chats.config.attachments
+      if mode == false
+        errors.add(:files, :not_allowed)
+        return
+      end
+
+      if (max_count = Chats.config.max_attachments_per_message) && files.size > max_count
+        errors.add(:files, :too_many, count: max_count)
+      end
+
+      files.each do |file|
+        errors.add(:files, :must_be_images) if mode == :images && !file.content_type.to_s.start_with?("image/")
+
+        if (max_size = Chats.config.max_attachment_size) && file.byte_size.to_i > max_size
+          errors.add(:files, :too_big, count: max_size / (1024 * 1024))
+        end
+      end
+    end
+
+    def register_on_conversation
+      conversation.register_last_message!(self)
+    end
+
+    def heal_conversation_pointers
+      conversation.recompute_last_message! if conversation.last_message_id == id
+    end
+
+    def broadcast_created
+      Chats::Broadcasts.message_created(self)
+    end
+
+    def broadcast_updated
+      Chats::Broadcasts.message_updated(self)
+    end
+
+    def broadcast_destroyed
+      Chats::Broadcasts.message_destroyed(self)
+    end
+
+    # The single notifier hook (see Chats.notify). System messages don't
+    # notify: the host posted them itself and already knows — re-emitting
+    # would double-count, the same reasoning the chats PRD applies to
+    # moderation flag events.
+    def notify_host
+      return if system?
+
+      Chats.notify(:message_created, message: self)
+    end
+  end
+end

data/lib/chats/models/participant.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Chats
+  # A messager's seat in a conversation. The +messager+ is polymorphic — any
+  # `acts_as_messager` model can sit here (a User, an Organization, a support
+  # Agent) — and ALL per-member state lives on this row:
+  #
+  #   role        "member" | "owner" (group creator/admin)
+  #   last_read_at    the read horizon (see "Read state" below)
+  #   muted_at        notifications muted (the gem still delivers messages;
+  #                   hosts consult `notifiable?` in their notifier hook)
+  #   left_at         soft-left groups (history kept, no new messages seen)
+  #   last_notified_at  bookkeeping for "notify once per unread burst"
+  #                     debounced notifications (see #should_notify?)
+  #
+  # == Read state: a horizon, not per-message receipts
+  #
+  # We deliberately store ONE timestamp per participant instead of a
+  # per-message receipts table. A message is unread for you iff
+  # `created_at > your last_read_at`; you "read" a conversation by advancing
+  # the horizon. This gives unread counts, unread badges and "Seen"
+  # indicators with zero extra writes per message (a receipts table writes
+  # N rows per message per N participants — the classic chat-schema scaling
+  # trap), and it's exactly how Basecamp's Campfire models it. If a future
+  # use case truly needs per-message receipts (e.g. per-member "read by 7/9"
+  # in large groups), they can be added as a new table without breaking this
+  # API.
+  class Participant < ApplicationRecord
+    self.table_name = "chats_participants"
+
+    ROLES = %w[member owner].freeze
+
+    belongs_to :conversation, class_name: "Chats::Conversation", inverse_of: :participants
+    belongs_to :messager, polymorphic: true
+
+    scope :active, -> { where(left_at: nil) }
+    scope :muted, -> { where.not(muted_at: nil) }
+
+    validates :role, inclusion: { in: ROLES }
+    # One-seat-per-messager uniqueness is enforced by the DB unique index
+    # ONLY: Conversation#add_participant! relies on `create_or_find_by!`,
+    # which needs the index violation (not a pre-insert validation) to make
+    # concurrent joins race-safe. Same rationale as Conversation#direct_key.
+    validate :group_must_have_room, on: :create
+
+    def owner? = role == "owner"
+    def left? = left_at.present?
+    def active? = left_at.nil?
+    def muted? = muted_at.present?
+
+    def display_name
+      Chats.display_name_for(messager)
+    end
+
+    # --- Read state -----------------------------------------------------------
+
+    # Messages this participant hasn't seen: anything newer than their read
+    # horizon, excluding their own messages and deleted tombstones. The
+    # explicit IS NULL leg keeps senderless SYSTEM messages counted — SQL's
+    # three-valued logic would otherwise drop them (NOT(NULL = …) is NULL,
+    # not TRUE). Same fix as Conversation.unread_by.
+    def unread_messages
+      conversation.messages.visible
+                  .where("chats_messages.created_at > ?", last_read_at || Conversation::EPOCH)
+                  .where(
+                    "chats_messages.sender_type IS NULL OR " \
+                    "NOT (chats_messages.sender_type = ? AND chats_messages.sender_id = ?)",
+                    messager_type, messager_id.to_s
+                  )
+    end
+
+    def unread_count
+      unread_messages.count
+    end
+
+    def unread?
+      unread_messages.exists?
+    end
+
+    # Advance the read horizon to now and tell everyone who cares:
+    #   - the conversation stream gets a fresh read-state payload (powers the
+    #     "Seen" indicator on the other side, when read receipts are on)
+    #   - this messager's OWN inbox + badge refresh (their other devices/tabs
+    #     should drop the unread highlight too)
+    #   - the HOST gets a `:conversation_read` notifier event — but only when
+    #     the horizon actually swallowed unread content. Hosts use it to keep
+    #     external notification surfaces truthful (e.g. mark this chat's rows
+    #     read in a notification center the moment the thread is read, so a
+    #     bell badge doesn't keep advertising messages the user has already
+    #     seen). Same notify hook as :message_created; error-isolated.
+    def read!(at: Time.current)
+      return self if last_read_at && last_read_at >= at
+
+      had_unread = unread?
+      update!(last_read_at: at)
+      broadcast_read_state if Chats.config.read_receipts
+      Chats::Broadcasts.refresh_inbox_of(messager)
+      Chats::Broadcasts.update_badge_of(messager)
+      Chats.notify(:conversation_read, conversation: conversation, participant: self) if had_unread
+      self
+    end
+
+    def mute! = update!(muted_at: Time.current)
+    def unmute! = update!(muted_at: nil)
+
+    def leave!
+      update!(left_at: Time.current)
+    end
+
+    # --- Notification etiquette (for host notifier hooks) ----------------------
+
+    # Should the host notify this participant about +message+? Encapsulates
+    # the etiquette every messaging product implements so each host doesn't
+    # re-derive it: don't notify yourself, the muted, the departed — and for
+    # debounced email digests, don't notify twice for the same unread burst.
+    def notifiable_for?(message)
+      return false if left? || muted?
+      return false if message.sender == messager
+
+      true
+    end
+
+    # For "email me only once until I come back" digests: true when there's
+    # something unread AND we haven't already notified since the last read.
+    # Pair with `mark_notified!` after actually sending.
+    def should_notify?
+      return false unless unread?
+
+      last_notified_at.nil? || last_notified_at < (last_read_at || Conversation::EPOCH)
+    end
+
+    def mark_notified!(at: Time.current)
+      update!(last_notified_at: at)
+    end
+
+    private
+
+    def group_must_have_room
+      return if conversation.nil? || conversation.direct?
+
+      max = Chats.config.max_group_size
+      return unless max && conversation.participants.active.count >= max
+
+      errors.add(:base, :group_full, count: max)
+    end
+
+    def broadcast_read_state
+      Chats::Broadcasts.read_state(conversation)
+    end
+  end
+end

data/lib/chats/models/reaction.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Chats
+  # An emoji reaction on a message. One row per (message, reactor, emoji) —
+  # the unique index makes `toggle!` race-safe. Reactors are polymorphic like
+  # every actor in this gem.
+  class Reaction < ApplicationRecord
+    self.table_name = "chats_reactions"
+
+    # Reactions are short by nature; 16 chars comfortably fits any emoji
+    # grapheme cluster (ZWJ sequences like 👨‍👩‍👧‍👦 are up to ~11 chars) while
+    # making "smuggle a paragraph into a reaction" impossible.
+    EMOJI_MAX_LENGTH = 16
+
+    belongs_to :message, class_name: "Chats::Message", inverse_of: :reactions
+    belongs_to :reactor, polymorphic: true
+
+    validates :emoji, presence: true, length: { maximum: EMOJI_MAX_LENGTH }
+    validates :emoji, uniqueness: { scope: %i[message_id reactor_type reactor_id] }
+    validate :reactions_must_be_enabled, on: :create
+    validate :reactor_must_be_participant, on: :create
+
+    # ONE after_commit with on: — NOT separate after_create_commit +
+    # after_destroy_commit macros: registering the SAME method name through
+    # two *_commit macros silently keeps only the last registration (each
+    # macro defines an after_commit filter keyed by method name). Documented
+    # Rails behavior: https://guides.rubyonrails.org/active_record_callbacks.html#using-both-after-create-commit-and-after-update-commit
+    after_commit :broadcast_change, on: %i[create destroy]
+
+    # Add the reaction if absent, remove it if present (the universal
+    # tap-to-toggle semantic). Returns the created reaction, or false when
+    # toggled off. Race-safe: a concurrent double-tap resolves through the
+    # unique index instead of raising.
+    def self.toggle!(message:, reactor:, emoji:)
+      existing = find_by(message: message, reactor: reactor, emoji: emoji)
+      if existing
+        existing.destroy!
+        false
+      else
+        create!(message: message, reactor: reactor, emoji: emoji)
+      end
+    rescue ActiveRecord::RecordNotUnique
+      # Lost the race with an identical create — treat as toggle-off.
+      find_by(message: message, reactor: reactor, emoji: emoji)&.destroy!
+      false
+    end
+
+    # Grouped summary for rendering: [["👍", 3], ["🚗", 1]] — stable order so
+    # bubbles don't shuffle when counts change.
+    def self.summary_for(message)
+      where(message: message).group(:emoji).count.sort_by { |emoji, _count| emoji }
+    end
+
+    private
+
+    def reactions_must_be_enabled
+      errors.add(:base, :reactions_disabled) unless Chats.config.reactions
+    end
+
+    def reactor_must_be_participant
+      return if message.nil? || reactor.nil?
+
+      errors.add(:reactor, :not_a_participant) unless message.conversation.participant?(reactor)
+    end
+
+    def broadcast_change
+      Chats::Broadcasts.message_updated(message) unless message.destroyed?
+    end
+  end
+end

data/lib/chats/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Chats
+  VERSION = "0.1.1"
+end