tina4ruby 3.13.93 → 3.13.96

data/lib/tina4/middleware.rb

@@ -35,6 +35,32 @@ module Tina4
         global_middleware << klass unless global_middleware.include?(klass)
       end
 
+      # Global middleware that runs BEFORE route matching.
+      #
+      # A middleware opts in by declaring `def self.pre_match?; true; end`.
+      #
+      # NOT `before_match?` - the hook discovery treats every `before_*` method
+      # as a middleware hook and calls it with (request, response), so that name
+      # made the flag itself run as middleware and 500 the request.
+      # Everything else stays where it has always run - after matching - so
+      # this is additive and no existing middleware changes behaviour.
+      #
+      # The split exists because the two groups need opposite things. CORS must
+      # run before matching so its headers survive a short-circuited 401/403;
+      # a browser that gets a 401 without them reports a CORS error and the real
+      # status is invisible. CSRF must run AFTER, because it reads the matched
+      # route's metadata to honour a route marked no_auth - PHP shipped exactly
+      # that bypass as dead code once, because the metadata was not set yet.
+      def pre_match_middleware
+        global_middleware.select { |k| k.respond_to?(:pre_match?) && k.pre_match? }
+      end
+
+      # Global middleware that runs after matching, once the matched route's
+      # metadata is readable. This is the default.
+      def post_match_middleware
+        global_middleware.reject { |k| k.respond_to?(:pre_match?) && k.pre_match? }
+      end
+
       def clear!
         @before_handlers = []
         @after_handlers = []
@@ -47,17 +73,33 @@ module Tina4
       # Signature matches Python/PHP/Node orchestrators: pass the list of
       # middleware classes explicitly.
       #
+      # THE RETURN-VALUE CONTRACT is #apply_before_result below — one table,
+      # applied to EVERY before_* hook at EVERY scope. Per-route middleware
+      # comes through this same method (Tina4::Route#run_middleware), so there
+      # is exactly one implementation of the table, not two.
+      #
       # M2 — visible-but-resilient: every before_* call is wrapped so a THROW
       # never crashes the worker. On a throw the error is LOGGED and the
       # response becomes a clean 500 ({"error":"Internal Server Error",
       # "status":500}), then processing halts (handler skipped) — deterministic,
-      # never an unhandled exception. A before_* that sets status >= 400 also
-      # halts (the existing 4xx short-circuit). after_* still run on either
-      # halt path (see the dispatcher / #run_after docstring).
+      # never an unhandled exception. after_* still run on either halt path
+      # (see the dispatcher / #run_after docstring).
       #
       # Returns true on success, or false to halt the request (handler skipped).
       def run_before(middleware_classes, request, response)
-        # 1. Block-based before handlers (pattern-matched)
+        # The response object the CALLER holds. A hook may hand back a
+        # different Response; on a halt that object IS the answer, so its state
+        # is adopted onto this one before returning — otherwise the dispatcher
+        # would serve the object it still has a reference to and the
+        # short-circuit would silently vanish.
+        origin = response
+
+        # 1. Block-based before handlers (pattern-matched). These are a
+        #    Ruby-only surface (Python/PHP/Node have no block form) and keep
+        #    their historical "false halts" contract: a block's value is its
+        #    last expression, so reading a returned Response as a
+        #    short-circuit would fire on any block ending in a chainable
+        #    response call.
         before_handlers.each do |entry|
           next unless matches_pattern?(request.path, entry[:pattern])
 
@@ -79,14 +121,12 @@ module Tina4
               middleware_500(response, "#{class_label(klass)}.#{method_name}", error)
               return false
             end
-            # Support returning [request, response] (Python convention) or false to halt
-            if result == false
-              return false
-            elsif result.is_a?(Array) && result.length == 2
-              request, response = result
-              # If response already has a non-2xx status, halt processing
-              return false if response.status_code >= 400
-            end
+
+            halt, request, response = apply_before_result(result, request, response)
+            next unless halt
+
+            adopt_response(origin, response) unless response.equal?(origin)
+            return false
           end
         end
 
@@ -108,7 +148,17 @@ module Tina4
       # M2 — every after_* call is wrapped: a THROW is LOGGED and turns the
       # response into a clean 500, then the REMAINING after_* still run (they
       # may add headers/logging). Never an unhandled crash.
