cosmonats 0.4.0 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f94d9b1e192b098e1bcb3ce77998d7b0ed9aca359af41fefe2a572624fa6b91
-  data.tar.gz: 12bba3015a4beb335efae8dfe5fc178a6c467d203eaf61f922bf1b3091b67ce6
+  metadata.gz: 9167e7ccc35b55db0664e863eb04b007614dfc78efb7f203706b18e58ed2593f
+  data.tar.gz: 3654c4f5681440e79498b04328cd6565e646f6e9185c4705ca82aef517bf3342
 SHA512:
-  metadata.gz: e24c844b4f17aa7eaffceebdd6b847858855fc0b5526b5537832893fd144e71f427ae352700adff3c5b39ed5cd04c89bc84007d01548ff97ba701a45e8c836b9
-  data.tar.gz: d1a7d5e0d45c5f9b03388259b45a5a6ce659dd39378a0f13e8f31cf36d7f969a332076cada74b564f2fd7d504c646df0715778679d0e67743a5f0ef08398e7c9
+  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/api/stream.rb

@@ -45,21 +45,24 @@ module Cosmo
 
       def retries
         client.list_consumers(name).sum { _1["num_redelivered"].to_i }
+      rescue NATS::Error
+        0
       end
 
       def each
         return if total.zero?
 
-        state = info[:state]
-        current = @offset || state.first_seq.to_i
-        last = state.last_seq.to_i
+        candidates = {}
+        current, last, subjects = scan_range
 
         loop do
           break if current > last
 
-          job = message(current)
-          current += 1
-          next unless job
+          subject, job = next_candidate(subjects, candidates, current)
+          break unless job
+
+          candidates.delete(subject)
+          current = job.seq.to_i + 1
 
           yield job
         end
@@ -120,6 +123,33 @@ module Cosmo
 
       private
 
+      def scan_range
+        data = info
+        state = data[:state]
+        current = @offset || state.first_seq.to_i
+        subjects = Array(data[:config].subjects).reject { _1.start_with?(Cron::Entry::SUBJECT_PREFIX) }
+        [current, state.last_seq.to_i, subjects]
+      end
+
+      # Lowest-seq message at or after current across all job subject filters,
+      # caching each subject's next candidate so it isn't re-queried every step.
+      def next_candidate(subjects, candidates, current)
+        subjects.each do |subject|
+          next if candidates.key?(subject)
+
+          candidates[subject] = next_message(subject, current)
+        end
+
+        candidates.compact.min_by { |_, msg| msg.seq.to_i }
+      end
+
+      # Jump straight to the next message on the subject after seq, skipping any acked/deleted gaps
+      def next_message(subject, seq)
+        Job.new(name, client.get_message(name, next: true, seq: seq, subject: subject, direct: true))
+      rescue NATS::JetStream::Error::NotFound
+        nil
+      end
+
       def client
         self.class.client
       end

data/lib/cosmo/cli.rb

@@ -124,7 +124,7 @@ module Cosmo
             class_name = entry.delete(:class)
             API::Cron.instance.upsert!(**entry, name: name, class_name: class_name)
             sum + 1
-          end
+          end.to_i
 
           puts "Cron sync complete: #{schedules} schedule(s) registered" unless schedules.zero?
           puts "Cosmo streams#{" and cron schedules" unless schedules.zero?} set up successfully."

data/lib/cosmo/client.rb

@@ -69,6 +69,8 @@ module Cosmo
       return [] if data.nil? || data["streams"].nil?
 
       data["streams"]
+    rescue NATS::Error
+      []
     end
 
     def pause_stream(name)
@@ -101,8 +103,8 @@ module Cosmo
       js.consumer_info(stream_name, consumer_name)
     end
 
-    def get_message(name, **options)
-      js.get_msg(name, **options)
+    def get_message(stream_name, **options)
+      js.get_msg(stream_name, **options)
     end
 
     def delete_message(name, seq)

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

