lepus 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9eb1d12b4ce05f9c4e9070d7083b68417b7a41b7cdb2b1a99cad2931c9879fe
-  data.tar.gz: 1a6eafc5a47b48a228279e5ede1a06acfea053b04cf686e8984719633d60e66b
+  metadata.gz: 050afe09c334acbba0db8685b273d8746e494f767fc0ff2304b545445838acc5
+  data.tar.gz: 2a6f2c1a0059e94c444d027200adba9b6a371d9481620cf8bcac650e30e21158
 SHA512:
-  metadata.gz: 40432e83f566507da124995e9a60130e10dbf54cc499ad8d3a6598369c0b8d3d9b78ab28be9fa6ca82812951092e28baead30d15d8b83feb6eeed9c6a30ebe32
-  data.tar.gz: '08948dbc7e9a927e2d26787a81c1106c1afb392aed5373248c54a02909a96d8d21b7e9f8c42a90e3ac4bc6179bfe1e5cc0c77c483be7d4808293bc6c51259213'
+  metadata.gz: 6338054122b5480c8db2f79d4b594ffb49f61b05736699722878c41ebc6cd1f591c1eae0aa824ad81203f6ca25ad68751df9c55dceede2ea312e306bacc4a7cf
+  data.tar.gz: 52e8af27c44ba24ee602f8c4aaf4732f20b1f428b4f71c234a8f186c79b311cf467dbd3e15c9b5d3217a91d0acf03d4fe30cad0d337e5e74ea53a1a9338f5cbf

data/CHANGELOG.md

@@ -4,6 +4,31 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.3.0 - 2026-11-06
+* Added: brand mark and README logo
+* Changed: the web dashboard is redesigned around a live topology map (exchanges, queues, consumers, retry and error queues) with a message rate strip and tables for processes, queues and connections; it loads nothing from CDNs and sends a strict Content-Security-Policy
+* Added: `GET /api/topology`, `GET /api/overview` and `GET /api/meta` dashboard endpoints, plus `ManagementAPI#bindings`, `#consumers` and `#overview`
+* Added: consumer heartbeats report their `retry_queue` and `error_queue`
+* Added: the dashboard shows delayed messages: delay queues and `<exchange>.delayed` exchanges are recognised by Lepus' own naming and arguments, their messages are counted on the queue or exchange they are released to (map, headline, queues table) and `/api/topology` exposes `delay_ms`, `target`, `target_type`, `delayed`, `delays` and `releases_to`
+* Added: consumer heartbeats report the consumer's `delays` and how many messages it handed back with `delay!`, which no longer count as processed
+* Added: `/api/queues` includes each queue's state, flags, arguments, idle time, utilisation and backlog rates
+* Changed: `/api/exchanges` keeps the `<exchange>.delayed` exchanges of the consumers' exchanges
+* Added: `bin/web-demo` serves the dashboard on a simulated broker (`HEAVY=1` for a large one)
+* Removed: the dashboard's offline mode; its service worker now unregisters itself and clears its caches
+* Fixed: the management API client uses the percent-decoded vhost from `rabbitmq_url` instead of always `/`
+* Fixed: `Lepus::Primitive::String` no longer requires dry-inflector or ActiveSupport; it uses them only when the app has already loaded one
+* Fixed: the dashboard no longer serves arbitrary files from outside its assets directory
+* Fixed: the Rails mount example in `docs/web.md`
+* Added: `delay:` option on `Producer.publish` and `Lepus::Publisher#publish` (milliseconds, or anything responding to `in_milliseconds`) delivers messages later through per-delay TTL queues, without the delayed-message plugin
+* Added: `delay!(ms)` (aliased `delay`) consumer helper re-delivers the current message to the consumer's own queue after the delay and acks it, incrementing the `x-lepus-delayed-count` header
+* Added: `delay:` through the default exchange delivers to the queue named by `routing_key` later, e.g. `Lepus::Publisher.new("").publish(payload, routing_key: "jobs", delay: 5_000)` (also on `channel_publish`)
+* Added: `config.delay_queue_expires` (default 1 hour) sets how long unused delay queues are kept beyond their delay before RabbitMQ deletes them
+* Added: `delays:` option on producer and consumer `configure` restricts delays to a fixed set, raising `Lepus::Error` for any other value, to bound the number of delay queues
+* Added: info log the first time each process declares a delay queue
+* Added: `delay` key in the `publish.lepus` instrumentation payload
+* Added: `Lepus::Testing` records `delay` and `expiration` of fake messages, and `lepus_publish_message.with_delay(ms)` matcher
+* Fixed: `Consumers::Config#retry_queue_name` and `#error_queue_name` return nil instead of raising when the queue is not configured
+
 ## 0.2.2 - 2026-10-30
 * Added: `lepus start --except A,B` (and `Supervisor.new(except:)`) runs every consumer but the ones listed
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    lepus (0.2.2)
+    lepus (0.3.0)
       base64
       bunny
       concurrent-ruby
@@ -23,7 +23,7 @@ GEM
       logger (~> 1, >= 1.7)
       sorted_set (~> 1, >= 1.0.2)
     coderay (1.1.3)
