whoosh 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dcdd58c23ddbf6deaa47e53584d661eaad24ac247734aa7bf9cb3a3b3222aae3
-  data.tar.gz: cb40914a6bcc3ed0bd53108320278b8cb339d00593ec5a8c312024aacc78c13f
+  metadata.gz: 03b756c310f71435839a3628bfdfa9499bb70869b9475e75eb6cce861caa9583
+  data.tar.gz: a848d792014e80cc6bee413ad14277881895a62a40854644f3a088bfe0ea164a
 SHA512:
-  metadata.gz: 0f14ef114d78e7b220ad6afb8cbe90e2a5b9ff9493f1e549cb016c29f80c87b7e76bd281332f0244df04f79c7f0a63fc547e3892e00331f952a387fd008ca1db
-  data.tar.gz: 55b556be2c0d39472350653331af872f16afd3f34fa1535d252f5cb033fffea60a57542a88dfb6cfd49f13933f77b6c9c7dda3c500878dbe8a0d32ff596fbc13
+  metadata.gz: b764fa79a9e8297c66e0ce0c56be1127c1d1780ccb3840a0868a55841c4cb1108efffeff90cdaf4105a7df9259764aff7a8afe1047a42809e0c039b1e74be11d
+  data.tar.gz: 297cc80e8ca6ba22df946e07204f114bda7634480f5af72520caa0bdfde7b8604e6b66bf1b081f3527bede997a320b9ffc1b44c14fba21c2a05e5778101451c5

data/README.md

@@ -337,14 +337,65 @@ whoosh db status              # migration status
 
 ## Performance
 
-| Benchmark | Result |
-|-----------|--------|
-| Simple JSON endpoint | **406K req/s** |
-| Schema-validated endpoint | **115K req/s** |
-| Router lookup (static) | **6.1M lookups/s** |
+### HTTP Benchmark: `GET /health → {"status":"ok"}`
+
+> Apple Silicon arm64, 12 cores. [Full benchmark suite](benchmarks/comparison/)
+
+**Single process** (fair 1:1 comparison):
+
+| Framework | Language | Server | Req/sec |
+|-----------|----------|--------|---------|
+| Fastify | Node.js 22 | built-in | 69,200 |
+| **Whoosh** | Ruby 3.4 +YJIT | **Falcon** | **24,400** |
+| **Whoosh** | Ruby 3.4 +YJIT | Puma (5 threads) | **15,500** |
+| FastAPI | Python 3.13 | uvicorn | 8,900 |
+| Sinatra | Ruby 3.4 | Puma (5 threads) | 7,100 |
+| PHP (raw) | PHP 8.5 | built-in | 2,000 |
+
+> Whoosh + Falcon is **2.7x faster** than FastAPI single-core. Whoosh + Puma is **1.7x faster** than FastAPI. Use Falcon (recommended) for best performance.
+
+**Multi-worker** (production deployment):
+
+| Framework | Language | Server | Req/sec |
+|-----------|----------|--------|---------|
+| **Whoosh** | Ruby 3.4 +YJIT | **Falcon (4 workers)** | **87,400** |
+| Fastify | Node.js 22 | built-in (single thread) | 69,200 |
+| **Whoosh** | Ruby 3.4 +YJIT | Puma (4w×4t) | **52,500** |
+| Roda | Ruby 3.4 | Puma (4w×4t) | 14,700 |
+
+> **Note:** Fastify is single-threaded by design (Node.js event loop). It can scale via `cluster` module but was not tested in that mode. Whoosh + Falcon with 4 workers uses 4 cores.
+
+### Real-World Benchmark: `GET /users/:id` from PostgreSQL (1000 rows)
+
+**Single process:**
+
+| Framework | Language | Req/sec |
+|-----------|----------|---------|
+| Fastify + pg | Node.js 22 | 36,900 |
+| **Whoosh + Falcon (fiber PG pool)** | Ruby 3.4 +YJIT | **13,400** |
+| **Whoosh + Puma (Sequel)** | Ruby 3.4 +YJIT | **8,600** |
+| Roda + Puma | Ruby 3.4 | 6,700 |
+| Sinatra + Puma | Ruby 3.4 | 4,400 |
+| FastAPI + uvicorn | Python 3.13 | 2,400 |
+
+**Multi-worker (PostgreSQL):**
+
+| Framework | Language | Req/sec |
+|-----------|----------|---------|
+| **Whoosh + Falcon (4 workers, fiber PG pool)** | Ruby 3.4 +YJIT | **45,900** |
+| Fastify (single thread) | Node.js 22 | 36,900 |
+
+> Whoosh + Falcon with fiber-aware PG pool is **5.6x faster** than FastAPI. Multi-worker Falcon **beats Fastify by 24%** on real PostgreSQL workloads.
+
+### Micro-benchmarks
+
+| Component | Throughput |
+|-----------|-----------|
+| Router lookup (static, cached) | **6.1M ops/s** |
+| JSON encode (Oj) | **5.4M ops/s** |
 | Framework overhead | **~2.5µs per request** |
 
