featureflip 2.13.0 → 2.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c41498d43abe3f592e70ef93178a39bbabfc481072cf1862b3a18399ad3972db
-  data.tar.gz: 00b9495f23ece99027e3c03c647616cd240a11338f8376511ac4bbd2ce46e826
+  metadata.gz: 2abe9cc6f772c5d01773b0c34ecd9de2323fb7f7228ebbe7806ca88967ce60c6
+  data.tar.gz: 37ba38ab6f4c4dd207119f6e292b0fa45131b721ab7c63616a7e26a7b0defc87
 SHA512:
-  metadata.gz: 3c397937ed703003e47e5999a9ffd0cd6004ce0ee02e0b216ba6c99c06dec2b03a37ceb9163b8fba36cc413747782fc13ccd84ed7218e307cd21f92ded5566da
-  data.tar.gz: ca65db25d697572ceae8f048bb5672407639fd9aeebf0bc3e0f691cfd08e3993983d78c80f80ad9997852725ebd319ca0b19c069c455fde3b8b43c4c54f73e41
+  metadata.gz: 140f40e9b708ae00f732e7d1df67558d000094f7000d0e521f3fef6f0f49155148123e96988edfc57840ba96cfa75097327768b26628a04bd359bfc5c71ed2e9
+  data.tar.gz: e8537c6c21a1b0143604b7f699849b8cf1065bc88f2fdad0cce65d199e96c604d1440d4304cf0efc129f47c559f35ca220a5721fd2446fa31253d610459344e9

data/lib/featureflip/client.rb

@@ -28,6 +28,13 @@ module Featureflip
       @core.initialized?
     end
 
+    # Where the flag data came from: a StartupInfo whose +source+ is "live" after a
+    # successful fetch, "snapshot" when started from the configured snapshot_store, or
+    # "none" (defaults served). It moves to "live" once the Evaluation API is reached.
+    def startup_info
+      @core.startup_info
+    end
+
     def bool_variation(key, context, default_value)
       return default_value if @closed
       @core.bool_variation(key, context, default_value)

data/lib/featureflip/config.rb

@@ -13,6 +13,30 @@ module Featureflip
     # than changing behavior.
     attr_accessor :wrapper_name, :wrapper_version
 
+    # Opt-in last-known-config store (see Featureflip::FileSnapshotStore). When the
+    # initial fetch fails or times out the client starts from the stored snapshot
+    # instead of serving defaults. Honored on the first Client.get per SDK key. Not
+    # part of the different-config comparison; its identity is compared separately.
+    attr_accessor :snapshot_store
+
+    # How old a stored snapshot may be and still be used, in seconds. Must be a
+    # positive, finite number; there is no "never expire" value.
+    DEFAULT_MAX_SNAPSHOT_AGE_SECONDS = 86_400
+    UNSET = Object.new.freeze
+    private_constant :UNSET
+    attr_reader :max_snapshot_age_seconds
+
+    def max_snapshot_age_seconds=(value)
+      @max_snapshot_age_explicit = true
+      @max_snapshot_age_seconds = value
+    end
+
+    # True when the caller passed a max age, so the "option ignored" warning can tell
+    # an omitted option from the default.
+    def max_snapshot_age_explicit?
+      @max_snapshot_age_explicit
+    end
+
     # Evaluation inspectors -- callables invoked once per variation call with a
     # Models::EvaluationEvent. Always an Array; non-callable entries are dropped
     # on assignment rather than blowing up on the evaluation hot path.
@@ -33,7 +57,9 @@ module Featureflip
       logger: nil,
       inspectors: nil,
       wrapper_name: nil,
-      wrapper_version: nil
+      wrapper_version: nil,
+      snapshot_store: nil,
+      max_snapshot_age_seconds: UNSET
     )
       @sdk_key = sdk_key
       @base_url = base_url
@@ -50,6 +76,9 @@ module Featureflip
       self.inspectors = inspectors
       @wrapper_name = wrapper_name
       @wrapper_version = wrapper_version
+      @snapshot_store = snapshot_store
+      @max_snapshot_age_explicit = !UNSET.equal?(max_snapshot_age_seconds)
+      @max_snapshot_age_seconds = @max_snapshot_age_explicit ? max_snapshot_age_seconds : DEFAULT_MAX_SNAPSHOT_AGE_SECONDS
 
       validate!
     end
@@ -76,6 +105,7 @@ module Featureflip
     def validate!
       finalize!
       validate_positive_fields!
+      validate_snapshot_options!
     end
 
     private
@@ -93,6 +123,17 @@ module Featureflip
       end
     end
 
