chats 0.1.1

data/lib/chats/models/concerns/messager.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Chats
+  # Included by `acts_as_messager`. Gives any model an inbox and the two
+  # verbs that make the whole gem read like plain English:
+  #
+  #   alice.chat_with(bob)                       # find-or-create the DM
+  #   alice.chat_with(bob, about: ride)          # the DM about that ride
+  #   alice.chat_with(bob, carol, title: "Trip") # a group
+  #
+  #   alice.message!(bob, "hola!")               # DM in one line
+  #   alice.message!(conversation, "hola!")      # or into a conversation
+  #
+  #   alice.chats                                # her inbox, newest first
+  #   alice.unread_chats_count                   # for the nav badge
+  module Messager
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :chat_participations,
+               class_name: "Chats::Participant",
+               as: :messager,
+               inverse_of: :messager,
+               dependent: :destroy
+
+      has_many :chat_conversations,
+               through: :chat_participations,
+               source: :conversation
+
+      # `dependent: :nullify`: when a messager account is destroyed, their
+      # messages stay as context for everyone else (sender shows as a
+      # localized "deleted account"), mirroring what every serious messaging
+      # product does. The sender-presence validation only runs on create, so
+      # orphaned rows remain valid.
+      has_many :chat_messages,
+               class_name: "Chats::Message",
+               as: :sender,
+               dependent: :nullify
+
+      Chats.register_messager(self)
+    end
+
+    # Find-or-create a conversation with one or more other messagers.
+    # One other → the direct thread (per-pair, or per-pair-per-subject when
+    # `about:` is given). Several others → a group.
+    #
+    # Raises Chats::BlockedError / Chats::NotAllowedError — see
+    # Conversation.direct_between! / .group!.
+    def chat_with(*others, about: nil, title: nil)
+      others = others.flatten.compact
+      raise ArgumentError, "chat_with requires at least one other messager" if others.empty?
+
+      if others.size == 1
+        Chats::Conversation.direct_between!(self, others.first, about: about)
+      else
+        Chats::Conversation.group!(self, others, title: title, about: about)
+      end
+    end
+
+    # Send a message — to a messager (resolving/creating the direct thread)
+    # or straight into a Chats::Conversation. Returns the Chats::Message.
+    #
+    #   alice.message!(bob, "are you coming?")
+    #   alice.message!(bob, "about the ride", about: ride)
+    #   alice.message!(conversation, "hi all!", files: [photo])
+    def message!(target, body = nil, about: nil, files: [], reply_to: nil)
+      conversation =
+        case target
+        when Chats::Conversation then target
+        else chat_with(target, about: about)
+        end
+
+      attributes = { sender: self, body: body, reply_to: reply_to }
+      attributes[:files] = files if files.present?
+      conversation.messages.create!(**attributes)
+    end
+
+    # The inbox: every active conversation, blocked counterparts hidden,
+    # newest activity first. A relation — chain `.limit`, `.includes`, etc.
+    def chats
+      Chats::Conversation.inbox_for(self)
+    end
+
+    # Number of conversations with unread messages (the WhatsApp-style nav
+    # badge counts conversations, not messages — 47 unread messages in one
+    # thread is still "1 thing to deal with").
+    def unread_chats_count
+      # reorder(nil): the inbox scope orders by a COALESCE expression, which
+      # PostgreSQL rejects inside a COUNT(DISTINCT …) aggregate.
+      chats.unread_by(self).reorder(nil).distinct.count
+    end
+
+    def unread_chats?
+      chats.unread_by(self).reorder(nil).exists?
+    end
+
+    # This messager's participant row in +conversation+ (nil when not in it).
+    def chat_participation_in(conversation)
+      conversation.participant_for(self)
+    end
+  end
+end

data/lib/chats/models/conversation.rb

