toggly 1.2.1 → 1.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a484fa27dd7cc53210f2af73984c93d9109205f797172203aea42c44c4722569
-  data.tar.gz: 79a64ed42c9497e8ce8ca0f59d4dc3c21e52e68ba5e24b3b76680767d2a4787b
+  metadata.gz: d58d487720427aea654a419504c20f753656ac862aa355bf25532a97446be208
+  data.tar.gz: 60ff9681f37a920b85e25e316ffda754fb8bfe018fef1e53ea34ebbc144f437a
 SHA512:
-  metadata.gz: 07f924fb8addc26c7af35f31f0a023680201f097cfa6b26826c333a2dc3a2086c07ae094ca23413daf176546a886dbd39598914a79c0ae6cd35c8c0aeb5df564
-  data.tar.gz: 353559ba9d83853a589d843f01b52cbdb9287074b7be77505784515df99b2505317d54225456b7818c210d050b5cd170abe1a8bc315545dad5f534f9a7537244
+  metadata.gz: 2dc9099207126915eb954e3f6f8f6ce6a9d502da83e88cf9bfcd54c2574f2f4310b03b69627334d33110e5d0ff940ea0e25d33ac34c62b5cd479713b3fc6f415
+  data.tar.gz: c308b2523eea162fd10680541b103650eb07a92b7e952ad90d60e27b80fcefcc85dd7f1a27c520f03eff64681f1db69c9caf950cb383dbf824455ecce3ee4a1f

data/CHANGELOG.md

@@ -5,6 +5,36 @@ 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).
 
+## [1.4.2] - 2026-10-16
+
+### Fixed
+- Usage scopes that raise `Exception` (not only `StandardError`) record an
+  error outcome instead of treating the attempt as success [OPS-1758].
+- A clean usage scope nested in an outer `rescue` no longer inherits that
+  exception from `$!` and records a failure [OPS-1758].
+- `Interrupt`, `SystemExit`, and `SignalException` are attempt-only (no
+  error or duration), matching the Python usage-scope contract [OPS-1758].
+
+## [1.4.1] - 2026-10-15
+
+### Fixed
+- `UsageScopeRunner` uses `ensure` so non-local exits still record success or
+  failure duration after the attempt [OPS-1758].
+
+## [1.4.0] - 2026-10-11
+
+### Added
+- `Client#use` usage scope (attempt + duration + errors) and `VariantStats`
+  wire fields `errorCount`, `durationSumMs`, `errorDurationSumMs` [OPS-1758].
+
+### Fixed
+- `Client#use` and `UsageScopeRunner.run` return the block's value [OPS-1758].
+
+## [1.3.0] - 2026-10-04
+
+### Added
+- `Toggly::SegmentMembership` for Backend-key targeting-list membership updates.
+
 ## [1.2.1] - 2026-09-28
 
 ### Fixed

data/lib/toggly/client.rb

@@ -273,6 +273,24 @@ module Toggly
       @telemetry.record_usage(feature_key.to_s, identity, variant: variant)
     end
 
+    # Run a block inside a usage scope (attempt + duration + errors). Does not evaluate the flag.
+    #
+    # @yieldparam scope [Telemetry::FeatureUsageScope]
+    def use(feature_key, identity: nil, variant: "enabled", &)
+      key = feature_key.to_s
+      resolved_identity = identity.nil? ? variant_user_id(nil) : identity
+      handlers = [
+        -> { @telemetry&.record_usage(key, resolved_identity, variant: variant) },
+        ->(ms) { @telemetry&.record_usage_scope_success(key, ms, variant: variant) },
+        ->(ms) { @telemetry&.record_usage_scope_failure(key, ms, variant: variant) }
+      ]
+      if @telemetry.nil? || !@telemetry.usage_enabled?
+        scope = Telemetry::FeatureUsageScope.new
+        return yield scope
+      end
+      Telemetry::UsageScopeRunner.run(handlers, &)
+    end
+
     # Record a feature viewed/rendered event
     #
     # @param feature_key [String, Symbol]

