cogworker 0.1.0

data/lib/cogworker/swarm.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module Cogworker
+  # Multi-process supervisor: forks `COGWORKER_COUNT` worker children from
+  # one parent (copy-on-write memory sharing) and relays signals to them.
+  # `PHASED_RESTART=true` makes a restart trigger cycle children one at a
+  # time (quiet -> wait -> replace) instead of all at once, so the pool as a
+  # whole never has zero capacity.
+  #
+  # The parent process is never itself a job-processing Launcher — it only
+  # forks/reaps/signals. Each child re-runs the full CLI boot (re-requiring
+  # app code, resetting its own identity) *after* `fork`, never before, so
+  # nothing in Heartbeat/Scheduled/the periodic Ticker ever starts a
+  # background thread in the parent that would silently vanish in a child.
+  class Swarm
+    # How long a phased-restart replacement waits for the outgoing child to
+    # exit on its own before giving up and force-killing it. Graceful
+    # shutdown (Manager#stop! draining in-flight jobs) can legitimately take
+    # a while, but this loop is single-threaded and blocking — one child
+    # that never exits (a hung Redis call outliving even Manager#stop!'s
+    # own 25s join, or anything else) must not be able to wedge the whole
+    # restart cycle, and the supervisor's entire signal-handling loop with
+    # it, forever.
+    GRACEFUL_STOP_TIMEOUT = 20
+
+    def initialize(argv, count: ENV.fetch('COGWORKER_COUNT', 1).to_i, phased: ENV['PHASED_RESTART'] == 'true')
+      @argv = argv
+      @count = [count, 1].max
+      @phased = phased
+      @children = {} # pid => slot index
+      @signal_queue = ::Queue.new
+      @stopping = false
+    end
+
+    def run
+      install_signal_traps
+      @count.times { |slot| fork_child(slot) }
+      supervise
+    end
+
+    private
+
+    def fork_child(slot)
+      pid = ::Process.fork do
+        Cogworker.reset_identity!
+        CLI.new.run(@argv.dup)
+        # `exit!`, not plain `exit`: `Launcher#run` only returns once
+        # `Manager#stop!` has had its bounded (default 25s) chance to join
+        # every processor thread — but per that method's own doc, a thread
+        # stuck past its deadline (mid a hung Redis call, say) is left
+        # running, not killed. A non-daemon thread still alive there would
+        # make plain `exit`'s normal interpreter shutdown wait for it
+        # indefinitely, so this OS process would never actually go away —
+        # and `Swarm#initiate_restart`'s own `Process.waitpid(pid)` for this
+        # exact child would then block forever right along with it.
+        ::Process.exit!(true)
+      end
+      @children[pid] = slot
+      Cogworker.logger.info { "swarm: started child pid=#{pid} slot=#{slot}" }
+    end
+
+    def install_signal_traps
+      Signal.trap(Signals::QUIET) { @signal_queue << :quiet }
+      Signal.trap(Signals::STOP) { @signal_queue << :stop }
+      Signal.trap(Signals::INTERRUPT) { @signal_queue << :stop }
+      Signal.trap(Signals::RESTART) { @signal_queue << :restart }
+    end
+
+    def supervise
+      until @stopping && @children.empty?
+        drain_signals
+        reap_children
+        sleep 0.2
+      end
+    end
+
+    def drain_signals
+      until @signal_queue.empty?
+        case @signal_queue.pop
+        when :quiet then relay(Signals::QUIET)
+        when :stop then initiate_stop
+        when :restart
+          Cogworker.logger.info { "swarm: restart signal received, phased=#{@phased}" }
+          initiate_restart
+        else Cogworker.logger.warn { "Unknown signal: #{signal}" }
+        end
+      end
+    end
+
+    def relay(signal)
+      @children.each_key { |pid| safe_kill(pid, signal) }
+    end
+
+    def initiate_stop
+      @stopping = true
+      relay(Signals::STOP)
+    end
+
+    # Non-phased: signal every child at once; the normal reap/respawn path
+    # below brings each one back as it exits, so there's a brief capacity
+    # dip but no explicit special-casing needed. Phased: replace children
+    # one at a time, waiting for each replacement to finish forking before
+    # touching the next, so total capacity never drops by more than one
+    # slot at a time.
+    def initiate_restart
+      return relay(Signals::STOP) unless @phased
+
+      @children.keys.each do |pid| # rubocop:disable Style/HashEachMethods -- mutates @children (delete/fork_child) during iteration; each_key is unsafe here
+        next unless @children.key?(pid)
+
+        slot = @children.delete(pid)
+        Cogworker.logger.info { "swarm: phased restart stopping child pid=#{pid} slot=#{slot}" }
+        safe_kill(pid, Signals::STOP)
+        wait_for_exit(pid)
+        Cogworker.logger.info { "swarm: phased restart child pid=#{pid} slot=#{slot} exited, respawning" }
+        fork_child(slot)
+      end
+    end
+
+    # Polls instead of a plain blocking `Process.waitpid(pid)`, specifically
+    # so a child that never exits can't block this forever: past
+    # GRACEFUL_STOP_TIMEOUT it's force-killed and reaped instead of leaving
+    # `initiate_restart` (and every other signal this single-threaded
+    # supervisor needs to handle) stuck behind it indefinitely.
+    def wait_for_exit(pid)
+      deadline = monotonic_now + GRACEFUL_STOP_TIMEOUT
+      until ::Process.waitpid(pid, ::Process::WNOHANG)
+        if monotonic_now > deadline
+          Cogworker.logger.warn { "swarm: child pid=#{pid} didn't stop within #{GRACEFUL_STOP_TIMEOUT}s, killing" }
+          safe_kill(pid, 'KILL')
+          ::Process.waitpid(pid)
+          return
+        end
+        sleep 0.1
+      end
+    rescue Errno::ECHILD
+      nil
+    end
+
+    def monotonic_now
+      ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+    end
+
+    def reap_children
+      pid = begin
+        ::Process.waitpid(-1, ::Process::WNOHANG)
+      rescue Errno::ECHILD
+        nil
+      end
+      return unless pid
+
+      slot = @children.delete(pid)
+      return if slot.nil? # already handled by initiate_restart
+
+      if @stopping
+        Cogworker.logger.info { "swarm: child pid=#{pid} slot=#{slot} exited" }
+      else
+        Cogworker.logger.warn { "swarm: child pid=#{pid} slot=#{slot} exited unexpectedly, respawning" }
+        fork_child(slot)
+      end
+    end
+
+    def safe_kill(pid, signal)
+      ::Process.kill(signal, pid)
+    rescue Errno::ESRCH
+      nil
+    end
+  end
+end