@@ -0,0 +1,347 @@
+# frozen_string_literal: true
+
+module Chats
+  # A conversation: either a +direct+ 1:1 thread or a +group+. Optionally
+  # *about* a host record (the polymorphic +subject+ — a ride, an order, a
+  # listing), which is how marketplace-style apps attach a chat to a domain
+  # object.
+  #
+  # == Direct conversations & the +direct_key+
+  #
+  # Two people opening a DM with each other at the same instant must end up
+  # in the SAME conversation. We guarantee that with a deterministic
+  # +direct_key+ ("the sorted pair of participant keys, plus the subject key
+  # when the conversation is about something") backed by a UNIQUE index, and
+  # `create_or_find_by!` which turns the index violation into a find. See
+  # `.direct_between!`.
+  #
+  # The subject participates in the key on purpose: the same pair can have
+  # one thread per subject (per-listing threads, marketplace-style) AND one
+  # subjectless thread (classic DMs). The host picks the cardinality simply
+  # by passing or omitting `about:`.
+  #
+  # == Denormalization
+  #
+  # +last_message_at+ and +last_message_id+ exist so the inbox (the hottest
+  # query in any messaging product) is one indexed ORDER BY plus one
+  # `includes(:last_message)` — no MAX() subqueries, no N+1.
+  class Conversation < ApplicationRecord
+    self.table_name = "chats_conversations"
+
+    KINDS = %w[direct group].freeze
+    TITLE_MAX_LENGTH = 120
+    EPOCH = Time.utc(1970).freeze
+
+    belongs_to :subject, polymorphic: true, optional: true
+    # No DB foreign key on last_message_id (see migration): a circular
+    # conversations<->messages FK pair makes deletes order-dependent. The
+    # association is best-effort denormalization, never authority.
+    belongs_to :last_message, class_name: "Chats::Message", optional: true
+
+    has_many :participants,
+             class_name: "Chats::Participant",
+             inverse_of: :conversation,
+             dependent: :destroy
+    has_many :messages,
+             class_name: "Chats::Message",
+             inverse_of: :conversation,
+             dependent: :destroy
+
+    scope :direct, -> { where(kind: "direct") }
+    # `groups` (plural): `scope :group` would collide with ActiveRecord's own
+    # GROUP BY class method.
+    scope :groups, -> { where(kind: "group") }
+    scope :about, ->(subject) { where(subject: subject) }
+    scope :recent_first, lambda {
+      # COALESCE keeps freshly-created (still message-less) conversations
+      # sorted by creation time, portable across sqlite/postgres/mysql
+      # (no NULLS LAST, which sqlite/mysql spell differently).
+      order(Arel.sql("COALESCE(chats_conversations.last_message_at, chats_conversations.created_at) DESC"))
+    }
+
+    # A messager's inbox: every conversation they're an active participant of
+    # (not left), minus direct threads with someone they're blocked with,
+    # newest activity first. THE hot query — keep it composable and indexed.
+    scope :inbox_for, lambda { |messager|
+      joins(:participants)
+        .where(chats_participants: { left_at: nil })
+        .where(chats_participants: { messager_type: messager.class.polymorphic_name, messager_id: messager.id })
+        .excluding_blocked_for(messager)
+        .recent_first
+    }
+
+    # Hide direct conversations whose counterpart is blocked (either
+    # direction — `Chats.blocked_ids_for` is bidirectional by contract).
+    # Group conversations are NOT hidden: industry standard is that blocking
+    # someone doesn't eject you from shared group spaces. Data is never
+    # deleted — lift the block and the thread reappears.
+    scope :excluding_blocked_for, lambda { |messager|
+      blocked_ids = Chats.blocked_ids_for(messager)
+      next all if blocked_ids.respond_to?(:empty?) && blocked_ids.empty?
+
+      blocked_seats = Chats::Participant.select(:conversation_id).where(
+        messager_type: messager.class.polymorphic_name, messager_id: blocked_ids
+      )
+
+      where.not(id: direct.where(id: blocked_seats))
+    }
+
+    # Conversations holding messages the messager hasn't read yet (excluding
+    # their own messages and tombstones). Compose with `inbox_for`:
+    #   Chats::Conversation.inbox_for(user).unread_by(user).distinct.count
+    scope :unread_by, lambda { |messager|
+      joins(:participants, :messages)
+        .where(chats_participants: { messager_type: messager.class.polymorphic_name, messager_id: messager.id })
+        .where(chats_messages: { deleted_at: nil })
+        .where("chats_messages.created_at > COALESCE(chats_participants.last_read_at, ?)", EPOCH)
+        # "Not sent by me" — with an explicit IS NULL leg: system messages
+        # have a NULL sender, and in SQL's three-valued logic a bare
+        # NOT(sender_type = X AND …) evaluates to NULL (not TRUE) for them,
+        # silently dropping system messages from unread counts.
+        .where(
+          "chats_messages.sender_type IS NULL OR NOT (chats_messages.sender_type = ? AND chats_messages.sender_id = ?)",
+          messager.class.polymorphic_name, messager.id.to_s
+        )
+    }
+
+    validates :kind, inclusion: { in: KINDS }
+    validates :title, length: { maximum: TITLE_MAX_LENGTH }, allow_blank: true
+    # direct_key uniqueness is enforced by the DB unique index ONLY — on
+    # purpose, not an oversight. `create_or_find_by!` (the race-safe
+    # find-or-create in .direct_between!) works by attempting the INSERT and
+    # converting the index violation into a find; a model-level uniqueness
+    # validation would fire first, raise RecordInvalid, and break the whole
+    # mechanism. https://api.rubyonrails.org/classes/ActiveRecord/Relation.html#method-i-create_or_find_by
+    validate :groups_must_be_enabled, if: :group?
+
+    # --- Finding & creating ---------------------------------------------------
+
+    class << self
+      # The direct conversation between +a+ and +b+ (about +subject+, when
+      # given), or nil. Read-only twin of `.direct_between!`.
+      def direct_between(a, b, about: nil)
+        find_by(direct_key: direct_key_for([a, b], subject: about))
+      end
+
+      # Find-or-create the direct conversation between two messagers,
+      # race-safely (see class comment). Raises:
+      #   Chats::BlockedError    if the pair is blocked (either direction)
+      #   Chats::NotAllowedError if the host `can_message` policy says no
+      def direct_between!(a, b, about: nil)
+        raise ArgumentError, "both participants are required" if a.nil? || b.nil?
+        raise ArgumentError, "can't open a conversation with yourself" if a == b
+        raise Chats::BlockedError, "messagers are blocked" if Chats.blocked_between?(a, b)
+        raise Chats::NotAllowedError, "policy forbids messaging" unless Chats.can_message?(a, b)
+
+        conversation = create_or_find_by!(direct_key: direct_key_for([a, b], subject: about)) do |c|
+          c.kind = "direct"
+          c.subject = about
+        end
+
+        # `create_or_find_by!` may have FOUND a conversation created a moment
+        # ago by the other side — participants are ensured idempotently
+        # either way (their own unique index makes this race-safe too).
+        [a, b].each { |messager| conversation.add_participant!(messager) }
+        conversation
+      end
+
+      # Create a group conversation. +others+ excludes the creator (who joins
+      # as "owner"). Raises Chats::NotAllowedError when groups are disabled
+      # or the host `can_create_group` policy says no.
+      def group!(creator, others, title: nil, about: nil)
+        raise Chats::NotAllowedError, "group conversations are disabled" unless Chats.config.groups
+        unless Chats.config.can_create_group.call(creator)
+          raise Chats::NotAllowedError,
+                "policy forbids creating groups"
+        end
+
+        others = Array(others) - [creator]
+        raise ArgumentError, "a group needs at least 2 other participants" if others.size < 2
+
+        transaction do
+          conversation = create!(kind: "group", title: title, subject: about)
+          conversation.add_participant!(creator, role: "owner")
+          others.each { |messager| conversation.add_participant!(messager) }
+          conversation
+        end
+      end
+
+      # Deterministic identity for a direct pair (+ optional subject).
+      # GlobalID params already encode class + id, so "User 4" and
+      # "Organization 4" can never collide. Sorting makes it order-independent.
+      def direct_key_for(pair, subject: nil)
+        key = pair.map { |messager| Chats.messager_key(messager) }.sort.join("|")
+        key += "|about:#{subject.to_global_id.to_param}" if subject
+        key
+      end
+
+      # Per-conversation unread counts for a messager over a set of
+      # conversations, in ONE grouped query — the inbox uses this to render
+      # row badges without N+1:
+      #   Chats::Conversation.unread_counts_for(user, conversations) # => { id => count }
+      def unread_counts_for(messager, conversations)
+        ids = Array(conversations).map { |c| c.is_a?(Conversation) ? c.id : c }
+        return {} if ids.empty?
+
+        unread_by(messager).where(chats_conversations: { id: ids })
+                           .group("chats_conversations.id")
+                           .count("chats_messages.id")
+      end
+    end
+
+    # --- Predicates & lookups -------------------------------------------------
+
+    def direct? = kind == "direct"
+    def group? = kind == "group"
+
+    def participant_for(messager)
+      return nil if messager.nil?
+
+      participants.find_by(messager: messager)
+    end
+
+    def participant?(messager)
+      return false if messager.nil?
+
+      participants.active.exists?(messager_type: messager.class.polymorphic_name, messager_id: messager.id)
+    end
+
+    def other_participants(messager)
+      participants.active.where.not(
+        messager_type: messager.class.polymorphic_name, messager_id: messager.id
+      )
+    end
+
+    # What this conversation is called from +viewer+'s seat: a direct thread
+    # is named after the counterpart; a group after its title (or its
+    # members, when untitled).
+    def title_for(viewer)
+      if direct?
+        other = other_participants(viewer).includes(:messager).first
+        other ? Chats.display_name_for(other.messager) : I18n.t("chats.conversation.empty_title")
+      else
+        title.presence || participants.active.includes(:messager).limit(4).map do |p|
+          Chats.display_name_for(p.messager)
+        end.join(", ")
+      end
+    end
+
+    # A short human label for the subject ("Madrid → Barcelona", "Order
+    # #4221"), provided by the subject model via `chat_subject_label`
+    # (see Chats::ChatSubject). Nil when the conversation is about nothing.
+    def subject_label
+      return nil if subject.nil?
+
+      subject.try(:chat_subject_label) || "#{subject.class.model_name.human} #{subject.id}"
+    end
+
+    # --- Membership -----------------------------------------------------------
+
+    # Idempotent, race-safe membership. Re-adding someone who left re-joins
+    # them (their read state survives — by design, so history isn't re-marked
+    # unread).
+    def add_participant!(messager, role: "member")
+      participant = participants.create_or_find_by!(
+        messager_type: messager.class.polymorphic_name, messager_id: messager.id
+      ) do |p|
+        p.role = role
+      end
+      participant.update!(left_at: nil) if participant.left?
+      participant
+    end
+
+    # --- Messaging ------------------------------------------------------------
+
+    # Post a message from your APP into the conversation — "Your ride was
+    # cancelled", "Payment received" — rendered as a centered system note,
+    # not a bubble. This is the stable entry point notification systems
+    # (e.g. a Noticed delivery method) should call.
+    def post_system_message!(body)
+      messages.create!(kind: "system", body: body)
+    end
+
+    # --- Read state -----------------------------------------------------------
+
+    def unread_count_for(messager)
+      participant_for(messager)&.unread_count || 0
+    end
+
+    def unread_for?(messager)
+      unread_count_for(messager).positive?
+    end
+
+    def mark_read_by!(messager)
+      participant_for(messager)&.read!
+    end
+
+    # Denormalized pointers the inbox sorts/previews by. Called from
+    # Chats::Message callbacks inside the message's own transaction.
+    # `update_columns` on purpose: no validations/callbacks/broadcast loops —
+    # this is bookkeeping, not domain change. updated_at is bumped manually
+    # so fragment caches keyed on the conversation still invalidate.
+    def register_last_message!(message) # :nodoc:
+      update_columns(
+        last_message_at: message.created_at,
+        last_message_id: message.id,
+        updated_at: Time.current
+      )
+    end
+
+    def recompute_last_message! # :nodoc:
+      latest = messages.order(created_at: :desc, id: :desc).first
+      update_columns(
+        last_message_at: latest&.created_at,
+        last_message_id: latest&.id,
+        updated_at: Time.current
+      )
+    end
+
+    # --- Moderation contract (duck-typed, zero coupling) ------------------------
+    #
+    # These methods make the conversation a well-behaved reportable the moment
+    # the HOST includes the moderate gem's concern (`Chats::Conversation.
+    # has_reportable_content :title`). They're plain Ruby — defining them
+    # without moderate installed costs nothing. See README "Trust & Safety".
+
+    def reported_owner
+      # The accountable human for a conversation: its owner (groups) or the
+      # first participant (direct — moderation of direct threads usually
+      # targets a specific *message*, but DSA tooling wants an owner).
+      owner = participants.find_by(role: "owner") || participants.order(:created_at).first
+      owner&.messager
+    end
+
+    def moderation_label
+      "Chat conversation #{id}"
+    end
+
+    def moderation_snapshot(field)
+      title if field.to_s == "title"
+    end
+
+    def removable_reported_field?(field)
+      field.to_s == "title" && title.present?
+    end
+
+    def remove_reported_field!(field)
+      return false unless field.to_s == "title"
+
+      update!(title: nil)
+      true
+    end
+
+    def report_visible_to?(viewer, field: nil)
+      participant?(viewer)
+    end
+
+    def moderation_content_type
+      group? ? "group" : "conversation"
+    end
+
+    private
+
+    def groups_must_be_enabled
+      errors.add(:kind, :groups_disabled) unless Chats.config.groups
+    end
+  end
+end