data/lib/toggly/segment_membership.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Toggly
+  # Backend-key client for targeting-list membership on app.toggly.io.
+  class SegmentMembership
+    def initialize(app_key:, app_base_url: "https://app.toggly.io")
+      raise ArgumentError, "app_key is required" if app_key.nil? || app_key.empty?
+
+      @app_key = app_key
+      @base = app_base_url.sub(%r{/+\z}, "")
+    end
+
+    def list_segments
+      request(Net::HTTP::Get, "/api/v2/segments")
+    end
+
+    def add_segment_members(segment, identifiers)
+      request(Net::HTTP::Post, items_path(segment), { identifiers: identifiers })
+    end
+
+    def remove_segment_members(segment, identifiers)
+      request(Net::HTTP::Delete, items_path(segment), { identifiers: identifiers })
+    end
+
+    def replace_segment_members(segment, identifiers)
+      request(Net::HTTP::Put, items_path(segment), { identifiers: identifiers })
+    end
+
+    private
+
+    def items_path(segment)
+      "/api/v2/segments/#{URI.encode_www_form_component(segment).gsub("+", "%20")}/items"
+    end
+
+    def request(klass, path, body = nil)
+      uri = URI.parse("#{@base}#{path}")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = 30
+      http.read_timeout = 30
+      req = klass.new(uri)
+      req["Authorization"] = @app_key
+      req["Accept"] = "application/json"
+      if body
+        req["Content-Type"] = "application/json"
+        req.body = JSON.generate(body)
+      end
+      response = http.request(req)
+      unless response.is_a?(Net::HTTPSuccess)
+        raise Toggly::NetworkError.new(
+          "Segment membership failed",
+          status_code: response.code.to_i,
+          response_body: response.body
+        )
+      end
+
+      # Mutations may return 204/empty bodies; do not JSON-parse blank payloads.
+      body = response.body.to_s
+      return nil if body.strip.empty?
+
+      JSON.parse(body)
+    end
+  end
+end

data/lib/toggly/telemetry/grpc_clients.rb

@@ -231,7 +231,10 @@ module Toggly
               checkCount: vs[:checkCount].to_i,
               requestCount: vs[:requestCount].to_i,
               usedCount: vs[:usedCount].to_i,
-              viewedCount: vs[:viewedCount].to_i
+              viewedCount: vs[:viewedCount].to_i,
+              errorCount: vs[:errorCount].to_i,
+              durationSumMs: vs[:durationSumMs].to_i,
+              errorDurationSumMs: vs[:errorDurationSumMs].to_i
             )
           end
           sm

data/lib/toggly/telemetry/pb/usage_pb.rb

@@ -8,7 +8,7 @@
 require "google/protobuf"
 require "google/protobuf/timestamp_pb"
 
