whoosh 1.3.0 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 589d3cd63bfe7cb2a7ae32d8de43c064eb0e9dadfae68ecb1907bea9a099cd7d
-  data.tar.gz: a18f684c03fa83b5e7e86febd6eca0bc79d01d5c3cf719b729118eea91510e9c
+  metadata.gz: 99edefedd7d17b1c477fcd07d7ba72b317560d670706ec1361c197df013a9834
+  data.tar.gz: d94a866bf3e588e64591b1e1e32e62db4b5fae74511420b5942e42a04eb1dc8a
 SHA512:
-  metadata.gz: 3ffb5d9e6d905e3914d9cf54738966c5d3ba625a89f33c8c2b3c98698f9a04ba1b6710584efa69917e24ef02b52b870f616a4ad6e6a7d631c4707319d1db7e47
-  data.tar.gz: e57044ee4ec0c6a1b872d85cd0abeb274ee3c260c46dcc38b925994a6b88c7b004188314c7b60e8e3a7ce5aef4198581c817fbd8870ceaca6ddbe20fce4abd75
+  metadata.gz: c2d1793270458869874e09f720c053eb3625b2943323bd1ff24a9e9620bebd3cbe9705fb1bde81cfe60211084f8d7a0862407548f1699a5f5a25c4bb392f764b
+  data.tar.gz: f86e8837a57fcbee513a514d6bf32d2901833187f038cd64d0b8bfb71897a97507c65ee5297af3ce92e940ee697d0443165efeda980a8fb1d8b3cb334a4ae89b

data/README.md

@@ -13,7 +13,7 @@
   <img src="https://img.shields.io/badge/ruby-%3E%3D%203.4.0-red" alt="Ruby">
   <img src="https://img.shields.io/badge/rack-3.0-blue" alt="Rack">
   <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
-  <img src="https://img.shields.io/badge/tests-509%20passing-brightgreen" alt="Tests">
+  <img src="https://img.shields.io/badge/tests-540%20passing-brightgreen" alt="Tests">
   <img src="https://img.shields.io/badge/overhead-2.5%C2%B5s-orange" alt="Performance">
 </p>
 
@@ -21,11 +21,11 @@
 
 ## Why Whoosh?
 
-- **AI-first** — MCP server built-in, LLM streaming, token tracking, plugin auto-discovery for 18+ AI gems
-- **Fast** — 2.5µs framework overhead, 406K req/s on simple JSON, YJIT + Oj auto-enabled
-- **Batteries included** — Auth, rate limiting, caching, background jobs, file uploads, pagination, metrics
-- **Zero config to start** — `whoosh new myapp && cd myapp && whoosh s`
-- **OpenAPI 3.1** — Swagger UI + ReDoc auto-generated from your routes and schemas
+- **AI-first** — Every app is an MCP server automatically. LLM wrapper with structured output, caching, and streaming. Vector search built-in. 18+ AI gem auto-discovery.
+- **Fast** — 2.5µs framework overhead, 87K req/s with Falcon. Beats Fastify on multi-worker PostgreSQL benchmarks.
+- **Batteries included** — Auth, rate limiting, caching, background jobs, file uploads, vector search, pagination, metrics, CI pipeline.
+- **Zero config to start** — `whoosh new myapp && cd myapp && whoosh s` — everything works.
+- **AI-agent friendly** — `whoosh describe` dumps your app as JSON for AI tools. Generated `CLAUDE.md` in every project. `whoosh check` catches mistakes before runtime.
 
 ## Install
 
@@ -130,6 +130,45 @@ app.access_control do
 end
 ```
 
+### AI / LLM Integration
+
+```ruby
+# Chat with any LLM (auto-detects ruby_llm gem)
+app.post "/chat" do |req, llm:|
+  { reply: llm.chat(req.body["message"]) }
+end
+
+# Structured output — LLM returns validated JSON
+app.post "/extract" do |req, llm:|
+  data = llm.extract(req.body["text"], schema: InvoiceSchema)
+  { invoice: data }
+end
+
+# RAG in 3 lines
+app.post "/ask" do |req, vectors:, llm:|
+  context = vectors.search("knowledge", vector: embed(req.body["q"]), limit: 5)
+  { answer: llm.chat(req.body["q"], system: "Context: #{context}") }
+end
+```
+
+### Vector Search
+
+```ruby
+app.post "/index" do |req, vectors:|
+  vectors.insert("docs", id: req.body["id"],
+    vector: req.body["embedding"],
+    metadata: { title: req.body["title"] })
+  { indexed: true }
+end
+
+app.post "/search" do |req, vectors:|
+  results = vectors.search("docs", vector: req.body["embedding"], limit: 10)
+  { results: results }
+end
+```
+
+In-memory by default (cosine similarity). Install `zvec` gem for production-grade HNSW index.
+
 ### LLM Streaming (OpenAI-compatible)
 
 ```ruby
