Wildcard Subscription

Overview

A wildcard subscription lets one subscriber match a whole family of channels with a single call, instead of wiring up a separate subscribe_to_events for every sub-channel and touching code each time a new one appears. It's the natural fit for monitoring, logging, or fan-in aggregation across a channel hierarchy — for example, watching every regional order channel from one place.

KubeMQ matches wildcard tokens against the channel hierarchy server-side at delivery time. * matches exactly one dot-separated segment, and > matches one or more trailing segments, so an EventsSubscription.new(channel: 'ruby-events.wildcard.*') catches any single-segment suffix. Every delivered event still carries its exact channel, so the handler can tell which concrete sub-channel it came from even though the subscription itself only named a pattern.

Gotchas: * matches exactly one segment — it won't reach two levels deep, so orders.* misses orders.us.east; use > for that. Wildcards are only valid on Events subscriptions, not on send_event/publishes or on events-store, queues, or commands/queries. And an overly broad pattern like > at the root will quietly pull in every channel under that prefix, including ones you didn't intend to monitor.

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: 'wildcard-example')
  puts "Connected to #{address}"

  cancel = KubeMQ::CancellationToken.new

  sub = KubeMQ::PubSub::EventsSubscription.new(channel: 'ruby-events.wildcard.*')
  client.subscribe_to_events(sub, cancellation_token: cancel, on_error: ->(e) { puts "Error: #{e.message}" }) do |event|
    puts "Received on #{event.channel}: #{event.metadata}"
  end
  sleep 1

  %w[ruby-events.wildcard.a ruby-events.wildcard.b ruby-events.wildcard.c].each do |ch|
    msg = KubeMQ::PubSub::EventMessage.new(channel: ch, metadata: "hello from #{ch}", body: 'data')
    client.send_event(msg)
    puts "Sent to #{ch}"
  end

  sleep 2
rescue KubeMQ::Error => e
  puts "KubeMQ error: #{e.message}"
ensure
  cancel&.cancel
  client&.close
  puts 'Done'
end

How It Works

• Wildcard patterns (* and >) let a single subscription match multiple channels.
• * matches a single segment: ruby-events.wildcard.* matches ruby-events.wildcard.a but not ruby-events.wildcard.a.b.
• > matches one or more segments: ruby-events.> matches all channels starting with ruby-events..
• Wildcards are supported for events subscriptions only — not for events store, commands, or queries.
• Review timeouts, channel names, and client IDs before running against shared environments.

Related

• Pattern overview
• Ruby SDK Reference
• Basic Pub/Sub
• Consumer Group