chats 0.1.1

data/app/controllers/chats/application_controller.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Chats
+  # Base controller for every engine screen. It inherits from the HOST's
+  # controller (config.parent_controller, "::ApplicationController" by
+  # default) so the host's layout, helpers, auth filters, locale switching
+  # and exception handling all apply to the chat screens for free — the same
+  # integration style as api_keys' dashboard.
+  #
+  # NOTE: the superclass is resolved when this class is autoloaded, which in
+  # a booted app happens AFTER initializers — so `config.parent_controller`
+  # set in config/initializers/chats.rb is honored. In development the class
+  # is reloaded on every change, picking up config changes too.
+  class ApplicationController < Chats.config.parent_controller.constantize
+    before_action :chats_authenticate!
+
+    helper Chats::EngineHelper
+    helper_method :chats_current_messager
+
+    layout :chats_layout
+
+    private
+
+    # The conversing actor for this request, via the host-configured method
+    # (`current_user` by default — Devise-compatible out of the box).
+    def chats_current_messager
+      @chats_current_messager ||= begin
+        method_name = Chats.config.current_messager_method
+        unless respond_to?(method_name, true)
+          raise Chats::ConfigurationError,
+                "chats can't find ##{method_name} on #{self.class.superclass.name}. " \
+                "Set config.current_messager_method in config/initializers/chats.rb " \
+                "to the controller method that returns the logged-in #{Chats.config.messager_class}."
+        end
+
+        send(method_name)
+      end
+    end
+
+    def chats_authenticate!
+      method_name = Chats.config.authenticate_method
+      unless respond_to?(method_name, true)
+        raise Chats::ConfigurationError,
+              "chats can't find ##{method_name} on #{self.class.superclass.name}. " \
+              "Set config.authenticate_method in config/initializers/chats.rb " \
+              "to your authentication filter (e.g. :authenticate_user! with Devise)."
+      end
+
+      send(method_name)
+    end
+
+    # nil falls through to the parent controller's regular layout resolution,
+    # so by default chat screens look like the rest of the host app.
+    def chats_layout
+      Chats.config.layout
+    end
+
+    # Conversations are ALWAYS resolved through the viewer's own inbox
+    # relation: not-a-participant, left, or blocked-counterpart threads all
+    # come back as a plain 404 — existence is never leaked to outsiders.
+    def find_conversation(id = params[:id])
+      chats_current_messager.chats.find(id)
+    end
+  end
+end