+    def validate_snapshot_options!
+      age = @max_snapshot_age_seconds
+      valid = age.is_a?(Numeric) && !age.is_a?(Complex) && age.to_f.finite? && age.positive?
+      unless valid
+        raise ConfigurationError, "max_snapshot_age_seconds must be a positive, finite number, got #{age.inspect}"
+      end
+      return if @snapshot_store.nil? || (@snapshot_store.respond_to?(:get) && @snapshot_store.respond_to?(:put))
+
+      raise ConfigurationError, "snapshot_store must respond to #get and #put"
+    end
+
     def default_logger
       if defined?(Rails) && Rails.respond_to?(:logger)
         Rails.logger

data/lib/featureflip/data_source/streaming.rb

@@ -36,7 +36,7 @@ module Featureflip
       RECONNECT_BASE_DELAY_SECONDS = 1
       MAX_BACKOFF_SECONDS = 30
 
-      def initialize(sdk_key:, config:, http_client:, on_flag_updated:, on_flag_deleted:, on_segment_updated:, on_error:, on_sync: nil, on_fallback_to_polling: nil, on_recovered: nil)
+      def initialize(sdk_key:, config:, http_client:, on_flag_updated:, on_flag_deleted:, on_segment_updated:, on_error:, on_sync: nil, on_fallback_to_polling: nil, on_recovered: nil, on_ping: nil)
         @sdk_key = sdk_key
         @config = config
         @http_client = http_client
@@ -47,6 +47,7 @@ module Featureflip
         @on_sync = on_sync
         @on_fallback_to_polling = on_fallback_to_polling
         @on_recovered = on_recovered
+        @on_ping = on_ping
         @stop_flag = false
         @thread = nil
         @retry_count = 0
@@ -283,6 +284,9 @@ module Featureflip
           # re-synced. Full replace, never a per-key merge.
           flags, segments = @http_client.parse_flags_response(JSON.parse(data))
           @on_sync&.call(flags, segments)
+        when "ping"
+          # The server's keep-alive: the stream is live and healthy.
+          @on_ping&.call
         end
       rescue UnevaluableEntityError => e
         # Not a malformed payload: the frame was well-formed and simply described

data/lib/featureflip/evaluation/condition_evaluator.rb

@@ -1,3 +1,4 @@
+require_relative "context_attribute"
 require "time"
 
 module Featureflip
@@ -10,7 +11,7 @@ module Featureflip
       REGEX_TIMEOUT_SECONDS = 0.1
 
       def evaluate_condition(condition, context)
-        attr_value = context[condition.attribute]
+        attr_value = ContextAttribute.resolve(context, condition.attribute)
 
         return condition.negate if attr_value.nil?
 

data/lib/featureflip/evaluation/context_attribute.rb

@@ -0,0 +1,24 @@
+module Featureflip
+  module Evaluation
+    # Looks an attribute up in an evaluation context hash.
+    #
+    # "user_id" is the canonical spelling of the user identifier and "userId" is
+    # accepted as an alias (#4518). A lookup of exactly one of the two returns
+    # "user_id" when it is non-nil, else "userId" when it is non-nil, else nil.
+    # An empty string is a value and does not fall through. Every other key,
+    # including other casings, is an ordinary attribute.
+    module ContextAttribute
+      module_function
+
+      def resolve(context, attribute)
+        if attribute == "user_id" || attribute == "userId"
+          value = context["user_id"]
+          value = context["userId"] if value.nil?
+          value
+        else
+          context[attribute]
+        end
+      end
+    end
+  end
+end

data/lib/featureflip/evaluation/evaluator.rb

@@ -1,3 +1,4 @@
+require_relative "context_attribute"
 require_relative "condition_evaluator"
 require_relative "bucketing"
 require_relative "canonical_number"
@@ -164,7 +165,7 @@ module Featureflip
       end
 
       def warn_unbucketable(flag, rule_id, serve)
-        UnbucketableWarnings.warn(@logger, flag.key, rule_id, serve.bucket_by || "userId")
+        UnbucketableWarnings.warn(@logger, flag.key, rule_id, serve.bucket_by || "user_id")
       end
 
       # Returns the variation key to serve, or nil when a Rollout serve can't bucket
@@ -178,13 +179,13 @@ module Featureflip
       end
 
       def resolve_rollout(serve, context)
-        bucket_by = serve.bucket_by || "userId"
-        bucket_value = context[bucket_by]
-        # Alias "userId" <-> "user_id" for the built-in user identifier
-        bucket_value = context["user_id"] if bucket_value.nil? && bucket_by == "userId"
-        bucket_value = context["userId"] if bucket_value.nil? && bucket_by == "user_id"
+        bucket_by = serve.bucket_by || "user_id"
+        # "user_id" and "userId" resolve the same identity (user_id first).
+        bucket_value = ContextAttribute.resolve(context, bucket_by)
         bucket_value_str =
-          if bucket_value.nil? then ""
+          # An Array or Hash (a JSON array or object, empty or not) has no spelling every
+          # SDK shares, so it can't be bucketed, like a missing value (#4572).
+          if bucket_value.nil? || bucket_value.is_a?(Array) || bucket_value.is_a?(Hash) then ""
           elsif bucket_value.is_a?(Float) then CanonicalNumber.format(bucket_value)
           elsif defined?(::BigDecimal) && bucket_value.is_a?(::BigDecimal) then CanonicalNumber.format_big_decimal(bucket_value)
           else bucket_value.to_s
