flagstack 0.1.0

data/lib/flagstack/railtie.rb

@@ -0,0 +1,26 @@
+module Flagstack
+  class Railtie < Rails::Railtie
+    initializer "flagstack.configure", after: :load_config_initializers do
+      # Auto-configure when FLAGSTACK_TOKEN is present
+      Flagstack.set_default
+    end
+
+    initializer "flagstack.configure_flipper", after: "flagstack.configure" do
+      # If Flagstack is configured, set it as the default Flipper
+      next unless Flagstack.configuration && Flagstack.flipper
+
+      if defined?(Flipper)
+        # Set Flagstack's Flipper instance as the default
+        Flipper.instance = Flagstack.flipper
+        Flagstack.configuration.log("Set Flagstack as default Flipper instance", level: :info)
+      end
+    end
+
+    # Graceful shutdown when Rails exits
+    config.after_initialize do
+      at_exit do
+        Flagstack.shutdown if Flagstack.configuration
+      end
+    end
+  end
+end

data/lib/flagstack/synchronizer.rb

@@ -0,0 +1,81 @@
+module Flagstack
+  # Synchronizes features from Flagstack into the local adapter.
+  # This mirrors Flipper Cloud's approach: remote is source of truth,
+  # local adapter is kept in sync for fast reads.
+  class Synchronizer
+    def initialize(client:, flipper:, config:)
+      @client = client
+      @flipper = flipper
+      @config = config
+    end
+
+    # Pull features from Flagstack and write them into local adapter
+    def sync
+      @config.log("Synchronizing features from Flagstack", level: :debug)
+
+      data = @client.sync
+      return false unless data && data["features"]
+
+      features = data["features"]
+      @config.log("Received #{features.size} features from Flagstack", level: :debug)
+
+      features.each do |feature_data|
+        sync_feature(feature_data)
+      end
+
+      @config.log("Synchronized #{features.size} features to local adapter", level: :info)
+      true
+    rescue => e
+      @config.log("Sync failed: #{e.message}", level: :error)
+      false
+    end
+
+    private
+
+    def sync_feature(feature_data)
+      key = feature_data["key"]
+      gates = feature_data["gates"] || {}
+      enabled = feature_data["enabled"]
+      feature = @flipper[key]
+
+      # Clear existing gates first (disable everything)
+      feature.disable
+
+      # Sync boolean gate from the feature's enabled status
+      if enabled == true
+        feature.enable
+      end
+      # If false or nil, feature stays disabled from the disable above
+
+      # Sync actor gates
+      (gates["actors"] || []).each do |actor_id|
+        actor = Actor.new(actor_id)
+        feature.enable_actor(actor)
+      end
+
+      # Sync group gates
+      (gates["groups"] || []).each do |group_name|
+        feature.enable_group(group_name.to_sym)
+      end
+
+      # Sync percentage of actors
+      if gates["percentage_of_actors"]&.positive?
+        feature.enable_percentage_of_actors(gates["percentage_of_actors"])
+      end
+
+      # Sync percentage of time
+      if gates["percentage_of_time"]&.positive?
+        feature.enable_percentage_of_time(gates["percentage_of_time"])
+      end
+    end
+  end
+
+  # Simple actor class for sync operations
+  class Actor
+    attr_reader :flipper_id
+
+    def initialize(id)
+      @flipper_id = id
+    end
+  end
+end

data/lib/flagstack/telemetry/metric.rb

@@ -0,0 +1,33 @@
+module Flagstack
+  class Telemetry
+    class Metric
+      attr_reader :key, :time, :result
+
+      def initialize(key, result, time = Time.now)
+        @key = key.to_s
+        @result = !!result
+        @time = time.to_i / 60 * 60 # Round to minute
+      end
+
+      def as_json
+        {
+          "key" => key,
+          "time" => time,
+          "result" => result
+        }
+      end
+
+      def eql?(other)
+        self.class.eql?(other.class) &&
+          @key == other.key &&
+          @time == other.time &&
+          @result == other.result
+      end
+      alias :== :eql?
+
+      def hash
+        [self.class, @key, @time, @result].hash
+      end
+    end
+  end
+end

data/lib/flagstack/telemetry/metric_storage.rb

@@ -0,0 +1,32 @@
+module Flagstack
+  class Telemetry
+    class MetricStorage
+      def initialize
+        @mutex = Mutex.new
+        @storage = Hash.new(0)
+      end
+
+      def increment(metric)
+        @mutex.synchronize do
+          @storage[metric] += 1
+        end
+      end
+
+      def drain
+        @mutex.synchronize do
+          metrics = @storage.dup
+          @storage.clear
+          metrics.freeze
+        end
+      end
+
+      def empty?
+        @mutex.synchronize { @storage.empty? }
+      end
+
+      def size
+        @mutex.synchronize { @storage.size }
+      end
+    end
+  end
+end

