solid-jobs 0.1.3 → 0.4.0

data/docs/reliability.md

@@ -1,63 +1,61 @@
 # Reliability model
 
-SolidJobs uses a Redis-backed at-least-once state machine:
+SolidJobs uses a namespaced Redis-backed at-least-once state machine:
 
 ```text
 READY
   |
-  | BLMOVE reservation
+  | atomic claim
   v
-IN_PROGRESS ---- ACK/LREM ----> removed
+CLAIMED ---- fenced completion ----> removed
   |
-  +---- application error ----> RETRY or DEAD, then ACK
+  +---- application error ----> RETRYING or DISCARDED, then completion
   +---- graceful timeout -----> READY
-  +---- process crash --------> reservation retained
+  +---- node crash -----------> claim retained
                                   |
                                   +---- recovery ----> READY
 ```
 
-The reservation list is named `<process-identity>:reserved:<processor-id>`.
-Each execution receives a distinct reservation journal entry:
+Ready tasks live in `solid_jobs:channel:<name>`. Each executor owns at most one
+claimed-task list and one claim journal entry:
 
 ```text
-job_id          stable across replay
-reservation_id  unique per execution attempt
-process_id      owning process identity
-worker_id       owning Processor Ractor
-attempt         monotonically increasing execution count
-reserved_at     wall-clock reservation time
+task_id      stable across replay
+claim_token  unique per execution attempt
+node_id      owning server identity
+executor_id  owning Executor Ractor
+channel      destination used by recovery
+attempt      monotonically increasing execution count
+claimed_at   wall-clock claim time
 ```
 
-ACK and requeue are fenced by `reservation_id`. Their Lua scripts first
-verify that the worker still owns the current journal generation. A delayed
-or revived worker cannot remove or requeue a newer reservation, even when a
-supervisor reuses the same processor slot.
+Completion and requeue are fenced by `claim_token`. Their Lua scripts verify
+that the executor still owns the current journal generation before changing
+state. A delayed or revived executor cannot complete or requeue a newer claim.
 
-The payload retains its canonical `queue` field, allowing another process to
-restore it after the owner is no longer alive. Recovery uses process liveness
-and heartbeat, never reservation age alone, so a legitimate long-running job
-is not stolen while its owner remains alive.
+The envelope retains its canonical `channel`, allowing another node to restore
+it after its owner dies. Recovery uses node liveness and heartbeat, never claim
+age alone, so a legitimate long-running task is not stolen.
 
 ## Failure boundaries
 
-- Before reservation: the job remains in `queue:<name>`.
-- After reservation or during `perform`: the job remains reserved.
-- After the application effect but before ACK: recovery replays the job.
-- Redis unavailable during ACK: the job remains reserved and is replayed.
-- Graceful shutdown: the active job may finish within the configured timeout;
+- Before claim: the task remains in `solid_jobs:channel:<name>`.
+- After claim or during `execute_task`: the task remains claimed.
+- After the application effect but before completion: recovery replays it.
+- Redis unavailable during completion: the task remains claimed and is replayed.
+- Graceful shutdown: the active task may finish within the configured timeout;
   otherwise it is interrupted and requeued.
-- `SIGKILL`: no handler runs; recovery relies exclusively on Redis state.
+- `SIGKILL`: recovery relies exclusively on Redis state.
 
-This design intentionally favors no job loss over duplicate suppression.
-Exactly-once side effects require application-level idempotency.
+This design favors no task loss over duplicate suppression. Exactly-once side
+effects require application-level idempotency.
 
 ## Startup isolation
 
-The server does not reserve work while components are booting. Heartbeat,
-Processor, and Scheduler Ractors initialize their local configuration and
-Redis pool, report `READY` exactly once, and wait behind
-`SolidJobs::StartupBarrier`. Processing starts only after every component is
-ready:
+The server does not claim work while components are booting. Heartbeat,
+Engine, and Timer Ractors initialize their local configuration and Redis
+pool, report `READY` exactly once, and wait behind
+`SolidJobs::StartupBarrier`:
 
 ```text
 BOOTING -> ALL_READY -> RUNNING
@@ -65,85 +63,69 @@ BOOTING -> ALL_READY -> RUNNING
 ```
 
 Boot failure is terminal. Already-ready components receive `:abort`, close
