cosmonats 0.4.1 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0bb0db4ef3d9dac8fe723ab7440ccc6b2fcd3d5c746efd2cb3dd4c5a28c2d6f6
-  data.tar.gz: 06b65ca804dda9a66bc239feefb54cb9bdad2c23d63a0e514c97c33f602616f7
+  metadata.gz: 9167e7ccc35b55db0664e863eb04b007614dfc78efb7f203706b18e58ed2593f
+  data.tar.gz: 3654c4f5681440e79498b04328cd6565e646f6e9185c4705ca82aef517bf3342
 SHA512:
-  metadata.gz: 0525004e2df9b1d37488e698a83ce5decf8681a673e6d66e720dc74788c78f7ebd16abd63510f830a62a8efbdad09bcc06278747e8423bce892bcaa9663f43ad
-  data.tar.gz: b1b522586095c52f72631c80f1e6d8f22fc8853450515ecf49c91469bed0cd2269273cb0a2de95f46fd8c6e18d9a71e3ee7b5c9fad25cc60bf16cd2a62d2c1c2
+  metadata.gz: b92b7cce247a690370cfcf3f0941a30c63e35678b51228f784046ec9e04922d7632279d6f0d8f20641b168a06c5aa6f5198881b2060b65b4bad1e0abbffbf8c7
+  data.tar.gz: d005e21357274d3ef2a53601a0b7c9647d3fedef049a3ef64064b59ed1c3ee6f9c160c8304d05b5886da70c5b5227a2dabebfe3dce4e328ae62ad7bd37c4e2de

data/README.md

