rollout 3.1.0 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f825c30d598b5b2b194b97b0371bbd1ceda8f341458a64b1a601941ee11580eb
-  data.tar.gz: '038f689c1fe1f5eb3aba0e4eaadcc80da24f320b863a4fffecf6ca3fe4355ba4'
+  metadata.gz: cadea20a7d731c5538e5d6b6b19b34075843230fd5c6d75ffc4c269ce667a63f
+  data.tar.gz: '06483d373ff87c4e0537ab73d57be5bba089d43a4abacd87168bdf338cb4ca5e'
 SHA512:
-  metadata.gz: 2dd85351ad0860f8a2bd86b8b018fad5ed6175751f3018fcc20cad2e96fed7df38de74fc04205207a6de627b168fa0dd04575bf534aa461ed6d4d9b74d36d013
-  data.tar.gz: ab692a6ae7d929d52df99b7d9de6f0ca41a018c72f5cddc05b3fa37051418ca476b7b89af862c77353e8a82646d0adfa8832a04a8c96b3941a6d865da69626d0
+  metadata.gz: 515d4d646e3c4c2c2fee20d77088a9dd22fe5730dd605764abfbc0e189591f7eaaf076830940358500e05eed30f456b9389f8843bad1df283d01b795eae6e935
+  data.tar.gz: c41503b0e1acff3c3c99de9b08d7c06167f2d4a2f7c7fc493230c11c70f633dcae0bc4c5a7028d04e11b01dfd7edfb6eaaf6d33255c559cd4b93fda206e10427

data/.github/workflows/release.yml

@@ -5,6 +5,7 @@ on:
     tags:
       - 'rollout/v*'
       - 'rollout-redis-adapter/v*'
+      - 'rollout-active_record-adapter/v*'
 
 permissions:
   contents: write
@@ -32,6 +33,7 @@ jobs:
           case "$GITHUB_REF_NAME" in
             rollout/v*) name=rollout; directory=. ;;
             rollout-redis-adapter/v*) name=rollout-redis-adapter; directory=rollout-redis-adapter ;;
+            rollout-active_record-adapter/v*) name=rollout-active_record-adapter; directory=rollout-active_record-adapter ;;
             *) echo "Unexpected tag $GITHUB_REF_NAME" >&2; exit 1 ;;
           esac
           version="${GITHUB_REF_NAME##*/v}"
@@ -60,7 +62,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Create GitHub Release
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@v3
         with:
           tag_name: ${{ github.ref }}
           name: ${{ needs.publish.outputs.name }} ${{ needs.publish.outputs.version }}

data/.github/workflows/test.yml

@@ -28,7 +28,7 @@ jobs:
           bundle exec rspec spec --format progress --format RspecJunitFormatter --out test_results/rspec.xml
       - name: Upload test results
         if: always()
-        uses: actions/upload-artifact@v5
+        uses: actions/upload-artifact@v6
         with:
           name: core-test-results-${{ matrix.ruby-version }}
           path: test_results/rspec.xml
@@ -65,8 +65,110 @@ jobs:
           bundle exec rspec --format progress --format RspecJunitFormatter --out test_results/rspec.xml
       - name: Upload test results
         if: always()
-        uses: actions/upload-artifact@v5
+        uses: actions/upload-artifact@v6
         with:
           name: redis-test-results-${{ matrix.ruby-version }}
           path: rollout-redis-adapter/test_results/rspec.xml
           retention-days: 30
