cosmonats 0.7.0 → 0.8.0

data/lib/cosmo/api/stats/processes.rb

@@ -6,17 +6,27 @@ module Cosmo
       # Live worker processes, one entry per process, refreshed by Cosmo::Heartbeat.
       class Processes < Registry
         TTL = 60
-        BUCKET = "cosmo_processes"
+        BUCKET = "_cosmoprocesses"
+        KINDS = %w[jobs streams jobs+streams none].freeze
 
-        # Sorted by host and pid before paging: every heartbeat rewrites an entry, so the bucket's own
-        # order shifts constantly and would move processes between pages.
+        # Which processors a process is pulling for, judged by its non-empty subscriptions.
+        #
+        # @param process [Hash]
+        # @return [String] one of {KINDS}
+        def self.kind(process)
+          types = Hash(process[:subscriptions]).reject { |_, names| Array(names).empty? }.keys.map(&:to_s).sort
+          types.empty? ? "none" : types.join("+")
+        end
+
+        # Sorted by kind, host and pid before paging: every heartbeat rewrites an entry, so the bucket's own
+        # order shifts constantly and would move processes between pages, and each kind stays contiguous.
         #
         # @param page [Integer, nil]
         # @param limit [Integer]
         # @return [Array<Hash>]
         def list(page: nil, limit: LIMIT)
           offset = ([page.to_i, 1].max - 1) * limit
-          all.sort_by { [_1[:hostname].to_s, _1[:pid].to_i] }.slice(offset, limit).to_a
+          all.sort_by { [KINDS.index(self.class.kind(_1)) || KINDS.size, _1[:hostname].to_s, _1[:pid].to_i] }.slice(offset, limit).to_a
         end
 
         # @param identity [String] a unique process id, e.g. +hostname-pid+

data/lib/cosmo/api/stats/totals.rb

@@ -3,23 +3,15 @@
 module Cosmo
   module API
     module Stats
-      # Processed and failed job totals across all workers.
+      # Processed and failed job totals across all workers, in the +_cosmototals+ counters. They never expire.
       class Totals < Counter
+        STREAM_NAME = "_cosmototals"
+        DESCRIPTION = "Cosmo statistics"
+
         def self.instance
           @instance ||= new("jobs")
         end
 
-        # Counts the block's outcome: +true+ is processed, +false+ or a raise is failed.
-        #
-        # @return [void]
-        def with
-          result = yield
-          increment(:processed) if result == true
-          increment(:failed) if result == false
-        rescue Exception # rubocop:disable Lint/RescueException
-          increment(:failed)
-        end
-
         # @return [Integer]
         def processed
           get(:processed)

data/lib/cosmo/api/stats.rb

@@ -3,6 +3,7 @@
 require "cosmo/api/stats/totals"
 require "cosmo/api/stats/busy"
 require "cosmo/api/stats/processes"
+require "cosmo/api/stats/metrics"
 
 module Cosmo
   module API
@@ -34,11 +35,11 @@ module Cosmo
       end
 
       def scheduled
-        Stream.new("scheduled").size
+        Config.scheduled.enabled ? Stream.new("scheduled").size : 0
       end
 
       def dead
-        Stream.new("dead").size
+        Config.dead.enabled ? Stream.new("dead").size : 0
       end
     end
   end

data/lib/cosmo/batch/counters.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "cosmo/api/counter"
+
+module Cosmo
+  class Batch
+    # Every batch's total, pending, and failed counters, in the +_cosmobatches+ stream. They are purged once the batch
+    # finishes, and expire +config.batches.expiry+ after their last update otherwise, along with the batch's KV state.
+    class Counters < API::Counter
+      STREAM_NAME = "_cosmobatches"
+      DESCRIPTION = "Cosmo batch progress"
+
+      # @return [Hash]
+      def self.stream_config
+        super.merge(max_age: Config.to_ns(Utils::Duration.parse(Config.batches.expiry)))
+      end
+    end
+  end
+end

data/lib/cosmo/batch.rb

@@ -3,6 +3,7 @@
 require "securerandom"
 require "cosmo/batch/callback"
 require "cosmo/batch/dispatcher"
+require "cosmo/batch/counters"
 
 module Cosmo
   # Groups jobs together and runs a callback once they've all finished.
@@ -51,8 +52,8 @@ module Cosmo
   # Every batch has an id (bid, a random hex string). State lives
   # in two places, both keyed by that bid:
   #
