cymometer 1.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 150360c27078f80b80d9531315d4889593e0351fcca5a6a91825ac293ea9d56a
+  data.tar.gz: 3933828dedeed48b056b6e9e61e8c0e31ad66ea193734ee79df2aa817cd3a05d
+SHA512:
+  metadata.gz: a558786ac975e737ae70e32fe1c4293f6f55faad9294a1208871a1c3f06d09e2325437b9b60aa7b9a269280949696fbbda8d03b5b1ca669eedf4a40d49c528c2
+  data.tar.gz: 47fefe6630bb6303a31e8359597e606391296257218670492342b8b7f3793ff97cf78fb10f9dfbe21a2f09c7ff3ed9c6c5be68b6140c86c9b743f22ffec7cb44

data/.ruby-version

@@ -0,0 +1 @@
+3.3.4

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Charlton Trezevant
+
+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,313 @@
+# Cymometer
+
+<img src="./.github/cymometer.jpg" width="230" />
+
+Cymometer is a decaying counter for rate limiting using Redis. It provides a simple and efficient mechanism for counting events over a sliding time window, which is useful in applications such as rate limiting.
+
+Cymometer uses Redis sorted sets and Lua scripts to maintain atomic increment and decrement operations, ensuring accurate and thread-safe counting in distributed systems.
+
+### Features
+
+- **Atomic Operations:** Uses Redis Lua scripts for atomic increment and decrement.
+- **Configurable Limits:** Set custom limits and time windows for your counters.
+- **Transaction Support:** Execute blocks of code only if the counter can be incremented.
+- **No Redis Client Dependency:** Works with any Redis client, as long as you assign it to `Cymometer.redis`.
+- **Helper DSL:** Optional, makes it easy to add per-class, named rate limiters to jobs, service objects, or any Ruby class.
+
+## Installation
+
+```ruby
+gem 'cymometer'
+```
+
+## Usage
+
+### Configuration 
+
+First, assign a Redis client to `Cymometer.redis` before using the gem:
+
+```ruby
+require 'redis'
+require 'cymometer'
+
+# Initialize Redis client
+redis = Redis.new(host: 'localhost', port: 6379, db: 0)
+
+# Assign Redis client to Cymometer
+Cymometer.redis = redis
+```
+
+The Cymometer gem does not specify a dependency on a particular Redis client. You can configure a default Redis client to be used by all Cymometer counters, or supply one to the `Cymometer::Counter` initializer.
+
+#### Global Configuration
+
+```ruby
+custom_redis = Redis.new(host: 'localhost', port: 6379, db: 1)
+Cymometer.redis = custom_redis
+```
+
+#### Per-Counter Configuration
+
+```ruby
+custom_redis = Redis.new(host: 'localhost', port: 6379, db: 1)
+
+counter = Cymometer::Counter.new(
+  key_namespace: 'api',
+  key: 'user_456',
+  limit: 500,
+  window: 1800,     # 30 minutes
+  redis: custom_redis
+)
+```
+
+### Create a Counter 
+
+Create a new counter with a namespace, key, limit, and window size:
+
+```ruby
+counter = Cymometer::Counter.new(
+  key_namespace: 'api',
+  key: 'user_123',
+  limit: 1000, # Maximum allowed actions in the time window
+  window: 3600 # Time window in seconds (e.g., 1 hour)
+)
+```
+
+#### Options 
+
+- `key_namespace`: A namespace to group related counters.
+- `key`: A unique identifier for the counter (e.g., user ID).
+- `limit`: The maximum number of allowed actions within the time window.
+- `window`: The time window in seconds over which the actions are counted.
+
+
+### Increment a Counter 
+
+To increment the counter and check if the limit has been exceeded:
+
+```ruby
+begin
+  count = counter.increment!
+  puts "Counter incremented. Current count: #{count}"
+rescue Cymometer::Counter::LimitExceeded => e
+  puts "Rate limit exceeded: #{e.message}"
+end
+```
+
+If the limit is not exceeded, increment! returns the current count. Otherwise, a `Cymometer::Counter::LimitExceeded` exception is raised.
+
+### Decrement a Counter 
+
+If you need to undo an action (e.g., due to an error), you can decrement the counter:
+
+```ruby
+count = counter.decrement!
+puts "Counter decremented. Current count: #{count}"
+```
+
+The `decrement!` method safely decrements the counter by removing the oldest entry. If the counter is already at zero, it remains unchanged.
+
+### Getting the Current Count
+
+To retrieve the current count without modifying the counter:
+
+```ruby
+puts "Current count: #{counter.count}"
+```
+
+### Using Transactions
+
+Transactions allow you to execute a block of code only if the counter can be incremented:
+
+```ruby
+begin
+  result = counter.transaction do
+    # Your rate-limited code goes here
+    perform_api_call
+    "Success"
+  end
+  puts result
+rescue Cymometer::Counter::LimitExceeded => e
+  puts "Rate limit exceeded: #{e.message}"
+rescue => e
+  puts "An error occurred: #{e.message}"
+end
+```
+
+If the counter can be incremented, the block is executed. If the block raises an exception, the counter is decremented automatically, and the exception is re-raised. If the limit is exceeded, the block is not executed, and `Cymometer::Counter::LimitExceeded` is raised.
+
+#### Rollback Behavior
+
+If you want the counter to remain incremented even when an exception occurs (i.e., not roll back the increment), set `rollback` to false:
+
+```ruby
+begin
+  result = counter.transaction(rollback: false) do
+    # Your rate-limited code here
+    perform_api_call
+    "Success"
+  end
+  puts result
+rescue Cymometer::Counter::LimitExceeded => e
+  puts "Rate limit exceeded: #{e.message}"
+rescue => e
+  puts "An error occurred: #{e.message}"
+  # The counter remains incremented despite the exception
+end
+```
+
+###### Rollback Enabled (default)
+
+Useful when you want to ensure that only successful actions count against the rate limit (e.g., API endpoints where you don’t want failed requests (due to server errors) to penalize the user).
+
+###### Rollback Disabled (with `rollback: false`)
+
+Useful when you want all attempts, successful or not, to count against the rate limit to prevent abuse (e.g., login attempts where you need to prevent brute-force attacks by limiting the number of attempts regardless of success).
+
+### Cymometer::Helper DSL
+
+The `Cymometer::Helper` DSL makes it easy to add per-class, named rate limiters to jobs, service objects, or any Ruby class. Counters are lazily instantiated and memoized per instance, so repeat calls are efficient. You declare your counters and options up front with a simple block, then access them with the counter method. No boilerplate required!
+
+#### When to Use
+- **Background jobs:** Limit how often certain work can be performed per job type or account.
+- **Custom service classes:** Rate limit expensive or risky operations across different classes or namespaces.
+- **Dynamic keys:** Build counter keys from instance data (e.g., a user ID, IP address, etc) at runtime.
+
+#### How It Works
+1. Include the module in your class.
+2. Declare counters and options in a configure_cymometer block using a simple DSL.
+3. Access counters by name with counter(:counter_name) anywhere in your class.
+
+#### DSL Options
+- `namespace "my_app"`: Sets a prefix for all counter keys.
+- `counter :name do ... end`: Defines a new counter. Inside the block, you can specify:
+  - `limit`: Max actions per window.
+  - `window`: Time window in seconds.
+  - `key { ... }`: (Optional) Block to dynamically build the counter's unique key using instance data.
+
+
+Here's an example:
+
+```ruby
+class MyJob
+  include Cymometer::Helper
+
+  configure_cymometer do
+    namespace "my_app"
+
+    counter :fast_calls do
+      limit 10        # max 10 per window
+      window 30       # 30 seconds
+    end
+
+    counter :slow_calls do
+      limit 3
+      window 300      # 5 minutes
+      key { some_dynamic_method } # key is built at runtime
+    end
+  end
+
+  def perform
+    # Increment and check the :fast_calls rate limit
+    counter(:fast_calls).increment!
+
+    # Use a transaction for the :slow_calls counter
+    counter(:slow_calls).transaction do
+      do_something_slow
+    end
+  end
+
+  private
+
+  def some_dynamic_method
+    "user_#{user_id}"
+  end
+end
+```
+
+> [!NOTE]
+> Centralizing your rate limits into configuration (e.g, `Rails.application.config_for(:rate_limits)[:my_job][:fast_calls]` in Rails) is a great way to keep them clear, maintainable, and easy to test.
+
+#### Testing with Cymometer::Helper
+
+<details>
+
+<summary> 🛠️ Tips and Tricks </summary>
+
+
+`Cymometer::Helper` makes it very straightforward to test rate limiting configuration and behavior in your test suite. We'll use RSpec for these examples, but you could achieve the same result with Minitest or your preferred test suite.
+
+To start, create a `Cymometer::Counter` test double:
+
+```ruby
+let(:test_counter) { instance_double("Cymometer::Counter") }
+```
+
+Then, add some stubs. In the example below, we configure spy methods to return our test double from `Cymometer::Counter#new`, and configure the `transaction` and `increment!` methods to increment an instance variable counter for our tests. 
+
+```ruby
+  allow(Cymometer::Counter).to receive(:new).and_return(test_counter)
+  @transactions_counter = 0
+
+  allow(test_counter).to receive(:transaction) do |&block|
+    @transactions_counter += 1
+    block&.call
+  end
+
+  allow(test_counter).to receive(:increment!) { @transactions_counter += 1 }
+```
+
+You can then wire up tests for rate limiting behavior. Here's an example:
+
+
+```ruby
+  describe "rate limiting behavior" do
+    before do
+      @transactions_counter = 0
+    end
+
+    # Tests for configuration
+    it "configures and uses Cymometer counters for rate limiting" do
+      counters = described_class.cymometer_counters
+
+      expect(counters[:hour_api_calls]).not_to be_nil
+      expect(counters[:hour_api_calls][:limit]).to equal(Rails.application.config_for(:rate_limits)[:api_calls_job][:per_hour])
+      expect(counters[:hour_api_calls][:window]).to equal(1.hour.to_i)
+    end
+
+    # Tests for behavior
+    context "for a project in trial mode" do
+      let(:job) { described_class.new }
+
+      before do
+        allow(project).to receive(:trial_mode?).and_return(true)
+      end
+
+      it "increments all counters" do
+        @transactions_counter = 0
+
+        described_class.perform_now(backlog_entry)
+
+        expect(@transactions_counter).to eq(2)
+      end
+    end
+  end
+
+```
+
+</details>
+
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/packfiles/cymometer.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "standard/rake"
+
+task default: %i[test standard]