+      #
+      # RETURN VALUES: an after_* hook shapes the response the same way a
+      # before_* one does — a returned Tina4::Response BECOMES the response, a
+      # returned [request, response] pair rebinds both. What it CANNOT do is
+      # halt: the handler has already run, so there is nothing left to skip,
+      # and stopping the remaining after_* would contradict the AFTER-ON-4xx
+      # resilience rule above (they exist to add headers/logging on every path).
+      # So `false` and a >= 400 status are inert here by design.
       def run_after(middleware_classes, request, response)
+        origin = response
+
         # 1. Block-based after handlers (pattern-matched)
         after_handlers.each do |entry|
           next unless matches_pattern?(request.path, entry[:pattern])
@@ -129,11 +179,16 @@ module Tina4
               middleware_500(response, "#{class_label(klass)}.#{method_name}", error)
               next
             end
-            if result.is_a?(Array) && result.length == 2
+            if result.is_a?(Tina4::Response)
+              response = result
+            elsif result.is_a?(Array) && result.length == 2
               request, response = result
             end
           end
         end
+
+        adopt_response(origin, response) unless response.equal?(origin)
+        response
       end
 
       # Deterministic clean 500 for a middleware that threw. Logs the cause
@@ -156,8 +211,118 @@ module Tina4
         response.json({ error: "Internal Server Error", status: 500 }, 500)
       end
 
+      # The `false` row of the return-value table, on its own.
+      #
+      # A middleware that halts by returning false keeps the response it set;
+      # only a response still left default/empty becomes a 403. Public because
+      # per-route "filter" middleware (a 2-arg callable returning false, see
+      # Tina4::Route#run_middleware) must obey the SAME row as a before_* hook,
+      # and the rule should exist exactly once.
+      def refuse(response)
+        forbid(response) if default_response?(response)
+        response
+      end
+
       private
 
+      # ── THE BEFORE-HOOK RETURN-VALUE TABLE ────────────────────────────────
+      #
+      # Interpret ONE before_* hook's return value. Identical in Python, PHP,
+      # Ruby and Node, and applied at EVERY scope — global (Router.use) and
+      # per-route (route.middleware) both land here.
+      #
+      #   a Tina4::Response      SHORT-CIRCUIT. That object IS the response, at
+      #                          ANY status. This is the PRIMARY rule: it is the
+      #                          only one that can express a 302 redirect.
+      #   [request, response]    rebind both, continue
+      #   false                  SHORT-CIRCUIT. Send the response AS SET; only
+      #                          when it is still default/empty does it become a
+      #                          403. (Per-route middleware used to answer a
+      #                          halt with a HARDCODED 403 that threw away
+      #                          whatever the middleware had set — that is gone.)
+      #   nil / anything else    continue
+      #
+      # LEGACY COMPATIBILITY PATH (retained, deliberately NOT the main
+      # mechanism): after the hook returns, a response status >= 400 also
+      # short-circuits, even when the hook returned nil. Middleware written
+      # before the Response rule existed signals refusal that way, so it stays
+      # honoured — but it cannot express a 3xx redirect, which is exactly why
+      # the Response rule above is primary and this one is the fallback.
+      #
+      # This check used to be nested INSIDE the "returned a 2-element Array"
+      # branch, so a hook that set 403 and returned nil was ignored and the
+      # handler RAN — an auth middleware that refused without returning the pair
+      # was a no-op. Python, PHP and Node all check the status unconditionally
+      # after the call; Rails short-circuits on the response STATE, not on what
+      # the filter returned. Now it is unconditional here too.
+      #
+      # Returns [halt?, request, response].
+      def apply_before_result(result, request, response)
+        if result.is_a?(Tina4::Response)
+          return [true, request, result]
+        elsif result.is_a?(Array) && result.length == 2
+          request, response = result
+        elsif result == false
+          refuse(response)
+          return [true, request, response]
+        end
+
+        status = status_of(response)
+        return [true, request, response] if status.is_a?(Integer) && status >= 400
+
+        [false, request, response]
+      end
+
+      # Read a response's status defensively — a middleware may hand back any
+      # response-shaped object. Mirrors the Python master's
+      # `getattr(response, "status_code", None) or getattr(response, "status", 0)`.
+      def status_of(response)
+        return response.status_code if response.respond_to?(:status_code)
+        return response.status if response.respond_to?(:status)
+
+        nil
+      end
+
+      # Has this response been left untouched? Only then does a `false` return
+      # get turned into a 403 — a middleware that already answered keeps its
+      # own answer.
+      def default_response?(response)
+        status = status_of(response)
+        return false unless status.nil? || status == 200
+
+        body = response.respond_to?(:body) ? response.body : nil
+        body.to_s.empty?
+      end
+
+      # The canonical refusal, in the same shape as #middleware_500 so the two
+      # framework-generated error bodies match byte for byte across all four
+      # frameworks.
+      def forbid(response)
+        if response.respond_to?(:json)
+          response.json({ error: "Forbidden", status: 403 }, 403)
+        elsif response.respond_to?(:status_code=)
+          response.status_code = 403
+        end
+        response
+      end
+
+      # Copy a response's state onto the object the CALLER still holds.
+      #
+      # Ruby passes references, so a hook that MUTATES the response it was given
+      # needs nothing from us. This exists for the hook that hands back a
+      # DIFFERENT Response object: the contract says that object IS the
+      # response, and the dispatcher only ever serves the one it passed in.
+      # Applied on the halt paths, where the response is the answer.
+      def adopt_response(target, source)
+        return target unless target.is_a?(Tina4::Response) && source.is_a?(Tina4::Response)
+
+        target.status_code = source.status_code
+        target.headers     = source.headers
+        target.body        = source.body
+        target.cookies     = source.cookies
+        target
+      end
+
       # Human-readable label for a middleware (class name, or the class of an
       # instance) used in the logged 500 message.
       def class_label(klass)
