flipper_trail 0.1.0

data/lib/flipper_trail/entry.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module FlipperTrail
+  # An immutable record of a single feature-flag change: which feature and gate,
+  # the operation, the before/after state, the {Actor}, and when it happened.
+  #
+  # @!attribute [rw] feature_name
+  #   @return [String] the feature key
+  # @!attribute [rw] operation
+  #   @return [Symbol] the write performed (`:add`, `:remove`, `:clear`,
+  #     `:enable`, `:disable`)
+  # @!attribute [rw] gate_name
+  #   @return [String, nil] the gate affected, if any
+  # @!attribute [rw] before
+  #   @return [Object] the gate state before the change
+  # @!attribute [rw] after
+  #   @return [Object] the gate state after the change
+  # @!attribute [rw] actor
+  #   @return [Actor, nil] who made the change
+  # @!attribute [rw] created_at
+  #   @return [Time] when the change was recorded
+  Entry = Struct.new(
+    :feature_name, :operation, :gate_name, :before, :after, :actor, :created_at,
+    keyword_init: true
+  ) do
+    # @return [Boolean] whether the change altered the feature's state
+    def changed?
+      before != after
+    end
+  end
+end

data/lib/flipper_trail/generators/flipper_trail/install_generator.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/migration'
+require 'active_record'
+
+module FlipperTrail
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      include ::Rails::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      def self.next_migration_number(dirname)
+        next_number = current_migration_number(dirname) + 1
+        ::ActiveRecord::Migration.next_migration_number(next_number)
+      end
+
+      def create_initializer
+        template 'initializer.rb.tt', 'config/initializers/flipper_trail.rb'
+      end
+
+      # NOTE: must NOT be named `create_migration` — Rails::Generators::Migration already defines an
+      # instance method `create_migration(destination, data, config)` that migration_template calls internally;
+      # a zero-arg Thor command of the same name shadows it and raises ArgumentError (given 3, expected 0).
+      def create_migration_file
+        migration_template 'migration.rb.tt', 'db/migrate/create_flipper_trail_entries.rb'
+      end
+    end
+  end
+end

data/lib/flipper_trail/generators/flipper_trail/templates/initializer.rb.tt

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+FlipperTrail.configure do |config|
+  # config.storage = :active_record # optional — inferred from the Flipper adapter you wrap; set to override
+  # Mongoid users: indexes are declared on the audit document but not auto-built. Create them once:
+  #   bin/rails runner 'require "flipper_trail/storage/mongoid"; FlipperTrail::Storage::Mongoid::Entry.create_indexes'
+  # config.actor_resolver       = -> { Current.user } # MUST be zero-arity (runs off-request too)
+  # config.system_actor         = { type: "system", id: nil, label: "system" }
+  # config.ignored_features     = []
+  # config.raise_on_audit_error = false # true = a failing audit write aborts the flag write
+  # config.on_error             = ->(error, entry) { Rails.logger.error("[flipper_trail] #{error.message}") }
+end
+
+# Wrap the FlipperTrail decorator around your real Flipper adapter, e.g.:
+#
+#   require "flipper/adapters/active_record"
+#
+#   Flipper.configure do |config|
+#     config.adapter { FlipperTrail.wrap(Flipper::Adapters::ActiveRecord.new) }
+#   end
+#
+# Capture the acting user per request (e.g. in ApplicationController):
+#
+#   before_action { FlipperTrail::Current.actor = current_user }
+#
+# In front of a mounted Flipper::UI, insert the middleware so UI toggles are attributed:
+#
+#   config.middleware.use FlipperTrail::Middleware, resolver: ->(env) { ... }

data/lib/flipper_trail/generators/flipper_trail/templates/migration.rb.tt

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+class CreateFlipperTrailEntries < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :flipper_trail_entries do |t|
+      t.string :feature_name, null: false
+      t.string :operation, null: false
+      t.string :gate_name
+      t.json :before_state
+      t.json :after_state
+      t.string :actor_type
+      t.string :actor_id
+      t.string :actor_label
+      t.datetime :created_at, null: false
+    end
+
+    add_index :flipper_trail_entries, %i[feature_name created_at]
+    add_index :flipper_trail_entries, :created_at
+    add_index :flipper_trail_entries, %i[actor_id created_at]
+  end
+end