data/lib/flagstack/telemetry/submitter.rb

@@ -0,0 +1,83 @@
+require "zlib"
+require "json"
+require "securerandom"
+
+module Flagstack
+  class Telemetry
+    class Submitter
+      MAX_RETRIES = 3
+
+      def initialize(client, config)
+        @client = client
+        @config = config
+        @request_id = SecureRandom.uuid
+      end
+
+      def call(metrics)
+        return if metrics.empty?
+
+        body = build_body(metrics)
+        compressed = gzip(body)
+
+        response = submit_with_retry(compressed)
+        handle_response(response) if response
+      rescue => e
+        @config.log("Telemetry submission failed: #{e.message}", level: :error)
+      end
+
+      private
+
+      def build_body(metrics)
+        {
+          request_id: @request_id,
+          metrics: metrics.map do |metric, count|
+            metric.as_json.merge("value" => count)
+          end
+        }.to_json
+      end
+
+      def gzip(body)
+        io = StringIO.new
+        io.set_encoding("BINARY")
+        gz = Zlib::GzipWriter.new(io)
+        gz.write(body)
+        gz.close
+        io.string
+      end
+
+      def submit_with_retry(body)
+        retries = 0
+        begin
+          @client.post_telemetry(body)
+        rescue => e
+          retries += 1
+          if retries < MAX_RETRIES
+            sleep(backoff_delay(retries))
+            retry
+          end
+          raise
+        end
+      end
+
+      def backoff_delay(attempt)
+        # Exponential backoff: 1s, 2s, 4s
+        (2 ** (attempt - 1)) + rand(0.0..0.5)
+      end
+
+      def handle_response(response)
+        return unless response
+
+        # Server can control telemetry via headers
+        if (interval = response["Telemetry-Interval"])
+          @config.telemetry_interval = interval.to_i
+          @config.log("Telemetry interval updated to #{interval}s", level: :debug)
+        end
+
+        if response["Telemetry-Shutdown"] == "true"
+          @config.telemetry_enabled = false
+          @config.log("Telemetry shutdown requested by server", level: :info)
+        end
+      end
+    end
+  end
+end

data/lib/flagstack/telemetry.rb

@@ -0,0 +1,99 @@
+module Flagstack
+  class Telemetry
+    attr_reader :storage
+
+    def initialize(client, config)
+      @client = client
+      @config = config
+      @storage = MetricStorage.new
+      @pid = Process.pid
+      @started = false
+      @mutex = Mutex.new
+    end
+
+    def start
+      @mutex.synchronize do
+        return if @started
+        start_timer
+        @started = true
+        @config.log("Telemetry started (interval: #{@config.telemetry_interval}s)", level: :info)
+      end
+    end
+
+    def stop
+      @mutex.synchronize do
+        return unless @started
+        @timer_thread&.kill
+        @timer_thread = nil
+        flush
+        @started = false
+        @config.log("Telemetry stopped", level: :info)
+      end
+    end
+
+    def record(feature_key, result)
+      return unless @config.telemetry_enabled
+
+      # Fork detection - restart if PID changed
+      check_fork
+
+      metric = Metric.new(feature_key, result)
+      @storage.increment(metric)
+    end
+
+    def flush
+      return if @storage.empty?
+
+      metrics = @storage.drain
+      submitter = Submitter.new(@client, @config)
+
+      # Submit in background thread to not block
+      Thread.new { submitter.call(metrics) }
+    end
+
+    def running?
+      @started
+    end
+
+    private
+
+    def start_timer
+      @timer_thread = Thread.new do
+        loop do
+          sleep(@config.telemetry_interval)
+          flush if @started
+        end
+      end
+      @timer_thread.abort_on_exception = false
+    end
+
+    def check_fork
+      return if @pid == Process.pid
+
+      @mutex.synchronize do
+        return if @pid == Process.pid
+
+        @config.log("Fork detected, restarting telemetry", level: :info)
+
+        # Drain any pending metrics before fork reset
+        # Note: We can't submit in parent process after fork, so we lose these
+        # metrics. This is a known limitation of forking servers.
+        # The metrics collected in the child process will be submitted normally.
+        unless @storage.empty?
+          @config.log("Discarding #{@storage.size} metrics from parent process after fork", level: :debug)
+        end
+
+        @pid = Process.pid
+        @storage = MetricStorage.new
+        @timer_thread&.kill
+        @timer_thread = nil
+        start_timer if @started
+      end
+    end
+  end
+end
+
+# Load nested classes after the Telemetry class is defined
+require "flagstack/telemetry/metric"
+require "flagstack/telemetry/metric_storage"
+require "flagstack/telemetry/submitter"

data/lib/flagstack/version.rb

