cosmonats 0.5.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ade68e6438fc5ea6cec3fd97bf2794c87f2117414c56c69e49e67544f35e7ab
-  data.tar.gz: db98a44b41d057795b6a9f8c56316252b4cad1ab2f2a07912a66e16c09a86013
+  metadata.gz: 96e901f7365784bf2fb7087311112efb263f295eddbe25a96ff32de4ebfe0652
+  data.tar.gz: b1f7327b126f85e50222af5adf2172b8fab84aa051209e9c0e9b478254bcb8a8
 SHA512:
-  metadata.gz: bd359b85f69bcdc85f800ec8dc0e4b24ff09e905851e412047dd96a0154c21b459bf52465493ee1a05c664968817828124fa35919cd7174d0f3c0ebe0ba867ca
-  data.tar.gz: dbb223d897a14e457bcf78085896ed0c7f1548eb7565621e35b62257879065dfb653d8cc58a396c921d508afe92e1b9640cbfd3cf9845d00ee471b577609ffa7
+  metadata.gz: 1ab5c6cc101edf8dbf8909f544ed9a9fd8603c76f073dad60c5251e086195518e07ec5a6815bcf382b05c7b80f67fb6994a4615be933b33c29103ea3082990af
+  data.tar.gz: 85b15998b6286a331558e847835f6a94cf0936adae88e70a18035335b2414096d583e4619b7b2e5f5c7e579117c0d3626dbb99e189084fc3cf7aedc25dfc4fba

data/LICENSE.txt

