rollout 2.6.2 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: fbabd7f8b0651b97e5ebe8a2bdc4b990c810e162
-  data.tar.gz: 4b5f9ff84fbcbbbef81e05c885b67cf699309e47
+SHA256:
+  metadata.gz: f825c30d598b5b2b194b97b0371bbd1ceda8f341458a64b1a601941ee11580eb
+  data.tar.gz: '038f689c1fe1f5eb3aba0e4eaadcc80da24f320b863a4fffecf6ca3fe4355ba4'
 SHA512:
-  metadata.gz: 1a87eb9c45aef7a24868361e04f5bdb53fb55ab2949fb411a3f39198ddac4085b63d05a730f06820feaed797327772f4bf95fc783f8f5d5c55dcf24379c51d99
-  data.tar.gz: 7c7e3b692bf11cbcebd99ad2a8d3e4db41a2b233ac5ce5ae0551c15f522e93d0f474e3fc5f868b3fedd76d1d8fb8751d178ac39ef3721b10e9a99b2499e3ec32
+  metadata.gz: 2dd85351ad0860f8a2bd86b8b018fad5ed6175751f3018fcc20cad2e96fed7df38de74fc04205207a6de627b168fa0dd04575bf534aa461ed6d4d9b74d36d013
+  data.tar.gz: ab692a6ae7d929d52df99b7d9de6f0ca41a018c72f5cddc05b3fa37051418ca476b7b89af862c77353e8a82646d0adfa8832a04a8c96b3941a6d865da69626d0

data/.github/workflows/release.yml

@@ -3,44 +3,68 @@ name: Release
 on:
   push:
     tags:
-      - 'v*'
+      - 'rollout/v*'
+      - 'rollout-redis-adapter/v*'
+
+permissions:
+  contents: write
+  id-token: write
 
 jobs:
-  release:
+  publish:
     runs-on: ubuntu-latest
-    services:
-      redis:
-        image: redis:7-alpine
-        ports:
-          - 6379:6379
-        options: >-
-          --health-cmd "redis-cli ping"
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
+    outputs:
+      name: ${{ steps.package.outputs.name }}
+      version: ${{ steps.package.outputs.version }}
+      previous_tag: ${{ steps.package.outputs.previous_tag }}
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
       - name: Setup Ruby
         uses: ruby/setup-ruby@v1
         with:
-          bundler-cache: true
-      - name: Run tests
-        run: bundle exec rspec 
+          ruby-version: '3.3'
+      - name: Select package
+        id: package
+        run: |
+          case "$GITHUB_REF_NAME" in
+            rollout/v*) name=rollout; directory=. ;;
+            rollout-redis-adapter/v*) name=rollout-redis-adapter; directory=rollout-redis-adapter ;;
+            *) echo "Unexpected tag $GITHUB_REF_NAME" >&2; exit 1 ;;
+          esac
+          version="${GITHUB_REF_NAME##*/v}"
+          spec_version=$(ruby -e 'puts Gem::Specification.load(ARGV[0]).version' "$directory/$name.gemspec")
+          if [ "$spec_version" != "$version" ]; then
+            echo "Tag version $version does not match gemspec $spec_version" >&2
+            exit 1
+          fi
+          previous_tag=$(git tag --list "$name/v*" --sort=-version:refname | awk -v current="$GITHUB_REF_NAME" '$0 != current { print; exit }')
+          previous_tag=${previous_tag:-v2.6.2}
+          echo "name=$name" >> "$GITHUB_OUTPUT"
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          echo "directory=$directory" >> "$GITHUB_OUTPUT"
+          echo "previous_tag=$previous_tag" >> "$GITHUB_OUTPUT"
+      - name: Build selected gem
+        working-directory: ${{ steps.package.outputs.directory }}
+        run: gem build "${{ steps.package.outputs.name }}.gemspec"
+      - name: Configure RubyGems credentials
+        uses: rubygems/configure-rubygems-credentials@v2.1.0
+      - name: Publish selected gem
+        working-directory: ${{ steps.package.outputs.directory }}
+        run: gem push "${{ steps.package.outputs.name }}-${{ steps.package.outputs.version }}.gem"
+
+  github-release:
+    needs: publish
+    runs-on: ubuntu-latest
+    steps:
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v2
         with:
           tag_name: ${{ github.ref }}