@@ -196,7 +197,7 @@ module Featureflip
         # empty key. Mirrors the engine + C#/Java SDK evaluators.
         return serve.variation || "" if (serve.variations || []).empty?
 
-        # A missing, nil or empty bucket value can't be bucketed: return nil so the caller
+        # A missing, nil, empty or non-scalar bucket value can't be bucketed: return nil so the caller
         # skips the rule (or serves the fallthrough's variation) instead of hashing the empty
         # string into an arbitrary bucket. Whitespace, "0", 0 and false bucket normally (#4236).
         return nil if bucket_value_str == ""

data/lib/featureflip/shared_core.rb

@@ -45,6 +45,7 @@ module Featureflip
                 "Using existing configuration. Close all handles first to apply new config."
               )
             end
+            _warn_snapshot_options_ignored(existing._config, config)
             return existing
           else
             # Stale entry — remove and replace
@@ -58,6 +59,22 @@ module Featureflip
       end
     end
 
+    # The snapshot store is honored on the first get per SDK key. A later get that
+    # passes a different store instance, or an explicit different max age, is told so.
+    # An omitted store or max age is not a request, so a wrapper that does not forward
+    # them never triggers the warning.
+    def self._warn_snapshot_options_ignored(existing, requested)
+      store_differs = !requested.snapshot_store.nil? && !requested.snapshot_store.equal?(existing.snapshot_store)
+      age_differs = requested.max_snapshot_age_explicit? &&
+                    requested.max_snapshot_age_seconds != existing.max_snapshot_age_seconds
+      return unless store_differs || age_differs
+
+      requested.logger&.warn(
+        "Featureflip: snapshot_store/max_snapshot_age_seconds option ignored because a client " \
+        "for this SDK key already exists. Close all handles first to apply it."
+      )
+    end
+
     def self._create_for_testing(flags)
       core = allocate
       core.send(:init_test_mode, flags)
@@ -75,9 +92,20 @@ module Featureflip
 
     # --- Instance methods ---
 
-    def initialize(sdk_key:, config:)
+    # Wall and monotonic clocks, injectable so the refresh rule is testable without
+    # waiting minutes.
+    # @api private
+    Clock = Struct.new(:wall_ms, :monotonic)
+    SYSTEM_CLOCK = Clock.new(
+      -> { (Time.now.to_f * 1000).to_i },
+      -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+    ).freeze
+
+    def initialize(sdk_key:, config:, clock: SYSTEM_CLOCK)
       @sdk_key = sdk_key
       @config = config
+      @clock = clock
+      init_snapshot_state
       # Snapshot the (already-filtered) inspector list at construction: config is
       # immutable-after-init from the core's point of view, so the evaluation path
       # needs no locking. Deliberately excluded from _configs_equal -- callables
@@ -147,6 +175,12 @@ module Featureflip
       @initialized
     end
 
+    # Where the flag data came from: live, a stored snapshot, or nowhere. Moves to
+    # live on the first successful full live apply.
+    def startup_info
+      @startup || StartupInfo.new(Snapshot::SOURCE_LIVE)
+    end
+
     # --- Evaluation methods ---
 
     # The typed accessors declare the JSON type they expect so a mismatch degrades
@@ -298,6 +332,9 @@ module Featureflip
       # would leave a restarted non-streaming core with no data source at all.
       @streaming_handler = nil
       @polling_handler = nil
+      # A forked child has no writer thread, so a slot the parent claimed would stay
+      # claimed forever and wedge persistence.
+      reset_write_slot
 
       if @config.streaming
         start_streaming
@@ -339,7 +376,7 @@ module Featureflip
       end
       @event_processor = nil
 
-      @config.logger&.info("Featureflip: core shut down for SDK key #{@sdk_key}")
+      @config.logger&.info("Featureflip: core shut down")
     end
 
     def bootstrap!
@@ -349,18 +386,118 @@ module Featureflip
       start_event_processor if @config.send_events
     end
 
+    # Without a snapshot store a failure raises InitializationError, as before. With
+    # one, the failure falls back to the stored snapshot (or defaults) and init
+    # completes; the data source started afterwards keeps trying and recovers.
     def fetch_initial_flags
-      Timeout.timeout(@config.init_timeout) do
-        flags, segments = @http_client.get_flags
-        @store.init(flags, segments)
-        @initialized = true
+      # Only the fetch is under the timeout. Applying inside it would let a timeout that
+      # lands after a successful fetch fall back to a snapshot over live data.
+      flags, segments = Timeout.timeout(@config.init_timeout) { @http_client.get_flags }
+      # Establishes the baseline; fires nothing (the store has no snapshot yet).
+      apply_snapshot(flags, segments)
+      @initialized = true
+    rescue Timeout::Error => e
+      if @config.snapshot_store.nil?
+        raise InitializationError, "Initialization timed out after #{@config.init_timeout}s"
       end