data/app/controllers/chats/conversations_controller.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+module Chats
+  # The inbox (index), the thread (show), starting conversations from host
+  # pages (create), and the per-member actions (read/typing/leave/mute).
+  class ConversationsController < ApplicationController
+    before_action :set_conversation, only: %i[show read typing leave mute unmute refresh]
+
+    # The inbox. Everything is preloaded/batched so rendering N rows costs a
+    # constant number of queries (conversations + last messages + participants
+    # + one grouped unread-count query — see Conversation.unread_counts_for).
+    def index
+      @conversations = chats_current_messager.chats
+                                             .includes(:last_message, :subject, participants: :messager)
+                                             .limit(200)
+      @conversations = apply_search(@conversations)
+      @unread_counts = Chats::Conversation.unread_counts_for(chats_current_messager, @conversations)
+    end
+
+    # The thread. Renders the LATEST page of messages; older pages stream in
+    # through a lazy Turbo Frame chain (keyset-paginated — see
+    # Message.before_message and _messages_page.html.erb).
+    def show
+      @participant = @conversation.participant_for(chats_current_messager)
+
+      anchor = params[:before].present? ? @conversation.messages.find_by(id: params[:before]) : nil
+      scope = @conversation.messages.includes(:sender, :reactions)
+      scope = scope.with_attached_files if scope.respond_to?(:with_attached_files)
+      scope = scope.before_message(anchor) if anchor
+
+      # Fetch newest-first + reverse so "the last N messages" render in
+      # chronological order. One extra record peeks whether older pages exist.
+      page = scope.recent_first.limit(Chats.config.messages_per_page + 1).to_a
+      @more_messages = page.size > Chats.config.messages_per_page
+      @messages = page.first(Chats.config.messages_per_page).reverse
+
+      if anchor
+        # Older-page request from the pagination frame: render just the page.
+        render partial: "chats/conversations/messages_page",
+               locals: { conversation: @conversation, messages: @messages, more: @more_messages }
+      else
+        # The «new messages» divider: computed BEFORE read! advances the
+        # horizon (after it, nothing is unread anymore). Anchored to the
+        # oldest unread bubble on the rendered page; when the backlog runs
+        # deeper than one page it pins to the top of the page instead —
+        # the scroll-up frame chain holds the rest.
+        if @participant&.unread?
+          @first_unread_id = @participant.unread_messages.where(id: @messages.map(&:id)).oldest_first.pick(:id) ||
+                             @messages.first&.id
+        end
+
+        # Opening the thread reads it. (Live appends while the thread stays
+        # open are read via the thread controller's POST to #read.)
+        @participant&.read!
+      end
+    end
+
+    # Stale-thread catch-up: appends messages created — and replaces ones
+    # edited/tombstoned — since the newest `updated_at` the client has
+    # rendered (`?since=` in ms). The thread controller calls this when the
+    # tab wakes from a long sleep or its Turbo Stream subscription
+    # reconnects, i.e. whenever broadcasts may have been missed. Mobile
+    # WebViews suspend WebSockets aggressively, so without this a
+    # backgrounded chat silently loses messages until a manual reload.
+    # Pattern from Basecamp's Campfire (Rooms::RefreshesController):
+    # https://github.com/basecamp/once-campfire
+    def refresh
+      head :no_content and return if params[:since].blank?
+
+      since = Time.zone.at(0, params[:since].to_i, :millisecond)
+      scope = @conversation.messages.includes(:sender, :reactions)
+      scope = scope.with_attached_files if scope.respond_to?(:with_attached_files)
+
+      @new_messages = scope.created_since(since).oldest_first.limit(Chats.config.messages_per_page + 1).to_a
+
+      # A backlog deeper than one page would mean splicing an arbitrary
+      # amount of history through surgical appends; a Turbo 8 page refresh
+      # (morph + scroll preservation) re-renders the latest page + frame
+      # chain correctly instead. Raw tag rather than `turbo_stream.refresh`
+      # so we don't depend on turbo-rails ≥ 2.0 helpers.
+      if @new_messages.size > Chats.config.messages_per_page
+        render html: '<turbo-stream action="refresh"></turbo-stream>'.html_safe,
+               content_type: "text/vnd.turbo-stream.html"
+        return
+      end
+
+      @updated_messages = scope.updated_since(since)
+      render "chats/conversations/refresh", formats: :turbo_stream
+    end
+
+    # Start (or resume) a direct conversation from a host page. The
+    # recipient/subject arrive as SIGNED GlobalIDs minted by the
+    # `chat_button_to` helper — unforgeable and purpose-scoped, so raw
+    # polymorphic params never reach `GlobalID::Locator`. Policy and block
+    # checks still run inside `chat_with` (defense in depth).
+    def create
+      recipient = locate_signed!(params.require(:recipient_sgid), purpose: :chats_recipient)
+      raise ActiveRecord::RecordNotFound unless Chats.messager_class?(recipient.class)
+
+      subject = params[:subject_sgid].presence &&
+                locate_signed!(params[:subject_sgid], purpose: :chats_subject)
+
+      conversation = chats_current_messager.chat_with(recipient, about: subject)
+      redirect_to conversation_path(conversation)
+    rescue Chats::BlockedError
+      # Fallback is the INBOX (engine root) — inside the engine, `root_path`
+      # already resolves there, never to the host root.
+      redirect_back fallback_location: conversations_path, alert: t("chats.flashes.blocked")
+    rescue Chats::NotAllowedError
+      redirect_back fallback_location: conversations_path, alert: t("chats.flashes.not_allowed")
+    end
+
+    # Advance the viewer's read horizon. Called by the thread Stimulus
+    # controller (debounced) when new messages arrive while the thread is
+    # visible. Side effects (read-state broadcast, badge refresh) live in
+    # Participant#read!.
+    def read
+      @conversation.participant_for(chats_current_messager)&.read!
+      head :no_content
+    end
+
+    # Ephemeral typing ping (client throttles to ~1 every 3s while typing).
+    # Nothing is persisted; see Chats::Broadcasts.typing.
+    def typing
+      Chats::Broadcasts.typing(@conversation, chats_current_messager) if Chats.config.typing_indicators
+      head :no_content
+    end
+
+    def leave
+      # Direct threads can't be left (mute or block instead) — leaving would
+      # strand a 1:1 thread in a weird half-state.
+      raise ActiveRecord::RecordNotFound if @conversation.direct?
+
+      title = @conversation.title_for(chats_current_messager)
+      @conversation.participant_for(chats_current_messager)&.leave!
+      redirect_to conversations_path, notice: t("chats.flashes.left", title: title)
+    end
+
+    def mute
+      @conversation.participant_for(chats_current_messager)&.mute!
+      redirect_to conversation_path(@conversation), notice: t("chats.flashes.muted")
+    end
+
+    def unmute
+      @conversation.participant_for(chats_current_messager)&.unmute!
+      redirect_to conversation_path(@conversation), notice: t("chats.flashes.unmuted")
+    end
+
+    private
+
+    def set_conversation
+      @conversation = find_conversation
+    end
+
+    def locate_signed!(sgid, purpose:)
+      GlobalID::Locator.locate_signed(sgid, for: purpose) || raise(ActiveRecord::RecordNotFound)
+    end
+
+    # Partial, case-insensitive matching across the inbox metadata users can
+    # actually see: participant names, conversation titles, subject labels,
+    # and message bodies. The inbox is capped at 200 rows, so metadata is
+    # filtered portably in Ruby from the already-preloaded objects while the
+    # potentially larger message-body set stays in SQL. No PostgreSQL-only
+    # full-text dependency is needed for this scale.
+    def apply_search(conversations)
+      return conversations unless Chats.config.search
+
+      query = params[:q].to_s.strip
+      return conversations if query.empty?
+
+      loaded = conversations.to_a
+      normalized_query = query.downcase
+      pattern = "%#{Chats::Conversation.sanitize_sql_like(query.downcase)}%"
+      message_match_ids =
+        if Chats.config.encrypt_messages
+          []
+        else
+          Chats::Message.where(conversation_id: loaded.map(&:id), deleted_at: nil)
+                        .where("LOWER(chats_messages.body) LIKE ?", pattern)
+                        .distinct
+                        .pluck(:conversation_id)
+        end
+
+      loaded.select do |conversation|
+        message_match_ids.include?(conversation.id) ||
+          searchable_metadata(conversation).downcase.include?(normalized_query)
+      end
+    end
+
+    def searchable_metadata(conversation)
+      participant_names = conversation.participants.filter_map do |participant|
+        Chats.display_name_for(participant.messager) if participant.active?
+      end
+
+      [conversation.title, conversation.subject_label, *participant_names].compact.join(" ")
+    end
+  end
+end

