tina4ruby 3.13.94 → 3.13.97

data/lib/tina4/response_cache.rb

@@ -37,7 +37,10 @@ module Tina4
   #   TINA4_CACHE_USERNAME / TINA4_CACHE_PASSWORD — credentials when not in the URL
   #
   class ResponseCache
-    CacheEntry = Struct.new(:body, :content_type, :status_code, :expires_at)
+    # vary / vary_values carry the RFC 9111 s4.1 bookkeeping: the field names
+    # the origin nominated, and the values they had on the request that caused
+    # this response to be stored.
+    CacheEntry = Struct.new(:body, :content_type, :status_code, :expires_at, :vary, :vary_values)
 
     # @param ttl [Integer] default TTL in seconds (0 = disabled)
     # @param max_entries [Integer] maximum cache entries
@@ -82,12 +85,16 @@ module Tina4
       return [request, response] unless method == "GET"
 
       url = request.respond_to?(:url) ? request.url : (request.respond_to?(:path) ? request.path : "/")
-      hit = internal_lookup(method, url)
+      hit = internal_lookup(method, url, request)
       if hit
         if response.respond_to?(:call)
           new_response = response.call(hit.body, hit.status_code, hit.content_type)
           set_cache_headers(new_response, "HIT", remaining_ttl(hit.expires_at))
-          return [request, new_response]
+          # Returning the Response OBJECT is what short-circuits. Returning the
+          # [request, response] pair only REBINDS and continues, so the handler
+          # ran anyway and the cache never saved a single call -- while still
+          # stamping X-Cache: HIT, which made the header a lie.
+          return new_response
         end
       end
 
@@ -138,13 +145,43 @@ module Tina4
                response.to_s
              end
 
-      internal_store(method, url, status.to_i, content_type.to_s, body)
+      # This response came OUT of the cache; re-storing it would also overwrite
+      # its X-Cache: HIT header with MISS.
+      return [request, response] if header_value(response, "X-Cache") == "HIT"
+
+      internal_store(method, url, status.to_i, content_type.to_s, body, request: request, response: response)
       # The handler ran (cache miss) — annotate the response so clients can
       # see this was a fresh response and how long it will be cached.
       set_cache_headers(response, "MISS", @ttl)
       [request, response]
     end
 
+    # ── Class-level hooks, so `middleware: [Tina4::ResponseCache]` works ──
+
+    class << self
+      # Middleware.discover_methods walks klass.singleton_class and calls
+      # klass.send(name, ...) -- it finds CLASS methods only. before_cache and
+      # after_cache are INSTANCE methods, so attaching the class discovered no
+      # hooks at all and the cache was a SILENT no-op: no warning, no header,
+      # no caching. These two delegate to the module-level singleton (the same
+      # instance Tina4.cache_get uses), which reads TTL and backend from ENV.
+      #
+      # @param request [Object]
+      # @param response [Object]
+      # @return [Tina4::Response, Array] the Response on a HIT (short-circuit),
+      #   otherwise the [request, response] pair
+      def before_response_cache(request, response)
+        Tina4.cache_instance.before_cache(request, response)
+      end
+
+      # @param request [Object]
+      # @param response [Object]
+      # @return [Array] the [request, response] pair
+      def after_response_cache(request, response)
+        Tina4.cache_instance.after_cache(request, response)
+      end
+    end
+
     # ── Direct Cache API (same across all 4 languages) ──────────
 
     # Get a value from the cache by key.
@@ -244,13 +281,12 @@ module Tina4
           keys_to_remove.each { |k| @store.delete(k) }
           keys_to_remove.size
         end
-      elsif @backend.respond_to?(:sweep)
-        # The file backend supports an explicit sweep that returns a count.
-        @backend.sweep
       else
-        # Network/db backends expire entries lazily (TTL) — parity with
-        # Python, whose non-memory backends return 0 from sweep.
-        0
+        # Every backend answers sweep now - the base class returns 0 for the
+        # providers that expire server-side, and memory/file/database return a
+        # real count. The respond_to?(:sweep) guard that used to be here could
+        # not tell "not supported" from "evicted nothing".
+        @backend.sweep
       end
     end
 
@@ -305,7 +341,7 @@ module Tina4
     end
 
     # Internal: retrieve a cached response. Used by middleware hooks only.
-    def internal_lookup(method, url)
+    def internal_lookup(method, url, request = nil)
       return nil unless enabled?
       return nil unless method == "GET"
 
@@ -319,8 +355,8 @@ module Tina4
 
       # For memory backend, entry is a CacheEntry; for others, reconstruct
       if entry.is_a?(CacheEntry)
