whoosh 1.4.1 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5baff744454d485e7f9788aca18285ece0c8901a5abea6f9c2f3fd4a22a7de75
-  data.tar.gz: 6c2062d73b6bec5e60c0adfd897e7e8aec5d10fa366439471592fc196bfe5bbd
+  metadata.gz: f93acb5a2f85aecd9f3feafc165962aa721a762dad30caa2d2550ed500afbec8
+  data.tar.gz: e44f3b1217d9177417b21820abd6d1788969556603c2d9aff7f26d7351c703d2
 SHA512:
-  metadata.gz: 7ef32b36e7405fe117eefc60908baf71a9553d328ccd2fd7823c715b7e37d4f01aeedc29a7cb1709e865410d407a32bc511f49353b90339702a06bb7f9a31425
-  data.tar.gz: 75188ded90b9205cb7c779d18252ef842989ec84d76ad78e1167d4ca267e544918b39c5d2a3596abe0b2d6001620e98e4272a75bdd62491b4130127bba78487c
+  metadata.gz: 77dd95d3cefc8053ff9c183207273adc8b99e4df806ad1374b277dfde6a64ffb31f82765c502c05d81eb4d4a9b4f6d681a2ffb0ebaf75353369e5179eeb17758
+  data.tar.gz: ea988031ce4f4dd47959bd84782caa4ad019e7570f5cd2d17cba754b3851955a4520c7d5ee76815b53da7e381a9fde0a833895a7cc59386e2354dfc6f7604f74

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-542%20passing-brightgreen" alt="Tests">
+  <img src="https://img.shields.io/badge/tests-659%20passing-brightgreen" alt="Tests">
   <img src="https://img.shields.io/badge/overhead-2.5%C2%B5s-orange" alt="Performance">
 </p>
 
@@ -346,6 +346,43 @@ app.docs enabled: true, redoc: true
 - `/redoc` — ReDoc
 - `/openapi.json` — Machine-readable spec
 
