Ruby SDK

Ruby SDK for Toggly feature flag management. Works with or without Toggly.io.

Packages

Package	Description	RubyGems
toggly	Core SDK with zero dependencies	toggly
toggly-rails	Rails integration with Railtie	toggly-rails
toggly-cache	Redis caching support	toggly-cache

Requirements

• Ruby floor: 3.2 or later.
• Rails floor: 7.0 or later (for toggly-rails).
• Redis client floor: redis 4.0 or later (for toggly-cache). Connect it to a Redis server through REDIS_URL or your existing client configuration.

The maintained test set resolves Ruby 3.2.11, 3.3.12, 3.4.10, and 4.0.6. It resolves Rails 7.0.10, 7.1.6, 7.2.3.2, 8.0.5.1, and 8.1.3.1 with valid Ruby hosts. Packed-gem hosts verify Rails 7.0.10 with Redis 4.8.1 and Rails 8.1.3.1 with Redis 6.0.0; the cache fixture uses a Redis 8 server. Your application still needs a Ruby/Rails combination supported by Rails itself.

Quick Start

Installation

Add to your Gemfile:

Gemfile

# Core SDK only
gem 'toggly'

# With Rails integration
gem 'toggly-rails'

# With Redis caching
gem 'toggly-cache'

Then run:

bundle install

Basic Usage

require 'toggly'

# One definitions client per process. Without a key, these nonempty
# defaults select offline mode; with a key, startup fetches definitions.
client = Toggly::Client.new(
  app_key: ENV['TOGGLY_APP_KEY'],
  environment: 'Production',
  defaults: { 'ExpressCheckout' => false }
)
begin
  # Example values: in a web app use the authenticated user and an
  # Order that the user is authorized to access, before the first check.
  context = Toggly::Context.new(
    identity: 'user-123', groups: ['premium'],
    claims: { 'role' => 'customer' },
    request: Toggly::RequestContext.new(
      user_agent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)',
      accept_language: 'en-US,en;q=0.9', country: 'US'
    ),
    entity: Toggly::EntityContext.new(
      kind: 'Order', key: 'order-42',
      attributes: { 'Vip' => true, 'Total' => 149.95 }
    )
  )
  puts client.enabled?('ExpressCheckout', context: context)
ensure
  client.close # Scripts own cleanup; services close at process shutdown.
end

The constructor loads definitions for the app/environment. Request context is supplied later to each local evaluation; changing users or Orders does not fetch definitions again. See Quick Start for the first flag exercise.

Rails Integration

Generate the initializer:

rails generate toggly:install

Configure in config/initializers/toggly.rb:

Toggly::Rails.configure do |config|
  config.app_key = Rails.application.credentials.dig(:toggly, :app_key)
  config.environment = Rails.env.production? ? 'Production' : 'Staging'
  config.defaults = { 'ExpressCheckout' => false, 'new_dashboard' => false }
end

The Railtie installs controller/view helpers and closes the process client at exit. For targeted checks, configure the full request builder and attach the entity before the first controller check. These simple checks use the configured request context:

app/controllers/dashboard_controller.rb

class DashboardController < ApplicationController
  def show
    if feature_enabled?(:new_dashboard)
      render :new_dashboard
    else
      render :dashboard
    end
  end
end

app/views/layouts/application.html.erb

<%= feature(:promo_banner) do %>
  <div class="promo">Special Offer!</div>
<% end %>
<%= feature(:promo_banner, negate: true) do %>
  <div class="standard">Standard offer</div>
<% end %>

Features

• Zero Dependencies: Core SDK has no external dependencies
• Shared client: Reuse definitions across requests; pass a separate context for each user/entity
• Rails Integration: Railtie, controller concern, view helpers
• User Targeting: Target features by user identity, groups, or traits
• Percentage Rollouts: Gradual feature releases with consistent bucketing
• Offline Mode: Works without network using default values
• Redis Caching: Optional persistence with Redis
• Background Refresh: Automatic definition updates
• Live updates: Optional WebSocket streaming (websocket-client-simple)
• Signed definitions: Fetch from the signed definitions endpoint

Next Steps

• Installation Guide - Detailed installation instructions
• Quick Start - Get up and running quickly
• Configuration - All configuration options
• Signed definitions - Signed endpoint configuration
• Live updates - WebSocket real-time updates
• User Context - Targeting with user context
• Rails Integration - Deep dive into Rails features
• Caching - Redis and snapshot providers
• Testing - RSpec and Minitest helpers

Run the Ruby/Rack SDK sample to explore request-local context, Order evaluation, native filters, snapshots and process cleanup. Its local fixture mode works without a live Toggly application. Browse the Samples catalog for more application examples.

For a Rails application, run the Ruby Rails SDK sample to explore the native Railtie, controller and view helpers, request context and Order evaluation. Its local fixture demo runs without a live Toggly application.