-Optimizations: YJIT auto-enabled, Oj JSON auto-detected (5-10x faster), O(1) static route cache, pre-frozen headers, compiled middleware chain.
+Optimizations: YJIT auto-enabled, Oj JSON auto-detected, O(1) static route cache, compiled middleware chain, pre-frozen headers.
 
 ## Configuration
 

data/lib/whoosh/app.rb

@@ -276,8 +276,10 @@ module Whoosh
         register_doc_routes if @config.docs_enabled?
         register_metrics_route
         @router.freeze!
-        inner = method(:handle_request)
-        app = @middleware_stack.build(inner)
+
+        # Compile the entire middleware + handler into a single lambda
+        # This eliminates 4x nested method calls per request
+        app = build_compiled_handler
         start_job_workers
         @shutdown.register { @di.close_all }
         @shutdown.register { @mcp_manager.shutdown_all }
@@ -301,7 +303,7 @@ module Whoosh
     end
 
     def auto_configure_jobs
-      backend = Jobs::MemoryBackend.new
+      backend = Jobs.build_backend(@config.data)
       Jobs.configure(backend: backend, di: @di)
     end
 
@@ -319,7 +321,7 @@ module Whoosh
         worker = Jobs::Worker.new(
           backend: Jobs.backend, di: @di,
           max_retries: max_retries, retry_delay: retry_delay,
-          instrumentation: @instrumentation
+          instrumentation: @instrumentation, logger: @logger
         )
         thread = Thread.new { worker.run_loop }
         thread.abort_on_exception = false
@@ -368,6 +370,78 @@ module Whoosh
       @middleware_stack.use(Middleware::RequestLogger, logger: @logger, metrics: @metrics)
     end
 
+    # Compiled handler inlines all default middleware into a single lambda
+    # Eliminates nested method calls — ~3-4x faster than middleware stack
+    def build_compiled_handler
+      logger = @logger
+      metrics = @metrics
+      max_bytes = 1_048_576
+      security_headers = Middleware::SecurityHeaders::HEADERS
+
+      -> (env) {
+        # 1. RequestLimit — check content length
+        content_length = env["CONTENT_LENGTH"]&.to_i || 0
+        if content_length > max_bytes
+          return [413, { "content-type" => "application/json" },
+            [JSON.generate({ error: "request_too_large", max_bytes: max_bytes })]]
+        end
+
+        # 2. Request ID (from RequestLogger)
+        request_id = env["HTTP_X_REQUEST_ID"] || SecureRandom.uuid
+        env["whoosh.request_id"] = request_id
+
+        start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        # 3. CORS preflight
+        origin = env["HTTP_ORIGIN"]
+        if env["REQUEST_METHOD"] == "OPTIONS" && origin
+          cors_headers = {
+            "access-control-allow-methods" => "GET, POST, PUT, PATCH, DELETE, OPTIONS",
+            "access-control-allow-headers" => "Content-Type, Authorization, X-API-Key, X-Request-ID",
+            "access-control-max-age" => "86400",
+            "access-control-allow-origin" => "*",
+            "access-control-expose-headers" => "X-Request-ID",
+            "vary" => "Origin"
+          }
+          return [204, cors_headers, []]
+        end
+
+        # 4. Handle request (core)
+        status, headers, body = handle_request(env)
+
+        # Ensure headers are mutable (streaming returns frozen headers)
+        headers = headers.dup if headers.frozen?
+
+        # 5. Security headers (inline, no allocation)
+        security_headers.each { |k, v| headers[k] ||= v }
+
+        # 6. CORS headers
+        if origin
+          headers["access-control-allow-origin"] = "*"
+          headers["access-control-expose-headers"] = "X-Request-ID"
+          headers["vary"] = "Origin"
+        end
+
+        # 7. Request ID in response
+        headers["x-request-id"] = request_id
+
+        # 8. Logging + metrics
+        duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round(2)
+        logger.info("request_complete",
+          method: env["REQUEST_METHOD"], path: env["PATH_INFO"],
+          status: status, duration_ms: duration_ms, request_id: request_id)
+
+        if metrics
+          metrics.increment("whoosh_requests_total",
+            labels: { method: env["REQUEST_METHOD"], path: env["PATH_INFO"], status: status.to_s })
+          metrics.observe("whoosh_request_duration_seconds",
+            duration_ms / 1000.0, labels: { path: env["PATH_INFO"] })
+        end
+
+        [status, headers, body]
+      }
+    end
+
     def register_mcp_tools
       @router.routes.each do |route|
         next unless route[:metadata] && route[:metadata][:mcp]

