Reconnection

Overview

Production connections drop for reasons that have nothing to do with your application code: the broker restarts during a rolling upgrade, a load balancer fails over, a network blip severs the connection. Without built-in reconnection, every client in your fleet needs its own hand-rolled retry-connect loop, and it's easy to get the backoff wrong — too aggressive and you hammer a recovering broker, too slow and you leave the application dark longer than necessary. Automatic reconnection moves that logic into the client itself, so the connection self-heals without any code the application has to write or maintain.

It works by passing a KubeMQ::ReconnectPolicy to the client — base_interval, max_delay, and max_attempts shape the backoff curve, with a default of 1–30 second delays, a 2x multiplier, and 25% jitter to avoid a thundering herd when many clients reconnect at once. Once reconnected, subscriptions automatically resume from their last received position, so no manual re-subscribe logic is needed. Gotchas: the default policy retries unlimited attempts, so a broker that's gone for good will be retried forever unless you set max_attempts explicitly; in-flight send_event calls made during the outage window still raise immediately — the policy governs the connection, not individual sends; and jitter means retry timing isn't perfectly predictable, which is intentional but can complicate log correlation across a fleet of reconnecting clients.

Prerequisites

• KubeMQ server running on localhost:50000
• Ruby SDK installed (gem install kubemq)

Code

require 'kubemq'

address = ENV.fetch('KUBEMQ_ADDRESS', 'localhost:50000')

begin
  client = KubeMQ::PubSubClient.new(
    address: address,
    client_id: 'reconnect-example',
    reconnect_policy: KubeMQ::ReconnectPolicy.new(base_interval: 2.0)
  )
  puts "Connected to #{address}"

  info = client.ping
  puts "Ping OK: host=#{info.host}, version=#{info.version}"

  channel = 'ruby-error-handling.reconnection'
  3.times do |i|
    msg = KubeMQ::PubSub::EventMessage.new(channel: channel, metadata: "heartbeat-#{i}", body: "data-#{i}")
    client.send_event(msg)
    puts "Sent heartbeat #{i}"
    sleep 1
  end
rescue KubeMQ::Error => e
  puts "KubeMQ error: #{e.message}"
ensure
  client&.close
  puts 'Done'
end

How It Works

• The SDK's ReconnectPolicy automatically reconnects with exponential backoff and jitter.
• Default settings: 1–30 second backoff, 2x multiplier, 25% jitter, unlimited attempts.
• Subscriptions auto-resume from the last received position after reconnection.
• Customize via KubeMQ::ReconnectPolicy.new(base_interval:, max_delay:, max_attempts:).
• Review timeouts, channel names, and client IDs before running against shared environments.

Related

• Ruby SDK Reference
• Custom Timeouts
• Connection Error