cosmonats 0.2.0 → 0.4.0

data/README.md

@@ -1,12 +1,65 @@
-# 🚀 Cosmonats - lightweight background and stream processing
+# 🚀 Cosmonats
 
-It is a Ruby background job and stream processing framework powered by NATS JetStream.
-It provides a familiar API for job queues while adding powerful stream processing capabilities,
-solving the scalability limitations of Redis and database-backed queues through true horizontal scaling and
-disk-backed persistence.
+Background jobs + real-time event streaming for Ruby — unified, in one gem, backed by NATS.  
+**No Redis. No DB polling. Disk-backed, horizontally scalable — no message is ever silently dropped.**
+
+<div align="center">
 
 ![logo.svg](logo.svg)
 
+[![Gem Version](https://badge.fury.io/rb/cosmonats.svg)](https://rubygems.org/gems/cosmonats)
+[![Downloads](https://img.shields.io/gem/dt/cosmonats.svg)](https://rubygems.org/gems/cosmonats)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.1-red)](https://www.ruby-lang.org)
+[![License: LGPL v3](https://img.shields.io/badge/License-LGPL%20v3-blue.svg)](LICENSE.txt)
+[![Build Status](https://github.com/bitsbeam/cosmonats/actions/workflows/ci.yml/badge.svg)](https://github.com/bitsbeam/cosmonats/actions)
+
+*Battle-tested in production. Tens of millions of jobs processed and counting.*
+
+</div>
+
+
+## ⚡ Taste it
+
+```ruby
+# Define a job with a familiar look
+class SendEmailJob
+  include Cosmo::Job
+  options stream: :default, retry: 3, dead: true
+
+  def perform(user_id, template)
+    EmailService.send(user_id, template)
+  end
+end
+
+# Enqueue it
+SendEmailJob.perform_async(123, "welcome")
+SendEmailJob.perform_in(1.day, 123, "followup")
+```
+
+```ruby
+# Process a continuous real-time event stream
+class ClicksProcessor
+  include Cosmo::Stream
+  options stream: :clickstream, batch_size: 100,
+          consumer: { subjects: ["events.clicks.>"] }
+
+  def process_one
+    Analytics.track(message.data)
+    message.ack
+  end
+end
+
+ClicksProcessor.publish({ user_id: 123, page: "/home" }, subject: "events.clicks.homepage")
+```
+
+```bash
+bundle exec cosmo -C config/cosmo.yml -c 20         # Run jobs + streams with 20 threads
+bundle exec cosmo -C config/cosmo.yml -c 20 jobs    # Jobs only
+bundle exec cosmo -C config/cosmo.yml -c 20 streams # Streams only
+```
+
+![webui.gif](webui.gif)
+
 ## 📖 Index
 
 - [Why?](#-why)
@@ -25,65 +78,73 @@ disk-backed persistence.
 
 
 ## 🎯 Why?
-Among many others, why creating another? Cosmonats is a background processing framework for Ruby, powered by **[NATS](https://nats.io/)**.
-It's designed to solve the fundamental scaling problems that plague Redis/DB-based job queues and at the same time to provide both job and stream
-processing capabilities.
 
-### The Problem with Redis at Scale
+Most background job libraries use Redis or Postgres — tools that were never designed for this. Think of NATS as Redis — but Redis is KV first then messaging;
+NATS is messaging first, then KV. What NATS is:
+
+- **~20 MB binary, ~10 MB RAM at idle** Trivial to run anywhere.
+- **Disk-backed persistent streams** Messages survive restarts, don't require RAM to fit.
+- **True horizontal clustering** Lose a node — other nodes take over, zero message loss.
+- **Multilingual** Official clients for Ruby, Go, Python, Rust, Java, .NET, and more. Any service can publish or consume.
+
+One NATS server replaces your message broker, job queue, and KV store — with lower operational overhead.
+
+|                   | Redis/DB-backed               | NATS/Cosmonats             |
+|-------------------|-------------------------------|----------------------------|
+| Persistence       | In-memory / DB bloat          | Disk-backed, TB-scale      |
+| Scaling           | Sentinel only / Vertical only | True horizontal clustering |
+| Background jobs   | Yes                           | Yes                        |
+| Real-time stream  | No                            | Yes                        |
+| Zero message loss | No                            | Yes                        |
+| Message replay    | No                            | Yes                        |
+| Backpressure      | No, grow unbounded            | Yes                        |
+| Multi-DC          | Complex setup                 | Native geo-distribution    |
 
-- **Single-threaded command processing** - All operations serialized, creating contention with many workers
-- **Memory-only persistence** - Everything must fit in RAM, expensive to scale
-- **Vertical scaling only** - Can't truly distribute a single queue across nodes
-- **Polling overhead** - Thousands of blocked connections
-- **No native backpressure** - Queues can grow unbounded
-- **Weak durability** - Async replication can lose jobs during failures 
 
-**Note:** Alternatives like Dragonfly solve the threading bottleneck but still face memory/scaling limitations.
+### Killer Features:
 
-### The Problem with RDBMS at Scale
+#### — Jobs + Streams, unified in one gem.
 
-- **Database contention** - Polling queries compete with application queries for resources
-- **Connection pool pressure** - Workers consume database connections, starving the application
-- **Row-level locking overhead** - `SELECT FOR UPDATE SKIP LOCKED` still scans rows under high concurrency
-- **Vacuum/autovacuum impact** - High-churn job tables degrade database performance
-- **Vertical scaling only** - Limited by single database instance capabilities
-- **Index bloat** - High UPDATE/DELETE volume causes index degradation over time
-- **Table bloat** - Constant row updates fragment tables, requiring maintenance
-- **`LISTEN/NOTIFY` limitations** - 8KB payload limit, no persistence, breaks down at high volumes (10K+ notifications/sec)
-- **No native horizontal scaling** - Cannot distribute a single job queue across multiple database nodes
+Most Ruby gems handle exactly that — background jobs. If you also need to consume a continuous event feed, that's a second system, second config, second set of
+worker processes, second Dockerfile entry. Cosmonats is the only Ruby gem with a first-class `Job` primitive *and* a first-class `Stream` primitive, sharing
+one server, one config, one CLI, one monitoring endpoint.
 
-**Note:** Solutions using DB might be ok for moderate workloads but face these fundamental limitations at higher scales.
+#### — Message replay and time-travel debugging.
 
-### The Solution
+NATS persists messages to disk and lets any consumer rewind to any point — beginning of time, a specific timestamp, or only new messages.
+- **Incident recovery** — your pipeline crashed for 3 hours. Replay from the crash timestamp.
+- **New consumer bootstrap** — a new service needs historical events. Start it from the beginning.
+- **Bug reproduction** — replay the exact sequence of messages that caused a production issue.
 
-Built on **NATS**, `cosmonats` provides:
+#### — Multi-datacenter queues, natively.
 
-✅ **True horizontal scaling** - Distribute streams across cluster nodes  
-✅ **Disk-backed persistence** - TB-scale queues with memory cache   
-✅ **Replicated acknowledgments** - Survive multi-node failures  
-✅ **Built-in flow control** - Automatic backpressure  
-✅ **Multi-DC support** - Native geo-distribution, and super clusters  
-✅ **High throughput & low latency** - Millions of messages per second  
-✅ **Stream processing** - Beyond simple job queues  
+NATS has a first-class cluster + leaf-node architecture for geo-distribution. Spanning multiple regions or datacenters is a config block — not a separate
+product or a third-party replication tool. NATS was built for edge computing, IoT, and satellite communication — multi-DC is a first-class concern, not an
+afterthought.
+
+#### — Transport-level deduplication + built-in KV. No extra infrastructure.
+
+NATS deduplicates messages at the **broker** — same-ID messages within the configured window are dropped before they ever reach a worker. No uniqueness gems,
+no advisory locks, no extra round-trips. It also ships a built-in Key/Value store usable for distributed locks and rate limiting — no Redis, no Memcached,
+nothing else to run.
 
 
 ## ✨ Features
 
 ### 🎪 Job Processing
-- **Familiar compatible API** - Easy migration from existing codebases
-- **Priority queues** - Multiple priority levels (critical, high, default, low)
-- **Scheduled jobs** - Execute jobs at specific times or after delays
-- **Automatic retries** - Configurable retry strategies with exponential backoff
-- **Dead letter queue** - Capture permanently failed jobs
-- **Job uniqueness** - Prevent duplicate job execution
+- **Familiar API** — `perform_async`, `perform_in`, `perform_at`
+- **Priority queues** — critical, high, default, low with weighted round-robin
+- **Scheduled jobs** — execute at a specific time or after a delay
+- **Automatic retries** — exponential backoff, configurable attempts
+- **Dead letter queue** — capture permanently failed jobs
+- **Job uniqueness** — prevent duplicate execution
 
 ### 🌊 Stream Processing
-- **Real-time data streams** - Process continuous event streams
-- **Batch processing** - Handle multiple messages efficiently
-- **Message replay** - Reprocess messages from any point in time
-- **Consumer groups** - Multiple consumers with load balancing
-- **Exactly-once semantics** - With proper configuration
-- **Custom serialization** - JSON, MessagePack, Protobuf support
+- **Real-time event streams** — process continuous data feeds
+- **Batch processing** — handle multiple messages in one go
+- **Message replay** — reprocess from any point in time
+- **Consumer groups** — load-balanced across workers
+- **Custom serialization** — JSON, MessagePack, Protobuf
 
 
 ## 📦 Installation
@@ -93,64 +154,88 @@ Built on **NATS**, `cosmonats` provides:
 gem "cosmonats"
 ```
 
-**Requirements:** Ruby 3.1.0+, NATS Server ([installation guide](https://docs.nats.io/running-a-nats-service/introduction/installation))
+**Requirements:** Ruby ≥ 3.1, NATS Server ([install guide](https://docs.nats.io/running-a-nats-service/introduction/installation))
+
+Spin up NATS instantly with Docker — one command, that's it:
+```bash
+docker run -p 4222:4222 -p 8222:8222 nats:alpine -js
+```
+
+Or add it to your existing `docker-compose.yml`:
+```yaml
+services:
+  nats:
+    image: nats:alpine
+    command: -js
+    ports:
+      - "4222:4222"
+      - "8222:8222"
+```
+
+Mount the monitoring UI in your Rack app:
+```ruby
+require "cosmo/web"
+
+# Rails
+mount Cosmo::Web => "/cosmo"
+
+# Any Rack app (config.ru)
+map "/cosmo" { run Cosmo::Web }
+```
 
 
 ## 🚀 Quick Start
 
-### 1. Create a Job
+### 1. Create `config/cosmo.yml`
+
+```yaml
+concurrency: 5                     # Number of worker threads
+
+consumers:                         # Declare consumer groups for streams, things that pull messages and process them
+  jobs:                            # Consumer configs for jobs (or streams)
+    default:                       # Stream name
+      ack_policy: explicit         # Acknowledgment required for each message, can be explicit, none, or all
+      max_deliver: 10              # Max retry attempts before sending to a dead stream
+      max_ack_pending: 10          # Max messages waiting for ack, if exceeded, the server will stop delivering new messages until some are acked
+      ack_wait: 15                 # Seconds to wait for ack before redelivering
+      subject: jobs.%{name}.>      # Subject pattern for this consumer, %{name} replaced with stream name, becomes `jobs.default.>`
+
+setup:                             # Initial stream creation only `cosmo -S`
+  jobs:                            # Stream configs for jobs (or streams)
+    default:                       # Stream name
+      storage: file                # Storage type (file or memory)
+      retention: workqueue         # Retention policy (limits, interest, workqueue). workqueue - deletes acked/nacked, limits - append only
+      subjects: ["jobs.%{name}.>"] # Subject pattern for this stream, %{name} replaced with stream name
+      allow_direct: true           # Allow direct messages to stream (required for web UI)
+```
+
+### 2. Create streams in NATS (one-time), grabs config from setup section of `config/cosmo.yml`
+
+```bash
+bundle exec cosmo -S
+```
+
+### 3. Define a job in `app/jobs/`
 
 ```ruby
 class SendEmailJob
   include Cosmo::Job
-
-  # configure job options (optional)
   options stream: :default, retry: 3, dead: true
 
   def perform(user_id, email_type)
-    user = User.find(user_id)
-    UserMailer.send(email_type, user).deliver_now
+    UserMailer.send(email_type, user_id).deliver_now
   end
 end
 ```
 
-### 2. Enqueue Jobs
+### 4. Enqueue & run
 
 ```ruby
-SendEmailJob.perform_async(123, 'welcome')           # Immediately
-SendEmailJob.perform_in(1.hour, 123, 'reminder')     # Delayed
-SendEmailJob.perform_at(1.day.from_now, 123, 'test') # Scheduled
-```
-
-### 3. Configure (config/cosmo.yml)
-
-```yaml
-concurrency: 10
-max_retries: 3
-
-consumers:
-  jobs:
-    default:
-      ack_policy: explicit
-      max_deliver: 3
-      max_ack_pending: 3
-      ack_wait: 60
-
-streams:
-  default:
-    storage: file
-    retention: workqueue
-    subjects: ["jobs.default.>"]
+SendEmailJob.perform_async(42, "welcome")
 ```
 
-### 4. Setup & Run
-
 ```bash
-# Setup streams
-cosmo -C config/cosmo.yml --setup
-
-# Start processing
-cosmo -C config/cosmo.yml -c 10 -r ./app/jobs jobs
+bundle exec cosmo -C config/cosmo.yml -c 10 -r ./app/jobs jobs
 ```
 
 
@@ -158,16 +243,14 @@ cosmo -C config/cosmo.yml -c 10 -r ./app/jobs jobs
 
 ### Jobs
 
-Simple background tasks with a familiar API:
-
 ```ruby
 class ReportJob
   include Cosmo::Job
-  
+
   options(
     stream: :critical,  # Stream name
     retry: 5,           # Retry attempts
-    dead: true          # Use dead letter queue
+    dead: true          # Send to dead letter queue on final failure
   )
 
   def perform(report_id)
@@ -175,20 +258,18 @@ class ReportJob
     Report.find(report_id).generate!
   rescue StandardError => e
     logger.error "Failed: #{e.message}"
-    raise  # Triggers retry
+    raise  # Triggers retry with exponential backoff
   end
 end
 
-# Usage
 ReportJob.perform_async(42)                              # Enqueue now
 ReportJob.perform_in(30.minutes, 42)                     # Delayed
-ReportJob.perform_at(Time.parse('2026-01-25 10:00'), 42) # Scheduled
+ReportJob.perform_at(Time.parse("2026-01-25 10:00"), 42) # Scheduled
+ReportJob.perform_sync(42)                               # Inline, no NATS (great for tests)
 ```
 
 ### Streams
 
-Real-time event processing with powerful features:
-
 ```ruby
 class ClicksProcessor
   include Cosmo::Stream
@@ -205,62 +286,115 @@ class ClicksProcessor
     }
   )
 
-  # Process one message
+  # Process one message at a time
   def process_one
-    data = message.data
-    Analytics.track_click(data)
-    message.ack  # Success
+    Analytics.track_click(message.data)
+    message.ack
   end
-  
-  # OR process batch
+
+  # OR process a batch
   def process(messages)
-    Analytics.track_click(messages.map(&:data))
+    Analytics.bulk_track(messages.map(&:data))
     messages.each(&:ack)
   end
 end
 
 # Publishing
-ClicksProcessor.publish(
-  { user_id: 123, page: '/home' },
-  subject: 'events.clicks.homepage'
-)
+ClicksProcessor.publish({ user_id: 123, page: "/home" }, subject: "events.clicks.homepage")
 
-# Message acknowledgment strategies
+# Acknowledgment strategies
 message.ack                          # Success
-message.nack(delay: 5_000_000_000)   # Retry (5 seconds in nanoseconds)
+message.nack(delay: 5_000_000_000)   # Retry in 5 seconds (nanoseconds)
 message.term                         # Permanent failure, no retry
 ```
 
 ### Configuration
 
-**File-based (config/cosmo.yml):**
+**NATS subjects** follow a dot-separated hierarchy (`events.clicks.homepage`).
+The `>` wildcard matches everything after that prefix. Think of subjects as topic names — flexible routing with no extra configuration.
+
+**Full `config/cosmo.yml` example:**
 ```yaml
-timeout: 25     # Shutdown timeout in seconds
-concurrency: 10 # Number of worker threads
-max_retries: 3  # Default max retries
+timeout: 25                 # Shutdown timeout in seconds
+concurrency: &concurrency 1 # Number of worker threads
+max_retries: &max_retries 3 # Default max retries
+
+stream_config: &stream_config
+  storage: file         # storage type (file or memory)
+  retention: workqueue  # retention policy (limits, interest, workqueue)
+  duplicate_window: 120 # time window for duplicate message detection in seconds
+  discard: old          # discard new messages when stream is full (discard new or old)
+  allow_direct: true    # allow direct messages to stream, required for web UI
+  subjects:
+    - jobs.%{name}.>    # subject pattern for stream, %{name} will be replaced with stream name
+
+consumer_config: &consumer_config
+  ack_policy: explicit    # ack policy (explicit, none, all), each individual message must be acknowledged
+  max_deliver: 10         # maximum number of times a message will be delivered before it's considered failed
+  max_ack_pending: 20     # maximum number of messages with pending ack for this consumer
+  ack_wait: 60            # time in seconds to wait for an ack before redelivering the message
+  subject: jobs.%{name}.> # subject pattern for consumer, %{name} will be replaced with stream name
 
 consumers:
-  streams:
-    - class: MyStream
-      batch_size: 50
-      consumer:
-        ack_policy: explicit
-        max_deliver: 3
-        subjects: ["events.>"]
+  jobs:
+    critical:
+      <<: *consumer_config
+      priority: 50
+    high:
+      <<: *consumer_config
+      priority: 30
+    default:
+      <<: *consumer_config
+      priority: 15
+    low:
+      <<: *consumer_config
+      priority: 5
+    scheduled:
+      <<: *consumer_config
+      max_deliver: 1
+      max_ack_pending: 100
+      ack_wait: 10
 
 setup:
-  streams:
-    my_stream:
-      storage: file         # or memory
-      retention: workqueue  # or limits
-      max_age: 86400       # 1d in seconds
-      subjects: ["events.>"]
+  jobs:
+    critical:
+      <<: *stream_config
+      description: Very critical priority jobs
+    high:
+      <<: *stream_config
+      description: Higher priority jobs
+    default:
+      <<: *stream_config
+      description: Default priority jobs
+    low:
+      <<: *stream_config
+      description: Lower priority jobs
+    scheduled:
+      <<: *stream_config
+      description: Scheduled jobs
+    dead:
+      <<: *stream_config
+      retention: limits
+      max_msgs: 10000
+      max_age: 604800 # 7d
+      description: Broken jobs (DLQ)
+
+development:
+  verbose: false
+  concurrency: *concurrency
+
+staging:
+  verbose: true
+  concurrency: 3
+
+production:
+  concurrency: 3
 ```
 
 **Programmatic:**
 ```ruby
 Cosmo::Config.set(:concurrency, 20)
-Cosmo::Config.set(:setup, :streams, :custom, { storage: 'file', subjects: ['custom.>'] })
+Cosmo::Config.set(:setup, :streams, :custom, { storage: "file", subjects: ["custom.>"] })
 ```
 
 **Environment variables:**
@@ -277,28 +411,15 @@ export COSMO_STREAMS_FETCH_TIMEOUT=0.1
 ```ruby
 class UrgentJob
   include Cosmo::Job
-  options stream: :critical  # priority: 50 in config
+  options stream: :critical  # priority: 50 in config — polled most frequently
 end
-
-# config/cosmo.yml
-consumers:
-  jobs:
-    critical:
-      priority: 50  # Polled more frequently
-    default:
-      priority: 15
 ```
 
 **Custom Serializers:**
 ```ruby
 module MessagePackSerializer
-  def self.serialize(data)
-    MessagePack.pack(data)
-  end
-  
-  def self.deserialize(payload)
-    MessagePack.unpack(payload)
-  end
+  def self.serialize(data) = MessagePack.pack(data)
+  def self.deserialize(payload) = MessagePack.unpack(payload)
 end
 
 class FastStream
@@ -317,21 +438,21 @@ class ResilientJob
     process_data(data)
   rescue RetryableError => e
     logger.warn "Retryable: #{e.message}"
-    raise  # Will retry
+    raise  # Will retry with exponential backoff
   rescue FatalError => e
     logger.error "Fatal: #{e.message}"
-    # Don't raise - won't retry
+    # Don't raise — won't retry, won't go to DLQ
   end
 end
 ```
 
 **Testing:**
 ```ruby
-# Synchronous execution
-SendEmailJob.perform_sync(123, 'test')
+# Synchronous — no NATS needed
+SendEmailJob.perform_sync(123, "test")
 
-# Test job creation
-jid = SendEmailJob.perform_async(123, 'welcome')
+# Async — returns a job ID
+jid = SendEmailJob.perform_async(123, "welcome")
 assert_kind_of String, jid
 ```
 
@@ -339,29 +460,24 @@ assert_kind_of String, jid
 ## 🖥️ CLI Reference
 
 ```bash
-# Setup streams
-cosmo -C config/cosmo.yml --setup
-
-# Run processors
-cosmo -C config/cosmo.yml -c 20 -r ./app/jobs jobs     # Jobs only
-cosmo -C config/cosmo.yml -c 20 streams                # Streams only
-cosmo -C config/cosmo.yml -c 20                        # Both
+cosmo -C config/cosmo.yml --setup                  # Create streams in NATS (idempotent)
+cosmo -C config/cosmo.yml -c 20 -r ./app/jobs jobs # Jobs only
+cosmo -C config/cosmo.yml -c 20 streams            # Streams only
+cosmo -C config/cosmo.yml -c 20                    # Both
 ```
 
-**Common Flags:**
-
-| Flag | Description | Example |
-|------|-------------|---------|
-| `-C, --config PATH` | Config file path | `-C config/cosmo.yml` |
-| `-c, --concurrency INT` | Worker threads | `-c 20` |
-| `-r, --require PATH` | Auto-require directory | `-r ./app/jobs` |
-| `-t, --timeout NUM` | Shutdown timeout (sec) | `-t 60` |
-| `-S, --setup` | Setup streams & exit | `--setup` |
+| Flag                    | Description            | Example               |
+|-------------------------|------------------------|-----------------------|
+| `-C, --config PATH`     | Config file path       | `-C config/cosmo.yml` |
+| `-c, --concurrency INT` | Worker threads         | `-c 20`               |
+| `-r, --require PATH`    | Auto-require directory | `-r ./app/jobs`       |
+| `-t, --timeout NUM`     | Shutdown timeout (sec) | `-t 60`               |
+| `-S, --setup`           | Setup streams & exit   | `--setup`             |
 
 
 ## 🚢 Deployment
 
-**NATS Cluster:**
+**NATS Cluster config:**
 ```bash
 # nats-server.conf
 port: 4222
@@ -385,7 +501,7 @@ services:
     volumes:
       - ./nats.conf:/etc/nats/nats-server.conf
       - nats-data:/var/lib/nats
-  
+
   worker:
     build: .
     environment:
@@ -419,17 +535,14 @@ SyslogIdentifier=cosmo
 WantedBy=multi-user.target
 ```
 
-Enable and start:
 ```bash
-sudo systemctl enable cosmo
-sudo systemctl start cosmo
-sudo systemctl status cosmo
+sudo systemctl enable cosmo && sudo systemctl start cosmo
 ```
 
 
 ## 📊 Monitoring
 
-**Structured Logging:**
+**Structured logs:**
 ```
 2026-01-23T10:15:30.123Z INFO pid=12345 tid=abc jid=def: start
 2026-01-23T10:15:32.456Z INFO pid=12345 tid=abc jid=def elapsed=2.333: done
@@ -438,22 +551,22 @@ sudo systemctl status cosmo
 **Stream Metrics:**
 ```ruby
 client = Cosmo::Client.instance
-info = client.stream_info('default')
+info = client.stream_info("default")
 
 info.state.messages       # Total messages
 info.state.bytes          # Total bytes
 info.state.consumer_count # Number of consumers
 ```
 
-**Prometheus:** NATS exposes metrics at `:8222/metrics`
-- `jetstream_server_store_msgs` - Messages in stream
-- `jetstream_consumer_delivered_msgs` - Delivered messages
-- `jetstream_consumer_ack_pending` - Pending acknowledgments
+**Prometheus** — NATS exposes metrics at `:8222/metrics`:
+- `jetstream_server_store_msgs` — Messages in stream
+- `jetstream_consumer_delivered_msgs` — Delivered messages
+- `jetstream_consumer_ack_pending` — Pending acknowledgments
 
 
 ## 💼 Examples
 
-**Email Queue:**
+**Email queue with scheduling:**
 ```ruby
 class EmailJob
   include Cosmo::Job
@@ -465,8 +578,8 @@ class EmailJob
   end
 end
 
-EmailJob.perform_async(123, 'welcome')
-EmailJob.perform_in(1.day, 123, 'followup')
+EmailJob.perform_async(123, "welcome")
+EmailJob.perform_in(1.day, 123, "followup")
 ```
 
 **Image Processing Pipeline:**
@@ -475,37 +588,37 @@ class ImageProcessor
   include Cosmo::Stream
   options(
     stream: :images,
-    consumer: { subjects: ['images.uploaded.>'] }
+    consumer: { subjects: ["images.uploaded.>"] }
   )
 
   def process_one
-    processed = ImageService.process(message.data['url'])
-    publish(processed, subject: 'images.processed.optimized')
+    processed = ImageService.process(message.data["url"])
+    publish(processed, subject: "images.processed.optimized")
     message.ack
   rescue => e
     logger.error "Processing failed: #{e.message}"
-    message.nack(delay: 30_000_000_000)
+    message.nack(delay: 30_000_000_000) # retry in 30s
   end
 end
 
-ImageProcessor.publish({ url: 'https://example.com/image.jpg' }, subject: 'images.uploaded.user')
+ImageProcessor.publish({ url: "https://example.com/image.jpg" }, subject: "images.uploaded.user")
 ```
 
 **Real-Time Analytics:**
 ```ruby
 class AnalyticsAggregator
   include Cosmo::Stream
-  options batch_size: 1000, consumer: { subjects: ['events.*.>'] }
+  options batch_size: 1000, consumer: { subjects: ["events.*.>"] }
 
   def process(messages)
-    events = messages.map(&:data)
-    aggregates = events.group_by { |e| e['type'] }.transform_values(&:count)
+    aggregates = messages.map(&:data).group_by { |e| e["type"] }.transform_values(&:count)
     Analytics.bulk_insert(aggregates)
     messages.each(&:ack)
   end
 end
 ```
 
+---
 
 <div align="center">