MQTT Topic validation, normalization, and wildcard matching.
Topic Format
Topics are /-separated strings. Wildcards are:
+- Single-level wildcard (matches exactly one level)#- Multi-level wildcard (matches zero or more levels, must be last)
Shared Subscriptions (MQTT 5.0)
Shared subscriptions use the format $share/group_name/topic_filter.
Messages are distributed among subscribers in a group using round-robin.
Examples
# Validation
iex> MqttX.Topic.validate("sensors/temperature")
{:ok, ["sensors", "temperature"]}
iex> MqttX.Topic.validate("sensors/+/humidity")
{:ok, ["sensors", :single_level, "humidity"]}
iex> MqttX.Topic.validate("sensors/#")
{:ok, ["sensors", :multi_level]}
# Matching
iex> MqttX.Topic.matches?(["sensors", :single_level, "temp"], ["sensors", "room1", "temp"])
true
iex> MqttX.Topic.matches?(["sensors", :multi_level], ["sensors", "room1", "temp"])
true
# Shared subscriptions
iex> MqttX.Topic.shared?("$share/group1/sensors/#")
true
iex> MqttX.Topic.parse_shared("$share/group1/sensors/#")
{:shared, "group1", "sensors/#"}
Summary
Functions
Flatten a normalized topic back to a binary string.
Match a topic filter against a concrete topic.
The most levels a topic or filter may have (128).
Normalize a topic to a list.
Parse a shared subscription filter.
Check if a topic filter is a shared subscription.
Check if a topic is valid.
Whether topic is a valid Topic Name (§4.7): not empty, at most 65 535
bytes and 128 levels, well-formed UTF-8 without U+0000,
and no + or #. The rule validate_publish/1 applies to a binary, in
one pass over its bytes and without building the levels — for a sender
that only needs to know.
Validate and normalize a topic filter.
Validate a topic for publishing (no wildcards allowed).
Check if a topic contains wildcards.
Types
Functions
@spec flatten(normalized_topic()) :: binary()
Flatten a normalized topic back to a binary string.
@spec matches?(normalized_topic(), normalized_topic()) :: boolean()
Match a topic filter against a concrete topic.
The filter can contain wildcards, the topic should not.
Examples
iex> MqttX.Topic.matches?(["sensors", :single_level, "temp"], ["sensors", "room1", "temp"])
true
iex> MqttX.Topic.matches?(["sensors", :multi_level], ["sensors", "room1", "temp"])
true
iex> MqttX.Topic.matches?(["sensors", "room1"], ["sensors", "room2"])
false
@spec max_levels() :: pos_integer()
The most levels a topic or filter may have (128).
@spec normalize(binary() | list()) :: normalized_topic()
Normalize a topic to a list.
Wildcards are converted to atoms :single_level (+) and :multi_level (#).
Check if a topic is valid.
Whether topic is a valid Topic Name (§4.7): not empty, at most 65 535
bytes and 128 levels, well-formed UTF-8 without U+0000,
and no + or #. The rule validate_publish/1 applies to a binary, in
one pass over its bytes and without building the levels — for a sender
that only needs to know.
@spec validate(binary() | list()) :: {:ok, normalized_topic()} | {:error, :invalid_topic}
Validate and normalize a topic filter.
Returns {:ok, normalized_topic} or {:error, :invalid_topic}.
A filter starting with $share/ is a Shared Subscription (MQTT 5.0
§4.8.2) and must have the shape $share/{ShareName}/{filter}: the
ShareName is at least one character and contains none of /, +, #,
and the Topic Filter after it is non-empty. Anything else that starts with
$share/ ("$share//t", "$share/g", "$share/g/", "$share/+/t") is
rejected rather than installed as a literal subscription.
@spec validate_publish(binary() | list()) :: {:ok, normalized_topic()} | {:error, :invalid_topic}
Validate a topic for publishing (no wildcards allowed).
Returns {:ok, normalized_topic} or {:error, :invalid_topic}.
This validates a Topic Name: the $share/ structure rules of
validate/1 apply to filters only, so a PUBLISH to a topic literally
named $share/g/t is just a topic name.
@spec wildcard?(normalized_topic()) :: boolean()
Check if a topic contains wildcards.