data/lib/whoosh/cache.rb

@@ -1,4 +1,3 @@
-# lib/whoosh/cache.rb
 # frozen_string_literal: true
 
 module Whoosh
@@ -6,20 +5,21 @@ module Whoosh
     autoload :MemoryStore, "whoosh/cache/memory_store"
     autoload :RedisStore,  "whoosh/cache/redis_store"
 
+    # Auto-detect: REDIS_URL set → Redis, otherwise → Memory
     def self.build(config_data = {})
       cache_config = config_data["cache"] || {}
-      store = cache_config["store"] || "memory"
       default_ttl = cache_config["default_ttl"] || 300
+      redis_url = ENV["REDIS_URL"] || cache_config["url"]
 
-      case store
-      when "memory"
-        MemoryStore.new(default_ttl: default_ttl)
-      when "redis"
-        url = cache_config["url"] || "redis://localhost:6379"
-        pool_size = cache_config["pool_size"] || 5
-        RedisStore.new(url: url, default_ttl: default_ttl, pool_size: pool_size)
+      if redis_url && cache_config["store"] != "memory"
+        begin
+          RedisStore.new(url: redis_url, default_ttl: default_ttl)
+        rescue Errors::DependencyError
+          # Redis gem not installed, fall back to memory
+          MemoryStore.new(default_ttl: default_ttl)
+        end
       else
-        raise ArgumentError, "Unknown cache store: #{store}"
+        MemoryStore.new(default_ttl: default_ttl)
       end
     end
   end

data/lib/whoosh/cli/project_generator.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "securerandom"
 
 module Whoosh
   module CLI
@@ -13,19 +14,47 @@ module Whoosh
           FileUtils.mkdir_p(File.join(dir, d))
         end
 
+        jwt_secret = SecureRandom.hex(32)
+
         write(dir, "app.rb", app_rb(name))
         write(dir, "config.ru", config_ru)
-        write(dir, "Gemfile", gemfile(full: full))
-        write(dir, "Rakefile", "require \"rspec/core/rake_task\"\nRSpec::Core::RakeTask.new(:spec)\ntask default: :spec\n")
+        write(dir, "Gemfile", gemfile(minimal: minimal, full: full))
+        write(dir, "Rakefile", rakefile)
         write(dir, "config/app.yml", app_yml(name))
-        write(dir, "config/plugins.yml", plugins_yml_template)
+        write(dir, "config/plugins.yml", plugins_yml)
         write(dir, "endpoints/health.rb", health_endpoint)
         write(dir, "schemas/health.rb", health_schema)
         write(dir, "test/test_helper.rb", test_helper)
-        write(dir, ".env.example", env_example_template)
-        write(dir, "Dockerfile", dockerfile_template)
-        write(dir, ".dockerignore", dockerignore_template)
-        puts "Created #{name}/ — run `cd #{name} && bundle install && whoosh server`"
+        write(dir, ".env", env_file(jwt_secret))
+        write(dir, ".env.example", env_example)
+        write(dir, ".gitignore", gitignore)
+        write(dir, ".rspec", rspec_config)
+        write(dir, "Dockerfile", dockerfile)
+        write(dir, ".dockerignore", dockerignore)
+        write(dir, "README.md", readme(name))
+
+        # Create empty SQLite DB directory
+        FileUtils.mkdir_p(File.join(dir, "db"))
+
+        # Auto-run bundle install
+        puts "Created #{name}/"
+        puts ""
+        Dir.chdir(dir) do
+          puts "Installing dependencies..."
+          system("bundle install --quiet")
+        end
+        puts ""
+        puts "  #{name}/ is ready!"
+        puts ""
+        puts "  cd #{name}"
+        puts "  whoosh s            # start server at http://localhost:9292"
+        puts "  whoosh s --reload   # start with hot reload"
+        puts ""
+        puts "  http://localhost:9292/health    # health check"
+        puts "  http://localhost:9292/healthz   # health probes"
+        puts "  http://localhost:9292/docs      # Swagger UI"
+        puts "  http://localhost:9292/metrics   # Prometheus metrics"
+        puts ""
       end
 
       class << self
