cosmonats 0.3.0 → 0.4.1

data/lib/cosmo/active_job/options.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Cosmo
+  module ActiveJobAdapter
+    # Adds +cosmo_options+ to ActiveJob classes.
+    #
+    #   class MyJob < ApplicationJob
+    #     cosmo_options retry: 5, dead: false
+    #
+    #     def perform(user_id)
+    #       # ...
+    #     end
+    #   end
+    #
+    # Options mirror those accepted by +Cosmo::Job+:
+    #   retry:  [Integer]  Number of retries before giving up (default: 3)
+    #   dead:   [Boolean]  Move to DLQ when retries exhausted? (default: true)
+    #   stream: [Symbol]   Override the NATS stream (default: derived from queue_name)
+    module Options
+      VALID_OPTIONS = %i[retry dead stream].freeze
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # Set Cosmo-specific options for this job class.
+        # Merges with any options inherited from a superclass.
+        # Raises +ArgumentError+ for unknown keys.
+        def cosmo_options(**opts)
+          unknown = opts.keys - Cosmo::ActiveJobAdapter::Options::VALID_OPTIONS
+          raise ::ArgumentError, "Unknown cosmo_options key(s): #{unknown.join(", ")}" if unknown.any?
+
+          @cosmo_options = get_cosmo_options.merge(opts)
+        end
+
+        # Returns the resolved options, walking up the inheritance chain.
+        def get_cosmo_options # rubocop:disable Naming/AccessorMethodName
+          if @cosmo_options
+            @cosmo_options.dup
+          elsif superclass.respond_to?(:get_cosmo_options)
+            superclass.get_cosmo_options
+          else
+            {}
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cosmo/active_job.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "cosmo/active_job/options"
+require "cosmo/active_job/executor"
+require "cosmo/active_job/adapter"
+
+module Cosmo
+  # ActiveJob integration for Cosmonats.
+  #
+  # In a Rails app the Railtie (loaded via cosmonats) handles everything.
+  # For standalone use:
+  #
+  #   require "cosmo/active_job"
+  #   ActiveJob::Base.queue_adapter = Cosmo::ActiveJobAdapter::Adapter.new
+  module ActiveJobAdapter
+  end
+end
+
+# Register the adapter under the conventional ActiveJob name so that
+# `config.active_job.queue_adapter = :cosmonats` resolves automatically.
+if defined?(ActiveJob)
+  ActiveJob::QueueAdapters::CosmonatsAdapter = Cosmo::ActiveJobAdapter::Adapter
+
+  if defined?(ActiveSupport)
+    ActiveSupport.on_load(:active_job) { include Cosmo::ActiveJobAdapter::Options }
+  else
+    ActiveJob::Base.include(Cosmo::ActiveJobAdapter::Options)
+  end
+end

data/lib/cosmo/api/busy.rb

@@ -7,7 +7,7 @@ module Cosmo
     class Busy
       TTL = 70
       HEARTBEAT = 30
-      BUCKET = "cosmostats"
+      BUCKET = "cosmo_jobs_busy"
 
       def self.instance
         @instance ||= new
@@ -40,7 +40,7 @@ module Cosmo
       end
 
       def list(limit: 25)
-        @kv.keys(limit:).filter_map { Utils::Json.parse(@kv.get(_1)) }.map { _1.merge(data: Utils::Json.parse(_1[:data])) }
+        @kv.keys(limit:).filter_map { Utils::Json.parse(@kv.get(_1)&.value) }.map { _1.merge(data: Utils::Json.parse(_1[:data])) }
       end
 
       def size

data/lib/cosmo/api/counter.rb

@@ -3,7 +3,7 @@
 module Cosmo
   module API
     class Counter
-      STREAM_NAME = "cosmostats"
+      STREAM_NAME = "_cosmostats"
 
       def self.instance
         @instance ||= new("jobs")
@@ -38,7 +38,7 @@ module Cosmo
       def get(key)
         raw = client.get_message(STREAM_NAME, direct: true, subject: subject(key))
         Utils::Json.parse(raw.data, default: { "val" => 0 })[:val].to_i
