featurehub-sdk 1.3.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0cd81cc23b520be9a702b06ab17071c1eddb40bd2a79cc0617c22509f1574cc9
-  data.tar.gz: e2c3cf069c8635fc574db0d6c5a8dcdef2170058d282747c2b0481f84998078b
+  metadata.gz: c3c5127a58f5d1a4c63242919d593399ee0e097dcbd54239584d3620eb00f5a9
+  data.tar.gz: 4de3a2a249d35c6dfd52249a6b42171cd27e9aac8ed4c95f2c0efdaa9947663b
 SHA512:
-  metadata.gz: 7092b35679401cd732ece4a49366a84e136df729d8bbdc3285da81ade5cb90ffad19a5431c9fe25e9c5b8f9b2c777a144e90859d22c9230c22f3278909de35af
-  data.tar.gz: a134bea6b240aa6aced1158e5c0bd70c4c3b7754d047387aeb517fdec8b35e2572599971aea11abfcdb477ed68dd2d29657b0747acd1a2c87fc93d59927e1457
+  metadata.gz: 9a41c73c154804782a9795337e33de707a482f2fedb41337783222f561ce1eccae41dfca59ad393a36d9fa8d214f8f54778b016092de3c04e4c9d83c9da44a95
+  data.tar.gz: aac1dfb0a3d61d77f4046b9710f146ce0f2d0562a7c324e8e03c43c7276c5eb555322f9b3e49543aeb9958b1b4328b15dc003c29da682160a3b29ac782c830af

data/.claude/CLAUDE.md