@@ -249,54 +414,24 @@ module Tina4
   # ---------------------------------------------------------------------------
 
   # CorsClassMiddleware -- sets CORS headers from env vars on every response.
-  # Uses the same config source as CorsMiddleware module.
+  #
+  # A thin adapter over Tina4::CorsMiddleware, which owns the whole policy.
+  # It used to be a SECOND, independent implementation of the same rules and
+  # the two had already drifted: this copy had no wildcard/credentials guard,
+  # fell back to the Referer header (a full URL, not an origin), and on an
+  # allow-list MISS returned `allowed.first` - stamping some OTHER allowed
+  # origin onto the response of an origin that was not allowed at all. One
+  # feature, one implementation.
   class CorsClassMiddleware
     class << self
       def before_cors(request, response)
-        config = load_config
-        origin = resolve_origin(request, config)
-
-        response.headers["access-control-allow-origin"]  = origin
-        response.headers["access-control-allow-methods"] = config[:methods]
-        response.headers["access-control-allow-headers"] = config[:headers]
-        response.headers["access-control-max-age"]       = config[:max_age]
-        if config[:credentials] == "true"
-          response.headers["access-control-allow-credentials"] = "true"
-        end
-
-        [request, response]
-      end
-
-      private
+        env = request.respond_to?(:env) && request.env ? request.env : {}
+        origin = request.headers["origin"] if request.respond_to?(:headers)
+        env = env.merge("HTTP_ORIGIN" => origin) if origin
 
-      def load_config
-        {
-          origins:     ENV["TINA4_CORS_ORIGINS"]     || "*",
-          methods:     ENV["TINA4_CORS_METHODS"]     || "GET, POST, PUT, PATCH, DELETE, OPTIONS",
-          headers:     ENV["TINA4_CORS_HEADERS"]     || "Content-Type,Authorization,X-Request-ID",
-          max_age:     ENV["TINA4_CORS_MAX_AGE"]     || "86400",
-          credentials: ENV["TINA4_CORS_CREDENTIALS"] || "false"
-        }
-      end
-
-      def is_preflight(request)
-        request.method&.upcase == "OPTIONS" &&
-          request.headers["origin"] &&
-          request.headers["access-control-request-method"]
-      end
-
-      def resolve_origin(request, config)
-        request_origin = request.headers["origin"] || request.headers["referer"]
+        Tina4::CorsMiddleware.apply_headers(response.headers, env)
 
