Shunt

A high-performance, rule-based message router for NATS JetStream with an integrated HTTP gateway and automated token management.

Rules are stored in NATS KV and hot-reloaded via KV Watch — no restarts required.

Features

• High Performance: Microsecond rule evaluation, asynchronous processing, thousands of messages per second.
• KV-Based Rules: Rules stored in NATS KV, hot-reloaded via Watch. Manage with shunt kv push/pull/list/delete.
• Array Processing: Batch message processing with array operators (any, all, none) and forEach iteration.
• Primitive Message Support: Handle strings, numbers, arrays, and objects at the root.
• HTTP Gateway (optional subsystem): Bidirectional HTTP-to-NATS bridge with inbound webhook ingestion and outbound API calls.
• Auth Manager (optional subsystem): OAuth2 and custom-HTTP token management, stored in NATS KV.
• NATS JetStream Native: Pull consumers for durable, scalable message processing. Per-rule publish mode override (core or jetstream) for mixed delivery guarantees.
• Debounce: Per-rule suppression of rapid re-fires within a configurable time window.
• Rule Engine: Dynamic conditions, payload/header/subject templating, KV data enrichment with local cache, time-based logic.
• Cryptographic Security: NKey signature verification for message integrity.
• Production Ready: Structured logging, Prometheus metrics, graceful shutdown, full NATS auth support.

Architecture

Single binary with subcommands:

• shunt serve — Start the routing server. Runs NATS-to-NATS message routing with optional subsystems:
  • Gateway (gateway.enabled: true): Bidirectional HTTP-to-NATS bridge for webhooks and outbound API calls.
  • Auth Manager (authManager.enabled: true): Manages OAuth2/custom-HTTP tokens in NATS KV.
• shunt kv push / pull / list / delete — Manage rules in NATS KV.
• shunt lint / test / check — Validate rules offline.
• shunt new / scaffold — Generate rule templates.

What's here

• Core Concepts

  The shared rule syntax — triggers, conditions, and actions.

• System Variables

  Built-in variables available in templating and conditions.

• Array Processing

  Operators (any, all, none) and forEach iteration.

• Primitive Messages

  Strings, numbers, arrays, and objects at the root.

• Security

  NKey signature verification and message integrity.

• Deployment

  Production deployment patterns and rule management via Git.

• Configuration

  All configuration options.

• KV Enrichment

  Enrich messages with data from NATS KV with local caching.

• Local Testing Tutorial

  Step-by-step walkthrough for local development.

Source

Shunt is open source under the Apache 2 License — see the GitHub repository.

Inspiration

This should be considered a re-imagining of rule-router for my use. rule-router is a mature, well architected project please go star it!