quonfig 0.0.2

data/Gemfile

@@ -0,0 +1,26 @@
+source 'https://rubygems.org'
+
+gem 'concurrent-ruby', '~> 1.0', '>= 1.0.5'
+gem 'faraday'
+gem 'ld-eventsource'
+gem 'uuid'
+
+gem 'activesupport', '>= 4'
+
+group :development do
+  gem 'allocation_stats'
+  gem 'benchmark-ips'
+  gem 'bundler'
+  gem 'juwelier', '~> 2.4.9'
+  gem 'rdoc'
+  gem 'simplecov', '>= 0'
+end
+
+group :test do
+  gem 'semantic_logger', '!= 4.16.0', require: "semantic_logger/sync"
+  gem 'minitest'
+  gem 'minitest-focus'
+  gem 'minitest-reporters'
+  gem 'timecop'
+  gem 'webrick'
+end

data/Gemfile.lock

@@ -0,0 +1,177 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (7.1.3.2)
+      base64
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      mutex_m
+      tzinfo (~> 2.0)
+    addressable (2.8.6)
+      public_suffix (>= 2.0.2, < 6.0)
+    allocation_stats (0.1.5)
+    ansi (1.5.0)
+    base64 (0.2.0)
+    benchmark-ips (2.13.0)
+    bigdecimal (3.1.7)
+    builder (3.2.4)
+    concurrent-ruby (1.2.3)
+    connection_pool (2.4.1)
+    descendants_tracker (0.0.4)
+      thread_safe (~> 0.3, >= 0.3.1)
+    docile (1.4.0)
+    domain_name (0.6.20240107)
+    drb (2.2.1)
+    faraday (1.10.3)
+      faraday-em_http (~> 1.0)
+      faraday-em_synchrony (~> 1.0)
+      faraday-excon (~> 1.1)
+      faraday-httpclient (~> 1.0)
+      faraday-multipart (~> 1.0)
+      faraday-net_http (~> 1.0)
+      faraday-net_http_persistent (~> 1.0)
+      faraday-patron (~> 1.0)
+      faraday-rack (~> 1.0)
+      faraday-retry (~> 1.0)
+      ruby2_keywords (>= 0.0.4)
+    faraday-em_http (1.0.0)
+    faraday-em_synchrony (1.0.0)
+    faraday-excon (1.1.0)
+    faraday-httpclient (1.0.1)
+    faraday-multipart (1.0.4)
+      multipart-post (~> 2)
+    faraday-net_http (1.0.1)
+    faraday-net_http_persistent (1.2.0)
+    faraday-patron (1.0.0)
+    faraday-rack (1.0.0)
+    faraday-retry (1.0.3)
+    ffi (1.17.4)
+    ffi-compiler (1.3.2)
+      ffi (>= 1.15.5)
+      rake
+    git (1.19.1)
+      addressable (~> 2.8)
+      rchardet (~> 1.8)
+    github_api (0.19.0)
+      addressable (~> 2.4)
+      descendants_tracker (~> 0.0.4)
+      faraday (>= 0.8, < 2)
+      hashie (~> 3.5, >= 3.5.2)
+      oauth2 (~> 1.0)
+    hashie (3.6.0)
+    highline (3.0.1)
+    http (5.2.0)
+      addressable (~> 2.8)
+      base64 (~> 0.1)
+      http-cookie (~> 1.0)
+      http-form_data (~> 2.2)
+      llhttp-ffi (~> 0.5.0)
+    http-cookie (1.0.5)
+      domain_name (~> 0.5)
+    http-form_data (2.3.0)
+    i18n (1.14.4)
+      concurrent-ruby (~> 1.0)
+    juwelier (2.4.9)
+      builder
+      bundler
+      git
+      github_api
+      highline
+      kamelcase (~> 0)
+      nokogiri
+      psych
+      rake
+      rdoc
+      semver2
+    jwt (2.8.1)
+      base64
+    kamelcase (0.0.2)
+      semver2 (~> 3)
+    ld-eventsource (2.2.2)
+      concurrent-ruby (~> 1.0)
+      http (>= 4.4.1, < 6.0.0)
+    llhttp-ffi (0.5.0)
+      ffi-compiler (~> 1.0)
+      rake (~> 13.0)
+    macaddr (1.7.2)
+      systemu (~> 2.6.5)
+    mini_portile2 (2.8.9)
+    minitest (5.22.3)
+    minitest-focus (1.4.0)
+      minitest (>= 4, < 6)
+    minitest-reporters (1.6.1)
+      ansi
+      builder
+      minitest (>= 5.0)
+      ruby-progressbar
+    multi_json (1.15.0)
+    multi_xml (0.6.0)
+    multipart-post (2.4.0)
+    mutex_m (0.2.0)
+    nokogiri (1.18.9)
+      mini_portile2 (~> 2.8.2)
+      racc (~> 1.4)
+    oauth2 (1.4.11)
+      faraday (>= 0.17.3, < 3.0)
+      jwt (>= 1.0, < 3.0)
+      multi_json (~> 1.3)
+      multi_xml (~> 0.5)
+      rack (>= 1.2, < 4)
+    psych (5.1.2)
+      stringio
+    public_suffix (5.0.4)
+    racc (1.8.1)
+    rack (3.1.18)
+    rake (13.1.0)
+    rchardet (1.8.0)
+    rdoc (6.6.3.1)
+      psych (>= 4.0.0)
+    ruby-progressbar (1.13.0)
+    ruby2_keywords (0.0.5)
+    semantic_logger (4.15.0)
+      concurrent-ruby (~> 1.0)
+    semver2 (3.4.2)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.12.3)
+    simplecov_json_formatter (0.1.4)
+    stringio (3.1.0)
+    systemu (2.6.5)
+    thread_safe (0.3.6)
+    timecop (0.9.8)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    uuid (2.3.9)
+      macaddr (~> 1.0)
+    webrick (1.8.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activesupport (>= 4)
+  allocation_stats
+  benchmark-ips
+  bundler
+  concurrent-ruby (~> 1.0, >= 1.0.5)
+  faraday
+  juwelier (~> 2.4.9)
+  ld-eventsource
+  minitest
+  minitest-focus
+  minitest-reporters
+  rdoc
+  semantic_logger (!= 4.16.0)
+  simplecov
+  timecop
+  uuid
+  webrick
+
+BUNDLED WITH
+   2.3.5

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2023 Prefab, Inc.
+
+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,213 @@
+# quonfig
+
+Ruby SDK for [Quonfig](https://quonfig.com) — Feature Flags, Live Config, and Dynamic Log Levels.
+
+> **Note:** This SDK is pre-1.0 and the API is not yet stable.
+
+## Installation
+
+Add the gem to your Gemfile:
+
+```ruby
+gem 'quonfig'
+```
+
+Or install directly:
+
+```bash
+gem install quonfig
+```
+
+## Quickstart
+
+```ruby
+require 'quonfig'
+
+client = Quonfig::Client.new(sdk_key: ENV['QUONFIG_BACKEND_SDK_KEY'])
+
+# Feature flags
+if client.enabled?('new-dashboard')
+  # show new dashboard
+end
+
+# Typed config values
+limit   = client.get_int('rate-limit')
+name    = client.get_string('app.display-name')
+regions = client.get_string_list('allowed-regions')
+
+# Context-aware evaluation — pass a context hash as the last argument
+value = client.get_string('homepage-hero', user: { key: 'user-123', country: 'US' })
+```
+
+## Context
+
+Contexts are hashes grouped by scope (`user`, `team`, `device`, etc.). You can
+attach a context in three ways:
+
+### 1. Per-call context
+
+```ruby
+client.get_bool('beta-feature', user: { key: 'user-123', plan: 'pro' })
+```
+
+### 2. `in_context` block
+
+Everything evaluated inside the block sees the supplied context. The block's
+return value is returned from `in_context`.
+
+```ruby
+result = client.in_context(user: { key: 'user-123', plan: 'pro' }) do |bound|
+  {
+    hero:   bound.get_string('homepage-hero'),
+    limit:  bound.get_int('rate-limit'),
+    beta?:  bound.enabled?('beta-feature')
+  }
+end
+```
+
+### 3. `with_context` — BoundClient for repeated lookups
+
+`with_context` returns an immutable `BoundClient` that carries the context on
+every call. Useful when you want to pass a context-bound handle down the stack.
+
+```ruby
+bound = client.with_context(user: { key: 'user-123', plan: 'pro' })
+
+bound.get_string('homepage-hero')
+bound.enabled?('beta-feature')
+bound.get_int('rate-limit')
+```
+
+## Datadir / offline mode
+
+For tests, CI, or air-gapped environments, point the client at a local workspace
+directory instead of the Quonfig API. In datadir mode the SDK loads JSON config
+files from disk and performs no network I/O.
+
+```ruby
+client = Quonfig::Client.new(
+  datadir:     '/path/to/workspace',
+  environment: 'production'
+)
+
+client.get_bool('feature-x')
+```
+
+You can also set `QUONFIG_DIR` in the environment and omit the `datadir:`
+option; when `QUONFIG_DIR` is set the SDK switches to datadir mode
+automatically. `environment` is required in datadir mode — it can be provided
+via the option or via `QUONFIG_ENVIRONMENT`.
+
+```bash
+export QUONFIG_DIR=/path/to/workspace
+export QUONFIG_ENVIRONMENT=production
+```
+
+```ruby
+client = Quonfig::Client.new  # reads QUONFIG_DIR + QUONFIG_ENVIRONMENT
+```
+
+## Environment variables
+
+| Variable                    | Purpose                                                                                  |
+|-----------------------------|------------------------------------------------------------------------------------------|
+| `QUONFIG_BACKEND_SDK_KEY`   | SDK key used to authenticate against the Quonfig API. Used when `sdk_key:` is omitted.   |
+| `QUONFIG_DIR`               | Path to a workspace directory. When set, the SDK runs in datadir/offline mode.           |
+| `QUONFIG_ENVIRONMENT`       | Environment name (`production`, `staging`, `development`) evaluated in datadir mode.     |
+| `QUONFIG_TELEMETRY_URL`     | Overrides the telemetry endpoint. Defaults to `https://telemetry.quonfig.com`.           |
+
+## Constructor options
+
+```ruby
+Quonfig::Client.new(
+  sdk_key:         '...',                          # required unless QUONFIG_BACKEND_SDK_KEY is set
+  api_urls:        ['https://primary.quonfig.com'],
+  telemetry_url:   'https://telemetry.quonfig.com',
+  enable_sse:      true,
+  enable_polling:  false,
+  poll_interval:   60,
+  init_timeout:    10,
+  on_no_default:   :error,
+  global_context:  {},
+  datadir:         '/path/to/workspace',
+  environment:     'production'
+)
+```
+
+| Option            | Type                       | Default                                                             | Description                                                                                       |
+|-------------------|----------------------------|---------------------------------------------------------------------|---------------------------------------------------------------------------------------------------|
+| `sdk_key`         | `String`                   | `ENV['QUONFIG_BACKEND_SDK_KEY']`                                    | SDK key for API authentication.                                                                   |
+| `api_urls`        | `Array<String>`            | `['https://primary.quonfig.com']`                                    | Ordered list of API base URLs to try. SSE stream URLs are derived by prepending `stream.` to each hostname. |
+| `telemetry_url`   | `String`                   | `https://telemetry.quonfig.com` (or `ENV['QUONFIG_TELEMETRY_URL']`) | Base URL for the telemetry service.                                                               |
+| `enable_sse`      | `Boolean`                  | `true`                                                              | Receive real-time updates over Server-Sent Events.                                                |
+| `enable_polling`  | `Boolean`                  | `false`                                                             | Poll the API on an interval as a fallback.                                                        |
+| `poll_interval`   | `Integer` (seconds)        | `60`                                                                | Polling interval when `enable_polling` is `true`.                                                 |
+| `init_timeout`    | `Integer` (seconds)        | `10`                                                                | Maximum time to wait for the initial config load.                                                 |
+| `on_no_default`   | `Symbol`                   | `:error`                                                            | Behavior when a key has no value and no default: `:error`, `:warn`, or `:ignore`.                 |
+| `global_context`  | `Hash`                     | `{}`                                                                | Context applied to every evaluation.                                                              |
+| `datadir`         | `String`                   | `ENV['QUONFIG_DIR']`                                                | Path to a local workspace. When set, the SDK runs offline from disk.                              |
+| `environment`     | `String`                   | `ENV['QUONFIG_ENVIRONMENT']`                                        | Environment to evaluate in datadir mode. Required when `datadir` is set.                          |
+
+## Typed getters
+
+Each typed getter takes a config key and an optional context hash. If the key
+is missing or the stored value does not match the requested type, the getter
+returns `nil`.
+
+| Method                                          | Returns                       |
+|-------------------------------------------------|-------------------------------|
+| `get_string(key, contexts = nil)`               | `String` or `nil`             |
+| `get_int(key, contexts = nil)`                  | `Integer` or `nil`            |
+| `get_float(key, contexts = nil)`                | `Float` or `nil`              |
+| `get_bool(key, contexts = nil)`                 | `true`, `false`, or `nil`     |
+| `get_string_list(key, contexts = nil)`          | `Array<String>` or `nil`      |
+| `get_duration(key, contexts = nil)`             | `Float` (seconds) or `nil`    |
+| `get_json(key, contexts = nil)`                 | `Hash`, `Array`, or `nil`     |
+| `enabled?(feature_name, contexts = nil)`        | `true` or `false`             |
+
+Example:
+
+```ruby
+client.get_string('app.display-name')
+client.get_int('rate-limit', user: { key: 'user-123' })
+client.get_float('pricing.multiplier')
+client.get_bool('flags.new-checkout')
+client.get_string_list('allowed-regions')
+client.get_duration('request-timeout')
+client.get_json('homepage.layout')
+client.enabled?('beta-feature', user: { key: 'user-123' })
+```
+
+## Dynamic log levels (SemanticLogger)
+
+Quonfig can drive per-class log levels at runtime. Set config keys like
+`log-levels.my_app.foo.bar` to one of `trace`, `debug`, `info`, `warn`, `error`,
+`fatal` and wire the filter into SemanticLogger:
+
+```ruby
+require 'quonfig'
+require 'semantic_logger'
+
+client = Quonfig::Client.new(sdk_key: ENV['QUONFIG_BACKEND_SDK_KEY'])
+SemanticLogger.add_appender(io: $stdout, filter: client.semantic_logger_filter)
+```
+
+Lookup is exact-match only: logger name `MyApp::Foo::Bar` normalizes to
+`log-levels.my_app.foo.bar`. If no key is set the log is allowed through and
+SemanticLogger's static level decides. There is no hierarchy walk — a value on
+`log-levels.my_app` does not affect `log-levels.my_app.foo.bar`.
+
+Pass `key_prefix:` to use a prefix other than `log-levels.`:
+
+```ruby
+client.semantic_logger_filter(key_prefix: 'debug.')
+```
+
+## Documentation
+
+Full documentation, including SPEC, SDK reference, and operational guides, is
+available at [https://quonfig.com/docs](https://quonfig.com/docs).
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  warn e.message
+  warn 'Run `bundle install` to install missing gems'
+  exit e.status_code
+end
+
+require 'rake'
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+task default: :test
+
+unless ENV['CI']
+  require 'juwelier'
+  Juwelier::Tasks.new do |gem|
+    # gem is a Gem::Specification... see http://guides.rubygems.org/specification-reference/ for more options
+    gem.name = 'quonfig'
+    gem.homepage = 'https://github.com/quonfig/sdk-ruby'
+    gem.license = 'MIT'
+    gem.summary = %(Quonfig Ruby SDK)
+    gem.description = %(Quonfig — feature flags and live config, stored as files in git.)
+    gem.email = 'jeff@quonfig.com'
+    gem.authors = ['Jeff Dwyer']
+
+    # dependencies defined in Gemfile
+  end
+  Juwelier::RubygemsDotOrgTasks.new
+
+  desc 'Code coverage detail'
+  task :simplecov do
+    ENV['COVERAGE'] = 'true'
+    Rake::Task['test'].execute
+  end
+
+  require 'rdoc/task'
+  Rake::RDocTask.new do |rdoc|
+    version = File.exist?('VERSION') ? File.read('VERSION') : ''
+
+    rdoc.rdoc_dir = 'rdoc'
+    rdoc.title = "quonfig #{version}"
+    rdoc.rdoc_files.include('README*')
+    rdoc.rdoc_files.include('lib/**/*.rb')
+  end
+end
+
+# Add release task for CI
+task :release do
+  sh 'mkdir -p pkg'
+  version = File.read('VERSION').strip
+  gem_file = "pkg/quonfig-#{version}.gem"
+  sh "gem build quonfig.gemspec --output #{gem_file}"
+  sh "gem push #{gem_file}"
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.2

data/dev/allocation_stats

@@ -0,0 +1,60 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+gemspec = Dir.glob(File.expand_path("../../*.gemspec", __FILE__)).first
+spec = Gem::Specification.load(gemspec)
+
+# Add the require paths to the $LOAD_PATH
+spec.require_paths.each do |path|
+  full_path = File.expand_path("../" + path, __dir__)
+  $LOAD_PATH.unshift(full_path) unless $LOAD_PATH.include?(full_path)
+end
+
+spec.require_paths.each do |path|
+  require "./lib/reforge-sdk"
+end
+
+require 'reforge-sdk'
+
+$prefab = Reforge::Client.new(collect_logger_counts: false, collect_evaluation_summaries: false,
+                             context_upload_mode: :none)
+$prefab.get('a.live.integer')
+
+puts '-' * 80
+
+require 'allocation_stats'
+
+$runs = 100
+
+def measure(description)
+  puts "Measuring #{description}..."
+  stats = $prefab.with_context(user: { email_suffix: 'yahoo.com' }) do
+    AllocationStats.trace do
+      $runs.times do
+        yield
+      end
+    end
+  end
+
+  allocations = stats.allocations(alias_paths: true).group_by(:sourcefile, :sourceline, :class)
+
+  if ENV['TOP']
+    puts allocations.sort_by_size.to_text.split("\n").first(20)
+  end
+
+  puts "Total allocations: #{allocations.all.values.map(&:size).sum}"
+  puts "Total memory: #{allocations.all.values.flatten.map(&:memsize).sum}"
+  puts stats.gc_profiler_report
+end
+
+measure "no-JIT context (#{$runs} runs)" do
+  $prefab.get('a.live.integer')
+end
+
+puts "\n\n"
+
+measure "with JIT context (#{$runs} runs)" do
+  $prefab.get('a.live.integer', { a: { b: "c" } })
+end

data/dev/benchmark

@@ -0,0 +1,40 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+gemspec = Dir.glob(File.expand_path("../../*.gemspec", __FILE__)).first
+spec = Gem::Specification.load(gemspec)
+
+# Add the require paths to the $LOAD_PATH
+spec.require_paths.each do |path|
+  full_path = File.expand_path("../" + path, __dir__)
+  $LOAD_PATH.unshift(full_path) unless $LOAD_PATH.include?(full_path)
+end
+
+spec.require_paths.each do |path|
+  require "./lib/reforge-sdk"
+end
+
+require 'reforge-sdk'
+require 'benchmark/ips'
+
+prefab = Reforge::Client.new(collect_logger_counts: false, collect_evaluation_summaries: false,
+                            context_upload_mode: :none)
+
+prefab.get('prefab.auth.allowed_origins')
+
+prefab.with_context(user: { email_suffix: 'yahoo.com' }) do
+  Benchmark.ips do |x|
+    x.report("noop") do
+    end
+
+    x.report('prefab.get') do
+      prefab.get('prefab.auth.allowed_origins')
+    end
+
+    x.report('prefab.get with jit context') do
+      prefab.get('prefab.auth.allowed_origins', { a: { b: "c" } })
+    end
+  end
+end

data/dev/console

@@ -0,0 +1,12 @@
+#!/usr/bin/env bundle exec ruby
+# frozen_string_literal: true
+
+require 'irb'
+require_relative "./script_setup"
+
+if !ENV['REFORGE_LOG_CLIENT_BOOTSTRAP_LOG_LEVEL']
+  puts "run with REFORGE_LOG_CLIENT_BOOTSTRAP_LOG_LEVEL=debug (or trace) for more output"
+end
+
+# Start an IRB session
+IRB.start(__FILE__)

data/dev/script_setup.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+gemspec = Dir.glob(File.expand_path("../../*.gemspec", __FILE__)).first
+spec = Gem::Specification.load(gemspec)
+
+# Add the require paths to the $LOAD_PATH
+spec.require_paths.each do |path|
+  full_path = File.expand_path("../" + path, __dir__)
+  $LOAD_PATH.unshift(full_path) unless $LOAD_PATH.include?(full_path)
+end
+
+spec.require_paths.each do |path|
+  require "./lib/quonfig"
+end
+
+SemanticLogger.add_appender(io: $stdout)