flipper-firebase_remote_config 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 532ea32e91582a6ec5e68d328a951e98f5477137726cff2a177e53545f9b2d02
+  data.tar.gz: feaa5358f7005276dc1421370824fb55294319b85209e2c80a70e7816a8dbd79
+SHA512:
+  metadata.gz: 2b08ecc82798840db761e5ccce7eab46e5adb0ccff42fde2329c0f44fb93c979811cc258225ab76289d2aac59755f1b009ea2fc4e2e7aae135f4653b51d4391c
+  data.tar.gz: 584edf4b6539b719974469fe9893982c2ae1563921979cc03d235aaeb6ead4b7a30a9395d814b63b6a26a21509e72329514fa02dfa7a1e2786386b7db3c917d6

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Added
+- Initial Flipper adapter targeting the Firebase Remote Config v1 REST API.
+- One Remote Config parameter per feature (prefix configurable, default
+  `flipper__`), with an `__index__` sentinel parameter listing known feature
+  keys.
+- In-process template + ETag cache with a configurable TTL (default 30s) and a
+  `#reload!` method to force-refresh.
+- Optimistic-concurrency retry: one retry on HTTP 409/412 then re-raise.
+- Service-account authentication via `googleauth`.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DevOps Health
+
+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,128 @@
+# flipper-firebase_remote_config
+
+A [Flipper](https://www.flippercloud.io/docs) adapter that stores feature state
+in [Firebase Remote Config](https://firebase.google.com/docs/remote-config).
+Useful when you want flags reachable from both your Ruby backend and your
+Firebase-using mobile / web clients without standing up a separate flag store.
+
+## Read this first — when not to use it
+
+Firebase Remote Config is **eventually consistent** and **rate-limited for
+writes** (Firebase publishes a daily write quota per project, on the order of
+hundreds of writes/day). This makes it a poor fit for:
+
+- Per-request flag flipping
+- High-frequency A/B test ramping
+- Anything that depends on a write being visible immediately
+
+It is a good fit for low-frequency operational toggles that you want a single
+source of truth for across server and client platforms.
+
+**Always wrap this adapter with [`Flipper::Adapters::Memoizable`](https://www.flippercloud.io/docs/adapters/memoizable)
+or the per-request `Flipper::Middleware::Memoizer`** to avoid a Remote Config
+fetch on every flag check.
+
+## Installation
+
+```ruby
+# Gemfile
+gem 'flipper-firebase_remote_config'
+```
+
+## Configuration
+
+```ruby
+require 'flipper'
+require 'flipper/adapters/firebase_remote_config'
+require 'flipper/adapters/memoizable'
+
+Flipper.configure do |config|
+  config.adapter do
+    base = Flipper::Adapters::FirebaseRemoteConfig.new(
+      project_id:  ENV.fetch('FIREBASE_PROJECT_ID'),
+      credentials: ENV.fetch('GOOGLE_APPLICATION_CREDENTIALS'), # path to service-account JSON
+      prefix:      'flipper__',  # optional, default 'flipper__'
+      cache_ttl:   30,           # optional, default 30 seconds
+    )
+    Flipper::Adapters::Memoizable.new(base)
+  end
+end
+```
+
+The service account needs the **Firebase Remote Config Admin** role (or
+equivalent custom role granting `cloudconfig.configs.get` and
+`cloudconfig.configs.update`).
+
+`credentials` accepts:
+
+- A file path to a service-account JSON key (`String`)
+- An open `IO`/`StringIO` containing service-account JSON
+- A pre-built `Google::Auth::*` credentials object
+- `nil` to fall back to Application Default Credentials
+
+## Storage layout
+
+Each Flipper feature becomes one Remote Config parameter, named
+`<prefix><feature_key>`. The parameter's `defaultValue.value` is a JSON blob
+representing the gate state:
+
+```json
+{
+  "boolean": "true",
+  "actors": ["1", "2"],
+  "groups": ["admins"],
+  "percentage_of_actors": "25",
+  "percentage_of_time": null
+}
+```
+
+A sentinel parameter `<prefix>__index__` holds a JSON array of all known
+feature keys, so listing features doesn't have to scan every parameter.
+
+## Concurrency and retries
+
+Remote Config uses ETag-based optimistic concurrency. The adapter:
+
+1. Fetches the template + ETag (cached for `cache_ttl` seconds).
+2. Mutates the template in memory.
+3. Publishes with `If-Match: <etag>`.
+4. On a `412 Precondition Failed`, reloads and retries **once**. If the retry
+   also fails, `Flipper::Adapters::FirebaseRemoteConfig::ETagMismatch` is
+   raised.
+
+If you have a write-heavy multi-process workload that frequently conflicts,
+this adapter is the wrong tool.
+
+## Not yet supported
+
+- **Remote Config conditions.** Firebase Remote Config has a powerful
+  conditional value system (per-platform, per-country, per-user-property). v0.1
+  ignores it: every gate is stored as the parameter's `defaultValue` only. If
+  you change a parameter's `conditionalValues` in the Firebase console, the
+  adapter will not see those changes. Conditions may be exposed as a Flipper
+  extension in a future release; PRs welcome.
+- **Server-side caching beyond the adapter's in-process TTL.** Combine with
+  `Flipper::Adapters::Memoizable` and ideally a longer-lived cache (Redis,
+  Memcached) for high-traffic apps.
+
+## Why this gem talks REST directly
+
+The Firebase Remote Config v1 API does not have a generated Ruby client gem
+(`google-apis-firebaseremoteconfig_v1` is not published to RubyGems, and the
+deprecated umbrella `google-api-client` does not include it either). So the
+two REST calls we actually need (`GET` + `PUT` on
+`/v1/projects/{id}/remoteConfig`) go through `Net::HTTP` directly. Auth is
+real: we depend on [`googleauth`](https://github.com/googleapis/google-auth-library-ruby)
+for the OAuth2 service-account flow. See `CLAUDE.md` for the longer story.
+
+## Development
+
+```sh
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT.

data/lib/flipper/adapters/firebase_remote_config/client.rb

@@ -0,0 +1,127 @@
+require 'json'
+require 'net/http'
+require 'uri'
+require 'googleauth'
+
+module Flipper
+  module Adapters
+    class FirebaseRemoteConfig
+      class Error < StandardError; end
+      class ETagMismatch < Error; end
+
+      SCOPE        = 'https://www.googleapis.com/auth/firebase.remoteconfig'.freeze
+      API_HOST     = 'firebaseremoteconfig.googleapis.com'.freeze
+      OPEN_TIMEOUT = 5
+      READ_TIMEOUT = 15
+
+      # Thin REST wrapper around the Firebase Remote Config v1 API.
+      #
+      # Why hand-rolled instead of a generated client: there is no published
+      # service gem for `firebaseremoteconfig_v1` — neither bundled inside the
+      # (deprecated) `google-api-client` umbrella, nor as a stand-alone
+      # `google-apis-firebaseremoteconfig_v1`. We use `googleauth` directly
+      # for the OAuth2 service-account flow, and Net::HTTP for the two
+      # endpoints we actually need.
+      class Client
+        attr_reader :project_id
+
+        def initialize(project_id:, credentials: nil, http: nil)
+          @project_id  = project_id
+          @credentials = build_credentials(credentials)
+          @http        = http # injection seam for tests
+        end
+
+        # Returns [template_hash, etag_string]. The template is the parsed JSON
+        # body as a Hash; etag is the opaque string from the ETag response
+        # header, which the server demands back on the next write.
+        def fetch_template
+          response = request(:get, template_path)
+          ensure_success!(response)
+          [JSON.parse(response.body), response['ETag']]
+        end
+
+        # Publishes a modified template. Raises ETagMismatch on 409/412 so the
+        # adapter can reload and retry; raises Error on any other failure.
+        def publish_template(template, etag)
+          response = request(
+            :put,
+            template_path,
+            body: JSON.generate(template),
+            headers: { 'Content-Type' => 'application/json; UTF-8',
+                       'If-Match' => etag || '*' }
+          )
+          raise ETagMismatch, response.body if etag_conflict?(response)
+
+          ensure_success!(response)
+          response
+        end
+
+        private
+
+        def template_path
+          "/v1/projects/#{@project_id}/remoteConfig"
+        end
+
+        def request(method, path, body: nil, headers: {})
+          uri = URI("https://#{API_HOST}#{path}")
+          req_class = method == :get ? Net::HTTP::Get : Net::HTTP::Put
+          req = req_class.new(uri)
+          headers.each { |k, v| req[k] = v }
+          @credentials&.apply!(req.to_hash.merge('Authorization' => nil))
+          token = fetch_access_token
+          req['Authorization'] = "Bearer #{token}" if token
+          req.body = body if body
+
+          http_for(uri).request(req)
+        end
+
+        def http_for(uri)
+          return @http if @http
+
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = true
+          http.open_timeout = OPEN_TIMEOUT
+          http.read_timeout = READ_TIMEOUT
+          http
+        end
+
+        def fetch_access_token
+          return nil unless @credentials
+
+          @credentials.fetch_access_token! unless @credentials.access_token
+          @credentials.access_token
+        end
+
+        def build_credentials(credentials)
+          case credentials
+          when String
+            ::Google::Auth::ServiceAccountCredentials.make_creds(
+              json_key_io: File.open(credentials),
+              scope: SCOPE
+            )
+          when IO, StringIO
+            ::Google::Auth::ServiceAccountCredentials.make_creds(
+              json_key_io: credentials,
+              scope: SCOPE
+            )
+          when nil
+            ::Google::Auth.get_application_default([SCOPE])
+          else
+            credentials
+          end
+        end
+
+        def etag_conflict?(response)
+          [409, 412].include?(response.code.to_i)
+        end
+
+        def ensure_success!(response)
+          return if (200..299).cover?(response.code.to_i)
+
+          raise Error,
+                "Firebase Remote Config API error #{response.code}: #{response.body}"
+        end
+      end
+    end
+  end
+end

data/lib/flipper/adapters/firebase_remote_config/version.rb

@@ -0,0 +1,7 @@
+module Flipper
+  module Adapters
+    class FirebaseRemoteConfig
+      VERSION = '0.0.1'.freeze
+    end
+  end
+end

data/lib/flipper/adapters/firebase_remote_config.rb

@@ -0,0 +1,266 @@
+require 'json'
+require 'set'
+require 'flipper'
+require 'flipper/adapters/firebase_remote_config/version'
+require 'flipper/adapters/firebase_remote_config/client'
+
+module Flipper
+  module Adapters
+    # Flipper adapter that stores feature state as Firebase Remote Config
+    # parameters. One parameter per feature; an index parameter tracks the
+    # known feature keys so listing doesn't have to scan the whole template.
+    #
+    # The in-memory representation of a template is the raw API JSON shape:
+    #
+    #   {
+    #     "parameters" => {
+    #       "flipper__search" => {
+    #         "valueType" => "JSON",
+    #         "defaultValue" => { "value" => "{\"boolean\":\"true\",...}" }
+    #       },
+    #       "flipper____index__" => { ... JSON array of feature keys ... }
+    #     },
+    #     "conditions" => [...],
+    #     ...
+    #   }
+    #
+    # See README.md for the rationale and for caveats (eventual consistency,
+    # write quotas, no support for Remote Config conditions in v0.1).
+    class FirebaseRemoteConfig
+      DEFAULT_PREFIX     = 'flipper__'.freeze
+      INDEX_SUFFIX       = '__index__'.freeze
+      DEFAULT_CACHE_TTL  = 30 # seconds
+
+      attr_reader :name
+
+      def initialize(project_id: nil, credentials: nil, client: nil,
+                     prefix: DEFAULT_PREFIX, cache_ttl: DEFAULT_CACHE_TTL)
+        @name      = :firebase_remote_config
+        @prefix    = prefix
+        @cache_ttl = cache_ttl
+        @client    = client || Client.new(project_id: project_id, credentials: credentials)
+        @cache     = nil
+        @cached_at = nil
+      end
+
+      def features
+        Set.new(index_from(load_template))
+      end
+
+      def add(feature)
+        with_template do |template|
+          ensure_parameter(template, feature.key)
+          add_to_index(template, feature.key)
+        end
+        true
+      end
+
+      def remove(feature)
+        with_template do |template|
+          template['parameters']&.delete(parameter_name(feature.key))
+          remove_from_index(template, feature.key)
+        end
+        true
+      end
+
+      def clear(feature)
+        with_template do |template|
+          write_gates(template, feature.key, default_config)
+        end
+        true
+      end
+
+      def get(feature)
+        read_gates(load_template, feature.key)
+      end
+
+      def get_multi(features)
+        template = load_template
+        features.to_h do |feature|
+          [feature.key, read_gates(template, feature.key)]
+        end
+      end
+
+      def get_all
+        template = load_template
+        index_from(template).to_h do |feature_key|
+          [feature_key, read_gates(template, feature_key)]
+        end
+      end
+
+      def enable(feature, gate, thing)
+        mutate_gates(feature) { |gates| apply_enable_gate(gates, gate, thing) }
+        true
+      end
+
+      def disable(feature, gate, thing)
+        mutate_gates(feature) { |gates| apply_disable_gate(gates, gate, thing) }
+        true
+      end
+
+      # Drop the in-process cache. Call this when you know the template has
+      # drifted (e.g. another process published a new version).
+      def reload!
+        @cache = nil
+        @cached_at = nil
+        self
+      end
+
+      private
+
+      def mutate_gates(feature)
+        with_template do |template|
+          gates = yield(read_gates(template, feature.key))
+          write_gates(template, feature.key, gates)
+          add_to_index(template, feature.key)
+        end
+      end
+
+      def apply_enable_gate(gates, gate, thing)
+        case gate.data_type
+        when :boolean
+          default_config.merge(gate.key => thing.value.to_s)
+        when :integer
+          gates.merge(gate.key => thing.value.to_s)
+        when :set
+          gates.merge(gate.key => (gates[gate.key] || Set.new) | [thing.value.to_s])
+        when :json
+          gates.merge(gate.key => thing.value)
+        else
+          raise ArgumentError, "Unsupported gate data_type: #{gate.data_type.inspect}"
+        end
+      end
+
+      def apply_disable_gate(gates, gate, thing)
+        case gate.data_type
+        when :boolean
+          default_config
+        when :integer
+          gates.merge(gate.key => thing.value.to_s)
+        when :set
+          gates.merge(gate.key => (gates[gate.key] || Set.new) - [thing.value.to_s])
+        when :json
+          gates.merge(gate.key => nil)
+        else
+          raise ArgumentError, "Unsupported gate data_type: #{gate.data_type.inspect}"
+        end
+      end
+
+      def default_config
+        {
+          boolean: nil,
+          actors: Set.new,
+          groups: Set.new,
+          percentage_of_actors: nil,
+          percentage_of_time: nil
+        }
+      end
+
+      def load_template
+        return @cache[:template] if @cache && @cached_at && (Time.now - @cached_at) < @cache_ttl
+
+        template, etag = @client.fetch_template
+        @cache     = { template: template, etag: etag }
+        @cached_at = Time.now
+        template
+      end
+
+      # Mutate the cached template in place inside the block, then publish it.
+      # Retries once on ETag mismatch by reloading and reapplying the block.
+      def with_template
+        attempts = 0
+        begin
+          template = load_template
+          etag     = @cache[:etag]
+          yield template
+          @client.publish_template(template, etag)
+          reload!
+        rescue FirebaseRemoteConfig::ETagMismatch
+          attempts += 1
+          if attempts <= 1
+            reload!
+            retry
+          end
+          raise
+        end
+      end
+
+      def parameter_name(feature_key)
+        "#{@prefix}#{feature_key}"
+      end
+
+      def index_parameter_name
+        "#{@prefix}#{INDEX_SUFFIX}"
+      end
+
+      def index_from(template)
+        raw = parameter_value(template, index_parameter_name)
+        return [] if raw.nil?
+
+        JSON.parse(raw)
+      rescue JSON::ParserError
+        []
+      end
+
+      def add_to_index(template, feature_key)
+        keys = (index_from(template) + [feature_key]).uniq.sort
+        write_parameter(template, index_parameter_name, JSON.generate(keys))
+      end
+
+      def remove_from_index(template, feature_key)
+        keys = index_from(template) - [feature_key]
+        write_parameter(template, index_parameter_name, JSON.generate(keys))
+      end
+
+      def ensure_parameter(template, feature_key)
+        return if (template['parameters'] || {}).key?(parameter_name(feature_key))
+
+        write_gates(template, feature_key, default_config)
+      end
+
+      def read_gates(template, feature_key)
+        raw_json = parameter_value(template, parameter_name(feature_key))
+        return default_config if raw_json.nil?
+
+        raw = JSON.parse(raw_json, symbolize_names: true)
+        deserialize_gates(raw)
+      rescue JSON::ParserError
+        default_config
+      end
+
+      def write_gates(template, feature_key, gates)
+        write_parameter(template, parameter_name(feature_key),
+                        JSON.generate(serialize_gates(gates)))
+      end
+
+      def parameter_value(template, name)
+        param = (template['parameters'] || {})[name]
+        param&.dig('defaultValue', 'value')
+      end
+
+      def write_parameter(template, name, json_value)
+        template['parameters'] ||= {}
+        template['parameters'][name] = {
+          'valueType' => 'JSON',
+          'defaultValue' => { 'value' => json_value }
+        }
+      end
+
+      def serialize_gates(gates)
+        gates.each_with_object({}) do |(key, value), acc|
+          acc[key] = value.is_a?(Set) ? value.to_a : value
+        end
+      end
+
+      def deserialize_gates(raw)
+        default_config.merge(
+          boolean: raw[:boolean],
+          actors: Set.new(Array(raw[:actors])),
+          groups: Set.new(Array(raw[:groups])),
+          percentage_of_actors: raw[:percentage_of_actors],
+          percentage_of_time: raw[:percentage_of_time]
+        )
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: flipper-firebase_remote_config
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Roberto Quintanilla
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: flipper
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: googleauth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Stores Flipper features as Firebase Remote Config parameters, reading
+  and writing via the Firebase Remote Config REST API.
+email:
+- roberto.quintanilla@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/flipper/adapters/firebase_remote_config.rb
+- lib/flipper/adapters/firebase_remote_config/client.rb
+- lib/flipper/adapters/firebase_remote_config/version.rb
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Flipper adapter backed by Firebase Remote Config.
+test_files: []