featureflip 2.13.1 → 2.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c4c086d9a3b50763d562f2a79ef07aa449ddbdb1b88446d8fee98948d7c3933c
-  data.tar.gz: bf96d5faeb953a5219f1de18d5ff85d404b5fbf3daa783550b3b64837b0c72bc
+  metadata.gz: 2abe9cc6f772c5d01773b0c34ecd9de2323fb7f7228ebbe7806ca88967ce60c6
+  data.tar.gz: 37ba38ab6f4c4dd207119f6e292b0fa45131b721ab7c63616a7e26a7b0defc87
 SHA512:
-  metadata.gz: 2a2a87d48a71704a9b2885885a55c74f664497be27703bb4dcb83463756347f771803cfa6608f2c2512b8cff19a982a21ab72d76c52ec53a45fd3d5187f02f45
-  data.tar.gz: be23805658d9ce4f0ba3c4a49f0fde25ea8e2e05e0da8497ab4ec94b557ee9d554b1ed870782acf6df2cbe8476bc5691ae8728eb4438a1259b304c09d91fc4fa
+  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/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.1"
+  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.1
+  version: 2.14.0
 platform: ruby
 authors:
 - Featureflip
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-30 00:00:00.000000000 Z
+date: 2026-11-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logger
@@ -93,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