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 subscribeToEvents 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 setting channel = "orders.>" in subscribeToEvents catches everything under the prefix regardless of depth. Every delivered event still carries its exact channel, so the collector 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 publishEvent/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
• Kotlin SDK installed (implementation("io.kubemq.sdk:kubemq-sdk-kotlin:1.0.1"))

Code

package io.kubemq.sdk.examples.events

import io.kubemq.sdk.client.KubeMQClient
import io.kubemq.sdk.pubsub.eventMessage
import kotlinx.coroutines.delay
import kotlinx.coroutines.flow.take
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking

private const val ADDRESS = "localhost:50000"
private const val CLIENT_ID = "kotlin-events-wildcard-subscription"

fun main() = runBlocking {
    val client = KubeMQClient.pubSub {
        address = ADDRESS
        clientId = CLIENT_ID
    }

    client.use {
        // Subscribe with '>' wildcard -- receives from all "orders.*" channels
        val wildcardJob = launch {
            client.subscribeToEvents {
                channel = "orders.>"
            }.take(3).collect { msg ->
                println("[wildcard >] ${msg.channel}: ${String(msg.body)}")
            }
        }

        delay(500)

        // Publish to specific channels
        client.publishEvent(eventMessage {
            channel = "orders.created"
            body = "Order 1001 created".toByteArray()
        })
        client.publishEvent(eventMessage {
            channel = "orders.shipped"
            body = "Order 1002 shipped".toByteArray()
        })
        client.publishEvent(eventMessage {
            channel = "orders.delivered"
            body = "Order 1003 delivered".toByteArray()
        })

        wildcardJob.join()
        println("Done.")
    }
}

How It Works

• The > wildcard matches all sub-channels under a prefix (e.g., orders.> matches orders.created, orders.shipped, etc.).
• The msg.channel field on received events shows the actual channel the event was published to.
• Wildcard subscriptions work with events only; the SDK rejects wildcards on all events-store operations.
• This pattern is useful for monitoring, logging, or aggregating events across related channels.

Related

• Basic Pub/Sub
• Consumer Group
• Events Reference