@@ -1,169 +1,21 @@
-                   GNU LESSER GENERAL PUBLIC LICENSE
-                       Version 3, 29 June 2007
-
- Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
-
-
-  This version of the GNU Lesser General Public License incorporates
-the terms and conditions of version 3 of the GNU General Public
-License, supplemented by the additional permissions listed below.
-
-  0. Additional Definitions.
-
-  As used herein, "this License" refers to version 3 of the GNU Lesser
-General Public License, and the "GNU GPL" refers to version 3 of the GNU
-General Public License.
-
-  "The Library" refers to a covered work governed by this License,
-other than an Application or a Combined Work as defined below.
-
-  An "Application" is any work that makes use of an interface provided
-by the Library, but which is not otherwise based on the Library.
-Defining a subclass of a class defined by the Library is deemed a mode
-of using an interface provided by the Library.
-
-  A "Combined Work" is a work produced by combining or linking an
-Application with the Library.  The particular version of the Library
-with which the Combined Work was made is also called the "Linked
-Version".
-
-  The "Minimal Corresponding Source" for a Combined Work means the
-Corresponding Source for the Combined Work, excluding any source code
-for portions of the Combined Work that, considered in isolation, are
-based on the Application, and not on the Linked Version.
-
-  The "Corresponding Application Code" for a Combined Work means the
-object code and/or source code for the Application, including any data
-and utility programs needed for reproducing the Combined Work from the
-Application, but excluding the System Libraries of the Combined Work.
-
-  1. Exception to Section 3 of the GNU GPL.
-
-  You may convey a covered work under sections 3 and 4 of this License
-without being bound by section 3 of the GNU GPL.
-
-  2. Conveying Modified Versions.
-
-  If you modify a copy of the Library, and, in your modifications, a
-facility refers to a function or data to be supplied by an Application
-that uses the facility (other than as an argument passed when the
-facility is invoked), then you may convey a copy of the modified
-version:
-
-   a) under this License, provided that you make a good faith effort to
-   ensure that, in the event an Application does not supply the
-   function or data, the facility still operates, and performs
-   whatever part of its purpose remains meaningful, or
-
-   b) under the GNU GPL, with none of the additional permissions of
-   this License applicable to that copy.
-
-  3. Object Code Incorporating Material from Library Header Files.
-
-  The object code form of an Application may incorporate material from
-a header file that is part of the Library.  You may convey such object
-code under terms of your choice, provided that, if the incorporated
-material is not limited to numerical parameters, data structure
-layouts and accessors, or small macros, inline functions and templates
-(ten or fewer lines in length), you do both of the following:
-
-   a) Give prominent notice with each copy of the object code that the
-   Library is used in it and that the Library and its use are
-   covered by this License.
-
-   b) Accompany the object code with a copy of the GNU GPL and this license
-   document.
-
-  4. Combined Works.
-
-  You may convey a Combined Work under terms of your choice that,
-taken together, effectively do not restrict modification of the
-portions of the Library contained in the Combined Work and reverse
-engineering for debugging such modifications, if you also do each of
-the following:
-
-   a) Give prominent notice with each copy of the Combined Work that
-   the Library is used in it and that the Library and its use are
-   covered by this License.
-
-   b) Accompany the Combined Work with a copy of the GNU GPL and this license
-   document.
-
-   c) For a Combined Work that displays copyright notices during
-   execution, include the copyright notice for the Library among
-   these notices, as well as a reference directing the user to the
-   copies of the GNU GPL and this license document.
-
-   d) Do one of the following:
-
-       0) Convey the Minimal Corresponding Source under the terms of this
-       License, and the Corresponding Application Code in a form
-       suitable for, and under terms that permit, the user to
-       recombine or relink the Application with a modified version of
-       the Linked Version to produce a modified Combined Work, in the
-       manner specified by section 6 of the GNU GPL for conveying
-       Corresponding Source.
-
-       1) Use a suitable shared library mechanism for linking with the
-       Library.  A suitable mechanism is one that (a) uses at run time
-       a copy of the Library already present on the user's computer
-       system, and (b) will operate properly with a modified version
-       of the Library that is interface-compatible with the Linked
-       Version.
-
-   e) Provide Installation Information, but only if you would otherwise
-   be required to provide such information under section 6 of the
-   GNU GPL, and only to the extent that such information is
-   necessary to install and execute a modified version of the
-   Combined Work produced by recombining or relinking the
-   Application with a modified version of the Linked Version. (If
-   you use option 4d0, the Installation Information must accompany
-   the Minimal Corresponding Source and Corresponding Application
-   Code. If you use option 4d1, you must provide the Installation
-   Information in the manner specified by section 6 of the GNU GPL
-   for conveying Corresponding Source.)
-
-  5. Combined Libraries.
-
-  You may place library facilities that are a work based on the
-Library side by side in a single library together with other library
-facilities that are not Applications and are not covered by this
-License, and convey such a combined library under terms of your
-choice, if you do both of the following:
-
-   a) Accompany the combined library with a copy of the same work based
-   on the Library, uncombined with any other library facilities,
-   conveyed under the terms of this License.
-
-   b) Give prominent notice with the combined library that part of it
-   is a work based on the Library, and explaining where to find the
-   accompanying uncombined form of the same work.
-
-  6. Revised Versions of the GNU Lesser General Public License.
-
-  The Free Software Foundation may publish revised and/or new versions
-of the GNU Lesser General Public License from time to time. Such new
-versions will be similar in spirit to the present version, but may
-differ in detail to address new problems or concerns.
-
-  Each version is given a distinguishing version number. If the
-Library as you received it specifies that a certain numbered version
-of the GNU Lesser General Public License "or any later version"
-applies to it, you have the option of following the terms and
-conditions either of that published version or of any later version
-published by the Free Software Foundation. If the Library as you
-received it does not specify a version number of the GNU Lesser
-General Public License, you may choose any version of the GNU Lesser
-General Public License ever published by the Free Software Foundation.
-
-  If the Library as you received it specifies that a proxy can decide
-whether future versions of the GNU Lesser General Public License shall
-apply, that proxy's public statement of acceptance of any version is
-permanent authorization for you to choose that version for the
-Library.
-
-Copyright (c) BitsBeam LLC
-
-https://www.gnu.org/licenses/lgpl-3.0.txt
+MIT License
+
+Copyright (c) 2026 Dmitry Vorotilin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -10,7 +10,7 @@ Background jobs + real-time event streaming for Ruby — unified, in one gem, ba
 [![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)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.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.*
@@ -168,6 +168,19 @@ gem "cosmonats"
 
 **Requirements:** Ruby ≥ 3.1, NATS Server ([install guide](https://docs.nats.io/running-a-nats-service/introduction/installation))
 
+**Optional gems** — not installed with `cosmonats`, add them only for the features you use:
+
+| Feature                                       | Gems              |
+|-----------------------------------------------|-------------------|
+| Monitoring UI (`Cosmo::Web`)                  | `rack`            |
+| Health check HTTP server (`/health`, `/ping`) | `rack`, `webrick` |
+
+```ruby
+# Gemfile
+gem "rack", "~> 3.0"
+gem "webrick", "~> 1.9"
+```
+
 Spin up NATS instantly with Docker — one command, that's it:
 ```bash
 docker run -p 4222:4222 -p 8222:8222 nats:alpine -js
@@ -336,7 +349,7 @@ 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)
+  discard: old          # what to drop when the stream is full (new rejects publishes, old evicts the oldest)
   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
@@ -364,7 +377,7 @@ consumers:
       priority: 5
     scheduled:
       <<: *consumer_config
-      max_deliver: 1
+      max_deliver: 5
       max_ack_pending: 100
       ack_wait: 10
 
@@ -384,6 +397,7 @@ setup:
       description: Lower priority jobs
     scheduled:
       <<: *stream_config
+      discard: old            # required here: NATS refuses `discard: new` on the stream holding cron schedules
       description: Scheduled jobs
     dead:
       <<: *stream_config
@@ -423,10 +437,16 @@ export COSMO_STREAMS_FETCH_TIMEOUT=0.1
 ### Cron
 
 Recurring jobs, without a separate scheduler process. A schedule is just a message parked in the
-job's own NATS stream (requires NATS Server 2.14+) — NATS fires it on the cron expression, and it
-lands back in the stream as a regular job. Deploy it once; whatever's in NATS is exactly what runs
-and exactly what shows up in the web UI's **Crons** tab, where each entry can be inspected, run
-immediately, or deleted.
+`scheduled` stream (requires NATS Server 2.14+) — NATS fires it on the cron expression, and the
+worker's scheduler dispatches the job on to the stream that runs it, the same path a delayed job
+takes. Deploy it once; whatever's in NATS is exactly what runs and exactly what shows up in the web
+UI's **Crons** tab, where each entry can be inspected, run immediately, or deleted.
+
+Every schedule lives in `scheduled` because NATS only lets a schedule fire at a subject its own
+stream covers, and refuses `discard: new` on any stream with scheduling enabled. Keeping schedules
+in one stream leaves every stream that actually runs jobs free to choose its own discard policy.
+The trade is that cron firings are dispatched by the scheduler, so at least one worker has to be
+running without `--no-scheduler`.
 
 Declare schedules right in `config/cosmo.yml`:
 
@@ -641,19 +661,79 @@ setup beyond having `sentry-ruby` initialized.
 ## 🖥️ CLI Reference
 
 ```bash
-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
+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
+cosmo -C config/cosmo.yml jobs --streams default,high # Jobs, limited to these streams
+cosmo -C config/cosmo.yml jobs --stream critical      # Jobs, limited to one stream
+cosmo -C config/cosmo.yml jobs --no-scheduler         # Jobs, without dispatching scheduled jobs
+COSMO_JOBS_STREAMS=default,high cosmo jobs            # Same filter, without touching the command line
+```
+
+Each selected stream gets its own durable consumer, named `consumer-<stream>`. Every process that subscribes to a stream
+pulls from that same consumer, so running a dedicated fleet per stream splits the work instead of duplicating it.
+The `scheduled` stream is a service stream: it is always dispatched, and naming it in `--streams` selects nothing, use
+`--no-scheduler` on workers that should not dispatch scheduled jobs. Unknown stream names abort the process.
+
+**Global flags** (before the command):
+
+| 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 & sync cron, then exit  | `--setup`             |
+| `-v, --version`         | Print version and exit                | `--version`           |
+| `-h, --help`            | Show help and exit                    | `--help`               |
+
+**`jobs` command options:**
+
+| Flag                    | Description                                                       | Example                        |
+|-------------------------|--------------------------------------------------------------------|---------------------------------|
+| `--streams NAMES`       | Only subscribe to these job streams, instead of all configured ones | `--streams default,high`      |
+| `--stream NAME`         | Same as `--streams`, for a single stream                           | `--stream default`             |
+| `--[no-]scheduler`      | Dispatch scheduled jobs (default: yes)                             | `--no-scheduler`               |
+| `--subject NAME`        | Job's subject                                                      | `--subject jobs.default.foo`   |
+
+`--streams`/`--stream` also read from `COSMO_JOBS_STREAMS` (comma-separated) when neither flag is given.
+
+**`streams` command options** (`--stream`/`--subject`/`--consumer_name`/`--batch_size` apply only when running a single processor; ignored once `--processors` selects more than one):
+
+| Flag                     | Description                          | Example                         |
+|--------------------------|---------------------------------------|---------------------------------|
+| `--processors NAMES`     | Only run these stream processor classes | `--processors OrderProcessor` |
+| `--stream NAME`          | Stream name                          | `--stream orders`              |
+| `--subject NAME`         | Subject name                         | `--subject orders.created`     |
+| `--consumer_name NAME`   | Consumer name                        | `--consumer_name orders-consumer` |
+| `--batch_size NUM`       | Messages per fetch batch             | `--batch_size 50`               |
+
+
+### Health check
+
+Pass `-p/--http-port` (or set `http.port` in the config) to start a small WEBrick HTTP server alongside the workers.
+It needs the optional `rack` and `webrick` gems (see [Installation](#-installation)); without a port they're never loaded.
+
+```yaml
+http:
+  port: 9090
+  host: 0.0.0.0 # default
+```
+
+`GET /health` returns `200` when processors are running and NATS is connected, `503` otherwise:
+
+```bash
+curl localhost:9090/health
+# {"status":"ok","checks":{"engine":true,"nats":true}}
 ```
 
-| 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`             |
+`GET /ping` always returns `200 pong` without checking anything, handy as a liveness probe (use `/health` for readiness):
+
+```bash
+curl localhost:9090/ping
+# pong
+```
 
 
 ## 🚢 Deployment
@@ -725,6 +805,10 @@ sudo systemctl enable cosmo && sudo systemctl start cosmo
 
 **Web UI** — mount `Cosmo::Web` (see [Installation](#-installation)) for a live, htmx-powered dashboard:
 - **Jobs** — enqueued, scheduled, busy, and dead views, with per-job retry and delete
+- **Processes** — the Jobs dashboard lists every live worker (idle ones included): host, pid, IP, NATS connection
+  name, command line, subscribed streams, busy/concurrency, running/quiet/stopping state, memory, NATS RTT and
+  reconnects. Each worker
+  beats into the `cosmo_processes` KV bucket every 10s, and a crashed worker drops out within 60s
 - **Streams** — per-stream state (messages, bytes, consumers) with pause/resume
 - **Crons** — every schedule deployed in NATS, with run-now and delete
 - **Batches** — open and finished batches with pending/succeeded/failed counts

data/lib/cosmo/api/counter.rb

@@ -4,23 +4,26 @@ module Cosmo
   module API
     class Counter
       STREAM_NAME = "_cosmostats"
+      STREAM_CONFIG = {
+        subjects: ["#{STREAM_NAME}.>"],
+        allow_msg_counter: true,
+        allow_direct: true,
+        max_msgs_per_subject: 1,
+        description: "Cosmo statistics"
+      }.freeze
 
-      def self.instance
-        @instance ||= new("jobs")
+      # Creates the counters stream, or brings an existing one up to STREAM_CONFIG. Every stored
+      # counter message carries the running total, so only the last one per subject is kept.
+      #
+      # @return [void]
+      def self.setup!
+        Client.instance.setup_stream(STREAM_NAME, STREAM_CONFIG)
       end
 
       def initialize(namespace)
         @namespace = namespace
       end
 
-      def with
-        result = yield
-        increment(:processed) if result == true
-        increment(:failed) if result == false
-      rescue Exception # rubocop:disable Lint/RescueException
-        increment(:failed)
-      end
-
       def increment(key, by: 1, msg_id: nil)
         publish(key, "+#{by}", msg_id: msg_id)
       end
@@ -64,7 +67,7 @@ module Cosmo
           raise if rescued
 
           rescued = true
-          client.create_stream(STREAM_NAME, subjects: ["#{STREAM_NAME}.>"], allow_msg_counter: true, allow_direct: true, description: "Cosmo statistics")
+          client.create_stream(STREAM_NAME, STREAM_CONFIG)
           retry
         end
       end

data/lib/cosmo/api/cron/entry.rb

@@ -54,12 +54,31 @@ module Cosmo
           parts.join(".")
         end
 
-        # Subject where NATS fires the generated job message.
-        # Must be a subject covered by the same stream.
+        # Subject where NATS fires the generated job message. A schedule may only target a
+        # subject its own stream covers, so every schedule fires into the scheduled stream and
+        # the scheduler forwards the job on to {#dispatch_subject}.
         def target_subject
+          "jobs.#{::Cosmo::Job::StreamFilter::SCHEDULED}.#{job_name}"
+        end
+
+        # Subject the scheduler dispatches the fired job to, on the stream that runs it.
+        def dispatch_subject
           "jobs.#{@stream}.#{job_name}"
         end
 
+        # Headers stored on the schedule template. NATS copies the +X-+ ones onto every message
+        # it fires, which is how the scheduler learns where the job belongs.
+        def schedule_headers
+          headers = {
+            "Nats-Schedule" => @expression,
+            "Nats-Schedule-Target" => target_subject,
+            "X-Stream" => @stream,
+            "X-Subject" => dispatch_subject
+          }
+          headers["Nats-Schedule-Time-Zone"] = @timezone if @timezone
+          headers
+        end
+
         def job_name
           @job_name ||= Utils::String.underscore(@class_name)
         end
@@ -73,7 +92,8 @@ module Cosmo
             args: @args,
             name: @name,
             schedule_subject: schedule_subject,
-            target_subject: target_subject
+            target_subject: target_subject,
+            dispatch_subject: dispatch_subject
           }.compact
         end
 

data/lib/cosmo/api/cron.rb

@@ -10,18 +10,22 @@ module Cosmo
     # Derives the schedule list entirely from NATS.
     # Whatever is deployed in NATS is exactly what appears in the UI.
     #
-    # Schedule templates live in the same job stream they target (e.g. +default+),
-    # stored at subjects matching +cosmo.cron.<stream>.>+. NATS 2.14 fires each
-    # template by publishing the body to +Nats-Schedule-Target+ as a regular
-    # JetStream message that accumulates alongside pending jobs.
+    # Every schedule template lives in the +scheduled+ stream, at a subject matching
+    # +cosmo.cron.<target stream>.>+. NATS fires a template by publishing its body to
+    # +Nats-Schedule-Target+, which has to be a subject the storing stream covers, so a firing
+    # lands back in +scheduled+ and the job processor's scheduler dispatches it to the stream
+    # that runs it. That confines message scheduling - and the +discard: old+ NATS demands
+    # wherever scheduling is enabled - to a single stream.
     class Cron
+      STREAM = ::Cosmo::Job::StreamFilter::SCHEDULED.to_s
+
       def self.instance
         @instance ||= new
       end
 
       # @return [Array<Hash>] every cron schedule currently deployed in NATS
       def all
-        Stream.jobs.flat_map { |s| schedules_from_stream(s.name) }
+        schedules
       rescue StandardError
         []
       end
@@ -31,20 +35,14 @@ module Cosmo
       def upsert!(class_name: nil, stream: nil, schedule: nil, args: [], timezone: nil, name: nil)
         e = Entry.new(class_name: class_name, stream: stream, expression: schedule,
                       args: args, timezone: timezone, name: name)
-        headers = {
-          "Nats-Schedule" => e.expression,
-          "Nats-Schedule-Target" => e.target_subject
-        }
-        headers["Nats-Schedule-Time-Zone"] = e.timezone if e.timezone
-        client.publish(e.schedule_subject, e.job_payload, stream: e.stream, header: headers)
-        build_from_nats(e.stream, e.schedule_subject)
+        client.publish(e.schedule_subject, e.job_payload, stream: STREAM, header: e.schedule_headers)
+        build_from_nats(e.schedule_subject)
       end
 
       # Purge the schedule message from NATS (stops future firings).
       # @param subject [String]
       def delete!(subject)
-        stream_name = subject.to_s.split(".")[2]
-        client.purge(stream_name, subject)
+        client.purge(STREAM, subject)
       rescue NATS::JetStream::Error::NotFound, NATS::IO::Timeout
         nil
       end
@@ -52,13 +50,12 @@ module Cosmo
       # Dispatch the job immediately to the target stream, bypassing the timer.
       # @param schedule_subject [String] e.g. "cosmo.cron.default.report_job.daily"
       def run_now!(schedule_subject) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
-        stream_name = schedule_subject.to_s.split(".")[2]
-        msg = client.get_message(stream_name, subject: schedule_subject)
+        msg = client.get_message(STREAM, subject: schedule_subject)
         return unless msg
 
         headers = msg.headers || {}
         body = Utils::Json.parse(msg.data) || {}
-        target = headers["Nats-Schedule-Target"]
+        target = headers["X-Subject"]
         return unless target && body[:class]
 
         payload = Utils::Json.dump({
@@ -68,7 +65,7 @@ module Cosmo
                                      retry: body[:retry] || Job::Data.default_retry,
                                      dead: body[:dead].nil? ? Job::Data::DEFAULTS[:dead] : body[:dead]
                                    })
-        client.publish(target, payload, stream: stream_name)
+        client.publish(target, payload, stream: headers["X-Stream"])
       rescue NATS::JetStream::Error::NotFound
         nil
       end
@@ -79,14 +76,13 @@ module Cosmo
         @client ||= Client.instance
       end
 
-      def schedules_from_stream(stream_name)
-        filter = "#{Entry::SUBJECT_PREFIX}.#{stream_name}.>"
-        subjects = client.cron_subjects_in_stream(stream_name, filter)
-        subjects.filter_map { |subj| build_from_nats(stream_name, subj) }
+      def schedules
+        subjects = client.cron_subjects_in_stream(STREAM, "#{Entry::SUBJECT_PREFIX}.>")
+        subjects.filter_map { |subj| build_from_nats(subj) }
       end
 
-      def build_from_nats(stream_name, subject)
-        msg = client.get_message(stream_name, subject: subject)
+      def build_from_nats(subject)
+        msg = client.get_message(STREAM, subject: subject)
         return unless msg
 
         headers = msg.headers || {}
@@ -94,13 +90,13 @@ module Cosmo
 
         {
           class: body[:class],
-          stream: stream_name,
+          stream: headers["X-Stream"],
           schedule: headers["Nats-Schedule"],
           timezone: headers["Nats-Schedule-Time-Zone"],
           args: body[:args] || [],
           name: name_from_subject(subject),
           schedule_subject: subject,
-          target_subject: headers["Nats-Schedule-Target"],
+          dispatch_subject: headers["X-Subject"],
           registry_key: subject.split(".").drop(2).join("/")
         }
       rescue StandardError

data/lib/cosmo/api/job.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "time"
+
 module Cosmo
   module API
     class Job
@@ -38,9 +40,37 @@ module Cosmo
         @message.subject
       end
 
+      def error_class
+        headers&.dig("X-Error-Class")
+      end
+
+      def error_message
+        headers&.dig("X-Error-Message")
+      end
+
+      def error_backtrace
+        headers&.dig("X-Error-Backtrace")
+      end
+
+      # @return [Array<String>] the backtrace frames, which travel as a single header line
+      def error_backtrace_lines
+        error_backtrace.to_s.split(::Cosmo::Job::Failure::BACKTRACE_SEPARATOR)
+      end
+
+      def error?
+        !error_class.to_s.empty? || !error_message.to_s.empty?
+      end
+
       def timestamp
         headers&.dig("Nats-Time-Stamp")
       end
+
+      # @return [Time, nil] when the message was stored in its stream, parsed from +Nats-Time-Stamp+
+      def stored_at
+        Time.iso8601(timestamp) if timestamp
+      rescue ::ArgumentError
+        nil
+      end
     end
   end
 end