moderate 1.0.0.beta1 → 1.0.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 446ba3a97f77b4a88ebbd1d6e45e7935d6002be573835ef750829f54adaa47a7
-  data.tar.gz: 799dd6c0e21cac2b0b8038e268cf02baec331717c427ddf1d51bafa482b88776
+  metadata.gz: 20519d26bf4bc96f23e6f679b3b175376700280e36f21fffa409230688526b25
+  data.tar.gz: 8abc344dcf72c577de12ba70dbf96895f008a041355a75308f815d8b267f5dd1
 SHA512:
-  metadata.gz: 00f2800700b563559a9d8d40dc2a3fea24d487d24d2f660059908a2b377cce5627354961f3bfeff0d7f1da2c5666cc9aac45c1603a48c15ff20c9ad4b2502d33
-  data.tar.gz: c047552f0534a7df8642d2615d112723b19ecaeb62d870261c13c4fb8b114833dc0ba72ae9a646cb8e4cacba658bd1e705724c451c58a2b0348506aece0c4fbd
+  metadata.gz: 65f2ad5ae6dae9a4a1269900e67205cfedaa5f82ff3b87d218ac34dee0e05bdb417fd77289126c47c9cf372b0dfd710fc1fa5d455d1f1f256395d2ec4bc7e79c
+  data.tar.gz: 5d3a60adaef05e13b448c1563d3104423c2d94d63ae0b10c7f2432268188a745849ca29df9e99fdb4860670a4c4f3f6fe7eda8fa07a4dd4a8f47169eca97d3f8

data/CHANGELOG.md