@@ -0,0 +1,85 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+bundle install          # Install dependencies
+bundle exec rake        # Run tests + linting (default)
+bundle exec rspec       # Run tests only
+bundle exec rubocop     # Lint only
+
+# Run a single test file
+bundle exec rspec spec/feature_hub/sdk/feature_hub_config_spec.rb
+
+# Run a specific test by line number
+bundle exec rspec spec/feature_hub/sdk/feature_hub_config_spec.rb:42
+```
+
+## Architecture
+
+This is the FeatureHub Ruby SDK (gem: `featurehub-sdk`, version 2.0.0), targeting Ruby >= 3.2. All code lives under `lib/feature_hub/sdk/` and is namespaced as `FeatureHub::Sdk`.
+
+### Core Data Flow
+
+```
+FeatureHubConfig.init(url, api_key)
+  → creates EdgeService (streaming SSE or polling HTTP)
+  → edge service receives feature JSON from FeatureHub server
+  → FeatureHubRepository stores feature states
+
+config.new_context().user_key("id").build()
+  → ClientEvalContext: polls edge, evaluates strategies locally
+  → ServerEvalContext: sends context as HTTP header, server evaluates
+
+context.feature("MY_FLAG").boolean
+  → FeatureStateHolder checks interceptors, then calls repository.apply(strategies, ctx)
+  → ApplyFeature matches rollout strategies, returns Applied(value)
+```
+
+### Key Classes
+
+- **FeatureHubConfig** ([feature_hub_config.rb](lib/feature_hub/sdk/feature_hub_config.rb)): Entry point. Detects client vs server evaluation by checking for `*` in the API key. Manages edge service lifecycle. Call `new_context()` to get a context builder.
+
+- **FeatureHubRepository** ([feature_repository.rb](lib/feature_hub/sdk/feature_repository.rb)): Stores features as a hash (symbol keys → `FeatureStateHolder`). Notifies listeners on changes (`:features`, `:feature`, `:delete_feature`, `:failed`). Checks interceptors before applying strategies. Tracks readiness via `@ready`.
+
+- **FeatureStateHolder** ([feature_state_holder.rb](lib/feature_hub/sdk/feature_state_holder.rb)): Wraps feature JSON (`key`, `id`, `type`, `value`, `version`, `l` (locked), `strategies`). Provides typed accessors: `.flag`, `.string`, `.number`, `.raw_json`, `.boolean`. Supports `with_context(ctx)` for strategy evaluation.
+
+- **Context classes** ([context.rb](lib/feature_hub/sdk/context.rb)): Fluent builder pattern — `context.user_key("x").platform("ios").country("gb").build()`. Attributes stored as `symbol → [array]`. Two subclasses: `ClientEvalFeatureContext` (local strategy eval) and `ServerEvalFeatureContext` (server-side eval, sends `x-featurehub` header).
+
+- **Edge services**: `StreamingEdgeService` ([streaming_edge_service.rb](lib/feature_hub/sdk/streaming_edge_service.rb)) uses SSE via `ld-eventsource`. `PollingEdgeService` ([poll_edge_service.rb](lib/feature_hub/sdk/poll_edge_service.rb)) uses Faraday with `Concurrent::TimerTask`, supports ETags. Call `force_new_edge_service()` after process fork (Puma/Passenger/Unicorn).
+
+- **ApplyFeature** ([impl/apply_features.rb](lib/feature_hub/sdk/impl/apply_features.rb)): Client-side strategy evaluator. Iterates rollout strategies, calculates percentage allocation via Murmur3 hash of `percentage_key + feature_id`, matches attribute conditions via `MatcherRegistry`. Returns `Applied(matched:, value:)`.
+
+- **EnvironmentInterceptor** ([interceptors.rb](lib/feature_hub/sdk/interceptors.rb)): Override features at runtime via `FEATUREHUB_OVERRIDE_FEATURES=true` + `FEATUREHUB_<FEATURE_NAME>=<value>` env vars.
+
+### Client vs Server Evaluation
+
+- **Client-evaluated** API key contains `*` (e.g., `abc*def`): full strategy data sent to SDK, evaluated locally by `ApplyFeature`.
+- **Server-evaluated** API key has no `*`: context attributes sent as `x-featurehub` HTTP header, server evaluates and returns resolved values.
+
+### Strategy Attribute Matchers
+
+`MatcherRegistry` dispatches to typed matchers based on `field_type`: `BOOLEAN`, `STRING`/`DATE`/`DATE_TIME` (via `StringMatcher`), `NUMBER`, `SEMANTIC_VERSION` (uses `sem_version` gem), `IP_ADDRESS` (CIDR support). All conditions in a strategy must match for the strategy to apply.
+
+## RBS Type Signatures
+
+Type definitions live in [sig/feature_hub/featurehub.rbs](sig/feature_hub/featurehub.rbs). Key signatures to be aware of:
+
+- **Feature value type**: `[bool? | String? | Float?]` — the union type used throughout for feature values (`Applied#value`, `FeatureStateHolder#value`, `RolloutStrategy#value`, `InterceptorValue`)
+- **`FeatureStateHolder#initialize`** takes `key:`, `repo:`, `feature_state:`, `parent_state:`, and `ctx:` — the `parent_state` and `ctx` support the `with_context` pattern for context-scoped evaluation
+- **`InternalFeatureRepository`** is the abstract interface that `FeatureHubRepository` implements; `FeatureStateHolder` and context classes depend on this interface, not the concrete class
+- **`ClientContext#build`** returns `ClientContext` (async); **`build_sync`** also returns `ClientContext` (blocking)
+- **`FeatureHubConfig#repository`** takes an optional `InternalFeatureRepository?` and returns one — it acts as both getter and setter
+- **`RolloutStrategyAttribute`**: `values` is `Array[[bool? | String? | Float?]]`; use `float_values` / `str_values` for typed access
+- **`RolloutStrategyCondition`**: predicate methods only (e.g., `equals?`, `regex?`, `includes?`) — no raw string comparison against condition type strings
+
+## Conventions
+
+- `# frozen_string_literal: true` on every file
+- Double-quoted strings (RuboCop enforced)
+- Feature keys stored/looked up as symbols internally
+- RuboCop: max line length 120, metrics cops disabled, documentation disabled
+- Tests mirror lib structure: `spec/feature_hub/sdk/**/*_spec.rb`
+- Use `instance_double` for mocking, `aggregate_failures` for multiple assertions

data/.ruby-version

@@ -1 +1 @@
-3.2.0
+3.3.10

data/CHANGELOG.md

