moderate 1.0.0.beta1 → 1.0.0

data/lib/moderate/services/resolve_report.rb

@@ -32,14 +32,33 @@ module Moderate
     #      means disclosure, appeal path). Different people, different rights — see
     #      docs/notifications.md ("Why two decision events").
     class ResolveReport
-      def initialize(report, by:)
+      # The decision notices are queued on the report and sent when the outermost
+      # transaction commits (Moderate::DeferredNotices). `deliver: false` leaves them
+      # to a caller that queues them on a record of its own (ResolveFlag, on the flag),
+      # via `#deliver_decision_notices`.
+      #
+      # `conduct_since:` is when the conduct this decision answers was first raised —
+      # the report's own creation by default; ResolveFlag passes the flag's. A ban
+      # decided on the same person since then already answered it (see
+      # #ban_reported_user!).
+      def initialize(report, by:, deliver: true, conduct_since: nil)
         @report = report
         @moderator = by
+        @deliver = deliver
+        @conduct_since = conduct_since
       end
 
+      # The report being decided.
+      attr_reader :report
+
       # Resolve WITH action (the report was valid; we acted on the content/account).
       # `resolution_basis` records the legal/contractual ground bucket; it's
       # validated against the migration's check-constraint list by the model.
+      #
+      # A resolve restricts something: `remove_content:`, `ban_user:`, or both. One with
+      # neither is refused (RecordInvalid): recording it would tell the affected person a
+      # restriction was imposed when none was. A decision that restricts nothing is a
+      # `dismiss!`, whose statement says so.
       def resolve!(note:, remove_content: false, ban_user: false, resolution_basis: "terms")
         note = require_note!(note)
         actions = {
@@ -47,10 +66,16 @@ module Moderate
           ban_user: truthy?(ban_user),
           resolution_basis: resolution_basis.to_s.strip.presence || "terms"
         }
+        require_action!(actions)
+
+        # A ban nothing would apply is refused before anything changes (see
+        # Moderate.ensure_ban_handler!): never "account suspended" for a suspension
+        # that didn't happen.
+        Moderate.ensure_ban_handler! if actions[:ban_user] && report.reported_user.present?
 
         transition!("actioned", note: note, actions: actions) do
-          remove_reported_content! if actions[:remove_content]
-          ban_reported_user!(note: note) if actions[:ban_user]
+          remove_reported_content!(note: note, actions: actions) if actions[:remove_content]
+          ban_reported_user!(note: note, actions: actions) if actions[:ban_user]
         end
       end
 
@@ -62,16 +87,44 @@ module Moderate
         transition!("dismissed", note: note, actions: { resolution_basis: "no_violation" })
       end
 
+      # The two decision events (see the class doc, point 4). Sent by `resolve!` /
+      # `dismiss!` themselves unless this service was built with `deliver: false`.
+      def deliver_decision_notices
+        notify_user_banned
+        notify_reporter
+        notify_affected_user
+        notify_content_removed
+      end
+
       private
 
-      attr_reader :report, :moderator
+      attr_reader :moderator
 
       # The atomic core. Everything that mutates state happens under the row lock;
       # the (slow, fallible) notifications happen AFTER the lock is released, so a
       # broken mailer can't hold a database lock or roll back the decision.
-      def transition!(status, note:, actions:)
+      def transition!(status, note:, actions:, &enforcement)
+        # The report's connection, captured before anything is saved: every notice of
+        # this decision joins ITS transaction, whatever a host callback switches to.
+        @connection = Moderate::DeferredNotices.connection_for(report.class)
+
+        # One lock order everywhere: content, then (for a ban) the person, then the
+        # report — the order a flag escalation takes too, so they never deadlock. The
+        # person's lock serializes two bans of one account from different content.
+        Moderate.with_row_lock(report.reportable) do
+          Moderate.with_row_lock(actions[:ban_user] ? report.reported_user : nil) do
+            lock_and_transition!(status, note: note, actions: actions, &enforcement)
+          end
+        end
+
+        report
+      end
+
+      def lock_and_transition!(status, note:, actions:)
         report.with_lock do
