lightrate-client 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c63b6519eeb427af97e5de527bc710be417a302dedde208d0915b259c9ef1ed7
-  data.tar.gz: 62a4447c9e7f57358552a447aa06553a51a40a116c09d376e9a3e6d4c18ddcfe
+  metadata.gz: 603315821de731679dd12cf30666482ded677ed36e4fe4c29c6aae078ad7cac7
+  data.tar.gz: bb796d172549d872a3a278f765ebea08e7db53721874cf5be126856fb00f4c98
 SHA512:
-  metadata.gz: 47024b5debeb8cbfef45d0cbdb7263bd43a7d4959acf37bf506541a12af07149dc27869775e73468793baddb0dc60d73ffa50fc4868f14fc99098b949ef42189
-  data.tar.gz: d89180c3cb9399316b73903ec63078d9bd02a522a157781916f09c154658a82024ef87064752996a77144f7ac370e97176975bf409817c7960a5820e918a003f
+  metadata.gz: 9754e47d78fadbb327059923d779853b6526afbaa4337a724d8d142beb39ea44fd0865024d6befc10172be6849b303c92b35d8772a40deed7a0a6beaa5af7ad4
+  data.tar.gz: 4535cd08a0487c99c70a80fac6c20c1f3fbec7cd3f6fefe1343ccb87233bf4497edd01c6ab82d92856054239b927c85ffe54625a9e2c9a5c93c91c8fa230c9bc

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    lightrate-client (1.0.0)
+    lightrate-client (1.0.2)
       faraday (~> 2.0)
       faraday-retry (~> 2.0)
       json (~> 2.0)

data/examples/basic_usage.rb

@@ -103,8 +103,28 @@ begin
   puts "   (These create separate buckets due to different HTTP methods)"
   puts
 
+  puts "7. Different users calling same operation:"
+  result7a = client.consume_local_bucket_token(
+    operation: 'send_notification',
+    user_identifier: 'user123'
+  )
+  result7b = client.consume_local_bucket_token(
+    operation: 'send_notification',
+    user_identifier: 'user456'
+  )
+  result7c = client.consume_local_bucket_token(
+    operation: 'send_notification',
+    user_identifier: 'user789'
+  )
+
+  puts "   User 123 - Success: #{result7a.success} #{result7a.bucket_status}"
+  puts "   User 456 - Success: #{result7b.success} #{result7b.bucket_status}"
+  puts "   User 789 - Success: #{result7c.success} #{result7c.bucket_status}"
+  puts "   (These create separate buckets due to different users)"
+  puts
+
   # Example 7: Direct API call using consume_tokens