-          name: ${{ github.ref_name }}
+          name: ${{ needs.publish.outputs.name }} ${{ needs.publish.outputs.version }}
           generate_release_notes: true
+          previous_tag: ${{ needs.publish.outputs.previous_tag }}
           draft: false
-          prerelease: false 
-      - name: Set up RubyGems credentials
-        env:
-          RUBYGEMS_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}
-        run: |
-          mkdir -p ~/.gem
-          echo ":rubygems_api_key: $RUBYGEMS_API_KEY" > ~/.gem/credentials
-          chmod 0600 ~/.gem/credentials
-      - name: Release to RubyGems
-        run: bundle exec rake release
+          prerelease: false

data/.github/workflows/test.yml

@@ -4,13 +4,41 @@ on:
   push:
     branches:
       - master
+      - v3
   pull_request:
-    branches:
-      - master
+
 
 jobs:
-  test:
+  core:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['3.3', '3.2', '3.1', '3.0', '2.7', '2.6', '2.5', '2.4']
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: true
+      - name: Run core tests
+        run: |
+          mkdir -p test_results
+          bundle exec rspec spec --format progress --format RspecJunitFormatter --out test_results/rspec.xml
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v5
+        with:
+          name: core-test-results-${{ matrix.ruby-version }}
+          path: test_results/rspec.xml
+          retention-days: 30
+
+  redis:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['3.3', '3.2', '3.1', '3.0', '2.7', '2.6', '2.5', '2.4']
     services:
       redis:
         image: redis:7-alpine
@@ -23,10 +51,22 @@ jobs:
           --health-retries 5
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
       - name: Setup Ruby
         uses: ruby/setup-ruby@v1
         with:
+          ruby-version: ${{ matrix.ruby-version }}
+          working-directory: rollout-redis-adapter
           bundler-cache: true
-      - name: Run tests
-        run: bundle exec rspec 
+      - name: Run Redis adapter tests
+        working-directory: rollout-redis-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: redis-test-results-${{ matrix.ruby-version }}
+          path: rollout-redis-adapter/test_results/rspec.xml
+          retention-days: 30

data/.gitignore

@@ -18,7 +18,9 @@ coverage
 rdoc
 pkg
 *.gem