data/lib/cogworker/testing.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Cogworker
+  # `Client.push`'s enqueue-mode switch, checked at the very end of the
+  # client middleware chain in place of the real `raw_push` — the same spot
+  # every enqueue path (`perform_async`/`perform_in`/`perform_at`, or a
+  # direct `Client.push` call) already funnels through, so flipping this
+  # mode covers all of them for free. Three states:
+  #
+  # - `:disabled` (default) — the real thing: pushes onto actual Redis, same
+  #   as every non-test run. Nothing here changes any existing behavior.
+  # - `:fake` — the client middleware chain still runs (so custom middleware
+  #   that mutates the job hash, e.g. tagging, is exercised same as in prod),
+  #   but the normalized job hash is appended to `jobs_for(klass_name)`
+  #   instead of touching Redis — nothing is scheduled or executed. Use
+  #   `SomeJob.jobs` (added to `Job::ClassMethods`) to assert what got
+  #   pushed, `SomeJob.clear`/`Testing.clear_jobs!` to reset between
+  #   examples.
+  # - `:inline` — the job runs synchronously, right here in the calling
+  #   thread, through the real server middleware chain
+  #   (`Cogworker.config.server_chain`) — same as `Processor#execute`, minus
+  #   the parts of that only make sense for an async worker process (work
+  #   registration, stats counters, retry/dead routing on failure: there's
+  #   no Processor here to retry anything later). An exception raised by
+  #   `perform` propagates straight to the caller, same as calling
+  #   `SomeJob.new.perform(*args)` directly would — this is a testing
+  #   convenience, not a fire-and-forget execution path. `perform_in`/
+  #   `perform_at`'s delay is ignored entirely; the job still runs
+  #   immediately.
+  #
+  # A plain module-level ivar, not thread-local: this is a mode flipped once
+  # in a test's setup, not a per-request runtime toggle — same single-
+  # process assumption `Cogworker.config`/`Cogworker.server_process!` already
+  # make.
+  module Testing
+    class << self
+      def fake!(&block)
+        set(:fake, &block)
+      end
+
+      def inline!(&block)
+        set(:inline, &block)
+      end
+
+      def disable!(&block)
+        set(:disabled, &block)
+      end
+
+      def fake?
+        mode == :fake
+      end
+
+      def inline?
+        mode == :inline
+      end
+
+      def disabled?
+        mode == :disabled
+      end
+
+      def mode
+        @mode ||= :disabled
+      end
+
+      # `SomeJob.jobs` reads this via `Job::ClassMethods#jobs` — every job
+      # pushed for that exact class name while fake mode was on, oldest
+      # first, as the same normalized (string-keyed) job hash `Client.push`
+      # always produces (so `job['args']`/`job['at']`/`job['jid']` etc. all
+      # work exactly as they would reading a job back out of Redis).
+      def jobs_for(klass_name)
+        registry[klass_name] ||= []
+      end
+
+      def clear_jobs!
+        registry.clear
+      end
+
+      # Runs one job synchronously through the real server middleware chain.
+      # Only ever called from `Client.push` while `inline?`.
+      def perform_inline(job)
+        klass = Object.const_get(job['class'])
+        worker = klass.new
+        worker.jid = job['jid'] if worker.respond_to?(:jid=)
+
+        Cogworker.config.server_chain.invoke(worker, job, job['queue']) do
+          worker.perform(*job['args'])
+        end
+      end
+
+      private
+
+      def registry
+        @registry ||= {}
+      end
+
+      def set(new_mode)
+        previous = mode
+        @mode = new_mode
+        return new_mode unless block_given?
+
+        begin
+          yield
+        ensure
+          @mode = previous
+        end
+      end
+    end
+  end
+end

