cosmonats 0.2.0 → 0.4.0

data/lib/cosmo/active_job/adapter.rb

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

data/lib/cosmo/active_job/executor.rb

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

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
 
@@ -48,16 +76,10 @@ module Cosmo
 
       def count
         keys.size
-      rescue NATS::KeyValue::NoKeysFoundError
+      rescue NATS::KeyValue::NoKeysFoundError, NATS::JetStream::Error::NotFound
         0
       end
       alias size count
-
-      private
-
-      def kv
-        @kv ||= Client.instance.kv(@name, **@options)
-      end
     end
   end
 end

data/lib/cosmo/api/stream.rb

@@ -10,12 +10,13 @@ module Cosmo
       include Enumerable
 
       def self.all
-        client.list_streams.filter_map { new(_1) }
+        client.list_streams.map { new(_1.dig("config", "name")) }
       end
 
       def self.jobs
-        names = Config[:setup][:jobs].keys - %i[scheduled dead]
-        all.select { names.include?(_1.name.to_sym) }
+        client.list_streams.select { _1.dig("config", "metadata", "_cosmo.type") == "jobs" }
+                           .reject { %w[scheduled dead].include?(_1.dig("config", "name")) }
+                           .map { new(_1.dig("config", "name")) }
       end
 
       def self.client
@@ -34,14 +35,16 @@ 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 { it["num_redelivered"].to_i }
+        client.list_consumers(name).sum { _1["num_redelivered"].to_i }
       end
 
       def each
@@ -55,10 +58,10 @@ module Cosmo
           break if current > last
 
           job = message(current)
-          break unless job
+          current += 1
+          next unless job
 
           yield job
-          current += 1
         end
       end
 
@@ -83,7 +86,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
@@ -100,6 +106,18 @@ module Cosmo
         client.delete_message(name, seq)
       end
 
+      def pause!
+        client.pause_stream(name)
+      end
+
+      def unpause!
+        client.unpause_stream(name)
+      end
+
+      def paused?
+        client.stream_paused?(name)
+      end
+
       private
 
       def client

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,19 +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
-              Client.instance.create_stream(name, config)
+              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/updated"
+          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
+
+          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
 
@@ -233,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