-          report.reload
+          # `with_lock` already re-read the row under the lock (SELECT … FOR UPDATE):
+          # no plain reload here — under MySQL's REPEATABLE READ a plain read pins the
+          # transaction's snapshot, and every later check must see what committed.
 
           # Re-check inside the lock — see class doc point (1). A closed report is a
           # no-op error, never a silent re-apply of enforcement.
@@ -100,57 +153,235 @@ module Moderate
           )
 
           audit_decision(status, actions, note)
-        end
 
-        deliver_decision_notices
-        report
+          # Sent when the outermost transaction commits, never on a rollback.
+          report.after_commit_notice(on: @connection) { deliver_decision_notices } if @deliver
+        end
       end
 
       # --- Enforcement (host contracts only) ----------------------------------
 
-      def remove_reported_content!
-        return if report.reportable.blank?
-        return unless report.reportable.respond_to?(:remove_reported_field!)
+      # The reportable's own removal (`remove_reported_field!`). When it says it
+      # removed something, the removal is audited here, inside the decision's
+      # transaction, and announced as `content_removed` with the decision notices.
+      def remove_reported_content!(note:, actions:)
+        # Already removed by an earlier decision on the same content and field: close
+        # against it (like a flag does), the reporter told it's gone, nothing removed
+        # or announced a second time.
+        if (prior = covering_removal)
+          actions[:content_already_removed_by] = prior.id
+          return true
+        end
+
+        # Nothing to remove from (the content was deleted, its report nullified) or
+        # no way to remove it: refused like a removal that removed nothing.
+        removable = report.reportable.present? && report.reportable.respond_to?(:remove_reported_field!)
+        removed_text = text_about_to_be_removed if removable
+        removed = removable && report.reportable.remove_reported_field!(report.reported_field)
+        # Verified, not taken on trust: the host said it removed something, so the field
+        # must read as gone now (re-read under the same lock). A host method that rewrote
+        # the field instead removed nothing: refused, nobody stamped, no digest recorded.
+        refuse_unremoved! unless removed && content_gone?
+
+        actions[:removed_text_digest] = text_digest(removed_text) if removed_text.present?
+        @content_removed = content_removed_payload(note)
+        stamp_covered_reports!(removed_text)
+        Moderate.audit(:content_removed, **content_removed_event)
+        true
+      end
+
+      def covered_note
+        prior = report.resolution_actions.to_h["content_already_removed_by"]
+        prior ? " (already removed by the decision on Report ##{prior})" : ""
+      end
+
+      # The decision that removed this report's content while this report was pending:
+      # the one that stamped it (covered_by_report_id, see #stamp_covered_reports!),
+      # provided it did remove the content, it still stands (no appeal against it was
+      # upheld: an overturned removal covers nothing, whatever the stamp says), and the
+      # content is gone now (read fresh, under the content's lock). No clocks are
+      # compared: a report that wasn't pending when the content was removed (a repost,
+      # a removal that didn't take, a late report) was never stamped.
+      def covering_removal
+        prior_id = report.covered_by_report_id
+        return if prior_id.blank? || !content_gone?
+
+        # Locking reads (see Moderate.with_row_lock), like every "already done" check.
+        prior = Moderate::Report.actioned.lock.find_by(id: prior_id)
+        return unless prior && truthy?(prior.resolution_actions.to_h["remove_content"])
+        return if Moderate::Appeal.upheld.where(report_id: prior.id).lock.exists?
+
+        prior
+      end
+
+      # The field's text right before this decision removes it, read under the
+      # content's lock with a locking read: what is actually being removed, which may
+      # differ from what this report saw at intake. nil when the content exposes no
+      # text (no moderation_snapshot) or reads blank.
+      def text_about_to_be_removed
+        content = report.reportable.reload(lock: true)
+        return unless content.respond_to?(:moderation_snapshot)
+
+        content.moderation_snapshot(report.reported_field).presence
+      rescue ActiveRecord::RecordNotFound
+        nil
+      end
+
+      def text_digest(text)
+        Digest::SHA256.hexdigest(text.to_s)
+      end
+
+      # Just removed this report's content, under its lock: stamp the OTHER reports
+      # pending on the same content and field whose intake snapshot holds the text that
+      # was ACTUALLY removed (`removed_text`, read right before the removal, not this
+      # report's own intake text), so each can later be closed as "already removed by"
+      # this decision. Nobody is stamped when that text is blank or unreadable. A report
+      # filed concurrently either committed before this read (then its snapshot is the
+      # text it saw: the removed text if it saw the content we removed) or after it
+      # (then it isn't stamped, and a removal on it is refused): never a false cover.
+      def stamp_covered_reports!(text)
+        return if text.blank? || report.reportable_type.blank? || report.reportable_id.blank?
+
+        pending = Moderate::Report.open
+          .where(reportable_type: report.reportable_type, reportable_id: report.reportable_id)
+          .where(reported_field: report.reported_field, covered_by_report_id: nil)
+          .where.not(id: report.id).lock
+        ids = pending.select { |other| other.snapshot.to_h.with_indifferent_access[:content_text] == text }.map(&:id)
+        Moderate::Report.where(id: ids).update_all(covered_by_report_id: report.id) if ids.any?
+      end
+
+      # Is the reported field's content gone, read fresh with a locking read? The
+      # record deleted, the record saying it is (`deleted?`, a soft-delete tombstone),
+      # or the field reading as empty through BOTH the snapshot accessor (what a report
+      # captures) and the field itself (an attachment, a non-text field).
+      def content_gone?
+        content = report.reportable&.reload(lock: true)
+        return true if content.nil?
+        return true if content.respond_to?(:deleted?) && content.deleted?
+
+        field = report.reported_field
+        return false if field.blank?
+        return false if content.respond_to?(:moderation_snapshot) && content.moderation_snapshot(field).present?
+
+        value = content.respond_to?(:moderation_field_value, true) ? content.send(:moderation_field_value, field) : content.try(field)
+        value.respond_to?(:attached?) ? !value.attached? : value.blank?
+      rescue ActiveRecord::RecordNotFound
+        true
+      end
+
+      # "Remove the content" was asked and the reportable removed nothing (the field
+      # isn't removable, or it's already gone). Recording the decision anyway would
+      # tell the affected person "content removed" for content that's still there, so
+      # the whole decision is refused (and rolled back, a ban with it).
+      def refuse_unremoved!
+        message = I18n.t(
+          "moderate.errors.nothing_removed",
+          content: report.reportable_label,
+          default: "Nothing was removed: #{report.reportable_label} has nothing removable there (already " \
+                   "removed, deleted, or not removable). Resolve without removing content, or dismiss."
+        )
+        report.errors.add(:base, message)
+        raise ActiveRecord::RecordInvalid, report
+      end
+
+      def content_removed_payload(note)
+        {
+          report_id: report.id,
+          reportable_type: report.reportable_type,
+          reportable_id: report.reportable_id,
+          reported_field: report.reported_field,
+          reported_field_label: report.reported_field_label,
+          reason: note,
+          summary: ["Content removed: #{report.reportable_label}", report.reported_field_label].compact.join(" · ")
+        }.compact
+      end
 