-        if config[:origins] == "*"
-          "*"
-        elsif request_origin
-          allowed = config[:origins].split(",").map(&:strip)
-          clean = request_origin.chomp("/")
-          allowed.include?(clean) ? clean : allowed.first || "*"
-        else
-          config[:origins].split(",").first&.strip || "*"
-        end
+        [request, response]
       end
     end
   end

data/lib/tina4/migration.rb

@@ -71,7 +71,23 @@ module Tina4
       created_at = Time.now.utc.strftime("%Y-%m-%d %H:%M:%S UTC")
       safe_name = description.gsub(/[^a-z0-9]+/i, "_").downcase.gsub(/^_|_$/, "")
 
-      if kind == "ruby" || kind == "python"
+      # MEASURED 2026-08-06: the accepted kind differed in every framework -
+      # python "python", php "php", ruby "ruby" OR "python", node "class" - and
+      # NONE validated it, so create_migration(..., kind="python") produced a
+      # code migration in Python and Ruby and a SILENT .sql file in PHP and
+      # Node. "code" is now the canonical spelling in all four; each keeps its
+      # own language name as a legacy alias; anything else raises.
+      # Ruby also accepted "python", which was a copy-paste from the master
+      # and is dropped: a Ruby project never wants a .py migration.
+      kind = (kind || "sql").to_s.strip.downcase
+      unless %w[sql code ruby].include?(kind)
+        raise ArgumentError,
+              "Unknown migration kind #{kind.inspect}. Use 'sql' (default) or " \
+              "'code' (alias: 'ruby'). An unrecognised kind used to produce a " \
+              ".sql file silently, which is why this now raises."
+      end
+
+      if %w[code ruby].include?(kind)
         filename = "#{timestamp}_#{safe_name}.rb"
         filepath = File.join(@migrations_dir, filename)
 

data/lib/tina4/orm.rb

@@ -120,6 +120,22 @@ module Tina4
       # Auto-map flag — defaults to TRUE for cross-framework parity (Python's
       # ORM has auto_map=True by default). The instance variable is treated
       # as "unset" when nil; only an explicit `false` disables it.
+      #
+      # INERT IN RUBY, DELIBERATELY. Nothing reads this flag: Ruby is
+      # snake_case-native, so the attribute name a developer writes IS the
+      # column name and there is nothing for a case mapping to do. It exists
+      # only so a model ported from PHP (where `autoMap` really does map a
+      # camelCase property onto a snake_case column) does not blow up on an
+      # unknown setter. Setting it either way changes NOTHING.
+      #
+      # This is not an oversight to "fix" by adding conversion: the owner's
+      # naming rule (2026-07-29) is that the column name must mirror the
+      # DATABASE, and a language-specific case mapping may only ever be an
+      # OPT-IN. Adding camel->snake here by default would be that mapping, on
+      # by default, which is the opposite. Use `field_mapping` to point an
+      # attribute at a differently-named column — that is the supported
+      # mechanism, and spec/orm_column_case_spec.rb pins all of this so the
+      # flag cannot quietly grow behaviour later.
       def auto_map
         defined?(@auto_map) && !@auto_map.nil? ? @auto_map : true
       end
@@ -302,7 +318,7 @@ module Tina4
         end
       end
 
-      def where(conditions, params = [], limit: nil, offset: nil, order_by: nil, include: nil)
+      def where(conditions, params = [], limit: 100, offset: nil, order_by: nil, include: nil)
         sql = "SELECT * FROM #{table_name}"
         if soft_delete
           sql += " WHERE (#{soft_delete_field} IS NULL OR #{soft_delete_field} = 0) AND (#{conditions})"
@@ -316,7 +332,7 @@ module Tina4
         instances
       end
 
-      def all(limit: nil, offset: nil, order_by: nil, include: nil)
+      def all(limit: 100, offset: nil, order_by: nil, include: nil)
         sql = "SELECT * FROM #{table_name}"
         if soft_delete
           sql += " WHERE #{soft_delete_field} IS NULL OR #{soft_delete_field} = 0"
