Rebus.MatchRule (rebus v0.3.0)

A validated, canonical D-Bus signal match rule.

Construct rules with new/1, then pass them to Rebus.add_match/3. Rebus deliberately accepts structured criteria instead of raw rule strings, so every outbound rule is bounded, correctly quoted, and safe to use for client-side filtering when several subscriptions share a connection.

The generated rule always contains type='signal'. Supported criteria are :sender, :interface, :member, :path, :path_namespace, :destination, :args, :arg_paths, and :arg0namespace. :path and :path_namespace are mutually exclusive. :args and :arg_paths are maps or keyword lists keyed by indexes 0 through 63.

eavesdrop is not accepted, and sender matching is split between the bus and Rebus; see Signal subscriptions and match rules.

Summary

Types

criteria()

t()

validation_error()

Functions

matches?(rule, message)

Returns whether an inbound signal matches the criteria that Rebus can safely evaluate after the bus has routed it.

new(opts)

Builds a safe signal match rule.

new!(opts)

Builds a match rule, raising ArgumentError when it is invalid.

to_string(match_rule)

Returns the canonical D-Bus representation used for both AddMatch and RemoveMatch.

Types

criteria()

@type criteria() :: %{
  optional(:sender) => binary(),
  optional(:interface) => binary(),
  optional(:member) => binary(),
  optional(:path) => binary(),
  optional(:path_namespace) => binary(),
  optional(:destination) => binary(),
  optional(:args) => %{required(non_neg_integer()) => binary()},
  optional(:arg_paths) => %{required(non_neg_integer()) => binary()},
  optional(:arg0namespace) => binary()
}

t()

@type t() :: %Rebus.MatchRule{criteria: criteria(), string: binary()}

validation_error()

@type validation_error() ::
  :duplicate_match_option
  | :invalid_match_rule
  | :invalid_match_option
  | :invalid_match_value
  | :invalid_match_argument
  | :conflicting_match_paths
  | :match_rule_too_long

Functions

matches?(rule, message)

@spec matches?(t(), Rebus.Message.t()) :: boolean()

Returns whether an inbound signal matches the criteria that Rebus can safely evaluate after the bus has routed it.

Rebus compares unique-name :sender values, :interface, :member, :path, :path_namespace, :destination, :args, :arg_paths, and :arg0namespace. A well-known :sender is left to the bus for broadcast signals. A directed signal is accepted for a well-known :sender when the sender header is that exact name. Ownership-aware matching for subscribed signals is handled by the connection. This function does not emulate bus access policy or eavesdropping.

new(opts)

@spec new(keyword()) :: {:ok, t()} | {:error, validation_error()}

Builds a safe signal match rule.

The rule is limited to 1024 bytes, matching the reference D-Bus implementation's match-rule limit. Invalid input returns a stable atom and never includes caller-provided rule text.

Examples

iex> {:ok, rule} = Rebus.MatchRule.new(
...>   sender: "org.freedesktop.DBus",
...>   member: "NameOwnerChanged"
...> )
iex> Rebus.MatchRule.to_string(rule)
"type='signal',sender='org.freedesktop.DBus',member='NameOwnerChanged'"

new!(opts)

@spec new!(keyword()) :: t()

Builds a match rule, raising ArgumentError when it is invalid.

to_string(match_rule)

@spec to_string(t()) :: binary()

Returns the canonical D-Bus representation used for both AddMatch and RemoveMatch.