toggly 0.2.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 661719eeb6fb2dec747b0f3bfd1dfa08349702573d583f72919abb6c5b6ae8d0
-  data.tar.gz: f1fdf90d3fa48390637f5ea000c21a6002f6764623ed562b822569f3e0e10862
+  metadata.gz: 62d54073d16c04726b00e66b33a8edc9081b9dc397a8f8a8e5aac5316c00bacd
+  data.tar.gz: 8687814d25dbba0b4353622aed082f508f5ce185107419614e018cd4ea047afe
 SHA512:
-  metadata.gz: 4e6045eb73a91c81ccb3d9e7f3b4096958453f825025b18be81707beb6d96a6ca8f636ab1ee2e6b2852ccca5c7461d93009906de1967bf3a04a44e08425ce70d
-  data.tar.gz: c19d57ca41c649c359c29a0c4d6b5c8377d8cdcb03c4fdd1ff8020559d5d9788929aa9ee88e8281226e5e3175c1d8bb5647184c8d3d3c307a21ad6306c7f7546
+  metadata.gz: 6fae978a95aea14cccb5c639623ed55bc65559feab2bf3053fa9c785ddaee516dcffd10977afb58f2f78b353b80d55ef48cf7defd18b564a92d7c966abd4d8f4
+  data.tar.gz: 82b457f3764084effd4b0724a422dfabc69972aff30e6c0af7bff1b28ab215c287662026c86b4e36be657c7351001134093bfc7ca18aab326b547fa41842ca2e

data/CHANGELOG.md

@@ -5,6 +5,63 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-09-08
+
+### Added
+
+- Definition-refresh cache hit/miss counters on `Usage.SendStats`
+  (`definitionCacheHits` / `definitionCacheMisses`), counted once per refresh
+  attempt (poll skip, HTTP 304, matching ETag, network error keeping cache =
+  hit; new revision applied = miss). Concurrent in-flight skips are not counted.
+- Soft-fail restore of the full usage batch (feature stats + hashes + cache
+  counters) when `SendStats` fails; cache-only batches still flush.
+
+## [0.4.0] - 2026-09-06
+
+### Added
+
+- Batched usage (`Usage.SendStats`) and business metrics (`Metrics.SendMetrics`)
+  telemetry with ~1 minute flush and best-effort flush on `close` / `at_exit`.
+- Public client APIs: `record_usage`, `record_view`, `measure`,
+  `increment_counter`, `observe`, `flush_telemetry`.
+- Auto `record_check` from `enabled?` when usage tracking is enabled.
+- Config: `enable_usage_tracking`, `enable_metrics`, `metrics_base_url`,
+  flush intervals; set `TOGGLY_DISABLE_TELEMETRY=1` to disable globally.
+- Optional `grpc` + `google-protobuf` transport (core gem stays zero required
+  runtime deps); gRPC metadata `ua` = `toggly-ruby/{VERSION}`.
+- FNV-1a UTF-8 signed int32 identity hashing with golden vectors matching
+  Go/Node/Python; `variantStats` / `variantValues` wire fields.
+
+### Fixed
+
+- Assign full `Google::Protobuf::Timestamp` objects for nested time fields
+  (FeatureStat/MetricStat/observations) instead of mutating nil fields.
+- Cooperative flush-timer stop on `close` (condition wake + join timeout)
+  instead of `Thread#kill` during an in-flight send.
+
+## [0.3.0] - 2026-09-04
+
+### Added
+
+- EvalContext fields `claims` and `request` (`userAgent`, `acceptLanguage`,
+  `country`) plus `Toggly::RequestContext` and `Toggly::HttpRequestMapper`
+  (headers → request; country order `cf-ipcountry` → `x-vercel-ip-country` →
+  `cloudfront-viewer-country`).
+- Segment filters: `BrowserFamily`, `BrowserLanguage`, `Country` /
+  `CountryFamily`, `DeviceType`, `OS` / `OperatingSystem` with indexed params
+  and Percentage fail-closed gating.
+- `UserClaims` filter (`Claim` + `Value`).
+- `Microsoft.Percentage`, `Microsoft.TimeWindow`, and `Microsoft.Targeting`
+  aliases; golden fixtures under `docs/filter-parity/fixtures/`.
+
+### Changed
+
+- Sticky percentage hashing now uses Definitions / toggly-eval SHA-256
+  (`featureKey + "\n" + userId`, little-endian uint32 / `0xFFFFFFFF * 100`)
+  instead of FNV-1a. Existing sticky cohorts shift when upgrading from 0.2.x.
+- Unknown filter names fail closed.
+- Percentage missing or `≤0` fails closed (aligned with filter-parity contract).
+
 ## [0.2.1] - 2026-09-03
 
 ### Changed