@@ -79,13 +79,10 @@ module Cosmo
           sw = stopwatch
           Logger.with(jid: data[:jid])
           Logger.info "start"
-          instance = worker_class.new
-          instance.jid = data[:jid]
-          if duration
-            Timeout.timeout(duration) { instance.perform(*data[:args]) }
-          else
-            instance.perform(*data[:args])
-          end
+
+          instance = worker_class.new.tap { |w| w.jid = data[:jid] }
+          perform_job(instance, data: data, message: message, duration: duration)
+
           message.ack
           Logger.with(elapsed: sw.elapsed_seconds) { Logger.info "done" }
           true
@@ -110,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])
@@ -118,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
@@ -190,6 +187,21 @@ module Cosmo
           API::Counter.instance.with(&block)
         end
       end
+
+      # @param job_instance [Cosmo::Job]
+      # @param data [Hash]
+      # @param message [NATS::Msg]
+      # @param duration [Float, nil]
+      #
+      # rubocop:disable Lint/UnusedMethodArgument
+      def perform_job(job_instance, data:, message:, duration: nil)
+        if duration
+          Timeout.timeout(duration) { job_instance.perform(*data[:args]) }
+        else
+          job_instance.perform(*data[:args])
+        end
+      end
+      # rubocop:enable Lint/UnusedMethodArgument
     end
   end
 end

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/sentry/auto.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "cosmo/job/processor"
+require "cosmo/sentry/job_processor_middleware"
+
+Cosmo::Job::Processor.prepend Cosmo::Sentry::JobProcessorMiddleware

data/lib/cosmo/sentry/job_processor_middleware.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+# rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+module Cosmo
+  module Sentry
+    module JobProcessorMiddleware
+      NAME_PREFIX = "Cosmonats"
+      OP_NAME = "queue.cosmonats"
+      SPAN_ORIGIN = "auto.queue.cosmonats"
+      STATUS_OK = 200
+      STATUS_FAIL = 500
+
+      # @param job_instance [Cosmo::Job]
+      # @param data [Hash]
+      # @param message [NATS::Msg]
+      # @param duration [Float, nil]
+      def perform_job(job_instance, data:, message:, duration: nil)
+        unless ::Sentry.initialized?
+          super
+          return
+        end
+
+        scope = ::Sentry.get_current_scope
+        transaction_name = "#{NAME_PREFIX}/#{job_instance.class.name}"
+        scope.set_transaction_name(transaction_name, source: :task)
+
+        transaction = ::Sentry.start_transaction(
+          name: scope.transaction_name,
+          source: scope.transaction_source,
+          op: OP_NAME,
+          origin: SPAN_ORIGIN
+        )
+        transaction&.set_data("messaging.message.id", data[:jid])
+        transaction&.set_data("messaging.destination.name", "#{message.metadata.stream}:#{message.subject}")
+        transaction&.set_data("messaging.message.retry.count", data[:retry] || 0)
+
+        begin
+          super
+
+          transaction&.set_http_status(STATUS_OK)
+          transaction&.finish
+        rescue StandardError => e
+          ::Sentry.capture_exception(
+            e,
+            contexts: {
+              cosmonats: data.merge(
+                nats_stream: message.metadata.stream,
+                nats_subject: message.subject,
+                timeout_duration: duration
+              )
+            },
+            hint: {
+              background: true,
+              integration: "cosmonats"
+            }
+          )
+          transaction&.set_http_status(STATUS_FAIL)
+          transaction&.finish
+
+          raise e
+        end
+      end
+    end
+  end
+end
+# rubocop:enable Metrics/MethodLength, Metrics/AbcSize

data/lib/cosmo/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Cosmo
-  VERSION = "0.4.0"
+  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); }
@@ -509,6 +516,23 @@ details code { display: block; max-width: 400px; white-space: pre-wrap; }
 .htmx-request .htmx-indicator,
 .htmx-request.htmx-indicator   { opacity: 1; }
 