-  puts "7. Direct API call using consume_tokens:"
+  puts "8. Direct API call using consume_tokens:"
   api_response = client.consume_tokens(
     operation: 'send_notification',
     user_identifier: 'user789',

data/examples/repeated_calls_example.rb

@@ -0,0 +1,125 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'lightrate_client'
+
+# This example demonstrates making repeated calls to the same HTTP endpoint
+# using consume_local_bucket_token. It shows how the local bucket cache
+# reduces API calls and improves performance by reusing tokens locally.
+
+# Create a client with default bucket size
+# Note: Both API key and application ID are required for all requests
+client = LightrateClient::Client.new(
+  ENV['LIGHTRATE_API_KEY'] || 'your_api_key_here',
+  ENV['LIGHTRATE_APPLICATION_ID'] || 'your_application_id_here',
+  default_local_bucket_size: 10,  # Fetch 10 tokens at a time
+  logger: ENV['DEBUG'] ? Logger.new(STDOUT) : nil
+)
+
+puts "=" * 80
+puts "Repeated HTTP Target Example"
+puts "=" * 80
+puts
+
+# Simulate making 20 calls to the same HTTP endpoint
+target_path = '/posts'
+target_method = 'GET'
+user_id = 'user_12345'
+
+puts "Making 20 calls to #{target_method} #{target_path} for user #{user_id}"
+puts
+puts "Breakdown:"
+puts "  - First call: Will fetch tokens from API (expected to return 10 tokens)"
+puts "  - Calls 2-10: Should consume from local bucket (no API calls)"
+puts "  - Call 11: Local bucket empty, will fetch more from API"
+puts "  - And so on..."
+puts
+puts "-" * 80
+puts
+
+api_calls = 0
+cache_hits = 0
+call_times = []
+
+20.times do |i|
+  call_number = i + 1
+  start_time = Time.now
+  
+  # Make the API call through the client
+  result = client.consume_local_bucket_token(
+    path: target_path,
+    http_method: target_method,
+    user_identifier: user_id
+  )
+  
+  elapsed_time = (Time.now - start_time) * 1000  # Convert to milliseconds
+  
+  call_times << elapsed_time
+  
+  if result.used_local_token
+    cache_hits += 1
+    cache_status = "✓ Local cache hit"
+  else
+    api_calls += 1
+    cache_status = "✗ API call made"
+  end
+  
+  if result.bucket_status
+    tokens_remaining = result.bucket_status[:tokens_remaining]
+    max_tokens = result.bucket_status[:max_tokens]
+    bucket_info = " | Bucket: #{tokens_remaining}/#{max_tokens} tokens"
+  else
+    bucket_info = ""
+  end
+  
+  printf "Call %2d: %s (%.2f ms)%s\n", 
+         call_number, 
+         cache_status, 
+         elapsed_time,
+         bucket_info
+end
+
+puts
+puts "-" * 80
+puts "Summary"
+puts "-" * 80
+puts "Total calls: 20"
+puts "API calls made: #{api_calls}"
+puts "Cache hits: #{cache_hits}"
+puts "Cache hit rate: #{(cache_hits.to_f / 20 * 100).round(1)}%"
+puts
+puts "Timing statistics:"
+puts "  Average time: #{(call_times.sum / call_times.length).round(2)} ms"
+puts "  Fastest call: #{call_times.min.round(2)} ms"
+puts "  Slowest call: #{call_times.max.round(2)} ms"
+puts
+
+# Show the difference between cached and non-cached calls
+if call_times.length > 0
+  api_call_times = []
+  cache_call_times = []
+  
+  20.times do |i|
+    if i == 0 || i % 10 == 0  # API calls happen on first call and when bucket is empty
+      api_call_times << call_times[i]
+    else
+      cache_call_times << call_times[i]
+    end
+  end
+  
+  if cache_call_times.any?
+    avg_cache_time = cache_call_times.sum / cache_call_times.length
+    avg_api_time = api_call_times.sum / api_call_times.length if api_call_times.any?
+    
+    if avg_api_time
+      speedup = avg_api_time / avg_cache_time
+      puts "Performance:"
+      puts "  Average cached call: #{avg_cache_time.round(2)} ms"
+      puts "  Average API call: #{avg_api_time.round(2)} ms"
+      puts "  Speed improvement: #{speedup.round(1)}x faster with cache"
+    end
+  end
+end
+
+puts
+puts "=" * 80

data/lib/lightrate_client/client.rb

@@ -37,61 +37,50 @@ module LightrateClient
     # @param user_identifier [String] The user identifier
     # @param tokens_requested [Integer] Number of tokens to consume
     def consume_local_bucket_token(operation: nil, path: nil, http_method: nil, user_identifier:)
-      # Get or create bucket for this user/operation/path combination
-      bucket = get_or_create_bucket(user_identifier, operation, path, http_method)
+      # Synchronize the entire process to prevent race conditions
+      # First, try to find an existing bucket that matches this request
+      bucket = find_bucket_by_matcher(user_identifier, operation, path, http_method)
+
+      if bucket && bucket.check_and_consume_token
+        return LightrateClient::ConsumeLocalBucketTokenResponse.new(
+          success: true,
+          used_local_token: true,
+          bucket_status: bucket.status
+        )
+      end
+
+      # No matching bucket or bucket is empty - make API call to get tokens and rule info
+      tokens_to_fetch = @configuration.default_local_bucket_size
+      
+      # Make the API call
+      response = consume_tokens(operation: operation, path: path, http_method: http_method, user_identifier: user_identifier, tokens_requested: tokens_to_fetch)
+
+      if response.rule.is_default
+        return LightrateClient::ConsumeLocalBucketTokenResponse.new(
+          success: response.tokens_consumed > 0,
+          used_local_token: false,
+          bucket_status: nil
+        )
+      end
 
-      # Use the bucket's mutex to synchronize the entire operation
-      # This prevents race conditions between multiple threads trying to consume from the same bucket
+      bucket = fill_bucket_and_create_if_not_exists(user_identifier, response.rule, response.tokens_consumed)
+
+      tokens_available = bucket.check_and_consume_token
+
+      return LightrateClient::ConsumeLocalBucketTokenResponse.new(
+        success: tokens_available,
+        used_local_token: false,
+        bucket_status: bucket.status
+      )
+    end
+
+    def consume_token_from_bucket(bucket, provided_tokens = 0)
       bucket.synchronize do
-        # Try to consume a token atomically first
-        has_tokens, consumed_successfully = bucket.check_and_consume_token
-        
-        # If we successfully consumed a local token, return success
-        if consumed_successfully
-          return LightrateClient::ConsumeLocalBucketTokenResponse.new(
-            success: true,
-            used_local_token: true,
-            bucket_status: bucket.status
-          )
-        end
+        fetch_required = !bucket.has_tokens? || bucket.expired?
 
-        # No local tokens available, need to fetch from API
-        tokens_to_fetch = get_bucket_size_for_operation(operation, path)
-        
-        # Make API call
-        request = LightrateClient::ConsumeTokensRequest.new(
-          application_id: @configuration.application_id,
-          operation: operation,
-          path: path,
-          http_method: http_method,
-          user_identifier: user_identifier,
-          tokens_requested: tokens_to_fetch
-        )
-        
-        # Make the API call
-        response = post("/api/v1/tokens/consume", request.to_h)
-        tokens_consumed = response['tokensConsumed']&.to_i || 0
-
-        # If we got tokens from API, refill the bucket and try to consume
-        if tokens_consumed > 0
-          tokens_added, has_tokens_after_refill = bucket.refill_and_check(tokens_consumed)
-          
-          # Try to consume a token after refilling
-          _, final_consumed = bucket.check_and_consume_token
-          
-          return LightrateClient::ConsumeLocalBucketTokenResponse.new(
-            success: final_consumed,
-            used_local_token: false,
-            bucket_status: bucket.status
-          )
-        else
-          # No tokens available from API
-          return LightrateClient::ConsumeLocalBucketTokenResponse.new(
-            success: false,
-            used_local_token: false,
-            bucket_status: bucket.status
-          )
-        end
+        token_available = bucket.check_and_consume_token
+
+        [token_available, fetch_required]
       end
     end
 
@@ -102,7 +91,8 @@ module LightrateClient
         path: path,
         http_method: http_method,
         user_identifier: user_identifier,
-        tokens_requested: tokens_requested
+        tokens_requested: tokens_requested,
+        tokens_requested_for_default_bucket_match: 1
       )
       consume_tokens_with_request(request)
     end
