lightrate-rails 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 30dc222ab05943e69909f0fed5361b5b470613bda38b6c2908114e2564d9e2a7
+  data.tar.gz: 3fe845e284c5378a8241fac838f885709b2438d466182f41244021afbe3d3d1a
+SHA512:
+  metadata.gz: d39ed9be6dc10b7ad1f693c4bdeb0f42f82fd8cc0b93f83c7e6cdfecd7a7a50c049f6e801c3aa6f5c28cd65624aed08d2768d8e4ddc7859f2e72f2e5094b3480
+  data.tar.gz: 98014b3bb3baeacff7a236344db56e360c069e3fb1b5b5f9b548d17d2bea2036a4c09580c5a03bc82c113e718e7403e43780e270ff1b660bd9f4484ac05c181d

data/Gemfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in lightrate-rails.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,328 @@
+PATH
+  remote: .
+  specs:
+    lightrate-rails (1.0.0)
+      lightrate-client (~> 1.0)
+      rails (>= 6.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actioncable (8.0.3)
+      actionpack (= 8.0.3)
+      activesupport (= 8.0.3)
+      nio4r (~> 2.0)
+      websocket-driver (>= 0.6.1)
+      zeitwerk (~> 2.6)
+    actionmailbox (8.0.3)
+      actionpack (= 8.0.3)
+      activejob (= 8.0.3)
+      activerecord (= 8.0.3)
+      activestorage (= 8.0.3)
+      activesupport (= 8.0.3)
+      mail (>= 2.8.0)
+    actionmailer (8.0.3)
+      actionpack (= 8.0.3)
+      actionview (= 8.0.3)
+      activejob (= 8.0.3)
+      activesupport (= 8.0.3)
+      mail (>= 2.8.0)
+      rails-dom-testing (~> 2.2)
+    actionpack (8.0.3)
+      actionview (= 8.0.3)
+      activesupport (= 8.0.3)
+      nokogiri (>= 1.8.5)
+      rack (>= 2.2.4)
+      rack-session (>= 1.0.1)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+      useragent (~> 0.16)
+    actiontext (8.0.3)
+      actionpack (= 8.0.3)
+      activerecord (= 8.0.3)
+      activestorage (= 8.0.3)
+      activesupport (= 8.0.3)
+      globalid (>= 0.6.0)
+      nokogiri (>= 1.8.5)
+    actionview (8.0.3)
+      activesupport (= 8.0.3)
+      builder (~> 3.1)
+      erubi (~> 1.11)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+    activejob (8.0.3)
+      activesupport (= 8.0.3)
+      globalid (>= 0.3.6)
+    activemodel (8.0.3)
+      activesupport (= 8.0.3)
+    activerecord (8.0.3)
+      activemodel (= 8.0.3)
+      activesupport (= 8.0.3)
+      timeout (>= 0.4.0)
+    activestorage (8.0.3)
+      actionpack (= 8.0.3)
+      activejob (= 8.0.3)
+      activerecord (= 8.0.3)
+      activesupport (= 8.0.3)
+      marcel (~> 1.0)
+    activesupport (8.0.3)
+      base64
+      benchmark (>= 0.3)
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
+    addressable (2.8.7)
+      public_suffix (>= 2.0.2, < 7.0)
+    ast (2.4.3)
+    base64 (0.3.0)
+    benchmark (0.4.1)
+    bigdecimal (3.2.3)
+    builder (3.3.0)
+    concurrent-ruby (1.3.5)
+    connection_pool (2.5.4)
+    crack (1.0.0)
+      bigdecimal
+      rexml
+    crass (1.0.6)
+    date (3.4.1)
+    diff-lcs (1.6.2)
+    docile (1.4.1)
+    drb (2.2.3)
+    erb (5.0.2)
+    erubi (1.13.1)
+    faraday (2.14.0)
+      faraday-net_http (>= 2.0, < 3.5)
+      json
+      logger
+    faraday-net_http (3.4.1)
+      net-http (>= 0.5.0)
+    faraday-retry (2.3.2)
+      faraday (~> 2.0)
+    globalid (1.3.0)
+      activesupport (>= 6.1)
+    hashdiff (1.2.1)
+    i18n (1.14.7)
+      concurrent-ruby (~> 1.0)
+    io-console (0.8.1)
+    irb (1.15.2)
+      pp (>= 0.6.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    json (2.15.0)
+    language_server-protocol (3.17.0.5)
+    lightrate-client (1.0.0)
+      faraday (~> 2.0)
+      faraday-retry (~> 2.0)
+      json (~> 2.0)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    loofah (2.24.1)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.12.0)
+    mail (2.8.1)
+      mini_mime (>= 0.1.1)
+      net-imap
+      net-pop
+      net-smtp
+    marcel (1.1.0)
+    mini_mime (1.1.5)
+    minitest (5.25.5)
+    net-http (0.6.0)
+      uri
+    net-imap (0.5.11)
+      date
+      net-protocol
+    net-pop (0.1.2)
+      net-protocol
+    net-protocol (0.2.2)
+      timeout
+    net-smtp (0.5.1)
+      net-protocol
+    nio4r (2.7.4)
+    nokogiri (1.18.10-aarch64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.18.10-aarch64-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.18.10-arm-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.18.10-arm-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.18.10-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.18.10-x86_64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.18.10-x86_64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.18.10-x86_64-linux-musl)
+      racc (~> 1.4)
+    parallel (1.27.0)
+    parser (3.3.9.0)
+      ast (~> 2.4.1)
+      racc
+    pp (0.6.2)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.5.1)
+    psych (5.2.6)
+      date
+      stringio
+    public_suffix (6.0.2)
+    racc (1.8.1)
+    rack (3.2.1)
+    rack-session (2.1.1)
+      base64 (>= 0.1.0)
+      rack (>= 3.0.0)
+    rack-test (2.2.0)
+      rack (>= 1.3)
+    rackup (2.2.1)
+      rack (>= 3)
+    rails (8.0.3)
+      actioncable (= 8.0.3)
+      actionmailbox (= 8.0.3)
+      actionmailer (= 8.0.3)
+      actionpack (= 8.0.3)
+      actiontext (= 8.0.3)
+      actionview (= 8.0.3)
+      activejob (= 8.0.3)
+      activemodel (= 8.0.3)
+      activerecord (= 8.0.3)
+      activestorage (= 8.0.3)
+      activesupport (= 8.0.3)
+      bundler (>= 1.15.0)
+      railties (= 8.0.3)
+    rails-dom-testing (2.3.0)
+      activesupport (>= 5.0.0)
+      minitest
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.6.2)
+      loofah (~> 2.21)
+      nokogiri (>= 1.15.7, != 1.16.7, != 1.16.6, != 1.16.5, != 1.16.4, != 1.16.3, != 1.16.2, != 1.16.1, != 1.16.0.rc1, != 1.16.0)
+    railties (8.0.3)
+      actionpack (= 8.0.3)
+      activesupport (= 8.0.3)
+      irb (~> 1.13)
+      rackup (>= 1.0.0)
+      rake (>= 12.2)
+      thor (~> 1.0, >= 1.2.2)
+      tsort (>= 0.2)
+      zeitwerk (~> 2.6)
+    rainbow (3.1.1)
+    rake (13.3.0)
+    rdoc (6.14.2)
+      erb
+      psych (>= 4.0.0)
+    regexp_parser (2.11.3)
+    reline (0.6.2)
+      io-console (~> 0.5)
+    rexml (3.4.4)
+    rspec (3.13.1)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.5)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-rails (6.1.5)
+      actionpack (>= 6.1)
+      activesupport (>= 6.1)
+      railties (>= 6.1)
+      rspec-core (~> 3.13)
+      rspec-expectations (~> 3.13)
+      rspec-mocks (~> 3.13)
+      rspec-support (~> 3.13)
+    rspec-support (3.13.6)
+    rubocop (1.81.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.47.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
+    rubocop-capybara (2.22.1)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.72, >= 1.72.1)
+    rubocop-factory_bot (2.27.1)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.72, >= 1.72.1)
+    rubocop-rspec (2.31.0)
+      rubocop (~> 1.40)
+      rubocop-capybara (~> 2.17)
+      rubocop-factory_bot (~> 2.22)
+      rubocop-rspec_rails (~> 2.28)
+    rubocop-rspec_rails (2.29.1)
+      rubocop (~> 1.61)
+    ruby-progressbar (1.13.0)
+    securerandom (0.4.1)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.2)
+    simplecov_json_formatter (0.1.4)
+    stringio (3.1.7)
+    thor (1.4.0)
+    timeout (0.4.3)
+    tsort (0.2.0)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.1.0)
+    uri (1.0.3)
+    useragent (0.16.11)
+    vcr (6.3.1)
+      base64
+    webmock (3.25.1)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+    websocket-driver (0.8.0)
+      base64
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.5)
+    zeitwerk (2.7.3)
+
+PLATFORMS
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm-linux-gnu
+  arm-linux-musl
+  arm64-darwin
+  x86_64-darwin
+  x86_64-linux-gnu
+  x86_64-linux-musl
+
+DEPENDENCIES
+  bundler (~> 2.0)
+  lightrate-rails!
+  rake (~> 13.0)
+  rspec (~> 3.0)
+  rspec-rails (~> 6.0)
+  rubocop (~> 1.0)
+  rubocop-rspec (~> 2.0)
+  simplecov (~> 0.21)
+  vcr (~> 6.0)
+  webmock (~> 3.0)
+
+BUNDLED WITH
+   2.5.21