@@ -41,58 +70,147 @@ module Whoosh
 
             require "whoosh"
 
+            # Auto-enable YJIT + Oj for best performance
+            Whoosh::Performance.optimize!
+
             App = Whoosh::App.new
 
+            # --- API Documentation ---
             App.openapi do
-              title "#{name.capitalize} API"
+              title "#{name.gsub(/[-_]/, " ").split.map(&:capitalize).join(" ")} API"
               version "0.1.0"
             end
 
+            App.docs enabled: true, redoc: true
+
+            # --- Security ---
+            App.auth do
+              jwt secret: ENV["JWT_SECRET"], algorithm: :hs256, expiry: 3600
+            end
+
+            App.rate_limit do
+              default limit: 60, period: 60
+            end
+
+            # --- Health Check ---
+            App.health_check do
+              probe(:api) { true }
+            end
+
+            # --- Load Endpoints ---
             App.load_endpoints(File.join(__dir__, "endpoints"))
           RUBY
         end
 
         def config_ru
-          "# frozen_string_literal: true\n\nrequire_relative \"app\"\n\nrun App.to_rack\n"
+          <<~RUBY
+            # frozen_string_literal: true
+
+            require_relative "app"
+
+            run App.to_rack
+          RUBY
         end
 
-        def gemfile(full: false)
-          g = "source \"https://rubygems.org\"\n\ngem \"whoosh\"\n"
+        def gemfile(minimal: false, full: false)
+          g = <<~GEM
+            source "https://rubygems.org"
+
+            gem "whoosh"
+
+            # Server (Falcon recommended for best performance)
+            gem "falcon"
+
+            # Fast JSON (5-10x faster than stdlib)
+            gem "oj"
+
+            # Database
+            gem "sequel"
+            gem "sqlite3"
+          GEM
+
           if full
-            g += "\n# AI & NLP\ngem \"ruby_llm\"\ngem \"lingua-ruby\"\ngem \"ner-ruby\"\n\n# Database\ngem \"sequel\"\ngem \"sqlite3\"\n"
+            g += <<~GEM
+
+              # AI & NLP
+              gem "ruby_llm"
+              gem "lingua-ruby"
+              gem "ner-ruby"
+              gem "guardrails-ruby"
+            GEM
           end
-          g += "\ngroup :development, :test do\n  gem \"rspec\"\n  gem \"rack-test\"\nend\n"
-        end
 
-        def app_yml(name)
-          app_yml_template(name)
+          g += <<~GEM
+
+            group :development, :test do
+              gem "rspec"
+              gem "rack-test"
+            end
+          GEM
+
+          g
         end
 
-        def env_example_template
-          "# WHOOSH_PORT=9292\n# WHOOSH_ENV=development\n# DATABASE_URL=sqlite://db/development.sqlite3\n# REDIS_URL=redis://localhost:6379\n"
+        def rakefile
+          <<~RUBY
+            require "rspec/core/rake_task"
+            RSpec::Core::RakeTask.new(:spec)
+            task default: :spec
+          RUBY
         end
 
-        def app_yml_template(name)
+        def app_yml(name)
           <<~YAML
             app:
-              name: "#{name.capitalize} API"
+              name: "#{name.gsub(/[-_]/, " ").split.map(&:capitalize).join(" ")} API"
               port: 9292
               host: localhost
 
+            server:
+              type: falcon
+              workers: auto
+
             database:
               url: <%= ENV.fetch("DATABASE_URL", "sqlite://db/development.sqlite3") %>
               max_connections: 10
+              log_level: debug
 
             cache:
               store: memory
               default_ttl: 300
 
+            jobs:
+              backend: memory
+              workers: 2
+              retry: 3
+
             logging:
               level: info
               format: json
 
             docs:
               enabled: true
+
+            performance:
+              yjit: true
+          YAML
+        end
+
+        def plugins_yml
+          <<~YAML
+            # Plugin configuration
+            # Gems are auto-discovered from Gemfile.lock
+            # Configure or disable here:
+            #
+            # lingua:
+            #   languages: [en, id, ms]
+            #
+            # guardrails:
+            #   language_check:
+            #     enabled: true
+            #
+            # ner:
+            #   enabled: false
           YAML
         end
 
@@ -111,61 +229,176 @@ module Whoosh
         end
 
         def health_schema
