togglefleet 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 608c0c99556263faeb1c847374977afa7173f249b83062523d80078891b187ca
+  data.tar.gz: 5a498caa5253020f3b096d495801701fba336126cc8e66f5c10e60f7628c5dd1
+SHA512:
+  metadata.gz: 7fc721286453dbda46fae8f0bcebb8a4a8adf22a8aaefd1beefeeddffda82b350ecad4ae39fdc1a26abced744116778a2ff31f8b3deae93b1c18a7a1c3b52bdf
+  data.tar.gz: 28d5b041acb5538a9681bada4c0f1c7b636784bc5b875b7415a64aa2bfebedd4bad876d6eab447760615780b6cc4657ed6e948a0f763a52be3d03f3edc9c90e3

data/LICENSE

@@ -0,0 +1,17 @@
+MIT License
+
+Copyright (c) 2026 ToggleFleet
+
+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. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE.

data/README.md

@@ -0,0 +1,124 @@
+# ToggleFleet — Ruby SDK
+
+Cloud feature flags for Ruby. All five gates — **boolean, actor, group, % of actors, % of time** —
+evaluated **locally** in your process, so checking a flag is a hash lookup, not a network round-trip.
+The gem refreshes your environment's config in the background using conditional (ETag) requests, and
+its percentage bucketing is byte-identical to the server, so a sticky rollout is the same whether you
+evaluate in-app or via the REST API.
+
+```ruby
+gem "togglefleet"
+```
+
+## Quick start
+
+```ruby
+# config/initializers/togglefleet.rb
+ToggleFleet.configure do |c|
+  c.sdk_key          = ENV["TOGGLEFLEET_SDK_KEY"]  # one key per environment (Settings → SDK keys)
+  c.refresh_interval = 15                          # seconds between background refreshes
+  c.default          = false                       # fail-safe value if a flag is unknown
+end
+
+# Group membership is decided in YOUR code:
+ToggleFleet.register_group(:admins)   { |user| user.admin? }
+ToggleFleet.register_group(:internal) { |user| user.email.end_with?("@yourco.com") }
+
+ToggleFleet.start  # initial fetch + background refresh thread (recommended)
+```
+
+```ruby
+# anywhere in your app — no network call happens here
+if ToggleFleet.enabled?(:checkout_v2, actor: current_user)
+  render "checkout/v2"
+end
+```
+
+## The gates
+
+A flag is **on** for an actor if **any** gate matches (first match wins):
+
+| Gate | Turn it on in the dashboard | Effect |
+|------|------------------------------|--------|
+| Boolean | "Fully on" | on for everyone |
+| Actor | add actor IDs | on for those specific actors |
+| Group | add group names | on for actors your registered predicate matches |
+| % of actors | set 0–100 | sticky — the same actors keep it as you ramp |
+| % of time | set 0–100 | random per call |
+
+## Actors
+
+An "actor" is anything you want to flag on. The gem derives a stable id:
+
+1. `actor.togglefleet_id` if defined, else
+2. `actor.id` (works out of the box for ActiveRecord), else
+3. the value itself (so a plain string, symbol, or integer works).
+
+```ruby
+ToggleFleet.enabled?(:beta, actor: current_user)   # uses current_user.id
+ToggleFleet.enabled?(:beta, actor: "account_42")   # plain string id
+ToggleFleet.enabled?(:beta)                         # no actor: boolean / % of time only
+```
+
+You can also pass groups explicitly (in addition to registered predicates):
+
+```ruby
+ToggleFleet.enabled?(:eu_pricing, actor: user, groups: [:eu_customer])
+```
+
+## Bulk snapshot
+
+Resolve every flag at once — useful for handing state to a front end:
+
+```ruby
+ToggleFleet.all(actor: current_user)
+# => { "checkout_v2" => true, "dark_mode" => false, ... }
+```
+
+## Reliability
+
+- **Local evaluation** — `enabled?` never blocks on the network.
+- **Background refresh** — a single daemon thread polls every `refresh_interval` seconds with an
+  `If-None-Match` ETag, so unchanged configs cost one `304` and zero parsing.
+- **Fail-safe** — if the service is unreachable, the gem serves the last good config; if it never
+  loaded, every flag returns `config.default` (defaults to `false`).
+- **Instrumentation** — hook every evaluation for metrics or logging:
+
+```ruby
+ToggleFleet.configure do |c|
+  c.sdk_key = ENV["TOGGLEFLEET_SDK_KEY"]
+  c.on_evaluation = ->(flag, actor, result) { StatsD.increment("flag.#{flag}.#{result}") }
+end
+```
+
+## Multiple environments at once
+
+The module-level `ToggleFleet.*` is a singleton, but you can build standalone clients:
+
+```ruby
+prod = ToggleFleet::Client.new(ToggleFleet::Configuration.new.tap { |c| c.sdk_key = ENV["PROD_KEY"] }).start
+staging = ToggleFleet::Client.new(ToggleFleet::Configuration.new.tap { |c| c.sdk_key = ENV["STAGING_KEY"] }).start
+```
+
+## REST API (any language)
+
+No Ruby? Hit the API directly with an environment's SDK key.
+
+```
+GET /v1/evaluate?flag=checkout_v2&actor=dave&groups=admins
+Authorization: Bearer tf_live_…
+→ { "flag": "checkout_v2", "enabled": true }
+
+GET /v1/config
+Authorization: Bearer tf_live_…
+→ { "flags": { "checkout_v2": { "boolean": false, "percentage_of_actors": 25,
+      "percentage_of_time": 0, "actors": ["dave"], "groups": ["admins"], "id": "…" } } }
+```
+
+`/v1/config` returns the whole environment so you can cache and evaluate locally (that's what this
+gem does). `/v1/evaluate` does a single server-side check — note that **group** gates are resolved
+client-side, so pass `groups=` when using `/v1/evaluate`.
+
+## License
+
+MIT © ToggleFleet