-      rescue NATS::JetStream::Error::NotFound, NATS::JetStream::Error::ServiceUnavailable
+      rescue NATS::JetStream::Error::NotFound, NATS::JetStream::Error::ServiceUnavailable, NATS::IO::Timeout
         0
       end
 

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

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "json"
+
+module Cosmo
+  module API
+    class Cron
+      # Value object representing a single cron schedule entry.
+      # Each schedule maps one job class (and optional args) to a NATS 2.14 message schedule.
+      #
+      # NATS 2.14 message scheduling uses a 6-field cron format:
+      #   second minute hour day-of-month month day-of-week
+      #
+      # @-shortcuts (@daily, @every 5m, @at ...) are passed through unchanged —
+      # the server understands them natively. Plain 5-field UNIX cron expressions
+      # need a seconds field prepended to become valid 6-field expressions.
+      #
+      #   "0 9 * * 1-5"  →  "0 0 9 * * 1-5"   (at 09:00 on weekdays)
+      #   "@daily"        →  "@daily"            (unchanged)
+      class Entry
+        SUBJECT_PREFIX = "cosmo.cron"
+
+        def self.normalize_expression(expr)
+          str = expr.to_s.strip
+          return str if str.start_with?("@")
+
+          fields = str.split
+          fields.size == 5 ? "0 #{str}" : str
+        end
+
+        attr_reader :class_name, :stream, :expression, :args, :timezone, :name
+
+        # @param class_name [String] Fully-qualified Ruby class name (e.g. "ReportJob")
+        # @param stream     [String] Target job stream name (e.g. "default")
+        # @param expression [String] NATS schedule expression (@daily, @every 5m, "0 0 9 * * 1-5", etc.)
+        # @param args       [Array]  Arguments passed to the job's +perform+ method
+        # @param timezone   [String, nil] IANA timezone name (e.g. "America/New_York"). Cron expressions only.
+        # @param name       [String, Symbol, nil] Disambiguates multiple schedules on the same class.
+        def initialize(class_name:, stream:, expression:, args: [], timezone: nil, name: nil)
+          @class_name = class_name.to_s
+          @stream     = stream.to_s
+          @expression = self.class.normalize_expression(expression)
+          @args       = Array(args)
+          @timezone   = timezone
+          @name       = name&.to_s
+        end
+
+        # Subject where the schedule message lives in NATS (one per unique schedule).
+        # e.g. "cosmo.cron.default.report_job" or "cosmo.cron.default.report_job.monthly"
+        def schedule_subject
+          parts = [SUBJECT_PREFIX, @stream, job_name]
+          parts << @name if @name
+          parts.join(".")
+        end
+
+        # Subject where NATS fires the generated job message.
+        # Must be a subject covered by the same stream.
+        def target_subject
+          "jobs.#{@stream}.#{job_name}"
+        end
+
+        def job_name
+          @job_name ||= Utils::String.underscore(@class_name)
+        end
+
+        def as_json
+          {
+            class: @class_name,
+            stream: @stream,
+            schedule: @expression,
+            timezone: @timezone,
+            args: @args,
+            name: @name,
+            schedule_subject: schedule_subject,
+            target_subject: target_subject
+          }.compact
+        end
+
+        # JSON payload sent as the body of the schedule message.
+        # Mirrors the format produced by Job::Data so the job processor can handle it.
+        def job_payload
+          Utils::Json.dump({
+                             jid: SecureRandom.hex(12),
+                             class: @class_name,
+                             args: @args,
+                             retry: ::Cosmo::Job::Data::DEFAULTS[:retry],
+                             dead: ::Cosmo::Job::Data::DEFAULTS[:dead]
+                           })
+        end
+
+        def to_s
+          "#<Cosmo::API::Cron::Entry class=#{@class_name} expression=#{@expression} stream=#{@stream}>"
+        end
+        alias inspect to_s
+      end
+    end
+  end
+end

data/lib/cosmo/api/cron.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "cosmo/api/cron/entry"
+
+module Cosmo
+  module API
+    # Web-facing API for cron schedules. Single interface for all cron NATS operations.
+    #
+    # 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.
+    class Cron
+      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) }
+      rescue StandardError
+        []
+      end
+
+      # Publish (or replace) a schedule message in NATS.
+      # @return [Hash, nil] the persisted schedule as a hash, or nil on failure
+      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)
+      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)
+      rescue NATS::JetStream::Error::NotFound, NATS::IO::Timeout
+        nil
+      end
+
+      # 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)
+        return unless msg
+
+        headers = msg.headers || {}
+        body = Utils::Json.parse(msg.data) || {}
+        target = headers["Nats-Schedule-Target"]
+        return unless target && body[:class]
+
+        payload = Utils::Json.dump({
+                                     jid: SecureRandom.hex(12),
+                                     class: body[:class],
+                                     args: body[:args] || [],
+                                     retry: body[:retry] || Job::Data::DEFAULTS[:retry],
+                                     dead: body[:dead].nil? ? Job::Data::DEFAULTS[:dead] : body[:dead]
+                                   })
+        client.publish(target, payload, stream: stream_name)
+      rescue NATS::JetStream::Error::NotFound
+        nil
+      end
+
+      private
+
+      def client
+        @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) }
+      end
+
+      def build_from_nats(stream_name, subject)
+        msg = client.get_message(stream_name, subject: subject)
+        return unless msg
+
+        headers = msg.headers || {}
+        body = Utils::Json.parse(msg.data) || {}
+
+        {
+          class: body[:class],
+          stream: stream_name,
+          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"],
+          registry_key: subject.split(".").drop(2).join("/")
+        }
+      rescue StandardError
+        nil
+      end
+
+      # "cosmo.cron.default.report_job"         → nil
+      # "cosmo.cron.default.report_job.monthly" → "monthly"
+      def name_from_subject(subject)
+        parts = subject.to_s.split(".")
+        parts.length > 4 ? parts.drop(4).join(".") : nil
+      end
+    end
+  end
+end

