tina4ruby 3.13.98 → 3.13.99

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db66aec06f70379f6d717725d53c4d0a8a93c98f90cd65dff744e787a3c91593
-  data.tar.gz: 40240b850e132eec2cca262192eda3f6b3d228a2ee7c691d3b8d190a1e92bac6
+  metadata.gz: 11d1350ed25f20cfc7c7ba9757417c0eb33e87292eb45876d3bed30119fefcca
+  data.tar.gz: 8bd0d33d8ae49492bd8784fb838339951ad92439bf96a615d71ffe2e488dfd7a
 SHA512:
-  metadata.gz: 4b693353e1ae71d945e7f4b4526668c7e59a57a8fe440be5355a57015857b66b7be83663573ed74340e97122ac6cbccfb70fb22294d6c8559e058f66f6615ca2
-  data.tar.gz: 1d350415d02e713d96ffc3730d9aad377d011f5079caafffeae046e2ff51f3813ca640eecc91559d0fe9ae29999666f99f71aadc1528716f15d8234ce3f66d63
+  metadata.gz: e24bac573c4d4b58642fdc65071857c4a910dac229057f92c9eca2ba0936c1163a6e89bc79452c82f7d4601a4e64b0c10ce5c0af3e35384c16344491c6f61203
+  data.tar.gz: 0afe568dfd38eee2c0ce7c507b71b8c0110e11be10cce5197100244d30e56ac58e119b25a1e5757df8b26a9bb74172b4739d1e94ef029729e7b3e932e2847032

data/CHANGELOG.md

@@ -6,6 +6,90 @@ number means the same thing everywhere.
 **The authoritative release notes for every shipped version live in the documentation:**
 https://tina4.com/ruby/36-releases
 
