topic_match.hpp

Go to the documentation of this file.

/*
 _____             _        __  __       _       _
|_   _|__  _ __   (_) ___  |  \/  | __ _ | |_ ___| |__
  | |/ _ \| '_ \  | |/ __| | |\/| |/ _` || __/ __| '_ \
  | | (_) | |_) | | | (__  | |  | | (_| || || (__| | | |
  |_|\___/| .__/  |_|\___| |_|  |_|\__,_| \__\___|_| |_|
          |_|
 
Pure MQTT-style topic wildcard matching. No dependency on Agent or ZMQ, so it
is directly unit-testable and reusable outside the subscribe path.
 
Grammar (mirrors MQTT):
  - '+' matches exactly one topic level.
  - '#' matches this level and everything below it, INCLUDING the level it
    replaces -- e.g. pattern "sensors/#" also matches the bare topic
    "sensors", not just "sensors/x" and deeper. Legal only as the final
    token of a pattern; a pattern where '#' appears anywhere but last is
    invalid, and topic_match() always returns false for it (never matches,
    rather than throwing -- callers get "no delivery" instead of a crash on
    a malformed sub_topic string).
  - Any other token matches its topic-level counterpart literally.
  - A pattern containing neither '+' nor '#' is an exact-match literal: it
    must equal the topic character-for-character. (Byte-prefix matching is a
    property of the raw ZeroMQ SUBSCRIBE frame, not of this function --
    literal sub_topic entries keep using that path untouched; see
    Agent::connect_sub().)
 
Topic levels are separated by '/'. Only a token that is *exactly* "+" or "#"
is treated as a wildcard; a token that merely contains one of those
characters (e.g. "a+b") is matched literally, mirroring strict MQTT grammar.
 
topic_match() alone is NOT the whole delivery rule a MADS agent applies: a
literal (wildcard-free) sub_topic entry never reaches topic_match() at
runtime, it is handed to ZeroMQ as-is and matched by byte prefix. Use
subscription_match() below whenever the question is "would this agent
actually receive this message?" -- it is the single definition both
Agent::_topic_matches_subscription() and `mads doctor --graph` are built on,
so the wire and the topology graph can never drift apart.
 
Author(s): Paolo Bosetti
*/
 
#pragma once
 
#include <string>
#include <string_view>
 
namespace Mads {
 
bool topic_match(std::string_view pattern, std::string_view topic);
 
bool has_wildcard(std::string_view sub_entry);
 
enum class SubMatch {
  None,     
  Exact,    
  Prefix,   
  Wildcard, 
};
 
SubMatch subscription_match(std::string_view sub_entry, std::string_view topic);
 
inline bool subscription_matches(std::string_view sub_entry,
                                 std::string_view topic) {
  return subscription_match(sub_entry, topic) != SubMatch::None;
}
 
std::string literal_prefix(std::string_view pattern);
 
} // namespace Mads