-        report.reportable.remove_reported_field!(report.reported_field)
+      def content_removed_event
+        { subject: report, actor: moderator, recipients: [report.reported_user].compact, payload: @content_removed }
       end
 
-      def ban_reported_user!(note:)
-        user = report.reported_user
+      # The gem never bans directly — it asks the host's ban_handler what "banned"
+      # means (suspend, soft-delete, flip a flag…). ONE ban per person per episode: if
+      # a decision on this same person, on any content or field, already banned them
+      # since this conduct was raised, the account is suspended already — this decision
+      # records which one (`ban_already_applied_by`) instead of banning twice, unless
+      # your `config.banned` says the account isn't banned any more (unbanned in your
+      # app since), in which case the ban_handler runs again. (An older ban, before
+      # this conduct, doesn't count: the person may have been unbanned since, and new
+      # conduct deserves its own decision.)
+      def ban_reported_user!(note:, actions:)
+        # The person, read again with a locking read now that we hold their lock: a
+        # concurrent decision that banned them while we waited has committed, and
+        # `config.banned` and the ban_handler must see THAT state, not the copy loaded
+        # before the wait.
+        user = locked_person
         return if user.blank?
 
-        # The gem never bans directly — it asks the host's ban_handler what "banned"
-        # means (suspend, soft-delete, flip a flag…). No-op by default, so the
-        # decision still completes and audits even if no ban is wired.
-        Moderate.apply_ban(user: user, by: moderator, reason: note)
+        if (prior = prior_ban_decision(user)) && still_banned?(user)
+          actions[:ban_already_applied_by] = prior.id
+          return
+        end
+
+        @user_banned = Moderate.apply_ban(user: user, by: moderator, reason: note, announce: false)
+      end
+
+      def locked_person
+        person = report.reported_user
+        person && person.class.unscoped.lock.find_by(person.class.primary_key => person.id)
+      end
+
+      # An earlier ban of this episode covers this one only while the account is still
+      # banned. The host knows that (`config.banned`); without it, the earlier ban counts.
+      def still_banned?(user)
+        check = Moderate.config.banned
+        check.nil? || check.call(user) ? true : false
+      end
+
+      def prior_ban_decision(user)
+        since = @conduct_since || report.created_at
+        decided = Moderate::Report.actioned.where(reported_user_id: user.id, resolved_at: since..)
+          .where.not(id: report.id)
+        # A locking read: a ban committed by a concurrent decision while we waited for
+        # the person's lock is seen, whatever the isolation level.
+        decided.recent_first.lock.find { |prior| truthy?(prior.resolution_actions.to_h["ban_user"]) }
       end
 
       # --- Notifications (after the lock) -------------------------------------
 