data/README.md

@@ -0,0 +1,346 @@
+# Lightrate Rails
+
+A Ruby on Rails integration gem for LightRate API throttling. This gem provides seamless integration with the LightRate API using controller before_actions to automatically throttle requests using local token buckets that automatically refill from the server when needed.
+
+## Features
+
+- **Controller-Level Throttling**: Use `throttle_with_lightrate` in any controller to enable automatic rate limiting
+- **Flexible User Identification**: Customize user identification per-controller with full access to controller context
+- **Local Token Bucket Only**: Uses only the local token bucket approach for efficient throttling with automatic server refills
+- **Custom Exception Handling**: Raises `LightRateNoTokensAvailable` when no tokens are available
+- **Fine-Grained Control**: Use `:only` or `:except` options to throttle specific actions
+- **Controller Helpers**: Manual token consumption methods for advanced use cases
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'lightrate-rails'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install lightrate-rails
+```
+
+## Configuration
+
+### Basic Setup
+
+**Required:** Configure Lightrate in your Rails application initializer:
+
+```ruby
+# config/initializers/lightrate_rails.rb
+
+LightrateRails.configure do |config|
+  # Required: Your LightRate API key
+  config.api_key = ENV['LIGHTRATE_API_KEY']
+  
+  # Required: Your LightRate Application ID
+  config.application_id = ENV['LIGHTRATE_APPLICATION_ID']
+
+  # Optional: Enable/disable throttling globally (default: true)
+  config.enabled = Rails.env.production?
+  
+  # Optional: Default bucket size (default: 5)
+  config.default_local_bucket_size = 10
+end
+```
+
+**Note:** You must provide both a valid API key and Application ID. The gem will raise a `ConfigurationError` if either is missing.
+
+### Advanced Configuration
+
+```ruby
+LightrateRails.configure do |config|
+  # Required: Your LightRate API key
+  config.api_key = ENV['LIGHTRATE_API_KEY']
+  
+  # Required: Your LightRate Application ID
+  config.application_id = ENV['LIGHTRATE_APPLICATION_ID']
+  
+  # Enable/disable throttling globally (default: true)
+  config.enabled = true
+  
+  # Default local bucket size (default: 5)
+  config.default_local_bucket_size = 10
+  
+  # API client configuration
+  config.timeout = 30
+  config.retry_attempts = 3
+  config.logger = Rails.logger
+end
+```
+
+## Usage
+
+### Global Client Architecture
+
+The gem creates a single global LightRate client instance during Rails initialization. This approach provides several benefits:
+
+- **Efficiency**: No client creation overhead on each request
+- **Shared Token Buckets**: Token buckets are shared across all requests, providing better rate limiting
+- **Memory Efficiency**: Single client instance reduces memory usage
+- **Consistent State**: All parts of your application use the same client configuration
+
+### Controller-Level Throttling
+
+The gem automatically includes `LightrateRails::ControllerHelper` in all your controllers. To enable throttling, simply call `throttle_with_lightrate` in any controller:
+
+#### Basic Usage
+
+```ruby
+# Throttle all actions in this controller
+class ApiController < ApplicationController
+  throttle_with_lightrate
+end
+
+# Only throttle specific actions
+class UsersController < ApplicationController
+  throttle_with_lightrate only: [:create, :update, :destroy]
+  
+  def index; end    # NOT throttled
+  def show; end     # NOT throttled
+  def create; end   # Throttled
+  def update; end   # Throttled
+  def destroy; end  # Throttled
+end
+
+# Throttle all actions EXCEPT specific ones
+class PostsController < ApplicationController
+  throttle_with_lightrate except: [:index, :show]
+  
+  def index; end    # NOT throttled
+  def show; end     # NOT throttled
+  def create; end   # Throttled
+  def update; end   # Throttled
+  def destroy; end  # Throttled
+end
+
+# Disable throttling for this entire controller
+class HealthController < ApplicationController
+  skip_lightrate_throttling
+  
+  def status; end   # NOT throttled
+  def ping; end     # NOT throttled
+end
+```
+
+#### Custom User Identification
+
+By default, the gem uses `current_user.id` to identify users. You can customize this per-controller:
+
+```ruby
+# Use a different method on your user object
+class ApiController < ApplicationController
+  throttle_with_lightrate user_identifier: -> { current_user&.uuid }
+end
+
+# Use a symbol for a controller method
+class ApiController < ApplicationController
+  throttle_with_lightrate user_identifier: :get_api_user_id
+  
+  private
+  
+  def get_api_user_id
+    request.headers['X-API-User-ID']
+  end
+end
+
+# Combine multiple identifiers
+class ApiController < ApplicationController
+  throttle_with_lightrate user_identifier: -> {
+    "#{current_user&.id}:#{current_organization&.id}"
+  }
+end
+
+# Use API token for identification
+class ApiV2Controller < ApplicationController
+  throttle_with_lightrate user_identifier: -> { 
+    current_api_user&.token 
+  }
+end
+
+# Combine with :only option
+class ComplexController < ApplicationController
+  throttle_with_lightrate(
+    only: [:create, :update],
+    user_identifier: -> { request.headers['X-User-Token'] }
+  )
+end
+```
+
+### Manual Token Management in Controllers
+
+For advanced use cases, you can manually manage token consumption. The helper methods are automatically available in all controllers:
+
+```ruby
+class ApiController < ApplicationController
+  def expensive_operation
+    # Check if tokens are available for current path before proceeding
+    if lightrate_tokens_available?
+      # Your expensive operation here
+      perform_expensive_operation
+    else
+      render json: { error: 'Rate limit exceeded' }, status: 429
+    end
+  end
+  
+  def path_specific_operation
+    # Manually consume a token for a specific path
+    consume_lightrate_token_for_path(path: '/api/v1/special')
+    
+    # Your operation here
+  end
+  
+  def current_path_operation
+    # Consume a token for the current request path (most common use case)
+    consume_lightrate_token_for_current_path
+    
+    # Your operation here
+  end
+  
+  def conditional_operation
+    # Use the helper to conditionally execute code
+    if lightrate_tokens_available?
+      # Execute expensive operation
+      heavy_computation
+    else
+      # Fallback to lighter operation
+      light_computation
+    end
+  end
+  
+  def custom_user_operation
+    # Use a different user identifier
+    consume_lightrate_token_for_current_path(
+      user_identifier: current_user.uuid
+    )
+    
+    # Your operation here
+  end
+  
+  def specific_path_operation
+    # Consume token for a specific path and method
+    consume_lightrate_token_for_path(
+      path: "/api/v1/special-endpoint",
+      method: "POST",
+      user_identifier: current_user.id
+    )
+    
+    # Your operation here
+  end
+end
+```
+
+### Controller Configuration Methods
+
+Configure throttling behavior at the controller level:
+
+| Method | Description | Options |
+|--------|-------------|---------|
+| `throttle_with_lightrate(options = {})` | Enable throttling for this controller | `only:` - Array of action names to throttle<br>`except:` - Array of action names to exclude<br>`user_identifier:` - Proc or Symbol for custom user identification |
+| `skip_lightrate_throttling` | Disable throttling for this entire controller | None |
+
+### Available Helper Methods
+
+The gem provides several helper methods for manual token management. All methods share a single global LightRate client instance that is created during Rails initialization, ensuring efficient token bucket management across all requests.
+
+| Method | Description | Parameters |
+|--------|-------------|------------|
+| `lightrate_tokens_available?` | Check if tokens are available for current path | `user_identifier` |
+| `consume_lightrate_token_for_current_path` | Consume token for current request path | `user_identifier` |
+| `consume_lightrate_token_for_path` | Consume token for specific path | `path`, `method`, `user_identifier` |
+
+**Most Common Use Cases:**
+
+- **`lightrate_tokens_available?`** - Use this to check before expensive operations
+- **`consume_lightrate_token_for_current_path`** - Use this when you want to consume a token for the current request path
+- **`consume_lightrate_token_for_path`** - Use this for specific paths different from the current request
+
+### Exception Handling
+
+The gem automatically handles rate limiting through controller callbacks:
+
+- **HTML requests**: Redirects with flash message
+- **JSON requests**: Returns 429 status with JSON error
+- **XML requests**: Returns 429 status with XML error
+
+#### Customizing Throttling Responses
+
+You can customize the throttling response by overriding the `handle_rate_limit_exceeded` method in your controllers:
+
+```ruby
+class ApiController < ApplicationController
+  throttle_with_lightrate
+
+  private
+
+  def handle_rate_limit_exceeded(exception)
+    # Custom throttling response
+    render json: {
+      error: 'Rate Limited',
+      message: 'You have exceeded the rate limit for this endpoint.',
+      path: exception.path,
+      user: exception.user_identifier,
+      retry_after: 30
+    }, status: 429
+  end
+end
+```
+
+## Exception Classes
+
+### LightRateNoTokensAvailable
+
+Raised when no tokens are available for a request.
+
+```ruby
+begin
+  consume_lightrate_tokens(operation: 'my_operation')
+rescue LightrateRails::LightRateNoTokensAvailable => e
+  puts "No tokens available for path: #{e.path}"
+  puts "User: #{e.user_identifier}"
+  puts "Response: #{e.response}"
+end
+```
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `api_key` | String | `nil` | **Required** - Your LightRate API key |
+| `application_id` | String | `nil` | **Required** - Your LightRate Application ID |
+| `enabled` | Boolean | `true` | Enable/disable throttling globally |
+| `default_local_bucket_size` | Integer | `5` | Default size for local token buckets |
+| `timeout` | Integer | `30` | API request timeout in seconds |
+| `retry_attempts` | Integer | `3` | Number of API retry attempts |
+| `logger` | Logger | `Rails.logger` | Logger for API requests |
+
+**Note:** User identification is now configured per-controller using the `user_identifier` option in `throttle_with_lightrate`. See [Custom User Identification](#custom-user-identification) for details.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` 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/lightbourne-technologies/lightrate-rails. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/lightbourne-technologies/lightrate-rails/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Lightrate Rails project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/lightbourne-technologies/lightrate-rails/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/lightrate_rails/configuration.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module LightrateRails
+  class Configuration
+    attr_accessor :api_key, :application_id, :timeout, :retry_attempts, :logger, :default_local_bucket_size,
+                  :enabled
+
+    def initialize
+      @enabled = true
+      @timeout = 30
+      @retry_attempts = 3
+      @logger = nil
+      @default_local_bucket_size = 5
+    end
+
+    def valid?
+      api_key.present? && application_id.present?
+    end
+
+    def to_h
+      {
+        api_key: api_key.present? ? "******" : nil,
+        application_id: application_id,
+        enabled: enabled,
+        timeout: timeout,
+        retry_attempts: retry_attempts,
+        logger: logger,
+        default_local_bucket_size: default_local_bucket_size
+      }
+    end
+  end
+end

