Ruby

A Ruby gem for interacting with the Lightrate token management API, providing easy-to-use methods for consuming tokens with local token bucket support for improved performance.

Installation

Add this line to your application’s Gemfile:


gem 'lightrate-client'

And then execute:


bundle install

Or install it yourself as:


gem install lightrate-client

Configuration

Configure the client with your API credentials:


require 'lightrate_client'
 
LightrateClient.configure do |config|
  config.api_key = 'your_api_key'
  config.application_id = 'your_application_id' # required
  config.timeout = 30 # optional, defaults to 30 seconds
  config.retry_attempts = 3 # optional, defaults to 3
  config.logger = Logger.new(STDOUT) # optional, for request logging
end

Basic Usage


# Simple usage - pass your API key and application ID
client = LightrateClient::Client.new('your_api_key', 'your_application_id')
 
# Or use the convenience method
client = LightrateClient.new_client('your_api_key', 'your_application_id')
 
# With additional options
client = LightrateClient::Client.new('your_api_key', 'your_application_id',
  timeout: 60
)
 
# Or configure globally and use the default client
LightrateClient.configure do |config|
  config.api_key = 'your_api_key'
  config.application_id = 'your_application_id'
end
client = LightrateClient.client

Consuming Tokens

Basic Token Consumption (Local Bucket)

The Ruby client uses local token buckets for efficient rate limiting. Local buckets automatically refill from the server when needed.


# Consume tokens by operation (uses local token bucket)
response = client.consume_local_bucket_token(
  operation: 'send_email',
  user_identifier: 'user123'
)
 
# Or consume tokens by path
response = client.consume_local_bucket_token(
  path: '/api/v1/emails/send',
  http_method: 'POST',
  user_identifier: 'user123'
)
 
if response.success
  puts "Token consumed from #{response.used_local_token ? 'local bucket' : 'server'}"
else
  puts "Rate limited: No tokens available"
end

Direct HTTP API Usage

For advanced use cases where you need to bypass the local bucket and call the HTTP API directly:


# Direct API call (bypasses local bucket)
response = client.consume_tokens(
  operation: 'send_email',
  user_identifier: 'user123',
  tokens_requested: 1
)
 
if response.tokens_consumed > 0
  puts "Consumed #{response.tokens_consumed} tokens. Remaining: #{response.remaining_tokens}"
else
  puts "Rate limited: No tokens available"
end

Complete Example


require 'lightrate_client'
 
# Create a client with your API key and application ID
client = LightrateClient::Client.new('your_api_key', 'your_application_id')
 
begin
  # Consume tokens using local bucket
  response = client.consume_local_bucket_token(
    operation: 'send_email',
    user_identifier: 'user123'
  )
 
  if response.success
    puts "Token consumed from #{response.used_local_token ? 'local bucket' : 'server'}"
    # Proceed with your operation
    send_email_to_user('user123')
  else
    puts "Rate limit exceeded. Please try again later."
    # Handle rate limiting
  end
 
rescue LightrateClient::UnauthorizedError => e
  puts "Authentication failed: #{e.message}"
rescue LightrateClient::TooManyRequestsError => e
  puts "Rate limited: #{e.message}"
rescue LightrateClient::APIError => e
  puts "API Error (#{e.status_code}): #{e.message}"
rescue LightrateClient::NetworkError => e
  puts "Network error: #{e.message}"
end

Error Handling

The gem provides comprehensive error handling with specific exception types:


begin
  client.consume_tokens(...)
rescue LightrateClient::UnauthorizedError => e
  puts "Authentication failed: #{e.message}"
rescue LightrateClient::NotFoundError => e
  puts "Resource not found: #{e.message}"
rescue LightrateClient::APIError => e
  puts "API Error (#{e.status_code}): #{e.message}"
rescue LightrateClient::NetworkError => e
  puts "Network error: #{e.message}"
rescue LightrateClient::TimeoutError => e
  puts "Request timed out: #{e.message}"
end

Available Exception Types

LightrateClient::UnauthorizedError - Authentication failures (401)
LightrateClient::NotFoundError - Resource not found (404)
LightrateClient::TooManyRequestsError - Rate limit exceeded (429)
LightrateClient::APIError - General API errors
LightrateClient::NetworkError - Network-related errors
LightrateClient::TimeoutError - Request timeout errors