-descriptor_data = "\n\x0busage.proto\x12\x05Usage\x1a\x1fgoogle/protobuf/timestamp.proto\"\xcf\x03\n\x0b\x46\x65\x61tureStat\x12\x0e\n\x06\x61ppKey\x18\x01 \x01(\t\x12\x13\n\x0b\x65nvironment\x18\x02 \x01(\t\x12(\n\x04time\x18\x03 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12!\n\x05stats\x18\x04 \x03(\x0b\x32\x12.Usage.StatMessage\x12\x18\n\x10totalUniqueUsers\x18\x05 \x01(\x05\x12\x19\n\x0cinstanceName\x18\x06 \x01(\tH\x00\x88\x01\x01\x12\x39\n\x10processStartTime\x18\x07 \x01(\x0b\x32\x1a.google.protobuf.TimestampH\x01\x88\x01\x01\x12\x17\n\nappVersion\x18\x08 \x01(\tH\x02\x88\x01\x01\x12\x18\n\x10uniqueUserHashes\x18\t \x03(\x05\x12 \n\x13\x64\x65\x66initionCacheHits\x18\n \x01(\x05H\x03\x88\x01\x01\x12\"\n\x15\x64\x65\x66initionCacheMisses\x18\x0b \x01(\x05H\x04\x88\x01\x01\x42\x0f\n\r_instanceNameB\x13\n\x11_processStartTimeB\r\n\x0b_appVersionB\x16\n\x14_definitionCacheHitsB\x18\n\x16_definitionCacheMisses\"\xf2\x03\n\x0bStatMessage\x12\x0f\n\x07\x66\x65\x61ture\x18\x01 \x01(\t\x12\x18\n\x0c\x65nabledCount\x18\x02 \x01(\x05\x42\x02\x18\x01\x12\x19\n\rdisabledCount\x18\x03 \x01(\x05\x42\x02\x18\x01\x12+\n#uniqueContextIdentifierEnabledCount\x18\x04 \x01(\x05\x12,\n$uniqueContextIdentifierDisabledCount\x18\x05 \x01(\x05\x12%\n\x19uniqueRequestEnabledCount\x18\x06 \x01(\x05\x42\x02\x18\x01\x12&\n\x1auniqueRequestDisabledCount\x18\x07 \x01(\x05\x42\x02\x18\x01\x12\x15\n\tusedCount\x18\x08 \x01(\x05\x42\x02\x18\x01\x12\x1c\n\x14uniqueUsersUsedCount\x18\t \x01(\x05\x12\x18\n\x10uniqueUserHashes\x18\n \x03(\x05\x12:\n\x0cvariantStats\x18\x0b \x03(\x0b\x32$.Usage.StatMessage.VariantStatsEntry\x12\x1e\n\x16uniqueViewedUserHashes\x18\x0c \x03(\x05\x1aH\n\x11VariantStatsEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\"\n\x05value\x18\x02 \x01(\x0b\x32\x13.Usage.VariantStats:\x02\x38\x01\"`\n\x0cVariantStats\x12\x12\n\ncheckCount\x18\x01 \x01(\x05\x12\x14\n\x0crequestCount\x18\x02 \x01(\x05\x12\x11\n\tusedCount\x18\x03 \x01(\x05\x12\x13\n\x0bviewedCount\x18\x04 \x01(\x05\"\"\n\nStatResult\x12\x14\n\x0c\x66\x65\x61tureCount\x18\x01 \x01(\x05\x32;\n\x05Usage\x12\x32\n\tSendStats\x12\x12.Usage.FeatureStat\x1a\x11.Usage.StatResultBKZIgithub.com/ops-ai/Toggly.FeatureManagement/toggly-go/toggly/usage/usagepbb\x06proto3"
+descriptor_data = "\n\x0busage.proto\x12\x05Usage\x1a\x1fgoogle/protobuf/timestamp.proto\"\xcf\x03\n\x0b\x46\x65\x61tureStat\x12\x0e\n\x06\x61ppKey\x18\x01 \x01(\t\x12\x13\n\x0b\x65nvironment\x18\x02 \x01(\t\x12(\n\x04time\x18\x03 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12!\n\x05stats\x18\x04 \x03(\x0b\x32\x12.Usage.StatMessage\x12\x18\n\x10totalUniqueUsers\x18\x05 \x01(\x05\x12\x19\n\x0cinstanceName\x18\x06 \x01(\tH\x00\x88\x01\x01\x12\x39\n\x10processStartTime\x18\x07 \x01(\x0b\x32\x1a.google.protobuf.TimestampH\x01\x88\x01\x01\x12\x17\n\nappVersion\x18\x08 \x01(\tH\x02\x88\x01\x01\x12\x18\n\x10uniqueUserHashes\x18\t \x03(\x05\x12 \n\x13\x64\x65\x66initionCacheHits\x18\n \x01(\x05H\x03\x88\x01\x01\x12\"\n\x15\x64\x65\x66initionCacheMisses\x18\x0b \x01(\x05H\x04\x88\x01\x01\x42\x0f\n\r_instanceNameB\x13\n\x11_processStartTimeB\r\n\x0b_appVersionB\x16\n\x14_definitionCacheHitsB\x18\n\x16_definitionCacheMisses\"\xf2\x03\n\x0bStatMessage\x12\x0f\n\x07\x66\x65\x61ture\x18\x01 \x01(\t\x12\x18\n\x0c\x65nabledCount\x18\x02 \x01(\x05\x42\x02\x18\x01\x12\x19\n\rdisabledCount\x18\x03 \x01(\x05\x42\x02\x18\x01\x12+\n#uniqueContextIdentifierEnabledCount\x18\x04 \x01(\x05\x12,\n$uniqueContextIdentifierDisabledCount\x18\x05 \x01(\x05\x12%\n\x19uniqueRequestEnabledCount\x18\x06 \x01(\x05\x42\x02\x18\x01\x12&\n\x1auniqueRequestDisabledCount\x18\x07 \x01(\x05\x42\x02\x18\x01\x12\x15\n\tusedCount\x18\x08 \x01(\x05\x42\x02\x18\x01\x12\x1c\n\x14uniqueUsersUsedCount\x18\t \x01(\x05\x12\x18\n\x10uniqueUserHashes\x18\n \x03(\x05\x12:\n\x0cvariantStats\x18\x0b \x03(\x0b\x32$.Usage.StatMessage.VariantStatsEntry\x12\x1e\n\x16uniqueViewedUserHashes\x18\x0c \x03(\x05\x1aH\n\x11VariantStatsEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\"\n\x05value\x18\x02 \x01(\x0b\x32\x13.Usage.VariantStats:\x02\x38\x01\"\xa7\x01\n\x0cVariantStats\x12\x12\n\ncheckCount\x18\x01 \x01(\x05\x12\x14\n\x0crequestCount\x18\x02 \x01(\x05\x12\x11\n\tusedCount\x18\x03 \x01(\x05\x12\x13\n\x0bviewedCount\x18\x04 \x01(\x05\x12\x12\n\nerrorCount\x18\x05 \x01(\x05\x12\x15\n\rdurationSumMs\x18\x06 \x01(\x03\x12\x1a\n\x12\x65rrorDurationSumMs\x18\x07 \x01(\x03\"\"\n\nStatResult\x12\x14\n\x0c\x66\x65\x61tureCount\x18\x01 \x01(\x05\x32;\n\x05Usage\x12\x32\n\tSendStats\x12\x12.Usage.FeatureStat\x1a\x11.Usage.StatResultBKZIgithub.com/ops-ai/Toggly.FeatureManagement/toggly-go/toggly/usage/usagepbb\x06proto3"
 
 pool = ::Google::Protobuf::DescriptorPool.generated_pool
 pool.add_serialized_file(descriptor_data)