-  # 1. Three atomic counters (via API::Counter, namespace "batch", backed by
-  #    the shared _cosmostats stream):
+  # 1. Three atomic counters (via Batch::Counters, namespace "batch", in the
+  #    _cosmobatches stream, which expires them with the KV state below):
   #
   #      <bid>.total    - how many jobs have ever joined this batch
   #      <bid>.pending  - how many of them are still running
@@ -83,8 +84,7 @@ module Cosmo
   class Batch
     extend Dispatcher
 
-    BUCKET = "cosmo_jobs_batches"
-    DEFAULT_EXPIRY = "3d"
+    BUCKET = "_cosmobatches"
     EVENTS = %i[success complete].freeze
 
     def self.current
@@ -100,11 +100,11 @@ module Cosmo
     end
 
     def self.counter
-      @counter ||= API::Counter.new("batch")
+      @counter ||= Counters.new("batch")
     end
 
     def self.kv
-      @kv ||= API::KV.new(BUCKET, ttl: Utils::Duration.parse(Config[:batch_expiry] || DEFAULT_EXPIRY))
+      @kv ||= API::KV.new(BUCKET, ttl: Utils::Duration.parse(Config.batches.expiry), replicas: Config.replicas)
     end
 
     attr_reader :bid, :parent_id

data/lib/cosmo/cli.rb

@@ -2,6 +2,7 @@
 
 require "yaml"
 require "optparse"
+require "fileutils"
 
 module Cosmo
   # rubocop:disable-next Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/BlockLength
@@ -20,6 +21,7 @@ module Cosmo
     def run
       @argv = ARGV.dup
       flags, command, options = parse
+      return run_init if flags[:init]
       return run_setup(flags) if flags[:setup]
 
       load_config(flags)
@@ -57,10 +59,19 @@ module Cosmo
         path = default_path if File.exist?(default_path)
       end
 
-      Config.load(path)
-      Config.set(:concurrency, flags[:concurrency]) if flags[:concurrency]
-      Config.set(:timeout, flags[:timeout]) if flags[:timeout]
-      Config.set(:http, :port, flags[:http_port]) if flags[:http_port]
+      overrides = { concurrency: flags[:concurrency], timeout: flags[:timeout] }.compact
+      overrides[:http] = { port: flags[:http_port] } if flags[:http_port]
+      Config.load(path, overrides:)
+    end
+
+    def run_init
+      path = File.expand_path(Config::DEFAULT_PATH)
+      raise Error, "#{Config::DEFAULT_PATH} already exists" if File.exist?(path)
+
+      FileUtils.mkdir_p(File.dirname(path))
+      FileUtils.cp(Config::DEFAULTS_FILE, path)
+      puts "Created #{Config::DEFAULT_PATH} with Cosmo's defaults"
+      exit(0)
     end
 
     def run_setup(flags)
@@ -80,7 +91,8 @@ module Cosmo
         puts unless first_line
       end
 
-      API::Counter.setup!
+      services = Services.setup!
+      puts "Service streams are ready: #{services.join(", ")}" if services.any?
 
       schedules = Config.dig(:setup, :cron)&.reduce(0) do |sum, (name, entry)|
         class_name = entry.delete(:class)
@@ -151,6 +163,10 @@ module Cosmo
           flags[:setup] = true
         end
 
+        o.on "--init", "Write #{Config::DEFAULT_PATH} with Cosmo's defaults, then exit" do
+          flags[:init] = true
+        end
+
         o.on_tail "-v", "--version", "Print version" do
           puts "Cosmo #{VERSION}"
           exit(0)

data/lib/cosmo/client.rb

@@ -144,6 +144,31 @@ module Cosmo
       js.get_msg(stream_name, **options)
     end
 
+    # The last message on every subject matching +filters+, in one batched direct get (NATS ≥ 2.11). Needs
+    # +allow_direct+ on the stream.
+    #
+    # @param stream_name [String]
+    # @param filters [Array<String>] subject filters, wildcards allowed
+    # @return [Hash{String => String}] message data by subject
+    def last_messages(stream_name, filters) # rubocop:disable Metrics/AbcSize
+      inbox = nc.new_inbox
+      sub = nc.subscribe(inbox)
+      nc.publish("$JS.API.DIRECT.GET.#{stream_name}", Utils::Json.dump({ multi_last: filters, batch: 10_000 }), inbox)
+      messages = {}
+      loop do
+        msg = sub.next_msg(timeout: self.class.js_timeout)
+        subject = msg.header&.dig("Nats-Subject")
+        break unless subject
+
+        messages[subject] = msg.data
+      end
+      messages
+    rescue NATS::Timeout
+      messages
+    ensure
+      sub&.unsubscribe
+    end
+
     def delete_message(name, seq)
       response = nc.request("$JS.API.STREAM.MSG.DELETE.#{name}", JSON.dump({ seq: seq }))
       Utils::Json.parse(response.data, symbolize_names: false)