@@ -153,16 +192,21 @@ end
 
 ### MCP (Model Context Protocol)
 
+**Every route is automatically an MCP tool.** No `mcp: true` needed.
+
 ```ruby
-# Any route with mcp: true becomes an MCP tool automatically
-app.post "/summarize", mcp: true, request: SummarizeRequest do |req|
+# These are all MCP tools automatically:
+app.post "/summarize", request: SummarizeRequest do |req|
   { summary: llm.summarize(req.body[:text]) }
 end
 
-# Groups propagate mcp: true to all child routes
-app.group "/tools", mcp: true do
-  post("/translate") { |req| { result: translate(req.body[:text]) } }
-  post("/analyze")   { |req| { result: analyze(req.body[:text]) } }
+app.post "/translate" do |req|
+  { result: translate(req.body["text"]) }
+end
+
+# Opt OUT with mcp: false for internal routes:
+app.get "/internal", mcp: false do
+  { debug: "not exposed as MCP tool" }
 end
 ```
 
@@ -319,9 +363,13 @@ whoosh new my_api             # scaffold project (with Dockerfile)
 whoosh s                      # start server (like rails s)
 whoosh s --reload             # hot reload on file changes
 whoosh routes                 # list all routes
+whoosh describe               # dump app as JSON (AI-friendly)
+whoosh check                  # validate config, catch mistakes
 whoosh console                # IRB with app loaded
+whoosh ci                     # lint + security + audit + tests + coverage
 whoosh worker                 # background job worker
 whoosh mcp                    # MCP stdio server
+whoosh mcp --list             # list all MCP tools
 
 whoosh generate endpoint chat       # endpoint + schema + test
 whoosh generate schema User         # schema file