data/lib/cosmo/api/kv.rb

@@ -3,17 +3,48 @@
 module Cosmo
   module API
     class KV
+      attr_reader :kv
+
       def initialize(name, options = nil)
         @name = name
         @options = Hash(options)
+        @kv = Client.instance.kv(@name, **@options)
       end
 
-      def set(key, value)
-        kv.put(key, value.to_s)
+      def set(key, value, ttl: nil) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        return kv.put(key, value.to_s) unless ttl
+
+        # Pass ttl: (seconds) to set a 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
       end
 
       def get(key)
-        kv.get(key).value
+        kv.get(key)
       rescue NATS::KeyValue::KeyNotFoundError
         # nop
       end
@@ -24,9 +55,7 @@ module Cosmo
 
       def keys(subject = nil, limit: 25)
         results = []
-        params = { ignore_deletes: true, meta_only: true }
-        watcher = kv.watch(subject || ">", params)
-
+        watcher = kv.watch(subject || ">", ignore_deletes: true, meta_only: true)
         watcher.each do |entry|
           break unless entry
 
@@ -34,7 +63,6 @@ module Cosmo
           break if results.size >= limit
         end
         watcher.stop
-
         results
       end
 
@@ -52,12 +80,6 @@ module Cosmo
         0
       end
       alias size count
-
-      private
-
-      def kv
-        @kv ||= Client.instance.kv(@name, **@options)
-      end
     end
   end
 end

data/lib/cosmo/api/stream.rb

@@ -35,31 +35,36 @@ module Cosmo
       end
 
       def total
-        info[:state].messages.to_i
-      rescue StandardError
+        all_msgs = info[:state].messages.to_i
+        cron_count = Client.instance.cron_subjects_in_stream(name, "#{Cron::Entry::SUBJECT_PREFIX}.#{name}.>").size
+        [all_msgs - cron_count, 0].max
+      rescue NATS::Error
         0
       end
       alias size total
 
       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)
+          subject, job = next_candidate(subjects, candidates, current)
           break unless job
 
+          candidates.delete(subject)
+          current = job.seq.to_i + 1
+
           yield job
-          current += 1
         end
       end
 
@@ -84,7 +89,10 @@ module Cosmo
       end
 
       def message(seq)
-        Job.new(name, client.get_message(name, seq: seq, direct: true))
+        job = Job.new(name, client.get_message(name, seq: seq, direct: true))
+        return if job.subject.to_s.start_with?(Cron::Entry::SUBJECT_PREFIX)
+
+        job
       rescue NATS::JetStream::Error::NotFound
         # nop, acked/nacked
       end
@@ -115,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/api.rb

@@ -4,6 +4,7 @@ require "cosmo/api/stream"
 require "cosmo/api/counter"
 require "cosmo/api/kv"
 require "cosmo/api/stats"
+require "cosmo/api/cron"
 
 module Cosmo
   module API

data/lib/cosmo/cli.rb

@@ -4,7 +4,8 @@ require "yaml"
 require "optparse"
 
 module Cosmo
-  class CLI # rubocop:disable Metrics/ClassLength
+  # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/BlockLength
+  class CLI
     def self.run
       instance.run
     end
@@ -58,6 +59,10 @@ module Cosmo
 
       environment_path = File.expand_path("config/environment.rb")
       require environment_path if File.exist?(environment_path)
+
+      # Ensure the ActiveJob integration is loaded when ActiveJob is present
+      # but was not already pulled in by the app (e.g. non-Rails setup or the Railtie hasn't fired yet at this point).
+      require "cosmo/active_job" if defined?(::ActiveJob) && !defined?(Cosmo::ActiveJobAdapter::Executor)
     end
 
     def require_path(path)
@@ -71,8 +76,8 @@ module Cosmo
       require_files("app/streams") if File.directory?("app/streams")
     end
 
-    def flags_parser(flags) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
-      OptionParser.new do |o| # rubocop:disable Metrics/BlockLength
+    def flags_parser(flags)
+      OptionParser.new do |o|
         o.banner = "Usage: cosmo [flags] [command] [options]"
         o.separator ""
         o.separator "Command:"
