moderate 1.0.0.beta2 → 1.0.0

data/lib/moderate/models/concerns/content_filterable.rb

@@ -36,13 +36,68 @@ module Moderate
   # ACTIVE STORAGE ATTACHMENTS work out of the box: `moderates :avatar, with:
   # :your_image_adapter, mode: :flag` on a `has_one_attached :avatar` model needs
   # no extra wiring. AR dirty tracking can't see attachment writes — and Active
-  # Storage clears `attachment_changes` before after_commit — so the concern
+  # Storage drops `attachment_changes` in its own after_commit — so the concern
   # snapshots "these filtered attachments changed" in a before_save and consumes
   # the snapshot at commit time. The overridable seam below still exists for
   # richer cases (derived values, non-AS blobs).
+  #
+  # An attachment is classified only once its file is on the storage service, and
+  # it is classified even when the upload fails. Active Storage uploads a newly
+  # attached file in ITS after_commit (in whichever order the two after_commits were
+  # declared), so the concern hooks that upload itself, from before_save:
+  #
+  #   1. just before the upload starts, a ClassifyJob is enqueued UPLOAD_WAIT seconds
+  #      out: the durable intent. If the upload raises, or the process dies, that job
+  #      still runs, waits (bounded) for the file, and classifies it or audits
+  #      `classification_skipped`;
+  #   2. once the upload returns, the field is classified right away when its files
+  #      are on the service: inline for a synchronous adapter, by an immediate
+  #      ClassifyJob for an async one. A direct upload (an attached blob or signed
+  #      id, whose `upload` is a no-op) may not be there yet; then the job from step
+  #      1 takes it.
+  #
+  # Whichever classifies first claims the files (a moderate_classifications row,
+  # Moderate::Attachments), calls the adapter outside any lock and records the
+  # result; the rest find the claim or the record and stop, so a field is classified
+  # once per set of files. An adapter that raises leaves its claim until
+  # `config.classification_claim_ttl` runs out and schedules no retry itself: the
+  # guard job, a job's recheck at the claim's expiry, or a new save takes it over.
   module ContentFilterable
     extend ActiveSupport::Concern
 
+    # Extended onto one pending Active Storage attachment change (the object
+    # `has_one_attached` / `has_many_attached` upload from their after_commit), so
+    # the record hears just before and just after that change uploads its files.
+    # Per object, never a global patch. A failure of ours never breaks the upload.
+    module AfterUpload
+      def upload(...)
+        moderate_notify(:moderate_upload_starting)
+        result = super
+        moderate_notify(:moderate_upload_finished)
+        result
+      end
+
+      def moderate_watch(record, field)
+        (@moderate_watchers ||= {})[field.to_s] = record
+      end
+
+      private
+
+      def moderate_notify(event)
+        Array(@moderate_watchers).each do |field, record|
+          record.send(event, field)
+        rescue StandardError => error
+          Moderate.audit(
+            :classification_skipped,
+            subject: record,
+            payload: { field: field, reason: "filter_error", error_class: error.class.name,
+                       summary: "#{record.class.name}##{field}: #{event} raised #{error.class}" }
+          )
+        end
+      end
+    end
+    private_constant :AfterUpload
+
     included do
       # The set of filtered field names (Strings), inherited via class_attribute so
       # STI subclasses keep their parent's filtered fields. Accumulates across
@@ -73,6 +128,10 @@ module Moderate
 
     # :block enforcement — a validation. We deliberately skip :flag fields here
     # (their work happens after_commit) and blank values (nothing to classify).
+    #
+    # `:block` lets nothing in unverified: an attachment that points at a stored blob
+    # whose file isn't on the service (a direct upload that hasn't finished) fails
+    # with `:upload_not_finished` instead of being classified without its file.
     def moderate_blocked_fields_must_be_allowed
       moderation_filtered_fields.each do |field|
         policy = Moderate.filter_policy_for(self, field)
