tina4ruby 3.13.38 → 3.13.40

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ed3d68931d97c88f7d7ea9128420ce4b531da04f47536c3f64abac71f3edbb3
-  data.tar.gz: 4124c02d8ddefcb645eee1d5a52ddef31a4e2ebeecfd11fe81b7999a3784802a
+  metadata.gz: 0bb742a8cdfa909ee27c95cce703f14f678f03f93b764aea62501b4afde78e91
+  data.tar.gz: 3e0da501f8911d1df438ecebdab6b2f8ef67be7b66d39927672c23f089b351c4
 SHA512:
-  metadata.gz: 6a5f5f009385d5e4ce97d0289db83d2d60d1bb2410019c88892fe5f6c22fc2c358654021965ebe4a8b2d159ac7958dd6b57ba41c8b879cf385cc6632428666c5
-  data.tar.gz: 4a7d3a41ce8ca5e8283318d487745b90c726e03c648c4480807c8e2fd40910d7472e5371e0c910ef6e68e914d057d65faaa4955efaf585bc93d84919ac567de6
+  metadata.gz: 1f6998cc599c7ebae85a3a0020b8146721ca653a84f7f65635226072781aac2ad41ccec3cf3a749063960e3f1bae47c3e3eca97fe58375d6c01c0a5df7359487
+  data.tar.gz: ce0653713c6f9e0659b5f26a6068690db7915ccbc8cdeb87ca54c8cfe609c2b700f6e90a5f6ca90b8f6c198d33edbcea70599bb050855259504fd831f16b90f6

data/README.md

@@ -2,7 +2,7 @@
   <img src="https://tina4.com/logo.svg" alt="Tina4" width="200">
 </p>
 <h1 align="center">Tina4 Ruby</h1>
-<h3 align="center">TINA4 — The Intelligent Native Application 4ramework</h3>
+<h3 align="center">TINA4: The Intelligent Native Application 4ramework</h3>
 <p align="center"><em>Simple. Fast. Human. &nbsp;|&nbsp; Built for AI. Built for you.</em></p>
 <p align="center">55 built-in features. Zero runtime dependencies. One require, everything works.</p>
 <p align="center">