-      def deliver_decision_notices
-        notify_reporter
-        notify_affected_user
+      # user_banned → the banned person (Moderate.apply_ban, announced here so it waits
+      # for the commit like the rest).
+      def notify_user_banned
+        return unless @user_banned
+
+        Moderate.announce_ban(**@user_banned)
+      end
+
+      # content_removed → the person whose content it was (when there is one) and the
+      # host's admin channels. Only when the removal actually removed something.
+      def notify_content_removed
+        return unless @content_removed
+
+        Moderate.notify(:content_removed, **content_removed_event)
       end
 
       # report_decision → the reporter (Art. 16(5): inform the notice provider of the
-      # decision + redress). We stamp `decision_notified_at` ONLY when the hook
-      # reported a delivery — that timestamp is the record that the legal
-      # communication actually went out, so it must reflect reality, not intent.
-      # `Moderate.notify` returns the delivered boolean precisely for this gate.
+      # decision + redress). `decision_notified_at` is stamped only when the host's
+      # notifier confirms the message actually went out (Moderate.delivered!): a
+      # queued mail is not a delivered one, and the timestamp starts the appeal
+      # window (Art. 20(2)).
       def notify_reporter
         return if report.notifier_email.blank?
 
-        delivered = Moderate.notify(
+        Moderate.notify(
           :report_decision,
           subject: report,
           actor: moderator,
           recipients: [report.reporter].compact,
           payload: decision_payload.merge(
-            summary: "Decision on Report ##{report.id}: #{report.status}"
+            summary: "Decision on Report ##{report.id}: #{report.status}" \
+                     "#{covered_note}"
           )
         )
-
-        report.update_column(:decision_notified_at, Time.now) if delivered
       end
 
       # affected_user_decision → the content owner: the DSA Art. 17 statement of
@@ -160,11 +391,16 @@ module Moderate
       def notify_affected_user
         return unless report.actioned?
 
+        # Its removal was already announced by the decision that made it; a second
+        # statement only when this one also bans.
+        actions = report.resolution_actions.to_h
+        return if actions["content_already_removed_by"] && !truthy?(actions["ban_user"])
+
         affected = report.reported_user
         return if affected.blank?
         return unless affected.respond_to?(:email) && affected.email.present?
 
-        delivered = Moderate.notify(
+        Moderate.notify(
           :affected_user_decision,
           subject: report,
           actor: moderator,
@@ -173,8 +409,6 @@ module Moderate
             summary: "Statement of reasons for Report ##{report.id}"
           )
         )
-
-        report.update_column(:affected_user_notified_at, Time.now) if delivered
       end
 
       # The shared statement-of-reasons payload (Art. 17(3)). Every field the law
@@ -186,6 +420,8 @@ module Moderate
       #   - automated: whether automated means participated in detection/decision
       #     (Art. 17(3)(c)) — read off the report's recorded automated_processing
       #   - reason: the moderator's human-readable note
+      #   - reported_field_label: WHICH content the decision is about, in words the
+      #     affected user recognizes ("Chat message", never the column name "body")
       # The HOST renders the redress/appeal copy (it names the jurisdiction); the gem
       # supplies the data + the report so the host can mint the signed appeal link.
       def decision_payload
@@ -193,6 +429,8 @@ module Moderate
           report_id: report.id,
           status: report.status,
           action: action_label,
+          reported_field: report.reported_field,
+          reported_field_label: report.reported_field_label,
           resolution_basis: report.resolution_basis,
           # The contractual ground (in-app reports) vs. the legal ground (DSA notices).
           category: report.category,
@@ -203,6 +441,10 @@ module Moderate
           # already participated.
           automated: automated_processing_used?,
           reason: report.resolution_note,
+          # "Already actioned by decision X": the content was gone when this was decided.
+          content_already_removed_by: report.resolution_actions.to_h["content_already_removed_by"],
+          # A minimum ("at least until"): confirmed delivery (Moderate.delivered!)
+          # can move it later (Art. 20(2)), never earlier.
           appeal_deadline_at: report.appeal_deadline_at
         }.compact
       end