+### Client Generator
+
+Generate complete, typed, ready-to-run client apps from your Whoosh API — one command.
+
+```sh
+whoosh generate client react_spa          # React + Vite + TypeScript
+whoosh generate client expo               # Expo + React Native
+whoosh generate client ios                # SwiftUI + MVVM
+whoosh generate client flutter            # Dart + Riverpod + GoRouter
+whoosh generate client htmx               # Plain HTML + htmx, no build step
+whoosh generate client telegram_bot       # Ruby Telegram bot
+whoosh generate client telegram_mini_app  # React + Telegram WebApp SDK
+
+whoosh generate client react_spa --oauth  # Add Google/GitHub/Apple login
+```
+
+The generator **introspects your Whoosh app** via OpenAPI — it reads your routes, schemas, and auth config, then produces a typed client with:
+
+- API client with auth headers and automatic token refresh
+- Model types matching your schemas
+- Auth screens (login, register, logout)
+- CRUD screens for every resource
+- Navigation and routing
+- Starter tests
+
+If no Whoosh app exists yet, it scaffolds a standard backend (JWT auth + tasks CRUD) alongside the client.
+
+| Client | Stack | Token Storage |
+|--------|-------|---------------|
+| `react_spa` | React 19, Vite, TypeScript, React Router | localStorage |
+| `expo` | Expo SDK 52, Expo Router, TypeScript | SecureStore |
+| `ios` | SwiftUI, async/await, MVVM | Keychain |
+| `flutter` | Dart, Dio, Riverpod, GoRouter | flutter_secure_storage |
+| `htmx` | HTML, htmx 2.x, vanilla JS | localStorage |
+| `telegram_bot` | Ruby, telegram-bot-ruby | In-memory session |
+| `telegram_mini_app` | React, Telegram WebApp SDK | Telegram initData |
+
 ### Health Checks
 
 ```ruby
@@ -377,6 +414,8 @@ whoosh generate model User name:string email:string
 whoosh generate migration add_email_to_users
 whoosh generate plugin my_tool      # plugin boilerplate
 whoosh generate proto ChatRequest   # .proto file
+whoosh generate client react_spa    # full client app (7 types)
+whoosh generate client expo --oauth # with OAuth2 social login
 
 whoosh db migrate             # run migrations
 whoosh db rollback            # rollback

data/lib/whoosh/app.rb

@@ -250,6 +250,31 @@ module Whoosh
       Paginate.cursor(collection, cursor: cursor, limit: limit, column: column)
     end
 
+    def redirect(url, status: 302)
+      Response.redirect(url, status: status)
+    end
+
+    def download(data, filename:, content_type: nil)
+      Response.download(data, filename: filename, content_type: content_type || "application/octet-stream")
+    end
+
+    def send_file(path, content_type: nil)
+      Response.file(path, content_type: content_type)
+    end
+
+    def serve_static(prefix, root:)
+      get "#{prefix}/:_static_path" do |req|
+        file_path = File.join(root, req.params[:_static_path])
+        real = File.realpath(file_path) rescue nil
+        real_root = File.realpath(root) rescue root
+        if real && real.start_with?(real_root) && File.file?(real)
+          Response.file(real)
+        else
+          Response.not_found
+        end
+      end
+    end
+
     # --- Endpoint loading ---
 
     def load_endpoints(dir)
@@ -396,66 +421,71 @@ module Whoosh
       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
+        begin
+          # 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
+          # 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)
+          # 4. Handle request (core)
+          status, headers, body = handle_request(env)
 
-        # Ensure headers are mutable (streaming returns frozen headers)
-        headers = headers.dup if headers.frozen?
+          # 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 }
+          # 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
+          # 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
+          # 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)
+          # 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
+          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]
+          [status, headers, body]
+        rescue => e
+          [500, { "content-type" => "application/json" },
+            [JSON.generate({ error: "internal_error", message: e.message })]]
+        end
       }
     end
 
@@ -509,7 +539,8 @@ module Whoosh
         generator.add_route(
           method: route[:method], path: route[:path],
           request_schema: handler[:request_schema],
-          response_schema: handler[:response_schema]
+          response_schema: handler[:response_schema],
+          query_schema: handler[:query_schema]
         )
       end
 
@@ -540,13 +571,14 @@ module Whoosh
       })
     end
 
-    def add_route(method, path, request: nil, response: nil, **metadata, &block)
+    def add_route(method, path, request: nil, response: nil, query: nil, **metadata, &block)
       full_path = "#{@group_prefix}#{path}"
       merged_metadata = @group_metadata.merge(metadata)
       handler = {
         block: block,
         request_schema: request,
         response_schema: response,
+        query_schema: query,
         middleware: @group_middleware.dup
       }
       @router.add(method, full_path, handler, **merged_metadata)
@@ -662,6 +694,10 @@ module Whoosh
         @strategies[:jwt] = Auth::Jwt.new(secret: secret, algorithm: algorithm, expiry: expiry)
       end
 
+      def oauth2(provider: :custom, **opts)
+        @strategies[:oauth2] = Auth::OAuth2.new(provider: provider, **opts)
+      end
+
       def build
         @strategies.values.first
       end

data/lib/whoosh/auth/oauth2.rb

@@ -1,18 +1,74 @@
-# lib/whoosh/auth/oauth2.rb
 # frozen_string_literal: true
 
+require "securerandom"
+
 module Whoosh
   module Auth
     class OAuth2
-      def initialize(token_url: "/oauth/token", validator: nil)
+      PROVIDERS = {
+        google: {
+          authorize_url: "https://accounts.google.com/o/oauth2/v2/auth",
+          token_url: "https://oauth2.googleapis.com/token",
+          userinfo_url: "https://www.googleapis.com/oauth2/v3/userinfo"
+        },
+        github: {
+          authorize_url: "https://github.com/login/oauth/authorize",
+          token_url: "https://github.com/login/oauth/access_token",
+          userinfo_url: "https://api.github.com/user"
+        },
+        apple: {
+          authorize_url: "https://appleid.apple.com/auth/authorize",
+          token_url: "https://appleid.apple.com/auth/token",
+          userinfo_url: nil
+        }
+      }.freeze
+
+      attr_reader :provider
+
+      def initialize(provider: :custom, client_id: nil, client_secret: nil,
+                     authorize_url: nil, token_url: nil, userinfo_url: nil,
+                     redirect_uri: nil, scopes: [], validator: nil)
+        @provider = provider
+        @client_id = client_id
+        @client_secret = client_secret
+        @authorize_url = authorize_url
         @token_url = token_url
+        @userinfo_url = userinfo_url
+        @redirect_uri = redirect_uri
+        @scopes = scopes
         @validator = validator
+        apply_provider_defaults if PROVIDERS[@provider]
+      end
+
+      def authorize_url(state: SecureRandom.hex(16))
+        params = {
+          client_id: @client_id, redirect_uri: @redirect_uri,
+          response_type: "code", scope: @scopes.join(" "), state: state
+        }
+        "#{@authorize_url}?#{URI.encode_www_form(params)}"
+      end
+
+      def exchange_code(code)
+        response = HTTP.post(@token_url, json: {
+          client_id: @client_id, client_secret: @client_secret,
+          code: code, redirect_uri: @redirect_uri, grant_type: "authorization_code"
+        }, headers: { "Accept" => "application/json" })
+        raise Errors::UnauthorizedError, "Token exchange failed: #{response.status}" unless response.ok?
+        response.json
+      end
+
+      def userinfo(access_token)
+        return nil unless @userinfo_url
+        response = HTTP.get(@userinfo_url, headers: {
+          "Authorization" => "Bearer #{access_token}", "Accept" => "application/json"
+        })
+        raise Errors::UnauthorizedError, "Userinfo failed" unless response.ok?
+        response.json
       end
 
       def authenticate(request)
         auth_header = request.headers["Authorization"]
-        raise Errors::UnauthorizedError, "Missing authorization header" unless auth_header
-
+        raise Errors::UnauthorizedError, "Missing authorization" unless auth_header
         token = auth_header.sub(/\ABearer\s+/i, "")
         raise Errors::UnauthorizedError, "Missing token" if token.empty?
 
@@ -20,13 +76,20 @@ module Whoosh
           result = @validator.call(token)
           raise Errors::UnauthorizedError, "Invalid token" unless result
           result
+        elsif @userinfo_url
+          userinfo(token)
         else
           { token: token }
         end
       end
 
-      def token_url
-        @token_url
+      private
+
+      def apply_provider_defaults
+        defaults = PROVIDERS[@provider]
+        @authorize_url ||= defaults[:authorize_url]
+        @token_url ||= defaults[:token_url]
+        @userinfo_url ||= defaults[:userinfo_url]
       end
     end
   end

data/lib/whoosh/cli/client_generator.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+require "whoosh/client_gen/ir"
+require "whoosh/client_gen/introspector"
+require "whoosh/client_gen/base_generator"
+require "whoosh/client_gen/dependency_checker"
+require "whoosh/client_gen/fallback_backend"
+
+module Whoosh
+  module ClientGen
+    class Error < StandardError; end
+  end
+
+  module CLI
+    class ClientGenerator
+      CLIENT_TYPES = %i[react_spa expo ios flutter htmx telegram_bot telegram_mini_app].freeze
+
+      attr_reader :type, :oauth, :output_dir
+
+      def self.client_types
+        CLIENT_TYPES
+      end
+
+      def initialize(type:, oauth:, dir:, root: Dir.pwd)
+        @type = type.to_sym
+        @oauth = oauth
+        @output_dir = dir || default_output_dir
+        @root = root
+      end
+
+      def run
+        validate!
+        check_dependencies!
+        result = introspect_or_fallback
+
+        case result[:mode]
+        when :introspected
+          display_found(result[:ir])
+          ir = confirm_selection(result[:ir])
+          generate_client(ir)
+        when :fallback
+          display_fallback_prompt
+          generate_fallback_backend
+          ir = build_fallback_ir
+          generate_client(ir)
+        end
+
+        display_success
+      end
+
+      def validate!
+        unless CLIENT_TYPES.include?(@type)
+          raise ClientGen::Error, "Unknown client type: #{@type}. Supported: #{CLIENT_TYPES.join(", ")}"
+        end
+      end
+
+      def default_output_dir
+        "clients/#{@type}"
+      end
+
+      def check_dependencies!
+        result = ClientGen::DependencyChecker.check(@type)
+        return if result[:ok]
+
+        puts "\n⚠️  Missing dependencies for #{@type}:"
+        result[:missing].each do |dep|
+          msg = "  - #{dep[:cmd]} (check: #{dep[:check]})"
+          msg += " — found v#{dep[:found_version]}, need v#{dep[:min_version]}+" if dep[:found_version]
+          puts msg
+        end
+        puts "\nInstall the missing dependencies and try again."
+        exit 1
+      end
+
+      def introspect_or_fallback
+        app = load_app
+        if app
+          introspector = ClientGen::Introspector.new(app, base_url: detect_base_url(app))
+          ir = introspector.introspect
+          if ir.has_resources? || ir.has_auth?
+            { mode: :introspected, ir: ir }
+          else
+            { mode: :fallback }
+          end
+        else
+          { mode: :fallback }
+        end
+      end
+
+      private
+
+      def load_app
+        app_file = File.join(@root, "app.rb")
+        return nil unless File.exist?(app_file)
+
+        require app_file
+        ObjectSpace.each_object(Whoosh::App).first
+      rescue => e
+        puts "⚠️  Failed to load app: #{e.message}"
+        puts "Run `whoosh check` to debug."
+        nil
+      end
+
+      def detect_base_url(app)
+        config = app.instance_variable_get(:@config)
+        port = config&.respond_to?(:port) ? config.port : 9292
+        host = config&.respond_to?(:host) ? config.host : "localhost"
+        "http://#{host}:#{port}"
+      end
+
+      def display_found(ir)
+        puts "\n🔍 Inspecting Whoosh app...\n\n"
+        puts "Found:"
+        puts "  Auth:       #{ir.auth&.type || "none"}"
+        ir.resources.each do |r|
+          puts "  Resource:   #{r.name} (#{r.endpoints.length} endpoints)"
+        end
+        ir.streaming.each do |s|
+          puts "  Streaming:  #{s[:type]} on #{s[:path]}"
+        end
+        puts
+      end
+
+      def confirm_selection(ir)
+        ir
+      end
+
+      def display_fallback_prompt
+        puts "\n⚠️  No Whoosh app found (or no routes defined).\n\n"
+        puts "Generating standard starter with:"
+        puts "  - JWT auth (email/password login + register)"
+        puts "  - Tasks CRUD (title, description, status, due_date)"
+        puts "  - Matching backend endpoints"
+        if @oauth
+          puts "  - OAuth2 (Google, GitHub, Apple)"
+        end
+        puts
+      end
+
+      def generate_fallback_backend
+        ClientGen::FallbackBackend.generate(root: @root, oauth: @oauth)
+        puts "✅ Backend endpoints generated"
+      end
+
+      def build_fallback_ir
+        ClientGen::IR::AppSpec.new(
+          auth: ClientGen::IR::Auth.new(
+            type: :jwt,
+            endpoints: {
+              login: { method: :post, path: "/auth/login" },
+              register: { method: :post, path: "/auth/register" },
+              refresh: { method: :post, path: "/auth/refresh" },
+              logout: { method: :delete, path: "/auth/logout" },
+              me: { method: :get, path: "/auth/me" }
+            },
+            oauth_providers: @oauth ? %i[google github apple] : []
+          ),
+          resources: [
+            ClientGen::IR::Resource.new(
+              name: :tasks,
+              endpoints: [
+                ClientGen::IR::Endpoint.new(method: :get, path: "/tasks", action: :index, pagination: true),
+                ClientGen::IR::Endpoint.new(method: :get, path: "/tasks/:id", action: :show),
+                ClientGen::IR::Endpoint.new(method: :post, path: "/tasks", action: :create),
+                ClientGen::IR::Endpoint.new(method: :put, path: "/tasks/:id", action: :update),
+                ClientGen::IR::Endpoint.new(method: :delete, path: "/tasks/:id", action: :destroy)
+              ],
+              fields: [
+                { name: :title, type: :string, required: true },
+                { name: :description, type: :string, required: false },
+                { name: :status, type: :string, required: false, enum: %w[pending in_progress done], default: "pending" },
+                { name: :due_date, type: :string, required: false }
+              ]
+            )
+          ],
+          streaming: [],
+          base_url: "http://localhost:9292"
+        )
+      end
+
+      def generate_client(ir)
+        generator_class = load_generator_class
+        output = File.join(@root, @output_dir)
+
+        if Dir.exist?(output) && !Dir.empty?(output)
+          puts "⚠️  #{@output_dir}/ already exists."
+          print "Overwrite? [y/N] "
+          answer = $stdin.gets&.strip&.downcase
+          unless answer == "y"
+            puts "Aborted."
+            exit 0
+          end
+          FileUtils.rm_rf(output)
+        end
+
+        generator_class.new(ir: ir, output_dir: output, platform: platform_for_type).generate
+      end
+
+      def load_generator_class
+        require "whoosh/client_gen/generators/#{@type}"
+        Whoosh::ClientGen::Generators.const_get(camelize(@type.to_s))
+      end
+
+      def platform_for_type
+        case @type
+        when :react_spa, :expo, :telegram_mini_app then :typescript
+        when :ios then :swift
+        when :flutter then :dart
+        when :htmx then :html
+        when :telegram_bot then :ruby
+        end
+      end
+
+      def camelize(str)
+        str.split("_").map(&:capitalize).join
+      end
+
+      def display_success
+        puts "\n✅ Generated #{@type} client in #{@output_dir}/"
+        case @type
+        when :react_spa, :telegram_mini_app
+          puts "   Run: cd #{@output_dir} && npm install && npm run dev"
+        when :expo
+          puts "   Run: cd #{@output_dir} && npm install && npx expo start"
+        when :ios
+          puts "   Run: open #{@output_dir}/WhooshApp.xcodeproj"
+        when :flutter
+          puts "   Run: cd #{@output_dir} && flutter pub get && flutter run"
+        when :htmx
+          puts "   Run: cd #{@output_dir} && open index.html (or any static server)"
+        when :telegram_bot
+          puts "   Run: cd #{@output_dir} && bundle install && ruby bot.rb"
+        end
+      end
+    end
+  end
+end

data/lib/whoosh/cli/main.rb

@@ -600,6 +600,16 @@ module Whoosh
           require "whoosh/cli/generators"
           Whoosh::CLI::Generators.proto(name)
         end
+
+        desc "client TYPE", "Generate a client app (react_spa, expo, ios, flutter, htmx, telegram_bot, telegram_mini_app)"
+        option :oauth, type: :boolean, default: false, desc: "Include OAuth2 social login"
+        option :dir, type: :string, desc: "Output directory (default: clients/<type>)"
+        def client(type)
+          require "whoosh/cli/client_generator"
+          Whoosh::CLI::ClientGenerator.new(
+            type: type, oauth: options[:oauth], dir: options[:dir]
+          ).run
+        end
       }
     end
   end