@@ -198,7 +223,7 @@ module Cosmo
 
     # 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)
+    def create_kv_with_msg_ttl(name, replicas: 1, **options)
       payload = Utils::Json.dump({
         name: "KV_#{name}",
         subjects: ["$KV.#{name}.>"],
@@ -206,7 +231,8 @@ module Cosmo
         allow_direct: true,
         allow_msg_ttl: true,
         allow_rollup_hdrs: true,
-        max_msgs_per_subject: 1
+        max_msgs_per_subject: 1,
+        num_replicas: replicas
       }.merge(options))
       resp = nc.request("$JS.API.STREAM.CREATE.KV_#{name}", payload)
       result = Utils::Json.parse(resp.data, symbolize_names: false)

data/lib/cosmo/config/cosmo.yml

@@ -0,0 +1,58 @@
+# Cosmo configuration. Every value below is what Cosmo uses when you leave it out,
+# so you can delete anything you don't want to change. Listing your own job streams under setup.jobs
+# replaces the `default` stream and its consumer below. Scheduled jobs, dead jobs, and stats are
+# managed by Cosmo itself: tune them in Cosmo.configure instead.
+
+timeout: 25    # Shutdown timeout in seconds
+concurrency: 1 # Number of worker threads
+max_retries: 3 # Retries for a job class that sets none
+
+#http:          # Serve GET /health and /ping
+#  port: 9090
+#  host: 0.0.0.0
+
+stream_config: &stream_config
+  storage: file         # file or memory
+  retention: workqueue  # workqueue deletes acked messages; limits keeps them until max_age/max_msgs
+  duplicate_window: 120 # seconds a Nats-Msg-Id is remembered, so a resent job is stored once
+  discard: new          # what to drop when the stream is full: new rejects publishes, old evicts the oldest
+  allow_direct: true    # required by the web UI
+  subjects:
+    - jobs.%{name}.>    # %{name} is the stream name
+
+consumer_config: &consumer_config
+  ack_policy: explicit    # every message is acked on its own
+  max_deliver: 30         # deliveries before a message is given up on; keep it above every job class's retry
+  max_ack_pending: 20     # unacked messages before the server stops delivering more
+  ack_wait: 60            # seconds before an unacked message is redelivered
+  subject: jobs.%{name}.> # %{name} is the stream name
+
+setup:
+  jobs:
+    default:
+      <<: *stream_config
+      description: Default jobs
+#    critical:
+#      <<: *stream_config
+#      description: Critical jobs
+#  streams:               # Streams for Cosmo::Stream processors
+#    events:
+#      storage: file
+#      retention: limits
+#      max_age: 86400
+#      subjects:
+#        - events.>
+#  cron:                  # Recurring jobs, synced by `cosmo --setup`
+#    daily_report:
+#      class: ReportJob
+#      schedule: "@daily"
+#      stream: default
+
+consumers:
+  jobs:
+    default:
+      <<: *consumer_config
+      priority: 15         # relative polling weight among job streams
+#    critical:
+#      <<: *consumer_config
+#      priority: 50

data/lib/cosmo/config/settings.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Cosmo
+  class Config < ::Hash
+    # +config.scheduled+ in Cosmo.configure. Turned off, Cosmo neither creates the scheduled stream nor runs the
+    # scheduler, and delayed jobs (+perform_in+/+perform_at+) and crons raise {SchedulingDisabledError}.
+    Scheduled = Struct.new(:enabled, keyword_init: true)
+
+    # +config.dead+ in Cosmo.configure: the dead-letter stream's retention (+max_age+ in seconds or a duration such as
+    # "7d"). Turned off, a job that gives up is dropped instead of parked.
+    Dead = Struct.new(:enabled, :max_age, :max_msgs, :max_bytes, keyword_init: true)
+
+    # +config.batches+ in Cosmo.configure: how long a batch's tracking data lives (seconds or a duration such as "3d").
+    Batches = Struct.new(:expiry, keyword_init: true)
+
+    # +config.metrics+ in Cosmo.configure: per-day job metrics behind the web UI's Metrics tab, kept for +retention+
+    # (seconds or a duration such as "30d"). Turned off, nothing is recorded and the tab is hidden.
+    Metrics = Struct.new(:enabled, :retention, keyword_init: true)
+  end
+end