@@ -0,0 +1,3 @@
+module Flagstack
+  VERSION = "0.1.0"
+end

data/lib/flagstack.rb

@@ -0,0 +1,332 @@
+require "flagstack/version"
+require "flagstack/configuration"
+require "flagstack/client"
+require "flagstack/synchronizer"
+require "flagstack/poller"
+require "flagstack/telemetry"
+
+module Flagstack
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class APIError < Error; end
+
+  class << self
+    attr_reader :configuration
+
+    # Create a new Flagstack-backed Flipper instance
+    #
+    #   flipper = Flagstack.new(token: "fs_live_xxx")
+    #   flipper.enabled?(:feature)
+    #   flipper.enabled?(:feature, user)
+    #
+    def new(options = {})
+      config = Configuration.new(options)
+      yield config if block_given?
+      config.validate!
+
+      Instance.new(config).flipper
+    end
+
+    # Configure the default Flagstack instance
+    # Returns a Flipper instance that reads from local adapter synced with Flagstack
+    #
+    #   Flagstack.configure do |config|
+    #     config.token = ENV["FLAGSTACK_TOKEN"]
+    #   end
+    #
+    #   # Now use Flipper as normal
+    #   Flipper.enabled?(:feature)
+    #
+    def configure(options = {})
+      @configuration = Configuration.new(options)
+      yield @configuration if block_given?
+      @configuration.validate!
+
+      @instance = Instance.new(@configuration)
+
+      # Set as default Flipper instance so Flipper.enabled? uses our adapter
+      Flipper.configure do |config|
+        config.default { @instance.flipper }
+      end
+
+      # Initial sync
+      @instance.sync
+
+      # Start background polling
+      @instance.start_poller if @configuration.sync_method == :poll
+
+      # Start telemetry
+      @instance.start_telemetry
+
+      @instance.flipper
+    end
+
+    # Get the Flipper instance
+    def flipper
+      @instance&.flipper
+    end
+
+    # Force sync from Flagstack to local adapter
+    def sync
+      @instance&.sync
+    end
+
+    # Reset everything (useful for testing)
+    def reset!
+      @instance&.stop_poller
+      @instance&.stop_telemetry
+      @instance = nil
+      @configuration = nil
+    end
+
+    # Shutdown telemetry and polling gracefully
+    def shutdown
+      @instance&.stop_telemetry
+      @instance&.stop_poller
+    end
+
+    # Check connectivity to Flagstack server
+    # Returns { ok: boolean, message: string }
+    def health_check
+      @instance&.client&.health_check || { ok: false, message: "Not configured" }
+    end
+
+    # ==========================================================================
+    # Flipper-compatible API
+    # These methods provide a clean abstraction that can be backed by Flipper
+    # today, but replaced with a custom backend in the future.
+    # ==========================================================================
+
+    # Check if a feature is enabled
+    #
+    #   Flagstack.enabled?(:new_feature)
+    #   Flagstack.enabled?(:new_feature, current_user)
+    #
+    def enabled?(feature, actor = nil)
+      return false unless @instance&.flipper
+
+      if actor
+        @instance.flipper.enabled?(feature, actor)
+      else
+        @instance.flipper.enabled?(feature)
+      end
+    end
+
+    # Check if a feature is disabled
+    #
+    #   Flagstack.disabled?(:new_feature)
+    #   Flagstack.disabled?(:new_feature, current_user)
+    #
+    def disabled?(feature, actor = nil)
+      !enabled?(feature, actor)
+    end
+
+    # Enable a feature globally
+    #
+    #   Flagstack.enable(:new_feature)
+    #
+    def enable(feature)
+      @instance&.flipper&.[](feature)&.enable
+    end
+
+    # Disable a feature globally
+    #
+    #   Flagstack.disable(:new_feature)
+    #
+    def disable(feature)
+      @instance&.flipper&.[](feature)&.disable
+    end
+
+    # Enable a feature for a specific actor
+    #
+    #   Flagstack.enable_actor(:new_feature, current_user)
+    #
+    def enable_actor(feature, actor)
+      @instance&.flipper&.[](feature)&.enable_actor(actor)
+    end
+
+    # Disable a feature for a specific actor
+    #
+    #   Flagstack.disable_actor(:new_feature, current_user)
+    #
+    def disable_actor(feature, actor)
+      @instance&.flipper&.[](feature)&.disable_actor(actor)
+    end
+
+    # Enable a feature for a group
+    #
+    #   Flagstack.enable_group(:new_feature, :admins)
+    #
+    def enable_group(feature, group)
+      @instance&.flipper&.[](feature)&.enable_group(group)
+    end
+
+    # Disable a feature for a group
+    #
+    #   Flagstack.disable_group(:new_feature, :admins)
+    #
+    def disable_group(feature, group)
+      @instance&.flipper&.[](feature)&.disable_group(group)
+    end
+
+    # Enable a feature for a percentage of actors
+    #
+    #   Flagstack.enable_percentage_of_actors(:new_feature, 25)
+    #
+    def enable_percentage_of_actors(feature, percentage)
+      @instance&.flipper&.[](feature)&.enable_percentage_of_actors(percentage)
+    end
+
+    # Disable percentage of actors gate
+    #
+    #   Flagstack.disable_percentage_of_actors(:new_feature)
+    #
+    def disable_percentage_of_actors(feature)
+      @instance&.flipper&.[](feature)&.disable_percentage_of_actors
+    end
+
+    # Enable a feature for a percentage of time
+    #
+    #   Flagstack.enable_percentage_of_time(:new_feature, 50)
+    #
+    def enable_percentage_of_time(feature, percentage)
+      @instance&.flipper&.[](feature)&.enable_percentage_of_time(percentage)
+    end
+
+    # Disable percentage of time gate
+    #
+    #   Flagstack.disable_percentage_of_time(:new_feature)
+    #
+    def disable_percentage_of_time(feature)
+      @instance&.flipper&.[](feature)&.disable_percentage_of_time
+    end
+
+    # Access a feature by name (returns a Feature object)
+    #
+    #   Flagstack[:new_feature].enabled?
+    #   Flagstack[:new_feature].enable
+    #
+    def [](feature)
+      @instance&.flipper&.[](feature)
+    end
+
+    # List all features
+    #
+    #   Flagstack.features
+    #
+    def features
+      @instance&.flipper&.features || []
+    end
+
+    # Register a group for use with enable_group
+    #
+    #   Flagstack.register(:admins) { |actor| actor.admin? }
+    #
+    def register(group, &block)
+      Flipper.register(group, &block)
+    end
+
+    # Auto-configure when FLAGSTACK_TOKEN is present
+    def set_default
+      return unless ENV["FLAGSTACK_TOKEN"]
+      return if @configuration # Already configured
+
+      configure
+    rescue => e
+      # Don't fail app boot if Flagstack is misconfigured
+      warn "[Flagstack] Auto-configuration failed: #{e.message}"
+    end
+  end
+
+  # Instance holds the configured state for a Flagstack setup
+  class Instance
+    attr_reader :configuration, :client, :local_adapter, :flipper, :telemetry
+
+    def initialize(configuration)
+      @configuration = configuration
+      @client = Client.new(configuration)
+      @local_adapter = configuration.local_adapter || default_adapter
+      @flipper = Flipper.new(@local_adapter, instrumenter: TelemetryInstrumenter.new(self))
+      @synchronizer = Synchronizer.new(
+        client: @client,
+        flipper: @flipper,
+        config: @configuration
+      )
+      @poller = nil
+      @telemetry = Telemetry.new(@client, @configuration)
+    end
+
+    def sync
+      @synchronizer.sync
+    end
+
+    def start_poller
+      return if @poller&.running?
+
+      @poller = Poller.new(@synchronizer, @configuration)
+      @poller.start
+      @configuration.log("Started background poller (interval: #{@configuration.sync_interval}s)", level: :info)
+    end
+
+    def stop_poller
+      @poller&.stop
+      @poller = nil
+    end
+
+    def start_telemetry
+      return unless @configuration.telemetry_enabled
+      @telemetry.start
+    end
+
+    def stop_telemetry
+      @telemetry&.stop
+    end
+
+    def record_telemetry(feature_key, result)
+      @telemetry&.record(feature_key, result)
+    end
+
+    private
+
+    def default_adapter
+      # Try ActiveRecord first, fall back to Memory
+      if defined?(Flipper::Adapters::ActiveRecord)
+        begin
+          Flipper::Adapters::ActiveRecord.new
+        rescue => e
+          @configuration.log("Could not create ActiveRecord adapter: #{e.message}, using Memory", level: :warn)
+          Flipper::Adapters::Memory.new
+        end
+      else
+        Flipper::Adapters::Memory.new
+      end
+    end
+  end
+
+  # Instrumenter that records telemetry for feature flag checks
+  class TelemetryInstrumenter
+    def initialize(instance)
+      @instance = instance
+    end
+
+    def instrument(name, payload = {})
+      result = yield payload if block_given?
+
+      # Record telemetry for feature_operation events
+      if name == "feature_operation.flipper" && payload[:operation] == :enabled?
+        feature_name = payload[:feature_name]
+        @instance.record_telemetry(feature_name, payload[:result]) if feature_name
+      end
+
+      result
+    end
+  end
+end
+
+# Load Railtie if Rails is present
+require "flagstack/railtie" if defined?(Rails::Railtie)
+
+# Auto-configure when token is present (after Rails initializers if in Rails)
+unless defined?(Rails::Railtie)
+  Flagstack.set_default
+end