@@ -328,7 +344,7 @@ module Tina4
         instances
       end
 
-      def select(sql, params = [], limit: nil, offset: nil, include: nil)
+      def select(sql, params = [], limit: 100, offset: nil, include: nil)
         results = db.fetch(sql, params, limit: limit, offset: offset)
         instances = results.map { |row| from_hash(row) }
         eager_load(instances, include) if include
@@ -340,6 +356,51 @@ module Tina4
         results.first
       end
 
+      # The ONE process-wide query cache, shared by every model.
+      #
+      # The Python master holds this as a module-level `_query_cache =
+      # Cache(default_ttl=0, max_size=500)` in orm/model.py, so every model shares
+      # a single store. A plain `@query_cache ||=` here would NOT be that
+      # contract: `class << self` ivars are per-class, so each subclass would get
+      # its own cache and User.clear_cache would silently leave Order's entries
+      # alone. Anchoring the ivar on ORM itself keeps one store for all models,
+      # however deep the subclass.
+      def query_cache
+        ORM.instance_variable_get(:@query_cache) ||
+          ORM.instance_variable_set(:@query_cache, QueryCache.new(default_ttl: 0, max_size: 500))
+      end
+
+      # SQL query with result caching. Returns an array of ORM instances.
+      #
+      # Parity with the Python master's `cached` (orm/model.py:1077): same key
+      # shape, same tag, and a miss delegates to `select` so eager loading and the
+      # row cap behave identically to an uncached read.
+      #
+      # Entries are tagged with the model name so #clear_cache invalidates only
+      # this model's queries and leaves every other model's cached reads intact.
+      def cached(sql, params = [], ttl: 60, limit: 100, offset: nil, include: nil)
+        key = "#{name}:#{QueryCache.query_key(sql, params)}:#{limit}:#{offset || 0}"
+
+        # nil-check, NOT a truthiness check: a query that legitimately returns no
+        # rows caches an empty array, and that is a HIT. Treating it as a miss
+        # would re-run the query on every call for exactly the queries where
+        # caching pays off most.
+        hit = query_cache.get(key)
+        return hit unless hit.nil?
+
+        result = select(sql, params, limit: limit, offset: offset, include: include)
+        query_cache.set(key, result, ttl: ttl, tags: [name])
+        result
+      end
+
+      # Invalidate every cached query for THIS model. Tag-scoped, so it never
+      # flushes another model's entries. Mirrors the master's
+      # `_query_cache.clear_tag(cls.__name__)`.
+      def clear_cache
+        query_cache.clear_tag(name)
+        nil
+      end
+
       def count(conditions = nil, params = [])
         sql = "SELECT COUNT(*) as cnt FROM #{table_name}"
         where_parts = []
@@ -372,7 +433,7 @@ module Tina4
         result
       end
 
-      def with_trashed(conditions = "1=1", params = [], limit: 20, offset: 0)
+      def with_trashed(conditions = "1=1", params = [], limit: 100, offset: 0)
         sql = "SELECT * FROM #{table_name} WHERE #{conditions}"
         results = db.fetch(sql, params, limit: limit, offset: offset)
         results.map { |row| from_hash(row) }
@@ -456,7 +517,11 @@ module Tina4
           end
 
           parts = ["#{name} #{sql_type}"]
-          parts << "PRIMARY KEY" if opts[:primary_key]
+          # A COMPOSITE key is declared ONCE, at table level (below). An inline
+          # PRIMARY KEY per column is invalid DDL - SQLite, PostgreSQL and MySQL
+          # all reject two of them in one table, so a composite-key model could
+          # not create its own table at all.
+          parts << "PRIMARY KEY" if opts[:primary_key] && primary_key_fields.length == 1
           parts << "AUTOINCREMENT" if opts[:auto_increment]
           parts << "NOT NULL" if !opts[:nullable] && !opts[:primary_key]
           # A JSON column carries no DDL DEFAULT (parity with the Python master):
@@ -474,6 +539,12 @@ module Tina4
           col_defs << parts.join(" ")
         end
 