+
+  active_record:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - ruby-version: '3.3'
+            activerecord: '~> 8.1.0'
+            db: sqlite3
+          - ruby-version: '3.3'
+            activerecord: '~> 8.1.0'
+            db: postgresql
+          - ruby-version: '3.3'
+            activerecord: '~> 8.1.0'
+            db: mysql2
+          - ruby-version: '3.3'
+            activerecord: '~> 7.1.0'
+            db: postgresql
+          - ruby-version: '3.3'
+            activerecord: '~> 7.1.0'
+            db: mysql2
+          - ruby-version: '3.2'
+            activerecord: '~> 8.0.0'
+            db: sqlite3
+          - ruby-version: '3.1'
+            activerecord: '~> 7.2.0'
+            db: sqlite3
+          - ruby-version: '2.7'
+            activerecord: '~> 7.1.0'
+            db: sqlite3
+    env:
+      ACTIVERECORD_VERSION: ${{ matrix.activerecord }}
+      ROLLOUT_AR_ADAPTER: ${{ matrix.db }}
+      POSTGRES_HOST: localhost
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: rollout_test
+      MYSQL_HOST: 127.0.0.1
+      MYSQL_USER: root
+      MYSQL_PASSWORD: root
+      MYSQL_DATABASE: rollout_test
+      REDIS_HOST: 127.0.0.1
+    services:
+      redis:
+        image: redis:7-alpine
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: rollout_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+      mysql:
+        image: mysql:8.0
+        env:
+          MYSQL_ROOT_PASSWORD: root
+          MYSQL_DATABASE: rollout_test
+        ports:
+          - 3306:3306
+        options: >-
+          --health-cmd "mysqladmin ping -h 127.0.0.1 -uroot -proot"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+      - name: Install database client libraries
+        run: sudo apt-get update && sudo apt-get install -y libpq-dev default-libmysqlclient-dev
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          working-directory: rollout-active_record-adapter
+          bundler-cache: true
+          cache-version: ar-${{ matrix.ruby-version }}-${{ matrix.activerecord }}-${{ matrix.db }}
+      - name: Run Active Record adapter tests
+        working-directory: rollout-active_record-adapter
+        run: |
+          mkdir -p test_results
+          bundle exec rspec --format progress --format RspecJunitFormatter --out test_results/rspec.xml
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v5
+        with:
+          name: active-record-test-results-${{ matrix.ruby-version }}-${{ matrix.db }}-${{ strategy.job-index }}
+          path: rollout-active_record-adapter/test_results/rspec.xml
+          retention-days: 30

data/README.md

@@ -22,6 +22,11 @@ gem "rollout", "~> 3.1"
 gem "rollout-redis-adapter", "~> 0.1"
 ```
 
+Active Record applications can use `rollout-active_record-adapter` instead of
+`rollout-redis-adapter`. See the [Active Record adapter README](rollout-active_record-adapter/README.md).
+To copy current feature state from Redis, see
+[Migrate from Redis](rollout-active_record-adapter/README.md#migrate-from-redis).
+
 ## How it works
 
 Initialize a rollout object. I assign it to a global var.
@@ -29,7 +34,7 @@ Initialize a rollout object. I assign it to a global var.
 ```ruby
 require "redis"
 require "rollout"
-require "rollout/adapters/redis"
+require "rollout-redis-adapter"
 
 $redis = Redis.new
 $rollout = Rollout.new(adapter: Rollout::Adapters::Redis.new($redis))
@@ -196,7 +201,7 @@ gem "redis-namespace"
 require "redis"
 require "redis/namespace"
 require "rollout"
-require "rollout/adapters/redis"
+require "rollout-redis-adapter"
 
 $ns = Redis::Namespace.new(Rails.env, redis: $redis)
 $rollout = Rollout.new(adapter: Rollout::Adapters::Redis.new($ns))
@@ -232,11 +237,12 @@ Rollout 3-compatible UI release before upgrading production.
 
 ## Testing
 
-Install dependencies first. Core and the Redis adapter have separate Gemfiles:
+Install dependencies first. Core and the adapter gems have separate Gemfiles:
 
 ```bash
 bundle install
 bundle install --gemfile=rollout-redis-adapter/Gemfile
+bundle install --gemfile=rollout-active_record-adapter/Gemfile
 ```
 
 Core tests do not need Redis:
@@ -261,6 +267,15 @@ bundle exec rake spec:redis
 Optional connection settings: `REDIS_HOST`, `REDIS_PORT`, `REDIS_DB`. `REDIS_DB`
 overrides the default database 7 that is flushed before each example.
 
