tina4ruby 3.11.13 → 3.11.15

data/lib/tina4/router.rb

@@ -1,406 +1,406 @@
-# frozen_string_literal: true
-
-module Tina4
-  class Route
-    attr_reader :method, :path, :handler, :auth_handler, :swagger_meta,
-                :path_regex, :param_names, :template
-    attr_accessor :auth_required, :cached
-
-    def initialize(method, path, handler, auth_handler: nil, swagger_meta: {}, middleware: [], template: nil)
-      @method = method.to_s.upcase.freeze
-      @path = normalize_path(path).freeze
-      @handler = handler
-      @auth_handler = auth_handler
-      @swagger_meta = swagger_meta
-      @middleware = middleware.freeze
-      @template = template&.freeze
-      # Write routes are secure by default, unless custom middleware is registered
-      # (developer handles auth themselves via middleware)
-      @auth_required = %w[POST PUT PATCH DELETE].include?(@method) && middleware.empty?
-      @cached = false
-      @param_names = []
-      @path_regex = compile_pattern(@path)
-      @param_names.freeze
-    end
-
-    # Mark this route as requiring bearer-token authentication.
-    # Returns self for chaining: Router.get("/path") { ... }.secure
-    def secure
-      @auth_required = true
-      self
-    end
-
-    # Opt out of the secure-by-default auth on write routes.
-    # Returns self for chaining: Router.post("/login") { ... }.no_auth
-    def no_auth
-      @auth_required = false
-      self
-    end
-
-    # Mark this route as cacheable.
-    # Returns self for chaining: Router.get("/path") { ... }.cache
-    def cache
-      @cached = true
-      self
-    end
-
-    # Dual-mode: getter (no args) returns the middleware array;
-    # setter (with args) appends middleware and returns self for chaining.
-    # Router.post("/api") { ... }.middleware(AuthMiddleware)
-    def middleware(*middleware_classes)
-      return @middleware if middleware_classes.empty?
-
-      @middleware = @middleware.dup + middleware_classes
-      # Custom middleware means developer handles auth — disable built-in gate
-      # unless .secure was explicitly called.
-      @auth_required = false unless @auth_required
-      self
-    end
-
-    # Returns params hash if matched, false otherwise
-    def match?(request_path, request_method = nil)
-      return false if request_method && @method != "ANY" && @method != request_method.to_s.upcase
-      match_path(request_path)
-    end
-
-    # Returns params hash if matched, false otherwise
-    def match_path(request_path)
-      match = @path_regex.match(request_path)
-      return false unless match
-
-      if @param_names.empty?
-        {}
-      else
-        params = {}
-        @param_names.each_with_index do |param_def, i|
-          raw_value = match[i + 1]
-          params[param_def[:name]] = cast_param(raw_value, param_def[:type])
-        end
-        params
-      end
-    end
-
-    # Run per-route middleware chain; returns true if all pass
-    def run_middleware(request, response)
-      @middleware.each do |mw|
-        result = mw.call(request, response)
-        return false if result == false
-      end
-      true
-    end
-
-    private
-
-    def normalize_path(path)
-      p = path.to_s.gsub("\\", "/")
-      p = "/#{p}" unless p.start_with?("/")
-      p = p.chomp("/") unless p == "/"
-      p
-    end
-
-    # Supported typed-parameter constraints. Mirrored verbatim in
-    # tina4-python / tina4-php / tina4-nodejs for cross-framework parity.
-    #
-    # Any type name not in this table raises ``ArgumentError`` at route
-    # registration — we never silently fall through to the default matcher,
-    # because a typo like ``{id:inetger}`` would otherwise match anything
-    # and create a security footgun (see tina4-book#125).
-    PARAM_TYPE_PATTERNS = {
-      "string"  => "[^/]+",                                            # default, any non-slash segment
-      "int"     => '\d+',
-      "integer" => '\d+',
-      "float"   => '[\d.]+',
-      "number"  => '[\d.]+',
-      "alpha"   => "[A-Za-z]+",                                        # letters only
-      "alnum"   => "[A-Za-z0-9]+",                                     # letters + digits
-      "slug"    => "[a-z0-9-]+",                                       # URL slug
-      "uuid"    => "[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}",
-      "path"    => ".+",                                               # greedy
-      ".*"      => ".+",
-    }.freeze
-
-    def compile_pattern(path)
-      return Regexp.new("\\A/\\z") if path == "/"
-
-      parts = path.split("/").reject(&:empty?)
-      regex_parts = parts.map do |part|
-        if part =~ /\A\*(\w+)\z/
-          # Named catch-all splat parameter: *path captures everything after
-          name = Regexp.last_match(1)
-          @param_names << { name: name.to_sym, type: "path" }
-          '(.+)'
-        elsif part == "*"
-          # Bare catch-all wildcard: captures everything after under the "*" key
-          # to match Python/PHP/Node parity (docs say `request.params["*"]`).
-          @param_names << { name: :"*", type: "path" }
-          '(.+)'
-        elsif part =~ /\A\{(\w+)(?::([\w.*]+))?\}\z/
-          # Tina4/Python-style brace params: {id} or {id:int}
-          # This is the ONLY supported param syntax, matching Python exactly.
-          # Do NOT add :id (colon) style params.
-          name = Regexp.last_match(1)
-          type = Regexp.last_match(2) || "string"
-          unless PARAM_TYPE_PATTERNS.key?(type)
-            valid = PARAM_TYPE_PATTERNS.keys.reject { |k| k == ".*" }.sort.join(", ")
-            raise ArgumentError,
-                  "Unknown param type '#{type}' in route '#{path}'. Valid types: #{valid}."
-          end
-          @param_names << { name: name.to_sym, type: type }
-          "(#{PARAM_TYPE_PATTERNS[type]})"
-        else
-          Regexp.escape(part)
-        end
-      end
-      Regexp.new("\\A/#{regex_parts.join("/")}\\z")
-    end
-
-    def cast_param(value, type)
-      case type
-      when "int", "integer"
-        value.to_i
-      when "float", "number"
-        value.to_f
-      else
-        value
-      end
-    end
-  end
-
-  # A registered WebSocket route with path pattern matching (reuses Route's compile logic)
-  class WebSocketRoute
-    attr_reader :path, :handler, :path_regex, :param_names
-
-    def initialize(path, handler)
-      @path = normalize_path(path).freeze
-      @handler = handler
-      @param_names = []
-      @path_regex = compile_pattern(@path)
-      @param_names.freeze
-    end
-
-    # Returns params hash if matched, false otherwise
-    def match?(request_path)
-      match = @path_regex.match(request_path)
-      return false unless match
-
-      if @param_names.empty?
-        {}
-      else
-        params = {}
-        @param_names.each_with_index do |param_def, i|
-          raw_value = match[i + 1]
-          params[param_def[:name]] = raw_value
-        end
-        params
-      end
-    end
-
-    private
-
-    def normalize_path(path)
-      p = path.to_s.gsub("\\", "/")
-      p = "/#{p}" unless p.start_with?("/")
-      p = p.chomp("/") unless p == "/"
-      p
-    end
-
-    def compile_pattern(path)
-      return Regexp.new("\\A/\\z") if path == "/"
-
-      parts = path.split("/").reject(&:empty?)
-      regex_parts = parts.map do |part|
-        if part =~ /\A\{(\w+)\}\z/
-          name = Regexp.last_match(1)
-          @param_names << { name: name.to_sym }
-          '([^/]+)'
-        else
-          Regexp.escape(part)
-        end
-      end
-      Regexp.new("\\A/#{regex_parts.join("/")}\\z")
-    end
-  end
-
-  module Router
-    class << self
-      def routes
-        @routes ||= []
-      end
-
-      def get_routes
-        routes
-      end
-
-      def list_routes
-        routes
-      end
-
-      # Registered WebSocket routes
-      def ws_routes
-        @ws_routes ||= []
-      end
-
-      # Parity alias — returns all registered WebSocket routes.
-      def get_web_socket_routes
-        ws_routes
-      end
-
-      # Register a WebSocket route.
-      # The handler block receives (connection, event, data) where:
-      #   connection — WebSocketConnection with #send, #broadcast, #close, #params
-      #   event      — :open, :message, or :close
-      #   data       — String payload for :message, nil for :open/:close
-      def websocket(path, &block)
-        ws_route = WebSocketRoute.new(path, block)
-        ws_routes << ws_route
-        Tina4::Log.debug("WebSocket route registered: #{path}")
-        ws_route
-      end
-
-      # Find a matching WebSocket route for a given path.
-      # Returns [ws_route, params] or nil.
-      def find_ws_route(path)
-        normalized = path.gsub("\\", "/")
-        normalized = "/#{normalized}" unless normalized.start_with?("/")
-        normalized = normalized.chomp("/") unless normalized == "/"
-
-        ws_routes.each do |ws_route|
-          params = ws_route.match?(normalized)
-          return [ws_route, params] if params
-        end
-        nil
-      end
-
-      # Routes indexed by HTTP method for O(1) method lookup
-      def method_index
-        @method_index ||= Hash.new { |h, k| h[k] = [] }
-      end
-
-      def add(method, path, handler, auth_handler: nil, swagger_meta: {}, middleware: [], template: nil)
-        route = Route.new(method, path, handler,
-                          auth_handler: auth_handler,
-                          swagger_meta: swagger_meta,
-                          middleware: middleware,
-                          template: template)
-        routes << route
-        method_index[route.method] << route
-        Tina4::Log.debug("Route registered: #{method.upcase} #{path}")
-        route
-      end
-      # Convenience registration methods
-      def get(path, middleware: [], swagger_meta: {}, template: nil, &block)
-        add("GET", path, block, middleware: middleware, swagger_meta: swagger_meta, template: template)
-      end
-
-      def post(path, middleware: [], swagger_meta: {}, template: nil, &block)
-        add("POST", path, block, middleware: middleware, swagger_meta: swagger_meta, template: template)
-      end
-
-      def put(path, middleware: [], swagger_meta: {}, template: nil, &block)
-        add("PUT", path, block, middleware: middleware, swagger_meta: swagger_meta, template: template)
-      end
-
-      def patch(path, middleware: [], swagger_meta: {}, template: nil, &block)
-        add("PATCH", path, block, middleware: middleware, swagger_meta: swagger_meta, template: template)
-      end
-
-      def delete(path, middleware: [], swagger_meta: {}, template: nil, &block)
-        add("DELETE", path, block, middleware: middleware, swagger_meta: swagger_meta, template: template)
-      end
-
-      def any(path, middleware: [], swagger_meta: {}, template: nil, &block)
-        add("ANY", path, block, middleware: middleware, swagger_meta: swagger_meta, template: template)
-      end
-
-      def find_route(method, path)
-        normalized_method = method.upcase
-        # Normalize path once (not per-route)
-        normalized_path = path.gsub("\\", "/")
-        normalized_path = "/#{normalized_path}" unless normalized_path.start_with?("/")
-        normalized_path = normalized_path.chomp("/") unless normalized_path == "/"
-
-        # Check ANY routes first, then method-specific routes
-        candidates = (method_index["ANY"] || []) + (method_index[normalized_method] || [])
-        candidates.each do |route|
-          params = route.match_path(normalized_path)
-          return [route, params] if params
-        end
-        nil
-      end
-
-      # Find a route matching method + path. Returns [route, params] or nil.
-      # match(method, path) — consistent with Python, PHP, and Node.
-      def match(method, path)
-        find_route(method, path)
-      end
-
-      # Register a class-based middleware globally.
-      # The class should define static before_* and/or after_* methods.
-      # Example:
-      #   class AuthMiddleware
-      #     def self.before_auth(request, response)
-      #       unless request.headers["authorization"]
-      #         return [request, response.json({ error: "Unauthorized" }, 401)]
-      #       end
-      #       [request, response]
-      #     end
-      #   end
-      #   Tina4::Router.use(AuthMiddleware)
-      def use(klass)
-        Tina4::Middleware.use(klass)
-      end
-
-      def clear!
-        @routes = []
-        @method_index = Hash.new { |h, k| h[k] = [] }
-        @ws_routes = []
-      end
-      alias clear clear!
-
-      def group(prefix, auth_handler: nil, middleware: [], &block)
-        GroupContext.new(prefix, auth_handler, middleware).instance_eval(&block)
-      end
-
-      # Load route files from a directory (file-based route discovery)
-      def load_routes(directory)
-        return unless Dir.exist?(directory)
-        Dir.glob(File.join(directory, "**/*.rb")).sort.each do |file|
-          begin
-            load file
-            Tina4::Log.debug("Route loaded: #{file}")
-          rescue => e
-            Tina4::Log.error("Failed to load route #{file}: #{e.message}")
-          end
-        end
-      end
-    end
-
-    class GroupContext
-      def initialize(prefix, auth_handler = nil, middleware = [])
-        @prefix = prefix.chomp("/")
-        @auth_handler = auth_handler
-        @middleware = middleware
-      end
-
-      %w[get post put patch delete any].each do |m|
-        define_method(m) do |path, middleware: [], swagger_meta: {}, template: nil, &handler|
-          full_path = "#{@prefix}#{path}"
-          combined_middleware = @middleware + middleware
-          Tina4::Router.add(m, full_path, handler,
-                                  auth_handler: @auth_handler,
-                                  swagger_meta: swagger_meta,
-                                  middleware: combined_middleware,
-                                  template: template)
-        end
-      end
-
-      # Nested groups
-      def group(prefix, auth_handler: nil, middleware: [], &block)
-        full_prefix = "#{@prefix}#{prefix}"
-        combined_middleware = @middleware + middleware
-        nested_auth = auth_handler || @auth_handler
-        GroupContext.new(full_prefix, nested_auth, combined_middleware).instance_eval(&block)
-      end
-    end
-  end
-end
+# frozen_string_literal: true
+
+module Tina4
+  class Route
+    attr_reader :method, :path, :handler, :auth_handler, :swagger_meta,
+                :path_regex, :param_names, :template
+    attr_accessor :auth_required, :cached
+
+    def initialize(method, path, handler, auth_handler: nil, swagger_meta: {}, middleware: [], template: nil)
+      @method = method.to_s.upcase.freeze
+      @path = normalize_path(path).freeze
+      @handler = handler
+      @auth_handler = auth_handler
+      @swagger_meta = swagger_meta
+      @middleware = middleware.freeze
+      @template = template&.freeze
+      # Write routes are secure by default, unless custom middleware is registered
+      # (developer handles auth themselves via middleware)
+      @auth_required = %w[POST PUT PATCH DELETE].include?(@method) && middleware.empty?
+      @cached = false
+      @param_names = []
+      @path_regex = compile_pattern(@path)
+      @param_names.freeze
+    end
+
+    # Mark this route as requiring bearer-token authentication.
+    # Returns self for chaining: Router.get("/path") { ... }.secure
+    def secure
+      @auth_required = true
+      self
+    end
+
+    # Opt out of the secure-by-default auth on write routes.
+    # Returns self for chaining: Router.post("/login") { ... }.no_auth
+    def no_auth
+      @auth_required = false
+      self
+    end
+
+    # Mark this route as cacheable.
+    # Returns self for chaining: Router.get("/path") { ... }.cache
+    def cache
+      @cached = true
+      self
+    end
+
+    # Dual-mode: getter (no args) returns the middleware array;
+    # setter (with args) appends middleware and returns self for chaining.
+    # Router.post("/api") { ... }.middleware(AuthMiddleware)
+    def middleware(*middleware_classes)
+      return @middleware if middleware_classes.empty?
+
+      @middleware = @middleware.dup + middleware_classes
+      # Custom middleware means developer handles auth — disable built-in gate
+      # unless .secure was explicitly called.
+      @auth_required = false unless @auth_required
+      self
+    end
+
+    # Returns params hash if matched, false otherwise
+    def match?(request_path, request_method = nil)
+      return false if request_method && @method != "ANY" && @method != request_method.to_s.upcase
+      match_path(request_path)
+    end
+
+    # Returns params hash if matched, false otherwise
+    def match_path(request_path)
+      match = @path_regex.match(request_path)
+      return false unless match
+
+      if @param_names.empty?
+        {}
+      else
+        params = {}
+        @param_names.each_with_index do |param_def, i|
+          raw_value = match[i + 1]
+          params[param_def[:name]] = cast_param(raw_value, param_def[:type])
+        end
+        params
+      end
+    end
+
+    # Run per-route middleware chain; returns true if all pass
+    def run_middleware(request, response)
+      @middleware.each do |mw|
+        result = mw.call(request, response)
+        return false if result == false
+      end
+      true
+    end
+
+    private
+
+    def normalize_path(path)
+      p = path.to_s.gsub("\\", "/")
+      p = "/#{p}" unless p.start_with?("/")
+      p = p.chomp("/") unless p == "/"
+      p
+    end
+
+    # Supported typed-parameter constraints. Mirrored verbatim in
+    # tina4-python / tina4-php / tina4-nodejs for cross-framework parity.
+    #
+    # Any type name not in this table raises ``ArgumentError`` at route
+    # registration — we never silently fall through to the default matcher,
+    # because a typo like ``{id:inetger}`` would otherwise match anything
+    # and create a security footgun (see tina4-book#125).
+    PARAM_TYPE_PATTERNS = {
+      "string"  => "[^/]+",                                            # default, any non-slash segment
+      "int"     => '\d+',
+      "integer" => '\d+',
+      "float"   => '[\d.]+',
+      "number"  => '[\d.]+',
+      "alpha"   => "[A-Za-z]+",                                        # letters only
+      "alnum"   => "[A-Za-z0-9]+",                                     # letters + digits
+      "slug"    => "[a-z0-9-]+",                                       # URL slug
+      "uuid"    => "[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}",
+      "path"    => ".+",                                               # greedy
+      ".*"      => ".+",
+    }.freeze
+
+    def compile_pattern(path)
+      return Regexp.new("\\A/\\z") if path == "/"
+
+      parts = path.split("/").reject(&:empty?)
+      regex_parts = parts.map do |part|
+        if part =~ /\A\*(\w+)\z/
+          # Named catch-all splat parameter: *path captures everything after
+          name = Regexp.last_match(1)
+          @param_names << { name: name.to_sym, type: "path" }
+          '(.+)'
+        elsif part == "*"
+          # Bare catch-all wildcard: captures everything after under the "*" key
+          # to match Python/PHP/Node parity (docs say `request.params["*"]`).
+          @param_names << { name: :"*", type: "path" }
+          '(.+)'
+        elsif part =~ /\A\{(\w+)(?::([\w.*]+))?\}\z/
+          # Tina4/Python-style brace params: {id} or {id:int}
+          # This is the ONLY supported param syntax, matching Python exactly.
+          # Do NOT add :id (colon) style params.
+          name = Regexp.last_match(1)
+          type = Regexp.last_match(2) || "string"
+          unless PARAM_TYPE_PATTERNS.key?(type)
+            valid = PARAM_TYPE_PATTERNS.keys.reject { |k| k == ".*" }.sort.join(", ")
+            raise ArgumentError,
+                  "Unknown param type '#{type}' in route '#{path}'. Valid types: #{valid}."
+          end
+          @param_names << { name: name.to_sym, type: type }
+          "(#{PARAM_TYPE_PATTERNS[type]})"
+        else
+          Regexp.escape(part)
+        end
+      end
+      Regexp.new("\\A/#{regex_parts.join("/")}\\z")
+    end
+
+    def cast_param(value, type)
+      case type
+      when "int", "integer"
+        value.to_i
+      when "float", "number"
+        value.to_f
+      else
+        value
+      end
+    end
+  end
+
+  # A registered WebSocket route with path pattern matching (reuses Route's compile logic)
+  class WebSocketRoute
+    attr_reader :path, :handler, :path_regex, :param_names
+
+    def initialize(path, handler)
+      @path = normalize_path(path).freeze
+      @handler = handler
+      @param_names = []
+      @path_regex = compile_pattern(@path)
+      @param_names.freeze
+    end
+
+    # Returns params hash if matched, false otherwise
+    def match?(request_path)
+      match = @path_regex.match(request_path)
+      return false unless match
+
+      if @param_names.empty?
+        {}
+      else
+        params = {}
+        @param_names.each_with_index do |param_def, i|
+          raw_value = match[i + 1]
+          params[param_def[:name]] = raw_value
+        end
+        params
+      end
+    end
+
+    private
+
+    def normalize_path(path)
+      p = path.to_s.gsub("\\", "/")
+      p = "/#{p}" unless p.start_with?("/")
+      p = p.chomp("/") unless p == "/"
+      p
+    end
+
+    def compile_pattern(path)
+      return Regexp.new("\\A/\\z") if path == "/"
+
+      parts = path.split("/").reject(&:empty?)
+      regex_parts = parts.map do |part|
+        if part =~ /\A\{(\w+)\}\z/
+          name = Regexp.last_match(1)
+          @param_names << { name: name.to_sym }
+          '([^/]+)'
+        else
+          Regexp.escape(part)
+        end
+      end
+      Regexp.new("\\A/#{regex_parts.join("/")}\\z")
+    end
+  end
+
+  module Router
+    class << self
+      def routes
+        @routes ||= []
+      end
+
+      def get_routes
+        routes
+      end
+
+      def list_routes
+        routes
+      end
+
+      # Registered WebSocket routes
+      def ws_routes
+        @ws_routes ||= []
+      end
+
+      # Parity alias — returns all registered WebSocket routes.
+      def get_web_socket_routes
+        ws_routes
+      end
+
+      # Register a WebSocket route.
+      # The handler block receives (connection, event, data) where:
+      #   connection — WebSocketConnection with #send, #broadcast, #close, #params
+      #   event      — :open, :message, or :close
+      #   data       — String payload for :message, nil for :open/:close
+      def websocket(path, &block)
+        ws_route = WebSocketRoute.new(path, block)
+        ws_routes << ws_route
+        Tina4::Log.debug("WebSocket route registered: #{path}")
+        ws_route
+      end
+
+      # Find a matching WebSocket route for a given path.
+      # Returns [ws_route, params] or nil.
+      def find_ws_route(path)
+        normalized = path.gsub("\\", "/")
+        normalized = "/#{normalized}" unless normalized.start_with?("/")
+        normalized = normalized.chomp("/") unless normalized == "/"
+
+        ws_routes.each do |ws_route|
+          params = ws_route.match?(normalized)
+          return [ws_route, params] if params
+        end
+        nil
+      end
+
+      # Routes indexed by HTTP method for O(1) method lookup
+      def method_index
+        @method_index ||= Hash.new { |h, k| h[k] = [] }
+      end
+
+      def add(method, path, handler, auth_handler: nil, swagger_meta: {}, middleware: [], template: nil)
+        route = Route.new(method, path, handler,
+                          auth_handler: auth_handler,
+                          swagger_meta: swagger_meta,
+                          middleware: middleware,
+                          template: template)
+        routes << route
+        method_index[route.method] << route
+        Tina4::Log.debug("Route registered: #{method.upcase} #{path}")
+        route
+      end
+      # Convenience registration methods
+      def get(path, middleware: [], swagger_meta: {}, template: nil, &block)
+        add("GET", path, block, middleware: middleware, swagger_meta: swagger_meta, template: template)
+      end
+
+      def post(path, middleware: [], swagger_meta: {}, template: nil, &block)
+        add("POST", path, block, middleware: middleware, swagger_meta: swagger_meta, template: template)
+      end
+
+      def put(path, middleware: [], swagger_meta: {}, template: nil, &block)
+        add("PUT", path, block, middleware: middleware, swagger_meta: swagger_meta, template: template)
+      end
+
+      def patch(path, middleware: [], swagger_meta: {}, template: nil, &block)
+        add("PATCH", path, block, middleware: middleware, swagger_meta: swagger_meta, template: template)
+      end
+
+      def delete(path, middleware: [], swagger_meta: {}, template: nil, &block)
+        add("DELETE", path, block, middleware: middleware, swagger_meta: swagger_meta, template: template)
+      end
+
+      def any(path, middleware: [], swagger_meta: {}, template: nil, &block)
+        add("ANY", path, block, middleware: middleware, swagger_meta: swagger_meta, template: template)
+      end
+
+      def find_route(method, path)
+        normalized_method = method.upcase
+        # Normalize path once (not per-route)
+        normalized_path = path.gsub("\\", "/")
+        normalized_path = "/#{normalized_path}" unless normalized_path.start_with?("/")
+        normalized_path = normalized_path.chomp("/") unless normalized_path == "/"
+
+        # Check ANY routes first, then method-specific routes
+        candidates = (method_index["ANY"] || []) + (method_index[normalized_method] || [])
+        candidates.each do |route|
+          params = route.match_path(normalized_path)
+          return [route, params] if params
+        end
+        nil
+      end
+
+      # Find a route matching method + path. Returns [route, params] or nil.
+      # match(method, path) — consistent with Python, PHP, and Node.
+      def match(method, path)
+        find_route(method, path)
+      end
+
+      # Register a class-based middleware globally.
+      # The class should define static before_* and/or after_* methods.
+      # Example:
+      #   class AuthMiddleware
+      #     def self.before_auth(request, response)
+      #       unless request.headers["authorization"]
+      #         return [request, response.json({ error: "Unauthorized" }, 401)]
+      #       end
+      #       [request, response]
+      #     end
+      #   end
+      #   Tina4::Router.use(AuthMiddleware)
+      def use(klass)
+        Tina4::Middleware.use(klass)
+      end
+
+      def clear!
+        @routes = []
+        @method_index = Hash.new { |h, k| h[k] = [] }
+        @ws_routes = []
+      end
+      alias clear clear!
+
+      def group(prefix, auth_handler: nil, middleware: [], &block)
+        GroupContext.new(prefix, auth_handler, middleware).instance_eval(&block)
+      end
+
+      # Load route files from a directory (file-based route discovery)
+      def load_routes(directory)
+        return unless Dir.exist?(directory)
+        Dir.glob(File.join(directory, "**/*.rb")).sort.each do |file|
+          begin
+            load file
+            Tina4::Log.debug("Route loaded: #{file}")
+          rescue => e
+            Tina4::Log.error("Failed to load route #{file}: #{e.message}")
+          end
+        end
+      end
+    end
+
+    class GroupContext
+      def initialize(prefix, auth_handler = nil, middleware = [])
+        @prefix = prefix.chomp("/")
+        @auth_handler = auth_handler
+        @middleware = middleware
+      end
+
+      %w[get post put patch delete any].each do |m|
+        define_method(m) do |path, middleware: [], swagger_meta: {}, template: nil, &handler|
+          full_path = "#{@prefix}#{path}"
+          combined_middleware = @middleware + middleware
+          Tina4::Router.add(m, full_path, handler,
+                                  auth_handler: @auth_handler,
+                                  swagger_meta: swagger_meta,
+                                  middleware: combined_middleware,
+                                  template: template)
+        end
+      end
+
+      # Nested groups
+      def group(prefix, auth_handler: nil, middleware: [], &block)
+        full_prefix = "#{@prefix}#{prefix}"
+        combined_middleware = @middleware + middleware
+        nested_auth = auth_handler || @auth_handler
+        GroupContext.new(full_prefix, nested_auth, combined_middleware).instance_eval(&block)
+      end
+    end
+  end
+end