data/lib/toggly/telemetry/pb/usage_services_pb.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# Generated by the protocol buffer compiler. DO NOT EDIT!
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
 # Source: usage.proto for package 'Usage'
 
 require "grpc"

data/lib/toggly/telemetry/runtime.rb

@@ -120,6 +120,19 @@ module Toggly
         batcher&.record_view(feature, identity, variant: variant)
       end
 
+      def record_usage_scope_success(feature, duration_ms, variant: "enabled")
+        batcher = @mutex.synchronize { @usage_batcher }
+        batcher&.record_usage_duration(feature, duration_ms, variant: variant, failed: false)
+      end
+
+      def record_usage_scope_failure(feature, duration_ms, variant: "enabled")
+        batcher = @mutex.synchronize { @usage_batcher }
+        return unless batcher
+
+        batcher.record_usage_error(feature, variant: variant)
+        batcher.record_usage_duration(feature, duration_ms, variant: variant, failed: true)
+      end
+
       def record_definition_cache_hit
         batcher = @mutex.synchronize { @usage_batcher }
         batcher&.record_definition_cache_hit

data/lib/toggly/telemetry/usage_batcher.rb

@@ -4,8 +4,25 @@ module Toggly
   module Telemetry
     # In-memory feature usage aggregator (Usage.SendStats payload shape).
     class UsageBatcher
