flagstack 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 45801e9bdf69b3bbd9637ed2002a4510b8d6da904cb168f0e34e54515547f00e
+  data.tar.gz: 126b2472e808d34b95549d06739deb4d54a93700dc9a22220487a9f9e4a87fad
+SHA512:
+  metadata.gz: 83eeef5118a376835521710bc2fbb5da7591d792bd6e5992213a5ef01cd5a678d60aa6219eb7fdc90c31358c6c9409d427c4813316bf6f26112542d37f1e7179
+  data.tar.gz: 1a173b66ca308fc1b2188307e61eb4ec280f970623aa5766c30826d0b617e5e0ec569b2a8c870c804ade3831ba78c2748c2e379e7c3bff49ecf01bb09bf9d419

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Flagstack
+
+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:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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.

data/README.md

@@ -0,0 +1,379 @@
+# Flagstack Ruby Client
+
+Ruby client for [Flagstack](https://flagstack.io) feature flag management. Drop-in replacement for Flipper Cloud.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "flagstack"
+gem "flipper"
+gem "flipper-active_record"  # Recommended: for persistent local storage
+```
+
+Then run the generator:
+
+```bash
+rails generate flagstack:install
+```
+
+## Quick Start
+
+Set your API token:
+
+```bash
+export FLAGSTACK_TOKEN=fs_live_your_token_here
+```
+
+That's it! Flagstack auto-configures when `FLAGSTACK_TOKEN` is present. Your existing Flipper code works unchanged:
+
+```ruby
+Flipper.enabled?(:new_checkout)
+Flipper.enabled?(:beta_feature, current_user)
+```
+
+## How It Works
+
+Flagstack mirrors Flipper Cloud's architecture:
+
+```
+                    +-----------------+
+                    |    Flagstack    |
+                    |  (cloud server) |
+                    +--------+--------+
+                             |
+                             | sync (every 10-30s)
+                             v
+                    +--------+--------+
+                    | Local Adapter   |
+                    | (ActiveRecord   |
+                    |  or Memory)     |
+                    +--------+--------+
+                             |
+                             | all reads
+                             v
+                    +--------+--------+
+                    |  Your App       |
+                    | Flipper.enabled?|
+                    +-----------------+
+```
+
+1. **Flagstack is the source of truth** - Manage flags in the Flagstack UI
+2. **Data syncs to your local adapter** - Background poller keeps local data fresh
+3. **All reads are local** - Zero network latency for `enabled?` checks
+4. **Works offline** - If Flagstack is down, reads continue from local adapter
+
+## Configuration
+
+### Basic Configuration
+
+```ruby
+# config/initializers/flagstack.rb
+Flagstack.configure do |config|
+  config.token = ENV["FLAGSTACK_TOKEN"]
+  config.sync_interval = 10  # seconds (minimum 10)
+end
+```
+
+### Full Options
+
+```ruby
+Flagstack.configure do |config|
+  # Required
+  config.token = ENV["FLAGSTACK_TOKEN"]
+
+  # Server (default: https://flagstack.io)
+  config.url = ENV["FLAGSTACK_URL"]
+
+  # Sync interval in seconds (default: 10, minimum: 10)
+  config.sync_interval = 30
+
+  # Sync method: :poll (background thread) or :manual
+  config.sync_method = :poll
+
+  # Telemetry (usage metrics)
+  config.telemetry_enabled = true  # default: true
+  config.telemetry_interval = 60   # seconds between submissions
+
+  # HTTP timeouts in seconds
+  config.read_timeout = 5
+  config.open_timeout = 2
+  config.write_timeout = 5
+
+  # Local adapter (auto-detected if flipper-active_record is present)
+  # Falls back to Memory adapter if not specified
+  config.local_adapter = Flipper::Adapters::ActiveRecord.new
+
+  # Logging
+  config.logger = Rails.logger
+
+  # Debug HTTP requests
+  config.debug_output = $stderr
+
+  # Instrumentation (for monitoring)
+  config.instrumenter = ActiveSupport::Notifications
+end
+```
+
+## Telemetry
+
+Flagstack collects anonymous usage metrics to help you understand feature flag usage patterns. This data powers the Analytics dashboard in Flagstack.
+
+### What's Collected
+
+- Feature key (which flag was checked)
+- Result (enabled/disabled)
+- Timestamp (rounded to the minute)
+- Count (aggregated locally before submission)
+
+### Disabling Telemetry
+
+```ruby
+Flagstack.configure do |config|
+  config.token = ENV["FLAGSTACK_TOKEN"]
+  config.telemetry_enabled = false
+end
+```
+
+## Usage
+
+### With Rails (Recommended)
+
+When `FLAGSTACK_TOKEN` is set, Flagstack automatically configures itself. You can use either the Flagstack API or Flipper directly:
+
+```ruby
+# Native Flagstack API (recommended for new projects)
+Flagstack.enabled?(:new_checkout)
+Flagstack.enabled?(:beta_feature, current_user)
+
+# Flipper-compatible - existing code works unchanged
+Flipper.enabled?(:new_checkout)
+Flipper.enabled?(:beta_feature, current_user)
+
+# Feature objects work too
+Flagstack[:new_checkout].enabled?
+Flipper[:new_checkout].enabled?
+```
+
+### Manual Configuration
+
+```ruby
+# config/initializers/flagstack.rb
+flipper = Flagstack.configure do |config|
+  config.token = ENV["FLAGSTACK_TOKEN"]
+end
+
+# Use the returned Flipper instance directly
+flipper.enabled?(:new_checkout)
+
+# Or access it later
+Flagstack.flipper.enabled?(:new_checkout)
+```
+
+### Without Global State
+
+For multi-tenant apps or testing:
+
+```ruby
+# Create separate instances (doesn't affect Flagstack.configuration)
+flipper = Flagstack.new(token: "fs_live_xxx")
+flipper.enabled?(:feature)
+flipper.enabled?(:feature, current_user)
+```
+
+## Actor Setup
+
+For percentage rollouts and actor targeting, your user model needs a `flipper_id`:
+
+```ruby
+class User < ApplicationRecord
+  # Flipper expects this method for actor-based features
+  def flipper_id
+    "User_#{id}"
+  end
+end
+
+# Then use it
+Flipper.enabled?(:beta_feature, current_user)
+```
+
+## Local Features
+
+You can still create local-only features that aren't synced from Flagstack:
+
+```ruby
+# Enable a local feature
+Flipper.enable(:local_only_feature)
+
+# It works alongside Flagstack features
+Flipper.enabled?(:local_only_feature)  # true
+Flipper.enabled?(:flagstack_feature)    # from Flagstack
+```
+
+Note: Flagstack sync only affects features that exist in Flagstack. Your local features are preserved.
+
+## Token Types
+
+| Prefix | Environment | Use |
+|--------|-------------|-----|
+| `fs_live_` | Production | Live traffic |
+| `fs_test_` | Staging | Pre-production testing |
+| `fs_dev_` | Development | Shared development |
+| `fs_personal_` | Personal | Your local machine |
+
+## API Reference
+
+### Configuration
+
+#### `Flagstack.configure { |config| }`
+
+Configure and return a Flipper instance. Sets `Flagstack.configuration` and `Flagstack.flipper`.
+
+#### `Flagstack.new(options)`
+
+Create a standalone Flipper instance without affecting global state.
+
+#### `Flagstack.flipper`
+
+Returns the configured Flipper instance (after `configure`).
+
+### Feature Flag Checks
+
+#### `Flagstack.enabled?(feature, actor = nil)`
+
+Check if a feature is enabled, optionally for a specific actor.
+
+```ruby
+Flagstack.enabled?(:new_checkout)
+Flagstack.enabled?(:beta_feature, current_user)
+```
+
+#### `Flagstack.disabled?(feature, actor = nil)`
+
+Check if a feature is disabled.
+
+```ruby
+Flagstack.disabled?(:maintenance_mode)
+```
+
+#### `Flagstack[feature]`
+
+Access a feature object for method chaining.
+
+```ruby
+Flagstack[:new_checkout].enabled?
+Flagstack[:new_checkout].enabled?(current_user)
+```
+
+### Feature Flag Management
+
+#### `Flagstack.enable(feature)` / `Flagstack.disable(feature)`
+
+Enable or disable a feature globally.
+
+```ruby
+Flagstack.enable(:new_feature)
+Flagstack.disable(:old_feature)
+```
+
+#### `Flagstack.enable_actor(feature, actor)` / `Flagstack.disable_actor(feature, actor)`
+
+Enable or disable a feature for a specific actor.
+
+```ruby
+Flagstack.enable_actor(:beta_feature, current_user)
+```
+
+#### `Flagstack.enable_group(feature, group)` / `Flagstack.disable_group(feature, group)`
+
+Enable or disable a feature for a registered group.
+
+```ruby
+Flagstack.register(:admins) { |actor| actor.admin? }
+Flagstack.enable_group(:admin_tools, :admins)
+```
+
+#### `Flagstack.enable_percentage_of_actors(feature, percentage)`
+
+Enable a feature for a percentage of actors (deterministic based on actor ID).
+
+```ruby
+Flagstack.enable_percentage_of_actors(:new_feature, 25)  # 25% of users
+```
+
+#### `Flagstack.features`
+
+List all features.
+
+```ruby
+Flagstack.features.each { |f| puts f.key }
+```
+
+### Utilities
+
+#### `Flagstack.sync`
+
+Force a sync from Flagstack to the local adapter.
+
+#### `Flagstack.health_check`
+
+Check connectivity to Flagstack server. Returns `{ ok: true/false, message: "..." }`.
+
+```ruby
+result = Flagstack.health_check
+if result[:ok]
+  puts "Connected: #{result[:message]}"
+else
+  puts "Error: #{result[:message]}"
+end
+```
+
+#### `Flagstack.shutdown`
+
+Gracefully stop the poller and flush any pending telemetry. Called automatically on Rails shutdown.
+
+#### `Flagstack.reset!`
+
+Reset everything (clears configuration, stops poller). Useful for testing.
+
+## Testing
+
+In your test setup:
+
+```ruby
+RSpec.configure do |config|
+  config.before(:each) do
+    Flagstack.reset!
+  end
+end
+```
+
+For isolated tests, use `Flagstack.new` with a test token or stub the HTTP calls:
+
+```ruby
+# With WebMock
+stub_request(:get, "https://flagstack.io/api/v1/sync")
+  .to_return(
+    status: 200,
+    body: { features: [{ key: "test_feature", enabled: true, gates: {} }] }.to_json
+  )
+
+stub_request(:post, "https://flagstack.io/api/v1/telemetry")
+  .to_return(status: 202)
+
+flipper = Flagstack.new(token: "fs_test_xxx")
+expect(flipper.enabled?(:test_feature)).to be true
+```
+
+## Migrating from Flipper Cloud
+
+Flagstack is designed as a drop-in replacement:
+
+1. Replace `FLIPPER_CLOUD_TOKEN` with `FLAGSTACK_TOKEN`
+2. Replace `gem "flipper-cloud"` with `gem "flagstack"`
+3. Your `Flipper.enabled?` calls work unchanged
+
+## License
+
+MIT

data/lib/flagstack/client.rb

@@ -0,0 +1,127 @@
+require "net/http"
+require "json"
+
+module Flagstack
+  class Client
+    def initialize(config)
+      @config = config
+      @etag = nil
+    end
+
+    def sync
+      uri = URI("#{@config.url}/api/v1/sync")
+
+      response = request(:get, uri) do |req|
+        req["If-None-Match"] = @etag if @etag
+      end
+
+      case response.code.to_i
+      when 200
+        @etag = response["ETag"]
+        @config.log("Sync successful (ETag: #{@etag})", level: :debug)
+        JSON.parse(response.body)
+      when 304
+        @config.log("Sync not modified (304)", level: :debug)
+        nil # Cache is current
+      when 401
+        raise APIError, "Invalid API token"
+      when 429
+        @config.log("Rate limited, backing off", level: :warn)
+        nil
+      else
+        raise APIError, "API error: #{response.code} #{response.body}"
+      end
+    rescue Timeout::Error, Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNREFUSED => e
+      @config.log("Connection failed: #{e.message}", level: :error)
+      nil
+    end
+
+    def check(feature_key, actor_id: nil)
+      uri = URI("#{@config.url}/api/v1/features/#{feature_key}/check")
+      uri.query = URI.encode_www_form(actor_id: actor_id) if actor_id
+
+      response = request(:get, uri)
+      data = JSON.parse(response.body)
+      data["enabled"]
+    end
+
+    # Check if the Flagstack server is reachable and the token is valid
+    # Returns a hash with :ok (boolean) and :message (string)
+    def health_check
+      uri = URI("#{@config.url}/api/v1/sync")
+
+      response = request(:get, uri)
+
+      case response.code.to_i
+      when 200, 304
+        { ok: true, message: "Connected to Flagstack" }
+      when 401
+        { ok: false, message: "Invalid API token" }
+      when 429
+        { ok: true, message: "Connected (rate limited)" }
+      else
+        { ok: false, message: "Unexpected response: #{response.code}" }
+      end
+    rescue Timeout::Error, Net::OpenTimeout, Net::ReadTimeout => e
+      { ok: false, message: "Connection timeout: #{e.message}" }
+    rescue Errno::ECONNREFUSED => e
+      { ok: false, message: "Connection refused: #{e.message}" }
+    rescue => e
+      { ok: false, message: "Connection failed: #{e.message}" }
+    end
+
+    def post_telemetry(compressed_body)
+      uri = URI("#{@config.url}/api/v1/telemetry")
+
+      response = request(:post, uri) do |req|
+        req["Content-Type"] = "application/json"
+        req["Content-Encoding"] = "gzip"
+        req.body = compressed_body
+      end
+
+      case response.code.to_i
+      when 200..299
+        @config.log("Telemetry submitted successfully", level: :debug)
+        response
+      when 429
+        @config.log("Telemetry rate limited", level: :warn)
+        nil
+      else
+        @config.log("Telemetry failed: #{response.code}", level: :error)
+        nil
+      end
+    rescue Timeout::Error, Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNREFUSED => e
+      @config.log("Telemetry connection failed: #{e.message}", level: :error)
+      nil
+    end
+
+    private
+
+    def request(method, uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.read_timeout = @config.read_timeout
+      http.open_timeout = @config.open_timeout
+      http.write_timeout = @config.write_timeout if http.respond_to?(:write_timeout=)
+
+      # Debug output
+      http.set_debug_output(@config.debug_output) if @config.debug_output
+
+      request = case method
+      when :get then Net::HTTP::Get.new(uri)
+      when :post then Net::HTTP::Post.new(uri)
+      else raise ArgumentError, "Unknown method: #{method}"
+      end
+
+      request["Authorization"] = "Bearer #{@config.token}"
+      request["User-Agent"] = "flagstack-ruby/#{VERSION}"
+      request["Accept"] = "application/json"
+
+      yield request if block_given?
+
+      @config.instrument("http_request", method: method, uri: uri.to_s) do
+        http.request(request)
+      end
+    end
+  end
+end

data/lib/flagstack/configuration.rb

@@ -0,0 +1,112 @@
+require "logger"
+
+module Flagstack
+  class Configuration
+    # Authentication
+    attr_accessor :token
+
+    # Server
+    attr_accessor :url
+
+    # HTTP settings
+    attr_accessor :read_timeout, :open_timeout, :write_timeout
+
+    # Sync settings
+    attr_accessor :sync_interval, :sync_method
+
+    # Local adapter for fallback/caching
+    attr_accessor :local_adapter
+
+    # Telemetry settings
+    attr_accessor :telemetry_enabled, :telemetry_interval
+
+    # Logging
+    attr_accessor :logger, :debug_output
+
+    # Instrumentation (for monitoring systems)
+    attr_accessor :instrumenter
+
+    def initialize(options = {})
+      setup_auth(options)
+      setup_http(options)
+      setup_sync(options)
+      setup_telemetry(options)
+      setup_logging(options)
+      setup_instrumentation(options)
+    end
+
+    def validate!
+      raise ConfigurationError, "Token is required. Set FLAGSTACK_TOKEN or pass token option." if token.nil? || token.empty?
+    end
+
+    def log(message, level: :debug)
+      logger&.send(level, "[Flagstack] #{message}")
+    end
+
+    def instrument(name, payload = {}, &block)
+      if instrumenter
+        instrumenter.instrument("flagstack.#{name}", payload, &block)
+      elsif block
+        yield payload
+      end
+    end
+
+    def environment_from_token
+      return :unknown unless token
+
+      prefix = token.split("_")[1]
+      case prefix
+      when "live" then :production
+      when "test" then :staging
+      when "dev" then :development
+      when "personal" then :personal
+      else :unknown
+      end
+    end
+
+    private
+
+    def setup_auth(options)
+      @token = options.fetch(:token) { ENV["FLAGSTACK_TOKEN"] }
+      @url = options.fetch(:url) { ENV.fetch("FLAGSTACK_URL", "https://flagstack.io") }
+    end
+
+    def setup_http(options)
+      @read_timeout = options.fetch(:read_timeout, 5)
+      @open_timeout = options.fetch(:open_timeout, 2)
+      @write_timeout = options.fetch(:write_timeout, 5)
+    end
+
+    def setup_sync(options)
+      interval = options.fetch(:sync_interval) { ENV.fetch("FLAGSTACK_SYNC_INTERVAL", 10).to_i }
+      @sync_interval = [interval, 10].max  # Minimum 10 seconds
+
+      @sync_method = options.fetch(:sync_method, :poll)
+      @local_adapter = options[:local_adapter]
+    end
+
+    def setup_telemetry(options)
+      @telemetry_enabled = options.fetch(:telemetry_enabled) {
+        ENV.fetch("FLAGSTACK_TELEMETRY_ENABLED", "true") == "true"
+      }
+      @telemetry_interval = options.fetch(:telemetry_interval) {
+        ENV.fetch("FLAGSTACK_TELEMETRY_INTERVAL", 60).to_i
+      }
+    end
+
+    def setup_logging(options)
+      @debug_output = options[:debug_output]
+      @logger = options.fetch(:logger) do
+        if defined?(Rails) && Rails.respond_to?(:logger)
+          Rails.logger
+        else
+          Logger.new($stdout, level: Logger::INFO)
+        end
+      end
+    end
+
+    def setup_instrumentation(options)
+      @instrumenter = options[:instrumenter]
+    end
+  end
+end

data/lib/flagstack/poller.rb

@@ -0,0 +1,66 @@
+module Flagstack
+  class Poller
+    def initialize(synchronizer, config)
+      @synchronizer = synchronizer
+      @config = config
+      @running = false
+      @thread = nil
+      @pid = Process.pid
+    end
+
+    def start
+      return if @running
+
+      @running = true
+      @thread = Thread.new { run }
+      @thread.abort_on_exception = false
+    end
+
+    def stop
+      @running = false
+      @thread&.wakeup rescue nil
+      @thread&.join(2)
+      @thread = nil
+    end
+
+    def running?
+      @running && @thread&.alive?
+    end
+
+    private
+
+    def run
+      while @running
+        # Check for fork (important for Puma, Unicorn, etc.)
+        if forked?
+          reset_after_fork
+          next
+        end
+
+        sleep_with_jitter
+
+        begin
+          @synchronizer.sync
+        rescue => e
+          @config.log("Poll sync failed: #{e.message}", level: :error)
+        end
+      end
+    end
+
+    def sleep_with_jitter
+      # Add 10% jitter to prevent thundering herd
+      jitter = @config.sync_interval * 0.1 * rand
+      sleep(@config.sync_interval + jitter)
+    end
+
+    def forked?
+      Process.pid != @pid
+    end
+
+    def reset_after_fork
+      @config.log("Fork detected, resetting poller", level: :debug)
+      @pid = Process.pid
+      @running = false
+    end
+  end
+end