kontiki-boomerang 0.3.0

Overview

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

The pipeline stays stable because 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

The demo stack polls USGS, normalizes quakes, and notifies a Telegram chat.

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. Start the demo:

make stack-up-demo

3. Target a chat — subscription excerpt (operator config):

# stack/subscription.yaml (excerpt)
app:
  subscriptions:
    ops:                 # audience → recipient_id
      earthquakes:       # rule id
        status: active
        subscription:
          rule:
            category: natural.earthquake
            event_type: earthquake
            criteria:
              all_of:
                - key: magnitude
                  operator: gte
                  value: 4.5
          endpoints:
            - telegram.alerts

# stack/notifiers/telegram.yaml (excerpt)
app:
  endpoints:
    alerts:
      chat_id: "YOUR_CHAT_ID"

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)