star_gates 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91627ddc25a266e8584724a1e1973799dc693e883f4b5d01dfe33cb1ccbd6fbf
-  data.tar.gz: be8eaf8ff34249e3cf355c3fa8fd1159625aee1e23be009ce9664d644f837a6d
+  metadata.gz: 2747943c57b6c5a1d42a415ec8321bcab9420438f3425424432a35ada2571c97
+  data.tar.gz: 375a4a1f9f7d27ec78d35386bb973f37c5723a2ff7a37eb580d5cd9d80f9f686
 SHA512:
-  metadata.gz: 1ff36a75a319ed7646b3eab22a9b256078044f5144c2ab7eb62f8b052504a800565ab13c3e9c5a7010428df585cbc974f9d4b0c5eb1d8fefa20049cc6b61462b
-  data.tar.gz: df5408c183aba188434a0f74b0b330036b1951786fa3abd78b80b4eda7e7151b1270e17eaba39fb27f8422efeb25392ec0f575805c18f627053ed981056f8184
+  metadata.gz: db442d9496bc8ecaaae6a329c0b2bae1ac6f99a8a4375b57ec3e950941e7257c4a45045d1eb66494c2e74fc3c3075429ddf193173446ae09189b11b4dbfe8d2a
+  data.tar.gz: 9954bf6fccad1f849cd5fb411c3b79f2516ea46dc7b99da86ee4a373d3b4eb06e68cc14ba07a43c8c960bc4a0e5cf69086b40c5807495b79f3d4d250ce6fd7d6

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,54 @@
-## [Unreleased]
+# Changelog
 
-## [0.1.0] - 2025-07-08
+## Unreleased
 
-- Initial release
+### Changed
+
+- 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
+
+- 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,198 @@
 # 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(user: current_user, amount: 100)
+```
+
+Features start disabled. Use `rollout_canary` for percentage/group targeting,
+`enable` for full rollout, and `disable` to turn a feature off. Provide a user with
+an `id` for consistent percentage targeting.
+
+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
+        }
+```
 
-```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+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(user: current_user, amount: params[:amount])
+    render json: result
+  end
+end
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+The Rails integration fixture lives in `test/dummy/` and uses the root Gemfile.
 
-```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+## 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
 ```
 
-## Usage
+Circuit events include `circuit.auto_rollback`, `circuit.half_open`,
+`circuit.recovered`, and `circuit.retry`, prefixed with `star_gates.`.
+
+## 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
+```
 
-TODO: Write usage instructions here
+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'
+
+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
+pilot = StarGates::Feature::MockUser.new(id: 1, groups: [:pilots])
+ship.engage_warp('Alpha Centauri', pilot: pilot)
+```
+
+### Application examples
+
+- [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 user 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

data/lib/star_gates/adapters/redis_adapter.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require_relative 'base_adapter'
+
+module StarGates
+  module Adapters
+    class RedisAdapter < BaseAdapter
+      def initialize(config = {})
+        super
+        @redis = config[:redis] || redis_from_config
+        @key_prefix = config[:key_prefix] || 'star_gates'
+        @default_ttl = config[:default_ttl] || 3600 # 1 hour
+      end
+
+      def store(key, value)
+        serialized = serialize(value)
+        @redis.set(prefixed_key(key), serialized)
+      end
+
+      def fetch(key)
+        value = @redis.get(prefixed_key(key))
+        value ? deserialize(value) : nil
+      end
+
+      def delete(key)
+        @redis.del(prefixed_key(key))
+      end
+
+      def exists?(key)
+        @redis.exists?(prefixed_key(key)).positive?
+      end
+
+      def cache_fetch(key, expires_in: nil, &block)
+        prefixed = prefixed_key(key)
+        cached = @redis.get(prefixed)
+
+        if cached
+          deserialize(cached)
+        elsif block_given?
+          value = block.call
+          if value
+            serialized = serialize(value)
+            ttl = expires_in || @default_ttl
+            @redis.setex(prefixed, ttl, serialized)
+          end
+          value
+        end
+      end
+
+      def cache_write(key, value, expires_in: nil)
+        serialized = serialize(value)
+        ttl = expires_in || @default_ttl
+        @redis.setex(prefixed_key(key), ttl, serialized)
+      end
+
+      def cache_delete(key)
+        @redis.del(prefixed_key(key))
+      end
+
+      def publish(topic, message)
+        @redis.publish(topic_key(topic), serialize(message))
+      end
+
+      def subscribe(topic, &block)
+        # Redis pub/sub requires a dedicated connection
+        # This is a simplified version - in production, use a separate subscriber thread
+        @redis.subscribe(topic_key(topic)) do |on|
+          on.message do |_channel, message|
+            block.call(deserialize(message))
+          end
+        end
+      end
+
+      def healthy?
+        @redis.ping == 'PONG'
+      rescue StandardError
+        false
+      end
+
+      private
+
+      def prefixed_key(key)
+        "#{@key_prefix}:#{key}"
+      end
+
+      def topic_key(topic)
+        "#{@key_prefix}:topics:#{topic}"
+      end
+
+      def serialize(value)
+        case value
+        when String
+          value
+        when Symbol
+          value.to_s
+        else
+          JSON.generate(value)
+        end
+      end
+
+      def deserialize(value)
+        JSON.parse(value)
+      rescue JSON::ParserError
+        value
+      end
+
+      def redis_from_config
+        raise ArgumentError, "Redis gem not available. Install with: gem 'redis'" unless defined?(Redis)
+
+        # Try to use existing Redis configuration
+        if defined?(Rails) && Rails.application.config.respond_to?(:redis)
+          Redis.new(Rails.application.config.redis)
+        else
+          Redis.new
+        end
+      end
+    end
+  end
+end