+#global-spinner {
+  position: fixed;
+  top: var(--space-2x);
+  right: var(--space-2x);
+  width: 24px;
+  height: 24px;
+  border: 3px solid var(--color-border);
+  border-top-color: var(--color-primary);
+  border-radius: 50%;
+  animation: spin 0.6s linear infinite;
+  z-index: 100;
+}
+
+@keyframes spin {
+  to { transform: rotate(360deg); }
+}
+
 /* ── Responsive ────────────────────────────────────────────────────────── */
 @media (max-width: 768px) {
   .nav            { flex-wrap: wrap; }

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

@@ -5,6 +5,7 @@
               hx-target="#content"
               hx-swap="innerHTML"
               hx-push-url="true"
+              hx-indicator="#global-spinner"
               class="btn <%= "btn-primary" if @stream_name.to_s == stream_name.to_s %>">
         <%= h(stream_name) %>
       </button>
@@ -63,20 +64,37 @@
   <% 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 -%>
       <span class="btn btn-disabled">Next &#x2192;</span>

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

@@ -19,7 +19,8 @@
       <a href="<%= url_for('/jobs/busy') %>"
          hx-get="<%= url_for('/jobs/busy') %>"
          hx-target="#content"
-         hx-push-url="true">&#x23F3; Busy</a>
+         hx-push-url="true"
+         hx-indicator="#global-spinner">&#x23F3; Busy</a>
     </p>
   </article>
   <article class="stat-card">
@@ -29,6 +30,7 @@
          hx-get="<%= url_for('/jobs/enqueued') %>"
          hx-target="#content"
          hx-push-url="true"
+         hx-indicator="#global-spinner"
          class="<%= 'active' if referrer?('/jobs/enqueued') %>">&#x1F4EC; Enqueued</a>
     </p>
   </article>
@@ -39,6 +41,7 @@
          hx-get="<%= url_for('/jobs/scheduled') %>"
          hx-target="#content"
          hx-push-url="true"
+         hx-indicator="#global-spinner"
          class="<%= 'active' if referrer?('/jobs/scheduled') %>">&#x23F0; Scheduled</a>
     </p>
   </article>
@@ -49,6 +52,7 @@
          hx-get="<%= url_for('/jobs/dead') %>"
          hx-target="#content"
          hx-push-url="true"
+         hx-indicator="#global-spinner"
          class="<%= 'active' if referrer?('/jobs/dead') %>">&#x1F480; Dead</a>
     </p>
   </article>

data/lib/cosmo/web/views/layout.erb

@@ -28,6 +28,7 @@
   </header>
   <main class="container">
     <%= content_for :view %>
+    <div id="global-spinner" class="htmx-indicator" aria-hidden="true"></div>
   </main>
 </body>
 </html>

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

data/sig/cosmo/api/stream.rbs

@@ -44,6 +44,12 @@ module Cosmo
 
       private
 
+      def scan_range: () -> [::Integer, ::Integer, Array[::String]]
+
+      def next_candidate: (Array[::String] subjects, Hash[::String, Job?] candidates, ::Integer current) -> [::String, Job]?
+
+      def next_message: (::String subject, ::Integer seq) -> Job?
+
       def client: () -> Client
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cosmonats
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.2
 platform: ruby
 authors:
 - Dmitry Vorotilin
@@ -88,6 +88,8 @@ files:
 - lib/cosmo/processor.rb
 - lib/cosmo/publisher.rb
 - lib/cosmo/railtie.rb
+- lib/cosmo/sentry/auto.rb
+- lib/cosmo/sentry/job_processor_middleware.rb
 - lib/cosmo/stream.rb
 - lib/cosmo/stream/data.rb
 - lib/cosmo/stream/message.rb
@@ -197,7 +199,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.12
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Lightweight background and stream processing
 test_files: []