-      VariantStatsAgg = Struct.new(:check_count, :request_count, :used_count, :viewed_count, keyword_init: true) do
-        def initialize(check_count: 0, request_count: 0, used_count: 0, viewed_count: 0)
+      VariantStatsAgg = Struct.new(
+        :check_count,
+        :request_count,
+        :used_count,
+        :viewed_count,
+        :error_count,
+        :duration_sum_ms,
+        :error_duration_sum_ms,
+        keyword_init: true
+      ) do
+        def initialize(
+          check_count: 0,
+          request_count: 0,
+          used_count: 0,
+          viewed_count: 0,
+          error_count: 0,
+          duration_sum_ms: 0,
+          error_duration_sum_ms: 0
+        )
           super
         end
 
@@ -14,7 +31,10 @@ module Toggly
             checkCount: check_count,
             requestCount: request_count,
             usedCount: used_count,
-            viewedCount: viewed_count
+            viewedCount: viewed_count,
+            errorCount: error_count,
+            durationSumMs: duration_sum_ms,
+            errorDurationSumMs: error_duration_sum_ms
           }
         end
 
@@ -23,7 +43,10 @@ module Toggly
             check_count: check_count,
             request_count: request_count,
             used_count: used_count,
-            viewed_count: viewed_count
+            viewed_count: viewed_count,
+            error_count: error_count,
+            duration_sum_ms: duration_sum_ms,
+            error_duration_sum_ms: error_duration_sum_ms
           )
         end
       end
@@ -138,6 +161,27 @@ module Toggly
         end
       end
 
+      def record_usage_error(feature, variant: "enabled", count: 1)
+        return if count <= 0
+
+        @mutex.synchronize do
+          get_variant(get_feature(feature), variant.to_s).error_count += count
+        end
+      end
+
+      def record_usage_duration(feature, duration_ms, variant: "enabled", failed: false)
+        return if duration_ms <= 0
+
+        @mutex.synchronize do
+          stats = get_variant(get_feature(feature), variant.to_s)
+          if failed
+            stats.error_duration_sum_ms += duration_ms
+          else
+            stats.duration_sum_ms += duration_ms
+          end
+        end
+      end
+
       def empty?
         @mutex.synchronize { empty_unlocked? }
       end
@@ -180,6 +224,9 @@ module Toggly
               stats.request_count += snap_stats.request_count
               stats.used_count += snap_stats.used_count
               stats.viewed_count += snap_stats.viewed_count
+              stats.error_count += snap_stats.error_count
+              stats.duration_sum_ms += snap_stats.duration_sum_ms
+              stats.error_duration_sum_ms += snap_stats.error_duration_sum_ms
             end
             agg.unique_users_enabled.merge(snap_agg.unique_users_enabled)
             agg.unique_users_disabled.merge(snap_agg.unique_users_disabled)
@@ -250,7 +297,9 @@ module Toggly
         variant_stats = {}
         agg.variant_stats.each do |name, vs|
           next unless vs.check_count.positive? || vs.request_count.positive? ||
-                      vs.used_count.positive? || vs.viewed_count.positive?
+                      vs.used_count.positive? || vs.viewed_count.positive? ||
+                      vs.error_count.positive? || vs.duration_sum_ms.positive? ||
+                      vs.error_duration_sum_ms.positive?
 
           variant_stats[name] = vs.to_wire
         end

