Skip to content
jaque

Adapters

This page covers the four delivery adapters, how delivery is made durable and idempotent, and where it can run on a different process from the one that decides to notify.

The four adapters

Section titled “The four adapters”

Email, webhook, command, and Telegram — matching the four contact types.

Delivery is durable, not fire-and-forget

Section titled “Delivery is durable, not fire-and-forget”

Every notification decision is NotificationRequested in the event log first; NotificationSent or NotificationFailed follows once delivery is attempted. Whoever is delivering folds the log to reconstruct exactly which requested notifications are still open — idempotent by notification ID, so a redelivery after a crash never double-sends a notification that already landed and never loses one that’s still owed. Delivery is at least once: if ownership moves mid-flight (see below), a retry might repeat a send that was already in progress, but it will never skip one.

Where delivery runs: -notify-delivery

Section titled “Where delivery runs: -notify-delivery”

The engine that owns an object always decides whether to notify and writes that decision to the log — that part never changes. Who actually delivers is a separate switch:

  • embedded (the default) — the same process (-target all or -target engine) that decided also delivers.
  • external — delivery happens in one or more -target notifier processes instead, each pulling their share of open notifications from the log (see Cluster and coordination for how the work splits across several).

A slow receiver only blocks the log follower of whoever is delivering — its delivery shard’s queue fills, jaque_notifier_blocked_total counts it, jaque_eventlog_consumer_lag{follower="notifier"} grows — nothing is ever dropped for being slow. -notify-workers (default 4) and -notify-queue (default 64) size the delivery shards and the per-shard buffer, for whichever process is currently delivering.

SMTP

Section titled “SMTP”
-smtp-host, -smtp-port (default 25), -smtp-user, -smtp-pass, -smtp-from

Leave -smtp-host empty and email contacts fall back to the system mail binary instead of talking SMTP directly — useful for a host that already has local mail delivery configured and nothing else.

Telegram

Section titled “Telegram”

A telegram contact carries only chat_id — the bot token is not per-contact config, it’s a process secret: one bot per jaque instance, set once via -telegram-token or JAQUE_TELEGRAM_TOKEN, the same posture as SMTP credentials.

To set one up: talk to @BotFather on Telegram, /newbot, and keep the token it hands back. To find a chat_id: message the bot (or add it to a group), then read https://api.telegram.org/bot<token>/getUpdates — the chat.id on the message you sent is the value that goes in the contact’s chat_id.