@@ -218,6 +460,7 @@ module Moderate
             reported_user_id: report.reported_user_id,
             reportable_type: report.reportable_type,
             reportable_id: report.reportable_id,
+            reported_field: report.reported_field,
             actions: actions,
             resolution_basis: report.resolution_basis,
             automated: automated_processing_used?,
@@ -247,9 +490,19 @@ module Moderate
       def decision_visibility_for(status, actions)
         return "no_restriction" unless status == "actioned"
         return "account_suspended" if actions[:ban_user]
-        return "content_removed" if actions[:remove_content]
 
-        "other_restriction"
+        "content_removed" # resolve! requires one of the two (require_action!)
+      end
+
+      def require_action!(actions)
+        return if actions[:remove_content] || actions[:ban_user]
+
+        report.errors.add(:base, I18n.t(
+          "moderate.errors.resolve_needs_action",
+          default: "Resolving a report restricts something: remove the content, ban the account, or both. " \
+                   "To close it without a restriction, dismiss it."
+        ))
+        raise ActiveRecord::RecordInvalid, report
       end
 
       def automated_processing_used?

data/lib/moderate/text_validator.rb

@@ -1,27 +1,28 @@
 # frozen_string_literal: true
 
+require "active_model"
+
 module ActiveModel
   module Validations
+    # `validates :body, moderate: true` — the 0.x one-liner, kept for compatibility.
+    # It is the same check as `moderates :body, with: :wordlist, mode: :block`: the
+    # built-in offline :wordlist classifies the value, and an objectionable one adds
+    # the same `:objectionable_content` error (or your `message:`). No other filter
+    # policy applies to the field through it.
+    #
+    # Required by Moderate::Engine (it reopens ActiveModel::Validations, so Zeitwerk
+    # doesn't manage it).
     class ModerateValidator < EachValidator
       def validate_each(record, attribute, value)
         return if value.blank?
 
-        begin
-          text = value.to_s
-          return if text.nil?
+        policy = Moderate::Configuration::FilterPolicy.new(
+          class_name: record.class.name, field: attribute.to_s, adapter: :wordlist, mode: :block
+        )
+        return unless Moderate.classify(value, policy: policy).flagged?
 
-          if Moderate::Text.bad_words?(text)
-            record.errors.add(attribute, options[:message] || Moderate.configuration.error_message)
-          end
-        rescue Moderate::Error => e
-          Rails.logger.error "Moderate validation error: #{e.message}"
-          record.errors.add(attribute, "Moderation check failed: #{e.message}")
-        rescue StandardError => e
-          Rails.logger.error "Unexpected error in moderate validation: #{e.message}"
-          record.errors.add(attribute, "Moderation check failed")
-        end
+        record.errors.add(attribute, options[:message] || :objectionable_content)
       end
     end
-
   end
 end

data/lib/moderate/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Moderate
-  VERSION = "1.0.0.beta1"
+  VERSION = "1.0.0"
 end