data/lib/cosmo/config.rb

@@ -2,31 +2,68 @@
 
 require "yaml"
 require "forwardable"
+require "cosmo/config/settings"
 
 module Cosmo
   class Config < ::Hash
     NANO = 1_000_000_000
     DEFAULT_PATH = "config/cosmo.yml"
+    DEFAULTS_FILE = File.expand_path(DEFAULT_PATH, __dir__)
+    SERVICE_STREAMS = %i[scheduled dead].freeze
 
     class << self
       extend Forwardable
 
-      delegate %i[[] fetch dig to_h set load] => :instance
+      delegate %i[[] fetch dig load server_middleware client_middleware error_handlers replicas scheduled dead batches metrics] => :instance
     end
 
     def self.to_ns(seconds)
       (seconds.to_f * NANO).to_i
     end
 
+    def self.read(path)
+      Utils::Hash.symbolize_keys!(YAML.load_file(path, aliases: true) || {})
+    end
+
     def self.parse_file(path)
-      YAML.load_file(path, aliases: true).tap { normalize!(_1) }
+      read(path).tap { normalize!(_1) }
+    end
+
+    # The built-in {DEFAULTS_FILE} with +user+ deep-merged over it. Job streams are the one list that is not merged:
+    # a user who lists any in +setup.jobs+ gets exactly those, and the built-in +default+ stream and consumer go away.
+    # Without +setup.jobs+, +consumers.jobs.default+ still tunes the built-in consumer.
+    #
+    # @param user [Hash] a parsed config file, not yet normalized
+    # @return [Hash] the normalized effective config
+    # @raise [ConfigError] when +user+ configures something Cosmo.configure owns
+    def self.build(user)
+      validate!(user)
+      defaults = read(DEFAULTS_FILE)
+      if user.dig(:setup, :jobs)
+        defaults[:setup].delete(:jobs)
+        defaults[:consumers].delete(:jobs)
+      end
+      Utils::Hash.deep_merge(defaults, user).tap { normalize!(_1) }
+    end
+
+    def self.validate!(config)
+      %i[setup consumers].each do |section|
+        jobs = config.dig(section, :jobs)
+        name = SERVICE_STREAMS.find { jobs.is_a?(::Hash) && jobs.key?(_1) }
+        next unless name
+
+        raise ConfigError, "`#{section}.jobs.#{name}` is a Cosmo service stream: remove it from cosmo.yml " \
+                           "and tune it with Cosmo.configure { |config| config.#{name} }"
+      end
+      return unless config.key?(:batch_expiry)
+
+      raise ConfigError, "`batch_expiry` moved out of cosmo.yml: Cosmo.configure { |config| config.batches.expiry = ... }"
     end
 
     def self.normalize!(config) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
       Utils::Hash.symbolize_keys!(config)
 
       config[:timeout] = Utils::Duration.parse(config[:timeout]) if config[:timeout]
-      config[:batch_expiry] = Utils::Duration.parse(config[:batch_expiry]) if config[:batch_expiry]
 
       config[:consumers]&.each_key do |name|
         config[:consumers][name].each do |stream_name, c|
@@ -46,17 +83,6 @@ module Cosmo
           c[:max_age] = to_ns(Utils::Duration.parse(c[:max_age])) if c[:max_age]
           c[:duplicate_window] = to_ns(Utils::Duration.parse(c[:duplicate_window])) if c[:duplicate_window]
           c[:subjects] = c[:subjects].map { |s| format(s, name: name) } if c[:subjects]
-
-          # The scheduled stream carries every cron template, so it alone enables NATS message
-          # scheduling. A schedule can only target a subject its own stream covers, and NATS
-          # rejects `discard: new` on any stream with scheduling enabled - keeping both here
-          # leaves the streams that actually run jobs free to choose their own discard policy.
-          next unless type == :jobs && name.to_s == Job::StreamFilter::SCHEDULED.to_s
-
-          c[:allow_msg_schedules] = true
-          cron_subject = "#{API::Cron::Entry::SUBJECT_PREFIX}.>"
-          c[:subjects] = Array(c[:subjects])
-          c[:subjects] << cron_subject unless c[:subjects].include?(cron_subject)
         end
       end
     end
@@ -84,14 +110,113 @@ module Cosmo
       @internal ||= {}
     end
 