@@ -117,6 +107,8 @@ module LightrateClient
       raise ArgumentError, "Request validation failed" unless request.valid?
 
       response = post("/api/v1/tokens/consume", request.to_h)
+      # Parse JSON response if it's a string
+      response = JSON.parse(response) if response.is_a?(String)
       LightrateClient::ConsumeTokensResponse.from_hash(response)
     end
 
@@ -125,37 +117,26 @@ module LightrateClient
       @buckets_mutex = Mutex.new
     end
 
-    def get_or_create_bucket(user_identifier, operation, path, http_method = nil)
-      # Create a unique key for this user/operation/path combination
-      bucket_key = create_bucket_key(user_identifier, operation, path, http_method)
-      
-      # Double-checked locking pattern for thread-safe bucket creation
-      return @token_buckets[bucket_key] if @token_buckets[bucket_key]
+    def fill_bucket_and_create_if_not_exists(user_identifier, rule, initial_tokens)
+      bucket_key = "#{user_identifier}:rule:#{rule.id}"
       
       @buckets_mutex.synchronize do
-        # Check again inside the mutex to prevent duplicate creation
+        return @token_buckets[bucket_key] if @token_buckets[bucket_key] && !@token_buckets[bucket_key].expired?
+
         @token_buckets[bucket_key] ||= begin