@@ -1,4 +1,16 @@
-## [1.3.0] - 2024-01-12
+## [2.0.0] - 2026-03-22
+
+- Refactor FeatureState to FeatureStateHolder to be consistent with other SDKs
+- Add FeatureValueType to reduce duplication
+- Add local YAML file interceptor with an optional timer to watch for changes
+- Add `RawUpdateFeatureListener` base class so custom listeners can react to raw edge updates (including update source tracking)
+- Add `LocalYamlStore`: load features from a local YAML file without an Edge server, as an alternative to the value interceptor
+- Add `RedisSessionStore`: persist features in Redis so they survive process restarts and are shared across processes (client-evaluated only)
+- Support punch-through context evaluation for external stores so per-request context attributes are applied even when features come from Redis or YAML
+- Add `value` accessor to `FeatureStateHolder` as a convenience shortcut alongside the typed accessors
+- Edge services now explicitly close the repository on shutdown
+
+## [1.3.0] - 2026-01-11
 
 - update gem dependencies
 - bump minimum ruby version to 3.2

data/Gemfile

@@ -21,4 +21,4 @@ gem "murmurhash3", "~> 0.1.7"
 
 gem "sem_version", "~> 2.0.0"
 
-gem "ld-eventsource", "~> 2.3.0"
+gem "ld-eventsource", "~> 2.5.1"

data/Gemfile.lock

@@ -1,10 +1,10 @@
 PATH
   remote: .
   specs:
-    featurehub-sdk (1.3.0)
+    featurehub-sdk (2.0.0)
       concurrent-ruby (~> 1.3)
       faraday (~> 2)
-      ld-eventsource (~> 2.3.0)
+      ld-eventsource (~> 2.5.1)
       murmurhash3 (~> 0.1.7)
       sem_version (~> 2.0.0)
 
@@ -15,6 +15,7 @@ GEM
       public_suffix (>= 2.0.2, < 8.0)
     ast (2.4.3)
     concurrent-ruby (1.3.6)
+    connection_pool (3.0.2)
     diff-lcs (1.6.2)
     docile (1.4.1)
     domain_name (0.6.20240107)
@@ -25,6 +26,7 @@ GEM
     faraday-net_http (3.4.2)
       net-http (~> 0.5)
     ffi (1.17.3-arm64-darwin)
+    ffi (1.17.3-x86_64-darwin)
     ffi (1.17.3-x86_64-linux-gnu)
     ffi-compiler (1.3.2)
       ffi (>= 1.15.5)
@@ -37,9 +39,9 @@ GEM
     http-cookie (1.1.0)
       domain_name (~> 0.5)
     http-form_data (2.3.0)
-    json (2.18.0)
+    json (2.19.2)
     language_server-protocol (3.17.0.5)
-    ld-eventsource (2.3.0)
+    ld-eventsource (2.5.1)
       concurrent-ruby (~> 1.0)
       http (>= 4.4.1, < 6.0.0)
     lint_roller (1.1.0)
@@ -59,6 +61,10 @@ GEM
     racc (1.8.1)
     rainbow (3.1.1)
     rake (13.3.1)
+    redis (5.4.1)
+      redis-client (>= 0.22.0)
+    redis-client (0.28.0)
+      connection_pool
     regexp_parser (2.11.3)
     rspec (3.13.2)
       rspec-core (~> 3.13.0)
@@ -102,15 +108,17 @@ GEM
 
 PLATFORMS
   arm64-darwin
+  x86_64-darwin-24
   x86_64-linux
 
 DEPENDENCIES
   concurrent-ruby (~> 1.3)
   faraday (~> 2)
   featurehub-sdk!
-  ld-eventsource (~> 2.3.0)
+  ld-eventsource (~> 2.5.1)
   murmurhash3 (~> 0.1.7)
   rake (~> 13.0)
+  redis (~> 5)
   rspec (~> 3.0)
   rubocop (~> 1.21)
   sem_version (~> 2.0.0)
@@ -120,21 +128,23 @@ CHECKSUMS
   addressable (2.8.8) sha256=7c13b8f9536cf6364c03b9d417c19986019e28f7c00ac8132da4eb0fe393b057
   ast (2.4.3) sha256=954615157c1d6a382bc27d690d973195e79db7f55e9765ac7c481c60bdb4d383
   concurrent-ruby (1.3.6) sha256=6b56837e1e7e5292f9864f34b69c5a2cbc75c0cf5338f1ce9903d10fa762d5ab