data/lib/cogworker/unique_jobs/client_middleware.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Cogworker
+  module UniqueJobs
+    # Client middleware, registered unconditionally on every `Config` (like
+    # `Periodic::ReleaseMiddleware` on the server side) — a no-op for any
+    # job that isn't `unique: :until_executed`. For one that is, atomically
+    # claims `cogworker:unique:<digest>` (`SET NX`) before letting the job
+    # continue down the chain to the real push. A job that loses the claim
+    # (another copy is already enqueued/scheduled/running) never reaches
+    # `dispatch` at all — it sets `job['unique_skipped']` instead, which
+    # `Client.push` reads to return `nil` rather than a jid, the same
+    # "nothing was actually pushed" signal `sidekiq-unique-jobs` gives.
+    class ClientMiddleware
+      def call(_worker_class, job, _queue, redis_pool = Cogworker.config.redis_pool)
+        return yield unless UniqueJobs.until_executed?(job)
+
+        acquired = redis_pool.with do |c|
+          c.set(RedisKeys.unique_lock(UniqueJobs.digest(job)), job['jid'],
+                nx: true, ex: Cogworker.config.unique_lock_ttl)
+        end
+
+        if acquired
+          yield
+        else
+          job['unique_skipped'] = true
+        end
+      end
+    end
+  end
+end

data/lib/cogworker/unique_jobs/release_middleware.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Cogworker
+  module UniqueJobs
+    # Releases the `cogworker:unique:<digest>` lock (claimed by
+    # `ClientMiddleware` for `unique: :until_executed` jobs) on success, or
+    # on the terminal failed attempt — mirrors `Periodic::ReleaseMiddleware`
+    # exactly, just keyed by job content (class+queue+args) instead of a
+    # periodic pjid, so a retried job keeps its lock (no duplicate can sneak
+    # in while it's still retrying) and only releases once it's genuinely
+    # done, one way or the other. A no-op for any job that isn't
+    # `unique: :until_executed`. Registered unconditionally in every
+    # `Config`, same as `Periodic::ReleaseMiddleware`.
+    class ReleaseMiddleware
+      def call(_worker, job, _queue)
+        yield
+        release(job) if UniqueJobs.until_executed?(job)
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        release(job) if UniqueJobs.until_executed?(job) && JobUtil.terminal_failure?(job)
+        raise e
+      end
+
+      private
+
+      def release(job)
+        Cogworker.config.redis { |c| c.del(RedisKeys.unique_lock(UniqueJobs.digest(job))) }
+      end
+    end
+  end
+end

data/lib/cogworker/unique_jobs.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'digest/sha1'
+require 'json'
+
+module Cogworker
+  # Shared helpers for `unique: :until_executed` on regular jobs (anything
+  # pushed through `Client.push` — `perform_async`/`perform_in`/
+  # `perform_at`). Distinct from `Periodic::Entry#until_executed?`, which
+  # locks one cron *slot* per pjid; this locks on job *content* instead, so
+  # `ClientMiddleware` (before push) and `ReleaseMiddleware` (after the job
+  # hash has round-tripped through Redis/JSON) always agree on the same key
+  # without needing to stash it on the job hash itself.
+  module UniqueJobs
+    module_function
+
+    # `job['unique']` round-trips through JSON exactly like `job['retry']`
+    # (see `JobUtil.max_retries`) — a caller's `cogworker_options unique:
+    # :until_executed`/direct push hash may still hold the Symbol at the
+    # point `ClientMiddleware` sees it (before the job is ever
+    # `JSON.generate`d), while `ReleaseMiddleware` only ever sees the
+    # String a popped job was parsed back from. Comparing against `.to_s`
+    # handles both, plus the absent (`nil`) case, uniformly.
+    def until_executed?(job)
+      job['unique'].to_s == 'until_executed'
+    end
+
+    def digest(job)
+      Digest::SHA1.hexdigest("#{job['class']}|#{job['queue']}|#{job['args'].to_json}")
+    end
+  end
+end