-          bucket_size = get_bucket_size_for_operation(operation, path)
-          TokenBucket.new(bucket_size)
+          bucket_size = @configuration.default_local_bucket_size
+          TokenBucket.new(bucket_size, rule_id: rule.id, matcher: rule.matcher, http_method: rule.http_method, user_identifier: user_identifier)
         end
       end
-      
-      @token_buckets[bucket_key]
-    end
 
-    def get_bucket_size_for_operation(operation, path)
-      # Always use the default bucket size for all operations and paths
-      @configuration.default_local_bucket_size
+      @token_buckets[bucket_key].refill(initial_tokens)
+
+      @token_buckets[bucket_key]
     end
 
-    def create_bucket_key(user_identifier, operation, path, http_method = nil)
-      # Create a unique key that combines user, operation, and path
-      if operation
-        "#{user_identifier}:operation:#{operation}"
-      elsif path
-        "#{user_identifier}:path:#{path}:#{http_method}"
-      else
-        raise ArgumentError, "Either operation or path must be specified"
+    def find_bucket_by_matcher(user_identifier, operation, path, http_method)
+      @token_buckets.values.find do |bucket|
+        bucket.matches?(operation, path, http_method) && bucket.user_identifier == user_identifier
       end
     end
 

data/lib/lightrate_client/types.rb

@@ -3,15 +3,16 @@
 module LightrateClient
   # Request types
   class ConsumeTokensRequest
-    attr_accessor :application_id, :operation, :path, :http_method, :user_identifier, :tokens_requested, :timestamp
+    attr_accessor :application_id, :operation, :path, :http_method, :user_identifier, :tokens_requested, :tokens_requested_for_default_bucket_match, :timestamp
 
-    def initialize(application_id:, operation: nil, path: nil, http_method: nil, user_identifier:, tokens_requested:, timestamp: nil)
+    def initialize(application_id:, operation: nil, path: nil, http_method: nil, user_identifier:, tokens_requested:, tokens_requested_for_default_bucket_match: nil, timestamp: nil)
       @application_id = application_id
       @operation = operation
       @path = path
       @http_method = http_method
       @user_identifier = user_identifier
       @tokens_requested = tokens_requested
+      @tokens_requested_for_default_bucket_match = tokens_requested_for_default_bucket_match
       @timestamp = timestamp || Time.now
     end
 
@@ -23,6 +24,7 @@ module LightrateClient
         httpMethod: @http_method,
         userIdentifier: @user_identifier,
         tokensRequested: @tokens_requested,
+        tokensRequestedForDefaultBucketMatch: @tokens_requested_for_default_bucket_match,
         timestamp: @timestamp
       }.compact
     end
@@ -87,14 +89,16 @@ module LightrateClient
   end
 
   class Rule
-    attr_reader :id, :name, :refill_rate, :burst_rate, :is_default
+    attr_reader :id, :name, :refill_rate, :burst_rate, :is_default, :matcher, :http_method
 
-    def initialize(id:, name:, refill_rate:, burst_rate:, is_default: false)
+    def initialize(id:, name:, refill_rate:, burst_rate:, is_default: false, matcher: nil, http_method: nil)
       @id = id
       @name = name
       @refill_rate = refill_rate
       @burst_rate = burst_rate
       @is_default = is_default
+      @matcher = matcher
+      @http_method = http_method
     end
 
     def self.from_hash(hash)
@@ -103,18 +107,25 @@ module LightrateClient
         name: hash['name'] || hash[:name],
         refill_rate: hash['refillRate'] || hash[:refill_rate],
         burst_rate: hash['burstRate'] || hash[:burst_rate],
-        is_default: hash['isDefault'] || hash[:is_default] || false
+        is_default: hash['isDefault'] || hash[:is_default] || false,
+        matcher: hash['matcher'] || hash[:matcher],
+        http_method: hash['httpMethod'] || hash[:http_method]
       )
     end
   end
 
   # Token bucket for local token management
   class TokenBucket