-their local resources, and never enter their fetch loops. Cleanup is
-idempotent. Component startup is serialized, avoiding concurrent TCP/RESP
-initialization paths known to crash Ruby 3.4 (reproduced on 3.4.4 macOS arm64
-and 3.4.11 Linux x86_64; `rake startup_torture` is the reproducer); normal
-processing remains parallel after `RUNNING`.
-
-### Ruby 3.4 Ractor caveat
-
-Ruby 3.4's Ractor scheduler can deadlock the whole VM (main thread included)
-when a GC-triggered `rb_ractor_sched_barrier_start` runs while several
-Ractors exchange `move: true` messages: every thread parks in
-`ractor_sched_barrier_join_wait_locked` and the barrier never completes.
-`test/support/ractor_barrier_repro.rb` reproduces it **without SolidJobs or
-Redis** (one receiver, four senders, 24k moved messages per iteration):
-Ruby 3.4.4 freezes within the first iterations, Ruby 4.0.1 completes 30/30.
-Inside SolidJobs the same traffic pattern is the Processor → Heartbeat
-`:work`/`:done`/`:stats` channel, so any multi-Processor server on Ruby 3.4
-is exposed; once frozen, neither `Timeout` nor process exit
-(`rb_ractor_terminate_all`) can recover.
-
-Recommendation: **run multi-Ractor SolidJobs servers on Ruby ≥ 4.0**. On
-Ruby 3.4 use the client/API side freely, and prefer one process per
-Processor (`concurrency: 1`) for the server. Server-based stress tests are
-skipped on Ruby < 4 for this reason, and `Server#start` logs a warning when
-it detects `concurrency > 1` on Ruby < 4.
-
-### Bounded shutdown
-
-`Server#stop` never waits forever for a component. Each Ractor gets
-`shutdown_timeout + Server::STOP_GRACE` to return after `:stop`; the signal
-is re-sent up to `STOP_RESENDS` times, then the component is abandoned with
-an error log so the process can proceed with shutdown.
+their local resources, and never enter their claim loops. Cleanup is
+idempotent.
+
+## Ruby 3.4 Ractor caveat
+
+Ruby 3.4's Ractor scheduler can deadlock the VM when a GC-triggered scheduler
+barrier runs while several Ractors exchange moved messages.
+`test/support/ractor_barrier_repro.rb` reproduces this without SolidJobs or
+Redis. Ruby 4.0.1 completes the equivalent reproducer.
+
+Run multi-Ractor SolidJobs servers on Ruby >= 4.0. On Ruby 3.4, prefer one
+process per Engine (`concurrency: 1`). Conductor stress tests are skipped on
+Ruby versions affected by this runtime issue, and `Conductor#start` warns when it
+detects a multi-Ractor configuration there.
+
+## Bounded shutdown
+
+`Conductor#stop` never waits forever for a component. Each Ractor gets
+`shutdown_timeout + Conductor::STOP_GRACE` to return after `:stop`; the signal is
+re-sent up to `STOP_RESENDS` times before the component is abandoned with an
+error log.
 
 ## Configuration scope
 
 `SolidJobs.config` and the testing mode are Ractor-local, not thread-local.
-Every thread and fiber inside a Ractor (for example Puma workers or Rails
-request threads) shares the configuration set on that Ractor, while each
-Ractor keeps its own isolated configuration.
+Every thread and fiber inside a Ractor shares its configuration, while each
+Ractor owns isolated mutable state and Redis connections.
 
 ## Integrity auditing
 
-Fault and chaos tests can reconcile a known set of job IDs against every
-Redis-backed state:
+Fault tests can reconcile known task IDs against every Redis-backed state:
 
 ```ruby
 report = SolidJobs::IntegrityCheck.call(
-  expected_job_ids: submitted_job_ids,
+  expected_job_ids: submitted_task_ids,
   acked_key: "test:completed",
 )
 
 raise report.inspect unless report.ok?
 ```
 
-The report separates lost jobs, unexpected/orphaned jobs, inconsistent
-reservation journals, dangling attempt indexes, duplicate active states, and
-malformed payloads. ACK removes the completed job's attempt index atomically;
-requeue retains it so a recovered reservation increments the same attempt
-sequence.
+The report separates lost tasks, unexpected tasks, inconsistent claim
+journals, dangling attempt indexes, duplicate active states, and malformed
+envelopes. Completion removes the task's attempt index atomically; requeue
+retains it so recovery increments the same attempt sequence.
 
-## Backpressure and queues
+## Backpressure and channels
 
-Each Processor owns at most one reservation and reserves only immediately
-before execution. A process with concurrency `N` therefore holds at most `N`
-active reservations, regardless of Redis queue depth.
+Each Engine owns at most one claim and claims only immediately before
+execution. A node with concurrency `N` therefore holds at most `N` active
+claims, regardless of channel depth.
 
-Queue mode defaults to `:weighted`:
+Channel order defaults to `:weighted`:
 
-- `:weighted` uses bounded weighted round-robin and does not starve configured
-  queues;
-- `:strict` always checks queues in declaration order and may intentionally
-  starve lower-priority queues while a higher-priority queue remains busy;
-- `:random` samples the configured weighted queue list on each reservation.
+- `:weighted` uses bounded weighted round-robin;
+- `:priority` checks channels in declaration order;
+- `:shuffle` samples the configured weighted channel list.
 