@@ -80,6 +139,7 @@ module Moderate
 
         value = moderation_field_value(field)
         next if moderation_value_blank?(value)
+        next errors.add(field, :upload_not_finished) if Moderate::Attachments.upload_unfinished?(value)
 
         result = Moderate.classify(value, policy: policy)
         errors.add(field, :objectionable_content) if result.flagged?
@@ -90,59 +150,117 @@ module Moderate
     # (inline for synchronous adapters; via Moderate::ClassifyJob for async ones).
     #
     # We only act when the field actually CHANGED on this commit (re-saving an
-    # untouched record must not re-flag it and spam the queue), and we wrap each
-    # field in `begin/ensure` so the clean-up hook (`moderation_field_committed`)
-    # always runs even if classification raises — that hook is what clears the
-    # one-shot attachment snapshot.
+    # untouched record must not re-flag it and spam the queue). A field whose upload
+    # the concern is watching is left to that upload's hooks (see AfterUpload).
     def moderate_flag_filtered_fields
       moderation_filtered_fields.each do |field|
+        next if @moderate_watched_uploads&.include?(field)
+
         policy = Moderate.filter_policy_for(self, field)
         next unless policy.flag?
         next unless moderation_field_changed_for_commit?(field)
 
-        begin
-          # ASYNC adapters (remote moderation APIs) never classify inline —
-          # a network call in the request's after_commit would stall the
-          # response for as long as the provider takes. ClassifyJob re-reads
-          # the value at run time (so it always classifies what's actually
-          # persisted) and files the Flag through the same Flag.flag! builder.
-          if Moderate.config.adapter_async?(policy.adapter)
-            Moderate::ClassifyJob.perform_later(self, field)
-            next
-          end
-
-          value = moderation_field_value(field)
-          next if moderation_value_blank?(value)
-
-          result = Moderate.classify(value, policy: policy)
-          next unless result.flagged?
-
-          Moderate::Flag.flag!(
-            flaggable: self,
-            field: field,
-            # `reported_owner` comes from Moderate::Reportable. A filterable model
-            # is usually also reportable; if it isn't, the owner is simply nil
-            # (the flag still lands in the queue, just unattributed).
-            owner: (reported_owner if respond_to?(:reported_owner)),
-            source: result.source,
-            mode: policy.mode,
-            # Cap the stored excerpt so we never balloon a row with a huge body;
-            # 500 chars is plenty of context for a reviewer.
-            excerpt: value.to_s.truncate(500),
-            categories: result.categories,
-            scores: result.scores,
-            # Keep the policy that produced the flag alongside the adapter's raw
-            # payload, so the queue can show "flagged by <adapter> under
-            # <Class>#<field>" and an auditor can inspect the untouched response.
-            context: {
-              raw: result.raw,
-              policy: { class_name: policy.class_name, field: policy.field, mode: policy.mode.to_s }
-            }
-          )
-        ensure
-          moderation_field_committed(field)
-        end
+        moderate_flag_field(field, policy)
+      end
+    end
+
+    # Just before Active Storage uploads `field`'s files: enqueue the job that
+    # classifies them even if this upload fails (see the module comment).
+    def moderate_upload_starting(field)
+      policy = Moderate.filter_policy_for(self, field)
+      return unless policy.flag? && moderation_field_changed_for_commit?(field)
+
+      (@moderate_guarded_uploads ||= Set.new) << field
+      Moderate::ClassifyJob.set(wait: Moderate::ClassifyJob::UPLOAD_WAIT)
+        .perform_later(self, field, blob_ids: Moderate::Attachments.blob_ids(moderation_field_value(field)))
+    end
+
+    # The upload returned: classify now if the files are there (the guard job takes
+    # them otherwise).
+    def moderate_upload_finished(field)
+      @moderate_watched_uploads&.delete(field)
+      return moderation_field_committed(field) unless @moderate_guarded_uploads&.delete?(field)
+
+      moderate_flag_field(field, Moderate.filter_policy_for(self, field), guarded: true)
+    end
+
+    # Classify one changed field and file its Flag. Wrapped in `ensure` so the
+    # clean-up hook (`moderation_field_committed`) always runs even if
+    # classification raises — that hook is what clears the one-shot attachment
+    # snapshot.
+    #
+    # An attachment whose files aren't all on the service yet is never classified
+    # here: the after-upload guard job takes it (`guarded:`), or a ClassifyJob that
+    # waits for it is enqueued now.
+    def moderate_flag_field(field, policy, guarded: false)
+      value = moderation_field_value(field)
+      attachment = Moderate::Attachments.attachment?(value)
+      return if attachment && moderation_value_blank?(value)
+
+      if attachment && !Moderate::Attachments.uploaded?(value)
+        Moderate::ClassifyJob.perform_later(self, field, blob_ids: Moderate::Attachments.blob_ids(value)) unless guarded
+        return
       end