data/app/controllers/chats/messages_controller.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Chats
+  # Sending, editing, soft-deleting, and re-rendering message bubbles.
+  class MessagesController < ApplicationController
+    before_action :set_conversation
+    before_action :set_message, only: %i[show update destroy]
+    before_action :require_ownership!, only: %i[update destroy]
+
+    # Per-sender send throttle via Rails 8's built-in controller rate
+    # limiting (https://api.rubyonrails.org/classes/ActionController/RateLimiting.html).
+    # Feature-detected so the gem still loads on Rails 7.1 (where this is
+    # simply not enforced). Keyed by messager, not IP — one abusive account
+    # behind a corporate NAT must not silence the rest.
+    if respond_to?(:rate_limit) && Chats.config.send_rate_limit
+      rate_limit(
+        **Chats.config.send_rate_limit,
+        only: :create,
+        by: -> { send(Chats.config.current_messager_method)&.to_gid&.to_s || request.remote_ip },
+        with: -> { head :too_many_requests }
+      )
+    end
+
+    # A single bubble, re-rendered. Exists for one delightful reason: it's
+    # the "cancel edit" target — replacing the inline edit form back with the
+    # plain bubble via one turbo_stream GET, no full page reload.
+    def show
+      render_bubble_replacement
+    end
+
+    def create
+      @message = @conversation.messages.new(message_params.merge(sender: chats_current_messager))
+
+      if @message.save
+        respond_to do |format|
+          # The sender's OWN bubble appends instantly from this response (no
+          # waiting for the Action Cable round-trip); the broadcast then
+          # delivers the same element to everyone else — and to the sender
+          # again, where Turbo's append dedup (same DOM id) makes it a no-op.
+          format.turbo_stream
+          format.html { redirect_to conversation_path(@conversation) }
+        end
+      else
+        respond_to do |format|
+          format.turbo_stream { render :errors, status: :unprocessable_entity }
+          format.html do
+            redirect_to conversation_path(@conversation),
+                        alert: @message.errors.full_messages.to_sentence
+          end
+        end
+      end
+    end
+
+    # Swap the bubble for an inline edit form (turbo_stream), with a plain
+    # page as the no-JS fallback.
+    # Edits arrive from the COMPOSER (the long-press → Editar flow re-targets
+    # the composer form at this URL with _method=patch), so failures render
+    # into the composer's error slot — same surface as failed sends.
+    def update
+      @message.edit!(message_params[:body])
+      render_bubble_replacement
+    rescue ActiveRecord::RecordInvalid, Chats::NotAllowedError
+      render :errors, status: :unprocessable_entity
+    end
+
+    # Soft delete by default: tombstone the bubble (see Message#soft_delete!).
+    def destroy
+      @message.soft_delete!
+
+      respond_to do |format|
+        format.turbo_stream do
+          if @message.destroyed?
+            render turbo_stream: turbo_stream.remove(@message)
+          else
+            render_bubble_replacement
+          end
+        end
+        format.html { redirect_to conversation_path(@conversation) }
+      end
+    end
+
+    private
+
+    def set_conversation
+      @conversation = find_conversation(params[:conversation_id])
+    end
+
+    def set_message
+      @message = @conversation.messages.find(params[:id])
+    end
+
+    # Editing/deleting is for the author alone. 404 (not 403) so the action's
+    # existence mirrors what the actor can see — consistent with every other
+    # authorization miss in the engine.
+    def require_ownership!
+      raise ActiveRecord::RecordNotFound unless @message.sent_by?(chats_current_messager)
+    end
+
+    def message_params
+      permitted = %i[body reply_to_id]
+      permitted << { files: [] } if Chats.config.attachments
+      params.require(:message).permit(*permitted)
+    end
+
+    def render_bubble_replacement
+      respond_to do |format|
+        format.turbo_stream do
+          render turbo_stream: turbo_stream.replace(
+            @message,
+            partial: "chats/messages/message",
+            locals: { message: @message }
+          )
+        end
+        format.html { redirect_to conversation_path(@conversation) }
+      end
+    end
+  end
+end