-    attr_reader :available_tokens, :max_tokens
+    attr_reader :available_tokens, :max_tokens, :rule_id, :matcher, :http_method, :last_accessed_at, :user_identifier
 
-    def initialize(max_tokens)
+    def initialize(max_tokens, rule_id:, matcher:, http_method: nil, user_identifier:)
       @max_tokens = max_tokens
       @available_tokens = 0
+      @rule_id = rule_id
+      @matcher = matcher
+      @http_method = http_method
+      @last_accessed_at = Time.now
+      @user_identifier = user_identifier
       @mutex = Mutex.new
     end
 
@@ -145,10 +156,11 @@ module LightrateClient
     end
 
     # Refill the bucket with tokens from the server (caller must hold lock)
-    # @param tokens_to_fetch [Integer] Number of tokens to fetch
+    # @param tokens_to_add [Integer] Number of tokens to add
     # @return [Integer] Number of tokens actually added to the bucket
-    def refill(tokens_to_fetch)
-      tokens_to_add = [tokens_to_fetch, @max_tokens - @available_tokens].min
+    def refill(tokens_to_add)
+      touch
+      tokens_to_add = [tokens_to_add, @max_tokens - @available_tokens].min
       @available_tokens += tokens_to_add
       tokens_to_add
     end
@@ -167,29 +179,62 @@ module LightrateClient
       @available_tokens = 0
     end
 
+    # Check if this bucket matches the given request
+    def matches?(operation, path, http_method)
+      return false if expired?
+      return false unless @matcher
+      
+      begin
+        matcher_regex = Regexp.new(@matcher)
+        
+        # For operation-based requests, match against operation
+        if operation
+          return matcher_regex.match?(operation) && @http_method.nil?
+        end
+        
+        # For path-based requests, match against path and HTTP method
+        if path
+          return matcher_regex.match?(path) && @http_method == http_method
+        end
+        
+        false
+      rescue RegexpError
+        # If matcher is not a valid regex, fall back to exact match
+        if operation
+          return @matcher == operation && @http_method.nil?
+        elsif path
+          return @matcher == path && @http_method == http_method
+        end
+        false
+      end
+    end
+
+    # Check if bucket has expired (not accessed in 60 seconds)
+    def expired?
+      Time.now - @last_accessed_at > 60
+    end
+
+    # Update last accessed time
+    def touch
+      @last_accessed_at = Time.now
+    end
+
     # Check tokens and consume atomically (caller must hold lock)
     # This prevents race conditions between checking and consuming
     # @return [Array] [has_tokens, consumed_successfully]
     def check_and_consume_token
-      has_tokens = @available_tokens > 0
-      if has_tokens
-        @available_tokens -= 1
-        [true, true]
-      else
-        [false, false]
+      synchronize do
+        touch
+        has_tokens = @available_tokens > 0
+        if has_tokens
+          @available_tokens -= 1
+          true
+        else
+          false
+        end
       end
     end
 
-    # Refill and check tokens atomically (caller must hold lock)
-    # @param tokens_to_fetch [Integer] Number of tokens to fetch
-    # @return [Array] [tokens_added, has_tokens_after_refill]
-    def refill_and_check(tokens_to_fetch)
-      tokens_to_add = [tokens_to_fetch, @max_tokens - @available_tokens].min
-      @available_tokens += tokens_to_add
-      has_tokens_after = @available_tokens > 0
-      [tokens_to_add, has_tokens_after]
-    end
-
     # Synchronize access to this bucket for thread-safe operations
     # @yield Block to execute under bucket lock
     def synchronize(&block)

data/lib/lightrate_client/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LightrateClient
-  VERSION = "1.0.1"
+  VERSION = "1.0.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lightrate-client
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
 platform: ruby
 authors:
 - Lightbourne Technologies
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-10-16 00:00:00.000000000 Z
+date: 2025-11-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -179,6 +179,7 @@ files:
 - README.md
 - Rakefile
 - examples/basic_usage.rb
+- examples/repeated_calls_example.rb
 - lib/lightrate_client.rb
 - lib/lightrate_client/client.rb
 - lib/lightrate_client/configuration.rb