whoosh 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dcdd58c23ddbf6deaa47e53584d661eaad24ac247734aa7bf9cb3a3b3222aae3
-  data.tar.gz: cb40914a6bcc3ed0bd53108320278b8cb339d00593ec5a8c312024aacc78c13f
+  metadata.gz: 6d739583e7066d3f04675dbd6eb4e17809226c909f5c7d4d226b7672957e4a88
+  data.tar.gz: 5f12610ddf11479be668f3b0dc88de6f6c3f5640620299ca3512f48ffaf14922
 SHA512:
-  metadata.gz: 0f14ef114d78e7b220ad6afb8cbe90e2a5b9ff9493f1e549cb016c29f80c87b7e76bd281332f0244df04f79c7f0a63fc547e3892e00331f952a387fd008ca1db
-  data.tar.gz: 55b556be2c0d39472350653331af872f16afd3f34fa1535d252f5cb033fffea60a57542a88dfb6cfd49f13933f77b6c9c7dda3c500878dbe8a0d32ff596fbc13
+  metadata.gz: 305d2ea3aac7ba3a22be62c52c996aca50956cce5a0983a8d38cc0f76a55a817c25bdb3fe8877127752a0f3d1e3d81d894c80dc395ae4da39d562d2fad58098f
+  data.tar.gz: 2cd02f1ab2374bd1334d6dc6bab05fc460e108081eadb8119c9082af41f522c7fb5a8e7f63781b9451aeb319cd001522b7d6998290c662b3c8dbf0706ac03308

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 }
@@ -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/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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: whoosh
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
 platform: ruby
 authors:
 - Johannes Dwi Cahyo