+Active Record adapter tests default to SQLite. PostgreSQL and MySQL are also
+supported:
+
+```bash
+bundle exec rake spec:active_record
+ROLLOUT_AR_ADAPTER=postgresql bundle exec rake spec:active_record
+ROLLOUT_AR_ADAPTER=mysql2 bundle exec rake spec:active_record
+```
+
 ## Releasing
 
 Each gem has its own version and tag.
@@ -268,10 +283,12 @@ Each gem has its own version and tag.
 - Configure a RubyGems trusted publisher for the gem you are releasing. Use
   repository owner `fetlife`, repository `rollout`, workflow filename
   `release.yml`, and no GitHub environment.
-- Update and commit the version in `lib/rollout/version.rb` or
-  `rollout-redis-adapter/rollout-redis-adapter.gemspec`.
-- Tag the release commit with `rollout/vX.Y.Z` or
-  `rollout-redis-adapter/vX.Y.Z`, matching the gem version.
+- Update and commit the version in `lib/rollout/version.rb`,
+  `rollout-redis-adapter/rollout-redis-adapter.gemspec`, or
+  `rollout-active_record-adapter/rollout-active_record-adapter.gemspec`.
+- Tag the release commit with `rollout/vX.Y.Z`,
+  `rollout-redis-adapter/vX.Y.Z`, or
+  `rollout-active_record-adapter/vX.Y.Z`, matching the gem version.
 - Push the tag with `git push origin <tag>`. CI publishes the selected gem and
   creates its GitHub release.
 

data/Rakefile

@@ -16,6 +16,16 @@ namespace :spec do
       end
     end
   end
+
+  desc "Run Active Record adapter tests"
+  task :active_record do
+    gemfile = File.expand_path("rollout-active_record-adapter/Gemfile", __dir__)
+    Dir.chdir("rollout-active_record-adapter") do
+      Bundler.with_unbundled_env do
+        sh({ "BUNDLE_GEMFILE" => gemfile }, "bundle exec rspec")
+      end
+    end
+  end
 end
 
 task default: :spec

data/docs/upgrading-to-v3.md

@@ -2,7 +2,9 @@
 
 Rollout 3 keeps feature evaluation in the `rollout` gem and moves Redis
 persistence to `rollout-redis-adapter`. Existing Redis keys stay in place. This is
-not the later Active Record / PostgreSQL migration.
+not a storage migration onto Active Record. For the Active Record adapter
+and Redis cutover, see
+[rollout-active_record-adapter/README.md](../rollout-active_record-adapter/README.md).
 
 ## 1. Update dependencies
 
