star_gates 0.0.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91627ddc25a266e8584724a1e1973799dc693e883f4b5d01dfe33cb1ccbd6fbf
-  data.tar.gz: be8eaf8ff34249e3cf355c3fa8fd1159625aee1e23be009ce9664d644f837a6d
+  metadata.gz: 9150966ca03ffe47ce938c669d38ab3291e25b6b7aaea9560e89099ec255a65d
+  data.tar.gz: 0454b43be544e3c50026811f5d44ec3a28903c4ff824fcf3b855aaf70a733aba
 SHA512:
-  metadata.gz: 1ff36a75a319ed7646b3eab22a9b256078044f5144c2ab7eb62f8b052504a800565ab13c3e9c5a7010428df585cbc974f9d4b0c5eb1d8fefa20049cc6b61462b
-  data.tar.gz: df5408c183aba188434a0f74b0b330036b1951786fa3abd78b80b4eda7e7151b1270e17eaba39fb27f8422efeb25392ec0f575805c18f627053ed981056f8184
+  metadata.gz: 4d7802feb0b5ebc3aefcd585224cfd5dda9f95e9e8f23ee5653a087f5326d14764ce7e6a06d16ca01cafd60570325c910cb776464b2abce14b2ef05b0a202407
+  data.tar.gz: 3e57ca2506afe07616e9c884f1f74228c2f380601a0ca4779b311a422aa0c215d228835e9160b0689db744ec788252b752f5133703992063a06c6c7db87254d7

data/.dictate.toml

@@ -0,0 +1,19 @@
+[decree.supreme]
+trailing_whitespace = "deny"
+tabs_vs_spaces = "spaces"
+tab_width = 2
+final_newline = "require"
+line_endings = "lf"
+blank_line_whitespace = "deny"
+
+[decree.supreme.ignore.tab-character]
+filenames = ["Makefile", "GNUmakefile", "makefile"]
+extensions = ["md", "mdx", "tsv"]
+
+[decree.ruby]
+max_line_length = 120
+max_lines = 400
+ignore_comments = true
+ignore_blank_lines = true
+method_visibility_order = ["public", "protected", "private"]
+comment_spacing = true

data/.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: check-json
+      - id: check-case-conflict
+
+  - repo: local
+    hooks:
+      - id: dictator
+        name: dictator
+        entry: dictator lint
+        language: system
+        types: [text]
+        require_serial: true

data/CHANGELOG.md

@@ -1,5 +1,62 @@
-## [Unreleased]
+# Changelog
 
-## [0.1.0] - 2025-07-08
+## Unreleased
 
-- Initial release
+## 0.2.0 (2026-10-28)
+
+### Changed
+
+- Use explicit rollout `key:` and `groups:` context. Group predicates receive the
+  full context; simulation, debugging, and scenario analysis use key-based inputs
+  and results. Remove user-specific helpers and telemetry labels.
+- Require Ruby 4.0 or newer.
+- Require StateMachines 0.202.0 or newer.
+- Change the license to BSD-3-Clause.
+- Use ActiveSupport duration helpers without overriding Rails behavior.
+- Preserve fractional seconds in circuit cooldowns and failure windows.
+- Consolidate documentation and remove generated repository artifacts, keeping the space-fleet examples.
+- Move demos into the Rails dummy app and rewrite ship systems as StarGates gates.
+- Run gem and Rails integration tests separately, with explicit test discovery and Rails setup.
+- Use the Dictator GitHub Action and a project decree for structural linting.
+- Run both test suites with padded_cell and Minitest 6.
+
+### Fixed
+
+- Keep percentage rollout cohorts stable across workers and restarts with CRC32
+  key buckets. Upgrading reassigns cohorts previously based on Ruby's
+  process-randomized string hashes.
+- Correct dummy-app feature routing, persistent feature transitions, and circuit statistics.
+- Make weather demo failures explicit instead of random.
+
+### Added
+
+- Boolean flags with environment, configuration, and runtime overrides.
+- Flag status, metadata, and debugging helpers.
+
+## 0.1.0 (2025-10-30)
+
+### Security
+
+- Use safe YAML loading for configuration files.
+
+### Fixed
+
+- Correct percentage-string parsing for feature rollouts.
+- Remove dead time-parsing code.
+
+### Added
+
+- ChronoMachines retry policies with exponential backoff and jitter.
+- Circuit retry instrumentation.
+- Feature state transitions, rollout targeting, and automatic circuit-triggered rollback.
+- Transition history and introspection.
+- Regression coverage for configuration security, rollouts, concurrency, and retries.
+
+### Changed
+
+- Use immutable `Data.define` mock users instead of `OpenStruct`.
+- Use concurrent-ruby primitives for thread-safe registries and transition history.
+
+## 0.0.0
+
+- Internal development version.