@@ -98,20 +103,31 @@ module Cosmo
           flags[:config_file] = arg
         end
 
-        o.on "-S", "--setup", "Load config, create streams and exit" do
+        o.on "-S", "--setup", "Create/update streams and sync cron schedules, then exit" do
           load_config(flags)
           boot_application
 
-          Config[:setup]&.each_value do |configs|
+          Config[:setup]&.each do |type, configs|
+            next if type == :cron
+
+            first_line = true
             configs.each do |name, config|
-              Client.instance.stream_info(name)
-            rescue NATS::JetStream::Error::NotFound
-              meta = { metadata: { "_cosmo.type" => "jobs" } }
-              Client.instance.create_stream(name, config.merge(meta))
+              meta = { metadata: { "_cosmo.type" => "jobs" } } if type == :jobs
+              Client.instance.setup_stream(name.to_s, config.merge(Hash(meta)))
+              first_line ? print("Stream is ready: #{name}") : print(", #{name}")
+              first_line = false
             end
           end
 
-          puts "Cosmo streams were created successfully"
+          puts
+          schedules = Config.dig(:setup, :cron)&.reduce(0) do |sum, (name, entry)|
+            class_name = entry.delete(:class)
+            API::Cron.instance.upsert!(**entry, name: name, class_name: class_name)
+            sum + 1
+          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."
           exit(0)
         end
 
@@ -234,4 +250,5 @@ module Cosmo
     end
     # rubocop:enable Layout/TrailingWhitespace,Lint/IneffectiveAccessModifier
   end
+  # rubocop:enable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/BlockLength
 end

data/lib/cosmo/client.rb

@@ -42,12 +42,35 @@ module Cosmo
       js.update_stream(name: name, **config)
     end
 
+    # Create/update a stream, falling back to create when there's no stream.
+    # @param name [String] Stream name
+    # @param config [Hash] Full desired stream configuration
+    def setup_stream(name, config)
+      update_stream(name, config)
+    rescue NATS::JetStream::Error::StreamNotFound
+      create_stream(name, config)
+    end
+
+    # Return all subjects in +stream_name+ that match +filter+ using NATS's
+    # subjects_filter on STREAM.INFO (requires NATS ≥ 2.9).
+    # @return [Array<String>]
+    def cron_subjects_in_stream(stream_name, filter)
+      payload = Utils::Json.dump({ subjects_filter: filter })
+      resp = nc.request("$JS.API.STREAM.INFO.#{stream_name}", payload)
+      data = Utils::Json.parse(resp.data, symbolize_names: false)
+      (data&.dig("state", "subjects") || {}).keys
+    rescue StandardError
+      []
+    end
+
     def list_streams
       response = nc.request("$JS.API.STREAM.LIST", "")
       data = Utils::Json.parse(response.data, symbolize_names: false)
       return [] if data.nil? || data["streams"].nil?
 
       data["streams"]
+    rescue NATS::Error
+      []
     end
 
     def pause_stream(name)
@@ -80,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)
@@ -98,14 +121,39 @@ module Cosmo
       result["purged"] # number of messages purged
     end
 
-    def kv(name, **options)
+    def kv(name, allow_msg_ttl: false, **options)
       js.key_value(name)
     rescue NATS::KeyValue::BucketNotFoundError
-      js.create_key_value({ bucket: name }.merge(options))
+      allow_msg_ttl ? create_kv_with_msg_ttl(name, **options) : js.create_key_value({ bucket: name }.merge(options))
     end
 
     def close
       nc.close
     end
+
+    private
+
+    # NOTE: KV manager in nats-pure hardcodes the fields it copies into StreamConfig,
+    # so `allow_msg_ttl` is never forwarded via create_key_value. Send the raw stream-create API request instead.
+    def create_kv_with_msg_ttl(name, **options)
+      payload = Utils::Json.dump({
+        name: "KV_#{name}",
+        subjects: ["$KV.#{name}.>"],
+        storage: "file",
+        allow_direct: true,
+        allow_msg_ttl: true,
+        allow_rollup_hdrs: true,
+        max_msgs_per_subject: 1
+      }.merge(options))
+      resp = nc.request("$JS.API.STREAM.CREATE.KV_#{name}", payload)
+      result = Utils::Json.parse(resp.data, symbolize_names: false)
+      if result&.dig("error")
+        msg = result.dig("error", "description").to_s
+        # Two worker processes starting simultaneously can both attempt creation.
+        # If another process won the race, fall back to looking up the existing bucket.
+        raise NATS::JetStream::Error, msg unless msg.match?(/already in use|already exists/i)
+      end
+      js.key_value(name)
+    end
   end
 end