-          "# frozen_string_literal: true\n\nclass HealthResponse < Whoosh::Schema\n  field :status, String, required: true, desc: \"Health status\"\n  field :version, String, desc: \"API version\"\nend\n"
+          <<~RUBY
+            # frozen_string_literal: true
+
+            class HealthResponse < Whoosh::Schema
+              field :status, String, required: true, desc: "Health status"
+              field :version, String, desc: "API version"
+            end
+          RUBY
         end
 
         def test_helper
-          "# frozen_string_literal: true\n\nrequire \"rack/test\"\nrequire_relative \"../app\"\n\nRSpec.configure do |config|\n  config.include Rack::Test::Methods\nend\n"
+          <<~RUBY
+            # frozen_string_literal: true
+
+            require "whoosh/test"
+            require_relative "../app"
+
+            RSpec.configure do |config|
+              config.include Whoosh::Test
+
+              def app
+                App.to_rack
+              end
+            end
+          RUBY
         end
 
-        def plugins_yml_template
-          <<~YAML
-            # Plugin configuration
-            # Uncomment and configure as needed:
-            #
-            # lingua:
-            #   languages: [en, id, ms]
-            #
-            # guardrails:
-            #   language_check:
-            #     enabled: true
-            #
-            # ner:
-            #   enabled: false
-          YAML
+        def env_file(jwt_secret)
+          <<~ENV
+            # Generated by whoosh new — do NOT commit this file
+            JWT_SECRET=#{jwt_secret}
+            WHOOSH_ENV=development
+            DATABASE_URL=sqlite://db/development.sqlite3
+          ENV
+        end
+
+        def env_example
+          <<~ENV
+            # Copy to .env and fill in values
+            JWT_SECRET=change_me_to_a_random_64_char_hex
+            WHOOSH_ENV=development
+            DATABASE_URL=sqlite://db/development.sqlite3
+            # REDIS_URL=redis://localhost:6379
+          ENV
+        end
+
+        def gitignore
+          <<~GIT
+            # Dependencies
+            /vendor/bundle
+            /.bundle
+
+            # Environment
+            .env
+            .env.local
+            .env.production
+
+            # Database
+            db/*.sqlite3
+
+            # Logs
+            /log/*
+            /tmp/*
+
+            # OS
+            .DS_Store
+            *.swp
+            *~
+
+            # IDE
+            .idea/
+            .vscode/
+            *.code-workspace
+
+            # Gems
+            *.gem
+            Gemfile.lock
+          GIT
         end
 
-        def dockerfile_template
+        def rspec_config
+          <<~RSPEC
+            --require spec_helper
+            --format documentation
+            --color
+            --order random
+          RSPEC
+        end
+
+        def dockerfile
           <<~DOCKERFILE
             FROM ruby:3.4-slim
 
             WORKDIR /app
 
-            # Install dependencies
+            # Install system dependencies
+            RUN apt-get update -qq && apt-get install -y build-essential libsqlite3-dev
+
+            # Install gems
             COPY Gemfile Gemfile.lock ./
             RUN bundle install --without development test
 
             # Copy app
             COPY . .
 
-            # Expose port
             EXPOSE 9292
 
-            # Start server
+            # Start with Falcon for best performance
             CMD ["bundle", "exec", "whoosh", "s", "-p", "9292", "--host", "0.0.0.0"]
           DOCKERFILE
         end
 
-        def dockerignore_template
+        def dockerignore
           <<~IGNORE
             .git
             .env
+            .env.*
             node_modules
             tmp
             log
             db/*.sqlite3
+            *.gem
+            .DS_Store
           IGNORE
         end
+
+        def readme(name)
+          title = name.gsub(/[-_]/, " ").split.map(&:capitalize).join(" ")
+          <<~MD
+            # #{title} API
+
+            Built with [Whoosh](https://github.com/johannesdwicahyo/whoosh) — AI-first Ruby API framework.
+
+            ## Quick Start
+
+            ```bash
+            whoosh s              # http://localhost:9292
+            whoosh s --reload     # hot reload
+            ```
+
+            ## Endpoints
+
+            | Method | Path | Description |
+            |--------|------|-------------|
+            | GET | /health | Health check |
+            | GET | /healthz | Health probes |
+            | GET | /docs | Swagger UI |
+            | GET | /redoc | ReDoc |
+            | GET | /openapi.json | OpenAPI spec |
+            | GET | /metrics | Prometheus metrics |
+
+            ## Development
+
+            ```bash
+            whoosh generate endpoint users       # create endpoint + schema + test
+            whoosh generate schema CreateUser     # create schema
+            whoosh generate model User name:string email:string
+            whoosh routes                         # list all routes
+            whoosh console                        # IRB with app loaded
+            bundle exec rspec                     # run tests
+            ```
+
+            ## Deploy
+
+            ```bash
+            docker build -t #{name} .
+            docker run -p 9292:9292 -e JWT_SECRET=your_secret #{name}
+            ```
+          MD
+        end
       end
     end
   end

data/lib/whoosh/job.rb

@@ -1,4 +1,3 @@
-# lib/whoosh/job.rb
 # frozen_string_literal: true
 
 module Whoosh
@@ -12,9 +11,41 @@ module Whoosh
         @dependencies || []
       end
 
+      def queue(name = nil)
+        if name
+          @queue_name = name.to_s
+        else
+          @queue_name || "default"
+        end
+      end
+
+      def retry_limit(n = nil)
+        if n
+          @retry_limit = n
+        else
+          @retry_limit
+        end
+      end
+
+      def retry_backoff(strategy = nil)
+        if strategy
+          @retry_backoff = strategy
+        else
+          @retry_backoff || :linear
+        end
+      end
+
       def perform_async(**args)
         Jobs.enqueue(self, **args)
       end
+
+      def perform_in(delay_seconds, **args)
+        Jobs.enqueue(self, run_at: Time.now.to_f + delay_seconds, **args)
+      end
+
+      def perform_at(time, **args)
+        Jobs.enqueue(self, run_at: time.to_f, **args)
+      end
     end
 
     def perform(**args)

data/lib/whoosh/jobs/memory_backend.rb

@@ -1,4 +1,3 @@
-# lib/whoosh/jobs/memory_backend.rb
 # frozen_string_literal: true
 
 module Whoosh
@@ -6,6 +5,7 @@ module Whoosh
     class MemoryBackend
       def initialize
         @queue = []
+        @scheduled = []
         @records = {}
         @mutex = Mutex.new
         @cv = ConditionVariable.new
@@ -13,14 +13,25 @@ module Whoosh
 
       def push(job_data)
         @mutex.synchronize do
-          @queue << job_data
+          if job_data[:run_at] && job_data[:run_at] > Time.now.to_f
+            @scheduled << job_data
+            @scheduled.sort_by! { |j| j[:run_at] }
+          else
+            @queue << job_data
+          end
           @cv.signal
         end
       end
 
       def pop(timeout: 5)
         @mutex.synchronize do
-          @cv.wait(@mutex, timeout) if @queue.empty?
+          # Promote scheduled jobs that are ready
+          promote_scheduled
+
+          if @queue.empty?
+            @cv.wait(@mutex, timeout)
+            promote_scheduled
+          end
           @queue.shift
         end
       end
@@ -34,12 +45,37 @@ module Whoosh
       end
 
       def size
+        @mutex.synchronize { @queue.size + @scheduled.size }
+      end
+
+      def pending_count
         @mutex.synchronize { @queue.size }
       end
 
+      def scheduled_count
+        @mutex.synchronize { @scheduled.size }
+      end
+
       def shutdown
         @mutex.synchronize { @cv.broadcast }
       end
+
+      private
+
+      def promote_scheduled
+        now = Time.now.to_f
+        ready = []
+        remaining = []
+        @scheduled.each do |job|
+          if job[:run_at] <= now
+            ready << job
+          else
+            remaining << job
+          end
+        end
+        @scheduled = remaining
+        @queue.concat(ready)
+      end
     end
   end
 end

data/lib/whoosh/jobs/redis_backend.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Whoosh
+  module Jobs
+    class RedisBackend
+      @redis_available = nil
+
+      def self.available?
+        if @redis_available.nil?
+          @redis_available = begin
+            require "redis"
+            true
+          rescue LoadError
+            false
+          end
+        end
+        @redis_available
+      end
+
+      def initialize(url:, prefix: "whoosh:jobs")
+        unless self.class.available?
+          raise Errors::DependencyError, "Jobs Redis backend requires the 'redis' gem"
+        end
+        @redis = Redis.new(url: url)
+        @prefix = prefix
+      end
+
+      def push(job_data)
+        serialized = Serialization::Json.encode(job_data)
+        if job_data[:run_at] && job_data[:run_at] > Time.now.to_f
+          # Scheduled: use sorted set with run_at as score
+          @redis.zadd("#{@prefix}:scheduled", job_data[:run_at], serialized)
+        else
+          @redis.lpush("#{@prefix}:queue:#{job_data[:queue] || "default"}", serialized)
+        end
+      end
+
+      def pop(timeout: 5, queues: ["default"])
+        # First, promote scheduled jobs
+        promote_scheduled
+
+        # Try each queue in priority order
+        queues.each do |queue|
+          result = @redis.rpop("#{@prefix}:queue:#{queue}")
+          if result
+            return Serialization::Json.decode(result).transform_keys(&:to_sym)
+          end
+        end
+
+        # Block-wait on default queue
+        result = @redis.brpop("#{@prefix}:queue:#{queues.first}", timeout: timeout)
+        if result
+          Serialization::Json.decode(result[1]).transform_keys(&:to_sym)
+        end
+      rescue => e
+        nil
+      end
+
+      def save(record)
+        serialized = Serialization::Json.encode(record)
+        @redis.set("#{@prefix}:record:#{record[:id]}", serialized, ex: 86400) # 24h TTL
+      end
+
+      def find(id)
+        raw = @redis.get("#{@prefix}:record:#{id}")
+        return nil unless raw
+        data = Serialization::Json.decode(raw)
+        data.transform_keys(&:to_sym)
+      end
+
+      def size
+        pending_count + scheduled_count
+      end
+
+      def pending_count
+        count = 0
+        @redis.keys("#{@prefix}:queue:*").each do |key|
+          count += @redis.llen(key)
+        end
+        count
+      rescue => e
+        0
+      end
+
+      def scheduled_count
+        @redis.zcard("#{@prefix}:scheduled")
+      rescue => e
+        0
+      end
+
+      def shutdown
+        @redis.close
+      rescue => e
+        # Already closed
+      end
+
+      private
+
+      def promote_scheduled
+        now = Time.now.to_f
+        # Get all jobs ready to run
+        ready = @redis.zrangebyscore("#{@prefix}:scheduled", "-inf", now.to_s)
+        ready.each do |raw|
+          # Remove from scheduled set
+          removed = @redis.zrem("#{@prefix}:scheduled", raw)
+          next unless removed
+
+          job_data = Serialization::Json.decode(raw)
+          queue = job_data["queue"] || "default"
+          @redis.lpush("#{@prefix}:queue:#{queue}", raw)
+        end
+      rescue => e
+        # Don't crash on promote errors
+      end
+    end
+  end
+end

data/lib/whoosh/jobs/worker.rb

@@ -1,15 +1,15 @@
-# lib/whoosh/jobs/worker.rb
 # frozen_string_literal: true
 
 module Whoosh
   module Jobs
     class Worker
-      def initialize(backend:, di: nil, max_retries: 3, retry_delay: 5, instrumentation: nil)
+      def initialize(backend:, di: nil, max_retries: 3, retry_delay: 5, instrumentation: nil, logger: nil)
         @backend = backend
         @di = di
         @max_retries = max_retries
         @retry_delay = retry_delay
         @instrumentation = instrumentation
+        @logger = logger
         @running = true
       end
 
@@ -33,13 +33,27 @@ module Whoosh
 
       def execute(job_data)
         id = job_data[:id]
+        class_name = job_data[:class_name]
+
+        # Skip scheduled jobs that aren't ready yet
+        if job_data[:run_at] && job_data[:run_at].to_f > Time.now.to_f
+          @backend.push(job_data)
+          return
+        end
+
         record = @backend.find(id) || {}
-        record = record.merge(status: :running, started_at: Time.now.to_f)
+        record = record.merge(id: id, status: :running, started_at: Time.now.to_f)
         @backend.save(record)
 
-        job_class = Object.const_get(job_data[:class_name])
+        @logger&.info("job_started", job_id: id, class: class_name)
+
+        job_class = Object.const_get(class_name)
         job = job_class.new
 
+        # Determine retry settings from job class or defaults
+        max_retries = job_class.respond_to?(:retry_limit) && job_class.retry_limit ? job_class.retry_limit : @max_retries
+        backoff_strategy = job_class.respond_to?(:retry_backoff) ? job_class.retry_backoff : :linear
+
         # Inject DI deps
         if @di && job_class.respond_to?(:dependencies)
           job_class.dependencies.each do |dep|
@@ -49,23 +63,43 @@ module Whoosh
           end
         end
 
-        args = job_data[:args].transform_keys(&:to_sym)
+        args = job_data[:args]
+        args = args.transform_keys(&:to_sym) if args.is_a?(Hash)
         result = job.perform(**args)
         serialized = Serialization::Json.decode(Serialization::Json.encode(result))
 
         @backend.save(record.merge(status: :completed, result: serialized, completed_at: Time.now.to_f))
+        @logger&.info("job_completed", job_id: id, class: class_name)
+
       rescue => e
-        record = @backend.find(id) || {}
+        record = @backend.find(id) || { id: id }
         retry_count = (record[:retry_count] || 0) + 1
 
-        if retry_count <= @max_retries
-          sleep(@retry_delay) if @retry_delay > 0
-          @backend.save(record.merge(retry_count: retry_count, status: :pending))
-          @backend.push(job_data)
+        if retry_count <= max_retries
+          # Non-blocking retry: re-enqueue with delay timestamp instead of sleeping
+          delay = calculate_delay(retry_count, backoff_strategy)
+          run_at = Time.now.to_f + delay
+          @backend.save(record.merge(retry_count: retry_count, status: :scheduled, run_at: run_at))
+          @backend.push(job_data.merge(run_at: run_at))
+          @logger&.warn("job_retry", job_id: id, class: class_name, retry_count: retry_count, delay: delay)
         else
           error = { message: e.message, backtrace: e.backtrace&.first(10)&.join("\n") }
-          @backend.save(record.merge(status: :failed, error: error, retry_count: retry_count, completed_at: Time.now.to_f))
+          @backend.save(record.merge(
+            status: :failed, error: error, retry_count: retry_count, completed_at: Time.now.to_f
+          ))
           @instrumentation&.emit(:job_failed, { job_id: id, error: error })
+          @logger&.error("job_failed", job_id: id, class: class_name, error: e.message)
+        end
+      end
+
+      def calculate_delay(retry_count, strategy)
+        case strategy
+        when :exponential
+          @retry_delay * (2**(retry_count - 1))  # 5, 10, 20, 40...
+        when :linear
+          @retry_delay * retry_count              # 5, 10, 15, 20...
+        else
+          @retry_delay
         end
       end
     end

data/lib/whoosh/jobs.rb

@@ -1,4 +1,3 @@
-# lib/whoosh/jobs.rb
 # frozen_string_literal: true
 
 require "securerandom"
@@ -6,6 +5,7 @@ require "securerandom"
 module Whoosh
   module Jobs
     autoload :MemoryBackend, "whoosh/jobs/memory_backend"
+    autoload :RedisBackend,  "whoosh/jobs/redis_backend"
     autoload :Worker,        "whoosh/jobs/worker"
 
     @backend = nil
@@ -23,16 +23,27 @@ module Whoosh
         !!@backend
       end
 
-      def enqueue(job_class, **args)
+      def enqueue(job_class, run_at: nil, **args)
         raise Errors::DependencyError, "Jobs not configured — boot a Whoosh::App first" unless configured?
+
         id = SecureRandom.uuid
+        queue_name = job_class.respond_to?(:queue) ? job_class.queue : "default"
         record = {
-          id: id, class_name: job_class.name, args: args, status: :pending,
-          result: nil, error: nil, retry_count: 0,
-          created_at: Time.now.to_f, started_at: nil, completed_at: nil
+          id: id,
+          class_name: job_class.name,
+          args: args,
+          queue: queue_name,
+          status: run_at ? :scheduled : :pending,
+          run_at: run_at,
+          result: nil,
+          error: nil,
+          retry_count: 0,
+          created_at: Time.now.to_f,
+          started_at: nil,
+          completed_at: nil
         }
         @backend.save(record)
-        @backend.push({ id: id, class_name: job_class.name, args: args })
+        @backend.push({ id: id, class_name: job_class.name, args: args, queue: queue_name, run_at: run_at })
         id
       end
 
@@ -41,6 +52,18 @@ module Whoosh
         @backend.find(id)
       end
 
+      # Build the right backend from config (auto-detect pattern)
+      def build_backend(config_data = {})
+        jobs_config = config_data["jobs"] || {}
+        redis_url = ENV["REDIS_URL"] || jobs_config["redis_url"]
+
+        if redis_url && jobs_config["backend"] != "memory"
+          RedisBackend.new(url: redis_url)
+        else
+          MemoryBackend.new
+        end
+      end
+
       def reset!
         @backend = nil
         @di = nil

data/lib/whoosh/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Whoosh
-  VERSION = "1.0.1"
+  VERSION = "1.1.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: whoosh
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Johannes Dwi Cahyo
@@ -199,6 +199,7 @@ files:
 - lib/whoosh/job.rb
 - lib/whoosh/jobs.rb
 - lib/whoosh/jobs/memory_backend.rb
+- lib/whoosh/jobs/redis_backend.rb
 - lib/whoosh/jobs/worker.rb
 - lib/whoosh/logger.rb
 - lib/whoosh/mcp/client.rb