+  connection_pool (3.0.2) sha256=33fff5ba71a12d2aa26cb72b1db8bba2a1a01823559fb01d29eb74c286e62e0a
   diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
   docile (1.4.1) sha256=96159be799bfa73cdb721b840e9802126e4e03dfc26863db73647204c727f21e
   domain_name (0.6.20240107) sha256=5f693b2215708476517479bf2b3802e49068ad82167bcd2286f899536a17d933
   faraday (2.14.0) sha256=8699cfe5d97e55268f2596f9a9d5a43736808a943714e3d9a53e6110593941cd
   faraday-net_http (3.4.2) sha256=f147758260d3526939bf57ecf911682f94926a3666502e24c69992765875906c
-  featurehub-sdk (1.3.0)
+  featurehub-sdk (2.0.0)
   ffi (1.17.3-arm64-darwin) sha256=0c690555d4cee17a7f07c04d59df39b2fba74ec440b19da1f685c6579bb0717f
+  ffi (1.17.3-x86_64-darwin) sha256=1f211811eb5cfaa25998322cdd92ab104bfbd26d1c4c08471599c511f2c00bb5
   ffi (1.17.3-x86_64-linux-gnu) sha256=3746b01f677aae7b16dc1acb7cb3cc17b3e35bdae7676a3f568153fb0e2c887f
   ffi-compiler (1.3.2) sha256=a94f3d81d12caf5c5d4ecf13980a70d0aeaa72268f3b9cc13358bcc6509184a0
   http (5.3.1) sha256=c50802d8e9be3926cb84ac3b36d1a31fbbac383bc4cbecdce9053cb604231d7d
   http-cookie (1.1.0) sha256=38a5e60d1527eebc396831b8c4b9455440509881219273a6c99943d29eadbb19
   http-form_data (2.3.0) sha256=cc4eeb1361d9876821e31d7b1cf0b68f1cf874b201d27903480479d86448a5f3
-  json (2.18.0) sha256=b10506aee4183f5cf49e0efc48073d7b75843ce3782c68dbeb763351c08fd505
+  json (2.19.2) sha256=e7e1bd318b2c37c4ceee2444841c86539bc462e81f40d134cf97826cb14e83cf
   language_server-protocol (3.17.0.5) sha256=fd1e39a51a28bf3eec959379985a72e296e9f9acfce46f6a79d31ca8760803cc
-  ld-eventsource (2.3.0) sha256=b79187490fc567626c805b9f3d97d08a03d5e4cad045974b2089216bf37dba9f
+  ld-eventsource (2.5.1) sha256=19cb44b7d3f91f76b7401a1b74293b32c723389b2d6f9d81ecb803c628ac1b25
   lint_roller (1.1.0) sha256=2c0c845b632a7d172cb849cc90c1bce937a28c5c8ccccb50dfd46a485003cc87
   llhttp-ffi (0.5.1) sha256=9a25a7fc19311f691a78c9c0ac0fbf4675adbd0cca74310228fdf841018fa7bc
   logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
@@ -147,6 +157,8 @@ CHECKSUMS
   racc (1.8.1) sha256=4a7f6929691dbec8b5209a0b373bc2614882b55fc5d2e447a21aaa691303d62f
   rainbow (3.1.1) sha256=039491aa3a89f42efa1d6dec2fc4e62ede96eb6acd95e52f1ad581182b79bc6a
   rake (13.3.1) sha256=8c9e89d09f66a26a01264e7e3480ec0607f0c497a861ef16063604b1b08eb19c
+  redis (5.4.1) sha256=b5e675b57ad22b15c9bcc765d5ac26f60b675408af916d31527af9bd5a81faae
+  redis-client (0.28.0) sha256=888892f9cd8787a41c0ece00bdf5f556dfff7770326ce40bb2bc11f1bfec824b
   regexp_parser (2.11.3) sha256=ca13f381a173b7a93450e53459075c9b76a10433caadcb2f1180f2c741fc55a4
   rspec (3.13.2) sha256=206284a08ad798e61f86d7ca3e376718d52c0bc944626b2349266f239f820587
   rspec-core (3.13.6) sha256=a8823c6411667b60a8bca135364351dda34cd55e44ff94c4be4633b37d828b2d