wurk 1.0.1 → 1.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc76b5c62f729370d36c966fdbd391aa77bc0cdd9edfc64148024351a52e3191
-  data.tar.gz: 7293ddf887066f715c5263ea9eceb92b5c05bc5a8324651fa857cc4b2486f215
+  metadata.gz: 4f6df1c551958881248c0b6a97709e2a4999ec57f976cac37371d7c3e1c5d4e7
+  data.tar.gz: 450a316b29bada67e8deac2f1411ec1b084f57a2af48e752800b5aed01c9a0af
 SHA512:
-  metadata.gz: 0c571b8c549c76c48f12aa7bdc5d249cbcd1fed5f17f08ad96a4621d836e02c9bd587b0d0d22c9e713fa90778a1e48c065063d5d3deb6ca9e109e5bee606430a
-  data.tar.gz: 6c0056e1f4b18f4d63ecb5a5b790fdf2d81ea1cc2a650af8fde6c901181bf858cf602c21b689cd363869cd0301e9981eb3707f2f8a69335f1b9ba7dfa995a355
+  metadata.gz: 077cad32a71630367889448188e4bcaa59ed16b5853f37caf01efa5f907c939a4937d04fccb8df21eb256d9b685a50c2dce01cd041e5c5870573ee4c77eb7ef5
+  data.tar.gz: ec16e8f19b58332974d0e38cdb5ecb665b508698465435de29014ce2ff395ff1b374a827b098bcdd22abf1db9dc36d4692c3900e6b8091c1c22b0ebb1be878d1

data/README.md

@@ -56,7 +56,10 @@ 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`.
 - **[Migrating from Sidekiq](#migrating-from-sidekiq)** — the one-line swap and what to expect.
 - **API reference (parity specs):** [Sidekiq OSS](https://github.com/developerz-ai/wurk/blob/main/docs/target/sidekiq-free.md) · [Pro](https://github.com/developerz-ai/wurk/blob/main/docs/target/sidekiq-pro.md) · [Enterprise](https://github.com/developerz-ai/wurk/blob/main/docs/target/sidekiq-ent.md) — the authoritative surface Wurk matches exactly.
 - **[Securing the dashboard](https://github.com/developerz-ai/wurk/blob/main/docs/dashboard.md)** · **[Metrics history](https://github.com/developerz-ai/wurk/blob/main/docs/metrics-history.md)**

data/app/controllers/wurk/api_controller.rb

@@ -44,7 +44,7 @@ module Wurk
     def meta
       config = ::Wurk::Web.config
       render json: {
-        read_only: config.read_only?,
+        read_only: config.read_only? || !mutations_authorized?(config),
         read_only_message: config.read_only_message,
         custom_tabs: config.custom_tabs
       }
@@ -294,6 +294,27 @@ module Wurk
 
     private
 
+    # Engine-relative path probed as a representative mutation. Must be a real
+    # mutating route (POST /api/retries — bulk retry/delete/kill) so that a
+    # path-sensitive hook resolves it the same way the Authorization middleware
+    # will resolve the actual mutation. Probing `request.path_info` (which here
+    # is the GET /api/meta path) would let such a hook allow the probe while
+    # still 403ing real mutations, reviving the "button shows, then 403s" gap.
+    MUTATION_PROBE_PATH = '/api/retries'
+
+    # Per-request read-only signal for the SPA. When a registered authorization
+    # hook would reject a *mutating* request for this user (e.g. a viewer role
+    # that may GET but not retry/kill), report `read_only` so the SPA hides the
+    # destructive actions — the Authorization middleware already 403s the
+    # mutation itself, this just stops the buttons from showing. With no hook
+    # registered, `authorized?` is always true, so this is a no-op and the flag
+    # keeps reflecting the global read-only mode. Probes POST on a canonical
+    # mutating path (SAFE_METHODS are GET/HEAD/OPTIONS) so a path-sensitive hook
+    # answers for a real mutation, not the GET /api/meta request carrying it.
+    def mutations_authorized?(config)
+      config.authorized?(request.env, 'POST', MUTATION_PROBE_PATH)
+    end
+
     # Resolves a single entry by "<score>|<jid>" key and applies a whitelisted
     # action. 400 on an unknown action, 404 when the key matches nothing (e.g.
     # the entry was already retried/deleted from another tab).

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) }
@@ -153,13 +153,27 @@ module Wurk
       fetcher
     end
 
+    # Accepts both the CLI/string form (`"name"` / `"name,weight"`) and the
+    # nested-array form Sidekiq's YAML produces for weighted queues
+    # (`:queues: - [critical, 2]` parses to `["critical", 2]`). Without the Array
+    # branch a real sidekiq.yml crashes at boot with `Integer(): " 2]"` (#241).
     def parse_queue_entry(entry)
+      if entry.is_a?(::Array)
+        raise ArgumentError, "queue entry must be `[name]` or `[name, weight]`: `#{entry}`" if entry.size > 2
+
+        return parse_pair_queue_entry(entry[0], entry[1], entry)
+      end
+
       qname, weight_str = entry.to_s.split(',', 2)
-      qname = qname.to_s.strip
+      parse_pair_queue_entry(qname, weight_str, entry)
+    end
+
+    def parse_pair_queue_entry(name, weight, entry)
+      qname = name.to_s.strip
       raise ArgumentError, "queue name cannot be empty: `#{entry}`" if qname.empty?
-      return [qname, 0] if weight_str.nil?
+      return [qname, 0] if weight.nil?
 
-      weight = Integer(weight_str)
+      weight = Integer(weight)
       raise ArgumentError, "queue weight must be > 0: `#{entry}`" if weight <= 0
 
       [qname, weight]

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