+
+      # ASYNC adapters (remote moderation APIs) never classify inline — a network
+      # call in the request's after_commit would stall the response for as long
+      # as the provider takes. ClassifyJob re-reads the value at run time (so it
+      # always classifies what's actually persisted) and files the Flag through the
+      # same Flag.flag! builder.
+      if Moderate.config.adapter_async?(policy.adapter)
+        blob_ids = (Moderate::Attachments.blob_ids(value) if attachment)
+        Moderate::ClassifyJob.perform_later(self, field, blob_ids: blob_ids)
+        return
+      end
+
+      return if moderation_value_blank?(value)
+      return moderate_classify_attachment(field, policy) if attachment
+
+      result = Moderate.classify(value, policy: policy)
+      return unless result.flagged?
+
+      moderate_file_flag(field, policy, value, result)
+    ensure
+      moderation_field_committed(field)
+    end
+
+    # Claim, classify outside any lock, complete (Moderate::Attachments): the guard
+    # job and this path never both classify the same files, and a slow adapter never
+    # holds this record's row.
+    def moderate_classify_attachment(field, policy)
+      Moderate::Attachments.classify_once(
+        self, field,
+        owner: SecureRandom.uuid,
+        read: -> { self.class.unscoped.find_by(id: id)&.send(:moderation_field_value, field) },
+        classify: ->(value) { Moderate.classify(value, policy: policy) },
+        file: ->(value, result) { moderate_file_flag(field, policy, value, result) }
+      )
+    end
+
+    def moderate_file_flag(field, policy, value, result)
+      Moderate::Flag.flag!(
+        flaggable: self,
+        field: field,
+        # `reported_owner` comes from Moderate::Reportable. A filterable model is
+        # usually also reportable; if it isn't — or its owner isn't a person
+        # (Moderate.responsible_user) — the owner is simply nil (the flag still
+        # lands in the queue, just unattributed).
+        owner: Moderate.responsible_user(self),
+        source: result.source,
+        mode: policy.mode,
+        # Cap the stored excerpt so we never balloon a row with a huge body; 500
+        # chars is plenty of context for a reviewer.
+        excerpt: value.to_s.truncate(500),
+        categories: result.categories,
+        scores: result.scores,
+        # Keep the policy that produced the flag alongside the adapter's raw
+        # payload, so the queue can show "flagged by <adapter> under
+        # <Class>#<field>" and an auditor can inspect the untouched response.
+        context: {
+          raw: result.raw,
+          policy: { class_name: policy.class_name, field: policy.field, mode: policy.mode.to_s }
+        }
+      )
     end
 
     # --- Overridable field seam -----------------------------------------------
@@ -162,8 +280,8 @@ module Moderate
 
     # Did `field` change on the just-committed save? Defaults, in order:
     #   1. the attachment snapshot taken in before_save (AR dirty tracking can't