+Gemfile.lock
 gemfiles/*.lock
+test_results
 .rspec_status
 .bundle/config
 /vendor

data/README.md

@@ -1,16 +1,25 @@
 # rollout
 
-Fast feature flags based on Redis.
+Fast feature flags.
+
+Upgrading from Rollout 2? Follow the [Rollout 3 upgrade guide](docs/upgrading-to-v3.md)
+before updating your dependencies.
 
 [![Gem Version](https://badge.fury.io/rb/rollout.svg)](https://badge.fury.io/rb/rollout)
-[![CircleCI](https://circleci.com/gh/fetlife/rollout.svg?style=svg)](https://circleci.com/gh/fetlife/rollout)
+[![CI](https://github.com/fetlife/rollout/actions/workflows/test.yml/badge.svg)](https://github.com/fetlife/rollout/actions/workflows/test.yml)
 [![Code Climate](https://codeclimate.com/github/FetLife/rollout/badges/gpa.svg)](https://codeclimate.com/github/FetLife/rollout)
 [![Test Coverage](https://codeclimate.com/github/FetLife/rollout/badges/coverage.svg)](https://codeclimate.com/github/FetLife/rollout/coverage)
 
 ## Install it
 
 ```bash
-gem install rollout
+gem install rollout -v '~> 3.1'
+gem install rollout-redis-adapter -v '~> 0.1'
+```
+
+```ruby
+gem "rollout", "~> 3.1"
+gem "rollout-redis-adapter", "~> 0.1"
 ```
 
 ## How it works
@@ -18,17 +27,12 @@ gem install rollout
 Initialize a rollout object. I assign it to a global var.
 
 ```ruby
-require 'redis'
+require "redis"
+require "rollout"
+require "rollout/adapters/redis"
 
 $redis = Redis.new
-$rollout = Rollout.new($redis)
-```
-
-or even simpler
-
-```ruby
-require 'redis'
-$rollout = Rollout.new($redis) # Will use REDIS_URL env var or default redis url
+$rollout = Rollout.new(adapter: Rollout::Adapters::Redis.new($redis))
 ```
 
 
@@ -109,11 +113,12 @@ $rollout.activate_percentage(:chat, 20)
 The algorithm for determining which users get let in is this:
 
 ```ruby
-CRC32(user.id) < (2**32 - 1) / 100.0 * percentage
+Zlib.crc32(user.id.to_s) < (2**32 - 1) / 100.0 * percentage
 ```
 
-So, for 20%, users 0, 1, 10, 11, 20, 21, etc would be allowed in. Those users
-would remain in as the percentage increases.
+The result is deterministic: the same user is always in or out at a given
+percentage, and users already included remain included as the percentage
+increases.
 
 Deactivate all percentages like this:
 
@@ -128,7 +133,10 @@ In some cases you might want to have a feature activated for a random set of
 users. It can come specially handy when using Rollout for split tests.
 
 ```ruby
-$rollout = Rollout.new($redis, randomize_percentage: true)
+$rollout = Rollout.new(
+  adapter: Rollout::Adapters::Redis.new($redis),
+  randomize_percentage: true,
+)
 ```
 
 When on `randomize_percentage` will make sure that 50% of users for feature A
@@ -166,8 +174,9 @@ failure detection code.
 You can inspect the state of your feature using:
 
 ```ruby
->> $rollout.get(:chat)
-=> #<Rollout::Feature:0x00007f99fa4ec528 @data={}, @groups=[:caretakers], @name=:chat, @options={}, @percentage=0.05, @users=["1"]>
+feature = $rollout.get(:chat)
+feature.to_hash
+# => { percentage: 5.0, groups: [:caretakers], users: ["1"], data: {} }
 ```
 
 ## Namespacing
@@ -180,18 +189,32 @@ environments by using the
 [redis-namespace](https://github.com/resque/redis-namespace) gem.
 
 ```ruby
+gem "redis-namespace"
+```
+
+```ruby
+require "redis"
+require "redis/namespace"
+require "rollout"
+require "rollout/adapters/redis"
+
 $ns = Redis::Namespace.new(Rails.env, redis: $redis)
-$rollout = Rollout.new($ns)
+$rollout = Rollout.new(adapter: Rollout::Adapters::Redis.new($ns))
 $rollout.activate_group(:chat, :all)
 ```
 
-This example would use the "development:feature:chat:groups" key.
+This example stores the chat feature at `development:feature:chat` when
+`Rails.env` is `"development"`.
 
 ## Frontend / UI
 
 * [rollout-ui](https://github.com/fetlife/rollout-ui)
 * [Rollout-Dashboard](https://github.com/fiverr/rollout_dashboard/)
 
+These integrations may not yet support Rollout 3. Use a version compatible with
+the Rollout release you install. If you depend on rollout-ui, wait for a
+Rollout 3-compatible UI release before upgrading production.
+
 ## Implementations in other languages
 
 *   Python: https://github.com/asenchi/proclaim
@@ -207,13 +230,53 @@ This example would use the "development:feature:chat:groups" key.
 *   Eric Rafaloff - Maintainer - https://github.com/EricR
 
 
+## Testing
+
+Install dependencies first. Core and the Redis adapter have separate Gemfiles:
+
+```bash
+bundle install
+bundle install --gemfile=rollout-redis-adapter/Gemfile
+```
+
+Core tests do not need Redis:
+
+```bash
+bundle exec rake spec
+```
+
+Redis adapter tests flush database 7 by default. Use a disposable instance,
+not a shared or production Redis. Start Redis in a separate terminal:
+
+```bash
+docker run --rm -p 6379:6379 redis:7-alpine
+```
+
+Then run:
+
+```bash
+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.
+
 ## Releasing
 
-1. Bump version: `rake version:patch` (or `minor`/`major`)
-2. Commit and tag: `git commit -am "Bump version" && git tag v0.7.3`
-3. Push: `git push origin master --tags`
+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.
+- Push the tag with `git push origin <tag>`. CI publishes the selected gem and
+  creates its GitHub release.
 
-The GitHub Actions workflow will automatically publish to RubyGems when tags are pushed.
+Use package-prefixed tags, not `vX.Y.Z`. Publish core first when the adapter
+depends on a new core version.
 
 ## Copyright
 

data/Rakefile

@@ -1,9 +1,22 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
-RSpec::Core::RakeTask.new(:spec)
+RSpec::Core::RakeTask.new(:spec) do |task|
+  task.pattern = "spec/**/*_spec.rb"
+end
+
+namespace :spec do
+  desc "Run Redis adapter tests"
+  task :redis do
+    gemfile = File.expand_path("rollout-redis-adapter/Gemfile", __dir__)
+    Dir.chdir("rollout-redis-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

@@ -0,0 +1,101 @@
+# Upgrading to Rollout 3
+
+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.
+
+## 1. Update dependencies
+
+Add the adapter gem next to `rollout`:
+
+```ruby
+gem "rollout", "~> 3.1"
+gem "rollout-redis-adapter", "~> 0.1"
+```
+
+Use compatible releases of both gems. The Redis adapter is versioned
+independently of core. Rollout `3.0.0` used `backend:` and
+`Rollout::Redis::Backend`; `3.1.0` uses `adapter:` and
+`Rollout::Adapters::Redis`. If you use
+[rollout-ui](https://github.com/fetlife/rollout-ui), wait for a Rollout
+3-compatible UI release before upgrading production.
+
+## 2. Update requires and initialization
+
+```ruby
+# Before
+require "redis"
+require "rollout"
+
+$redis = Redis.new
+$rollout = Rollout.new(
+  $redis,
+  randomize_percentage: true,
+  logging: { history_length: 100, global: true },
+)
+```
+
+```ruby
+# After
+require "redis"
+require "rollout"
+require "rollout/adapters/redis"
+
+$redis = Redis.new
+$rollout = Rollout.new(
+  adapter: Rollout::Adapters::Redis.new($redis),
+  randomize_percentage: true,
+  logging: { history_length: 100, global: true },
+)
+```
+
+Pass the same Redis client, database, and namespace you already use. Repeat
+this change at every initialization site, including jobs, scripts, and
+consoles.
+
+`redis-namespace` still works:
+
+```ruby
+$ns = Redis::Namespace.new(Rails.env, redis: $redis)
+$rollout = Rollout.new(adapter: Rollout::Adapters::Redis.new($ns))
+```
+
+## 3. Breaking changes
+
+| Area | Breaking change | Required action |
+| --- | --- | --- |
+| Storage configuration | `Rollout.new(redis, options)` now requires `adapter:`. | Wrap the existing client in `Rollout::Adapters::Redis.new(redis)` and pass options as keywords. |
+| Storage access | `rollout.storage` is removed. `rollout.adapter` returns an adapter, not the Redis client. | Keep your own Redis client reference if application code needs direct access. |
+| Logging storage | `logging: { storage: other_redis }` is no longer supported. The Redis backend stores features and history through the same client. | Applications using separate history storage cannot preserve that setup with the current adapter. Removing the option does not migrate existing history. |
+| Custom logging | `Logger#log` and `Logger#update` are removed. Built-in logging is no longer an observer. | Use Rollout mutations and `logging.with_context` rather than calling those methods directly. |
+| Feature construction | `Feature.new(name, rollout:, state: payload)` no longer accepts a name argument or raw Redis payload. | Prefer `rollout.get(name)`. Direct construction requires `Feature.new(state: feature_state, rollout: rollout, options: rollout.options)`. |
+| Feature serialization | `feature.serialize` is removed. | Use `feature.to_feature_state` for a backend-neutral snapshot. Redis encoding belongs to `Rollout::Redis::Codec`. |
+| Feature metadata | Metadata is canonicalized to JSON. Symbol keys and values become strings. Values such as `Time`, `Date`, and `BigDecimal` persist as their JSON representations, not as original Ruby objects. | No data migration is required. JSON-serializable writes continue to work. |
+| History decoding | `Logging::Event.from_raw` is removed. | Decode persisted Redis members with `Rollout::Redis::Codec.decode_event(value, score)`. |
+
+## 4. History and lifecycle
+
+History reads can request a bound. `limit` is the newest N events, returned
+oldest-to-newest. Omit `limit` to read the full retained history. `0` returns
+no events.
+
+```ruby
+rollout.logging.events(:chat, limit: 10)
+rollout.logging.global_events(limit: 10)
+rollout.logging.last_event(:chat)
+```
+
+`last_event` reads one persisted member. It does not load the complete
+history.
+
+| Operation | Feature state | Per-feature history | Global history |
+| --- | --- | --- | --- |
+| `delete`, logging enabled | Removed | Removed | Retained |
+| `delete`, logging disabled | Removed | Retained | Retained |
+| `logging.delete` | Unchanged | Removed | Retained |
+| `clear!` | Removed | Retained | Retained |
+
+`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
+when it was already empty.

data/lib/rollout/feature.rb

@@ -1,28 +1,27 @@
 # frozen_string_literal: true
 
+require 'rollout/feature_state'
+
 class Rollout
   class Feature
     attr_accessor :groups, :users, :percentage, :data
     attr_reader :name, :options
 
-    def initialize(name, rollout:, state: nil, options: {})
-      @name = name
+    def initialize(state:, rollout:, options: {}, name: nil)
       @rollout = rollout
       @options = options
-
-      if state
-        raw_percentage, raw_users, raw_groups, raw_data = state.split('|', 4)
-        @percentage = raw_percentage.to_f
-        @users = users_from_string(raw_users)
-        @groups = groups_from_string(raw_groups)
-        @data = raw_data.nil? || raw_data.strip.empty? ? {} : JSON.parse(raw_data)
-      else
-        clear
-      end
+      @name = name.nil? ? state.name.to_sym : name
+      assign_state(state)
     end
 
-    def serialize
-      "#{@percentage}|#{@users.to_a.join(',')}|#{@groups.to_a.join(',')}|#{serialize_data}"
+    def to_feature_state
+      FeatureState.new(
+        name: @name,
+        percentage: @percentage,
+        users: Array(@users),
+        groups: Array(@groups),
+        data: @data,
+      )
     end
 
     def add_user(user)
@@ -43,10 +42,7 @@ class Rollout
     end
 
     def clear
-      @groups = groups_from_string('')
-      @users = users_from_string('')
-      @percentage = 0
-      @data = {}
+      assign_state(FeatureState.new(name: @name, percentage: 0))
     end
 
     def active?(user)
@@ -77,12 +73,21 @@ class Rollout
       c = self.clone
       c.instance_variable_set('@rollout', nil)
       c = Marshal.load(Marshal.dump(c))
-      c.instance_variable_set('@rollot', @rollout)
+      c.instance_variable_set('@rollout', @rollout)
       c
     end
 
     private
 
+    def assign_state(state)
+      state = state.deep_clone
+
+      @percentage = state.percentage
+      @users = users_from_array(state.users)
+      @groups = groups_from_array(state.groups)
+      @data = state.data
+    end
+
     def user_id(user)
       if user.is_a?(Integer) || user.is_a?(String)
         user.to_s
@@ -113,14 +118,8 @@ class Rollout
       end
     end
 
-    def serialize_data
-      return '' unless @data.is_a? Hash
-
-      @data.to_json
-    end
-
-    def users_from_string(raw_users)
-      users = (raw_users || '').split(',').map(&:to_s)
+    def users_from_array(users)
+      users = Array(users).map(&:to_s)
       if @options[:use_sets]
         users.to_set
       else
@@ -128,8 +127,8 @@ class Rollout
       end
     end
 
-    def groups_from_string(raw_groups)
-      groups = (raw_groups || '').split(',').map(&:to_sym)
+    def groups_from_array(groups)
+      groups = Array(groups).map(&:to_sym)
       if @options[:use_sets]
         groups.to_set
       else

data/lib/rollout/feature_state.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'json'
+
+class Rollout
+  class FeatureState
+    attr_reader :name, :percentage, :users, :groups, :data
+
+    def initialize(name:, percentage:, users: [], groups: [], data: {})
+      raise ArgumentError, "data must be a Hash" unless data.is_a?(Hash)
+
+      @name = name.to_s.dup
+      @percentage = percentage.to_f
+      @users = Array(users).map { |user| user.to_s.dup }
+      @groups = Array(groups).map { |group| group.to_s.dup }
+      @data = canonicalize_data(data)
+    end
+
+    def ==(other)
+      other.is_a?(FeatureState) &&
+        name == other.name &&
+        percentage == other.percentage &&
+        users == other.users &&
+        groups == other.groups &&
+        data == other.data
+    end
+
+    def deep_clone
+      self.class.new(
+        name: name,
+        percentage: percentage,
+        users: users,
+        groups: groups,
+        data: data,
+      )
+    end
+
+    private
+
+    def canonicalize_data(data)
+      JSON.parse(data.to_json)
+    end
+  end
+end