data/lib/flipper_trail/middleware.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'flipper_trail/current'
+
+module FlipperTrail
+  # Rack middleware that resolves the current actor for the duration of a request
+  # and stores it on {Current}, so flag changes during that request are attributed
+  # to it.
+  #
+  # @example Insert into a Rails app
+  #   config.middleware.use FlipperTrail::Middleware, resolver: ->(env) { env["warden"].user }
+  class Middleware
+    # @param app [#call] the next Rack app in the stack
+    # @param resolver [#call, nil] resolves the request's actor; may take the
+    #   Rack env (called with it) or take no arguments (called zero-arity). When
+    #   nil, falls back to the configured `actor_resolver`.
+    def initialize(app, resolver: nil)
+      @app = app
+      @resolver = resolver
+    end
+
+    # Sets the resolved actor on {Current} for the wrapped request.
+    #
+    # @param env [Hash] the Rack environment
+    # @return [Array(Integer, Hash, #each)] the Rack response
+    def call(env)
+      Current.set(actor: resolve(env)) { @app.call(env) }
+    end
+
+    private
+
+    # The injected `resolver:` MAY take env (it runs inside a request). The shared
+    # config.actor_resolver is ALWAYS called zero-arity — it's the same fallback the Recorder
+    # uses off-request (console/job), so keeping one contract avoids an arity-mismatch crash there.
+    def resolve(env)
+      if @resolver
+        @resolver.arity.zero? ? @resolver.call : @resolver.call(env)
+      else
+        FlipperTrail.configuration.actor_resolver&.call
+      end
+    end
+  end
+end

data/lib/flipper_trail/railtie.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'rails/railtie'
+
+module FlipperTrail
+  class Railtie < ::Rails::Railtie
+    generators do
+      require 'flipper_trail/generators/flipper_trail/install_generator'
+    end
+  end
+end

data/lib/flipper_trail/recorder.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'flipper_trail/actor'
+require 'flipper_trail/entry'
+
+module FlipperTrail
+  # Builds an {Entry} from a flag change and persists it through the configured
+  # storage backend. No-op changes (`before == after`) and ignored features are
+  # dropped.
+  class Recorder
+    # Records a single flag change as an audit entry.
+    #
+    # @param feature_name [String, Symbol] the feature key
+    # @param operation [Symbol] the write performed (`:add`, `:remove`,
+    #   `:clear`, `:enable`, `:disable`)
+    # @param gate_name [String, Symbol, nil] the gate affected, if any
+    # @param before [Object] the feature's gate state before the change
+    # @param after [Object] the feature's gate state after the change
+    # @return [Entry, nil] the persisted entry, or nil when the change was a
+    #   no-op or the feature is ignored
+    def record(feature_name:, operation:, gate_name:, before:, after:)
+      feature_name = feature_name.to_s
+      return if config.ignored_features.map(&:to_s).include?(feature_name)
+      return if before == after
+
+      entry = Entry.new(
+        feature_name: feature_name,
+        operation: operation,
+        gate_name: gate_name&.to_s,
+        before: before,
+        after: after,
+        actor: current_actor,
+        created_at: Time.now
+      ).freeze
+      persist(entry)
+      entry
+    end
+
+    # Resolves the actor to attribute a change to, trying the per-request
+    # {Current} actor, then the configured `actor_resolver`, then the system actor.
+    #
+    # @return [Actor, nil] the wrapped actor, or nil when none resolves
+    def current_actor
+      raw = Current.actor || config.actor_resolver&.call || config.system_actor
+      Actor.wrap(raw)
+    end
+
+    private
+
+    # Audit-write failures must never break the flag write that already succeeded.
+    # Swallow + route to on_error by default; opt into fail-closed via raise_on_audit_error.
+    def persist(entry)
+      config.storage_backend.record(entry)
+    rescue StandardError => e
+      raise if config.raise_on_audit_error
+
+      handler = config.on_error
+      handler ? handler.call(e, entry) : warn("[flipper_trail] audit write failed: #{e.class}: #{e.message}")
+    end
+
+    def config
+      FlipperTrail.configuration
+    end
+  end
+end