data/lib/lightrate_rails/controller_helper.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+module LightrateRails
+  module ControllerHelper
+    extend ActiveSupport::Concern
+
+    included do
+      rescue_from LightrateRails::LightRateNoTokensAvailable, with: :handle_rate_limit_exceeded
+      
+      # Class-level configuration for throttling
+      class_attribute :lightrate_throttled_actions, default: []
+      class_attribute :lightrate_throttle_only_specified, default: false
+      class_attribute :lightrate_user_identifier_method, default: nil
+      class_attribute :lightrate_enabled, default: false
+
+      # Main before_action that handles token consumption
+      before_action :consume_lightrate_token, if: :should_throttle_current_action?
+    end
+
+    class_methods do
+      # Enable throttling for this controller
+      # @param options [Hash] Configuration options
+      # @option options [Array<Symbol, String>] :only List of action names to throttle (optional)
+      # @option options [Array<Symbol, String>] :except List of action names to exclude from throttling (optional)
+      # @option options [Proc, Symbol] :user_identifier Custom method to get user identifier (optional)
+      #   Can be a Proc that receives the controller instance, or a Symbol for a controller method
+      # @example
+      #   throttle_with_lightrate only: [:create, :update]
+      #   throttle_with_lightrate user_identifier: -> { current_api_user.token }
+      #   throttle_with_lightrate user_identifier: :get_user_id
+      def throttle_with_lightrate(options = {})
+        self.lightrate_enabled = true
+        
+        if options.key?(:only)
+          self.lightrate_throttled_actions = Array(options[:only]).map(&:to_s)
+          self.lightrate_throttle_only_specified = true
+        elsif options.key?(:except)
+          # Store exceptions and handle in should_throttle_action?
+          self.lightrate_throttled_actions = Array(options[:except]).map(&:to_s)
+          self.lightrate_throttle_only_specified = :except
+        else
+          self.lightrate_throttled_actions = []
+          self.lightrate_throttle_only_specified = false
+        end
+
+        if options.key?(:user_identifier)
+          self.lightrate_user_identifier_method = options[:user_identifier]
+        end
+      end
+
+      # Disable throttling for this controller
+      def skip_lightrate_throttling
+        self.lightrate_enabled = false
+        self.lightrate_throttled_actions = []
+        self.lightrate_throttle_only_specified = true
+      end
+
+      # Check if the given action should be throttled
+      # @param action_name [String] The action name to check
+      # @return [Boolean] true if the action should be throttled
+      def should_throttle_action?(action_name)
+        return false unless lightrate_enabled
+        return false if lightrate_throttle_only_specified == true && lightrate_throttled_actions.empty?
+        return true if lightrate_throttled_actions.empty? && lightrate_throttle_only_specified == false
+        
+        if lightrate_throttle_only_specified == :except
+          # If using :except, throttle everything EXCEPT the listed actions
+          !lightrate_throttled_actions.include?(action_name.to_s)
+        else
+          # If using :only, throttle only the listed actions
+          lightrate_throttled_actions.include?(action_name.to_s)
+        end
+      end
+    end
+
+    # Check if tokens are available for the current request path
+    # Note: This method actually consumes a token to check availability
+    # @param user_identifier [String, nil] User identifier (defaults to current_user.id)
+    # @return [Boolean] true if tokens are available, false otherwise
+    def lightrate_tokens_available?(user_identifier: nil)
+      user_id = user_identifier || current_user&.id
+      return false unless user_id
+
+      begin
+        consume_lightrate_token_for_current_path(user_identifier: user_id)
+        true
+      rescue LightrateRails::LightRateNoTokensAvailable
+        false
+      end
+    end
+
+    # Consume a token for the current request path
+    # @param user_identifier [String, nil] User identifier (defaults to current_user.id)
+    # @return [LightrateClient::ConsumeLocalBucketTokenResponse] The response object
+    # @raise [LightrateRails::LightRateNoTokensAvailable] If no tokens are available
+    def consume_lightrate_token_for_current_path(user_identifier: nil)
+      user_id = user_identifier || current_user&.id
+      raise ArgumentError, "User identifier is required" unless user_id
+
+      response = lightrate_client.consume_local_bucket_token(
+        path: request.path,
+        http_method: request.request_method,
+        user_identifier: user_id
+      )
+
+      unless response.success
+        raise LightrateRails::LightRateNoTokensAvailable.new(request.path, user_id, response)
+      end
+
+      response
+    end
+
+    # Manually consume a token from the local bucket for a specific path
+    # @param path [String] The API path
+    # @param method [String] The HTTP method (defaults to current request method)
+    # @param user_identifier [String, nil] User identifier (defaults to current_user.id)
+    def consume_lightrate_token_for_path(path:, method: nil, user_identifier: nil)
+      user_id = user_identifier || current_user&.id
+      raise ArgumentError, "User identifier is required" unless user_id
+
+      http_method = method || request.request_method
+
+      response = lightrate_client.consume_local_bucket_token(
+        path: path,
+        http_method: http_method,
+        user_identifier: user_id
+      )
+
+      unless response.success
+        raise LightrateRails::LightRateNoTokensAvailable.new(path, user_id, response)
+      end
+
+      response
+    end
+
+    private
+
+    # Check if the current action should be throttled
+    # @return [Boolean]
+    def should_throttle_current_action?
+      return false unless LightrateRails.configuration.enabled
+      self.class.should_throttle_action?(action_name)
+    end
+
+    # Main before_action that consumes a token for the current request
+    # Raises LightRateNoTokensAvailable if no tokens are available, which is caught by rescue_from
+    def consume_lightrate_token
+      user_id = get_lightrate_user_identifier
+      
+      # Skip throttling if we can't identify the user
+      return if user_id.nil?
+
+      begin
+        response = lightrate_client.consume_local_bucket_token(
+          path: request.path,
+          http_method: request.request_method,
+          user_identifier: user_id
+        )
+
+        unless response.success
+          raise LightrateRails::LightRateNoTokensAvailable.new(request.path, user_id, response)
+        end
+      rescue LightrateClient::APIError => e
+        # Handle API errors - log and continue with request
+        Rails.logger.warn("LightRate API error: #{e.message}") if Rails.logger
+      rescue LightrateClient::ConfigurationError => e
+        # Handle configuration errors - log and continue with request
+        Rails.logger.error("LightRate configuration error: #{e.message}") if Rails.logger
+      end
+    end
+
+    # Get the user identifier for the current request
+    # Uses controller-level configuration if available, otherwise falls back to current_user.id
+    # @return [String, nil]
+    def get_lightrate_user_identifier
+      if self.class.lightrate_user_identifier_method
+        case self.class.lightrate_user_identifier_method
+        when Proc
+          instance_exec(&self.class.lightrate_user_identifier_method)
+        when Symbol
+          send(self.class.lightrate_user_identifier_method)
+        else
+          self.class.lightrate_user_identifier_method
+        end
+      elsif respond_to?(:current_user)
+        current_user&.id
+      else
+        'Anonymous'
+      end
+    rescue StandardError => e
+      Rails.logger.warn("Failed to get user identifier: #{e.message}") if Rails.logger
+      nil
+    end
+
+    def handle_rate_limit_exceeded(exception)
+      # Check if we're in an API controller (ActionController::API) or regular controller (ActionController::Base)
+      if self.class.ancestors.include?(ActionController::API)
+        # API controller - just render JSON
+        render json: {
+          error: 'Too Many Requests',
+          message: 'Rate limit exceeded. Please try again later.',
+        }, status: 429
+      else
+        # Regular controller - use respond_to
+        respond_to do |format|
+          format.html do
+            flash[:error] = "Rate limit exceeded. Please try again later."
+            redirect_back(fallback_location: root_path)
+          end
+          format.json do
+            render json: {
+              error: 'Too Many Requests',
+              message: 'Rate limit exceeded. Please try again later.',
+            }, status: 429
+          end
+          format.xml do
+            render xml: {
+              error: 'Too Many Requests',
+              message: 'Rate limit exceeded. Please try again later.',
+            }.to_xml(root: 'error'), status: 429
+          end
+        end
+      end
+    end
+
+    def lightrate_client
+      LightrateRails.client
+    end
+  end
+end