-    rescue Timeout::Error
-      raise InitializationError, "Initialization timed out after #{@config.init_timeout}s"
+
+      fall_back_to_snapshot(e, timed_out: true)
     rescue InitializationError
       raise
     rescue StandardError => e
-      raise InitializationError, "Failed to initialize: #{e.message}"
+      raise InitializationError, "Failed to initialize: #{e.message}" if @config.snapshot_store.nil?
+
+      fall_back_to_snapshot(e, timed_out: false)
+    end
+
+    def fall_back_to_snapshot(error, timed_out:)
+      load_snapshot_fallback(describe_init_failure(error, timed_out))
+      @initialized = true
+    end
+
+    # A short, key-free reason the initial fetch failed. A revoked key (HTTP 401/403)
+    # must read differently from an unreachable host.
+    def describe_init_failure(error, timed_out)
+      return "timed out after #{@config.init_timeout}s" if timed_out
+      return "HTTP #{error.status}" if error.respond_to?(:status) && error.status.is_a?(Integer)
+
+      message = error.message.to_s
+      message.empty? ? error.class.name : message
+    end
+
+    # Read the store on a thread, bounded by init_timeout. Returns [finished, value].
+    # A raising store is a miss (warned). A read still running at the deadline is
+    # abandoned and its late result ignored.
+    def read_snapshot_store(cause)
+      store = @config.snapshot_store
+      box = {}
+      reader = Thread.new do
+        box[:value] = store.get
+      rescue StandardError, ScriptError => e
+        box[:error] = e
+      end
+      reader.report_on_exception = false
+      unless reader.join(@config.init_timeout)
+        @config.logger&.warn(
+          "Featureflip: initial flag fetch failed (#{cause}) and the snapshot store read timed out " \
+          "after #{@config.init_timeout}s; serving defaults"
+        )
+        return [false, nil]
+      end
+      if box.key?(:error)
+        @config.logger&.warn(
+          "Featureflip: initial flag fetch failed (#{cause}) and the snapshot store read failed: " \
+          "#{box[:error].message}; serving defaults"
+        )
+        return [true, nil]
+      end
+      [true, box[:value]]
+    end
+
+    # Serve the stored snapshot after a failed initial fetch. Never raises. Applied
+    # without persisting, so loading it does not refresh its own fetchedAt. The store
+    # hands back opaque text; every check and every reason is decided here.
+    def load_snapshot_fallback(cause)
+      finished, value = read_snapshot_store(cause)
+      return unless finished # the read already warned
+
+      if value.nil? # a plain miss: no reason
+        @config.logger&.warn(
+          "Featureflip: initial flag fetch failed (#{cause}); no persisted snapshot; serving defaults"
+        )
+        return
+      end
+
+      now = @clock.wall_ms.call
+      begin
+        decoded = Snapshot.decode_envelope(value, @key_hash, now)
+      rescue Snapshot::InvalidError => e
+        reject_snapshot(cause, Snapshot::REASON_INVALID, e.why)
+        return
+      end
+      age_ms = [0, now - decoded.fetched_at_ms].max
+      age_seconds = age_ms / 1000
+      limit = @config.max_snapshot_age_seconds
+      if age_ms > limit * 1000
+        reject_snapshot(cause, Snapshot::REASON_EXPIRED, "#{age_seconds}s old, limit #{limit}s", age_seconds)
+        return
+      end
+
+      @store.init(decoded.flags, decoded.segments)
+      @startup = StartupInfo.new(Snapshot::SOURCE_SNAPSHOT, Snapshot::REASON_SNAPSHOT, age_seconds)
+      @config.logger&.warn(
+        "Featureflip: initial flag fetch failed (#{cause}); serving persisted snapshot (#{age_seconds}s old)"
+      )
+    rescue StandardError => e
+      @config.logger&.warn("Featureflip: snapshot load failed: #{e.class}: #{e.message}")
+    end
+
+    def reject_snapshot(cause, reason, why, age_seconds = nil)
+      @startup = StartupInfo.new(Snapshot::SOURCE_NONE, reason, age_seconds)
+      @config.logger&.warn(
+        "Featureflip: initial flag fetch failed (#{cause}); ignoring persisted snapshot " \
+        "(#{reason}: #{why}); serving defaults"
+      )
     end
 
     def start_data_source
@@ -382,6 +519,7 @@ module Featureflip
         on_flag_deleted: ->(key) { apply_flag_delete(key) },
         on_segment_updated: ->(flags, segments) { apply_snapshot(flags, segments) },
         on_sync: ->(flags, segments) { apply_snapshot(flags, segments) },
+        on_ping: -> { on_streaming_ping },
         on_error: ->(_err) { },
         on_fallback_to_polling: -> { fallback_to_polling },
         on_recovered: -> { stop_fallback_polling }