data/lib/cogworker/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Cogworker
+  VERSION = '0.1.0'
+end

data/lib/cogworker/web/action.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'erb'
+
+module Cogworker
+  class Web
+    # A fresh instance per request (never reused across requests/threads, so
+    # there's no cross-thread state to worry about). A registered route
+    # block is `instance_exec`'d against one of these, giving it bare
+    # `request`/`params`/`erb`/`redirect` the way TZ describes.
+    class Action
+      attr_reader :request, :params
+
+      def initialize(request, path_params)
+        @request = request
+        @params = request.params.merge(path_params)
+      end
+
+      # An extension's own routes may read either style — `params['x']` or
+      # `url_params('x')` (the latter is what the real History tab uses).
+      def url_params(key)
+        params[key.to_s]
+      end
+
+      # htmx sends this header on every request it issues (both its
+      # polling `hx-trigger` fetches and its `hx-post` form submissions), so
+      # a route can tell "the page is asking for a fragment to swap in"
+      # apart from a plain browser navigation — and fall back to a normal
+      # full-page render (or redirect) for anyone/anything without JS.
+      def hx_request?
+        request.get_header('HTTP_HX_REQUEST') == 'true'
+      end
+
+      # Accepts a Symbol (a built-in template, looked up in web/views/) or a
+      # raw ERB-source String (an extension handing over `File.read(...)`
+      # itself, as the real History tab does).
+      def erb(template, locals: {})
+        source = template.is_a?(Symbol) ? Views.read(template) : template
+        locals_binding = build_binding(locals)
+        ERB.new(source).result(locals_binding)
+      end
+
+      def redirect(location)
+        # Header names must be lowercase per the Rack spec — Rack::Lint
+        # (which Puma's default dev environment runs requests through)
+        # raises on a capitalized 'Location'.
+        halt([302, { 'location' => location }, []])
+      end
+
+      def halt(response)
+        throw :halt, response
+      end
+
+      private
+
+      def build_binding(locals)
+        b = binding
+        locals.each { |k, v| b.local_variable_set(k, v) }
+        b
+      end
+    end
+  end
+end

data/lib/cogworker/web/application.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Cogworker
+  class Web
+    # The shared route table. Built-in tabs register through the exact same
+    # `self.get`/`register` mechanism external extensions use (dogfooding),
+    # so there's only one code path to keep working.
+    module Application
+      class << self
+        def routes
+          @routes ||= []
+        end
+
+        def get(path, &block)
+          add_route('GET', path, &block)
+        end
+
+        def post(path, &block)
+          add_route('POST', path, &block)
+        end
+
+        # `mod.registered(self)` — `self` here is this Application module,
+        # so inside `registered` the extension calls `app.get(...)` against
+        # it directly, matching TZ's Sinatra-style `self.registered(app)`.
+        def register(mod)
+          mod.registered(self)
+        end
+
+        def call(env)
+          request = Rack::Request.new(env)
+          # Rack::URLMap sets PATH_INFO to "" (not "/") for a request that
+          # exactly matches a mount point with no trailing slash — normalize
+          # it so the root route still matches when this app is `map`'d.
+          path_info = request.path_info.empty? ? '/' : request.path_info
+          route = routes.reverse.find do |r|
+            r[:method] == request.request_method && Router.match(r[:pattern], path_info)
+          end
+          return not_found unless route
+
+          captures = Router.match(route[:pattern], path_info)
+          action = Action.new(request, captures)
+          result = catch(:halt) { action.instance_exec(&route[:block]) }
+          rack_triple?(result) ? result : [200, { 'content-type' => 'text/html; charset=utf-8' }, [result.to_s]]
+        end
+
+        private
+
+        def add_route(method, path, &block)
+          routes << { method: method, pattern: Router.compile(path), block: block }
+        end
+
+        def rack_triple?(value)
+          value.is_a?(Array) && value.size == 3 && value.first.is_a?(Integer)
+        end
+
+        def not_found
+          [404, { 'content-type' => 'text/plain' }, ['Not Found']]
+        end
+      end
+    end
+  end
+end