-Paused queues are excluded before reservation.
+Paused channels are excluded before claiming.
 
 ## Retry storms
 
-Retries use capped exponential backoff with equal jitter. For attempt `n`, the
-ceiling is `min(retry_base_delay * 2**n, retry_max_delay)` and the actual delay
+Retries use capped exponential backoff with equal jitter. For failure `n`, the
+ceiling is `min(retry_base_delay * 2**(n - 1), retry_max_delay)` and the delay
 is distributed between half and all of that ceiling. Defaults are 15 seconds
-and one hour. This spreads recovery traffic after a shared external outage.
+and one hour.

data/exe/solid-jobs

@@ -2,7 +2,6 @@
 # frozen_string_literal: true
 
 require "solid_jobs"
-require "solid_jobs/cli"
-
-exit SolidJobs::CLI.new.run
+require "solid_jobs/console"
 
+exit SolidJobs::Console.new.run

data/lib/active_job/queue_adapters/solid_jobs_adapter.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "solid_jobs"
-require "solid_jobs/active_job"
+require "solid_jobs/rails_adapter"
 
 module ActiveJob
   module QueueAdapters
@@ -27,16 +27,15 @@ module ActiveJob
       private
 
       def push(job, at: nil)
-        payload = {
-          "class" => SolidJobs::ActiveJob::Wrapper,
+        envelope = {
+          "task" => SolidJobs::RailsAdapter::AdapterTask,
           "wrapped" => job.class.name,
-          "queue" => job.queue_name,
-          "args" => [job.serialize],
+          "channel" => job.queue_name,
+          "arguments" => [job.serialize],
         }
-        payload["at"] = at if at
-        SolidJobs::Client.push(payload)
+        envelope["run_at"] = at if at
+        SolidJobs::Publisher.publish(envelope)
       end
     end
   end
 end
-

data/lib/solid_jobs/{config.rb → blueprint.rb}

@@ -3,36 +3,36 @@
 require "logger"
 
 module SolidJobs
-  class Config
-    DEFAULT_JOB_OPTIONS = {
-      "queue" => "default",
-      "retry" => true,
+  class Blueprint
+    DEFAULT_TASK_OPTIONS = {
+      "channel" => "default",
+      "max_failures" => 25,
     }.freeze
 
-    attr_accessor :concurrency, :dead_max_jobs, :dead_timeout, :logger,
+    attr_accessor :concurrency, :discarded_limit, :discarded_retention, :logger,
       :on_complex_arguments, :poll_interval_average, :shutdown_timeout,
       :reliable_fetch, :retry_base_delay, :retry_max_delay
-    attr_reader :client_middleware, :default_job_options, :error_handlers,
-      :redis_config, :server_middleware
+    attr_reader :default_task_options, :error_handlers, :execute_interceptors,
+      :publish_interceptors, :redis_config
 
-    def initialize(redis: nil, concurrency: 5, queues: ["default"])
+    def initialize(redis: nil, concurrency: 5, channels: ["default"])
       @redis_config = redis || SolidRedis.config(url: ENV.fetch("REDIS_URL", "redis://127.0.0.1:6379/0"))
       @concurrency = Integer(concurrency)
-      @queues = normalize_queues(queues)
-      @default_job_options = DEFAULT_JOB_OPTIONS
-      @client_middleware = Middleware::Chain.new
-      @server_middleware = Middleware::Chain.new
+      @channels = normalize_channels(channels)
+      @default_task_options = DEFAULT_TASK_OPTIONS
+      @publish_interceptors = InterceptorRegistry.new
+      @execute_interceptors = InterceptorRegistry.new
       @error_handlers = []
       @lifecycle_callbacks = Hash.new { |hash, event| hash[event] = [] }
       @on_complex_arguments = :raise
       @poll_interval_average = 5.0
       @shutdown_timeout = 25.0
-      @queue_mode = :weighted
+      @channel_order = :weighted
       @reliable_fetch = true
       @retry_base_delay = 15.0
       @retry_max_delay = 3_600.0
-      @dead_max_jobs = 10_000
-      @dead_timeout = 180 * 24 * 60 * 60
+      @discarded_limit = 10_000
+      @discarded_retention = 180 * 24 * 60 * 60
       @logger = Logger.new($stdout)
       @redis_pool = nil
     end
@@ -50,42 +50,42 @@ module SolidJobs
       redis_pool.with { |connection| yield connection }
     end
 
-    def queues
-      @queues.map(&:first)
+    def channels
+      @channels.map(&:first)
     end
 
-    def queues=(values)
-      @queues = normalize_queues(values)
+    def channels=(values)
+      @channels = normalize_channels(values)
     end
 
-    def queue_entries
-      @queues.dup
+    def channel_entries
+      @channels.dup
     end
 
-    def queue_mode
-      @queue_mode
+    def channel_order
+      @channel_order
     end
 
-    def queue_mode=(mode)
+    def channel_order=(mode)
       mode = mode.to_sym
-      unless %i[strict weighted random].include?(mode)
-        raise ArgumentError, "queue_mode must be :strict, :weighted, or :random"
+      unless %i[priority weighted shuffle].include?(mode)
+        raise ArgumentError, "channel_order must be :priority, :weighted, or :shuffle"
       end
 
-      @queue_mode = mode
+      @channel_order = mode
     end
 
-    def strict
-      queue_mode == :strict
+    def prioritized?
+      channel_order == :priority
     end
 
-    def strict=(value)
-      self.queue_mode = value ? :strict : :weighted
+    def prioritized=(value)
+      self.channel_order = value ? :priority : :weighted
     end
 
-    def default_job_options=(options)
-      @default_job_options = Utilities.shareable_copy(
-        DEFAULT_JOB_OPTIONS.merge(Utilities.stringify_keys(options)),
+    def default_task_options=(options)
+      @default_task_options = Utilities.shareable_copy(
+        DEFAULT_TASK_OPTIONS.merge(Utilities.stringify_keys(options)),
       )
     end
 
@@ -111,26 +111,26 @@ module SolidJobs
     end
 
     def inspect
-      "#<#{self.class.name} concurrency=#{concurrency} queues=#{queues.inspect}>"
+      "#<#{self.class.name} concurrency=#{concurrency} channels=#{channels.inspect}>"
     end
 
     def ractor_snapshot
       Utilities.shareable_copy(
         redis_config: redis_config,
         concurrency: concurrency,
-        queues: queue_entries,
-        queue_mode: queue_mode,
+        channels: channel_entries,
+        channel_order: channel_order,
         reliable_fetch: reliable_fetch,
-        default_job_options: default_job_options,
+        default_task_options: default_task_options,
         on_complex_arguments: on_complex_arguments,
         poll_interval_average: poll_interval_average,
         shutdown_timeout: shutdown_timeout,
-        dead_max_jobs: dead_max_jobs,
-        dead_timeout: dead_timeout,
+        discarded_limit: discarded_limit,
+        discarded_retention: discarded_retention,
         retry_base_delay: retry_base_delay,
         retry_max_delay: retry_max_delay,
-        client_middleware: client_middleware.snapshot,
-        server_middleware: server_middleware.snapshot,
+        publish_interceptors: publish_interceptors.export,
+        execute_interceptors: execute_interceptors.export,
       )
     end
 
@@ -138,31 +138,31 @@ module SolidJobs
       config = new(
         redis: snapshot.fetch(:redis_config),
         concurrency: snapshot.fetch(:concurrency),
-        queues: snapshot.fetch(:queues),
+        channels: snapshot.fetch(:channels),
       )
-      config.queue_mode = snapshot.fetch(:queue_mode)
+      config.channel_order = snapshot.fetch(:channel_order)
       config.reliable_fetch = snapshot.fetch(:reliable_fetch)
-      config.default_job_options = snapshot.fetch(:default_job_options)
+      config.default_task_options = snapshot.fetch(:default_task_options)
       config.on_complex_arguments = snapshot.fetch(:on_complex_arguments)
       config.poll_interval_average = snapshot.fetch(:poll_interval_average)
       config.shutdown_timeout = snapshot.fetch(:shutdown_timeout)
-      config.dead_max_jobs = snapshot.fetch(:dead_max_jobs)
-      config.dead_timeout = snapshot.fetch(:dead_timeout)
+      config.discarded_limit = snapshot.fetch(:discarded_limit)
+      config.discarded_retention = snapshot.fetch(:discarded_retention)
       config.retry_base_delay = snapshot.fetch(:retry_base_delay)
       config.retry_max_delay = snapshot.fetch(:retry_max_delay)
-      config.client_middleware.restore(snapshot.fetch(:client_middleware))
-      config.server_middleware.restore(snapshot.fetch(:server_middleware))
+      config.publish_interceptors.import(snapshot.fetch(:publish_interceptors))
+      config.execute_interceptors.import(snapshot.fetch(:execute_interceptors))
       config
     end
 
     private
 
-    def normalize_queues(values)
+    def normalize_channels(values)
       Array(values).map do |value|
         name, weight = value.is_a?(Array) ? value : [value, 1]
         name = String(name)
         weight = Integer(weight)
-        raise ArgumentError, "Queue weight must be positive" unless weight.positive?
+        raise ArgumentError, "Channel weight must be positive" unless weight.positive?
 
         [name.freeze, weight].freeze
       end