Broker Bridge Configuration Reference
The Broker Bridge subsystem runs a set of supervised, embedded WAMP subscribers that re-publish matching events to an external system — a message broker, an SMS gateway, or an email service — using the Mops expression language to map a WAMP event onto that system's own action shape. See Broker Bridge for the concepts behind the specification file and how a bridge module plugs into it.
Five bridges ship with Bondy: Kafka, AWS SNS (SMS), SMTP (email), Mailgun (email) and SendGrid (email). Each is enabled independently and can be mixed within the same specification file — one subscription might forward to Kafka while another sends an SMS, both driven by the same running bridge.
Use the SMTP bridge for email
SMTP is the supported path: it sends through a mail relay whose credentials, TLS settings and sender policy live in bondy.conf, on a bounded worker pool off the routing path. Mailgun and SendGrid predate it, configure the same underlying HTTP client through global application settings — so enabling both at once is mutually destructive — and support neither attachments nor custom headers.
Path to the Broker Bridge's JSON specification file, which declares the actual subscriptions and their per-bridge action mappings.
There is no default. When the key is unset, the Broker Bridge starts with no subscriptions. When the key names a file that does not exist, the Broker Bridge also starts with no subscriptions, and logs nothing about the missing file. A file that exists but does not parse stops the Broker Bridge.
Broker Bridge Specification Object
{
"id": "com.example.bridges",
"kind": "broker_bridge",
"version": "v1.0",
"meta": {},
"subscriptions": [
{
"bridge": "bondy_kafka_bridge",
"match": {
"realm": "com.example.realm",
"topic": "com.example.topic",
"options": {"match": "exact"}
},
"action": {
"type": "produce_sync",
"topic": "{{kafka.topics.wamp_events}}",
"key": "\"{{event.topic}}/{{event.publication_id}}\"",
"value": "{{event}}",
"options": {
"client_id": "default",
"acknowledge": true,
"required_acks": "all",
"partition": null,
"partitioner": {
"algorithm": "fnv32a",
"value": "\"{{event.topic}}/{{event.publication_id}}\""
},
"encoding": "json"
}
}
}
]
}Each entry in subscriptions names the target bridge module, a match selecting which realm/topic (with the usual exact/prefix/wildcard policy) triggers it, and an action — a Mops template evaluated against the event before being handed to that bridge's own action spec (see each bridge's section below for its action keys).
Kafka
Forwards WAMP events to Apache Kafka, and is by far the most configurable of the five — see the Kafka Bridge Configuration Reference for its clients, producer tuning, and topic mapping, and the Kafka Bridge Tutorial for a worked example.
Enables the Kafka bridge.
An action's options.encoding chooses how the record value is serialized: json, msgpack (with the text and bytes rule), erl (the Erlang External Term Format) or bert. With json, a value that is a string holding valid JSON text is sent unchanged. Any other value is encoded as JSON.
An action's options.client_id names the Kafka client that produces the record, one of the broker_bridge.kafka.clients.$name blocks. When the action omits client_id, or sets it to null, the bridge uses the first configured client. When no client is configured, the action fails validation with the reason no_kafka_client_configured.
An action's options.required_acks sets how many acknowledgements the Kafka broker collects before it answers:
"all"or-1: every in-sync replica."leader"or1: the partition leader only."none"or0: none, so the broker does not answer.
AWS SNS (SMS)
Sends SMS messages via AWS SNS (erlcloud_sns:publish_to_phone/2) — not general SNS pub/sub, specifically the SMS delivery path. An action needs only phone_number (E.164 format) and text_message.
Enables the AWS SNS bridge.
The AWS region SNS requests are sent to.
Overrides the SNS endpoint host, for a non-default AWS endpoint (e.g. a local test double).
The AWS credentials used to authenticate SNS requests.
SMTP
Sends email through a mail relay declared in bondy.conf. The action carries the message; the relay carries the credentials, the TLS settings, which realms may send, and which senders they may claim. Nothing secret appears in a specification file.
Delivery is asynchronous by construction. apply_action runs inside the subscriber that is delivering the event, so waiting there for an SMTP conversation would put a relay's latency directly on the router's event path — the bridge hands the message to a bounded worker pool and returns. A slow or dead relay fills its queue and starts refusing; publish and subscribe are untouched.
Enables the SMTP bridge.
Enable it on every node
A broker bridge subscriber handles only locally-published events. A node where this is off silently drops the events published to it, so an event's fate depends on which node its publisher happened to connect to.
There is nothing else to configure here: relays are declared under mail.*. See the Mail Configuration Reference.
Action
{
"bridge": "bondy_smtp_bridge",
"match": {
"realm": "com.example.realm",
"topic": "com.example.user.registered",
"options": {"match": "exact"}
},
"action": {
"realm": "{{event.realm}}",
"relay": "transactional",
"to": "{{event.kwargs.email}}",
"subject": "\"Welcome, {{event.kwargs.name}}\"",
"text": "\"Your account is ready.\"",
"html": "\"<h1>Welcome</h1><p>Your account is ready.</p>\"",
"headers": {},
"options": {}
}
}realm is required and decides which realm's authority the send is evaluated against — it has to be a realm that the named relay permits. Every other key is the mail request object: id, relay, from, to, cc, bcc, reply_to, subject, text, html, headers, attachments, priority and timeout. Unknown keys are rejected when the specification is loaded, not silently dropped.
A missing template variable sends nothing
Evaluating {{event.kwargs.email}} against an event that has no such key is a hard error, not an empty string. The action fails and no message is sent — a half-rendered email is worse than none.
Mailgun
Sends email via the Mailgun API (text/plain and/or text/html body content; no template support). An action needs email_address, sender, subject, and body.
Enables the Mailgun bridge.
The email library adapter used to talk to Mailgun. Leave at its default unless integrating a custom adapter.
The Mailgun sending domain.
The Mailgun API endpoint and key.
The default sender address, injected into the Mops evaluation context as {{email_sender}} for action templates that reference it.
SendGrid
Sends email via the SendGrid API. Supports both content-based (text/plain / text/html) and template-based (template_id + template_data) emails; a failed send retries up to 3 times with a 2-second backoff. An action needs email_address, sender, subject, and body.
Enables the SendGrid bridge.
The email library adapter used to talk to SendGrid. Leave at its default unless integrating a custom adapter.
The SendGrid API endpoint and key.
The default sender address, injected into the Mops evaluation context as {{email_sender}} for action templates that reference it.
See also
- Broker Bridge — the concepts behind subscriptions, actions, and the five bridge modules.
- Kafka Bridge Configuration Reference — Kafka's client, producer, and topic-mapping keys.
- Kafka Bridge Tutorial — a worked example forwarding WAMP events to Kafka.