data/app/controllers/chats/reactions_controller.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Chats
+  # Emoji reactions: tap-to-toggle, one endpoint.
+  class ReactionsController < ApplicationController
+    # Toggle: adds or removes (Reaction.toggle! is race-safe through the
+    # unique index). The response re-renders the bubble for the actor; the
+    # broadcast updates everyone else.
+    def create
+      conversation = find_conversation(params[:conversation_id])
+      message = conversation.messages.find(params[:message_id])
+
+      Chats::Reaction.toggle!(
+        message: message,
+        reactor: chats_current_messager,
+        emoji: params.require(:emoji)
+      )
+
+      respond_to do |format|
+        format.turbo_stream do
+          render turbo_stream: turbo_stream.replace(
+            message,
+            partial: "chats/messages/message",
+            locals: { message: message }
+          )
+        end
+        format.html { redirect_to conversation_path(conversation) }
+      end
+    rescue ActiveRecord::RecordInvalid
+      head :unprocessable_entity
+    end
+  end
+end

data/app/helpers/chats/engine_helper.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+module Chats
+  # View helpers, available BOTH inside the engine's own views and in the
+  # HOST app's views (mixed into ActionView via the engine's on_load hook,
+  # the same pattern the moderate gem uses for `report_link`).
+  module EngineHelper
+    # The "message this person" affordance for host pages — a listing, a
+    # profile, an order. Renders nothing when there's no viewer, the viewer
+    # IS the target, or policy/blocks forbid the pair, so it's always safe
+    # to drop into a page unconditionally:
+    #
+    #   <%= chat_button_to @driver, about: @ride, label: "Chat with driver" %>
+    #
+    # The recipient/subject travel as SIGNED GlobalIDs (purpose-scoped,
+    # minted here, verified in Chats::ConversationsController#create), so the
+    # endpoint never trusts raw polymorphic params. `expires_in: nil` because
+    # these buttons sit on long-lived pages — the default 1-month sgid expiry
+    # would quietly break stale tabs.
+    def chat_button_to(other, about: nil, label: nil, **html_options)
+      viewer = chats_viewer
+      return if viewer.nil? || other.nil? || viewer == other
+      return unless Chats.can_message?(viewer, other)
+
+      params = { recipient_sgid: other.to_sgid(expires_in: nil, for: :chats_recipient).to_s }
+      params[:subject_sgid] = about.to_sgid(expires_in: nil, for: :chats_subject).to_s if about
+
+      button_to(
+        label || I18n.t("chats.buttons.chat"),
+        chats_routes.conversations_path,
+        params: params,
+        method: :post,
+        **html_options
+      )
+    end
+
+    # A live unread-conversations badge, embeddable on ANY page (nav bars,
+    # tab docks). Subscribes to the messager's badge stream so it updates in
+    # real time without refreshing the page it sits on (see
+    # Chats::Broadcasts for why badges get their own stream).
+    def chats_unread_badge(messager = chats_viewer)
+      return if messager.nil?
+
+      safe_join([
+                  turbo_stream_from(messager, :chats_badge),
+                  render(partial: "chats/shared/unread_badge", locals: { count: messager.unread_chats_count })
+                ])
+    end
+
+    # An avatar for any messager: whatever `config.messager_avatar` returns
+    # (URL / ActiveStorage attachment / variant) or an initials placeholder.
+    def chats_messager_avatar(messager, css_class: "chats-avatar", loading: "eager")
+      name = Chats.display_name_for(messager).presence || "?"
+      source = begin
+        avatar = Chats.avatar_for(messager)
+        # An ActiveStorage attachment that isn't attached renders as a broken
+        # image — treat it as "no avatar" instead.
+        avatar.respond_to?(:attached?) && !avatar.attached? ? nil : avatar
+      end
+
+      if source
+        image_tag chats_avatar_image_source(source), alt: name, class: css_class, loading: loading
+      else
+        initials = name.split.first(2).map { |word| word[0] }.join.upcase
+        tag.span(initials, class: "#{css_class} chats-avatar--initials", "aria-hidden": true)
+      end
+    end
+
+    # WhatsApp-style compact timestamps, deliberately numeric so they need no
+    # date-name translations (many apps don't bundle rails-i18n; the gem must
+    # not require it): today → "14:05", this week-ish → "9/6", older → "9/6/25".
+    def chats_timestamp(time)
+      return "" if time.nil?
+
+      local = time.in_time_zone
+      if local.today?
+        local.strftime("%H:%M")
+      elsif local.year == Time.current.year
+        local.strftime("%-d/%-m")
+      else
+        local.strftime("%-d/%-m/%y")
+      end
+    end
+
+    # The inbox-row preview line for a conversation's latest message.
+    def chats_preview_for(conversation, viewer)
+      message = conversation.last_message
+      return I18n.t("chats.inbox.no_messages") if message.nil?
+
+      text =
+        if message.deleted?
+          I18n.t("chats.message.deleted")
+        elsif message.body.present?
+          message.body.truncate(90)
+        elsif message.attachments?
+          "📷 #{I18n.t("chats.message.attachment")}"
+        else
+          ""
+        end
+
+      # Tombstones read as a statement ("Message deleted") — never prefixed.
+      # Otherwise: "You:" for own messages, and in GROUPS the sender's first
+      # name (WhatsApp-style), since "who said it" is ambiguous there. System
+      # messages (no sender) stay bare.
+      prefix =
+        if message.deleted?
+          nil
+        elsif message.sent_by?(viewer)
+          I18n.t("chats.inbox.you_prefix")
+        elsif conversation.group? && message.sender
+          "#{Chats.display_name_for(message.sender).split.first}:"
+        end
+      [prefix, text].compact.join(" ")
+    end
+
+    # The avatar shown on an inbox row: the counterpart's (direct) or an
+    # initials disc from the group name.
+    def chats_conversation_avatar(conversation, viewer)
+      if conversation.direct?
+        other = conversation.other_participants(viewer).first
+        chats_messager_avatar(other&.messager)
+      else
+        initials = conversation.title_for(viewer).split.first(2).map { |word| word[0] }.join.upcase
+        tag.span(initials.presence || "👥", class: "chats-avatar chats-avatar--initials chats-avatar--group",
+                                           "aria-hidden": true)
+      end
+    end
+
+    # The gem's bundled stylesheet (CSS-variable themed — see chats.css).
+    # Called from the engine's own views; hosts that eject + restyle the
+    # views with their own framework simply don't include it.
+    def chats_styles
+      stylesheet_link_tag "chats", "data-turbo-track": "reload"
+    end
+
+    # Engine URL helpers that work from EVERY render context — this is more
+    # subtle than it looks, and the reason the broadcast partials use it:
+    #
+    #   * host views & the broadcast renderer (Turbo broadcasts render through
+    #     the host's ApplicationController renderer — no engine request, no
+    #     SCRIPT_NAME): the mounted proxy (`chats.`) carries the mount prefix
+    #     baked in at mount time, so URLs come out right with no request.
+    #   * engine views during requests: the engine controller inherits from
+    #     the host's ApplicationController, so the proxy is available there
+    #     too (and bare helpers would also work — the proxy just works
+    #     everywhere).
+    #   * no mount at all (bare view tests): fall back to the engine's own
+    #     url_helpers (prefix-less, but nothing better exists without a mount).
+    #
+    # NOTE: assumes the default mount name (`mount Chats::Engine => "/x"`
+    # auto-names the proxy `chats`). Hosts using `as: :something_else` should
+    # override this helper.
+    def chats_routes
+      respond_to?(:chats) ? chats : Chats::Engine.routes.url_helpers
+    end
+
+    private
+
+    # The current messager in whatever context the helper runs (host or
+    # engine view), resolved through the configured controller method.
+    def chats_viewer
+      method_name = Chats.config.current_messager_method
+      respond_to?(method_name) ? send(method_name) : nil
+    end
+
+    # Active Storage routes are drawn on the host app, not on this isolated
+    # engine. A bare `image_tag variant` is fine in normal host views, but
+    # inside engine views it asks the engine route set to polymorphically
+    # resolve ActiveStorage::VariantWithRecord and can fall through to
+    # `to_model`. Build the same proxy/redirect routes Rails would build,
+    # explicitly against the host route set, before `image_tag` sees it.
+    def chats_avatar_image_source(source)
+      return source unless chats_active_storage_source?(source)
+
+      routes = chats_main_routes
+
+      if source.respond_to?(:variation) && source.respond_to?(:blob)
+        routes.rails_representation_url(source, only_path: true)
+      elsif source.respond_to?(:blob)
+        routes.rails_blob_url(source.blob, only_path: true)
+      elsif source.respond_to?(:signed_id) && source.respond_to?(:filename)
+        routes.rails_blob_url(source, only_path: true)
+      else
+        source
+      end
+    end
+
+    def chats_active_storage_source?(source)
+      defined?(ActiveStorage) && source.class.name.start_with?("ActiveStorage::")
+    end
+
+    def chats_main_routes
+      respond_to?(:main_app) ? main_app : Rails.application.routes.url_helpers
+    end
+  end
+end
+
+# Expose the helpers to the HOST app's views (isolated engines don't share
+# helpers automatically). The hook lives HERE, at the bottom of the file that
+# defines the constant — not in an engine initializer — so it's
+# self-resolving: whenever this file loads (eager load, autoload on first
+# use, or the engine's to_prepare touch), the constant already exists by the
+# time the hook can possibly run. Registering it from an initializer instead
+# would blow up at boot in hosts where ActionView is already loaded during
+# initializers (web-console does this) because `include Chats::EngineHelper`
+# would fire before the autoloader is ready. Same pattern as the moderate
+# gem's report_link helper.
+if defined?(ActiveSupport)
+  ActiveSupport.on_load(:action_view) do
+    include Chats::EngineHelper
+  end
+end