cosmonats 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f850638b66506538b131180c03b64a13e31cd86f924503703812da49b6ba3d20
-  data.tar.gz: 0dfdab08193600f3bca2c32558ffb016a38657f9488789770eea5e60612281e9
+  metadata.gz: 6f94d9b1e192b098e1bcb3ce77998d7b0ed9aca359af41fefe2a572624fa6b91
+  data.tar.gz: 12bba3015a4beb335efae8dfe5fc178a6c467d203eaf61f922bf1b3091b67ce6
 SHA512:
-  metadata.gz: 56f46ac8a8c1409b1583033ad8b5cf9e513652fae2643b07344aa8f8bf1cca80f948463af92e2a989ec9679cc830ac05a6b873b1f0c9b5e10a1e6ef5e8399ad0
-  data.tar.gz: '086ae5c5b26471417e54c37d2f782c0c103340953e9a27ca8c02131478122f01ede30f2f8ab5a0b29c81ce7b4ea07a5c8de8e7f51957e4d9d5dfd5d670a0ff08'
+  metadata.gz: e24c844b4f17aa7eaffceebdd6b847858855fc0b5526b5537832893fd144e71f427ae352700adff3c5b39ed5cd04c89bc84007d01548ff97ba701a45e8c836b9
+  data.tar.gz: d1a7d5e0d45c5f9b03388259b45a5a6ce659dd39378a0f13e8f31cf36d7f969a332076cada74b564f2fd7d504c646df0715778679d0e67743a5f0ef08398e7c9

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    |
+
+
+### Killer Features:
 
-- **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 
+#### — Jobs + Streams, unified in one gem.
 
-**Note:** Alternatives like Dragonfly solve the threading bottleneck but still face memory/scaling limitations.
+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.
 
-### The Problem with RDBMS at Scale
+#### — Message replay and time-travel debugging.
 
-- **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
+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.
 
-**Note:** Solutions using DB might be ok for moderate workloads but face these fundamental limitations at higher scales.
+#### — Multi-datacenter queues, natively.
 
-### The Solution
+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.
 
-Built on **NATS**, `cosmonats` provides:
+#### — Transport-level deduplication + built-in KV. No extra infrastructure.
 
-✅ **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 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,71 +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))
 
-Add these lines to config/routes.rb:
+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.application.routes.draw do
-  mount Cosmo::Web => "/cosmo" # access web UI at http://localhost:3000/cosmo
-  ...
-end
+# Rails
+mount Cosmo::Web => "/cosmo"
+
+# Any Rack app (config.ru)
+map "/cosmo" { run Cosmo::Web }
 ```
 
 
 ## 🚀 Quick Start
 
-### 1. Create `config/cosmo.yml` and run `bundle exec cosmo -S` to create streams in NATS:
+### 1. Create `config/cosmo.yml`
 
 ```yaml
-concurrency: 5
-max_retries: 3
+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)
+```
 
-consumers:
-  jobs:
-    default:
-      ack_policy: explicit
-      max_deliver: 10
-      max_ack_pending: 10
-      ack_wait: 15
-      subject: jobs.%{name}.>
+### 2. Create streams in NATS (one-time), grabs config from setup section of `config/cosmo.yml`
 
-setup:
-  jobs:
-    default:
-      storage: file
-      retention: workqueue
-      subjects: ["jobs.%{name}.>"]
-      allow_direct: true
-``` 
+```bash
+bundle exec cosmo -S
+```
 
-### 2. Create a Job in app/workers
+### 3. Define a job in `app/jobs/`
 
 ```ruby
 class SendEmailJob
   include Cosmo::Job
-
   options stream: :default, retry: 3, dead: true
 
   def perform(user_id, email_type)
-    # Pretend to send email to user: UserMailer.send(email_type, user_id).deliver_now
-    sleep 0.5 # Simulate work
-    puts "#{user_id}, #{email_type}"
+    UserMailer.send(email_type, user_id).deliver_now
   end
 end
 ```
 
-### 3. Enqueue Jobs
+### 4. Enqueue & run
 
 ```ruby
-10.times { |i| SendEmailJob.perform_async(i, "welcome") }
+SendEmailJob.perform_async(42, "welcome")
 ```
 
-### 4. Run
-
 ```bash
-bundle exec cosmo jobs
+bundle exec cosmo -C config/cosmo.yml -c 10 -r ./app/jobs jobs
 ```
 
 
@@ -165,16 +243,14 @@ bundle exec cosmo 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)
@@ -182,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_sync(42)                               # Inline, no NATS (great for tests)
 ```
 
 ### Streams
 
-Real-time event processing with powerful features:
-
 ```ruby
 class ClicksProcessor
   include Cosmo::Stream
@@ -212,35 +286,34 @@ 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: &concurrency 1 # Number of worker threads
@@ -338,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
@@ -378,20 +438,20 @@ 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
+# Synchronous — no NATS needed
 SendEmailJob.perform_sync(123, "test")
 
-# Test job creation
+# Async — returns a job ID
 jid = SendEmailJob.perform_async(123, "welcome")
 assert_kind_of String, jid
 ```
@@ -400,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
@@ -446,7 +501,7 @@ services:
     volumes:
       - ./nats.conf:/etc/nats/nats-server.conf
       - nats-data:/var/lib/nats
-  
+
   worker:
     build: .
     environment:
@@ -480,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
@@ -506,15 +558,15 @@ 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
@@ -545,7 +597,7 @@ class ImageProcessor
     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
 
@@ -559,14 +611,14 @@ class AnalyticsAggregator
   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">
 

data/lib/cosmo/active_job/adapter.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Cosmo
+  module ActiveJobAdapter
+    # ActiveJob queue adapter that enqueues jobs via NATS JetStream.
+    #
+    # Usage:
+    #   config.active_job.queue_adapter = :cosmonats
+    #   # or explicitly:
+    #   config.active_job.queue_adapter = Cosmo::ActiveJobAdapter::Adapter.new
+    #
+    # The ActiveJob queue name maps directly to the Cosmo stream name.
+    class Adapter
+      # Enqueue a job to be run as soon as possible.
+      # @param job [ActiveJob::Base]
+      def enqueue(job)
+        publish(job, nil)
+      end
+
+      # Enqueue a job to be run at (or after) a given time.
+      # @param job [ActiveJob::Base]
+      # @param timestamp [Numeric] Unix timestamp (seconds, float)
+      def enqueue_at(job, timestamp)
+        publish(job, timestamp)
+      end
+
+      private
+
+      def publish(job, timestamp)
+        cosmo_opts = job_cosmo_options(job)
+        stream     = cosmo_opts.delete(:stream) || job.queue_name.to_sym
+        options    = { stream: stream }.merge(cosmo_opts)
+        options[:at] = timestamp if timestamp
+
+        data = Job::Data.new(Executor.name, [job.serialize], options)
+        Publisher.publish_job(data)
+      end
+
+      # Returns Cosmo-specific options declared on the job class via
+      # +cosmo_options+, falling back to an empty hash.
+      def job_cosmo_options(job)
+        job.class.respond_to?(:get_cosmo_options) ? job.class.get_cosmo_options : {}
+      end
+    end
+  end
+end

data/lib/cosmo/active_job/executor.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Cosmo
+  module ActiveJobAdapter
+    # Cosmo::Job that deserializes and executes an ActiveJob payload
+    class Executor
+      include Cosmo::Job
+
+      options stream: :default
+
+      def perform(job_data)
+        ::ActiveJob::Base.execute(Utils::Hash.stringify_keys(job_data))
+      end
+    end
+  end
+end