-    #      see attachment writes, and Active Storage clears `attachment_changes`
-    #      before after_commit — hence the one-shot snapshot),
+    #      see attachment writes, and Active Storage drops `attachment_changes`
+    #      in its own after_commit — hence the one-shot snapshot),
     #   2. ActiveRecord's own dirty tracking (`saved_change_to_attribute?`),
     #   3. `true` for a PORO/ActiveModel object with no dirty tracking at all —
     #      the conservative assumption.
@@ -188,18 +306,26 @@ module Moderate
       nil
     end
 
-    # before_save: record which FILTERED fields have a pending attachment write
-    # on this save. `attachment_changes` only exists on Active Storage models —
-    # plain models skip straight through.
+    # before_save: record which FILTERED fields have a pending attachment write on
+    # this save, and watch the upload of each (AfterUpload). `attachment_changes`
+    # only exists on Active Storage models — plain models skip straight through. A
+    # removal (`avatar = nil`) is a change with nothing to upload, so nothing to watch.
     def moderate_snapshot_attachment_changes
-      return true unless respond_to?(:attachment_changes)
+      return unless respond_to?(:attachment_changes)
 
+      @moderate_watched_uploads = Set.new
       moderation_filtered_fields.each do |field|
-        next unless attachment_changes.key?(field)
+        change = attachment_changes[field]
+        next if change.nil?
 
         (@moderate_changed_attachment_fields ||= Set.new) << field
+        next unless change.respond_to?(:upload)
+
+        change.extend(AfterUpload) unless change.is_a?(AfterUpload)
+        change.moderate_watch(self, field)
+        @moderate_watched_uploads << field
       end
-      true # never halt the save chain
+      nil # a callback's return value never halts the save (only `throw :abort` does)
     end
 
     # Blank check that can see through an `ActiveStorage::Attached` proxy — an

data/lib/moderate/models/concerns/deferred_notices.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Moderate
+  # Notices that must not reach anyone before the change they announce is durable.
+  #
+  # A service changes a record inside a transaction, then queues what to send with
+  # `record.after_commit_notice { … }`. The TRANSACTION owns the notice, exactly as it
+  # owns a record's after_commit callbacks: the notice is wrapped in an Envelope and
+  # enrolled in the current transaction (`connection.add_transaction_record`, the same
+  # call Active Record makes for a saved record, on every supported Rails), and
+  # the transaction finalizes it — sends it on commit, drops it on rollback or when an
+  # exception ends the transaction. Nothing lives on a Ruby instance or on the thread,
+  # so it doesn't matter which instance of a row was saved, whether the row was saved
+  # at all, or which thread runs next.
+  #
+  # Notices follow Active Record's after_commit rules, exactly:
+  #   - with no transaction open, the notice is sent at once;
+  #   - the notice joins the transaction of the connection it is queued ON. Queue it
+  #     inside the transaction that saved the record, on that transaction's connection:
+  #     `after_commit_notice(on: connection)`, where `on:` defaults to the record
+  #     class's connection at call time. The gem's services capture their model's
+  #     connection at the top of the transaction, before any save, and pass it to every
+  #     notice they queue, so a host callback that switches databases or shards
+  #     mid-save can't move them. A host that calls after_commit_notice itself passes
+  #     `on:` when it uses `connected_to`;
+  #   - in nested transactions that join their parent, and in savepoints
+  #     (`requires_new: true`) under a joinable parent, it moves up and is sent at the
+  #     OUTERMOST commit; a rolled-back savepoint drops only its own notices;
+  #   - under a parent that is not joinable (`transaction(joinable: false)`, and the
+  #     wrapper Rails' transactional tests run each test in), it is sent when the
+  #     savepoint is released — when after_commit runs too.
+  module DeferredNotices
+    # A queued notice, in the shape a transaction finalizes: Active Record calls
+    # `before_committed!`, then `committed!` or `rolledback!` on every record enrolled
+    # in it (and reads `trigger_transactional_callbacks?`, `destroyed?`,
+    # `_new_record_before_last_commit` when choosing which instance runs callbacks).
+    #
+    # @api private
+    class Envelope
+      attr_accessor :_new_record_before_last_commit
+
+      def initialize(notice)
+        @notice = notice
+        @finalized = false
+      end
+
+      def trigger_transactional_callbacks? = true
+      def has_transactional_callbacks? = true # rubocop:disable Naming/PredicatePrefix -- Active Record's name
+      def destroyed? = false
+      def before_committed!; end
+
+      # Sent once, when the transaction that owns the envelope runs commit callbacks.
+      # (Active Record also calls this with should_run_callbacks: false when it is only
+      # cleaning up after an exception: nothing is sent then.)
+      def committed!(should_run_callbacks: true)
+        return if @finalized
+
+        @finalized = true
+        @notice.call if should_run_callbacks
+      end
+
+      def rolledback!(force_restore_state: false, should_run_callbacks: true) # rubocop:disable Lint/UnusedMethodArgument
+        @finalized = true
+      end
+    end
+
+    # Enroll `notice` in `connection`'s current transaction, or send it now when there
+    # is no connection or it has no transaction open.
+    #
+    # @api private: call `record.after_commit_notice { … }`.
+    def self.defer(connection, &notice)
+      return notice.call unless connection&.current_transaction&.open?
+
+      connection.add_transaction_record(Envelope.new(notice))
+      nil
+    end
+
+    # The connection a service captures at the top of its transaction, before any save.
+    #
+    # @api private
+    def self.connection_for(model)
+      model.lease_connection
+    end
+
+    def after_commit_notice(on: DeferredNotices.connection_for(self.class), &notice)
+      DeferredNotices.defer(on, &notice)
+      self
+    end
+  end
+end