data/lib/flipper_trail/storage/active_record.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'active_record'
+require 'flipper_trail/entry'
+require 'flipper_trail/actor'
+
+module FlipperTrail
+  module Storage
+    class ActiveRecord
+      class Entry < ::ActiveRecord::Base
+        self.table_name = 'flipper_trail_entries'
+      end
+
+      def record(entry)
+        Entry.create!(
+          feature_name: entry.feature_name,
+          operation: entry.operation.to_s,
+          gate_name: entry.gate_name,
+          before_state: entry.before,
+          after_state: entry.after,
+          actor_type: entry.actor&.type,
+          actor_id: entry.actor&.id,
+          actor_label: entry.actor&.label,
+          created_at: entry.created_at
+        )
+      end
+
+      def query(feature: nil, actor_id: nil, since: nil, until_time: nil, limit: 100)
+        scope = Entry.all
+        scope = scope.where(feature_name: feature.to_s) if feature
+        scope = scope.where(actor_id: actor_id.to_s) if actor_id
+        scope = scope.where(arel_table[:created_at].gteq(since)) if since
+        scope = scope.where(arel_table[:created_at].lteq(until_time)) if until_time
+        # id DESC is a deterministic tiebreaker so bursts with equal created_at stay newest-first.
+        scope.order(created_at: :desc, id: :desc).limit(limit).map { |row| to_entry(row) }
+      end
+
+      private
+
+      def arel_table
+        Entry.arel_table
+      end
+
+      def to_entry(row)
+        FlipperTrail::Entry.new(
+          feature_name: row.feature_name,
+          operation: row.operation.to_sym,
+          gate_name: row.gate_name,
+          before: row.before_state,
+          after: row.after_state,
+          actor: FlipperTrail::Actor.new(type: row.actor_type, id: row.actor_id, label: row.actor_label),
+          created_at: row.created_at
+        ).freeze
+      end
+    end
+  end
+end

data/lib/flipper_trail/storage/mongoid.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'mongoid'
+require 'flipper_trail/entry'
+require 'flipper_trail/actor'
+
+module FlipperTrail
+  module Storage
+    class Mongoid
+      class Entry
+        include ::Mongoid::Document
+
+        store_in collection: 'flipper_trail_entries'
+
+        field :feature_name, type: String
+        field :operation, type: String
+        field :gate_name, type: String
+        field :before_state, type: Hash
+        field :after_state, type: Hash
+        field :actor_type, type: String
+        field :actor_id, type: String
+        field :actor_label, type: String
+        field :created_at, type: Time
+
+        index({ feature_name: 1, created_at: -1 })
+        index({ created_at: -1 })
+        index({ actor_id: 1, created_at: -1 })
+      end
+
+      def record(entry)
+        Entry.create!(
+          feature_name: entry.feature_name,
+          operation: entry.operation.to_s,
+          gate_name: entry.gate_name,
+          before_state: entry.before,
+          after_state: entry.after,
+          actor_type: entry.actor&.type,
+          actor_id: entry.actor&.id,
+          actor_label: entry.actor&.label,
+          created_at: entry.created_at
+        )
+      end
+
+      def query(feature: nil, actor_id: nil, since: nil, until_time: nil, limit: 100)
+        scope = Entry.all
+        scope = scope.where(feature_name: feature.to_s) if feature
+        scope = scope.where(actor_id: actor_id.to_s) if actor_id
+        scope = scope.gte(created_at: since) if since
+        scope = scope.lte(created_at: until_time) if until_time
+        # _id DESC is a deterministic tiebreaker (BSON ObjectId is creation-ordered)
+        # so equal-timestamp bursts stay newest-first.
+        scope.order_by(created_at: :desc, _id: :desc).limit(limit).map { |doc| to_entry(doc) }
+      end
+
+      private
+
+      def to_entry(doc)
+        FlipperTrail::Entry.new(
+          feature_name: doc.feature_name,
+          operation: doc.operation.to_sym,
+          gate_name: doc.gate_name,
+          before: doc.before_state,
+          after: doc.after_state,
+          actor: FlipperTrail::Actor.new(type: doc.actor_type, id: doc.actor_id, label: doc.actor_label),
+          created_at: doc.created_at
+        ).freeze
+      end
+    end
+  end
+end

data/lib/flipper_trail/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module FlipperTrail
+  VERSION = '0.1.0'
+end