-    def set(...)
-      Utils::Hash.set(self, ...)
+    # Replaces the contents with {.build} of the file at +path+ (or of no file), with +overrides+ merged over it, so
+    # command-line flags win over the file.
+    #
+    # @param path [String, nil]
+    # @param overrides [Hash, nil] e.g. +{ concurrency: 5 }+
+    def load(path = nil, overrides: nil)
+      user = path ? self.class.read(path) : {}
+      replace(self.class.build(Utils::Hash.deep_merge(user, Hash(overrides))))
+    end
+
+    attr_writer :replicas
+
+    # @return [Integer] replicas for every service stream and bucket, e.g. 3 on a NATS cluster
+    def replicas
+      @replicas || 1
+    end
+
+    # @return [Scheduled]
+    def scheduled
+      @scheduled ||= Scheduled.new(enabled: true)
     end
 
-    def load(path = nil)
-      return unless path
+    # @return [Dead]
+    def dead
+      @dead ||= Dead.new(enabled: true, max_age: 7 * 86_400, max_msgs: 10_000, max_bytes: -1)
+    end
+
+    # @return [Batches]
+    def batches
+      @batches ||= Batches.new(expiry: 3 * 86_400)
+    end
+
+    # @return [Metrics]
+    def metrics
+      @metrics ||= Metrics.new(enabled: true, retention: "30d")
+    end
+
+    # Callables given every error Cosmo rescues: failed jobs and stream batches, fetch and scheduler errors, rejected
+    # messages. Each is called with +(error, context)+, +context+ being a Hash with a +:source+ (+:job+, +:stream+,
+    # +:fetch+, +:scheduler+, +:reject+, +:retry_in+, +:limit+) and what is known there, e.g. a job's payload.
+    #
+    #   Cosmo.configure do |config|
+    #     config.error_handlers << ->(error, context) { Honeybadger.notify(error, context: context) }
+    #   end
+    #
+    # @return [Array<#call>]
+    def error_handlers
+      @error_handlers ||= []
+    end
+
+    # @return [::Logger] the logger Cosmo writes to, see {Logger.instance}
+    def logger
+      Logger.instance
+    end
+
+    # Replaces Cosmo's stdout logger, e.g. with +Rails.logger+. Give it +Cosmo::Logger::SimpleFormatter.new+ to keep
+    # Cosmo's +jid+/+elapsed+ context in each line.
+    #
+    # @param logger [::Logger]
+    def logger=(logger)
+      Logger.instance = logger
+    end
+
+    # Ignored when +COSMO_LOG_LEVEL+ is set, which always wins.
+    #
+    # @param level [Symbol, String, Integer] +:trace+, +:debug+, +:info+, +:warn+, +:error+, or +:fatal+
+    def log_level=(level)
+      Logger.level = level
+    end
+
+    # The chain every job execution runs through, starting with the built-in {Middleware::Limit}, {Middleware::Busy},
+    # {Middleware::Totals}, and {Middleware::Metrics}. It lives outside the loaded YAML, so {#load} keeps it. Register middleware
+    # at boot, before workers start:
+    #
+    #   Cosmo.configure do |config|
+    #     config.server_middleware do |chain|
+    #       chain.add MyMiddleware
+    #     end
+    #   end
+    #
+    # @yieldparam chain [Middleware::Chain]
+    # @return [Middleware::Chain]
+    def server_middleware
+      @server_middleware ||= Middleware::Chain.new do |chain|
+        chain.add Middleware::Limit
+        chain.add Middleware::Busy
+        chain.add Middleware::Totals
+        chain.add Middleware::Metrics
+      end
+      yield @server_middleware if block_given?
+      @server_middleware
+    end
 
-      replace(self.class.parse_file(path))
+    # The chain every job enqueue runs through, empty by default. A middleware is called with
+    # +(job_class_name, payload, stream)+ around the publish: it may change +payload+ (the Hash that gets published),
+    # or not yield to stop the publish, so +perform_async+ returns +nil+. +stream+ is the stream the job runs on.
+    #
+    #   Cosmo.configure do |config|
+    #     config.client_middleware { |chain| chain.add RequestIdMiddleware }
+    #   end
+    #
+    # @yieldparam chain [Middleware::Chain]
+    # @return [Middleware::Chain]
+    def client_middleware
+      @client_middleware ||= Middleware::Chain.new
+      yield @client_middleware if block_given?
+      @client_middleware
     end
   end
 end

data/lib/cosmo/heartbeat.rb