@@ -4,12 +4,50 @@ All notable changes to this project are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.0.beta2] - 2026-07-10
+
+Second beta on the road to 1.0. Fixes beta1's async-adapter routing bug (the one
+that forced hosts to hand-roll their own enqueue), makes Active Storage
+attachments filterable with zero wiring, and gives `Flag` first-class close
+methods. Drop-in upgrade from beta1: no migrations, no breaking API changes —
+and hosts that worked around the ClassifyJob bug can now delete the workaround.
+
+### Fixed
+
+- **Async adapters now actually run in `Moderate::ClassifyJob`.** beta1's `:flag`
+  after_commit called `Moderate.classify` inline for *every* adapter — including
+  ones declaring `synchronous? == false` — so a remote moderation API ran its
+  network call inside the request that saved the content, and `ClassifyJob`
+  (whose docs promised this routing) was never enqueued by anything. The concern
+  now checks `config.adapter_async?(policy.adapter)` (new public helper, same
+  probe as the `:block` validator) and enqueues the job instead; the job re-reads
+  the persisted value and files the Flag itself. Hosts that worked around this by
+  enqueuing `ClassifyJob` themselves and short-circuiting
+  `moderation_field_changed_for_commit?` can delete both workarounds. (#3)
+
+### Added
+
+- **Active Storage attachments filter out of the box.** `moderates :avatar, with:
+  :your_image_adapter, mode: :flag` on a `has_one_attached` model needs zero extra
+  wiring now: the concern snapshots `attachment_changes` in a `before_save` (AR
+  dirty tracking can't see attachment writes, and Active Storage clears the
+  changes before after_commit), consumes the snapshot at commit time, and both
+  the concern and `ClassifyJob` treat an unattached `ActiveStorage::Attached`
+  proxy as blank (nothing to classify — covers purge-between-enqueue-and-run).
+  The three `moderation_field_*` seam overrides remain for richer cases. (#3)
+- **Flag close sugar.** `Flag#action!(note:, by: nil)` / `Flag#dismiss!(note:, by: nil)` —
+  model-level closes mirroring `Report#resolve!`/`#dismiss!`, so hosts stop hand-writing
+  status updates. `by:` stays nil for automated closes (don't fake a human in the audit
+  trail). Canonical automated use: dismiss a pending flag whose flagged content was
+  **superseded** (text edited, photo replaced/reverted) — left pending it keeps `flagged?`
+  true and mislabels the NEW content in any host UI keyed on it. (#4)
+
 ## [1.0.0] - unreleased
 
 A complete, ground-up rewrite. `moderate` graduates from a single-purpose profanity
 validator (0.1.0) into a full **Trust & Safety** engine for Rails apps with user-generated
 content: report, block, filter, a moderation queue, appeals, and EU DSA / App Store / Google
-Play **aligned** primitives. (First cut ships as `1.0.0.beta1`.)
+Play **aligned** primitives. (First cut shipped as `1.0.0.beta1`; second as `1.0.0.beta2`.)
 
 > **Breaking:** 1.0 keeps the gem name but is an entirely new API. The 0.x profanity
 > validator (`validates :field, moderate: true`) still loads for backward compatibility

data/README.md

@@ -11,6 +11,8 @@ Trust & Safety (T&S) is the system within an app that lets users **report** abus
 
 If you have an app where users can upload / generate content or send messages to each other, you probably need a Trust & Safety system.
 
+![Moderate gem sample use case for reporting profiles and blocking users](/docs/images/moderate-user-report-block-actions.webp)
+
 `moderate` ships with mechanisms aligned with the **DSA** (EU Digital Services Act), and also aligned with the **Apple App Store** and Android's **Google Play** directives for User-Generated Content (UGC) in their app stores.
 
 ## 👨‍💻 Example

data/context7.json

@@ -0,0 +1,4 @@
+{
+  "url": "https://context7.com/rameerez/moderate",
+  "public_key": "pk_HibNJE5rTFvy1txHHXUot"
+}

data/lib/moderate/configuration.rb

@@ -230,6 +230,20 @@ module Moderate
       @adapters.key?(normalize_name(name))
     end
 
+    # Is the adapter registered under `name` background-only? Same probe the
+    # :block validator uses (`validate_block_mode_adapter!`): an adapter is
+    # async ONLY if it explicitly answers `synchronous? == false`; adapters
+    # that don't expose the predicate are assumed synchronous — the
+    # conservative default that keeps simple adapters working. The :flag
+    # enforcement path reads this to decide inline-classify vs routing the
+    # work through Moderate::ClassifyJob (see ContentFilterable).
+    def adapter_async?(name)
+      adapter = adapter_for(name)
+      return false if adapter.nil?
+
+      adapter.respond_to?(:synchronous?) && !adapter.synchronous?
+    end
+
     # --- Filters --------------------------------------------------------------
 
     # Declare a per-field filter policy in the initializer — the twin of

data/lib/moderate/jobs/classify_job.rb

@@ -149,6 +149,10 @@ module Moderate
     # easy to reproduce and keeps the job self-contained).
     def blank?(value)
       return true if value.nil?
+      # An ActiveStorage::Attached proxy with nothing attached is "blank" — the
+      # attachment may have been purged between enqueue and run, and a plain
+      # #empty?/#nil? probe can't see through the proxy.
+      return !value.attached? if value.respond_to?(:attached?)
       return value.strip.empty? if value.is_a?(String)
       return value.empty? if value.respond_to?(:empty?)
 

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

@@ -16,16 +16,30 @@ module Moderate
   #            Configuration validates that invariant (README: ":block requires a
   #            synchronous adapter").
   #   :flag  — an AFTER_COMMIT side effect. The save SUCCEEDS, then (only if the
-  #            field actually changed and the value trips the filter) a
-  #            `Moderate::Flag` is filed for review.
+  #            field actually changed) the value is classified and a
+  #            `Moderate::Flag` is filed when it trips. HOW it's classified
+  #            depends on the adapter: a synchronous adapter (the wordlist)
+  #            classifies inline right here; an ASYNC adapter (`synchronous? ==
+  #            false` — any remote moderation API) is routed through
+  #            `Moderate::ClassifyJob`, because blocking network I/O must never
+  #            run inside the request that saved the content. The job re-reads
+  #            the current value and files the Flag itself.
   #
   # WHY :flag lives in after_commit and not in a validator (this is the whole
   # reason `:flag` is a `moderates` mode you can't hand-roll with `validates`):
   # validators must be side-effect-free, and a Flag created inside a transaction
   # that later rolls back would silently vanish — you'd think you flagged something
   # you didn't. `after_commit` guarantees the surrounding transaction committed
-  # before we write the Flag. See docs/configuration.md ("`:flag` never lives in a
-  # validator").
+  # before we write the Flag (and that a ClassifyJob never races a rollback). See
+  # docs/configuration.md ("`:flag` never lives in a validator").
+  #
+  # 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
+  # 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).
   module ContentFilterable
     extend ActiveSupport::Concern
 
@@ -36,6 +50,10 @@ module Moderate
       class_attribute :moderation_filtered_fields, instance_writer: false, default: [].freeze
 
       validate :moderate_blocked_fields_must_be_allowed
+      # Snapshot attachment writes BEFORE Active Storage's own save callbacks
+      # clear `attachment_changes` — by after_commit they're gone (see
+      # activestorage's Attached::Model). One-shot; consumed + cleared below.
+      before_save :moderate_snapshot_attachment_changes
       after_commit :moderate_flag_filtered_fields
     end
 
@@ -61,20 +79,21 @@ module Moderate
         next unless policy.block?
 
         value = moderation_field_value(field)
-        next if value.blank?
+        next if moderation_value_blank?(value)
 
         result = Moderate.classify(value, policy: policy)
         errors.add(field, :objectionable_content) if result.flagged?
       end
     end
 
-    # :flag enforcement — an after_commit side effect that files a Moderate::Flag.
+    # :flag enforcement — an after_commit side effect that files a Moderate::Flag
+    # (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 a clean-up hook (`moderation_field_committed`)
-    # always runs even if classification raises — important for the attachment
-    # seam below, where a host sets a one-shot "changed" flag it must clear.
+    # 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.
     def moderate_flag_filtered_fields
       moderation_filtered_fields.each do |field|
         policy = Moderate.filter_policy_for(self, field)
@@ -82,8 +101,18 @@ module Moderate
         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 value.blank?
+          next if moderation_value_blank?(value)
 
           result = Moderate.classify(value, policy: policy)
           next unless result.flagged?
@@ -119,23 +148,29 @@ module Moderate
     # --- Overridable field seam -----------------------------------------------
     #
     # These three methods are the seam that lets one concern filter BOTH plain text
-    # columns AND non-column content (e.g. an Active Storage attachment), without
-    # the concern knowing anything about attachments. Defaults handle the common
-    # "it's a text attribute" case; a host overrides them for richer content.
-
-    # The value to classify for `field`. Default: the attribute reader. Override to
-    # return, say, an attachment's blob/URL for an image adapter. The classifier
-    # (text or image) is whatever the field's policy adapter is.
+    # columns AND non-column content, without hosts having to re-plumb the common
+    # cases. Defaults handle text attributes AND Active Storage attachments; a
+    # host overrides them for anything richer (derived values, external blobs).
+
+    # The value to classify for `field`. Default: the attribute reader — which for
+    # a `has_one_attached` field returns the `ActiveStorage::Attached` proxy, the
+    # natural input for an image adapter (it can read `.record`, `.blob`,
+    # `.variant(...)`, or download bytes as it sees fit).
     def moderation_field_value(field)
       public_send(field)
     end
 
-    # Did `field` change on the just-committed save? Default: ask ActiveRecord's
-    # dirty tracking (`saved_change_to_attribute?`). We guard with `respond_to?`
-    # so the concern also works on a PORO/ActiveModel object that lacks AR dirty
-    # tracking (in which case we conservatively assume it changed). Override for
-    # non-attribute content (e.g. track an attachment's "was replaced" flag).
+    # 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),
+    #   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.
+    # Override for non-attribute content the defaults can't see.
     def moderation_field_changed_for_commit?(field)
+      return true if @moderate_changed_attachment_fields&.include?(field.to_s)
+
       if respond_to?(:saved_change_to_attribute?)
         saved_change_to_attribute?(field)
       elsif respond_to?(:"saved_change_to_#{field}?")
@@ -146,10 +181,34 @@ module Moderate
     end
 
     # Per-field clean-up after the commit-time flag attempt (success OR failure).
-    # No-op by default; the attachment seam overrides it to reset a one-shot
-    # "changed" flag it set during the save.
-    def moderation_field_committed(_field)
+    # Consumes the one-shot attachment snapshot; override-and-super if you track
+    # extra per-field state of your own.
+    def moderation_field_committed(field)
+      @moderate_changed_attachment_fields&.delete(field.to_s)
       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.
+    def moderate_snapshot_attachment_changes
+      return true unless respond_to?(:attachment_changes)
+
+      moderation_filtered_fields.each do |field|
+        next unless attachment_changes.key?(field)
+
+        (@moderate_changed_attachment_fields ||= Set.new) << field
+      end
+      true # never halt the save chain
+    end
+
+    # Blank check that can see through an `ActiveStorage::Attached` proxy — an
+    # attachment with nothing attached must read as "nothing to classify"
+    # (Object#blank? can't tell: the proxy is truthy and has no #empty?).
+    def moderation_value_blank?(value)
+      return !value.attached? if value.respond_to?(:attached?)
+
+      value.blank?
+    end
   end
 end

data/lib/moderate/models/flag.rb

@@ -97,6 +97,26 @@ module Moderate
       status.in?(%w[actioned dismissed])
     end
 
+    # Close this flag as ACTIONED — someone (or an automated policy) took
+    # action on the flagged content. Model-level sugar mirroring
+    # Report#resolve!/#dismiss! so hosts stop hand-writing status updates.
+    # `by:` is the reviewing user when a human decided; leave it nil for
+    # automated closes — recording a human who never looked would poison the
+    # audit trail (DSA statements of reasons read these rows).
+    def action!(note:, by: nil)
+      close!(new_status: "actioned", note: note, by: by)
+    end
+
+    # Close this flag with NO action taken. The canonical automated use is
+    # SUPERSEDED content: when the flagged field changes (text edited, photo
+    # replaced/reverted), a still-pending flag is about content that is no
+    # longer live — leaving it pending keeps `flagged?` true and mislabels
+    # the NEW content in any host UI keyed on it. Hosts should dismiss with a
+    # note saying what superseded it.
+    def dismiss!(note:, by: nil)
+      close!(new_status: "dismissed", note: note, by: by)
+    end
+
     # A label for the flagged thing in the queue. Asks the flaggable for its own
     # `moderation_label` (Moderate::Reportable interface); falls back to a generic
     # "Type id" string for content that doesn't implement it.
@@ -108,6 +128,19 @@ module Moderate
 
     private
 
+    # Shared close path for action!/dismiss!. update! (not update_columns) on
+    # purpose: the `resolution_note presence if closed?` validation is the
+    # guard that every closed flag explains itself — sugar that skipped it
+    # would defeat the reason the sugar exists.
+    def close!(new_status:, note:, by:)
+      update!(
+        status: new_status,
+        resolution_note: note,
+        reviewed_by: by,
+        reviewed_at: Time.current
+      )
+    end
+
     # See the before_save comment: keep the NOT-NULL JSON columns non-null on MySQL.
     def default_json_columns
       self.categories ||= []

data/lib/moderate/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: moderate
 version: !ruby/object:Gem::Version
-  version: 1.0.0.beta1
+  version: 1.0.0.beta2
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-06-03 00:00:00.000000000 Z
+date: 2026-07-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -136,9 +136,11 @@ files:
 - config/moderate/blocklists/en.yml
 - config/moderate/blocklists/es.yml
 - config/routes.rb
+- context7.json
 - docs/compliance.md
 - docs/configuration.md
 - docs/dsa-notice-form.md
+- docs/images/moderate-user-report-block-actions.webp
 - docs/madmin.md
 - docs/notifications.md
 - examples/aws_rekognition_adapter.rb