wurk 1.0.3 → 1.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 000bd71bc3b9148d1f4250d32ebe25e300beee9f384b013ed3efabf2f778b1ce
-  data.tar.gz: eec8ea9f45d0ef0ccc0b894515dd6711adf08054757e0475178b45ed8ec81c37
+  metadata.gz: 4f6df1c551958881248c0b6a97709e2a4999ec57f976cac37371d7c3e1c5d4e7
+  data.tar.gz: 450a316b29bada67e8deac2f1411ec1b084f57a2af48e752800b5aed01c9a0af
 SHA512:
-  metadata.gz: 7b173cdc536f04367d2eea9b5c549d71f6fe7cbfa27095af3916dc690196421e45356bd663f35a1777a7b340ad57fe6c5b6be24aec3eb57aea3d128de30944a9
-  data.tar.gz: f89b858d93982f20efa5a1d79b8b2230736cf53bdd8b3d95d54fcc4c444bb90dc70822124d8ae80060b2110a68aec8116f807759bccc87b2478cd61872fa890a
+  metadata.gz: 077cad32a71630367889448188e4bcaa59ed16b5853f37caf01efa5f907c939a4937d04fccb8df21eb256d9b685a50c2dce01cd041e5c5870573ee4c77eb7ef5
+  data.tar.gz: ec16e8f19b58332974d0e38cdb5ecb665b508698465435de29014ce2ff395ff1b374a827b098bcdd22abf1db9dc36d4692c3900e6b8091c1c22b0ebb1be878d1

data/README.md