-        if Time.now.to_f > entry.expires_at
-          backend_delete(key)
+        if Time.now.to_f > entry.expires_at || !vary_matches?(entry, request)
+          backend_delete(key) if Time.now.to_f > entry.expires_at
           @mutex.synchronize { @misses += 1 }
           return nil
         end
@@ -328,36 +364,44 @@ module Tina4
         entry
       elsif entry.is_a?(Hash)
         expires_at = entry["expires_at"] || entry[:expires_at] || 0
-        if Time.now.to_f > expires_at
-          backend_delete(key)
-          @mutex.synchronize { @misses += 1 }
-          return nil
-        end
-        @mutex.synchronize { @hits += 1 }
-        CacheEntry.new(
+        rebuilt = CacheEntry.new(
           entry["body"] || entry[:body],
           entry["content_type"] || entry[:content_type],
           entry["status_code"] || entry[:status_code],
-          expires_at
+          expires_at,
+          entry["vary"] || entry[:vary] || [],
+          entry["vary_values"] || entry[:vary_values] || {}
         )
+        if Time.now.to_f > expires_at || !vary_matches?(rebuilt, request)
+          backend_delete(key) if Time.now.to_f > expires_at
+          @mutex.synchronize { @misses += 1 }
+          return nil
+        end
+        @mutex.synchronize { @hits += 1 }
+        rebuilt
       end
     end
 
     # Internal: store a response in the cache. Used by middleware hooks only.
-    def internal_store(method, url, status_code, content_type, body, ttl: nil)
+    def internal_store(method, url, status_code, content_type, body, ttl: nil, request: nil, response: nil)
       return unless enabled?
       return unless method == "GET"
       return unless @status_codes.include?(status_code)
+      return unless may_store?(request, response)
 
       effective_ttl = ttl || @ttl
       key = cache_key(method, url)
       expires_at = Time.now.to_f + effective_ttl
+      vary = vary_fields(response)
+      vary_values = vary.each_with_object({}) { |f, h| h[f] = header_value(request, f) }
 
       entry_data = {
         "body" => body,
         "content_type" => content_type,
         "status_code" => status_code,
-        "expires_at" => expires_at
+        "expires_at" => expires_at,
+        "vary" => vary,
+        "vary_values" => vary_values
       }
 
       case @backend_name
@@ -367,13 +411,87 @@ module Tina4
             oldest_key = @store.keys.first
             @store.delete(oldest_key)
           end
-          @store[key] = CacheEntry.new(body, content_type, status_code, expires_at)
+          @store[key] = CacheEntry.new(body, content_type, status_code, expires_at, vary, vary_values)
         end
       else
         backend_set(key, entry_data, effective_ttl)
       end
     end
 
+    # ── RFC 9111 conformance (shared-cache rules) ──────────────
+
+    # Response directives that let a SHARED cache store a response to a request
+    # carrying Authorization (RFC 9111 s3.5).
+    SHARED_CACHE_DIRECTIVES = %w[public s-maxage must-revalidate].freeze
+
+    # Case-insensitive header lookup on a request or response.
+    #
+    # @param carrier [Object, nil]
+    # @param name [String]
+    # @return [String, nil]
+    def header_value(carrier, name)
+      return nil if carrier.nil?
+      return nil unless carrier.respond_to?(:headers)
+
+      headers = carrier.headers
+      return nil unless headers.respond_to?(:each)
+
+      target = name.downcase
+      headers.each do |key, value|
+        return value.to_s if key.to_s.downcase == target
+      end
+      nil
+    end
+
+    # The lower-cased field names in a response's Vary header.
+    #
+    # @param response [Object, nil]
+    # @return [Array<String>]
+    def vary_fields(response)
+      raw = header_value(response, "Vary")
+      return [] if raw.nil? || raw.strip.empty?
+
+      raw.split(",").map { |f| f.strip.downcase }.reject(&:empty?)
+    end
+
+    # May a SHARED cache store this response? (RFC 9111 s3, s4.1)
+    #
+    # s3 -- "if the cache is shared: the Authorization header field is not
+    # present in the request ... or a response directive is present that
+    # explicitly allows shared caching". The key is method + URL only, so
+    # without this one authenticated caller's body is replayed to the next.
+    #
+    # s4.1 -- a stored response whose Vary contains "*" "always fails to
+    # match", so storing one is pointless.
+    #
+    # @param request [Object, nil]
+    # @param response [Object, nil]
+    # @return [Boolean]
+    def may_store?(request, response)
+      return false if vary_fields(response).include?("*")
+      return true if header_value(request, "Authorization").nil?
+
+      cache_control = header_value(response, "Cache-Control").to_s.downcase
+      SHARED_CACHE_DIRECTIVES.any? { |directive| cache_control.include?(directive) }
+    end
+
+    # Do the nominated request headers match the ones recorded on the entry?
+    #
+    # RFC 9111 s4.1 -- the cache MUST NOT use a stored response unless every
+    # request header field nominated by its Vary value matches. An absent field
+    # only matches an absent field.
+    #
+    # @param entry [CacheEntry]
+    # @param request [Object, nil]
+    # @return [Boolean]
+    def vary_matches?(entry, request)
+      vary = entry.respond_to?(:vary) ? (entry.vary || []) : []
+      return true if vary.empty?
+
+      recorded = entry.vary_values || {}
+      vary.all? { |field| header_value(request, field) == (recorded[field] || recorded[field.to_sym]) }
+    end
+
     # ── Backend initialization ─────────────────────────────────
 
     # Build the storage backend. Memory keeps an in-process LRU store on the

data/lib/tina4/router.rb

@@ -97,22 +97,68 @@ module Tina4
       end
     end
 
-    # Run per-route CLASS-based middleware. Function-style middleware
-    # (Proc/Lambda taking 3+ args: req, resp, next_handler) is skipped
-    # here — it's dispatched separately via #function_middleware which
-    # wraps the route handler in a continuation chain (see rack_app.rb).
+    # Run per-route middleware BEFORE the handler.
     #
-    # Returns true if all class-based middleware passed, false if any
-    # returned literal false (halt request).
+    # Dispatch is by SHAPE, in declaration order:
+    #
+    #   * a CLASS (or instance) declaring before_*/after_* hooks — handed to
+    #     Tina4::Middleware.run_before, the SAME orchestrator global middleware
+    #     goes through, so it gets the SAME hook discovery (definition order,
+    #     base->derived) and the SAME return-value table. There is no second,
+    #     divergent runner here.
+    #   * a String spec ("ResponseCache", "ResponseCache:300") — resolved to the
+    #     configured middleware first (parity with Python/PHP/Node).
+    #   * a 2-arg callable ("filter" middleware) — called directly; false halts.
+    #
+    # Function-style middleware (3+ args: req, resp, next_handler) is NOT run
+    # here — it wraps the handler in a continuation chain (see
+    # #function_middleware and DispatchPipeline#invoke_route_handler).
+    #
+    # This method used to call `mw.call(request, response)` on EVERYTHING. A
+    # class declaring `def self.before_auth` does not respond to .call, so
+    # per-route class middleware raised NoMethodError and the dispatcher turned
+    # every such request into a clean 500 — the documented per-route
+    # before_*/after_* mechanism never ran at all. The .call-everything body is
+    # superseded by the shape dispatch above; the 2-arg filter path below is
+    # what remains of it.
+    #
+    # Returns true if every middleware passed, false to halt (handler skipped).
     def run_middleware(request, response)
-      @middleware.each do |mw|
-        next if Route.function_middleware?(mw)
-        result = mw.call(request, response)
-        return false if result == false
+      hook_middleware.each do |mw|
+        if Route.filter_middleware?(mw)
+          next unless mw.call(request, response) == false
+
+          # Same `false` row of the return-value table a before_* hook gets:
+          # keep the response the filter set, 403 only if it set nothing.
+          Tina4::Middleware.refuse(response)
+          return false
+        else
+          return false unless Tina4::Middleware.run_before([mw], request, response)
+        end
       end
       true
     end
 
+    # Run per-route class middleware's after_* hooks, once the handler has run
+    # (or once a before_* halted). Same orchestrator, same discovery — see
+    # #run_middleware. Filter middleware has no after phase by construction.
+    def run_after_middleware(request, response)
+      hook_middleware.each do |mw|
+        next if Route.filter_middleware?(mw)
+
+        Tina4::Middleware.run_after([mw], request, response)
+      end
+      response
+    end
+
+    # Per-route middleware that takes part in the before/after passes:
+    # everything except function-style middleware, with String specs resolved
+    # to the middleware they name.
+    def hook_middleware
+      @middleware.reject { |mw| Route.function_middleware?(mw) }
+                 .map { |mw| mw.is_a?(::String) ? Router.resolve_string_middleware(mw) : mw }
+    end
+
     # Function-style middleware attached to this route, in declaration
     # order. The route dispatcher folds them into a Russian-doll
     # continuation chain — first declared is the OUTERMOST layer (runs
@@ -141,6 +187,22 @@ module Tina4
       false
     end
 
+    # Detect "filter" middleware: a plain 2-arg callable (Proc/Lambda/Method)
+    # that receives (request, response) and halts by returning false.
+    #
+    # This is the shape #run_middleware has always supported, kept working
+    # unchanged. It is NOT function middleware (3+ args, wraps the handler) and
+    # NOT class middleware (declares before_*/after_* hooks) — a Class or Module
+    # is never a filter even when it defines .call, because its hooks are the
+    # documented mechanism.
+    def self.filter_middleware?(mw)
+      return false if mw.is_a?(Class) || mw.is_a?(Module)
+
+      mw.respond_to?(:arity) && mw.respond_to?(:call)
+    rescue StandardError
+      false
+    end
+
     private
 
     def normalize_path(path)
@@ -295,6 +357,22 @@ module Tina4
   end
 
   module Router
+    # Known string-addressable middleware, for a route declared as
+    # `middleware: ["ResponseCache:300"]`. Matches PHP
+    # (Router::resolveStringMiddleware) and Node (resolveStringMiddleware),
+    # which both know exactly one name today. Python's registry is larger;
+    # unifying the three registries is scheduled separately, so this
+    # deliberately does NOT guess at Python's extra names.
+    #
+    # Each entry is a builder taking the parsed colon-args. See
+    # .resolve_string_middleware.
+    STRING_MIDDLEWARE = {
+      "ResponseCache" => lambda { |args|
+        ttl = args.first
+        ttl.to_s.match?(/\A\d+\z/) ? Tina4::ResponseCache.new(ttl: ttl.to_i) : Tina4::ResponseCache.new
+      }
+    }.freeze
+
     class << self
       def routes
         @routes ||= []
@@ -445,8 +523,23 @@ module Tina4
         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 in REGISTRATION order, which is what Python, PHP and Node
+        # all do. This used to be `ANY + method`, which made an ANY route beat
+        # every same-path specific route no matter when either was registered -
+        # so an app with an ordinary CMS catch-all (`any("/{slug}")`) silently
+        # swallowed the framework's own GET routes, `/__health` among them. The
+        # route was registered correctly; the router simply never reached it.
+        #
+        # `routes` is the registration-order array and `method_index` is the
+        # per-method fast path. With no ANY routes registered - the common case -
+        # the fast path is exactly what it was. Only an app that actually uses
+        # ANY pays for the ordered scan, and only that app needed it.
+        any_routes = method_index["ANY"]
+        candidates = if any_routes.nil? || any_routes.empty?
+                       method_index[normalized_method] || []
+                     else
+                       routes.select { |r| r.method == "ANY" || r.method == normalized_method }
+                     end
         candidates.each do |route|
           params = route.match_path(normalized_path)
           return [route, params] if params
@@ -534,6 +627,42 @@ module Tina4
         Tina4::Middleware.use(klass)
       end
 
+      # Resolve a string middleware spec to the middleware it names.
+      #
+      #   "ResponseCache"      -> ResponseCache with the default/env TTL
+      #   "ResponseCache:300"  -> ResponseCache with ttl = 300
+      #
+      # The head before the first ":" is the name; the colon-separated tail is
+      # its arguments. Same parse as Python's _resolve_string_middleware, PHP's
+      # Router::resolveStringMiddleware and Node's resolveStringMiddleware.
+      #
+      # ONE INSTANCE PER SPEC. Route middleware is resolved per dispatch in
+      # Ruby, so without memoising, every request would build a fresh
+      # ResponseCache with a fresh empty store and the cache could never hit.
+      # PHP memoises for exactly this reason; Python gets it for free by
+      # resolving once at registration.
+      #
+      # An unknown name RAISES, naming the known set — never a silent skip.
+      # Python raises ValueError, Node throws; a typo must surface, not
+      # quietly drop the middleware (which for an auth middleware would mean
+      # serving the route unprotected).
+      def resolve_string_middleware(spec)
+        spec = spec.to_s
+        @resolved_string_middleware ||= {}
+        return @resolved_string_middleware[spec] if @resolved_string_middleware.key?(spec)
+
+        name, _sep, tail = spec.partition(":")
+        builder = STRING_MIDDLEWARE[name]
+        unless builder
+          raise ArgumentError,
+                "Unknown middleware #{name.inspect}. Known string middleware: " \
+                "#{STRING_MIDDLEWARE.keys.sort.join(', ')}. For custom middleware, " \
+                "pass the class directly to .middleware(MyMiddleware)."
+        end
+
+        @resolved_string_middleware[spec] = builder.call(tail.empty? ? [] : tail.split(":"))
+      end
+
       def clear!
         @routes = []
         @method_index = Hash.new { |h, k| h[k] = [] }