Patterns & matching

You can subscribe to one channel (exact name) or to many channels with a pattern. Channel names use dot-separated tokens (e.g. a.b.c).

Token permissions vs subscription patterns

There are two matchers you should keep separate:

• Token rules (permissions): a restricted subset used in access tokens.
• Runtime subscription patterns: richer wildcards accepted when subscribing.

Token rules are intentionally limited to keep authorization non-ambiguous. In tokens, channel rules support only:

• exact channel: "a.b.c"
• prefix tree: "a.b.c.#" (base channel and any deeper channel under it)

Runtime subscriptions support additional wildcards (*, >, #, prefix*, prefix#, prefix>). See below.

Important rule: your runtime subscription must be a subset of what your token allows. If in doubt, keep token rules broad (roots like orders.#) and narrow down with runtime patterns.

See also:

• Client configuration
• Permissions model

Tenant

• Length: 1..128 bytes
• Allowed characters: a-z, A-Z, 0-9, _, -, ~, @, .
  • If the tenant is sent empty, it is set by default to ~, because the tenant cannot be absent.

Channel

• Length: 1..256 bytes
• Allowed characters: a-z, A-Z, 0-9, _, -, ~, @, ., and for subscription patterns also >, #, * (see Wildcard patterns).

Channel names usually use dot-separated tokens (example: a.b.c).

Wildcard patterns

Channel names are dot-separated tokens (e.g. a.b.c → tokens a, b, c). Subscription patterns use the same format with wildcards. Only the last token of a pattern may use tail wildcards (>, #, or prefix>, prefix#). In the middle of a pattern, only exact tokens, *, or prefix* are allowed.

Single-token matching

• Exact: abc — matches only the token abc.
• Any one token: * — matches exactly one token (any value).
• Prefix one token: prefix* — matches exactly one token if it starts with prefix (e.g. b* matches b or b1, but consumes only one token).

Tail wildcards (last token only)

• > (1+ levels, NATS-style): “one or more tokens after this”.
  Example: a.b.> matches a.b.x, a.b.x.y, but not a.b (at least one token after b is required).
• # (0+ levels, MQTT/RabbitMQ-style): “zero or more tokens after this”.
  Example: a.b.# matches a.b, a.b.x, a.b.x.y.

Prefix + tail (last token only)

• prefix>: current token must start with prefix, and there must be at least one more token after it.
  Example: a.b.c> matches a.b.c1.x, a.b.c99.x.y, but not a.b.c1 (no token after c1).
• prefix#: current token must start with prefix, then zero or more tokens.
  Example: a.b.c# matches a.b.c1, a.b.c1.x, a.b.c99.x.y.

Invalid patterns

• > or # in the middle: e.g. a.>.b, a.#.b — invalid.
• Tail in the middle: e.g. a.b.c>.x — invalid (tail must be the last token).
• * inside a token (other than the full token * or suffix prefix*) is not supported (e.g. a token like ab*c is invalid).