data/lib/lightrate_rails/engine.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module LightrateRails
+  class Engine < ::Rails::Engine
+    config.to_prepare do
+      # Include in ActionController::Base
+      if defined?(ActionController::Base)
+        ActionController::Base.include LightrateRails::ControllerHelper
+      end
+      
+      # Include in ActionController::API
+      if defined?(ActionController::API)
+        ActionController::API.include LightrateRails::ControllerHelper
+      end
+    end
+  end
+end

data/lib/lightrate_rails/errors.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module LightrateRails
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+
+  class LightRateNoTokensAvailable < Error
+    attr_reader :path, :user_identifier, :response
+
+    def initialize(path = nil, user_identifier = nil, response = nil)
+      @path = path
+      @user_identifier = user_identifier
+      @response = response
+      
+      message = "No tokens available for request"
+      message += " to #{path}" if path
+      message += " for user #{user_identifier}" if user_identifier
+      
+      super(message)
+    end
+  end
+end

data/lib/lightrate_rails/version.rb

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

data/lib/lightrate_rails.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "lightrate_client"
+require "lightrate_rails/version"
+require "lightrate_rails/engine"
+require "lightrate_rails/errors"
+require "lightrate_rails/configuration"
+require "lightrate_rails/controller_helper"
+
+module LightrateRails
+  class << self
+    def configure
+      yield(configuration)
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def client
+      @client ||= create_client
+    end
+
+    def create_client
+      raise ConfigurationError, "API key is required" unless configuration.api_key
+      raise ConfigurationError, "Application ID is required" unless configuration.application_id
+
+      @client = LightrateClient::Client.new(
+        configuration.api_key,
+        configuration.application_id,
+        {
+          timeout: configuration.timeout,
+          retry_attempts: configuration.retry_attempts,
+          logger: configuration.logger,
+          default_local_bucket_size: configuration.default_local_bucket_size
+        }
+      )
+    end
+
+    def reset!
+      @configuration = nil
+      @client = nil
+    end
+  end
+end

metadata

@@ -0,0 +1,211 @@
+--- !ruby/object:Gem::Specification
+name: lightrate-rails
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Lightbourne Technologies
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-10-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: lightrate-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+description: A Rails gem that provides seamless integration with Lightrate API throttling
+  using local token buckets and controller-level rate limiting.
+email:
+- grayden@lightbournetechnologies.ca
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- Gemfile.lock
+- README.md
+- Rakefile
+- lib/lightrate_rails.rb
+- lib/lightrate_rails/configuration.rb
+- lib/lightrate_rails/controller_helper.rb
+- lib/lightrate_rails/engine.rb
+- lib/lightrate_rails/errors.rb
+- lib/lightrate_rails/version.rb
+homepage: https://github.com/lightbourne-technologies/lightrate-client-rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/lightbourne-technologies/lightrate-client-rails
+  source_code_uri: https://github.com/lightbourne-technologies/lightrate-client-rails
+  changelog_uri: https://github.com/lightbourne-technologies/lightrate-client-rails/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.21
+signing_key:
+specification_version: 4
+summary: Ruby on Rails integration for Lightrate throttling
+test_files: []