data/lib/cymometer/configuration.rb

@@ -0,0 +1,13 @@
+module Cymometer
+  class RedisNotConfigured < StandardError; end
+
+  class << self
+    attr_writer :redis
+
+    def redis
+      raise RedisNotConfigured, "Please assign a Redis client to Cymometer.redis before using the gem." unless @redis
+
+      @redis
+    end
+  end
+end

data/lib/cymometer/counter.rb

@@ -0,0 +1,148 @@
+require "securerandom"
+
+module Cymometer
+  class Counter
+    class LimitExceeded < StandardError; end
+
+    DEFAULT_WINDOW = 3600 # Default window is 1 hour
+
+    attr_reader :window, :limit, :key
+
+    INCREMENT_LUA_SCRIPT = <<-LUA
+      local key = KEYS[1]
+      local current_time = tonumber(ARGV[1])
+      local window = tonumber(ARGV[2])
+      local limit = tonumber(ARGV[3])
+
+      -- Remove entries older than the window size
+      redis.call('ZREMRANGEBYSCORE', key, 0, current_time - window)
+
+      -- Get the current count
+      local count = redis.call('ZCOUNT', key, current_time - window, '+inf')
+
+      if count >= limit then
+        -- Limit exceeded, do not increment
+        return {0, count}
+      else
+        -- Increment the counter
+        redis.call('ZADD', key, current_time, current_time)
+        redis.call('EXPIRE', key, math.floor(window / 1000000))
+        return {1, count + 1}
+      end
+    LUA
+
+    DECREMENT_LUA_SCRIPT = <<-LUA
+      local key = KEYS[1]
+      local current_time = tonumber(ARGV[1])
+      local window = tonumber(ARGV[2])
+
+      -- Remove entries older than the window size
+      redis.call('ZREMRANGEBYSCORE', key, 0, current_time - window)
+
+      -- Attempt to remove the entry with the lowest score (oldest entry)
+      local entries = redis.call('ZRANGEBYSCORE', key, current_time - window, '+inf', 'LIMIT', 0, 1)
+
+      if next(entries) == nil then
+        -- No entries to remove, safe no-op
+        local count = 0
+        return {1, count}
+      else
+        local member = entries[1]
+        redis.call('ZREM', key, member)
+        local count = redis.call('ZCOUNT', key, current_time - window, '+inf')
+        return {1, count}
+      end
+    LUA
+
+    def initialize(key_namespace: nil, key: nil, limit: nil, window: nil, redis: nil)
+      @redis = redis || Cymometer.redis
+      @key = "#{key_namespace || "cymometer"}:#{key || generate_key}"
+      @window = window || DEFAULT_WINDOW
+      @limit = limit || 1
+      @increment_sha = nil
+      @decrement_sha = nil
+    end
+
+    # Atomically increments the counter and checks the limit
+    def increment!
+      current_time = (Time.now.to_f * 1_000_000).to_i # Microseconds
+      window = @window * 1_000_000 # Convert to microseconds
+
+      result = evalsha_with_fallback(
+        :increment,
+        INCREMENT_LUA_SCRIPT,
+        keys: [@key],
+        argv: [current_time, window, @limit]
+      )
+
+      success = result[0] == 1
+      count = result[1].to_i
+
+      raise LimitExceeded, "Limit of #{@limit} exceeded with count #{count}" unless success
+
+      count
+    end
+
+    # Atomically decrements the counter by removing the oldest entry
+    def decrement!
+      current_time = (Time.now.to_f * 1_000_000).to_i
+      window = @window * 1_000_000
+
+      result = evalsha_with_fallback(
+        :decrement,
+        DECREMENT_LUA_SCRIPT,
+        keys: [@key],
+        argv: [current_time, window]
+      )
+
+      result[1].to_i
+    end
+
+    # Returns the current count
+    def count
+      current_time = (Time.now.to_f * 1_000_000).to_i
+      window = @window * 1_000_000
+
+      # Clean expired entries
+      @redis.zremrangebyscore(@key, 0, current_time - window)
+      @redis.zcount(@key, current_time - window, "+inf").to_i
+    end
+
+    # Executes a block if the counter can be incremented.
+    # If the block raises an exception, decrements the counter and re-raises the exception.
+    def transaction(rollback: true)
+      increment!
+      begin
+        yield
+      rescue => e
+        decrement! if rollback
+        raise e
+      end
+    end
+
+    private
+
+    def generate_key
+      SecureRandom.uuid
+    end
+
+    def evalsha_with_fallback(type, script, keys:, argv:)
+      sha_var = (type == :increment) ? :@increment_sha : :@decrement_sha
+
+      sha = instance_variable_get(sha_var)
+      begin
+        # Try EVALSHA first
+        sha ||= @redis.script(:load, script)
+        instance_variable_set(sha_var, sha)
+        @redis.evalsha(sha, keys: keys, argv: argv)
+      rescue Redis::CommandError => e
+        raise unless e.message.include?("NOSCRIPT")
+
+        # If the script wasn't loaded, reload and try again
+        sha = @redis.script(:load, script)
+        instance_variable_set(sha_var, sha)
+        @redis.evalsha(sha, keys: keys, argv: argv)
+      end
+    end
+  end
+end