@@ -335,6 +383,22 @@ whoosh db rollback            # rollback
 whoosh db status              # migration status
 ```
 
+## AI Agent DX
+
+Every `whoosh new` project includes a `CLAUDE.md` with all framework patterns, commands, and conventions — so AI agents (Claude Code, Cursor, Copilot) can build with Whoosh immediately.
+
+```bash
+# Dump your entire app structure as JSON (routes, schemas, config, MCP tools)
+whoosh describe
+
+# AI tools can consume this to understand your API
+whoosh describe --routes     # routes with request/response schemas
+whoosh describe --schemas    # all schema definitions
+
+# Catch mistakes before runtime
+whoosh check                 # validates config, auth, dependencies
+```
+
 ## Performance
 
 ### HTTP Benchmark: `GET /health → {"status":"ok"}`

data/lib/whoosh/app.rb

@@ -235,6 +235,13 @@ module Whoosh
       [200, Streaming::LlmStream.headers, body]
     end
 
+    # WebSocket endpoint helper — use in handle_request, returns hijack response
+    def websocket(env, &block)
+      ws = Streaming::WebSocket.new(env)
+      block.call(ws)
+      ws.rack_response
+    end
+
     def paginate(collection, page:, per_page: 20)
       Paginate.offset(collection, page: page, per_page: per_page)
     end

data/lib/whoosh/streaming/websocket.rb

@@ -1,25 +1,34 @@
-# lib/whoosh/streaming/websocket.rb
 # frozen_string_literal: true
 
 require "json"
+require "digest"
+require "base64"
 
 module Whoosh
   module Streaming
     class WebSocket
-      def initialize(io)
-        @io = io
+      GUID = "258EAFA5-E914-47DA-95CA-5AB5DC65C3E5"
+
+      attr_reader :env
+
+      def initialize(env)
+        @env = env
+        @io = nil
         @closed = false
         @on_message = nil
         @on_close = nil
+        @on_open = nil
       end
 
-      def send(data)
-        return if @closed
-        formatted = data.is_a?(String) ? data : JSON.generate(data)
-        @io.write(formatted + "\n")
-        @io.flush if @io.respond_to?(:flush)
-      rescue IOError, Errno::EPIPE
-        @closed = true
+      # Check if the request is a WebSocket upgrade
+      def self.websocket?(env)
+        env["HTTP_UPGRADE"]&.downcase == "websocket" &&
+          env["HTTP_CONNECTION"]&.downcase&.include?("upgrade")
+      end
+
+      # Register callbacks
+      def on_open(&block)
+        @on_open = block
       end
 
       def on_message(&block)
@@ -30,6 +39,67 @@ module Whoosh
         @on_close = block
       end
 
+      # Send data to the client
+      def send(data)
+        return if @closed
+        formatted = data.is_a?(String) ? data : JSON.generate(data)
+        write_frame(formatted)
+      end
+
+      def close
+        return if @closed
+        @closed = true
+        write_close_frame
+        @io&.close rescue nil
+        @on_close&.call
+      end
+
+      def closed?
+        @closed
+      end
+
+      # Returns a Rack response that hijacks the connection
+      def rack_response
+        unless self.class.websocket?(@env)
+          return [400, { "content-type" => "text/plain" }, ["Not a WebSocket request"]]
+        end
+
+        # WebSocket handshake
+        key = @env["HTTP_SEC_WEBSOCKET_KEY"]
+        accept = Base64.strict_encode64(Digest::SHA1.digest(key + GUID))
+
+        headers = {
+          "Upgrade" => "websocket",
+          "Connection" => "Upgrade",
+          "Sec-WebSocket-Accept" => accept
+        }
+
+        # Use rack.hijack to take over the connection
+        if @env["rack.hijack"]
+          @env["rack.hijack"].call
+          @io = @env["rack.hijack_io"]
+
+          # Send handshake response manually
+          @io.write("HTTP/1.1 101 Switching Protocols\r\n")
+          headers.each { |k, v| @io.write("#{k}: #{v}\r\n") }
+          @io.write("\r\n")
+          @io.flush
+
+          # Notify open
+          @on_open&.call
+
+          # Start reading frames in a thread
+          Thread.new { read_loop }
+
+          # Return a dummy response (connection is hijacked)
+          [-1, {}, []]
+        else
+          # Fallback: return 101 and let the server handle hijack
+          [101, headers, []]
+        end
+      end
+
+      # For testing — simulate without real socket
       def trigger_message(msg)
         @on_message&.call(msg)
       end
@@ -39,12 +109,86 @@ module Whoosh
         @closed = true
       end
 
-      def close
+      private
+
+      def read_loop
+        while !@closed && @io && !@io.closed?
+          frame = read_frame
+          break unless frame
+
+          case frame[:opcode]
+          when 0x1 # Text frame
+            @on_message&.call(frame[:data])
+          when 0x8 # Close frame
+            close
+            break
+          when 0x9 # Ping
+            write_pong(frame[:data])
+          end
+        end
+      rescue IOError, Errno::ECONNRESET, Errno::EPIPE
         @closed = true
+        @on_close&.call
       end
 
-      def closed?
-        @closed
+      def read_frame
+        return nil unless @io && !@io.closed?
+
+        first_byte = @io.readbyte
+        fin = (first_byte & 0x80) != 0
+        opcode = first_byte & 0x0F
+
+        second_byte = @io.readbyte
+        masked = (second_byte & 0x80) != 0
+        length = second_byte & 0x7F
+
+        if length == 126
+          length = @io.read(2).unpack1("n")
+        elsif length == 127
+          length = @io.read(8).unpack1("Q>")
+        end
+
+        mask_key = masked ? @io.read(4).bytes : nil
+        payload = @io.read(length)&.bytes || []
+
+        if masked && mask_key
+          payload = payload.each_with_index.map { |b, i| b ^ mask_key[i % 4] }
+        end
+
+        { opcode: opcode, data: payload.pack("C*"), fin: fin }
+      rescue EOFError, IOError
+        nil
+      end
+
+      def write_frame(data, opcode: 0x1)
+        return unless @io && !@io.closed?
+
+        bytes = data.encode("UTF-8").bytes
+        frame = [0x80 | opcode] # FIN + opcode
+
+        if bytes.length < 126
+          frame << bytes.length
+        elsif bytes.length < 65536
+          frame << 126
+          frame += [bytes.length].pack("n").bytes
+        else
+          frame << 127
+          frame += [bytes.length].pack("Q>").bytes
+        end
+
+        frame += bytes
+        @io.write(frame.pack("C*"))
+        @io.flush
+      rescue IOError, Errno::EPIPE
+        @closed = true
+      end
+
+      def write_close_frame
+        write_frame("", opcode: 0x8) rescue nil
+      end
+
+      def write_pong(data)
+        write_frame(data, opcode: 0xA) rescue nil
       end
     end
   end

data/lib/whoosh/version.rb

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

metadata

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