data/lib/moderate/models/concerns/reportable.rb

@@ -9,7 +9,8 @@ module Moderate
   # `Moderate::Report#reportable` association. This concern answers the
   # Trust & Safety questions that polymorphism *can't*:
   #
-  #   - which fields of the record may be reported (`reportable_fields`)
+  #   - which fields of the record may be reported (`reportable_fields`), and
+  #     what humans should call each one (`labels:` / `reportable_field_label`)
   #   - who is *responsible* for the content (`reported_owner`) — the person a
   #     decision's statement of reasons must reach (DSA Art. 17) and who a ban
   #     would apply to
@@ -56,6 +57,15 @@ module Moderate
       # Empty default = "the whole record is reportable, no specific field."
       class_attribute :moderation_reportable_fields, instance_writer: false, default: [].freeze
 
+      # The human labels declared next to the fields (`labels: { body: "Chat
+      # message" }`), keyed by field name String. Values are Strings or callables
+      # (evaluated at read time, so a lambda can call I18n under the CURRENT
+      # locale). Same `class_attribute` reasoning as the field list above: it
+      # inherits down an STI tree and a subclass redeclaration doesn't mutate the
+      # parent. Read through `Moderate.reportable_field_label`, never directly —
+      # that's where the i18n and humanize fallbacks live.
+      class_attribute :moderation_reportable_field_labels, instance_writer: false, default: {}.freeze
+
       # Self-register in the gem's reportable registry the moment the concern is
       # included, so `Moderate.reportable_classes` is auto-discovered with NO
       # manual list to maintain (README: "Reportable classes are auto-discovered
@@ -73,10 +83,54 @@ module Moderate
       #
       #   reportable_fields :title, :description   # writer
       #   reportable_fields                         # => ["title", "description"]