data/lib/cymometer/helper.rb

@@ -0,0 +1,170 @@
+# Helpers for configuring/working with Cymometer::Counters in classes
+# (like background jobs) that require rate limit accounting
+module Cymometer
+  module Helper
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    # ------------------------------------------------------
+    # 1) Class-level methods
+    # ------------------------------------------------------
+    module ClassMethods
+      #
+      # DSL entrypoint
+      #
+      #   configure_cymometer do
+      #     namespace "my_namespace"
+      #     redis MyCustomRedis
+      #
+      #     counter :some_counter do
+      #       limit 10
+      #       window 60
+      #       key { "dynamic_key_for_#{self.object_id}" }
+      #     end
+      #   end
+      #
+      def configure_cymometer(&block)
+        DSL.new(self).instance_eval(&block)
+      end
+
+      #
+      # Access the counters hash
+      #
+      def cymometer_counters
+        @cymometer_counters ||= {}
+      end
+
+      #
+      # Accessors for the optional shared namespace & redis client
+      #
+      def cymometer_namespace
+        @cymometer_namespace
+      end
+
+      def cymometer_redis
+        @cymometer_redis
+      end
+
+      #
+      # Retrieve the stored counter config (hash) by name
+      #
+      def counter_config(name)
+        cymometer_counters[name.to_sym]
+      end
+    end
+
+    # ------------------------------------------------------
+    # 2) Instance-level method to fetch a configured counter
+    # ------------------------------------------------------
+    #
+    #   def perform
+    #     c = counter(:some_counter)
+    #     c.increment!
+    #   end
+    #
+    def counter(name)
+      config = self.class.counter_config(name)
+      raise "No Cymometer counter named #{name.inspect} in #{self.class}" unless config
+
+      # Memoize per-instance so we only build once
+      @__cymometer_counter_cache ||= {}
+      @__cymometer_counter_cache[name.to_sym] ||= build_cymometer_counter(config)
+    end
+
+    private
+
+    def build_cymometer_counter(config)
+      # Evaluate the 'key' if it's a Proc/Block
+      real_key =
+        if config[:key].respond_to?(:call)
+          instance_exec(&config[:key]) # The block is run in instance context
+        elsif config[:key]
+          config[:key].to_s
+        else
+          config[:name].to_s # Fallback to the counter's name
+        end
+
+      Cymometer::Counter.new(
+        key_namespace: config[:namespace] || self.class.cymometer_namespace || "cymometer",
+        key: real_key,
+        limit: config[:limit] || 1,
+        window: config[:window] || 3600,
+        redis: config[:redis] || self.class.cymometer_redis || Cymometer.redis
+      )
+    end
+
+    # ------------------------------------------------------
+    # 3) DSL builder classes for configure_cymometer
+    # ------------------------------------------------------
+    class DSL
+      def initialize(klass)
+        @klass = klass
+      end
+
+      def namespace(ns)
+        @klass.instance_variable_set(:@cymometer_namespace, ns)
+      end
+
+      def redis(client)
+        @klass.instance_variable_set(:@cymometer_redis, client)
+      end
+
+      def counter(name, &block)
+        conf = CounterConfig.new(name)
+        conf.instance_eval(&block) if block
+
+        # Merge into class's counters
+        new_counters = @klass.cymometer_counters.dup
+        new_counters[name.to_sym] = conf.to_h
+        @klass.instance_variable_set(:@cymometer_counters, new_counters)
+      end
+    end
+
+    class CounterConfig
+      attr_accessor :name, :limit, :window, :key, :redis, :namespace
+
+      def initialize(name)
+        @name = name.to_s
+      end
+
+      # standard:disable Lint/DuplicateMethods
+      # standard:disable Style/TrivialAccessors
+
+      # DSL methods
+      def limit(val)
+        @limit = val
+      end
+
+      def window(val)
+        @window = val
+      end
+
+      def key(val = nil, &block)
+        @key = block || val
+      end
+
+      def redis(client)
+        @redis = client
+      end
+
+      def namespace(ns)
+        @namespace = ns
+      end
+
+      # standard:enable Lint/DuplicateMethods
+      # standard:enable Style/TrivialAccessors
+
+      def to_h
+        {
+          name: @name,
+          limit: @limit,
+          window: @window,
+          key: @key,
+          redis: @redis,
+          namespace: @namespace
+        }
+      end
+    end
+  end
+end