data/lib/toggly/telemetry/usage_scope.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "English"
+
+module Toggly
+  module Telemetry
+    # Tracks one usage attempt; call {#fail} to mark failure without raising.
+    class FeatureUsageScope
+      def initialize
+        @failed = false
+      end
+
+      def fail
+        @failed = true
+      end
+
+      def failed?
+        @failed
+      end
+    end
+
+    # Runs a usage-scope block and records attempt, duration, and errors.
+    module UsageScopeRunner
+      module_function
+
+      def run(handlers, &block)
+        record_attempt, record_success, record_failure = handlers
+        record_attempt.call
+        start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        scope = FeatureUsageScope.new
+        outcome_recorded = false
+        # $! is the nearest enclosing rescue, not this scope. A clean return
+        # inside an outer rescue must not inherit that exception as a failure.
+        enclosing_error = $ERROR_INFO
+        begin
+          result = block.call(scope)
+          duration_ms = elapsed_ms(start)
+          if scope.failed?
+            record_failure.call(duration_ms)
+          else
+            record_success.call(duration_ms)
+          end
+          outcome_recorded = true
+          result
+        rescue StandardError => e
+          record_failure.call(elapsed_ms(start))
+          outcome_recorded = true
+          raise e
+        ensure
+          # Non-local exits (return/break/throw) and Exception subclasses that
+          # bypass rescue StandardError still need an outcome. Only a $! raised
+          # by this scope (different from the enclosing rescue) is a failure.
+          # Interrupt / SystemExit / SignalException match Python: attempt only.
+          unless outcome_recorded
+            duration_ms = elapsed_ms(start)
+            raised_here = !$ERROR_INFO.equal?(enclosing_error)
+            if attempt_only_exception?($ERROR_INFO) && raised_here && !scope.failed?
+              # Attempt already recorded; process control exits are not failures.
+            elsif scope.failed? || raised_here
+              record_failure.call(duration_ms)
+            else
+              record_success.call(duration_ms)
+            end
+          end
+        end
+      end
+
+      def attempt_only_exception?(error)
+        error.is_a?(SystemExit) || error.is_a?(Interrupt) || error.is_a?(SignalException)
+      end
+
+      def elapsed_ms(start)
+        ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round
+        ms.negative? ? 0 : ms
+      end
+    end
+  end
+end

data/lib/toggly/telemetry.rb

@@ -2,6 +2,7 @@
 
 require_relative "telemetry/grpc_clients"
 require_relative "telemetry/usage_batcher"
+require_relative "telemetry/usage_scope"
 require_relative "telemetry/metrics_batcher"
 require_relative "telemetry/runtime"
 

data/lib/toggly/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Toggly
-  VERSION = "1.2.1"
+  VERSION = "1.4.2"
 end

data/lib/toggly.rb

@@ -37,6 +37,7 @@ require_relative "toggly/snapshot_providers/file"
 require_relative "toggly/definition_cache"
 require_relative "toggly/definitions_provider"
 require_relative "toggly/client"
+require_relative "toggly/segment_membership"
 
 # Toggly - Feature Flag Management SDK for Ruby
 #

data/proto/usage.proto

@@ -44,6 +44,9 @@ message VariantStats {
   int32 requestCount = 2;
   int32 usedCount = 3;
   int32 viewedCount = 4;
+  int32 errorCount = 5;
+  int64 durationSumMs = 6;
+  int64 errorDurationSumMs = 7;
 }
 
 message StatResult {

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: toggly
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 1.4.2
 platform: ruby
 authors:
 - Ops.ai
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-04 00:00:00.000000000 Z
+date: 2026-10-17 00:00:00.000000000 Z
 dependencies: []
 description: High-performance Ruby SDK for Toggly feature flag management. Works with
   or without Toggly.io.
@@ -52,6 +52,7 @@ files:
 - lib/toggly/http_request_mapper.rb
 - lib/toggly/registry.rb
 - lib/toggly/request_context.rb
+- lib/toggly/segment_membership.rb
 - lib/toggly/snapshot_providers/base.rb
 - lib/toggly/snapshot_providers/file.rb
 - lib/toggly/snapshot_providers/memory.rb
@@ -66,6 +67,7 @@ files:
 - lib/toggly/telemetry/runtime.rb
 - lib/toggly/telemetry/runtime_flush.rb
 - lib/toggly/telemetry/usage_batcher.rb
+- lib/toggly/telemetry/usage_scope.rb
 - lib/toggly/user_agent_parser.rb
 - lib/toggly/variant_allocator.rb
 - lib/toggly/variant_result.rb