data/lib/flipper_trail.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require 'flipper_trail/version'
+require 'flipper_trail/configuration'
+require 'flipper_trail/current'
+require 'flipper_trail/actor'
+require 'flipper_trail/entry'
+require 'flipper_trail/recorder'
+require 'flipper_trail/adapter'
+require 'flipper_trail/middleware'
+
+# Records an append-only audit trail of Flipper feature-flag changes — who
+# changed what, when, and the before/after state — via an adapter decorator.
+# {configure} it once, then query it with {history}.
+module FlipperTrail
+  class << self
+    # The memoized global configuration.
+    #
+    # @return [Configuration] the shared configuration instance
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # The memoized global recorder that builds and persists audit entries.
+    #
+    # @return [Recorder] the shared recorder instance
+    def recorder
+      @recorder ||= Recorder.new
+    end
+
+    # Wrap a Flipper adapter so every write through it is audited.
+    #
+    # Shorthand for FlipperTrail::Adapter.new(adapter); pass the result to Flipper's config.adapter.
+    #
+    # @param adapter [Object] the real Flipper adapter to decorate
+    # @param recorder [FlipperTrail::Recorder, nil] optional recorder override (mainly for tests)
+    # @return [FlipperTrail::Adapter] the audit decorator to give to +config.adapter+
+    # @example
+    #   Flipper.configure { |c| c.adapter { FlipperTrail.wrap(Flipper::Adapters::ActiveRecord.new) } }
+    def wrap(adapter, recorder: nil)
+      Adapter.new(adapter, recorder: recorder)
+    end
+
+    # Configures the gem by yielding the global {Configuration}.
+    #
+    # @yieldparam config [Configuration] the configuration to mutate
+    # @return [void]
+    #
+    # @example
+    #   FlipperTrail.configure do |config|
+    #     config.storage = :active_record
+    #     config.actor_resolver = -> { Current.user }
+    #   end
+    def configure
+      yield configuration
+    end
+
+    # Queries the audit trail through the configured storage backend.
+    #
+    # @param filters [Hash] optional filters
+    # @option filters [String] :feature only entries for this feature key
+    # @option filters [String] :actor_id only entries by this actor id
+    # @option filters [Time] :since only entries created at or after this time
+    # @option filters [Time] :until only entries created at or before this time
+    # @option filters [Integer] :limit maximum number of entries (default 100)
+    # @return [Array<Entry>] the matching audit entries, newest first
+    #
+    # @example
+    #   FlipperTrail.history(feature: "search", limit: 10)
+    def history(**filters)
+      configuration.storage_backend.query(
+        feature: filters[:feature],
+        actor_id: filters[:actor_id],
+        since: filters[:since],
+        until_time: filters[:until],
+        limit: filters[:limit] || 100
+      )
+    end
+
+    # The actor the recorder would attribute a change to right now.
+    #
+    # @return [Actor, nil] the resolved actor, or nil when none is set
+    def current_actor
+      recorder.current_actor
+    end
+
+    # Resets the memoized configuration, recorder, and per-request actor.
+    #
+    # @return [void]
+    def reset!
+      @configuration = nil
+      @recorder = nil
+      Current.reset if defined?(Current)
+    end
+  end
+end
+
+require 'flipper_trail/railtie' if defined?(Rails::Railtie)

data/sig/flipper_trail.rbs

@@ -0,0 +1,68 @@
+# RBS type signatures for the public API of FlipperTrail.
+#
+# Only the public surface is described here. Everything that touches an external
+# library (flipper, activerecord, mongoid, rack env, ActiveSupport::CurrentAttributes)
+# is intentionally left as `untyped` — we do not chase typing the dependency surface.
+
+module FlipperTrail
+  VERSION: String
+
+  def self.configure: () { (Configuration) -> void } -> void
+  def self.configuration: () -> Configuration
+  def self.history: (**untyped) -> Array[Entry]
+  def self.current_actor: () -> Actor
+  def self.recorder: () -> Recorder
+  def self.wrap: (untyped adapter, ?recorder: untyped) -> Adapter
+  def self.reset!: () -> void
+
+  class Configuration
+    attr_accessor storage: untyped
+    attr_accessor actor_resolver: untyped
+    attr_accessor system_actor: untyped
+    attr_accessor ignored_features: untyped
+    attr_accessor on_error: untyped
+    attr_accessor raise_on_audit_error: bool
+
+    def initialize: () -> void
+    def storage_backend: () -> untyped
+  end
+
+  class Entry
+    attr_reader feature_name: untyped
+    attr_reader operation: untyped
+    attr_reader gate_name: untyped
+    attr_reader before: untyped
+    attr_reader after: untyped
+    attr_reader actor: untyped
+    attr_reader created_at: untyped
+
+    def changed?: () -> bool
+  end
+
+  class Actor
+    attr_reader type: untyped
+    attr_reader id: String?
+    attr_reader label: untyped
+
+    def initialize: (type: untyped, id: untyped, label: untyped) -> void
+    def self.wrap: (untyped) -> Actor?
+    def to_h: () -> Hash[Symbol, untyped]
+  end
+
+  class Current
+  end
+
+  class Adapter
+    def initialize: (untyped, ?recorder: untyped) -> void
+  end
+
+  class Middleware
+    def initialize: (untyped, ?resolver: untyped) -> void
+    def call: (untyped) -> untyped
+  end
+
+  class Recorder
+    def record: (**untyped) -> untyped
+    def current_actor: () -> Actor
+  end
+end