@@ -56,6 +56,7 @@ Plus Wurk extras: a worker topology DSL, a Kubernetes liveness/readiness listene
 ## Documentation
 
 - **[Website](https://developerz-ai.github.io/wurk/)** · **[Wiki / full docs](https://github.com/developerz-ai/wurk/wiki)** — the pitch, install, and the complete guide.
+- **[API reference (YARD)](https://developerz-ai.github.io/wurk/api/)** — generated docs for the public classes (`Wurk::Worker`, `Wurk::Client`, `Wurk::Configuration`, `Wurk::Batch`, `Wurk::Limiter`, `Wurk::Unique`, and the `Sidekiq::*` aliases). Machine-readable map for AI agents: **[llms.txt](https://developerz-ai.github.io/wurk/llms.txt)**.
 - **[Getting started & architecture](https://github.com/developerz-ai/wurk/blob/main/docs/idea/01-overview.md)** — how the swarm, manager, fetcher, and processor fit together.
 - **[Starting the worker](https://github.com/developerz-ai/wurk/blob/main/docs/running.md)** — Rails auto-start, the `wurk`/`wurkswarm` runners, and running standalone without Rails.
 - **[Active Job adapter](https://github.com/developerz-ai/wurk/blob/main/docs/active-job.md)** — run `ActiveJob`/`deliver_later` on Wurk with `queue_adapter = :wurk`.

data/lib/generators/wurk/install/templates/wurk.rb

@@ -16,9 +16,10 @@ Wurk.configure_server do |config|
   # Seconds to let in-flight jobs finish on shutdown (Sidekiq-compatible key):
   # config[:timeout] = 25
 
-  # The default is a single worker process (fork). To run several, declare a
-  # topology — `flat` spawns N identical forks; use `slot`s for dedicated
-  # queues. See docs/idea/03-process-model.md.
+  # By default Wurk forks one worker process per CPU core (set WURK_COUNT, or
+  # SIDEKIQ_COUNT, to override). For full control declare a topology — `flat`
+  # spawns N identical forks; use `slot`s for dedicated queues. Total in-flight
+  # jobs = forks × concurrency. See docs/idea/03-process-model.md.
   # config.topology = Wurk::Topology.flat(count: 2, queues: %w[critical default low], concurrency: 10)
 end
 

data/lib/wurk/batch.rb

@@ -9,6 +9,15 @@ module Wurk
   # Sidekiq Pro Batches. Group jobs, attach success/complete/death callbacks,
   # track progress. Spec: docs/target/sidekiq-pro.md §2.
   #
+  # @example Define a batch with a success callback
+  #   batch = Sidekiq::Batch.new
+  #   batch.description = "Nightly import"
+  #   batch.on(:success, ImportCallback, "user_id" => user.id)
+  #   batch.jobs do
+  #     rows.each { |r| ImportRowJob.perform_async(r.id) }
+  #   end
+  #   batch.bid   # => the batch id, persisted in Redis
+  #
   # Lifecycle:
   #   1. `Batch.new` allocates a fresh BID; the batch is `mutable?` until the
   #      first `#jobs` block flushes — that flush HSETs the core hash, ZADDs

data/lib/wurk/capsule.rb

@@ -38,7 +38,7 @@ module Wurk
     #   %w[high default low]        → mode :strict,   weights all 0
     #   %w[high,3 default,2 low,1]  → mode :weighted, weights {q=>w}
     #   %w[a,1 b,1 c,1]             → mode :random,   weights all 1
-    # @queues is expanded by weight so a uniform shuffle gives weighted
+    # `@queues` is expanded by weight so a uniform shuffle gives weighted
     # fairness (e.g. ["high","high","high","default","default","low"]).
     def queues=(val)
       parsed = Array(val).map { |entry| parse_queue_entry(entry) }

data/lib/wurk/cli.rb

@@ -398,10 +398,22 @@ module Wurk
 
     def boot_rails_application(require_path)
       require 'rails'
+      define_active_job_adapter
       require ::File.expand_path("#{require_path}/config/environment.rb")
       @config[:tag] ||= default_tag(::Rails.root) if defined?(::Rails) && ::Rails.respond_to?(:root)
     end
 
+    # Standalone mode never loads the engine, so the ActiveJob `:wurk` /
+    # `:sidekiq` adapters it normally defines are absent. Define them BEFORE the
+    # app boots — an app with `config.active_job.queue_adapter = :wurk` resolves
+    # the adapter during environment boot, which otherwise raises `uninitialized
+    # constant WurkAdapter` (#253). `require` no-ops for a mounted-engine app
+    # that already loaded it, and the adapter file itself rescues a missing
+    # ActiveJob gem, so a non-ActiveJob app is unaffected.
+    def define_active_job_adapter
+      require_relative '../active_job/queue_adapters/wurk_adapter'
+    end
+
     def initialize_logger
       return unless @config[:verbose] || ENV['DEBUG_INVOCATION'] == '1'
 

data/lib/wurk/client.rb

@@ -7,7 +7,14 @@ require_relative 'lua'
 module Wurk
   # Enqueue interface. Pipelined LPUSH / ZADD writes against the canonical
   # Sidekiq Redis schema — never change keys, JSON shape, or score format here:
-  # wire-compat is sacred.
+  # wire-compat is sacred. Most apps enqueue through the {Wurk::Worker} DSL
+  # (`MyJob.perform_async`), which routes here; reach for Client directly only to
+  # push a raw job hash or to drive the bulk/scheduled path explicitly.
+  #
+  # @example Push a raw job hash
+  #   Wurk::Client.new.push("class" => "MyJob", "args" => [1, 2], "queue" => "default")
+  # @example Bulk enqueue in one round-trip
+  #   Wurk::Client.new.push_bulk("class" => "MyJob", "args" => [[1], [2], [3]])
   #
   # Spec: docs/target/sidekiq-free.md §7.
   class Client
@@ -36,6 +43,7 @@ module Wurk
       copy
     end
 
+    # @param item [Hash] job payload; must carry `class` and `args`, may carry `at`, `queue`, `jid`, etc.
     # @return [String, nil] jid; nil when client middleware halts the push.
     def push(item)
       normed  = normalize_item(item)

data/lib/wurk/compat.rb

@@ -5,6 +5,25 @@
 #
 # Spec: docs/target/sidekiq-{free,pro,ent}.md.
 
+# The `Sidekiq::*` compatibility namespace. Every public Wurk class is exposed
+# here under its Sidekiq name so an existing Sidekiq/Pro/Enterprise app runs on
+# Wurk after a one-line gem swap. `Sidekiq::Job` / `Sidekiq::Worker` are
+# {Wurk::Job} / {Wurk::Worker}; `Sidekiq.configure_server` is
+# {Wurk.configure_server}; `Sidekiq::Batch`, `Sidekiq::Limiter`,
+# `Sidekiq::Client`, `Sidekiq::Pro::Web`, `Sidekiq::Enterprise` all resolve to
+# their Wurk implementations. This alias surface is the drop-in contract and is
+# never broken.
+#
+# @example The same code targets Sidekiq or Wurk unchanged
+#   class MyJob
+#     include Sidekiq::Job
+#     def perform(id); end
+#   end
+#   Sidekiq.configure_server { |c| c.concurrency = 10 }
+#
+# @note `Sidekiq.pro?` and `Sidekiq.ent?` return `false` — Wurk ships the Pro/Ent
+#   features for free but advertises as OSS. Don't gate behavior on them.
+# @see https://github.com/developerz-ai/wurk/blob/main/docs/migrate-from-sidekiq.md Migration guide
 module Sidekiq
   # Version stamps mirror Sidekiq's OSS release Wurk targets for compat.
   # Third-party gems version-gate on these; raise the MAJOR only when the

data/lib/wurk/configuration.rb

@@ -112,8 +112,14 @@ module Wurk
 
     # --- Default capsule shortcuts ---------------------------------------
 
+    # @return [Integer] threads per worker process for the default capsule
+    #   (default 5). The *process* count is separate — set via `WURK_COUNT`
+    #   (defaults to the CPU count). With a single capsule, total in-flight
+    #   jobs = `WURK_COUNT × concurrency`; with multiple capsules see
+    #   {#total_concurrency} for the cluster aggregate.
     def concurrency = default_capsule.concurrency
 
+    # @param val [Integer] threads per worker process
     def concurrency=(val)
       default_capsule.concurrency = val
     end
@@ -251,7 +257,18 @@ module Wurk
 
     # Yields a Wurk::Cron::Manager so the host app can register periodic
     # jobs at boot. Manager state is shared per-process so multiple
-    # `config.periodic` blocks accumulate (matches Sidekiq Ent §2.1).
+    # `config.periodic` blocks accumulate (matches Sidekiq Ent §2.1). This is
+    # the native replacement for the `sidekiq-cron` gem.
+    #
+    # @example Register cron jobs at boot
+    #   Wurk.configure_server do |config|
+    #     config.periodic do |mgr|
+    #       mgr.register("*/5 * * * *", ReportJob)
+    #       mgr.register("0 0 * * *", NightlyJob, tz: "UTC")
+    #     end
+    #   end
+    # @yieldparam mgr [Wurk::Cron::Manager] call `mgr.register(cron, JobClass, **opts)`
+    # @return [Wurk::Cron::Manager]
     #
     # Spec: docs/target/sidekiq-ent.md §2.
     def periodic

data/lib/wurk/fetcher/reliable.rb

@@ -96,7 +96,7 @@ module Wurk
 
       # Prefixed queue keys (`queue:<name>`) in fetch order. Strict mode
       # preserves declaration order. Random/weighted shuffle each call —
-      # @queues is pre-expanded by weight in Capsule#queues=, so uniform
+      # `@queues` is pre-expanded by weight in Capsule#queues=, so uniform
       # shuffle yields weighted fairness; .uniq trims duplicates. Paused
       # queues are filtered after shuffle so the membership test runs on
       # the smallest possible set.

data/lib/wurk/launcher.rb

@@ -241,10 +241,10 @@ module Wurk
     end
 
     # Heartbeat thread loop. `safe_thread` already wraps exceptions. Loops on
-    # @stopped — NOT @done — so a *quieted* process keeps beating and publishes
+    # `@stopped` — NOT `@done` — so a *quieted* process keeps beating and publishes
     # `quiet=true` instead of vanishing from the live set (#236). Only `#stop`
-    # flips @stopped; its `Thread#wakeup` breaks the sleep so the loop re-checks
-    # @stopped and exits without waiting out the interval.
+    # flips `@stopped`; its `Thread#wakeup` breaks the sleep so the loop re-checks
+    # `@stopped` and exits without waiting out the interval.
     def start_heartbeat
       until @stopped
         heartbeat

data/lib/wurk/limiter/leaky.rb

@@ -5,7 +5,7 @@ require_relative 'base'
 module Wurk
   module Limiter
     # Leaky bucket: drain rate = bucket_size / drain ops/sec. Stored as a
-    # HASH of {level, last} — Lua compares level vs bucket_size after
+    # HASH of `{level, last}` — Lua compares level vs bucket_size after
     # leaking elapsed * drain_per_sec.
     class Leaky < Base
       WAIT_SLEEP = 0.05

data/lib/wurk/limiter.rb

@@ -11,6 +11,16 @@ module Wurk
   # clock skew across hosts doesn't matter inside one Redis. Spec:
   # docs/target/sidekiq-ent.md §1.
   #
+  # @example Throttle to 50 concurrent uses, waiting up to the default timeout
+  #   STRIPE = Sidekiq::Limiter.concurrent("stripe", 50)
+  #
+  #   class ChargeJob
+  #     include Sidekiq::Job
+  #     def perform(id)
+  #       STRIPE.within_limit { Stripe::Charge.create(...) }
+  #     end
+  #   end
+  #
   # Layout (one file per type under `lib/wurk/limiter/`):
   #   * `Limiter::Base` owns the metadata write (lmtr:{name}) + the global
   #     `lmtr-list` registration so the Web UI can list every limiter, and

data/lib/wurk/unique.rb

@@ -25,6 +25,22 @@ module Wurk
   # holding the owning JID. Scheduled jobs extend the TTL by the delay so
   # the lock covers the entire wait+execution window (§3.4).
   #
+  # This is the native replacement for the `sidekiq-unique-jobs` gem; see the
+  # migration guide for the `lock:` → `unique_until:` translation table.
+  #
+  # @example Enable globally, then declare per worker
+  #   Sidekiq::Enterprise.unique!   # activate the middleware once, at boot
+  #
+  #   class ChargeJob
+  #     include Sidekiq::Job
+  #     sidekiq_options unique_for: 10.minutes, unique_until: :success
+  #
+  #     # optional: customize the dedup key
+  #     def self.sidekiq_unique_context(job)
+  #       job["args"].first   # dedup on the first arg only
+  #     end
+  #   end
+  #
   # Spec: docs/target/sidekiq-ent.md §3.
   module Unique
     KEY_PREFIX = 'unique:'
@@ -131,7 +147,11 @@ module Wurk
     # (skip). Returns nil when uniqueness should be skipped.
     def self.coerce_ttl(value)
       return nil if value.nil? || value == false
-      return value if value.is_a?(Integer) && value.positive?
+      # `.to_i`, not `value`: ActiveSupport::Duration overrides `is_a?(Integer)`
+      # to return true (it delegates to its underlying value), so `1.hour` passes
+      # this guard — returning the raw Duration handed redis-client a non-Integer
+      # EX arg and raised TypeError at enqueue (#253).
+      return value.to_i if value.is_a?(Integer) && value.positive?
       return value.to_i if value.is_a?(Numeric)
       return value.to_i if duration_like?(value)
 

data/lib/wurk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Wurk
-  VERSION = "1.0.3"
+  VERSION = "1.0.4"
 end

data/lib/wurk/worker.rb

@@ -3,9 +3,27 @@
 require_relative 'worker/setter'
 
 module Wurk
-  # The user-facing DSL: `include Wurk::Worker` (aliased to Sidekiq::Worker).
-  # Owns `sidekiq_options`, `perform_async`, `perform_in`, `perform_at`,
-  # `set`, `sidekiq_retry_in`, etc.
+  # The user-facing job DSL. `include Wurk::Worker` — or its modern alias
+  # `Sidekiq::Job` / `Sidekiq::Worker` — onto a class to make it a background
+  # job. The class gains `sidekiq_options`, the `perform_*` enqueue methods,
+  # `set`, and the retry-hook DSL; each instance gains `jid`, `logger`,
+  # `interrupted?`, and the batch helpers.
+  #
+  # @example A minimal job
+  #   class HardJob
+  #     include Sidekiq::Job
+  #     sidekiq_options queue: "critical", retry: 5
+  #
+  #     def perform(user_id, opts = {})
+  #       # ... your work ...
+  #     end
+  #   end
+  #
+  #   HardJob.perform_async(42, "fast" => true)   # enqueue now
+  #   HardJob.perform_in(5.minutes, 42)           # enqueue later
+  #
+  # @see Wurk::Worker::ClassMethods the enqueue + options DSL added to the class
+  # @see https://github.com/developerz-ai/wurk/blob/main/docs/migrate-from-sidekiq.md Migration guide
   #
   # Spec: docs/target/sidekiq-free.md §6 (Sidekiq::Job).
   module Worker
@@ -65,7 +83,17 @@ module Wurk
       batch.valid?
     end
 
+    # Class-level DSL mixed into every job class by {Wurk::Worker}. These are
+    # the public enqueue and configuration entry points.
     module ClassMethods # rubocop:disable Metrics/ModuleLength
+      # Set per-class job options (merged over any inherited options).
+      #
+      # @example
+      #   sidekiq_options queue: "mailers", retry: 3, unique_for: 10.minutes
+      # @param opts [Hash] any of `queue:`, `retry:`, `dead:`, `backtrace:`,
+      #   `expires_in:`, `tags:`, `pool:`, `unique_for:`, … (see the migration
+      #   guide's sidekiq_options table for the full set)
+      # @return [Hash] the merged, string-keyed options hash
       def sidekiq_options(opts = {})
         merged = get_sidekiq_options.merge(opts.transform_keys(&:to_s))
         @sidekiq_options_hash = merged
@@ -92,24 +120,57 @@ module Wurk
         self.sidekiq_retries_exhausted_block = block
       end
 
+      # Enqueue the job to run as soon as a worker is free. Arguments are
+      # forwarded to `#perform` and must be JSON-serializable
+      # (string/number/bool/nil/array/hash).
+      #
+      # @example
+      #   EmailJob.perform_async(user.id, "welcome")
+      # @return [String, nil] the job id (jid), or nil if a client middleware
+      #   halted the push
       def perform_async(*)
         Wurk::Worker::Setter.new(self, {}).perform_async(*)
       end
 
+      # Run `#perform` synchronously in the current thread (no Redis). Useful in
+      # tests and for inline execution.
+      #
+      # @return [Object] the return value of `#perform`
       def perform_inline(*)
         new.perform(*)
       end
       alias perform_sync perform_inline
 
+      # Schedule the job for later. `perform_at` is an alias taking an absolute
+      # time; `perform_in` takes a relative interval.
+      #
+      # @example
+      #   ReminderJob.perform_in(1.hour, lead.id)
+      #   ReminderJob.perform_at(Time.now + 3600, lead.id)
+      # @param interval [Numeric, Time] seconds-from-now, or an absolute Time
+      # @return [String, nil] the job id (jid)
       def perform_in(interval, *)
         Wurk::Worker::Setter.new(self, {}).perform_in(interval, *)
       end
       alias perform_at perform_in
 
+      # Enqueue many jobs in one round-trip via the Lua bulk path.
+      #
+      # @example
+      #   ImportJob.perform_bulk([[1], [2], [3]])
+      # @param items [Array<Array>] one args array per job
+      # @return [Array<String>] the job ids, in order
       def perform_bulk(items, **)
         Wurk::Worker::Setter.new(self, {}).perform_bulk(items, **)
       end
 
+      # Return a per-call option carrier so a single enqueue can override
+      # class-level options (queue, scheduling, pool, …).
+      #
+      # @example
+      #   ReportJob.set(queue: "low").perform_async(account.id)
+      # @param opts [Hash] per-call overrides
+      # @return [Wurk::Worker::Setter]
       def set(opts)
         Wurk::Worker::Setter.new(self, opts)
       end

data/lib/wurk.rb

@@ -72,6 +72,18 @@ require_relative 'wurk/deploy'
 
 require 'json'
 
+# Wurk — a 100% API-compatible, free, faster drop-in for Sidekiq + Sidekiq Pro
+# + Sidekiq Enterprise. Same Redis key schema, same job JSON, same Ruby DSL;
+# real parallelism via a fork-based swarm. Every public class is also exposed
+# under its `Sidekiq::*` name (see {Sidekiq}).
+#
+# Start here:
+#   * {Wurk::Worker} / `Sidekiq::Job` — define and enqueue jobs.
+#   * {Wurk::Configuration} — `Wurk.configure_server { |config| ... }`; note
+#     `WURK_COUNT` (forked processes) × `concurrency` (threads) = total in-flight.
+#   * {Wurk::Batch}, {Wurk::Limiter}, {Wurk::Unique} — Pro/Enterprise features, free.
+#
+# @see https://github.com/developerz-ai/wurk/blob/main/docs/migrate-from-sidekiq.md Migration guide
 module Wurk
   class Error < StandardError; end