+### Breaking: `request.params` is route-params-only, and `path_params` is renamed `params`
+
+Ruby had the worst version of the param-pollution bug: `params` used to merge the query
+string, the parsed body, AND the route params, so `request.params["id"]` could silently
+return a client-supplied value that shadowed the real route parameter. Client input now
+lives only in `request.query` and `request.body`. **The route-param accessor itself is
+renamed: `path_params` becomes `params`, with no alias.** A malformed JSON body used to parse
+to `{}`; it now returns the raw string it failed to parse. An empty body used to parse to
+`{}`; it now returns `nil`. `header()` lookup is case-fold only now (it no longer also
+converts `_` to `-`).
+
+**Migration.** Rename every `path_params` call site to `params`. Replace any `params[...]`
+read of a client-supplied value with `query[...]` or `body[...]`.
+
+### Breaking: security headers, CSRF, and the dev server default on
+
+`Content-Security-Policy: default-src 'self'` and the other security headers now emit by
+default (relax with `TINA4_CSP`; HSTS on HTTPS via `TINA4_HSTS`). The CSRF `403` body is
+unified to `{error, code, message, status}`, where Ruby used to send
+`{error: "CSRF_INVALID"}`. `TINA4_CSRF=true` now actually attaches the CSRF middleware, and a
+blank `TINA4_SECRET` fails closed instead of minting a forgeable public-default token. The
+dev server binds `127.0.0.1` by default (`TINA4_HOST=0.0.0.0` to expose it), refuses a
+cross-origin `/__dev` mutation, and never serves `.env` through the file endpoints. Static
+asset serving drops the `src/assets`/`assets` search directories and now honours
+`TINA4_PUBLIC_DIR`. A reflected XSS in the `403` error page is closed
+(`CGI.escapeHTML`-escaped now).
+
+**Migration.** Move assets under the configured public directory. Set `TINA4_CSP` if you
+depend on inline scripts or a third-party CDN.
+
+### Breaking: Mongo, MSSQL, and file-upload footguns closed
+
+An unparseable/unsupported MongoDB WHERE now raises instead of silently matching every
+document (a DELETE/UPDATE with no WHERE is rejected); `truncate()` on Mongo now actually
+empties the collection. The MSSQL adapter now raises on a genuinely unbindable parameter type
+instead of silently stringifying it (was preventing an injection/corruption risk). A repeated
+multipart file field now yields a list instead of silently dropping every upload but the
+last; an over-limit upload now answers `413` mid-stream instead of after buffering the whole
+body. Frond `{% include %}`/`{% extends %}`/`{% import %}` now raise on a path that escapes
+the templates directory.
+
+**Migration.** Add an explicit WHERE to any Mongo query relying on the old match-all
+fallback, or call `truncate()`. Handle `request.files[x]` as a list when multiple files can
+share a field name.
+
+### Breaking: ORM write-path and AutoCrud parity fixes
+
+`decimal_field` now emits a real `DECIMAL(p,s)` column instead of `REAL`, dropping precision
+and scale. A foreign-key auto `related_name` is now smart-pluralized (`Category` ->
+`categories`, not `categorys`). `validate()` on save now enforces length/type/format, where it
+used to check only for `null` -- a model that previously saved an over-length or
+wrong-format value now returns `false` from `save()` and writes nothing. `create_table()`
+injects the configured `soft_delete_field` automatically. `load()`'s signature changes to
+`load(filter, params, include)`, from `load(arg, params)` with no `include`, and it now
+JSON-coerces json columns. AutoCrud returns `422` (was `500`) on an invalid create/update, and
+never accepts `is_deleted` or a client-supplied primary key in the write body. `seed_table`'s
+`seed:` keyword is dropped, `FakeData#boolean` returns a native `true`/`false` (was `0`/`1`),
+and `seed_orm`'s idempotency skip is opt-in now via `idempotent:` (was unconditional -- it
+silently returned `seeded: 0` when the table already held enough rows).
+
+**Migration.** Update any accessor using the misspelled `categorys` name. Pass the RNG seed to
+your own `FakeData` instance instead of `seed_table(seed: ...)`. Update any `load()` call
+using the old positional shape.
+
+### Breaking: response, database-adapter, and dev-tooling fixes
+
+Responses gzip-compress when eligible; a cacheable 200 gets a strong ETag, and the
+static-file ETag format is unified to `W/"<size>-<mtime>"` across all four frameworks. Error
+pages can emit JSON now, not only HTML: `403`/`404`/`500` all negotiate `Accept`, and `404`
+carries a `request_id`. An undecorated route emits only `200` in the OpenAPI spec;
+`description` is omitted when unset instead of `description:""`. A route group's prefix join
+is normalized to match PHP. `tina4ruby serve` now honours `TINA4_PORT`, where it used to read
+only the bare `PORT` variable. `serverInfo.version` over MCP now reports the real framework
+version instead of `1.0.0`. The inline `@tests` descriptor builders are renamed
+`Tina4::Testing.assert_*` -> `expect_*`. `DatabaseAdapter::CONTRACT` was fictional (it named
+methods no driver implemented, and omitted `execute_many`/`fetch_one`); `get_database_type`
+existed on none of the seven drivers and is added to all of them. A legacy bracket-wrapped
+log-level spelling that duplicated the variable name inside the brackets is rejected now; use
+the plain level name (for example `TINA4_LOG_LEVEL=ALL`).
+
+**Migration.** Rename any `assert_*` descriptor call to `expect_*`. Reconcile `TINA4_PORT` vs
+bare `PORT` if your app set both. Expect every cache to revalidate once after upgrade, since
+the static-file ETag format changed.
+
 ### Breaking: Messenger `inbox()` / `read()` item shapes (3.13.96 parity)
 
 The IMAP read path is aligned to the settled cross-framework shape (Python is the

data/lib/tina4/ai.rb

@@ -70,10 +70,21 @@ module Tina4
       # Fetch the bytes at `url`, following up to `limit` redirects. Returns
       # nil on any network/HTTP failure so the caller can skip gracefully.
       #
+      # MEASURED 2026-08-13 on the real suite (not a mock): install_skills
+      # makes up to 18 sequential HTTPS calls (3 skills x 2 targets x
+      # (1 SKILL.md + refs)) to raw.githubusercontent.com, and a single
+      # transient timeout/reset on any one of them silently dropped that
+      # whole skill - `installed` came back missing "tina4-maintainer" with
+      # no other symptom. A short retry on the TRANSPORT-level failure modes
+      # only (never on a clean HTTP response, which is a real answer, not a
+      # glitch) is the fix a real end user running `tina4 ai` needs too, not
+      # just this suite.
+      #
       # @param url [String]
       # @param limit [Integer] max redirects to follow
+      # @param retries [Integer] transient-failure retries before giving up
       # @return [String, nil]
-      def fetch_bytes(url, limit = 5)
+      def fetch_bytes(url, limit = 5, retries = 2)
         return nil if limit <= 0
 
         uri = URI.parse(url)
@@ -85,15 +96,33 @@ module Tina4
         response = http.get(uri.request_uri)
         case response
         when Net::HTTPSuccess
-          response.body
+          return response.body
         when Net::HTTPRedirection
           location = response["location"]
-          location ? fetch_bytes(location, limit - 1) : nil
+          return location ? fetch_bytes(location, limit - 1, retries) : nil
         end
+
+        # Not a success or a redirect. A throttle/server hiccup (429 rate
+        # limit, 502/503/504) is worth one retry; anything else (404, a real
+        # 4xx) is a genuine answer - retrying would not change it.
+        return fetch_and_retry(url, limit, retries) if retries.positive? && TRANSIENT_HTTP_CODES.include?(response.code)
+
+        nil
+      rescue Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNRESET, Errno::ECONNREFUSED, SocketError, EOFError
+        return nil unless retries.positive?
+
+        fetch_and_retry(url, limit, retries)
       rescue StandardError
         nil
       end
 
+      TRANSIENT_HTTP_CODES = %w[429 500 502 503 504].freeze
+
+      def fetch_and_retry(url, limit, retries)
+        sleep(0.5)
+        fetch_bytes(url, limit, retries - 1)
+      end
+
       # Install the Tina4 SKILL.md skills into the project AND the user's
       # global ~/.claude/skills, network-fetched from the release tag matching
       # this framework version. Returns the skills fully installed.

data/lib/tina4/api.rb

@@ -107,7 +107,12 @@ module Tina4
       end
 
       @base_url = base_url.chomp("/")
+      # VERSION-DEC-03 (feature 130): every outbound request carries a
+      # default `Tina4/<version>` User-Agent. `headers` (the caller's own,
+      # from the constructor kwarg) is merged in LAST, so a caller-supplied
+      # "User-Agent" always wins -- this is a default, never a clobber.
       @headers = {
+        "User-Agent" => "Tina4/#{Tina4::VERSION}",
         "Content-Type" => "application/json",
         "Accept" => "application/json"
       }.merge(headers)

data/lib/tina4/auto_crud.rb

@@ -3,6 +3,14 @@ require "json"
 
 module Tina4
   module AutoCrud
+    # PAGE-DEC-01: the maximum per-page size the list handler will honour, no
+    # matter what a caller asks for via ?limit=/?per_page=. 100 is not an
+    # arbitrary pick - it is the SAME row cap ORM.all/db.fetch already default
+    # to, and the number Node's AutoCrud shares via its own DEFAULT_ROW_CAP
+    # constant. Without this a client could request the whole table in one
+    # query (?limit=1000000).
+    MAX_PER_PAGE = 100
+
     class << self
       # Track registered model classes
       def models
@@ -85,7 +93,16 @@ module Tina4
         Tina4::Router.add("GET", "#{prefix}/#{table}", proc { |req, res|
           begin
             per_page = (req.query["per_page"] || req.query["limit"] || 10).to_i
+            # PAGE-DEC-01: cap an oversized ?per_page=/?limit= BEFORE it is used to
+            # derive offset below, so the offset lines up with the size actually
+            # used (a client can no longer request the whole table in one query).
+            per_page = [per_page, MAX_PER_PAGE].min
             page     = (req.query["page"] || 1).to_i
+            # PAGE-DEC-01: clamp page < 1 -> page 1 BEFORE deriving offset, so
+            # offset=(page-1)*per_page can never go negative (page=0/negative used
+            # to hand PostgreSQL a negative OFFSET - a driver error - and silently
+            # misbehave on SQLite, while the envelope reported page:0).
+            page     = [page, 1].max
             limit    = per_page
             offset   = req.query["offset"] ? req.query["offset"].to_i : (page - 1) * per_page
             order_by = parse_sort(req.query["sort"])
@@ -149,9 +166,17 @@ module Tina4
         # POST /api/{table} -- create record
         post_route = Tina4::Router.add("POST", "#{prefix}/#{table}", proc { |req, res|
           begin
-            attributes = req.body_parsed
-            record = model_class.create(attributes)
-            if record.persisted?
+            # CRUD-MASS-ASSIGNMENT: allow-list before the body ever reaches
+            # the model (guards is_deleted + strips the PK -- see the helper).
+            attributes = allow_listed_attributes(model_class, req.body_parsed, is_create: true)
+            record = model_class.new(attributes)
+            # CRUD-VALIDATION-STATUS (CRUD-DEC-01): build + save directly
+            # (not .create, which returns the literal `false` on failure --
+            # calling .persisted? on that raised NoMethodError, caught by the
+            # generic rescue below as a stray 500). #save already returns
+            # self/false and #errors already carries the field messages, so
+            # this is the SAME safe pattern the PUT handler uses.
+            if record.save
               res.json({ data: record.to_h }, status: 201)
             else
               res.json({ errors: record.errors }, status: 422)
@@ -181,7 +206,9 @@ module Tina4
               next res.json({ error: "Not found" }, status: 404)
             end
 
-            attributes = req.body_parsed
+            # CRUD-MASS-ASSIGNMENT: allow-list -- the row is addressed by the
+            # URL {id}, never by the body (see the helper).
+            attributes = allow_listed_attributes(model_class, req.body_parsed, is_create: false)
             attributes.each do |key, value|
               setter = "#{key}="
               record.__send__(setter, value) if record.respond_to?(setter)
@@ -266,6 +293,37 @@ module Tina4
 
       private
 
+      # CRUD-MASS-ASSIGNMENT: filter a write body down to writable columns
+      # before it ever reaches `.new`/the setter loop. Only DECLARED fields
+      # (model_class.field_definitions) pass through; is_deleted is never
+      # client-writable (soft-delete is mutated only by #delete/#restore);
+      # and the primary key is stripped except a genuinely natural
+      # (single-column, non-auto_increment) key on CREATE -- the documented
+      # way to choose one (build_example keeps such a key in the sample
+      # body). Every other case strips it: an auto-increment CREATE (the
+      # database assigns it -- a client-supplied id previously let a POST
+      # silently claim/overwrite an unrelated row), and EVERY update (the
+      # row is addressed by the URL {id} alone; a body PK would otherwise
+      # move #save's own pk_filter WHERE clause off the URL-addressed row).
+      def allow_listed_attributes(model_class, data, is_create:)
+        return {} unless data.is_a?(Hash)
+
+        defs = model_class.respond_to?(:field_definitions) ? model_class.field_definitions : {}
+        pk_fields = model_class.respond_to?(:primary_key_fields) ? model_class.primary_key_fields.map(&:to_s) : []
+        single_pk = pk_fields.length == 1 ? pk_fields.first : nil
+        auto_increment = single_pk && defs[single_pk.to_sym] && defs[single_pk.to_sym][:auto_increment]
+        strip_pk = is_create ? !(single_pk && !auto_increment) : true
+
+        data.each_with_object({}) do |(key, value), allowed|
+          key_s = key.to_s
+          next unless defs.key?(key_s.to_sym)
+          next if key_s == "is_deleted"
+          next if strip_pk && pk_fields.include?(key_s)
+
+          allowed[key] = value
+        end
+      end
+
       # Parse sort parameter: "-name,created_at" => "name DESC, created_at ASC"
       def parse_sort(sort_str)
         return nil if sort_str.nil? || sort_str.empty?

data/lib/tina4/background.rb

@@ -7,37 +7,110 @@ module Tina4
   # PHP's `$app->background($callback, $interval)` — a callback that runs
   # periodically alongside the server lifecycle.
   #
-  # Ruby has no asyncio event loop, so each task runs in its own thread.
-  # The GIL keeps it cooperative-enough for the periodic work this is meant
-  # for (queue draining, health checks, simulators). Errors in the callback
-  # are caught and logged so they don't kill the thread.
+  # Ruby has no asyncio event loop, so each task runs in its own dedicated OS
+  # thread, started at registration time. Because the thread runs regardless of
+  # which web server (Puma/WEBrick) is in front, a Ruby background task is never
+  # a silent no-op under production — the thread IS the runtime (contrast the
+  # Python ASGI / PHP-FPM silent-no-op the other frameworks had to fix). The GIL
+  # keeps it cooperative-enough for the periodic work this is meant for (queue
+  # draining, health checks, simulators). Errors in the callback are caught and
+  # logged so they don't kill the thread.
   module Background
+    # Handle for one registered background task — the ONE background surface,
+    # identical across the four frameworks: a handle with a boolean `stop` plus a
+    # count. Mirrors Python's `BackgroundTask` (`handle.stop()`), PHP's
+    # `Tina4\BackgroundTask` (`$handle->stop()`) and Node's `background()` handle
+    # (`handle.stop()`).
+    #
+    # It also answers `[:callback]`/`[:interval]`/`[:thread]`/`[:running]` (read
+    # AND write) so a descriptor and a handle are the same object — code that
+    # introspected the old Hash descriptor keeps working unchanged.
+    class Task
+      attr_accessor :callback, :interval, :thread, :running
+
+      def initialize(callback, interval)
+        @callback = callback
+        @interval = interval
+        @thread = nil
+        @running = false
+      end
+
+      # Stop this task and DEREGISTER it. Idempotent — a second call is a safe
+      # no-op that returns false.
+      #
+      # @param timeout [Float] Seconds to wait for an in-flight run before killing.
+      # @return [Boolean] true if this call removed the task, false if already gone.
+      def stop(timeout: 2.0)
+        Background.stop_task(self, timeout: timeout)
+      end
+
+      # @return [Boolean] true once stop has run (the task is no longer running).
+      def stopped?
+        !@running
+      end
+
+      # @return [Boolean] true while the task is registered and ticking.
+      def running?
+        @running
+      end
+
+      # Hash-style read, so `task[:thread]` / `task[:running]` still work.
+      def [](key)
+        case key
+        when :callback then @callback
+        when :interval then @interval
+        when :thread then @thread
+        when :running then @running
+        end
+      end
+
+      # Hash-style write, so the scheduler's `task[:thread] = ...` still works.
+      def []=(key, value)
+        case key
+        when :callback then @callback = value
+        when :interval then @interval = value
+        when :thread then @thread = value
+        when :running then @running = value
+        end
+      end
+    end
+
     class << self
       # Register a periodic callback.
       #
       # @param callback [#call, nil] Object responding to `call` with no args.
       # @param interval [Float] Seconds between invocations (default 1.0).
       # @param block    [Proc]   Optional block (used if callback is nil).
-      # @return [Hash] The registered task descriptor.
+      # @return [Task] The registered task handle — call `.stop` to end it.
       def register(callback = nil, interval: 1.0, &block)
         cb = callback || block
         raise ArgumentError, "background requires a callback or block" if cb.nil?
         raise ArgumentError, "callback must respond to :call" unless cb.respond_to?(:call)
 
-        task = { callback: cb, interval: interval.to_f, thread: nil, running: false }
+        task = Task.new(cb, interval.to_f)
         mutex.synchronize { tasks << task }
         start_task(task)
         task
       end
 
-      # All registered task descriptors. Tests use this for introspection.
+      # All registered task handles. Tests use this for introspection.
       def tasks
         @tasks ||= []
       end
 
+      # Number of REGISTERED background tasks (stopped ones are already gone).
+      # The count half of the ONE shared surface, matching Python's
+      # `background_task_count()`, PHP's `backgroundTaskCount()` and Node's
+      # `backgroundTaskCount()`.
+      #
+      # @return [Integer]
+      def count
+        mutex.synchronize { tasks.length }
+      end
+
       # Stop and join every running task. Called on graceful shutdown.
       #
-      # Each stop_task deregisters its own descriptor, so there is no blanket
+      # Each stop_task deregisters its own handle, so there is no blanket
       # `tasks.clear` here: clearing would ALSO drop a task registered while
       # this loop was running — leaving its thread alive but invisible in the
       # registry, which is the worse of the two failure modes.
@@ -46,29 +119,37 @@ module Tina4
         snapshot.each { |task| stop_task(task, timeout: timeout) }
       end
 
-      # Stop a single task and DEREGISTER it. Used by tests that register, fire,
-      # then stop, and by any subsystem that owns a task for part of its life
+      # Stop a single task and DEREGISTER it. Used by `Task#stop`, by graceful
+      # shutdown, and by any subsystem that owns a task for part of its life
       # (e.g. Mqtt::Client#stop_keepalive).
       #
-      # The descriptor is removed from `tasks` so the registry never reports a
-      # stopped task as registered — leaving it in place made `tasks` grow for
-      # the life of the process on every start/stop cycle and made introspection
-      # lie about what is actually running.
+      # The handle is removed from `tasks` so the registry never reports a stopped
+      # task as registered — leaving it in place made `tasks` grow for the life of
+      # the process on every start/stop cycle and made introspection lie about
+      # what is actually running.
+      #
+      # Idempotent: a second call on the same handle removes nothing, finds no
+      # thread and returns false.
       #
-      # Idempotent: a second call on the same descriptor removes nothing, finds
-      # no thread and returns safely.
+      # @return [Boolean] true if this call removed a registered task, else false.
       def stop_task(task, timeout: 2.0)
-        task[:running] = false
-        # Identity, not equality: `tasks.delete(task)` uses `==`, which would
-        # take out any OTHER descriptor that happens to hold an equal Hash
-        # (same callback, same interval). Only this exact descriptor goes.
-        mutex.synchronize { tasks.delete_if { |registered| registered.equal?(task) } }
+        task.running = false
+        # Identity, not equality: `tasks.delete(task)` uses `==`, which would take
+        # out any OTHER handle that happens to compare equal. Only this exact one
+        # goes, and we record whether it WAS registered so stop() is a truthful bool.
+        was_registered = mutex.synchronize do
+          present = tasks.any? { |registered| registered.equal?(task) }
+          tasks.delete_if { |registered| registered.equal?(task) }
+          present
+        end
 
-        thread = task[:thread]
-        return unless thread
+        thread = task.thread
+        if thread
+          thread.join(timeout) || thread.kill
+          task.thread = nil
+        end
 
-        thread.join(timeout) || thread.kill
-        task[:thread] = nil
+        was_registered
       end
 
       private
@@ -78,14 +159,14 @@ module Tina4
       end
 
       def start_task(task)
-        task[:running] = true
-        task[:thread] = Thread.new do
-          while task[:running]
-            sleep task[:interval]
-            break unless task[:running]
+        task.running = true
+        task.thread = Thread.new do
+          while task.running
+            sleep task.interval
+            break unless task.running
 
             begin
-              task[:callback].call
+              task.callback.call
             rescue => e
               # Never let a callback error kill the thread — next interval still fires.
               if defined?(Tina4::Log) && Tina4::Log.respond_to?(:error)

data/lib/tina4/cache.rb

@@ -140,8 +140,9 @@ module Tina4
       @mutex.synchronize { @store.size }
     end
 
-    # Generate a stable cache key from a SQL query and params.
-    # Mirrors SQLTranslator.query_key for direct use on QueryCache.
+    # Generate a stable cache key from a SQL query and params. This is the ONE
+    # query-key source used by the ORM cache path (the former duplicate on
+    # SQLTranslator was removed - SQLTRANS-DEC-02).
     #
     # @param sql [String]
     # @param params [Array, nil]