@@ -461,15 +599,185 @@ module Featureflip
     # Every data-source write funnels through one of these three so the change
     # set is computed by the store and reported in one place.
     def apply_snapshot(flags, segments)
-      notify_update_listeners(@store.init(flags, segments))
+      changed = @store.init(flags, segments)
+      @startup = StartupInfo.new(Snapshot::SOURCE_LIVE)
+      persist_full
+      notify_update_listeners(changed)
     end
 
     def apply_flag_update(flag)
-      notify_update_listeners(@store.upsert(flag))
+      changed = @store.upsert(flag)
+      persist_delta
+      notify_update_listeners(changed)
     end
 
     def apply_flag_delete(key)
-      notify_update_listeners(@store.remove_flag(key))
+      changed = @store.remove_flag(key)
+      persist_delta
+      notify_update_listeners(changed)
+    end
+
+    # --- Snapshot persistence ---
+
+    def init_snapshot_state
+      @startup = StartupInfo.new(Snapshot::SOURCE_NONE)
+      @key_hash = Snapshot.compute_key_hash(@config.base_url, @sdk_key)
+      @snapshot_mutex = Mutex.new
+      @persist_in_flight = false
+      @persist_queued = false
+      @last_persist_at = nil
+      @last_persisted_data = nil
+    end
+
+    def snapshot_store
+      @config.snapshot_store
+    end
+
+    def snapshot_stopped?
+      @closed || @shut_down
+    end
+
+    def within_refresh_window?
+      last = @snapshot_mutex.synchronize { @last_persist_at }
+      !last.nil? && @clock.monotonic.call - last < Snapshot::REFRESH_INTERVAL_SECONDS
+    end
+
+    def serialize_state
+      Snapshot.serialize_flags_payload(@store.all_flags, @store.all_segments)
+    end
+
+    # After a single-flag delta, only once live: never right after a snapshot or
+    # none start, or stale data would get a fresh fetchedAt.
+    def persist_delta
+      persist if !snapshot_store.nil? && @startup.source == Snapshot::SOURCE_LIVE
+    end
+
+    # After a full live apply. Changed content is written at once. An unchanged state
+    # is only rewritten once the last write is a refresh interval old.
+    def persist_full
+      return if snapshot_store.nil? || snapshot_stopped?
+
+      if within_refresh_window?
+        begin
+          data = serialize_state
+        rescue StandardError => e
+          @config.logger&.warn("Featureflip: snapshot persist failed: #{e.class}: #{e.message}")
+          return
+        end
+        return if @snapshot_mutex.synchronize { data == @last_persisted_data }
+      end
+      persist
+    end
+
+    # The stream heartbeat: while live, refresh the stored fetchedAt at most once per
+    # refresh interval, so a healthy streaming client does not let its snapshot age out.
+    def on_streaming_ping
+      return if snapshot_store.nil? || @startup.source != Snapshot::SOURCE_LIVE
+      return if within_refresh_window?
+
+      persist
+    end
+
+    # Write the full state without blocking evaluation or init: at most one put in
+    # flight plus one trailing write, which reads the state when it runs.
+    def persist
+      return if snapshot_store.nil? || snapshot_stopped?
+
+      claimed = @snapshot_mutex.synchronize do
+        if @persist_in_flight
+          @persist_queued = true
+          false
+        else
+          @persist_in_flight = true
+        end
+      end
+      return unless claimed
+
+      @writer_started = false
+      begin
+        text = build_snapshot_text || finish_persist
+        if text.nil?
+          @writer_started = true # finish_persist already released the slot
+          return
+        end
+
+        start_write_thread(text)
+      rescue StandardError, ScriptError => e
+        # Can't start a thread. Don't leave the in-flight flag set, or every later
+        # write is wedged, and never let this escape into an apply.
+        @config.logger&.warn("Featureflip: snapshot persist failed: #{e.class}: #{e.message}")
+      ensure
+        # Also covers an Exception that is not a StandardError (a Timeout or stream
+        # stop landing here), which propagates after the slot is released.
+        reset_write_slot unless @writer_started
+      end
+    end
+
+    def reset_write_slot
+      @snapshot_mutex.synchronize do
+        @persist_in_flight = false
+        @persist_queued = false
+      end
+    end
+
+    def start_write_thread(text)
+      thread = Thread.new { persist_worker(text) }
+      # Marked the instant the thread exists: from here the writer owns the slot, so an
+      # exception landing later must not release it (that would allow a second writer).
+      @writer_started = true
+      silence_thread_report(thread)
+      thread
+    end
+
+    def silence_thread_report(thread)
+      thread.report_on_exception = false
+    end
+
+    # The envelope for the current state, stamped now. Never raises.
+    def build_snapshot_text
+      fetched_at = @clock.wall_ms.call
+      data = serialize_state
+      @snapshot_mutex.synchronize do
+        @last_persist_at = @clock.monotonic.call
+        @last_persisted_data = data
+      end
+      Snapshot.encode_envelope(@key_hash, fetched_at, data)
+    rescue StandardError => e
+      @config.logger&.warn("Featureflip: snapshot persist failed: #{e.class}: #{e.message}")
+      nil
+    end
+
+    # End one write. Returns the next envelope if a trailing write is due. No trailing
+    # write starts once the core is shut down.
+    def finish_persist
+      loop do
+        proceed = @snapshot_mutex.synchronize do
+          if @persist_queued && !snapshot_stopped?
+            @persist_queued = false
+            true
+          else
+            @persist_queued = false
+            @persist_in_flight = false
+            false
+          end
+        end
+        return nil unless proceed
+
+        text = build_snapshot_text
+        return text unless text.nil?
+      end
+    end
+
+    def persist_worker(text)
+      store = snapshot_store
+      until text.nil?
+        begin
+          store.put(text)
+        rescue StandardError, ScriptError => e
+          @config.logger&.warn("Featureflip: snapshot store write failed: #{e.class}: #{e.message}")
+        end
+        text = finish_persist
+      end
     end
 
     # Runs on the streaming/polling thread, OUTSIDE the store lock: listeners are