@@ -48,7 +48,12 @@ module Wurk
     def initialize(config, embedded: false)
       @config = config
       @embedded = embedded
+      # Two separate flags, deliberately. @done = "quieted" (stop fetching, stay
+      # alive, report quiet=true). @stopped = "shutting down" (terminate the
+      # heartbeat loop). Quiet must NOT stop the heartbeat — otherwise a quieted
+      # process never publishes quiet=true and expires out of the live set (#236).
       @done = false
+      @stopped = false
       @managers = config.capsules.values.map { |cap| Manager.new(cap) }
       @poller = build_poller
       @cron_poller = build_cron_poller
@@ -127,6 +132,7 @@ module Wurk
       # CAS-release the cluster lock now (planned shutdown) so a follower can
       # take over immediately instead of waiting out the TTL.
       @leader&.stop
+      stop_heartbeat
       clear_heartbeat
       fire_event(:exit, reverse: true)
     end
@@ -217,11 +223,30 @@ module Wurk
       @health_server&.stop
     end
 
-    # Heartbeat thread loop. `safe_thread` already wraps exceptions; we
-    # exit the loop the moment `stop` flips @done so the thread doesn't
-    # outlive the shutdown.
+    # Terminate the heartbeat loop and wait for it to exit before clear_heartbeat
+    # removes us from the `processes` SET — otherwise a final in-flight beat could
+    # SADD us back right after the SREM. Wakes the thread out of its BEAT_PAUSE
+    # sleep so shutdown isn't delayed up to a full interval.
+    def stop_heartbeat
+      @stopped = true
+      thread = @heartbeat_thread
+      return unless thread
+
+      begin
+        thread.wakeup
+      rescue ThreadError
+        nil
+      end
+      thread.join(BEAT_PAUSE)
+    end
+
+    # Heartbeat thread loop. `safe_thread` already wraps exceptions. Loops on
+    # `@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.
     def start_heartbeat
-      until @done
+      until @stopped
         heartbeat
         sleep BEAT_PAUSE
       end

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/railtie.rb

@@ -36,7 +36,25 @@ module Wurk
     # and the swarm boot. Console mode is detected reliably here — the console
     # command file defines ::Rails::Console before initializers run.
     def self.skip_boot?
-      ENV['WURK_DISABLED'] == '1' || defined?(::Rails::Console) || ::Rails.env.test?
+      ENV['WURK_DISABLED'] == '1' ||
+        building? ||
+        defined?(::Rails::Console) ||
+        ::Rails.env.test?
+    end
+
+    # A build/precompile step must never fork the swarm (#247). The default
+    # Rails Dockerfile runs `SECRET_KEY_BASE_DUMMY=1 ./bin/rails
+    # assets:precompile`; that loads `:environment` → fires after_initialize,
+    # but there's no Redis during `docker build`, so a fork would hang/fail the
+    # build. Same for other env-loading rake tasks (db:prepare, db:migrate).
+    # The real server path is unaffected: `rails server` / `puma` boot through
+    # Rails::Command, not Rake, and don't set the dummy secret.
+    def self.building?
+      return true if ENV.key?('SECRET_KEY_BASE_DUMMY')
+
+      defined?(::Rake) && ::Rake.application.top_level_tasks.any?
+    rescue StandardError
+      false
     end
   end
 end

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.1"
+  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

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
 # Standalone entry point. Loading "wurk" must work without Rails.
-# The engine and railtie live under "wurk/rails" and are only loaded
-# when the host app opts in.
+# The engine and railtie live under "wurk/rails"; they're auto-loaded at the
+# end of this file when Rails is present (drop-in parity, #246), and stay
+# unloaded otherwise so a no-Rails boot pulls in zero Rails code.
 
 require_relative 'wurk/version'
 require_relative 'wurk/keys'
@@ -71,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
 
@@ -280,3 +293,24 @@ require_relative 'wurk/api/fast'
 # fully defined first. compat.rb only redefines names, it does not gate
 # behavior, so trailing the load order is safe.
 require_relative 'wurk/compat'
+
+# Drop-in parity (#246): stock Sidekiq auto-loads its Rails integration when
+# Rails is present (`lib/sidekiq.rb`: `require "sidekiq/rails" if
+# defined?(Rails::Engine)`). Without the equivalent here, a host that follows
+# the README/migration guide with a plain `gem "wurk"` (no `require:`) boots
+# with the engine/railtie unloaded, so the `:wurk` / `:sidekiq` ActiveJob
+# adapter constant is never defined and `config.active_job.queue_adapter =
+# :wurk` raises NameError during the railtie phase. Loading the engine here
+# (idempotent with an explicit `require "wurk/rails"`) closes that gap while
+# keeping standalone, no-Rails boot fully Rails-free.
+#
+# Also gate on ActionDispatch::Routing::RouteSet: the engine's class body calls
+# `isolate_namespace Wurk`, which under railties >= 8.1 eager-reads
+# `ActionDispatch::Routing::RouteSet` to set the engine's @route_set_class.
+# Ecosystem test helpers (sidekiq-cron, …) load `rails/engine/railties` for the
+# railtie API alone — Rails::Engine is defined but ActionDispatch isn't — so a
+# bare `defined?(Rails::Engine)` check would crash with `uninitialized constant
+# Rails::Engine::Configuration::ActionDispatch` mid-`require "sidekiq"`. In a
+# real Rails host both are loaded by `rails/all` before Bundler.require, so the
+# stricter gate is invisible there.
+require_relative 'wurk/rails' if defined?(Rails::Engine) && defined?(::ActionDispatch::Routing::RouteSet)