data/README.md

@@ -2,7 +2,14 @@
 
 Core Ruby SDK for [Toggly](https://toggly.io) feature flag management.
 
-**Zero dependencies** - pure Ruby implementation.
+**Zero required runtime dependencies** — pure Ruby evaluation. Optional gems:
+
+- `websocket-client-simple` — live definition updates
+- `grpc` + `google-protobuf` — usage / business metrics telemetry send
+
+The Gemfile `:development, :test` group also includes `grpc` and
+`google-protobuf` so `bundle exec rspec` can exercise the native conversion
+path without making them required runtime deps of the published gem.
 
 Entity `ContextProperty` filters evaluate `Toggly::EntityContext` (`kind`, `key`, `attributes`) and are ANDed with user filters. `Toggly.register_context` optionally PUTs schemas to `sdk/{appKey}/contexts`.
 
@@ -10,6 +17,10 @@ Entity `ContextProperty` filters evaluate `Toggly::EntityContext` (`kind`, `key`
 
 ```ruby
 gem 'toggly'
+
+# Optional: send usage + business metrics over gRPC
+gem 'grpc'
+gem 'google-protobuf'
 ```
 
 ## Quick Start
@@ -23,10 +34,31 @@ client = Toggly::Client.new(
 )
 
 if client.enabled?(:my_feature)
-  # Feature is enabled
+  # Feature is enabled (also records a usage check when tracking is on)
 end
 ```
 
+## Usage & metrics telemetry
+
+When `app_key` is set, usage tracking and metrics default **on** (disable with
+`enable_usage_tracking: false` / `enable_metrics: false`, or
+`TOGGLY_DISABLE_TELEMETRY=1`). Batches flush about every 60 seconds and on
+`client.close`.
+
+```ruby
+client.record_usage('Checkout', identity: 'user-1')
+client.record_view('Banner', identity: 'user-1')
+client.measure('revenue', 12.5, feature: 'Checkout', variant: 'enabled')
+client.increment_counter('clicks', 1, feature: 'Banner')
+client.observe('latency_ms', 42.0)
+client.flush_telemetry
+client.close
+```
+
+gRPC metadata includes `ua` = `toggly-ruby/{VERSION}` against
+`metrics_base_url` (default `https://app.toggly.io/`). Without the optional
+`grpc` gem, evaluation still works; send is a no-op with a warning.
+
 ## Documentation
 
 See the [main README](../README.md) for full documentation.

data/lib/toggly/client/cache_telemetry.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Toggly
+  class Client
+    # Definition-refresh cache hit/miss recording for usage telemetry.
+    module CacheTelemetry
+      private
+
+      def record_refresh_cache_outcome(outcome)
+        if outcome == :miss
+          record_definition_cache_miss
+        else
+          record_definition_cache_hit
+        end
+      end
+
+      def record_definition_cache_hit
+        return unless @telemetry&.usage_enabled?
+
+        @telemetry.record_definition_cache_hit
+      end
+
+      def record_definition_cache_miss
+        return unless @telemetry&.usage_enabled?
+
+        @telemetry.record_definition_cache_miss
+      end
+
+      # True when a revision has been successfully loaded, including an empty
+      # feature set (valid last-good cache for error-path hits).
+      def definitions_cached?
+        @mutex.synchronize { @definitions_loaded }
+      end
+    end
+  end
+end

data/lib/toggly/client/snapshot_support.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Toggly
+  class Client
+    # Durable snapshot load/save helpers for Client.
+    module SnapshotSupport
+      private
+
+      # @return [Boolean] true when a durable snapshot was applied into memory
+      def load_snapshot
+        return false unless @config.snapshot_provider
+
+        data = @config.snapshot_provider.load
+        return false unless data
+
+        @mutex.synchronize do
+          @definitions = data[:definitions]
+          @definitions_loaded = true
+        end
+
+        log_debug("Loaded #{@definitions.size} features from snapshot")
+        true
+      rescue StandardError => e
+        log_warn("Failed to load snapshot: #{e.message}")
+        false
+      end
+
+      def save_snapshot
+        return unless @config.snapshot_provider
+
+        @config.snapshot_provider.save(@definitions)
+        log_debug("Saved snapshot with #{@definitions.size} features")
+      rescue StandardError => e
+        log_warn("Failed to save snapshot: #{e.message}")
+      end
+    end
+  end
+end

data/lib/toggly/client.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative "client/cache_telemetry"
+require_relative "client/snapshot_support"
+
 module Toggly
   # Main client for interacting with Toggly feature flags.
   #
@@ -21,6 +24,9 @@ module Toggly
   #   )
   #   client = Toggly::Client.new(config)
   class Client
+    include CacheTelemetry
+    include SnapshotSupport
+
     # @return [Config] Client configuration
     attr_reader :config
 
@@ -38,6 +44,8 @@ module Toggly
       @config.validate!
 
       @definitions = {}
+      # True once a revision (including empty) or durable snapshot was applied.
+      @definitions_loaded = false
       @mutex = Mutex.new
       @ready = false
       @closed = false
@@ -46,11 +54,16 @@ module Toggly
       @provider = DefinitionsProvider.new(
         config: @config,
         logger: @config.logger,
-        on_definitions_updated: -> { refresh }
+        on_definitions_updated: -> { refresh(force: true, from_websocket: true) }
       )
 
       @refresh_thread = nil
+      @refresh_in_flight = false
+      @pending_ws_refresh = false
+      @telemetry = nil
 
+      # Start telemetry before the first refresh so cache outcomes can be recorded.
+      start_telemetry
       initialize_definitions
       Toggly.register_entity_contexts_at_startup(@config) unless @config.disable_entity_context_registration
       start_background_refresh unless @config.disable_background_refresh
@@ -68,15 +81,22 @@ module Toggly
       definition = @mutex.synchronize { @definitions[key] }
 
       # Check defaults if not found
-      if definition.nil?
-        return default unless default.nil?
-        return @config.defaults[key] if @config.defaults.key?(key)
-        return @config.enable_undefined_in_dev if development?
-
-        return false
-      end
-
-      @engine.evaluate(definition, context)
+      result = if definition.nil?
+                 if !default.nil?
+                   default
+                 elsif @config.defaults.key?(key)
+                   @config.defaults[key]
+                 elsif development?
+                   @config.enable_undefined_in_dev
+                 else
+                   false
+                 end
+               else
+                 @engine.evaluate(definition, context)
+               end
+
+      record_check(key, result, context)
+      result
     end
 
     # Check if a feature is disabled
@@ -126,27 +146,113 @@ module Toggly
     # Manually refresh definitions
     #
     # @param force [Boolean] Force refresh even if not modified
+    # @param from_websocket [Boolean] True when triggered by a live WS notify
     # @return [Boolean] Whether definitions were updated
-    def refresh(force: false)
+    def refresh(force: false, from_websocket: false)
       return false if @config.offline_mode?
 
-      new_definitions = @provider.fetch(force: force)
-
-      if new_definitions
-        @mutex.synchronize do
-          @definitions = new_definitions
-          @ready = true
+      # Concurrent refresh skipped (in flight) — do not count.
+      @mutex.synchronize do
+        if @refresh_in_flight
+          @pending_ws_refresh = true if from_websocket
+          return false
         end
+        @refresh_in_flight = true
+      end
 
-        save_snapshot
-        log_info("Definitions refreshed (#{new_definitions.size} features)")
-        true
-      else
+      begin
+        result = @provider.fetch(force: force)
+        record_refresh_cache_outcome(result.cache_outcome)
+
+        if result.definitions
+          @mutex.synchronize do
+            @definitions = result.definitions
+            @definitions_loaded = true
+            @ready = true
+          end
+
+          save_snapshot
+          log_info("Definitions refreshed (#{result.definitions.size} features)")
+          true
+        else
+          false
+        end
+      rescue StandardError => e
+        log_error("Failed to refresh definitions: #{e.message}")
+        # Network error / timeout keeping last-good revision (incl. empty) — hit.
+        record_definition_cache_hit if definitions_cached?
         false
+      ensure
+        drain_pending = false
+        @mutex.synchronize do
+          @refresh_in_flight = false
+          if @pending_ws_refresh
+            @pending_ws_refresh = false
+            drain_pending = true
+          end
+        end
+        refresh(force: true, from_websocket: true) if drain_pending
       end
-    rescue StandardError => e
-      log_error("Failed to refresh definitions: #{e.message}")
-      false
+    end
+
+    # Record a feature used/interaction event
+    #
+    # @param feature_key [String, Symbol]
+    # @param identity [String, nil]
+    # @param variant [String]
+    def record_usage(feature_key, identity: nil, variant: "enabled")
+      return unless @telemetry&.usage_enabled?
+
+      @telemetry.record_usage(feature_key.to_s, identity, variant: variant)
+    end
+
+    # Record a feature viewed/rendered event
+    #
+    # @param feature_key [String, Symbol]
+    # @param identity [String, nil]
+    # @param variant [String]
+    def record_view(feature_key, identity: nil, variant: "enabled")
+      return unless @telemetry&.usage_enabled?
+
+      @telemetry.record_view(feature_key.to_s, identity, variant: variant)
+    end
+
+    # Aggregate a business measurement (sum over the flush window)
+    #
+    # @param metric [String]
+    # @param value [Numeric]
+    # @param options [Hash, Telemetry::MetricsFeatureOptions, nil]
+    def measure(metric, value, options = nil, **kwargs)
+      return unless @telemetry&.metrics_enabled?
+
+      @telemetry.measure(metric, value, options || (kwargs.empty? ? nil : kwargs))
+    end
+
+    # Increment a business counter
+    #
+    # @param metric [String]
+    # @param value [Numeric]
+    # @param options [Hash, Telemetry::MetricsFeatureOptions, nil]
+    def increment_counter(metric, value = 1.0, options = nil, **kwargs)
+      return unless @telemetry&.metrics_enabled?
+
+      @telemetry.increment_counter(metric, value, options || (kwargs.empty? ? nil : kwargs))
+    end
+
+    # Record a point-in-time business observation
+    #
+    # @param metric [String]
+    # @param value [Numeric]
+    # @param options [Hash, Telemetry::MetricsFeatureOptions, nil]
+    def observe(metric, value, options = nil, **kwargs)
+      return unless @telemetry&.metrics_enabled?
+
+      @telemetry.observe(metric, value, options || (kwargs.empty? ? nil : kwargs))
+    end
+
+    # Flush pending usage and metrics batches
+    def flush_telemetry
+      @telemetry&.flush_all
     end
 
     # Close the client and stop background refresh
@@ -155,6 +261,8 @@ module Toggly
       @provider.stop_websocket
       @refresh_thread&.kill
       @refresh_thread = nil
+      @telemetry&.close
+      @telemetry = nil
     end
 
     # Check if client is closed
@@ -183,8 +291,10 @@ module Toggly
     private
 
     def initialize_definitions
-      # Try to load from snapshot first
-      load_snapshot if @config.snapshot_provider
+      # Startup served from durable snapshot before first network — cache hit.
+      # Distinct from the subsequent refresh() network outcome (no double-count
+      # inside one refresh invocation; snapshot load is its own attempt).
+      record_definition_cache_hit if load_snapshot
 
       # Initialize with defaults if in offline mode
       if @config.offline_mode?
@@ -220,8 +330,11 @@ module Toggly
           break if @closed
 
           # When WebSocket is connected, skip HTTP refresh unless
-          # the fallback interval has elapsed
-          next if @provider.should_skip_refresh?
+          # the fallback interval has elapsed. Skipped poll = cache hit.
+          if @provider.should_skip_refresh?
+            record_definition_cache_hit
+            next
+          end
 
           refresh
         end
@@ -240,33 +353,42 @@ module Toggly
       @provider.start_websocket
     end
 
-    def load_snapshot
-      return unless @config.snapshot_provider
-
-      data = @config.snapshot_provider.load
-      return unless data
-
-      @mutex.synchronize do
-        @definitions = data[:definitions]
-      end
-
-      log_debug("Loaded #{@definitions.size} features from snapshot")
-    rescue StandardError => e
-      log_warn("Failed to load snapshot: #{e.message}")
+    def development?
+      env = ENV["RACK_ENV"] || ENV["RAILS_ENV"] || ENV["APP_ENV"] || "development"
+      env.downcase == "development"
     end
 
-    def save_snapshot
-      return unless @config.snapshot_provider
-
-      @config.snapshot_provider.save(@definitions)
-      log_debug("Saved snapshot with #{@definitions.size} features")
-    rescue StandardError => e
-      log_warn("Failed to save snapshot: #{e.message}")
+    def start_telemetry
+      return if @config.app_key.nil? || @config.app_key.empty?
+      return if ENV["TOGGLY_DISABLE_TELEMETRY"] == "1"
+      return unless @config.enable_usage_tracking || @config.enable_metrics
+
+      usage_provided = !@config.usage_client.nil?
+      metrics_provided = !@config.metrics_client.nil?
+      @telemetry = Telemetry::Runtime.new(
+        app_key: @config.app_key,
+        environment: @config.environment,
+        metrics_base_url: @config.metrics_base_url,
+        enable_usage_tracking: @config.enable_usage_tracking,
+        enable_metrics: @config.enable_metrics,
+        usage_flush_interval: @config.usage_flush_interval,
+        metrics_flush_interval: @config.metrics_flush_interval,
+        instance_name: @config.instance_name,
+        app_version: @config.app_version,
+        usage_client: @config.usage_client,
+        metrics_client: @config.metrics_client,
+        usage_client_provided: usage_provided,
+        metrics_client_provided: metrics_provided,
+        logger: @config.logger
+      )
+      @telemetry.start
     end
 
-    def development?
-      env = ENV["RACK_ENV"] || ENV["RAILS_ENV"] || ENV["APP_ENV"] || "development"
-      env.downcase == "development"
+    def record_check(feature_key, enabled, context)
+      return unless @telemetry&.usage_enabled?
+
+      identity = context&.identity
+      @telemetry.record_check(feature_key, enabled, identity)
     end
 
     def log_info(message)

data/lib/toggly/config.rb

@@ -58,11 +58,34 @@ module Toggly
     # @return [Logger, nil] Logger instance
     attr_accessor :logger
 
+    # @return [Boolean] Enable feature usage tracking (Usage.SendStats)
+    attr_accessor :enable_usage_tracking
+
+    # @return [Boolean] Enable business metrics (Metrics.SendMetrics)
+    attr_accessor :enable_metrics
+
+    # @return [String] Base URL for usage/metrics gRPC (default app.toggly.io)
+    attr_accessor :metrics_base_url
+
+    # @return [Numeric] Usage flush interval in seconds
+    attr_accessor :usage_flush_interval
+
+    # @return [Numeric] Metrics flush interval in seconds
+    attr_accessor :metrics_flush_interval
+
+    # Injectable usage transport (tests / custom senders). Must respond to +send_stats+.
+    attr_accessor :usage_client
+
+    # Injectable metrics transport (tests / custom senders). Must respond to +send_metrics+.
+    attr_accessor :metrics_client
+
     # Default values
     DEFAULT_BASE_URL = "https://definitions.toggly.io/"
     DEFAULT_REFRESH_INTERVAL = 300 # 5 minutes
     DEFAULT_HTTP_TIMEOUT = 10 # seconds
     DEFAULT_ENVIRONMENT = "Production"
+    DEFAULT_METRICS_BASE_URL = "https://app.toggly.io/"
+    DEFAULT_TELEMETRY_FLUSH_SECONDS = 60.0
 
     def initialize(**options)
       @app_key = options[:app_key]
@@ -82,6 +105,16 @@ module Toggly
       @use_signed_definitions = options[:use_signed_definitions] || false
       @allowed_key_ids = options[:allowed_key_ids] || []
       @logger = options[:logger]
+
+      telemetry_default = options.key?(:app_key) && !options[:app_key].to_s.empty? &&
+                          ENV["TOGGLY_DISABLE_TELEMETRY"] != "1"
+      @enable_usage_tracking = options.fetch(:enable_usage_tracking, telemetry_default)
+      @enable_metrics = options.fetch(:enable_metrics, telemetry_default)
+      @metrics_base_url = normalize_url(options[:metrics_base_url] || DEFAULT_METRICS_BASE_URL)
+      @usage_flush_interval = options.fetch(:usage_flush_interval, DEFAULT_TELEMETRY_FLUSH_SECONDS)
+      @metrics_flush_interval = options.fetch(:metrics_flush_interval, DEFAULT_TELEMETRY_FLUSH_SECONDS)
+      @usage_client = options[:usage_client]
+      @metrics_client = options[:metrics_client]
     end
 
     # Get the definitions endpoint URL
@@ -126,7 +159,12 @@ module Toggly
         enable_live_updates: @enable_live_updates,
         app_version: @app_version,
         instance_name: @instance_name,
-        use_signed_definitions: @use_signed_definitions
+        use_signed_definitions: @use_signed_definitions,
+        enable_usage_tracking: @enable_usage_tracking,
+        enable_metrics: @enable_metrics,
+        metrics_base_url: @metrics_base_url,
+        usage_flush_interval: @usage_flush_interval,
+        metrics_flush_interval: @metrics_flush_interval
       }
     end