@@ -26,6 +26,7 @@ module Cosmo
         loop do
           sleep(INTERVAL)
           beat
+          flush
         end
       end
       self
@@ -37,6 +38,7 @@ module Cosmo
     def stop
       @thread&.kill&.join
       @thread = nil
+      flush
       processes.unregister(identity)
     rescue StandardError => e
       Logger.debug "Heartbeat unregister error: #{e.class} #{e.message}"
@@ -51,6 +53,15 @@ module Cosmo
       Logger.debug "Heartbeat error: #{e.class} #{e.message}"
     end
 
+    # Writes the job metrics recorded since the last flush.
+    #
+    # @return [void]
+    def flush
+      API::Stats::Metrics.instance.flush if Config.metrics.enabled
+    rescue StandardError => e
+      Logger.debug "Metrics flush error: #{e.class} #{e.message}"
+    end
+
     # @return [String]
     def identity
       @identity ||= "#{Socket.gethostname}-#{::Process.pid}"

data/lib/cosmo/job/data.rb

@@ -36,8 +36,19 @@ module Cosmo
         @at ? :scheduled : @options[:stream]
       end
 
-      def subject(target: false)
-        ["jobs", stream(target:).to_s, Utils::String.underscore(@class_name)]
+      # @return [String] the subject the job is published to: the custom +subject:+ option, or the one derived
+      #   from its stream and class
+      def subject
+        @subject || subject_for(stream)
+      end
+
+      # @return [Hash{String => String, Integer}] dedup id, plus where to dispatch a delayed job once it is due
+      def headers
+        headers = { "Nats-Msg-Id" => jid }
+        return headers unless @at
+
+        target = stream(target: true)
+        headers.merge("X-Execute-At" => @at.to_i, "X-Stream" => target, "X-Subject" => subject_for(target))
       end
 
       def as_json
@@ -49,18 +60,12 @@ module Cosmo
         Utils::Json.dump(as_json)
       end
 
-      def to_args
-        headers = { "Nats-Msg-Id" => jid }
-        if @at
-          headers.merge!("X-Execute-At" => @at.to_i,
-                         "X-Stream" => stream(target: true),
-                         "X-Subject" => subject(target: true).join("."))
-        end
-        [@subject || subject.join("."), to_json, { stream: stream, header: headers }]
-      end
-
       private
 
+      def subject_for(stream)
+        "jobs.#{stream}.#{Utils::String.underscore(@class_name)}"
+      end
+
       def validate!
         raise ArgumentError, "stream is not provided" unless @options[:stream]
       end

data/lib/cosmo/job/enqueuer.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Cosmo
+  module Job
+    # The one path a job takes onto its stream, shared by {Job::ClassMethods#perform} and the ActiveJob adapter.
+    module Enqueuer
+      module_function
+
+      # Publishes the job through {Config#client_middleware}.
+      #
+      # @param class_name [String]
+      # @param args [Array]
+      # @param options [Hash] job options, see {Data}
+      # @param batch [Batch, nil] the batch the job joins; it is reserved a pending slot before the publish
+      #   (see Batch#jobs) and released again when the publish fails or a middleware stops it, so the batch never
+      #   waits on a lost job
+      # @return [String, nil] the job's jid, or nil when a client middleware stopped the publish
+      # @raise [StreamNotFoundError] when the target stream does not exist
+      # @raise [SchedulingDisabledError] for a delayed job while scheduling is turned off
+      def enqueue(class_name, args, options, batch: nil) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
+        options = options.merge(batch_id: batch.bid) if batch
+        data = Data.new(class_name, args, options)
+        raise SchedulingDisabledError if data.stream.to_s == Services::SCHEDULED && !Config.scheduled.enabled
+
+        batch&.register_job!
+        begin
+          published = pipe(class_name, data)
+        rescue StandardError
+          batch&.rollback_job!
+          raise
+        end
+        batch&.rollback_job! unless published
+        data.jid if published
+      end
+
+      def pipe(class_name, data)
+        payload = data.as_json
+        published = false
+        Config.client_middleware.invoke(class_name, payload, data.stream(target: true)) do
+          publish(data, payload)
+          published = true
+        end
+        published
+      end
+
+      def publish(data, payload)
+        Client.instance.publish(data.subject, Utils::Json.dump(payload), stream: data.stream, header: data.headers)
+      rescue NATS::JetStream::Error::NoStreamResponse
+        raise StreamNotFoundError, data.stream.to_s
+      end
+    end
+  end
+end