@@ -601,6 +909,9 @@ module Featureflip
     def init_test_mode(flags)
       @sdk_key = "test-key"
       @config = Config.new
+      @clock = SYSTEM_CLOCK
+      init_snapshot_state
+      @startup = StartupInfo.new(Snapshot::SOURCE_LIVE)
       @inspectors = []
       @store = Store::FlagStore.new
       @evaluator = Evaluation::Evaluator.new(logger: @config.logger)
@@ -633,6 +944,6 @@ module Featureflip
         a.send_events == b.send_events
     end
 
-    private_class_method :_configs_equal
+    private_class_method :_configs_equal, :_warn_snapshot_options_ignored
   end
 end

data/lib/featureflip/snapshot.rb

@@ -0,0 +1,256 @@
+require "digest"
+require "json"
+require "logger"
+require "securerandom"
+
+module Featureflip
+  # Where the client's flag data came from at startup.
+  #
+  # source: Snapshot::SOURCE_LIVE ("live") after a successful fetch from the
+  #   Evaluation API, Snapshot::SOURCE_SNAPSHOT ("snapshot") when started from the
+  #   snapshot store, Snapshot::SOURCE_NONE ("none") when there is no data yet
+  #   (caller defaults are served).
+  # reason: "snapshot" for a snapshot start, "snapshot-expired" or
+  #   "snapshot-invalid" when a stored snapshot was ignored. nil once the client is
+  #   live, or when nothing was stored.
+  # snapshot_age_seconds: age of the snapshot that was used or rejected as
+  #   expired, in whole seconds.
+  StartupInfo = Struct.new(:source, :reason, :snapshot_age_seconds) do
+    def initialize(source, reason = nil, snapshot_age_seconds = nil)
+      super
+      freeze
+    end
+  end
+
+  # Opaque text store for the last good flag snapshot (a duck type, not a base
+  # class). Implement two methods:
+  #
+  #   get       -> the String last stored, or nil if nothing is stored
+  #   put(text) -> store the String, replacing any previous value
+  #
+  # Both may be called from a background thread. A store that raises is handled: a
+  # failing get is a miss and a failing put is a dropped write, each with a logged
+  # warning. The SDK owns the stored text end to end (envelope, environment check,
+  # age check and every startup reason), so one store instance may safely be given
+  # to several SDK keys.
+  #
+  # Everything on Snapshot except the constants is internal (@api private): the
+  # public surface is the store contract above, FileSnapshotStore, StartupInfo and
+  # Config#snapshot_store.
+  module Snapshot
+    # StartupInfo#source values.
+    SOURCE_LIVE = "live".freeze
+    SOURCE_SNAPSHOT = "snapshot".freeze
+    SOURCE_NONE = "none".freeze
+
+    # StartupInfo#reason values.
+    REASON_SNAPSHOT = "snapshot".freeze
+    REASON_EXPIRED = "snapshot-expired".freeze
+    REASON_INVALID = "snapshot-invalid".freeze
+
+    # How far in the future a stored fetchedAt may be (clock skew between the writer
+    # and the reader) and still be accepted, with its age clamped to 0.
+    FUTURE_FETCHED_AT_TOLERANCE_MS = 60_000
+
+    # While live, an unchanged state is rewritten (refreshing fetchedAt) at most
+    # this often. Changed content is never throttled.
+    REFRESH_INTERVAL_SECONDS = 300.0
+
+    # Stored text failed a check. +why+ names the check, never the contents or key.
+    class InvalidError < StandardError
+      attr_reader :why
+
+      def initialize(why)
+        super(why)
+        @why = why
+      end
+    end
+
+    Decoded = Struct.new(:flags, :segments, :fetched_at_ms, keyword_init: true)
+
+    NullConfig = Struct.new(:logger, :base_url)
+    private_constant :NullConfig
+
+    # Identify the (base URL, SDK key) pair without storing the key.
+    def self.compute_key_hash(base_url, sdk_key)
+      Digest::SHA256.hexdigest("#{base_url.to_s.sub(%r{/+\z}, "")}\n#{sdk_key}")
+    end
+
+    # The stored text, from an already serialized +data+.
+    def self.encode_envelope(key_hash, fetched_at_ms, data_text)
+      "{\"v\":1,\"keyHash\":#{JSON.generate(key_hash)},\"fetchedAt\":#{Integer(fetched_at_ms)},\"data\":#{data_text}}"
+    end
+
+    # Parse and check stored text. Age is not checked here.
+    # Raises InvalidError for any failed check, in the pinned order.
+    def self.decode_envelope(text, key_hash, now_ms)
+      raise InvalidError, "store returned a non-string value" unless text.is_a?(String)
+
+      begin
+        env = JSON.parse(text)
+      rescue StandardError
+        raise InvalidError, text.empty? ? "empty text" : "not valid JSON"
+      end
+      raise InvalidError, "not a snapshot envelope" unless env.is_a?(Hash)
+
+      version = env["v"]
+      unless version.is_a?(Numeric) && version == 1
+        raise InvalidError, "unsupported envelope version"
+      end
+      raise InvalidError, "written for a different SDK key or base URL" unless env["keyHash"] == key_hash
+
+      fetched_at = positive_integer(env["fetchedAt"])
+      raise InvalidError, "fetchedAt is not a positive integer" if fetched_at.nil?
+      raise InvalidError, "fetchedAt is in the future" if fetched_at > now_ms + FUTURE_FETCHED_AT_TOLERANCE_MS
+
+      data = env["data"]
+      raise InvalidError, "missing data" unless data.is_a?(Hash)
+
+      begin
+        raise ArgumentError, "flags and segments must be arrays" unless data["flags"].is_a?(Array) && data["segments"].is_a?(Array)
+
+        flags, segments = payload_parser.parse_flags_response(data)
+      rescue StandardError
+        raise InvalidError, "data failed payload validation"
+      end
+      Decoded.new(flags: flags, segments: segments, fetched_at_ms: fetched_at)
+    end
+
+    def self.positive_integer(value)
+      case value
+      when Integer then value.positive? ? value : nil
+      when Float then value.finite? && value == value.floor && value.positive? ? value.to_i : nil
+      end
+    end
+
+    # The SDK's own live-payload parser (so the same wholesale-discard validation
+    # and unevaluable-entity drops apply), with logging off.
+    def self.payload_parser
+      Http::Client.new(nil, NullConfig.new(nil, ""))
+    end
+
+    # --- Serialization (in-memory state back to the /v1/sdk/flags wire shape) ---
+    #
+    # The models hold the wire spelling already (Boolean/Fixed/Rollout, And/Or, ...;
+    # an unknown value is kept verbatim), so this only renames fields. Flags and
+    # segments are sorted by key and the property order is fixed: the unchanged-state
+    # comparison relies on a deterministic text.
+
+    def self.serialize_flags_payload(flags, segments)
+      JSON.generate(
+        "flags" => flags.sort_by { |f| f.key.to_s }.map { |f| wire_flag(f) },
+        "segments" => segments.sort_by { |s| s.key.to_s }.map { |s| wire_segment(s) }
+      )
+    end
+
+    def self.wire_condition(c)
+      { "attribute" => c.attribute, "operator" => c.operator, "values" => c.values, "negate" => c.negate }
+    end
+
+    def self.wire_group(g)
+      { "operator" => g.operator, "conditions" => g.conditions.map { |c| wire_condition(c) } }
+    end
+
+    def self.wire_serve(s)
+      out = { "type" => s.type }
+      out["variation"] = s.variation unless s.variation.nil?
+      out["bucketBy"] = s.bucket_by unless s.bucket_by.nil?
+      out["salt"] = s.salt unless s.salt.nil?
+      unless s.variations.nil?
+        out["variations"] = s.variations.map { |v| { "key" => v.key, "weight" => v.weight } }
+      end
+      out
+    end
+
+    def self.wire_rule(r)
+      out = {
+        "id" => r.id,
+        "priority" => r.priority,
+        "conditionGroups" => r.condition_groups.map { |g| wire_group(g) },
+        "serve" => wire_serve(r.serve)
+      }
+      out["segmentKey"] = r.segment_key unless r.segment_key.nil?
+      out
+    end
+
+    def self.wire_flag(f)
+      {
+        "key" => f.key,
+        "version" => f.version,
+        "type" => f.type,
+        "enabled" => f.enabled,
+        "variations" => f.variations.map { |v| { "key" => v.key, "value" => v.value } },
+        "rules" => f.rules.map { |r| wire_rule(r) },
+        "fallthrough" => wire_serve(f.fallthrough),
+        "offVariation" => f.off_variation,
+        "prerequisites" => f.prerequisites.map do |p|
+          { "prerequisiteFlagKey" => p.prerequisite_flag_key, "expectedVariationKey" => p.expected_variation_key }
+        end
+      }
+    end
+
+    def self.wire_segment(s)
+      {
+        "key" => s.key,
+        "version" => s.version,
+        "conditions" => s.conditions.map { |c| wire_condition(c) },
+        "conditionLogic" => s.condition_logic
+      }
+    end
+
+    private_class_method :positive_integer, :payload_parser, :wire_condition, :wire_group,
+                         :wire_serve, :wire_rule, :wire_flag, :wire_segment
+  end
+
+  # Persist the snapshot text to one file (mode 0600), written atomically.
+  #
+  # The store is opaque: it neither parses nor checks what it holds, so one instance
+  # can be shared by several SDK keys. It never raises: a failure is logged and
+  # treated as a miss (get) or a dropped write (put). The parent directory must
+  # already exist; it is never created.
+  #
+  # There is deliberately no fsync before the rename, so a power loss can leave a
+  # zero-length or partial file. The SDK reads that as "snapshot-invalid", logs a
+  # warning and serves defaults, and the next successful write replaces it.
+  #
+  # A write runs on a background thread, so a process killed mid-write can leave a
+  # "<name>.<pid>.<hex>.tmp" file next to the snapshot. It is never read.
+  #
+  # Owner-only permissions are POSIX semantics; on Windows the file mode bits are
+  # not enforced and the file inherits the directory's access control list.
+  class FileSnapshotStore
+    def initialize(path, logger: nil)
+      @path = path.to_s
+      @logger = logger || ::Logger.new($stderr, level: ::Logger::WARN)
+    end
+
+    def get
+      File.binread(@path).force_encoding(Encoding::UTF_8).scrub
+    rescue Errno::ENOENT
+      nil
+    rescue StandardError => e
+      @logger.warn("Featureflip: snapshot file read failed (#{@path}): #{e.class}: #{e.message}")
+      nil
+    end
+
+    def put(text)
+      tmp = "#{@path}.#{Process.pid}.#{SecureRandom.hex(6)}.tmp"
+      begin
+        File.open(tmp, File::WRONLY | File::CREAT | File::EXCL, 0o600) do |f|
+          f.binmode
+          f.write(text.to_s.encode(Encoding::UTF_8))
+          f.flush
+        end
+        File.rename(tmp, @path)
+      rescue StandardError => e
+        @logger.warn("Featureflip: snapshot file write failed (#{@path}): #{e.class}: #{e.message}")
+        begin
+          File.unlink(tmp)
+        rescue StandardError
+          # nothing left to clean up
+        end
+      end
+      nil
+    end
+  end
+end