@@ -71,6 +71,13 @@ bundle exec cosmo -C config/cosmo.yml -c 20 streams # Streams only
   - [Streams](#streams)
   - [Configuration](#configuration)
 - [Advanced Usage](#-advanced-usage)
+  - [Cron](#cron)
+  - [Priority Queues](#priority-queues)
+  - [Concurrency Limiting](#concurrency-limiting)
+  - [Custom Serializers](#custom-serializers)
+  - [Error Handling](#error-handling)
+  - [Testing](#testing)
+  - [Integrations](#integrations)
 - [CLI Reference](#-cli-reference)
 - [Deployment](#-deployment)
 - [Monitoring](#-monitoring)
@@ -138,6 +145,8 @@ nothing else to run.
 - **Automatic retries** — exponential backoff, configurable attempts
 - **Dead letter queue** — capture permanently failed jobs
 - **Job uniqueness** — prevent duplicate execution
+- **Concurrency limits** — cap simultaneous executions per class or per key
+- **Cron scheduling** — recurring jobs manageable live from the web UI
 
 ### 🌊 Stream Processing
 - **Real-time event streams** — process continuous data feeds
@@ -145,6 +154,7 @@ nothing else to run.
 - **Message replay** — reprocess from any point in time
 - **Consumer groups** — load-balanced across workers
 - **Custom serialization** — JSON, MessagePack, Protobuf
+- **Pause / resume** — stop and restart a stream's processing without losing its position
 
 
 ## 📦 Installation
@@ -407,7 +417,48 @@ export COSMO_STREAMS_FETCH_TIMEOUT=0.1
 
 ## 🔧 Advanced Usage
 
-**Priority Queues:**
+### 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.
+
+Declare schedules right in `config/cosmo.yml`:
+
+```yaml
+setup:
+  cron:
+    daily_report:
+      class: ReportJob
+      schedule: "@daily"        # @-shortcuts are passed straight through to NATS
+      stream: default
+    weekday_digest:
+      class: ReportJob
+      schedule: "0 9 * * 1-5"   # 6-field NATS cron (seconds first); 5-field UNIX cron is auto-normalized
+      stream: default
+      args: ["daily"]
+      timezone: America/New_York # optional, cron expressions only
+```
+
+`cosmo -C config/cosmo.yml -S` syncs it — whatever's in the file is exactly what ends up scheduled in NATS, same as streams.
+
+Prefer to manage schedules at runtime instead? The same operations are available from Ruby:
+
+```ruby
+Cosmo::API::Cron.instance.upsert!(
+  class_name: "ReportJob", stream: "default", schedule: "0 9 * * 1-5",
+  args: ["daily"], timezone: "America/New_York", name: "weekday_report"
+)
+
+Cosmo::API::Cron.instance.all                                    # every schedule currently deployed
+Cosmo::API::Cron.instance.run_now!("cosmo.cron.default.report_job.weekday_report")  # bypass the timer
+Cosmo::API::Cron.instance.delete!("cosmo.cron.default.report_job.weekday_report")   # stop future firings
+```
+
+### Priority Queues
+
 ```ruby
 class UrgentJob
   include Cosmo::Job
@@ -415,7 +466,30 @@ class UrgentJob
 end
 ```
 
-**Custom Serializers:**
+### Concurrency Limiting
+
+```ruby
+class ThirdPartyApiJob
+  include Cosmo::Job
+  # At most 3 instances of this job run at once, cluster-wide.
+  # Jobs that lose the race are NAK'd with a delay equal to `duration`
+  # so they aren't redelivered until a slot is guaranteed free.
+  options limit: { duration: 30, concurrency: 3 }
+end
+
+class PerAccountSyncJob
+  include Cosmo::Job
+  # Scope the cap per key instead of class-wide — e.g. one concurrent sync per account.
+  options limit: { duration: 30, concurrency: { to: 1, key: ->(account_id) { account_id } } }
+
+  def perform(account_id)
+    Account.find(account_id).sync!
+  end
+end
+```
+
+### Custom Serializers
+
 ```ruby
 module MessagePackSerializer
   def self.serialize(data) = MessagePack.pack(data)
@@ -428,7 +502,8 @@ class FastStream
 end
 ```
 
-**Error Handling:**
+### Error Handling
+
 ```ruby
 class ResilientJob
   include Cosmo::Job
@@ -446,7 +521,8 @@ class ResilientJob
 end
 ```
 
-**Testing:**
+### Testing
+
 ```ruby
 # Synchronous — no NATS needed
 SendEmailJob.perform_sync(123, "test")
@@ -457,6 +533,40 @@ assert_kind_of String, jid
 ```
 
 
+### Integrations
+
+**ActiveJob:**
+```ruby
+# config/application.rb
+config.active_job.queue_adapter = :cosmonats
+```
+The ActiveJob queue name maps directly to a Cosmo stream. Use `cosmo_options` for anything
+Cosmo-specific — retries, DLQ behavior, or overriding the target stream:
+```ruby
+class ReportJob < ApplicationJob
+  cosmo_options retry: 5, dead: false, stream: :critical
+
+  def perform(report_id)
+    Report.find(report_id).generate!
+  end
+end
+```
+Inside a Rails app this is wired up automatically by the bundled Railtie — it registers the
+adapter and loads `config/cosmo.yml` if present. Outside Rails:
+```ruby
+require "cosmo/active_job"
+ActiveJob::Base.queue_adapter = Cosmo::ActiveJobAdapter::Adapter.new
+```
+
+**Sentry:**
+```ruby
+require "cosmo/sentry/auto"
+```
+Wraps every job execution in a Sentry transaction (`queue.cosmonats`) and captures unhandled
+exceptions with the job's id, stream, subject, and retry count attached as context — no other
+setup beyond having `sentry-ruby` initialized.
+
+
 ## 🖥️ CLI Reference
 
 ```bash
@@ -542,6 +652,12 @@ sudo systemctl enable cosmo && sudo systemctl start cosmo
 
 ## 📊 Monitoring
 
+**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
+- **Streams** — per-stream state (messages, bytes, consumers) with pause/resume
+- **Crons** — every schedule deployed in NATS, with run-now and delete
+- Summary counters (processed / failed / busy / enqueued / retries / scheduled / dead) backed by a NATS KV counter, no separate metrics store needed
+
 **Structured logs:**
 ```
 2026-01-23T10:15:30.123Z INFO pid=12345 tid=abc jid=def: start

data/lib/cosmo/api/kv.rb

@@ -8,39 +8,15 @@ module Cosmo
       def initialize(name, options = nil)
         @name = name
         @options = Hash(options)
-        @kv = Client.instance.kv(@name, **@options)
+        @kv = client.kv(@name, **@options)
       end
 
-      def set(key, value, ttl: nil) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      def set(key, value, ttl: nil)
         return kv.put(key, value.to_s) unless ttl
 
-        # Pass ttl: (seconds) to set a per-message expiry.
+        # Pass ttl: (seconds) to set per-message expiry.
         # Raises `NATS::KeyValue::KeyWrongLastSequenceError` when the key is live.
-        begin
-          value = value.to_s
-          put = lambda do |last_seq:|
-            headers = { "Nats-Expected-Last-Subject-Sequence" => last_seq.to_s, "Nats-TTL" => "#{ttl.to_i}s" }
-            Client.instance.js.publish("$KV.#{@name}.#{key}", value, header: headers)
-          rescue NATS::JetStream::Error::APIError => e
-            raise NATS::KeyValue::KeyWrongLastSequenceError, e.description if e.err_code == 10_071
-
-            raise
-          end
-
-          put.call(last_seq: 0)
-          kv.send(:_get, key) # fetch the created entry to get its revision
-        rescue NATS::KeyValue::KeyWrongLastSequenceError
-          # `kv.get` converts KeyDeletedError → KeyNotFoundError, hiding tombstone info.
-          # Use private _get instead — it raises KeyDeletedError with the entry's revision
-          begin
-            kv.send(:_get, key)
-          rescue NATS::KeyValue::KeyDeletedError => e
-            put.call(last_seq: e.entry.revision)
-            return kv.send(:_get, key)
-          end
-
-          raise
-        end
+        publish_cas(key, value.to_s, ttl, last_seq: 0).seq
       end
 
       def get(key)
@@ -49,6 +25,9 @@ module Cosmo
         # nop
       end
 
+      # Writes a KV-Operation tombstone. On a ttl-bearing bucket this leaves the
+      # subject occupied, so a subsequent #set(ttl:) CAS with last_seq: 0 will
+      # keep failing -- use #erase on those buckets instead.
       def delete(key)
         kv.delete(key)
       end
@@ -66,12 +45,21 @@ module Cosmo
         results
       end
 
+      # Writes a KV-Operation tombstone (same issue as #delete on ttl buckets).
       def purge(key)
         kv.purge(key)
       end
 
+      # Removes +key+ leaving no trace at all -- unlike #delete/#purge, which
+      # write a KV-Operation tombstone message. Mirrors how per-message
+      # Nats-TTL expiry removes a key, so callers never have to distinguish
+      # "deleted" from "TTL-expired" on read.
+      def erase(key)
+        client.purge("KV_#{@name}", "$KV.#{@name}.#{key}")
+      end
+
       def clean
-        Client.instance.purge("KV_#{@name}", ">")
+        client.purge("KV_#{@name}", ">")
       end
 
       def count
@@ -80,6 +68,26 @@ module Cosmo
         0
       end
       alias size count
+
+      private
+
+      # CAS = Compare-And-Swap: publish +value+ with a per-message Nats-TTL,
+      # but only if the subject's current last sequence matches +last_seq+
+      # (sent as the Nats-Expected-Last-Subject-Sequence header). Raises
+      # NATS::KeyValue::KeyWrongLastSequenceError if it doesn't match --
+      # e.g. last_seq: 0 means "only publish if nothing exists here yet".
+      def publish_cas(key, value, ttl, last_seq:)
+        headers = { "Nats-Expected-Last-Subject-Sequence" => last_seq.to_s, "Nats-TTL" => "#{ttl.to_i}s" }
+        client.js.publish("$KV.#{@name}.#{key}", value, header: headers)
+      rescue NATS::JetStream::Error::APIError => e
+        raise NATS::KeyValue::KeyWrongLastSequenceError, e.description if e.err_code == 10_071
+
+        raise
+      end
+
+      def client
+        Client.instance
+      end
     end
   end
 end

data/lib/cosmo/job/limit.rb

@@ -9,8 +9,9 @@ module Cosmo
     #
     # Acquiring a slot is a single atomic `set` (CAS with last-revision=0).
     # Only one worker can win a given slot; losers try the next number.
-    # When a job finishes the slot is deleted; if the worker crashes NATS
-    # expires it automatically via the per-message Nats-TTL header.
+    # When a job finishes, the slot is erased; if the worker crashes, NATS
+    # expires it automatically via the per-message Nats-TTL header. Both
+    # paths leave the slot equally empty -- no tombstone, no delete marker.
     class Limit
       BUCKET = "cosmo_jobs_limits"
 
@@ -40,11 +41,14 @@ module Cosmo
         nil # all slots occupied
       end
 
-      # Release a previously acquired slot.
+      # Release a previously acquired slot. Erases the slot entirely (no
+      # tombstone left behind) so a released slot looks identical to one
+      # reclaimed by Nats-TTL expiry -- callers never have to special-case a
+      # delete marker.
       def release(slot)
-        @kv.delete(slot)
+        @kv.erase(slot)
       rescue NATS::Error
-        # best effort — slot TTL will reclaim it if delete fails
+        # best effort — slot TTL will reclaim it if erase fails
       end
     end
   end

data/lib/cosmo/job/processor.rb

@@ -107,7 +107,7 @@ module Cosmo
 
       # Tries to acquire a concurrency slot for the job.
       # Returns the slot key (String) on success, or false if all slots are
-      # taken (message is NAK'd with a delay equal to +duration+ before returning).
+      # taken (a message is NAK'd with a delay of +retry_in+ before returning
       def acquire_concurrency_slot(worker_class, message, data)
         options = worker_class.concurrency_options
         key = worker_class.concurrency_key(data[:args])
@@ -115,7 +115,7 @@ module Cosmo
         slot = Limit.instance.acquire(key, jid: data[:jid], limit: options[:limit], duration: options[:duration])
         return slot if slot
 
-        message.nak(delay: options[:duration] * Config::NANO)
+        message.nak(delay: options[:retry_in] * Config::NANO)
         Logger.debug "concurrency limit reached for #{data[:class]}, re-queueing back #{data[:jid]}"
         false
       rescue NATS::Error => e

data/lib/cosmo/job.rb

@@ -19,14 +19,19 @@ module Cosmo
       #   limit: { duration: 30 }
       #   limit: { duration: 30, concurrency: 3 }
       #   limit: { duration: 30, concurrency: { to: 3, key: ->(id) { id } } }
+      #   limit: { duration: 30, concurrency: 3, retry_in: 5 }
       #
       # @option config [Integer] :"limit[:duration]"    hard execution timeout in seconds. The job thread is
       #   killed after this many seconds and counts as a failed attempt (retried with exponential backoff,
       #   moved to DLQ after retries exhausted).
       # @option config [Integer, Hash] :"limit[:concurrency]"  caps how many instances run at once across all
-      #   workers. Jobs that cannot acquire a slot are NAK'd with a delay equal to +duration+ so they are not
-      #   re-delivered until the slot is guaranteed free. Requires +duration+.
+      #   workers. Jobs that cannot acquire a slot are NAK'd (see +retry_in+) so they are not re-delivered until
+      #   the slot is likely free. Requires +duration+.
       #   Pass an Integer for a class-wide cap, or <tt>{ to: N, key: ->(args) {} }</tt> to scope per key.
+      # @option config [Integer] :"limit[:retry_in]"    seconds to wait before NATS redelivers a job that was
+      #   NAK'd for lack of a concurrency slot (default: half of +duration+). Counts against the same delivery
+      #   counter as any other retry -- a job stuck behind the concurrency limit for enough consecutive
+      #   attempts is dropped/DLQ'd exactly like one that keeps failing outright.
       def options(**config)
         if config[:limit] && config.dig(:limit, :concurrency) && !config.dig(:limit, :duration).to_i.positive?
           raise ArgumentError, "limit: duration is required when concurrency is set"
@@ -41,15 +46,17 @@ module Cosmo
       end
 
       # Returns a normalized concurrency config hash, or +nil+ when not configured.
-      # Always contains +:limit+, +:key+, and +:duration+.
+      # Always contains +:limit+, +:key+, +:duration+, and +:retry_in+.
       def concurrency_options
         value = default_options.dig(:limit, :concurrency)
-        duration = default_options.dig(:limit, :duration).to_i
         return unless value
 
+        duration = default_options.dig(:limit, :duration).to_i
+        retry_in = default_options.dig(:limit, :retry_in)&.to_i || (duration / 2)
+
         case value
-        when Integer then { limit: value, key: nil, duration: duration }
-        when Hash    then { limit: value.fetch(:to), key: value[:key], duration: duration }
+        when Integer then { limit: value, key: nil, duration: duration, retry_in: retry_in }
+        when Hash    then { limit: value.fetch(:to), key: value[:key], duration: duration, retry_in: retry_in }
         end
       end
 

data/lib/cosmo/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Cosmo
-  VERSION = "0.4.1"
+  VERSION = "0.4.2"
 end

data/lib/cosmo/web/assets/app.css

@@ -489,6 +489,13 @@ time {
   cursor: default;
   pointer-events: none;
 }
+.pagination .btn-primary.btn-disabled {
+  opacity: 1;
+}
+.pagination-gap {
+  color: var(--color-text-light);
+  padding: 0 var(--space-1-2);
+}
 
 /* ── Actions ───────────────────────────────────────────────────────────── */
 .actions-form { display: flex; flex-direction: column; gap: var(--space-1-2); }

data/lib/cosmo/web/helpers/application.rb

@@ -67,6 +67,21 @@ module Cosmo
           Rack::Utils.escape(value.to_s)
         end
 
+        # Build the list of page numbers to render around the current page, with
+        # `:gap` markers where numbers are skipped.
+        #   pages(5, 20) # => [1, :gap, 3, 4, 5, 6, 7, :gap, 20]
+        def pages(page, total_pages, window: 2)
+          return [] if total_pages <= 1
+
+          previous = nil
+          candidates = ([1, total_pages] + ((page - window)..(page + window)).to_a).grep(1..total_pages).uniq.sort
+          candidates.each_with_object([]) do |p, result|
+            pagination_fill_gap(result, previous, p)
+            result << p
+            previous = p
+          end
+        end
+
         def current_page?(path)
           request_path = @request.path_info
           request_path = "/" if request_path.empty?
@@ -85,6 +100,15 @@ module Cosmo
           referrer_path = "/" if referrer_path.empty?
           referrer_path == path
         end
+
+        private
+
+        def pagination_fill_gap(result, previous, page)
+          return unless previous
+
+          result << (previous + 1) if page - previous == 2
+          result << :gap if page - previous > 2
+        end
       end
     end
   end

data/lib/cosmo/web/views/jobs/_enqueued.erb

@@ -64,21 +64,36 @@
   <% if @total_pages > 1 -%>
   <div class="pagination">
     <% if @page > 1 -%>
-      <a hx-get="<%= url_for('/jobs/_enqueued', stream_name: @stream_name, page: @page - 1, limit: @limit) %>"
+      <a hx-get="<%= url_for('/jobs/enqueued', stream_name: @stream_name, page: @page - 1, limit: @limit) %>"
          hx-target="#enqueued-poller"
          hx-swap="outerHTML"
+         hx-push-url="true"
          hx-indicator="#global-spinner"
          class="btn">&#x2190; Prev</a>
     <% else -%>
       <span class="btn btn-disabled">&#x2190; Prev</span>
     <% end -%>
 
-    <span class="text-muted">Page <%= @page %> of <%= @total_pages %></span>
+    <% pages(@page, @total_pages).each do |p| -%>
+      <% if p == :gap -%>
+        <span class="pagination-gap">&hellip;</span>
+      <% elsif p == @page -%>
+        <span class="btn btn-primary btn-disabled"><%= p %></span>
+      <% else -%>
+        <a hx-get="<%= url_for('/jobs/enqueued', stream_name: @stream_name, page: p, limit: @limit) %>"
+           hx-target="#enqueued-poller"
+           hx-swap="outerHTML"
+           hx-push-url="true"
+           hx-indicator="#global-spinner"
+           class="btn"><%= p %></a>
+      <% end -%>
+    <% end -%>
 
     <% if @page < @total_pages -%>
-      <a hx-get="<%= url_for('/jobs/_enqueued', stream_name: @stream_name, page: @page + 1, limit: @limit) %>"
+      <a hx-get="<%= url_for('/jobs/enqueued', stream_name: @stream_name, page: @page + 1, limit: @limit) %>"
          hx-target="#enqueued-poller"
          hx-swap="outerHTML"
+         hx-push-url="true"
          hx-indicator="#global-spinner"
          class="btn">Next &#x2192;</a>
     <% else -%>

data/sig/cosmo/api/kv.rbs

@@ -19,10 +19,18 @@ module Cosmo
 
       def purge: (::String | ::Integer key) -> untyped
 
+      def erase: (::String | ::Integer key) -> ::Integer?
+
       def clean: () -> untyped
 
       def count: () -> ::Integer
       alias size count
+
+      private
+
+      def publish_cas: (::String | ::Integer key, ::String value, ::Integer? ttl, last_seq: ::Integer) -> untyped
+
+      def client: () -> Client
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cosmonats
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.4.2
 platform: ruby
 authors:
 - Dmitry Vorotilin