kontiki-boomerang 1.0.0

Overview

Boomerang is an alerting engine built on Kontiki. Producers publish alerts; the core matches YAML subscriptions; notifiers deliver (email, Telegram, …).

1.0.0 freezes YAML targeting (app.subscriptions, notifier app.endpoints) and the bus contracts. Both ends speak shared contracts (boomerang-contracts):

Producers ──► NormalizedAlert ──► subscription + alert-engine ──► NotificationRequest ──► Notifiers

• Upstream: add a producer that emits NormalizedAlert (AMQP alert.normalized or POST /alerts) — no change to the engine.
• Downstream: add a notifier that consumes {channel}.alerting.notification.requested and exposes a channel catalogue — same targeting model.
• Middle: who gets notified is declared in YAML (app.subscriptions + notifier app.endpoints).

More detail: docs/features.md · docs/contracts.md · docs/configuration.md.

Install

Run the platform (CLI entrypoints):

pip install kontiki-boomerang
# boomerang-subscription, boomerang-alert-engine,
# boomerang-email-notifier, boomerang-telegram-notifier, …

Extend Boomerang (producers / notifiers — contracts only):

pip install boomerang-contracts

The quickstart below uses Docker Compose instead of a local pip install.

Quickstart — earthquake → Telegram / MailHog

The demo stack polls USGS, normalizes quakes, and notifies Telegram plus email (MailHog). Targeting lives in stack/subscription.demo.yaml (magnitude >= 2 → telegram.alerts and email.inbox).

1. Bot token (once):

cp stack/notifiers/telegram_bot_token.yaml.example \
   stack/notifiers/telegram_bot_token.yaml
# set app.telegram.bot_token from BotFather

2. Telegram chat in stack/notifiers/telegram.yaml:

app:
  endpoints:
    alerts:
      chat_id: "YOUR_CHAT_ID"

3. Start the demo:

make stack-up-demo

Email copies land in MailHog (http://127.0.0.1:8025). When a matching quake arrives, Telegram looks like this:

Stop the stack:

make stack-down

Details (pipeline, HTTP ingest, catalogues, contracts): docs/features.md.

Documentation

• Index: docs/README.md
• Features: docs/features.md
• Contracts: docs/contracts.md
• Configuration: docs/configuration.md · docs/boomerang-config.example.yaml
• Stack config: stack/
• Contributing: CONTRIBUTING.md
• License: LICENSE (Apache-2.0)