data/lib/togglefleet/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ToggleFleet
+  VERSION = "0.1.0"
+end

data/lib/togglefleet.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "digest"
+require "uri"
+require_relative "togglefleet/version"
+
+# ToggleFleet — cloud feature flags for Ruby.
+#
+# Built from the ground up (Flipper's gate model as the reference, none of its code).
+# Design goals: evaluate flags LOCALLY so there is zero network on the hot path, refresh
+# the config in the background with conditional (ETag) requests, and fail safe.
+#
+#   ToggleFleet.configure { |c| c.sdk_key = ENV["TOGGLEFLEET_SDK_KEY"] }
+#   ToggleFleet.register_group(:admins) { |user| user.admin? }
+#   ToggleFleet.start                      # begin background refresh (optional but recommended)
+#
+#   ToggleFleet.enabled?(:checkout_v2, actor: current_user)   # => true / false
+#
+module ToggleFleet
+  class Error < StandardError; end
+
+  # The five gates, evaluated in order — first match wins (mirrors the server exactly).
+  GATES = %i[boolean actor group percentage_of_actors percentage_of_time].freeze
+
+  class Configuration
+    attr_accessor :sdk_key, :url, :refresh_interval, :default,
+                  :open_timeout, :read_timeout, :logger, :on_evaluation
+
+    def initialize
+      @sdk_key          = ENV["TOGGLEFLEET_SDK_KEY"]
+      @url              = ENV.fetch("TOGGLEFLEET_URL", "https://togglefleet.com")
+      @refresh_interval = Integer(ENV.fetch("TOGGLEFLEET_REFRESH", 15)) # seconds
+      @default          = false   # fail-safe result when a flag is unknown or never fetched
+      @open_timeout     = 3
+      @read_timeout     = 5
+      @logger           = nil
+      @on_evaluation    = nil      # ->(flag, actor, result) {}  for metrics/logging
+    end
+  end
+
+  # A self-contained client. Use ToggleFleet.* for the process-wide singleton, or build your
+  # own (e.g. to talk to two environments at once): ToggleFleet::Client.new(config).
+  class Client
+    attr_reader :config
+
+    def initialize(config)
+      @config  = config
+      @groups  = {}            # name => predicate proc
+      @flags   = {}            # flag key => state hash
+      @etag    = nil
+      @loaded  = false
+      @mutex   = Mutex.new
+      @poller  = nil
+    end
+
+    # Register a group predicate. Group membership is decided in YOUR code, so a flag enabled
+    # for :admins turns on for any actor where the block returns true.
+    def register_group(name, &block)
+      raise ArgumentError, "register_group needs a block" unless block
+      @mutex.synchronize { @groups[name.to_s] = block }
+      self
+    end
+
+    # Pull the config once and start the background refresh thread. Idempotent.
+    def start
+      sync
+      @mutex.synchronize do
+        @poller ||= Thread.new do
+          loop do
+            sleep(@config.refresh_interval)
+            begin; sync; rescue StandardError => e; log("refresh failed: #{e.class}: #{e.message}"); end
+          end
+        end
+        @poller.name = "togglefleet-refresh" if @poller.respond_to?(:name=)
+      end
+      self
+    end
+
+    # The whole point: evaluate locally, no network call here.
+    def enabled?(flag, actor: nil, groups: nil)
+      ensure_loaded
+      state  = @mutex.synchronize { @flags[flag.to_s] }
+      result = state ? evaluate(state, actor, groups) : @config.default
+      @config.on_evaluation&.call(flag.to_s, actor, result)
+      result
+    rescue StandardError => e
+      log("enabled?(#{flag}) error: #{e.class}: #{e.message}")
+      @config.default
+    end
+
+    # Snapshot every known flag for an actor — handy for bootstrapping a JS client.
+    def all(actor: nil, groups: nil)
+      ensure_loaded
+      keys = @mutex.synchronize { @flags.keys }
+      keys.each_with_object({}) { |k, h| h[k] = enabled?(k, actor: actor, groups: groups) }
+    end
+
+    # Force a refresh now (returns true if the config changed).
+    def sync
+      uri = URI.join(@config.url + "/", "v1/config")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @config.open_timeout
+      http.read_timeout = @config.read_timeout
+      req = Net::HTTP::Get.new(uri)
+      req["Authorization"] = "Bearer #{@config.sdk_key}"
+      req["If-None-Match"] = @etag if @etag
+      req["User-Agent"]    = "togglefleet-ruby/#{VERSION}"
+      res = http.request(req)
+
+      case res
+      when Net::HTTPNotModified
+        false
+      when Net::HTTPSuccess
+        flags = JSON.parse(res.body).fetch("flags", {})
+        @mutex.synchronize { @flags = flags; @etag = res["ETag"]; @loaded = true }
+        true
+      when Net::HTTPUnauthorized
+        raise Error, "invalid SDK key (401) — check config.sdk_key"
+      else
+        raise Error, "config fetch failed: HTTP #{res.code}"
+      end
+    end
+
+    private
+
+    def ensure_loaded
+      return if @loaded
+      begin; sync; rescue StandardError => e; log("initial load failed, using defaults: #{e.message}"); end
+    end
+
+    # Mirrors the server's evaluation byte-for-byte (same MD5 bucketing) so a sticky rollout
+    # is identical whether you evaluate here or call /v1/evaluate.
+    def evaluate(state, actor, explicit_groups)
+      return true if state["boolean"]
+
+      aid = actor_id(actor)
+      return true if aid && Array(state["actors"]).include?(aid)
+
+      member_of = resolve_groups(actor, explicit_groups)
+      return true unless (Array(state["groups"]) & member_of).empty?
+
+      pa = state["percentage_of_actors"].to_i
+      if pa.positive? && aid
+        bucket = Digest::MD5.hexdigest("#{state['id']}:#{aid}")[0, 8].to_i(16) % 100
+        return true if bucket < pa
+      end
+
+      pt = state["percentage_of_time"].to_i
+      return true if pt.positive? && rand(100) < pt
+
+      false
+    end
+
+    # Coerce an actor into a stable string id. Prefer an explicit #togglefleet_id, then #id,
+    # else the value itself (so plain strings/symbols/ints work too).
+    def actor_id(actor)
+      return nil if actor.nil?
+      return actor.togglefleet_id.to_s if actor.respond_to?(:togglefleet_id)
+      return actor.id.to_s if actor.respond_to?(:id)
+      actor.to_s
+    end
+
+    def resolve_groups(actor, explicit_groups)
+      names = Array(explicit_groups).map(&:to_s)
+      unless actor.nil?
+        @mutex.synchronize { @groups.dup }.each do |name, predicate|
+          begin
+            names << name if predicate.call(actor)
+          rescue StandardError => e
+            log("group #{name} predicate raised: #{e.message}")
+          end
+        end
+      end
+      names.uniq
+    end
+
+    def log(msg)
+      @config.logger&.warn("[togglefleet] #{msg}")
+    end
+  end
+
+  class << self
+    def configure
+      @config = Configuration.new
+      yield @config if block_given?
+      @client = Client.new(@config)
+      @config
+    end
+
+    def config
+      @config ||= Configuration.new
+    end
+
+    def client
+      @client ||= Client.new(config)
+    end
+
+    def register_group(name, &block) = client.register_group(name, &block)
+    def start = client.start
+    def sync = client.sync
+    def enabled?(flag, **opts) = client.enabled?(flag, **opts)
+    def all(**opts) = client.all(**opts)
+
+    # mostly for tests
+    def reset!
+      @config = nil
+      @client = nil
+    end
+  end
+end

metadata

@@ -0,0 +1,51 @@
+--- !ruby/object:Gem::Specification
+name: togglefleet
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- ToggleFleet
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: ToggleFleet is a cloud feature-flag service. This gem fetches your environment's
+  flags, caches them, and evaluates all five gates (boolean, actor, group, % of actors,
+  % of time) locally — so checking a flag is a hash lookup, not a network call. Background
+  refresh uses conditional ETag requests; evaluation is byte-identical to the server.
+email:
+- support@togglefleet.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/togglefleet.rb
+- lib/togglefleet/version.rb
+homepage: https://togglefleet.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://togglefleet.com
+  source_code_uri: https://github.com/takeaseatventure/togglefleet-ruby
+  documentation_uri: https://togglefleet.com/docs
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Cloud feature flags for Ruby — all five gates, evaluated locally.
+test_files: []