+        # A COMPOSITE key is declared ONCE, at table level; the per-column inline
+        # form above is suppressed for it.
+        if primary_key_fields.length > 1
+          col_defs << "PRIMARY KEY (#{primary_key_fields.join(', ')})"
+        end
+
         sql = "CREATE TABLE IF NOT EXISTS #{table_name} (#{col_defs.join(', ')})"
 
         # Translate AUTOINCREMENT to the engine's auto-increment syntax
@@ -499,8 +570,8 @@ module Tina4
       end
 
       def scope(name, filter_sql, params = [])
-        define_singleton_method(name) do |limit: 20, offset: 0|
-          where(filter_sql, params)
+        define_singleton_method(name) do |limit: 100, offset: 0|
+          where(filter_sql, params, limit: limit, offset: offset)
         end
       end
 
@@ -705,6 +776,17 @@ module Tina4
     # existence makes the choice correct regardless of @persisted. Auto-increment
     # PKs keep the legacy @persisted-based decision (a nil PK means "new row,
     # let the engine assign an id").
+    # A filter hash naming EVERY primary-key column.
+    #
+    # Addressing a row by one column of a composite key matches every row
+    # sharing that value. Feature 4 removed that from the raw write path; this
+    # is the same rule for the ORM above it.
+    def pk_filter
+      self.class.primary_key_fields.each_with_object({}) do |name, acc|
+        acc[name] = __send__(name) if respond_to?(name)
+      end
+    end
+
     def save
       @errors = []
       @relationship_cache = {} # Clear relationship cache on save
@@ -740,7 +822,20 @@ module Tina4
           # itself fails (e.g. table missing), fall back to INSERT so the caller
           # sees the real driver error rather than a silent no-op UPDATE.
           begin
-            self.class.exists(pk_value)
+            # This asked exists(pk_value), which tests only ONE key column. On a
+            # composite key that is true for any row sharing it, so inserting a
+            # genuinely NEW row was decided to be an UPDATE and silently
+            # OVERWROTE a different row: saving (acme, a2) rewrote (acme, a1).
+            # The probe has to name the whole key, like the write that follows.
+            if self.class.primary_key_fields.length > 1
+              self.class.where(
+                pk_filter.keys.map { |k| "#{k} = ?" }.join(" AND "),
+                pk_filter.values,
+                limit: 1
+              ).any?
+            else
+              self.class.exists(pk_value)
+            end
           rescue StandardError
             false
           end
@@ -756,11 +851,13 @@ module Tina4
             # UPDATE is unchanged (#165 targets INSERT only): keep excluding nil
             # so a save never nulls a column the caller didn't touch.
             data = to_db_hash(exclude_nil: true)
-            filter = { pk => pk_value }
-            data.delete(pk)
-            # Remove mapped primary key too
-            mapped_pk = self.class.field_mapping[pk.to_s]
-            data.delete(mapped_pk.to_sym) if mapped_pk
+            filter = pk_filter
+            # Never SET a key column - it is what addresses the row.
+            self.class.primary_key_fields.each do |k|
+              data.delete(k)
+              mapped = self.class.field_mapping[k.to_s]
+              data.delete(mapped.to_sym) if mapped
+            end
             db.update(self.class.table_name, data, filter)
           else
             # #165: OMIT a column the caller left unset (value nil, never
@@ -854,10 +951,10 @@ module Tina4
           db.update(
             self.class.table_name,
             { self.class.soft_delete_field => 1 },
-            { pk => pk_value }
+            pk_filter
           )
         else
-          db.delete(self.class.table_name, { pk => pk_value })
+          db.delete(self.class.table_name, pk_filter)
         end
       end
       @persisted = false
@@ -870,7 +967,7 @@ module Tina4
       raise "Cannot delete: no primary key value" unless pk_value
 
       self.class.db.transaction do |db|
-        db.delete(self.class.table_name, { pk => pk_value })
+        db.delete(self.class.table_name, pk_filter)
       end
       @persisted = false
       true
@@ -887,7 +984,7 @@ module Tina4
         db.update(
           self.class.table_name,
           { self.class.soft_delete_field => 0 },
-          { pk => pk_value }
+          pk_filter
         )
       end
       __send__("#{self.class.soft_delete_field}=", 0) if respond_to?("#{self.class.soft_delete_field}=")