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 calling KubeMQ.Client.subscribe_to_events(client, "elixir-events.>", ...) catches everything under the prefix regardless of depth. Every delivered event still carries its exact channel, so the callback 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
• Elixir SDK installed ({:kubemq, "~> 1.0"} in mix.exs)

Code

{:ok, client} = KubeMQ.Client.start_link(address: "localhost:50000", client_id: "elixir-events-wildcard")
parent = self()
counter = :counters.new(1, [:atomics])

{:ok, sub} =
  KubeMQ.Client.subscribe_to_events(client, "elixir-events.>",
    on_event: fn event ->
      :counters.add(counter, 1, 1)
      IO.puts("Received on channel '#{event.channel}': #{event.body}")
      send(parent, :received)
    end
  )

IO.puts("Subscribed to 'elixir-events.>' (wildcard)")
Process.sleep(500)

for topic <- ["elixir-events.orders", "elixir-events.users", "elixir-events.logs"] do
  event = KubeMQ.Event.new(channel: topic, body: "Message to #{topic}")
  :ok = KubeMQ.Client.send_event(client, event)
  IO.puts("Sent to '#{topic}'")
end

for _ <- 1..3 do
  receive do
    :received -> :ok
  after
    5_000 -> IO.puts("Timeout waiting")
  end
end

IO.puts("Total received: #{:counters.get(counter, 1)}")
KubeMQ.Subscription.cancel(sub)
KubeMQ.Client.close(client)

How It Works

• The > wildcard matches any sub-channel under the prefix (e.g., elixir-events.> matches elixir-events.orders, elixir-events.users)
• :counters module provides a thread-safe counter across concurrent callback invocations
• Each event's channel field shows which specific sub-channel it arrived on

Related

• Basic Pub/Sub
• Consumer Group