@@ -18,7 +18,7 @@
 ## Quick Start
 
 ```bash
-# With the Tina4 CLI (recommended — enables SCSS + live reload)
+# With the Tina4 CLI (recommended, enables SCSS + live reload)
 cargo install tina4    # or grab a binary from https://github.com/tina4stack/tina4/releases
 tina4 init ruby ./my-app
 cd my-app && tina4 serve
@@ -56,12 +56,12 @@ db = Tina4::Database.new("sqlite://app.db")
 | Category | Features |
 |----------|----------|
 | **Core HTTP** (7) | Router with path params (`{id:int}`, `{p:path}`), Server, Request/Response, Middleware pipeline, Static file serving, CORS |
-| **Database** (6) | SQLite, PostgreSQL, MySQL, MSSQL, Firebird — unified adapter, connection pooling, query cache, transactions, race-safe ID generation, SQL dialect translation |
+| **Database** (6) | SQLite, PostgreSQL, MySQL, MSSQL, Firebird: unified adapter, connection pooling, query cache, transactions, race-safe ID generation, SQL dialect translation |
 | **ORM** (7) | Active Record with typed fields, relationships (`has_one`/`has_many`/`belongs_to`), soft delete, QueryBuilder + MongoDB support, Auto-CRUD generator, migrations with rollback |
 | **Auth & Security** (5) | JWT (HS256/RS256), password hashing (PBKDF2-SHA256), API key validation, rate limiting, CSRF form tokens |
 | **Templating** (3) | Frond engine (Twig/Jinja2-compatible, pre-compiled 2.8× faster), SCSS auto-compilation, built-in CSS (~24 KB) |
 | **API & Integration** (5) | HTTP client (zero-dep), GraphQL with ORM auto-schema + GraphiQL IDE, WSDL/SOAP with auto WSDL, WebSocket (RFC 6455) + Redis backplane, MCP server (24 dev tools) |
-| **Background** (3) | Job queue (File/RabbitMQ/Kafka/MongoDB) with priority, delay, retry, dead letters — service runner — event system (on/emit/once/off) |
+| **Background** (3) | Job queue (File/RabbitMQ/Kafka/MongoDB) with priority, delay, retry, dead letters; service runner; event system (on/emit/once/off) |
 | **Data & Storage** (4) | Session (File/Redis/Valkey/MongoDB/DB), response cache (LRU, TTL), seeder + 50+ fake data generators, messenger (SMTP/IMAP) |
 | **Developer Tools** (7) | Dev dashboard (11 tabs), dev toolbar, error overlay (Catppuccin Mocha), dev mailbox, hot reload + CSS hot-reload, code metrics (complexity, coupling, maintainability), AI context installer (7 tools) |
 | **Utilities** (7) | DI container (transient + singleton), HtmlElement builder, inline testing (`@tests` decorator), i18n (6 languages), Swagger/OpenAPI auto-generation, CLI scaffolding (`generate model/route/migration/middleware`), structured logging |
@@ -84,14 +84,14 @@ tina4ruby generate model <name>
 
 ## Performance
 
-Benchmarked with `wrk` — 5,000 requests, 50 concurrent, median of 3 runs:
+Benchmarked with `wrk`: 5,000 requests, 50 concurrent, median of 3 runs:
 
 | Framework | JSON req/s | Deps | Features |
 |-----------|-----------|------|----------|
 | **Tina4 Ruby** | **10,243** | 0 | 55 |
 | Sinatra | 9,548 | 5+ | ~4 |
 
-Tina4 Ruby outperforms Sinatra while delivering **55 features vs ~4** — with zero runtime dependencies.
+Tina4 Ruby outperforms Sinatra while delivering **55 features vs ~4**, with zero runtime dependencies.
 
 **Across all 4 Tina4 implementations:**
 
@@ -105,7 +105,7 @@ Tina4 Ruby outperforms Sinatra while delivering **55 features vs ~4** — with z
 
 ## Cross-Framework Parity
 
-Tina4 ships identical features across four languages — same architecture, same conventions, same 55 features:
+Tina4 ships identical features across four languages: same architecture, same conventions, same 55 features:
 
 | | Python | PHP | Ruby | Node.js |
 |---|--------|-----|------|---------|

data/lib/tina4/api.rb

@@ -1,10 +1,17 @@
 # frozen_string_literal: true
 require "net/http"
+require "openssl"
 require "uri"
 require "json"
 require "base64"
 
 module Tina4
+  # Statuses that warrant an automatic retry when max_retries > 0: rate-limit
+  # (429) plus the transient server-side 5xx family. 4xx client errors (401,
+  # 404, …) are NOT retried — a repeat won't succeed. Parity with the Python
+  # master's _RETRY_STATUSES.
+  API_RETRY_STATUSES = [429, 500, 502, 503, 504].freeze
+
   class API
     attr_reader :base_url, :headers
 
@@ -18,9 +25,16 @@ module Tina4
     #     api = Tina4::API.new("https://self-signed.local", verify_ssl: false)
     #
     # Bearer wins over basic-auth when both are passed.
+    #
+    # 3.13.39: +max_retries / +retry_backoff enable opt-in automatic retry with
+    # exponential backoff (default max_retries: 0 = off, non-breaking) on a
+    # transport error (APIResponse#status == 0) or a retryable status
+    # (429/5xx). A retried non-idempotent request (POST/PUT/PATCH/DELETE) may be
+    # re-sent — retries are opt-in for exactly that reason. Parity with the
+    # Python master.
     def initialize(base_url, headers: {}, timeout: 30,
                    bearer_token: nil, username: nil, password: nil,
-                   verify_ssl: nil)
+                   verify_ssl: nil, max_retries: 0, retry_backoff: 0.5)
       @base_url = base_url.chomp("/")
       @headers = {
         "Content-Type" => "application/json",
@@ -28,6 +42,8 @@ module Tina4
       }.merge(headers)
       @timeout = timeout
       @verify_ssl = verify_ssl
+      @max_retries = [0, max_retries.to_i].max
+      @retry_backoff = retry_backoff.to_f
 
       # Bearer wins over basic-auth when both passed
       if bearer_token
@@ -142,9 +158,35 @@ module Tina4
       end
     end
 
+    # Execute the request with opt-in retry/backoff. Returns an APIResponse.
+    #
+    # With @max_retries > 0, a transport error (APIResponse#status == 0, the
+    # existing error sentinel) or a retryable status (429/5xx) is retried up to
+    # @max_retries times with exponential backoff (@retry_backoff seconds base,
+    # doubling each attempt); any other outcome (2xx, 3xx, other 4xx) returns at
+    # once. Parity with the Python master's _request.
     def execute(uri, request)
+      attempts = @max_retries + 1
+      response = nil
+      (0...attempts).each do |attempt|
+        response = attempt_request(uri, request)
+        code = response.status
+        retryable = code.zero? || API_RETRY_STATUSES.include?(code)
+        return response if !retryable || attempt == attempts - 1
+
+        sleep(@retry_backoff * (2**attempt))
+      end
+      response
+    end
+
+    # A single HTTP attempt. Returns the standardized APIResponse.
+    def attempt_request(uri, request)
       http = Net::HTTP.new(uri.host, uri.port)
       http.use_ssl = uri.scheme == "https"
+      # 3.13.39: honour verify_ssl: false (the dead-since-3.13.1 kwarg). Only
+      # disable verification when EXPLICITLY false — nil/true keep the secure
+      # default (OpenSSL::SSL::VERIFY_PEER).
+      http.verify_mode = OpenSSL::SSL::VERIFY_NONE if @verify_ssl == false
       http.open_timeout = @timeout
       http.read_timeout = @timeout
 

data/lib/tina4/auth.rb

@@ -15,7 +15,11 @@ module Tina4
     BLANK_SECRET_WARNING =
       "Auth: TINA4_SECRET is not set — JWT signing is insecure. Set TINA4_SECRET " \
       "to a random value (e.g. `openssl rand -hex 32`) in your environment or " \
-      ".env before serving traffic."
+      ".env before serving traffic. " \
+      "For LOCAL DEV, set TINA4_DEBUG=true and a per-machine secret is generated " \
+      "automatically into .env.local (gitignored). Seeing this warning means the " \
+      "run was NOT detected as dev - typically a container or CI without " \
+      "TINA4_DEBUG set, or TINA4_ENV=production."
 
     class << self
       def setup(root_dir = Dir.pwd)

data/lib/tina4/cli.rb

@@ -287,6 +287,10 @@ module Tina4
             status_icon = r[:status] == "success" ? "OK" : "FAIL"
             puts "  [#{status_icon}] #{r[:name]}"
           end
+          # FAIL-FAST: a failed migration must give CI a non-zero exit (parity
+          # with the Python master). Only the startup auto-migration hook
+          # swallows failures; the explicit CLI does not.
+          exit 1 if results.any? { |r| r[:status] == "failed" }
         end
       end
     end

data/lib/tina4/database.rb

@@ -255,6 +255,17 @@ module Tina4
         end
       end
 
+      # Autocommit is ON by default — parity with Python/PHP/Node. A standalone
+      # write (execute/insert/update/delete made OUTSIDE an explicit
+      # start_transaction()/commit() block) commits on its own connection before
+      # returning, so a write actually persists. An UNSET TINA4_AUTOCOMMIT is
+      # treated as TRUE; set TINA4_AUTOCOMMIT=false for strict manual mode (every
+      # write needs an explicit commit). Inside an explicit transaction the
+      # framework-issued commit is suppressed (gated on the thread tx-pin), so
+      # explicit transactions stay atomic. Mirrors Python's
+      # DatabaseAdapter._autocommit ("true"/"1"/"yes", default "true").
+      @autocommit = truthy?(ENV.fetch("TINA4_AUTOCOMMIT", "true"))
+
       # Register this connection so Tina4::Database.reset_request_caches can
       # clear its request-scoped entries at the start of every HTTP request.
       Tina4::Database.register_instance(self)
@@ -282,10 +293,11 @@ module Tina4
       @driver.connect(@connection_string, username: @username, password: @password)
       @connected = true
 
-      # Enable autocommit if TINA4_AUTOCOMMIT env var is set
-      if truthy?(ENV["TINA4_AUTOCOMMIT"]) && @driver.respond_to?(:autocommit=)
-        @driver.autocommit = true
-      end
+      # Push the resolved autocommit setting down to the driver when it exposes a
+      # native toggle (default ON — see @autocommit in #initialize). The
+      # framework-level commit in #autocommit_standalone_write covers drivers
+      # that have no native setter.
+      @driver.autocommit = @autocommit if @driver.respond_to?(:autocommit=)
 
       Tina4::Log.info("Database connected: #{@driver_name}")
     rescue => e
@@ -488,7 +500,9 @@ module Tina4
       placeholders = drv.placeholders(columns.length)
       sql = "INSERT INTO #{table} (#{columns.join(', ')}) VALUES (#{placeholders})"
       drv.execute(sql, data.values)
-      { success: true, last_id: drv.last_insert_id }
+      last_id = drv.last_insert_id
+      autocommit_standalone_write(drv)
+      { success: true, last_id: last_id }
     end
 
     def update(table, data, filter = {}, params = nil)
@@ -501,6 +515,7 @@ module Tina4
         sql = "UPDATE #{table} SET #{set_parts.join(', ')}"
         sql += " WHERE #{filter}" unless filter.empty?
         drv.execute(sql, data.values + Array(params))
+        autocommit_standalone_write(drv)
         return { success: true }
       end
 
@@ -510,6 +525,7 @@ module Tina4
       sql += " WHERE #{where_parts.join(' AND ')}" unless filter.empty?
       values = data.values + filter.values
       drv.execute(sql, values)
+      autocommit_standalone_write(drv)
       { success: true }
     end
 
@@ -528,6 +544,7 @@ module Tina4
         sql = "DELETE FROM #{table}"
         sql += " WHERE #{filter}" unless filter.empty?
         drv.execute(sql, Array(params))
+        autocommit_standalone_write(drv)
         return { success: true }
       end
 
@@ -536,6 +553,7 @@ module Tina4
       sql = "DELETE FROM #{table}"
       sql += " WHERE #{where_parts.join(' AND ')}" unless filter.empty?
       drv.execute(sql, filter.values)
+      autocommit_standalone_write(drv)
       { success: true }
     end
 
@@ -582,8 +600,10 @@ module Tina4
     # or a clean { error: } payload respectively.
     def execute(sql, params = [])
       cache_invalidate if @cache_enabled
-      result = current_driver.execute(sql, params)
+      drv = current_driver
+      result = drv.execute(sql, params)
       @last_error = nil
+      autocommit_standalone_write(drv)
       sql_upper = sql.strip.upcase
       if sql_upper.include?("RETURNING") || sql_upper.start_with?("CALL ") ||
          sql_upper.start_with?("EXEC ") || sql_upper.start_with?("SELECT ")
@@ -1104,6 +1124,31 @@ module Tina4
       %w[true 1 yes on].include?((val || "").to_s.strip.downcase)
     end
 
+    # Durability: commit a standalone write so it actually persists.
+    #
+    # Called after a write (execute/insert/update/delete) issued OUTSIDE an
+    # explicit transaction. The commit is suppressed when autocommit is off
+    # (TINA4_AUTOCOMMIT=false, strict manual mode) OR when a transaction is open
+    # on this thread (the thread tx-pin is set) — so an explicit
+    # start_transaction()/commit() block stays atomic and is never broken up by
+    # a per-statement commit. A commit with no transaction in progress is a
+    # harmless no-op on every engine (SQLite swallows the specific
+    # "no transaction is active" error in its driver; PostgreSQL/MySQL/MSSQL emit
+    # at most a benign warning), so this never raises in the common case. Mirrors
+    # the `not self._in_transaction and self.autocommit` gate in the Python
+    # master and PHP's `autoCommit && transaction === null`.
+    def autocommit_standalone_write(drv)
+      return unless @autocommit
+      return unless Thread.current[@tx_pin_key].nil?
+
+      drv.commit
+    rescue StandardError => e
+      # A standalone write already succeeded; a follow-up commit failure here
+      # must not mask that. Capture for #get_error and log, but don't raise.
+      @last_error = e.message
+      Tina4::Log.warning("autocommit commit after standalone write failed: #{e.message}")
+    end
+
     # "persistent" / "request" / "off" — mirrors Python connection.py.
     def cache_mode
       if @cache_persistent

data/lib/tina4/dev_admin.rb

@@ -312,6 +312,19 @@ module Tina4
         @error_tracker ||= ErrorTracker.new
       end
 
+      # Drop the lazily-memoized dev singletons so the next access rebuilds
+      # them from the CURRENT environment. The mailbox in particular resolves
+      # its directory from `TINA4_MAILBOX_DIR`/`data/mailbox` at construction
+      # time, so a singleton built under one env must not leak into a later
+      # caller (or test) running under a different env. Safe to call anytime —
+      # it only nils the caches.
+      def reset_singletons!
+        @message_log = nil
+        @request_inspector = nil
+        @mailbox = nil
+        @error_tracker = nil
+      end
+
       def enabled?
         Tina4::Env.is_truthy(ENV["TINA4_DEBUG"])
       end
@@ -631,19 +644,25 @@ module Tina4
           json_response(deps_install(body))
         when ["GET", "/__dev/api/git/status"]
           json_response(git_status_payload)
+        # All four MCP surfaces (REST shim + JSON-RPC + SSE) go through
+        # with_mcp_gate: capability (Tina4.mcp_enabled?) decides whether MCP
+        # runs at all (off → route behaves as unmounted, nil → RackApp 404,
+        # no info leak); per-request authorisation on the RAW socket peer +
+        # token decides whether THIS caller may use it (loopback always,
+        # remote only with TINA4_MCP_REMOTE + a valid TINA4_MCP_TOKEN — denied
+        # → 404 mcp_forbidden). The dev tools expose powerful ops (DB query,
+        # file read/WRITE, route listing). Mirrors the Python master gate.
         when ["GET", "/__dev/api/mcp/tools"]
-          json_response(mcp_tools_list)
+          with_mcp_gate(env) { json_response(mcp_tools_list) }
         when ["POST", "/__dev/api/mcp/call"]
-          body = read_json_body(env) || {}
-          json_response(mcp_tool_call(body))
-        # JSON-RPC + SSE endpoints that real MCP clients (Claude Code/Desktop)
-        # speak. Mounted on the same dispatch as the REST shim above and gated
-        # on the same enabled? (TINA4_DEBUG) check, so disabled → 404. They
-        # share the default MCP server's tool registry with the REST shim.
+          with_mcp_gate(env) do
+            body = read_json_body(env) || {}
+            json_response(mcp_tool_call(body))
+          end
         when ["POST", "/__dev/mcp"], ["POST", "/__dev/mcp/message"]
-          mcp_jsonrpc(env)
+          with_mcp_gate(env) { mcp_jsonrpc(env) }
         when ["GET", "/__dev/mcp/sse"]
-          mcp_sse_handshake
+          with_mcp_gate(env) { mcp_sse_handshake }
         when ["GET", "/__dev/api/scaffold"]
           json_response(scaffold_templates)
         when ["POST", "/__dev/api/scaffold/run"]
@@ -1570,6 +1589,70 @@ module Tina4
         end
       end
 
+      # Gate an MCP surface. Yields to the handler block only for an authorised
+      # caller. Returns:
+      #   nil            — capability off (route behaves as unmounted → 404, no
+      #                    "MCP exists" info leak; matches PHP not mounting it)
+      #   mcp_forbidden  — capability on but this caller is denied (explicit 404)
+      #   block result   — authorised caller proceeds
+      def with_mcp_gate(env)
+        return nil unless Tina4.mcp_enabled?
+        return mcp_forbidden unless mcp_request_allowed?(env)
+
+        yield
+      end
+
+      # 404 payload for a disallowed MCP request (parity with Python/PHP).
+      def mcp_forbidden
+        [404, { "content-type" => "application/json; charset=utf-8" },
+         [JSON.generate({ "error" => "MCP forbidden" })]]
+      end
+
+      # Per-request MCP authorisation using the RAW socket peer.
+      #
+      # Reads env["REMOTE_ADDR"] (never X-Forwarded-For — spoofable) and the
+      # token, then delegates to Tina4.request_allowed?. Loopback is always
+      # allowed; a remote caller needs TINA4_MCP_REMOTE=true plus a valid
+      # token. Mirrors the Python dev_admin _mcp_request_allowed.
+      def mcp_request_allowed?(env)
+        remote_ip = (env["REMOTE_ADDR"] || "").to_s
+        Tina4.request_allowed?(remote_ip, has_valid_token: mcp_token_ok?(env))
+      end
+
+      # Whether the request carried a token matching TINA4_MCP_TOKEN.
+      #
+      # Token transports (in order): Authorization: Bearer, X-MCP-Token,
+      # X-Api-Key. Compared timing-safe against TINA4_MCP_TOKEN (fallback
+      # TINA4_API_KEY). With NO configured token this returns false, so a
+      # remote caller can never present a "valid" token by accident.
+      def mcp_token_ok?(env)
+        expected = ENV["TINA4_MCP_TOKEN"]
+        expected = ENV["TINA4_API_KEY"] if expected.nil? || expected.empty?
+        return false if expected.nil? || expected.empty?
+
+        provided = ""
+        auth = (env["HTTP_AUTHORIZATION"] || "").to_s
+        provided = auth[7..].to_s.strip if auth.downcase.start_with?("bearer ")
+        provided = (env["HTTP_X_MCP_TOKEN"] || "").to_s if provided.empty?
+        provided = (env["HTTP_X_API_KEY"] || "").to_s if provided.empty?
+        return false if provided.empty?
+
+        secure_equal?(expected.to_s, provided)
+      end
+
+      # Constant-time string comparison (length check first so the
+      # fixed-length compare never raises on a mismatch).
+      def secure_equal?(expected, provided)
+        return false unless expected.bytesize == provided.bytesize
+
+        OpenSSL.fixed_length_secure_compare(expected, provided)
+      rescue StandardError
+        # Fallback for very old OpenSSL without fixed_length_secure_compare.
+        res = 0
+        expected.bytes.zip(provided.bytes) { |a, b| res |= (a ^ b.to_i) }
+        res.zero?
+      end
+
       def mcp_tools_list
         return { tools: [], count: 0 } unless defined?(Tina4::McpServer)
         server = Tina4._default_mcp_server