Live updates (WebSockets)

The Ruby SDK can listen for real-time updates so new definitions are applied quickly.

Enable

enable_live_updates defaults to true. Set it to false when you want HTTP polling only. Configure once at startup and close at process shutdown:

client = Toggly::Client.new(
  app_key: ENV['TOGGLY_APP_KEY'],
  defaults: { 'ExpressCheckout' => false },
  environment: 'Production',
  enable_live_updates: true
)

Live updates require the optional gem:

Gemfile

gem 'websocket-client-simple', '~> 0.8'

disable_background_refresh: true (or a nonpositive refresh interval) prevents both polling and WebSocket startup. The constructor still performs the initial definitions fetch unless in offline mode.

Without that gem, the SDK logs that live updates are unavailable and continues with background HTTP refresh.

How it works

The SDK connects to the definitions worker:

wss://{baseURL}/{appKey}/ws?sdk=ruby&sdkVersion={semver}&rev={cachedEtag}

rev is sent when a cached definitions ETag is available. Update messages:

Message	SDK action
flags-updated	Refresh definitions
update	Refresh definitions (legacy plain-text or JSON)
ping	Ignored

While the WebSocket is connected, periodic HTTP refresh is skipped unless the fallback interval (~20 minutes) elapses. Live updates accelerate freshness; the background refresh loop still provides eventual consistency when the socket is down.

See WebSocket sync (client-side) for the full protocol shared across SDKs.

Rails note

The adapter uses the core live-update default. It has no enable_live_updates or telemetry setters. To set core-only options, use this alternative single initializer instead of calling Toggly::Rails.configure and then reconfiguring:

config/initializers/toggly.rb

rails_config = Toggly::Rails::Configuration.new
rails_config.app_key = Rails.application.credentials.dig(:toggly, :app_key)
rails_config.environment = Rails.env.production? ? 'Production' : 'Staging'
rails_config.defaults = { 'ExpressCheckout' => false }
# Add request-builder/cache settings to rails_config here before applying it.
core_config = Toggly::Config.new
rails_config.apply_to(core_config)
core_config.enable_live_updates = false # Keep HTTP polling.
core_config.enable_usage_tracking = true
core_config.enable_metrics = true

# Establish adapter configuration so the Railtie does not auto-configure
# another client. Its middleware/helpers and at-exit close still apply.
Toggly::Rails.configuration = rails_config
Toggly.client = Toggly::Client.new(core_config)

For complete request filters, assign the context builder to rails_config.context_builder before apply_to. Telemetry requires the optional transports described in Configuration. Do not close the client after an individual request; the Railtie owns process cleanup.