@@ -39,7 +41,7 @@ $rollout = Rollout.new(
 # After
 require "redis"
 require "rollout"
-require "rollout/adapters/redis"
+require "rollout-redis-adapter"
 
 $redis = Redis.new
 $rollout = Rollout.new(
@@ -90,11 +92,18 @@ history.
 
 | Operation | Feature state | Per-feature history | Global history |
 | --- | --- | --- | --- |
-| `delete`, logging enabled | Removed | Removed | Retained |
+| `delete`, logging enabled | Removed | Removed | Retained; emits a global `delete` event when `global: true` and the adapter supports event-aware deletion |
 | `delete`, logging disabled | Removed | Retained | Retained |
 | `logging.delete` | Unchanged | Removed | Retained |
 | `clear!` | Removed | Retained | Retained |
 
+The deletion event includes the feature name, timestamp, and current logging
+context (for example, an actor supplied with `logging.with_context`). Built-in
+adapters write it only when the feature exists and global logging is enabled;
+it is subject to `history_length` like other global events. Older or custom
+adapters without `delete_feature_with_history` retain the previous deletion
+behavior and do not record a deletion event.
+
 `clear!` still resets each feature first, so logging-enabled instances record
 a reset event before the state is deleted. History remains subject to
 `history_length`. The Redis registry key is removed after clearing, including

data/lib/rollout/logging.rb

@@ -74,6 +74,18 @@ class Rollout
         @adapter.delete_feature_events(feature_name)
       end
 
+      def delete_event_for(feature_name)
+        return unless logging_enabled? && global
+
+        Event.new(
+          feature: feature_name.to_s,
+          name: :delete,
+          data: {},
+          context: current_context,
+          created_at: Time.now,
+        )
+      end
+
       def event_for(before, after)
         return unless logging_enabled?
 

data/lib/rollout/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Rollout
-  VERSION = '3.1.0'
+  VERSION = '3.2.0'
 end

data/lib/rollout.rb

@@ -38,9 +38,16 @@ class Rollout
   end
 
   def delete(feature)
-    @adapter.delete_feature(feature)
+    return @adapter.delete_feature(feature) unless respond_to?(:logging)
 
-    if respond_to?(:logging)
+    if @adapter.respond_to?(:delete_feature_with_history)
+      @adapter.delete_feature_with_history(
+        feature,
+        event: logging.delete_event_for(feature),
+        history_length: logging.history_length,
+      )
+    else
+      @adapter.delete_feature(feature)
       logging.delete(feature)
     end
   end

data/rollout.gemspec

@@ -14,7 +14,7 @@ Gem::Specification.new do |spec|
   spec.license     = 'MIT'
 
   spec.files = `git ls-files`.split("\n").reject do |file|
-    file.start_with?('rollout-redis-adapter/')
+    file.start_with?('rollout-redis-adapter/', 'rollout-active_record-adapter/')
   end
   spec.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   spec.executables   = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }

data/spec/rollout_spec.rb

@@ -191,5 +191,56 @@ RSpec.describe Rollout do
 
       expect(rollout.logging.events(:chat)).to eq []
     end
+
+    it "records a global deletion event with the current context" do
+      backend = RolloutMemoryBackend.new
+      rollout = described_class.new(adapter: backend, logging: { global: true })
+      rollout.activate_percentage(:chat, 25)
+
+      rollout.logging.with_context(actor: "alice") { rollout.delete(:chat) }
+
+      event = rollout.logging.global_events.last
+      expect(event.name).to eq :delete
+      expect(event.feature).to eq "chat"
+      expect(event.data).to eq({})
+      expect(event.context).to eq(actor: "alice")
+      expect(event.created_at).to be_a(Time)
+    end
+
+    it "does not record a deletion event for a missing feature" do
+      backend = RolloutMemoryBackend.new
+      rollout = described_class.new(adapter: backend, logging: { global: true })
+
+      rollout.delete(:chat)
+
+      expect(rollout.logging.global_events).to eq []
+    end
+
+    it "does not record a deletion event when logging is suppressed" do
+      backend = RolloutMemoryBackend.new
+      rollout = described_class.new(adapter: backend, logging: { global: true })
+      rollout.activate_percentage(:chat, 25)
+
+      rollout.logging.without { rollout.delete(:chat) }
+
+      expect(rollout.exists?(:chat)).to eq false
+      expect(rollout.logging.events(:chat)).to eq []
+      expect(rollout.logging.global_events.map(&:name)).to eq [:update]
+    end
+
+    it "preserves deletion behavior for adapters without event-aware deletion" do
+      backend_class = Class.new(RolloutMemoryBackend) do
+        undef_method :delete_feature_with_history
+      end
+      backend = backend_class.new
+      rollout = described_class.new(adapter: backend, logging: { global: true })
+      rollout.activate_percentage(:chat, 25)
+
+      expect { rollout.delete(:chat) }.not_to raise_error
+
+      expect(rollout.exists?(:chat)).to eq false
+      expect(rollout.logging.events(:chat)).to eq []
+      expect(rollout.logging.global_events.map(&:name)).to eq [:update]
+    end
   end
 end

data/spec/spec_helper.rb

@@ -11,6 +11,7 @@ class RolloutMemoryBackend
   def initialize
     @features = {}
     @events = Hash.new { |hash, key| hash[key] = [] }
+    @global_events = []
   end
 
   def fetch_feature(name)
@@ -47,7 +48,10 @@ class RolloutMemoryBackend
     mutation = yield fetch_feature(name)
     save_feature(mutation.fetch(:state))
     event = mutation[:event]
-    @events[name.to_s] << event if event
+    if event
+      @events[name.to_s] << event
+      @global_events << event if mutation[:global]
+    end
     mutation
   end
 
@@ -56,7 +60,7 @@ class RolloutMemoryBackend
   end
 
   def global_events(limit: nil)
-    limited_events([], limit)
+    limited_events(@global_events, limit)
   end
 
   def feature_updated_at(_name)
@@ -66,6 +70,16 @@ class RolloutMemoryBackend
     @events.delete(name.to_s)
   end
 
+  def delete_feature_with_history(name, event:, history_length:)
+    existed = feature_exists?(name)
+    delete_feature(name)
+    delete_feature_events(name)
+    if existed && event
+      @global_events << event
+      @global_events = @global_events.last(history_length)
+    end
+  end
+
   private
 
   def limited_events(events, limit)

data/spec/support/backend_contract.rb

@@ -38,6 +38,13 @@ RSpec.shared_examples "a rollout feature backend" do
     expect(backend.fetch_features([])).to eq []
   end
 
+  it "round-trips a double-precision percentage" do
+    percentage = 33.333333333333336
+    backend.save_feature(Rollout::FeatureState.new(name: :chat, percentage: percentage))
+
+    expect(backend.fetch_feature(:chat).percentage).to eq percentage
+  end
+
   it "does not share nested data with a fetched state" do
     backend.save_feature(
       Rollout::FeatureState.new(name: :chat, percentage: 0, data: { "labels" => ["a"] }),

data/spec/support/history_contract.rb

@@ -0,0 +1,174 @@
+RSpec.shared_examples "a rollout history backend" do
+  let(:rollout) { Rollout.new(adapter: backend, logging: logging) }
+  let(:logging) { true }
+  let(:feature) { :foo }
+
+  it "persists feature events oldest-to-newest" do
+    rollout.activate_percentage(feature, 50)
+    rollout.activate_percentage(feature, 75)
+    rollout.activate_group(feature, :hipsters)
+
+    events = rollout.logging.events(feature)
+    expect(events.map(&:name)).to eq %w[update update update]
+    expect(events.map { |event| event.data }).to eq [
+      { before: { percentage: 0 }, after: { percentage: 50 } },
+      { before: { percentage: 50 }, after: { percentage: 75 } },
+      { before: { groups: [] }, after: { groups: ["hipsters"] } },
+    ]
+    expect(rollout.logging.updated_at(feature)).to_not be_nil
+  end
+
+  it "does not write a history event when a double-precision percentage is unchanged" do
+    percentage = 33.333333333333336
+    rollout.activate_percentage(feature, percentage)
+
+    expect do
+      rollout.activate_percentage(feature, percentage)
+    end.not_to change { rollout.logging.events(feature).count }
+
+    expect(rollout.get(feature).percentage).to eq percentage
+  end
+
+  it "persists metadata changes and actor context" do
+    rollout.logging.with_context(actor: "alice") do
+      rollout.with_feature(feature) do |current|
+        current.percentage = 25.0
+        current.data.update(description: "New navigation")
+      end
+    end
+
+    event = rollout.logging.last_event(feature)
+    expect(event.data).to eq(
+      before: { percentage: 0, "data.description": nil },
+      after: { percentage: 25.0, "data.description": "New navigation" },
+    )
+    expect(event.context).to eq(actor: "alice")
+    expect(rollout.logging.events(feature).count).to eq 1
+  end
+
+  context "history truncation" do
+    let(:logging) { { history_length: 1 } }
+
+    it "keeps only the configured number of events" do
+      rollout.activate_percentage(feature, 25)
+      rollout.activate_percentage(feature, 30)
+
+      expect(rollout.logging.events(feature).map { |event| event.data[:after][:percentage] }).to eq [30]
+    end
+  end
+
+  context "global logs" do
+    let(:logging) { { global: true } }
+
+    it "logs changes across features oldest-to-newest" do
+      rollout.activate_percentage("foo", 25)
+      rollout.activate_percentage("bar", 30)
+      rollout.activate_percentage("baz", 40)
+
+      expect(rollout.logging.global_events.map(&:feature)).to eq %w[foo bar baz]
+      expect(rollout.logging.global_events(limit: 2).map(&:feature)).to eq %w[bar baz]
+    end
+  end
+
+  it "removes feature history on delete" do
+    rollout.activate_percentage(feature, 25)
+    rollout.delete(feature)
+
+    expect(rollout.logging.events(feature)).to eq []
+  end
+
+  it "records a global-only delete event for an existing feature" do
+    logged_rollout = Rollout.new(adapter: backend, logging: { global: true, history_length: 2 })
+    logged_rollout.activate_percentage(feature, 25)
+    logged_rollout.logging.with_context(actor: "alice") { logged_rollout.delete(feature) }
+
+    event = logged_rollout.logging.global_events.last
+    expect(event.name).to eq "delete"
+    expect(event.feature).to eq feature.to_s
+    expect(event.data).to eq({})
+    expect(event.context).to eq(actor: "alice")
+    expect(logged_rollout.logging.events(feature)).to eq []
+    expect(logged_rollout.logging.updated_at(feature)).to be_nil
+    expect(backend.feature_names.map(&:to_s)).not_to include(feature.to_s)
+  end
+
+  it "does not record deletions of missing features and honors global history length" do
+    logged_rollout = Rollout.new(adapter: backend, logging: { global: true, history_length: 1 })
+    logged_rollout.activate_percentage(feature, 25)
+    logged_rollout.delete(feature)
+    expect(logged_rollout.logging.global_events.map(&:name)).to eq ["delete"]
+
+    logged_rollout.delete(feature)
+
+    expect(logged_rollout.logging.global_events.map(&:name)).to eq ["delete"]
+  end
+
+  it "does not add a delete event when global history is disabled" do
+    logged_rollout = Rollout.new(adapter: backend, logging: { global: false })
+    logged_rollout.activate_percentage(feature, 25)
+
+    logged_rollout.delete(feature)
+
+    expect(logged_rollout.logging.global_events).to eq []
+    expect(logged_rollout.logging.events(feature)).to eq []
+  end
+
+  it "does not retain a delete event when history length is zero" do
+    logged_rollout = Rollout.new(adapter: backend, logging: { global: true, history_length: 0 })
+    logged_rollout.activate_percentage(feature, 25)
+
+    logged_rollout.delete(feature)
+
+    expect(logged_rollout.logging.global_events).to eq []
+    expect(logged_rollout.logging.events(feature)).to eq []
+  end
+
+  it "keeps feature history on clear!" do
+    rollout.activate_percentage(feature, 25)
+    rollout.clear!
+
+    expect(rollout.features).to eq []
+    expect(rollout.logging.events(feature).map { |event| event.data[:after][:percentage] }).to eq [25, 0]
+  end
+
+  it "keeps feature history when deleting without logging" do
+    rollout.activate_percentage(feature, 25)
+
+    Rollout.new(adapter: backend).delete(feature)
+
+    expect(rollout.exists?(feature)).to be_falsey
+    expect(rollout.logging.events(feature)).not_to eq []
+  end
+
+  it "logging.delete removes feature history only" do
+    rollout.activate_percentage(feature, 25)
+    rollout.logging.delete(feature)
+
+    expect(rollout.logging.events(feature)).to eq []
+    expect(rollout.logging.updated_at(feature)).to be_nil
+    expect(rollout.get(feature).percentage).to eq 25
+  end
+
+  it "adapter delete_feature preserves history" do
+    rollout.activate_percentage(feature, 25)
+    rollout.adapter.delete_feature(feature)
+
+    expect(rollout.exists?(feature)).to be_falsey
+    expect(rollout.logging.events(feature)).not_to eq []
+  end
+
+  it "returns the newest events oldest-to-newest when limited" do
+    rollout.activate_percentage(feature, 25)
+    rollout.activate_percentage(feature, 50)
+    rollout.activate_percentage(feature, 75)
+
+    expect(rollout.logging.events(feature, limit: 2).map { |event| event.data[:after][:percentage] }).to eq [50, 75]
+    expect(rollout.logging.events(feature, limit: 0)).to eq []
+    expect(rollout.logging.last_event(feature).data[:after][:percentage]).to eq 75
+  end
+
+  it "rejects an invalid history limit" do
+    expect { rollout.logging.events(feature, limit: -1) }.to raise_error(ArgumentError)
+    expect { rollout.adapter.feature_events(feature, limit: 1.5) }.to raise_error(ArgumentError)
+  end
+end

data/spec/support/rollout_backend_integration.rb

@@ -0,0 +1,77 @@
+RSpec.shared_examples "a rollout backend integration" do
+  let(:rollout) { Rollout.new(adapter: backend) }
+
+  it "persists combined feature state" do
+    rollout.with_feature(:chat) do |feature|
+      feature.percentage = 10.5
+      feature.groups = [:employees]
+      feature.users = ["123"]
+      feature.data.update(description: "New navigation", label: :beta)
+    end
+
+    feature = rollout.get(:chat)
+    expect(feature.percentage).to eq 10.5
+    expect(feature.groups).to eq [:employees]
+    expect(feature.users).to eq %w[123]
+    expect(feature.data).to eq("description" => "New navigation", "label" => "beta")
+    expect(rollout.exists?(:chat)).to eq true
+    expect(rollout.features).to eq [:chat]
+  end
+
+  it "persists metadata that contains pipes" do
+    rollout.activate_user(:chat, 8)
+    rollout.set_feature_data(:chat, "|call||text|" => "a|bunch|of|stuff")
+
+    expect(rollout.get(:chat).data).to include("|call||text|" => "a|bunch|of|stuff")
+    expect(rollout.get(:chat).users).to eq %w[8]
+  end
+
+  it "clears users, groups, percentage, and data on deactivate" do
+    rollout.activate_user(:chat, 42)
+    rollout.activate_group(:chat, :employees)
+    rollout.activate_percentage(:chat, 50)
+    rollout.set_feature_data(:chat, description: "foo")
+
+    rollout.deactivate(:chat)
+
+    expect(rollout.features).to eq [:chat]
+    expect(rollout.get(:chat).to_hash).to eq(
+      percentage: 0,
+      users: [],
+      groups: [],
+      data: {},
+    )
+  end
+
+  it "keeps users, groups, and data on deactivate_percentage" do
+    rollout.activate_user(:chat, 42)
+    rollout.activate_group(:chat, :employees)
+    rollout.activate_percentage(:chat, 50)
+    rollout.set_feature_data(:chat, description: "foo")
+
+    rollout.deactivate_percentage(:chat)
+
+    expect(rollout.get(:chat).percentage).to eq 0
+    expect(rollout.get(:chat).users).to eq %w[42]
+    expect(rollout.get(:chat).groups).to eq [:employees]
+    expect(rollout.get(:chat).data).to eq("description" => "foo")
+  end
+
+  it "removes the feature on delete" do
+    rollout.activate(:chat)
+    rollout.delete(:chat)
+
+    expect(rollout.features).to eq []
+    expect(rollout.exists?(:chat)).to eq false
+    expect(rollout.get(:chat).percentage).to eq 0
+  end
+
+  it "clears persisted features" do
+    rollout.activate(:signup)
+    rollout.activate(:chat)
+    rollout.clear!
+
+    expect(rollout.features).to eq []
+    expect(rollout.exists?(:chat)).to eq false
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rollout
 version: !ruby/object:Gem::Version
-  version: 3.1.0
+  version: 3.2.0
 platform: ruby
 authors:
 - James Golick
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-14 00:00:00.000000000 Z
+date: 2026-10-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: observer
@@ -154,6 +154,8 @@ files:
 - spec/rollout_spec.rb
 - spec/spec_helper.rb
 - spec/support/backend_contract.rb
+- spec/support/history_contract.rb
+- spec/support/rollout_backend_integration.rb
 homepage: https://github.com/FetLife/rollout
 licenses:
 - MIT