-      def reportable_fields(*fields)
-        self.moderation_reportable_fields = fields.map(&:to_s).freeze if fields.any?
+      #
+      # `labels:` names each field for humans — what the moderation queue, the
+      # statement of reasons, and the appeal page print instead of the raw column
+      # name (a moderator reading «Body» on a chat-message report has to guess
+      # what was reported). Optional and per field; anything unlabeled falls back
+      # to i18n, then to `field.humanize` (see `Moderate.reportable_field_label`).
+      #
+      #   reportable_fields :body, :files, labels: { body: "Chat message", files: "Chat photo" }
+      #
+      # Labels follow the same "last declaration wins" rule as the fields, and a
+      # label for a field you didn't declare raises — a typo'd key would otherwise
+      # silently never show up.
+      def reportable_fields(*fields, labels: nil)
+        if labels && fields.empty?
+          raise ArgumentError, "#{name}: `labels:` needs the fields it labels — " \
+            "declare them together, e.g. `reportable_fields :body, labels: { body: \"Message\" }`"
+        end
+
+        if fields.any?
+          field_names = fields.map(&:to_s).freeze
+          self.moderation_reportable_fields = field_names
+          self.moderation_reportable_field_labels = normalize_reportable_field_labels(labels, field_names)
+        end
+
         moderation_reportable_fields
       end
+
+      # The human label for one of this class's reported fields. Class-level sugar
+      # for `Moderate.reportable_field_label(self, field)`.
+      def reportable_field_label(field)
+        Moderate.reportable_field_label(self, field)
+      end
+
+      private
+
+      def normalize_reportable_field_labels(labels, field_names)
+        return {}.freeze if labels.blank?
+        raise ArgumentError, "#{name}: `labels:` must be a Hash of field => label" unless labels.respond_to?(:to_h)
+
+        normalized = labels.to_h.transform_keys(&:to_s)
+        unknown = normalized.keys - field_names
+        if unknown.any?
+          raise ArgumentError, "#{name}: `labels:` names #{unknown.map(&:inspect).join(", ")}, " \
+            "not among the reportable fields #{field_names.inspect}"
+        end
+
+        normalized.freeze
+      end
     end
 
     # Is `field` one a reporter is allowed to name? Two cases:
@@ -100,6 +154,13 @@ module Moderate
       self.class.reportable_fields.include?(field_s)
     end
 
+    # The human label for `field` on this record ("Chat message", not "Body"), or
+    # nil for a blank field (a whole-record report has no field to name). Sugar
+    # for `Moderate.reportable_field_label(self, field)`.
+    def reportable_field_label(field)
+      Moderate.reportable_field_label(self, field)
+    end
+
     # WHO is responsible for this content — the account a decision's statement of
     # reasons reaches (DSA Art. 17) and the user a ban would apply to.
     #
@@ -179,6 +240,25 @@ module Moderate
       true
     end
 
+    # The generic content bucket this record is (Report::CONTENT_TYPES: "message",
+    # "listing", "user_profile", …), stored on reports filed against it so the queue
+    # and the transparency counts can group by kind. nil (the default) leaves the
+    # report's content_type empty; a value outside CONTENT_TYPES is stored as "other".
+    def moderation_content_type(_field = nil)
+      nil
+    end
+
+    # The signed, purpose-scoped token that names this record in a report link
+    # (`/reports/new?target=…`), resolved back by Report.locate_signed_reportable.
+    # NON-expiring on purpose: it identifies which record to report and grants no
+    # capability, and an expiring token changes on every render, which defeats the
+    # fragment caching of anything that shows a report link (a chat bubble rendered
+    # once per broadcast, for every viewer). Prefer the view helper
+    # `moderate_report_target_path(record, field:)` to building URLs by hand.
+    def to_moderation_sgid
+      to_sgid_param(for: Moderate::Report::SIGNED_GLOBAL_ID_PURPOSE, expires_in: nil)
+    end
+
     # Open reports filed against this record, optionally narrowed to one field.
     # Hosts can use this when they need the actual relation (queue previews,
     # counters, "already reported" affordances) instead of just a boolean.
@@ -264,7 +344,7 @@ module Moderate
       return false if owner.nil?
 
       if owner.respond_to?(:id) && viewer.respond_to?(:id)
-        owner.id == viewer.id && owner.class == viewer.class
+        owner.id == viewer.id && owner.instance_of?(viewer.class)
       else
         owner == viewer
       end