data/lib/featureflip/store/flag_store.rb

@@ -36,6 +36,10 @@ module Featureflip
         @mutex.synchronize { @flags.values }
       end
 
+      def all_segments
+        @mutex.synchronize { @segments.values }
+      end
+
       def all_flags_map
         @mutex.synchronize { @flags.dup }
       end

data/lib/featureflip/version.rb

@@ -1,3 +1,3 @@
 module Featureflip
-  VERSION = "2.13.0"
+  VERSION = "2.14.0"
 end

data/lib/featureflip.rb

@@ -12,6 +12,7 @@ require_relative "featureflip/evaluation/evaluator"
 require_relative "featureflip/store/update_diff"
 require_relative "featureflip/store/flag_store"
 require_relative "featureflip/http/client"
+require_relative "featureflip/snapshot"
 require_relative "featureflip/events/event"
 require_relative "featureflip/events/event_processor"
 require_relative "featureflip/data_source/streaming"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: featureflip
 version: !ruby/object:Gem::Version
-  version: 2.13.0
+  version: 2.14.0
 platform: ruby
 authors:
 - Featureflip
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-27 00:00:00.000000000 Z
+date: 2026-11-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logger
@@ -81,6 +81,7 @@ files:
 - lib/featureflip/evaluation/bucketing.rb
 - lib/featureflip/evaluation/canonical_number.rb
 - lib/featureflip/evaluation/condition_evaluator.rb
+- lib/featureflip/evaluation/context_attribute.rb
 - lib/featureflip/evaluation/evaluator.rb
 - lib/featureflip/evaluation/unbucketable_warnings.rb
 - lib/featureflip/events/event.rb
@@ -92,6 +93,7 @@ files:
 - lib/featureflip/models/segment.rb
 - lib/featureflip/sdk_identity.rb
 - lib/featureflip/shared_core.rb
+- lib/featureflip/snapshot.rb
 - lib/featureflip/store/flag_store.rb
 - lib/featureflip/store/update_diff.rb
 - lib/featureflip/version.rb