-    concurrent-ruby (1.3.6)
+    concurrent-ruby (1.3.8)
     connection_pool (2.5.5)
     crack (1.0.0)
       bigdecimal
@@ -56,7 +56,7 @@ GEM
     rack-test (2.2.0)
       rack (>= 1.3)
     rainbow (3.1.1)
-    rbtree (0.4.6)
+    rbtree (0.4.7)
     redis (5.4.1)
       redis-client (>= 0.22.0)
     redis-client (0.27.0)

data/README.md

@@ -1,6 +1,11 @@
-# Lepus
+<h1 align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/brand/lockup-lepus-on-dark.svg">
+    <img alt="Lepus" src="docs/brand/lockup-lepus-on-light.svg" width="278">
+  </picture>
+</h1>
 
-![Lepus web dashboard](https://github.com/user-attachments/assets/a640fc43-2f53-4aa7-aede-f1464f3e6e03)
+![Lepus web dashboard](docs/images/lepus-web.png)
 
 Lepus is a lightweight but powerful Ruby library to help you to consume and produce messages to [RabbitMQ](https://www.rabbitmq.com/) using the [Bunny](https://github.com/ruby-amqp/bunny) gem. It's similar to the Sidekiq, Faktory, ActiveJob, SolidQueue, and other libraries, but using RabbitMQ as the message broker.
 
@@ -281,6 +286,73 @@ class MyProducer < Lepus::Producer
 end
 ```
 
+### Delayed messages
+
+Pass `delay:` (in milliseconds, or anything responding to `in_milliseconds` such as `5.minutes`) to deliver a message later. No RabbitMQ plugin is needed:
+
+```ruby
+OrderEventsProducer.publish({ order_id: 123 }, routing_key: "order.reminder", delay: 30_000)
+Lepus::Publisher.new("order_events").publish("ping", routing_key: "order.ping", delay: 5_000)
+```
+
+A consumer can also put the message it is processing back on its own queue for later with [`delay!`](#consumer-configuration).
+
+#### How it works
+
+Delays are built from regular RabbitMQ queues: a message waits in a queue nobody consumes until its `x-message-ttl` expires, then RabbitMQ dead-letters it to the real destination. These are real, durable queues that you will see in the management UI.
+
+```mermaid
+flowchart LR
+    P["publish(delay: 30_000)"] --> DX{{"order_events.delayed<br/>(headers exchange)"}}
+    DX -- "lepus-delay = 30000" --> DQ["order_events.delayed.30000<br/>(TTL 30s, no consumers)"]
+    DX -- "lepus-delay = 5000" --> DQ2["order_events.delayed.5000<br/>(TTL 5s, no consumers)"]
+    DQ -- "TTL expires:<br/>dead-letter" --> X{{"order_events"}}
+    DQ2 -- "TTL expires:<br/>dead-letter" --> X
+    X -- "original routing key" --> Q1["your consumer queues"]
+```
+
+```mermaid
+flowchart LR
+    C["consumer of reindex<br/>calls delay!(5_000)"] -- "ack + re-publish" --> DQ["reindex.delay.5000<br/>(TTL 5s, no consumers)"]
+    DQ -- "TTL expires:<br/>dead-letter" --> Q["reindex"]
+    Q --> C
+```
+
+- **One queue per distinct delay value, not per message.** A million messages delayed by 30 seconds share `order_events.delayed.30000`. The number of queues is (exchanges or consumer queues using delays) × (distinct delay values).
+- **Use a small set of fixed delays** such as 5s, 30s and 5min. Computed or random delays (`rand(1_000..60_000)`, `(run_at - Time.now) * 1000`, jitter in a backoff) create a new queue for nearly every message.
+- **Each delay value has its own TTL**, so a long delay never holds back a shorter one.
+- **Messages keep their routing key and headers** when they reach the target exchange, so existing bindings and consumers work unchanged.
+- **`delay!` re-delivers only to that consumer's queue**, not to other queues bound to the same exchange. It acks the current delivery and increments the `x-lepus-delayed-count` header. Nothing is delivered while the message waits, but if your code calls `delay!` on every attempt it repeats forever, so cap it with that header.
+
+#### Limiting the delay queues
+
+Delay queues belong to an exchange (producer delays) or a consumer queue (`delay!`), so the allowed delays are set there with `delays:`. Any other value raises `Lepus::Error` before anything is published, including in testing mode. Without `delays:`, any delay is accepted.
+
+```ruby
+class OrderEventsProducer < Lepus::Producer
+  configure(exchange: "order_events", delays: [5_000, 30_000])
+end
+
+class ReindexConsumer < Lepus::Consumer
+  configure(queue: "reindex", exchange: "stories", delays: [60_000, 300_000, 900_000])
+
+  def perform(message)
+    attempt = message.metadata.headers.to_h["x-lepus-delayed-count"].to_i
+    return delay!(self.class.config.delay_values[attempt]) if pending?(message) && attempt < 3
+
+    ack!
+  end
+end
+```
+
+`delay!` raising inside `perform` rejects the message like any other error. `Lepus::Publisher#publish(..., delay:)` has no allowlist; use a producer when you want one.
+
+Lepus also logs `[Lepus::Delay] Declared delay queue "order_events.delayed.30000" (3 in this process)` at info level the first time each process declares a delay queue, so a growing count is easy to spot.
+
+#### Cleanup
+
+Unused delay queues are deleted by RabbitMQ after the delay plus one hour (`x-expires`), together with any message still in them. Lepus re-declares a queue while it is in use, so pending messages never outlive it. Change the window with `config.delay_queue_expires = 600_000`, or set it to `nil` to keep the queues forever. Queue arguments can't change once a queue exists, so changing this later raises `Lepus::Error` for existing queues until they are deleted. See [Producers](docs/producers.md#delayed-messages) and [Consumers](docs/consumers.md#delaying-a-message) for details.
+
 ### Configuration > Consumer Worker
 
 You can configure the consumer process using the `worker` method. The default worker is named `:default`, but you can define more workers with different names for different consumers.
@@ -388,6 +460,24 @@ It may result in a infinite loop if the message is always rejected. To avoid thi
 
 Refer to the [Dead Letter Exchanges](https://www.rabbitmq.com/docs/dlx) documentation for more information about retry.
 
+A consumer can also put the current message back on its own queue for later with `delay!` (aliased `delay`). It acks the current delivery and increments the `x-lepus-delayed-count` header, so you can cap the attempts:
+
+```ruby
+class ReindexConsumer < Lepus::Consumer
+  configure(queue: "reindex", exchange: "stories", routing_key: "story.published")
+  use :json
+
+  def perform(message)
+    return delay!(5_000) if replica_behind? && message.metadata.headers.to_h["x-lepus-delayed-count"].to_i < 3
+
+    reindex(message.payload)
+    ack!
+  end
+end
+```
+
+The redelivery goes only to this consumer's queue (through `reindex.delay.5000`), not to other queues bound to the exchange. See [Consumers](docs/consumers.md#delaying-a-message) for details.
+
 ### Middlewares
 
 Consumers can use middlewares for recurring tasks like logging, error handling, parsing, and others. It comes with a few built-in middlewares:
@@ -596,7 +686,7 @@ plugin :lepus
 
 Lepus includes a built-in web dashboard that provides a real-time view of your message processing infrastructure. The dashboard allows you to monitor processes, queues, connections, and consumer performance.
 
-![Lepus web dashboard — overview of supervisors, workers, and recent activity](https://github.com/user-attachments/assets/a640fc43-2f53-4aa7-aede-f1464f3e6e03)
+![Lepus web dashboard: the topology map with messages flowing from exchanges through queues to consumers](docs/images/lepus-web.png)
 
 ### Starting the Web Dashboard
 
@@ -614,13 +704,18 @@ bundle exec lepus web --port 3000 --host 127.0.0.1
 
 ### Web Dashboard Features
 
-The Lepus web dashboard provides:
+The dashboard is one page that refreshes itself (every 5 seconds by default; the **Live** control in the top bar pauses it or picks 2, 5, 15 or 60 seconds, and polling also pauses while the tab is in the background):
+
+- **Topology map**: each exchange is a band of lines, one per bound queue, running exchange → queue → consumer → acknowledged. Amber tokens move at a pace that follows each segment's message rate, a hollow amber bar shows a backlog piling up at its queue, violet loops under a line are retries, a teal clock counts [delayed messages](#delayed-messages) waiting to be released and red bars count messages in error queues. Quiet queues fold into a "+N" row per exchange so large brokers stay readable.
+- **Headline**: messages flowing, queues backing up, retries, delayed messages and messages in error queues, in one sentence that doubles as the map's key.
+- **Message rates**: published, delivered, acknowledged and redelivered per second over the last 10 minutes or hour, with a table view.
+- **Processes**: supervisors, their workers (PID, memory, connections, heartbeat health) and each consumer's processed, rejected and errored counts, and how many messages it delayed (handed back with `delay!`).
+- **Queues**: a sortable, filterable table with ready, unacked, consumers, rates, retry and error queue sizes and what waits in delay queues.
+- **Connections**: the broker's client connections.
+
+The map and the queue table need the RabbitMQ Management API (see `management_api_url`); processes come from worker heartbeats. It follows the system light or dark theme, or you can pick one.
 
-- **Process Monitoring**: View all running supervisors and workers with their PIDs, memory usage, and heartbeat status
-- **Queue Management**: Monitor queue statistics including message counts, consumer connections, and memory usage
-- **Connection Tracking**: View active RabbitMQ connections and their states
-- **Consumer Performance**: Track processed, rejected, and errored messages per consumer
-- **Real-time Updates**: Dashboard automatically refreshes to show current system state
+To work on the UI without RabbitMQ, run `bin/web-demo` from a checkout (http://127.0.0.1:9393, `HEAVY=1` for a large simulated broker, `MOUNT=/lepus` to serve it under a sub-path).
 
 ### Integrating with Rails