data/LICENSE.txt

@@ -1,21 +1,28 @@
-The MIT License (MIT)
+BSD 3-Clause License
 
 Copyright (c) 2025 Abdelkader Boudih
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
 
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -1,39 +1,205 @@
 # StarGates
 
-TODO: Delete this and the text below, and describe your gem
+[![Gem Version](https://badge.fury.io/rb/star_gates.svg)](https://badge.fury.io/rb/star_gates)
+[![CI](https://github.com/seuros/star_gates/actions/workflows/ci.yml/badge.svg)](https://github.com/seuros/star_gates/actions/workflows/ci.yml)
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/star_gates`. To experiment with that code, run `bin/console` for an interactive prompt.
+Feature flags, gradual rollouts, and circuit-protected execution for Ruby.
+StarGates uses StateMachines for feature transitions, BreakerMachines for circuit
+protection, and ChronoMachines for retries.
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+Requires **Ruby 4.0+** and **ActiveSupport 8.1.1+**. Rails is optional.
 
-Install the gem and add to the application's Gemfile by executing:
+```ruby
+gem 'star_gates'
+```
+
+```sh
+bundle install
+```
+
+## Boolean flags
+
+```ruby
+require 'star_gates'
+
+StarGates.flags.configuration = { copilot: true }
+StarGates.flags.enabled?(:copilot)
+StarGates.flags.enable(:preview, metadata: { reason: 'testing' })
+StarGates.flags.disable(:preview)
+StarGates.flags.debug(:preview)
+StarGates.flags.reset!
+```
+
+Precedence: nonblank `FEATURE_<NAME>` environment variable, boolean configuration,
+runtime override, then `false`. Names are case-insensitive; dashes become underscores.
+Truthy strings are `true`, `1`, `yes`, and `on` (case-insensitive).
+
+For Rails, keep defaults explicit and resolve them lazily:
+
+```ruby
+# config/initializers/feature_flags.rb
+Rails.application.config.x.feature_flags = { copilot: true }
+StarGates.flags.configuration = -> { Rails.application.config.x.feature_flags }
+```
+
+`StarGates::Flags.new(env: {}, configuration: {})` creates an isolated registry.
+`all`, `enabled_flags`, `summary`, and `flag_status` expose values and their sources.
+Runtime transitions reuse `StarGates::Feature`; changes and metadata are process-local,
+not persisted or synchronized across workers. `reset!` clears both runtime state and
+metadata, not environment/configuration. `StarGates.reset!` resets gates separately.
+
+## Gates and rollouts
+
+```ruby
+StarGates.define do
+  gate :payments do
+    feature rollout: 25.percent
+    circuit threshold: 3, within: 1.minute, reset_after: 30.seconds
+
+    run { |context| PaymentAPI.charge(context[:amount]) }
+    fallback { |context| LegacyPaymentAPI.charge(context[:amount]) }
+  end
+end
+
+gate = StarGates[:payments]
+gate.feature.rollout_canary
+gate.call(key: 'account:42', amount: 100)
+```
+
+Features start disabled. Use `rollout_canary` for percentage/group targeting,
+`enable` for full rollout, and `disable` to turn a feature off. Pass a stable
+string or integer `key:` for percentage targeting, such as an account, resident,
+or device identifier.
+
+Percentage targeting stays consistent across workers and restarts. Increasing
+the rollout percentage retains keys already included.
+
+For group targeting, pass `groups: [:beta]` to match `feature group: :beta`.
+A predicate such as `feature group: ->(context) { context[:region] == 'eu' }`
+receives the full context passed to the gate.
+
+When a circuit opens, its feature rolls back from enabled to canary, or from canary
+to disabled. Gates use their fallback when the feature is unavailable or execution
+fails. Rails duration helpers retain their normal behavior, including fractional
+seconds such as `0.5.seconds`.
+
+### Retries
+
+Pass `retry_config` to a gate's `circuit` declaration:
+
+```ruby
+circuit threshold: 5,
+        within: 1.minute,
+        retry_config: {
+          max_attempts: 3,
+          base_delay: 0.1,
+          multiplier: 2,
+          max_delay: 5
+        }
+```
+
+Retries are opt-in and use ChronoMachines.
+
+## Rails
+
+Define gates in an initializer and call them from controllers or services:
+
+```ruby
+class PaymentsController < ApplicationController
+  def create
+    result = StarGates[:payments].call(key: "account:#{current_account.id}", amount: params[:amount])
+    render json: result
+  end
+end
+```
+
+The Rails integration fixture lives in `test/dummy/` and uses the root Gemfile.
+
+## Instrumentation
+
+StarGates emits events through `ActiveSupport::Notifications`:
+
+```ruby
+ActiveSupport::Notifications.subscribe('star_gates.circuit.auto_rollback') do |*args|
+  event = ActiveSupport::Notifications::Event.new(*args)
+  Rails.logger.warn(event.payload)
+end
+```
+
+Circuit events include `circuit.auto_rollback`, `circuit.half_open`,
+`circuit.recovered`, and `circuit.retry`, prefixed with `star_gates.`.
 
-```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+## Examples
+
+### Space fleet
+
+All demos live in `test/dummy/`. The fleet uses real `StarGates::Gate` instances
+for feature rollout, circuit protection, automatic rollback, and fallbacks.
+BreakerMachines is the underlying circuit engine, not a separate ship API.
+
+- [Spaceship](test/dummy/app/models/spaceship.rb): warp drive, fusion reactor, and navigation circuits.
+- [Spaceflight systems](test/dummy/app/models/spaceflight_systems.rb): simulated ship subsystems.
+- [Ship hierarchy](test/dummy/app/models/base_ship.rb): shared systems for the fleet.
+- [Corellian freighter](test/dummy/app/models/corellian_freighter.rb): specialized ship behavior.
+- [RMNS Atlas Monkey](test/dummy/app/models/rmns_atlas_monkey.rb): the Universal Commentary Engine.
+
+Run the fleet demo without starting Rails:
+
+```sh
+bundle exec ruby test/dummy/demos/space_fleet.rb
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+It demonstrates disabled-system fallback, pilot-only canary access, full rollout,
+hardware failures opening a circuit, automatic feature rollback, and explicit
+operator-approved recovery. Each ship's gates have independent state.
+
+```ruby
+require_relative 'test/dummy/app/models/spaceship'
 
-```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+ship = Spaceship.new('SG Atlas', 'SG-1')
+warp = ship.gate(:warp_drive) # A StarGates::Gate, with a feature and a circuit.
+warp.feature.rollout_canary
+ship.engage_warp('Alpha Centauri', key: 'crew:1', groups: [:pilots])
 ```
 
-## Usage
+### Application examples
 
-TODO: Write usage instructions here
+- [Payment feature](test/dummy/demos/payment_feature.rb): state-specific feature behavior.
+- [Transition history](test/dummy/demos/transition_demo.rb): recorded feature transitions.
+- [Introspection](test/dummy/demos/introspection_demo.rb): status, analytics, and context simulation.
+- [Application payment feature](test/dummy/demos/application_payment_feature.rb): application-level features.
+- [JSON-RPC controller](test/dummy/demos/jsonrpc_rails_controller.rb): optional JSON-RPC integration.
+
+Run standalone examples from the repository root:
+
+```sh
+bundle exec ruby test/dummy/demos/payment_feature.rb
+```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+```sh
+bin/setup
+bundle exec rake test
+bundle exec rake test:rails
+dictator lint .
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+Tests run with padded_cell and Minitest 6. Gem tests and Rails integration tests
+run in separate processes. `bundle exec rake` runs both suites. To select gem tests
+directly or pass runner options:
 
-## Contributing
+```sh
+bundle exec padded_cell test/gate_test.rb
+bundle exec rake test TESTOPTS='-j 4 --seed 1234'
+```
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/star_gates.
+See [CHANGELOG.md](CHANGELOG.md) for release history.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+[BSD-3-Clause](LICENSE.txt).
+
+> In space, nobody can hear your feature flags fail, but they'll notice when your fleet survives.

data/Rakefile

@@ -1,8 +1,18 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "minitest/test_task"
+require 'bundler/gem_tasks'
+require 'shellwords'
 
-Minitest::TestTask.create
+desc 'Run gem tests with padded_cell'
+task :test do
+  sh 'padded_cell', 'test/*_test.rb', *Shellwords.split(ENV.fetch('TESTOPTS', ''))
+end
 
-task default: :test
+namespace :test do
+  desc 'Run Rails integration tests with padded_cell'
+  task :rails do
+    sh 'padded_cell', 'test/dummy/test', *Shellwords.split(ENV.fetch('TESTOPTS', ''))
+  end
+end
+
+task default: [:test, 'test:rails']

data/lib/star_gates/adapters/base_adapter.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module StarGates
+  module Adapters
+    class BaseAdapter
+      def initialize(config = {})
+        @config = config
+      end
+
+      # Persistence operations
+      def store(key, value)
+        raise NotImplementedError, 'Subclasses must implement #store'
+      end
+
+      def fetch(key)
+        raise NotImplementedError, 'Subclasses must implement #fetch'
+      end
+
+      def delete(key)
+        raise NotImplementedError, 'Subclasses must implement #delete'
+      end
+
+      def exists?(key)
+        raise NotImplementedError, 'Subclasses must implement #exists?'
+      end
+
+      # Caching operations
+      def cache_fetch(key, expires_in: nil, &block)
+        if exists?(key)
+          fetch(key)
+        elsif block_given?
+          value = block.call
+          store(key, value) if value
+          value
+        end
+      end
+
+      def cache_write(key, value, expires_in: nil)
+        store(key, value)
+      end
+
+      def cache_delete(key)
+        delete(key)
+      end
+
+      # Messaging operations
+      def publish(topic, message)
+        # Default no-op implementation
+      end
+
+      def subscribe(topic, &)
+        # Default no-op implementation
+      end
+
+      # Health check
+      def healthy?
+        true
+      end
+
+      protected
+
+      attr_reader :config
+    end
+  end
+end

data/lib/star_gates/adapters/memory_adapter.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative 'base_adapter'
+require 'concurrent'
+
+module StarGates
+  module Adapters
+    class MemoryAdapter < BaseAdapter
+      def initialize(config = {})
+        super
+        @storage = Concurrent::Hash.new
+        @subscribers = Concurrent::Hash.new { |h, k| h[k] = Concurrent::Array.new }
+        @mutex = Mutex.new
+      end
+
+      def store(key, value)
+        @storage[key] = value
+      end
+
+      def fetch(key)
+        @storage[key]
+      end
+
+      def delete(key)
+        @storage.delete(key)
+      end
+
+      def exists?(key)
+        @storage.key?(key)
+      end
+
+      def cache_fetch(key, expires_in: nil, &block)
+        # Memory adapter doesn't support expiration, but we can implement basic caching
+        if @storage.key?(key)
+          @storage[key]
+        elsif block_given?
+          value = block.call
+          @storage[key] = value if value
+          value
+        end
+      end
+
+      def cache_write(key, value, expires_in: nil)
+        @storage[key] = value
+      end
+
+      def cache_delete(key)
+        @storage.delete(key)
+      end
+
+      def publish(topic, message)
+        subscribers = @subscribers[topic].to_a
+        return if subscribers.empty?
+
+        # Publish to subscribers in background fibers if available
+        if defined?(Fiber.scheduler) && Fiber.scheduler
+          subscribers.each do |subscriber|
+            Fiber.schedule { subscriber.call(message) }
+          end
+        else
+          subscribers.each { |subscriber| subscriber.call(message) }
+        end
+      end
+
+      def subscribe(topic, &block)
+        @subscribers[topic] << block
+      end
+
+      def clear!
+        @mutex.synchronize do
+          @storage.clear
+          @subscribers.clear
+        end
+      end
+
+      def size
+        @storage.size
+      end
+
+      def topics_count
+        @subscribers.size
+      end
+
+      def subscribers_count(topic)
+        @subscribers[topic].size
+      end
+
+      def healthy?
+        true
+      end
+    end
+  end
+end