data/lib/cymometer/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Cymometer
+  VERSION = "1.2.0"
+end

data/lib/cymometer.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "cymometer/version"
+require_relative "cymometer/configuration"
+require_relative "cymometer/counter"
+require_relative "cymometer/helper"
+
+module Cymometer
+end

data/sig/cymometer.rbs

@@ -0,0 +1,4 @@
+module Cymometer
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: cymometer
+version: !ruby/object:Gem::Version
+  version: 1.2.0
+platform: ruby
+authors:
+- Charlton Trezevant
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-06-11 00:00:00.000000000 Z
+dependencies: []
+description: A simple, atomic, memory-efficient frequency counter backed by Redis
+  Sorted Sets.
+email:
+- charlton@packfiles.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".ruby-version"
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/cymometer.rb
+- lib/cymometer/configuration.rb
+- lib/cymometer/counter.rb
+- lib/cymometer/helper.rb
+- lib/cymometer/version.rb
+- sig/cymometer.rbs
+homepage: https://github.com/packfiles/cymometer
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/packfiles/cymometer
+  source_code_uri: https://github.com/packfiles/cymometer
+  changelog_uri: https://github.com/packfiles/cymometer
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: A simple, atomic, memory-efficient frequency counter backed by Redis Sorted
+  Sets.
+test_files: []