tina4ruby 3.12.2 → 3.12.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a97e5249b5ffd22de2dac45ce08f27e217c9c1253192d41b036b0ef90e14dc11
-  data.tar.gz: d2a67f3f7a4e11dab682f2333e4aed920ada9ba553737c5c77899ed3b7bf8cd2
+  metadata.gz: be4da6079e890067fdf914b4dc287a01f68eeee914a51cd97f13e1d768d3d334
+  data.tar.gz: 61df8b97ae56df7aba1d40feee95d5f0208b969c5166cce97d8e6b65289ed720
 SHA512:
-  metadata.gz: beb243e57f2aa6df523fe64e63c2057a46058d711acda139342ca06144fd207949e24a3a35d25787d1f110bf7bead2cd85178c1cefb0c8158e46be89e7f31004
-  data.tar.gz: dd2169f5c8837fe90185e9c81eb5bd6e5fa49819230cf6ec79207f32aa6288a6eaec80236d565d7a0b561d08a95f7c0949456d21abd8ac887425c54ac7fe1997
+  metadata.gz: c2b2f07c1a30c66c114b7c77845751d6b8125125392cf8adf49689b23378c73d61b79a8882013eeccc6b28ce86dd15121437ec51e228690345c08f32d10572cf
+  data.tar.gz: b63ed9e9ffedece9880e1e57c43e355ec6b8ed4c5418914557ebb163e020728c5b8c0b4cfa41c08f86aae70160b2862eebbc52f128a0116cb6bc700bf4b63105

data/lib/tina4/ai.rb

@@ -212,11 +212,18 @@ module Tina4
           next unless system("which #{cmd} > /dev/null 2>&1")
 
           result = `#{cmd} install --upgrade tina4-ai 2>&1`
+          # Subprocess output is ASCII-8BIT — force UTF-8 with byte replacement
+          # so non-ASCII content (often emitted by pip on locale mismatch)
+          # doesn't crash String#strip with Encoding::CompatibilityError.
+          safe_result = result.dup.force_encoding("UTF-8")
+          unless safe_result.valid_encoding?
+            safe_result = safe_result.encode("UTF-8", "UTF-8", invalid: :replace, undef: :replace, replace: "?")
+          end
           if $?.success?
             puts "  \e[32m✓\e[0m Installed tina4-ai (mdview)"
             return
           else
-            puts "  \e[33m!\e[0m #{cmd} failed: #{result.strip[0..100]}"
+            puts "  \e[33m!\e[0m #{cmd} failed: #{safe_result.strip[0..100]}"
           end
         end
         puts "  \e[33m!\e[0m Python/pip not available -- skip tina4-ai"

data/lib/tina4/container.rb

@@ -61,7 +61,7 @@ module Tina4
       end
 
       # Check if a service is registered.
-      def has(name)
+      def has?(name)
         registry.key?(name.to_sym)
       end
 

data/lib/tina4/database.rb

@@ -83,7 +83,7 @@ module Tina4
     }.freeze
 
     # Static factory — cross-framework consistency: Database.create(url)
-    def self.create(url, username: "", password: "", pool: 0)
+    def self.create(url, username: "", password: "", pool: nil)
       new(url, username: username.empty? ? nil : username,
                password: password.empty? ? nil : password,
                pool: pool)
@@ -91,7 +91,7 @@ module Tina4
 
     # Construct a Database from environment variables.
     # Returns nil if the named env var is not set.
-    def self.from_env(env_key: "TINA4_DATABASE_URL", pool: 0)
+    def self.from_env(env_key: "TINA4_DATABASE_URL", pool: nil)
       url = ENV[env_key]
       return nil if url.nil? || url.strip.empty?
 
@@ -101,12 +101,18 @@ module Tina4
           pool: pool)
     end
 
-    def initialize(connection_string = nil, username: nil, password: nil, driver_name: nil, pool: 0)
+    def initialize(connection_string = nil, username: nil, password: nil, driver_name: nil, pool: nil)
       @connection_string = connection_string || ENV["TINA4_DATABASE_URL"]
       @username = username || ENV["TINA4_DATABASE_USERNAME"]
       @password = password || ENV["TINA4_DATABASE_PASSWORD"]
       @driver_name = driver_name || detect_driver(@connection_string)
-      @pool_size = pool  # 0 = single connection, N>0 = N pooled connections
+      # TINA4_DB_POOL falls back when caller doesn't pass `pool:` explicitly.
+      # Default 0 = single connection, N>0 = N pooled connections (round-robin).
+      @pool_size = if pool.nil?
+                     (ENV["TINA4_DB_POOL"] || "0").to_i
+                   else
+                     pool
+                   end
       @connected = false
 
       # Per-instance thread-local key for the transaction adapter pin.

data/lib/tina4/env.rb

@@ -62,7 +62,7 @@ module Tina4
     end
     lines.concat([
                    "",
-                   "Run `tina4 env-migrate` to rewrite your .env automatically,",
+                   "Run `tina4 env --migrate` to rewrite your .env automatically,",
                    "or rename manually. See https://tina4.com/release/3.12.0",
                    "Set TINA4_ALLOW_LEGACY_ENV=true to bypass during migration.",
                    sep, ""
@@ -132,6 +132,12 @@ module Tina4
       private
 
       def resolve_env_file(root_dir)
+        # TINA4_ENV_FILE wins — explicit path or filename (resolved against root_dir).
+        explicit = ENV["TINA4_ENV_FILE"]
+        if explicit && !explicit.empty?
+          return File.absolute_path?(explicit) ? explicit : File.join(root_dir, explicit)
+        end
+
         environment = ENV["ENVIRONMENT"]
         if environment && !environment.empty?
           candidate = File.join(root_dir, ".env.#{environment}")

data/lib/tina4/frond.rb

@@ -190,6 +190,11 @@ module Tina4
     end
 
     # Render a template file with data. Uses token caching for performance.
+    #
+    # Caching strategy:
+    #   * TINA4_DEBUG=true        — never cache (always re-read + re-tokenize).
+    #   * TINA4_TEMPLATE_CACHE_TTL > 0 — cache entries expire after N seconds.
+    #   * TINA4_TEMPLATE_CACHE_TTL == 0 (default in production) — permanent cache.
     def render(template, data = {})
       context = @globals.merge(stringify_keys(data))
 
@@ -197,11 +202,16 @@ module Tina4
       raise "Template not found: #{path}" unless File.exist?(path)
 
       debug_mode = ENV.fetch("TINA4_DEBUG", "").downcase == "true"
+      ttl = (ENV["TINA4_TEMPLATE_CACHE_TTL"] || "0").to_i
 
       unless debug_mode
-        # Production: use permanent cache (no filesystem checks)
         cached = @compiled[template]
-        return execute_cached(cached[0], context) if cached
+        if cached
+          # cached layout: [tokens, mtime, cached_at]
+          tokens, _mtime, cached_at = cached
+          fresh = ttl <= 0 || (Time.now.to_i - cached_at.to_i) < ttl
+          return execute_cached(tokens, context) if fresh
+        end
       end
       # Dev mode: skip cache entirely — always re-read and re-tokenize
       # so edits to partials and extended base templates are detected
@@ -210,7 +220,7 @@ module Tina4
       source = File.read(path, encoding: "utf-8")
       mtime = File.mtime(path)
       tokens = tokenize(source)
-      @compiled[template] = [tokens, mtime]
+      @compiled[template] = [tokens, mtime, Time.now.to_i]
       execute_with_tokens(source, tokens, context)
     end
 

data/lib/tina4/graphql.rb

@@ -845,6 +845,14 @@ module Tina4
   class GraphQL
     attr_reader :schema
 
+    # Class-level toggle for ORM auto-schema generation. Defaults to true,
+    # can be disabled via TINA4_GRAPHQL_AUTO_SCHEMA=false. Initializers and
+    # user app code can branch on this before calling `schema.from_orm(...)`.
+    def self.auto_schema_enabled?
+      val = ENV.fetch("TINA4_GRAPHQL_AUTO_SCHEMA", "true").to_s.strip.downcase
+      !%w[false 0 no off].include?(val)
+    end
+
     def initialize(schema = nil)
       @schema = schema || GraphQLSchema.new
       @executor = GraphQLExecutor.new(@schema)
@@ -916,7 +924,12 @@ module Tina4
     #   gql.register_route           # POST /graphql
     #   gql.register_route("/api/graphql")  # custom path
     #
-    def register_route(path = "/graphql")
+    def register_route(path = nil)
+      # TINA4_GRAPHQL_ENDPOINT — defaults to /graphql when caller doesn't override.
+      path ||= ENV.fetch("TINA4_GRAPHQL_ENDPOINT", "/graphql")
+      path = path.to_s
+      path = "/#{path}" unless path.start_with?("/")
+
       graphql = self
       Tina4.post path, auth: false do |request, response|
         body = request.body

data/lib/tina4/health.rb

@@ -7,8 +7,19 @@ module Tina4
     START_TIME = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
     class << self
+      # Return the configured health endpoint path.
+      # TINA4_HEALTH_PATH overrides the default "/__health" — kept consistent across all 4 frameworks.
+      def path
+        configured = ENV["TINA4_HEALTH_PATH"]
+        return "/__health" if configured.nil? || configured.empty?
+        configured.start_with?("/") ? configured : "/#{configured}"
+      end
+
       def register!
-        Tina4::Router.add("GET", "/health", method(:handle))
+        # Register at the configured path. The legacy "/health" path stays
+        # registered for backward-compat.
+        Tina4::Router.add("GET", path, method(:handle))
+        Tina4::Router.add("GET", "/health", method(:handle)) unless path == "/health"
       end
 
       def handle(_request, response)

data/lib/tina4/log.rb

@@ -2,6 +2,7 @@
 
 require "fileutils"
 require "json"
+require "logger"
 
 module Tina4
   module Log
@@ -27,23 +28,74 @@ module Tina4
     # ANSI escape code regex for stripping from file output
     ANSI_RE = /\033\[[0-9;]*m/
 
+    # Defaults used when env vars are unset.
+    DEFAULT_ROTATE_SIZE = 10 * 1024 * 1024 # 10MB
+    DEFAULT_ROTATE_KEEP = 5
+
     class << self
-      attr_reader :log_dir
+      attr_reader :log_dir, :log_file_path
 
       def configure(root_dir = Dir.pwd)
-        @log_dir = File.join(root_dir, "logs")
+        # TINA4_LOG_DIR — relative or absolute. Default "logs".
+        log_dir_env = ENV["TINA4_LOG_DIR"]
+        log_dir_env = "logs" if log_dir_env.nil? || log_dir_env.empty?
+        @log_dir = if File.absolute_path?(log_dir_env)
+                     log_dir_env
+                   else
+                     File.join(root_dir, log_dir_env)
+                   end
         FileUtils.mkdir_p(@log_dir)
 
-        @max_size_mb = (ENV["TINA4_LOG_MAX_SIZE"] || "10").to_i
-        @max_size = @max_size_mb * 1024 * 1024
-        @keep = (ENV["TINA4_LOG_KEEP"] || "5").to_i
-        @json_mode = production?
-        @log_file = File.join(@log_dir, "tina4.log")
+        # TINA4_LOG_FILE — explicit log file path (absolute or relative to log_dir).
+        # Default: <log_dir>/tina4.log.
+        log_file_env = ENV["TINA4_LOG_FILE"]
+        @log_file_path = if log_file_env && !log_file_env.empty?
+                           File.absolute_path?(log_file_env) ? log_file_env : File.join(@log_dir, log_file_env)
+                         else
+                           File.join(@log_dir, "tina4.log")
+                         end
+
+        # TINA4_LOG_ROTATE_SIZE — bytes per file before rotation. 0 = no rotation.
+        @rotate_size = (ENV["TINA4_LOG_ROTATE_SIZE"] || DEFAULT_ROTATE_SIZE).to_i
+        # TINA4_LOG_ROTATE_KEEP — number of rotated backups to keep.
+        @rotate_keep = (ENV["TINA4_LOG_ROTATE_KEEP"] || DEFAULT_ROTATE_KEEP).to_i
+
+        # TINA4_LOG_FORMAT — "text" or "json". Defaults to "json" in production, else "text".
+        format_env = ENV["TINA4_LOG_FORMAT"]
+        @format = format_env && !format_env.empty? ? format_env.downcase : (production? ? "json" : "text")
+        @json_mode = @format == "json"
+
+        # TINA4_LOG_OUTPUT — "stdout", "file", or "both". Defaults to "both".
+        output_env = ENV["TINA4_LOG_OUTPUT"]
+        @output = output_env && !output_env.empty? ? output_env.downcase : "both"
+        unless %w[stdout file both].include?(@output)
+          @output = "both"
+        end
+
+        # TINA4_LOG_CRITICAL — when true, raise on log write failures instead of swallowing.
+        @critical = truthy?(ENV["TINA4_LOG_CRITICAL"])
 
         @console_level = resolve_level
         @request_id = nil
         @current_context = {}
         @mutex = Mutex.new
+
+        # Build the file logger via stdlib Logger which handles rotation natively.
+        # Logger.new(path, shift_age, shift_size):
+        #   shift_age  = number of files to keep
+        #   shift_size = bytes before rotation
+        # When @rotate_size is 0, omit rotation args.
+        close_file_logger
+        if @output != "stdout"
+          @file_logger = if @rotate_size > 0
+                           ::Logger.new(@log_file_path, @rotate_keep, @rotate_size)
+                         else
+                           ::Logger.new(@log_file_path)
+                         end
+          # We do our own formatting — strip Logger's default formatter.
+          @file_logger.formatter = proc { |_sev, _t, _p, msg| msg.to_s.end_with?("\n") ? msg : "#{msg}\n" }
+        end
+
         @initialized = true
       end
 
@@ -79,8 +131,19 @@ module Tina4
         log(:error, message, context)
       end
 
+      # Test/teardown helper — closes the underlying Logger so the file
+      # handle is released (Windows / tmpdir cleanup).
+      def close_file_logger
+        @file_logger&.close rescue nil
+        @file_logger = nil
+      end
+
       private
 
+      def truthy?(val)
+        %w[true 1 yes on].include?(val.to_s.strip.downcase)
+      end
+
       def production?
         env = ENV["TINA4_ENV"] || ENV["RACK_ENV"] || ENV["RUBY_ENV"] || "development"
         env.downcase == "production"
@@ -92,9 +155,9 @@ module Tina4
 
         formatted = format_line(level, message)
 
-        # Console output respects TINA4_LOG_LEVEL
+        # Console output respects TINA4_LOG_LEVEL and TINA4_LOG_OUTPUT
         severity = SEVERITY_MAP[level] || 0
-        if severity >= @console_level
+        if severity >= @console_level && @output != "file"
           if @json_mode
             $stdout.puts json_line(level, message)
           else
@@ -102,8 +165,11 @@ module Tina4
           end
         end
 
-        # File always gets ALL levels, plain text (no ANSI)
-        write_to_file(strip_ansi(formatted))
+        # File output — always full level (consumer parses themselves) — unless disabled.
+        if @output != "stdout" && @file_logger
+          payload = @json_mode ? json_line(level, message) : strip_ansi(formatted)
+          write_to_file(payload)
+        end
 
         @current_context = {}
       end
@@ -166,37 +232,12 @@ module Tina4
       end
 
       def write_to_file(line)
-        rotate_if_needed
-        begin
-          File.open(@log_file, "a") { |f| f.puts(line) }
-        rescue IOError, SystemCallError
-          # Don't crash on log write failure
-        end
-      end
-
-      # Numbered rotation: tina4.log → tina4.log.1 → tina4.log.2 → ... → tina4.log.{keep}
-      def rotate_if_needed
-        return unless File.exist?(@log_file)
-
-        begin
-          return if File.size(@log_file) < @max_size
-        rescue SystemCallError
-          return
-        end
-
-        # Delete the oldest rotated file if it exists
-        oldest = "#{@log_file}.#{@keep}"
-        File.delete(oldest) if File.exist?(oldest)
-
-        # Shift existing rotated files: .{n} → .{n+1}
-        (@keep - 1).downto(1) do |n|
-          src = "#{@log_file}.#{n}"
-          dst = "#{@log_file}.#{n + 1}"
-          File.rename(src, dst) if File.exist?(src)
-        end
-
-        # Rename current log to .1
-        File.rename(@log_file, "#{@log_file}.1") rescue nil
+        return unless @file_logger
+        # Use << to bypass Logger's severity filtering — we already filtered above.
+        @file_logger << "#{line}\n"
+      rescue IOError, SystemCallError => e
+        raise if @critical
+        # Don't crash on log write failure
       end
     end
   end

data/lib/tina4/mcp.rb

@@ -136,6 +136,30 @@ module Tina4
     ["localhost", "127.0.0.1", "0.0.0.0", "::1", ""].include?(host)
   end
 
+  # Resolve whether the built-in MCP dev server should be active.
+  #
+  # Precedence:
+  #   * TINA4_MCP set explicitly → use that (truthy/falsey).
+  #   * Otherwise: enabled only when TINA4_DEBUG=true.
+  def self.mcp_enabled?
+    explicit = ENV["TINA4_MCP"]
+    if explicit && !explicit.empty?
+      return %w[true 1 yes on].include?(explicit.to_s.strip.downcase)
+    end
+    %w[true 1 yes on].include?(ENV.fetch("TINA4_DEBUG", "").to_s.strip.downcase)
+  end
+
+  # Resolve the dedicated MCP port. Defaults to (server port + 2000) — keeps
+  # MCP tooling reachable on a stable, predictable channel separate from the
+  # main HTTP port and the AI test port (port + 1000).
+  def self.mcp_port
+    explicit = ENV["TINA4_MCP_PORT"]
+    return explicit.to_i if explicit && !explicit.empty? && explicit.to_i > 0
+
+    base_port = (ENV["TINA4_PORT"] || ENV["PORT"] || "7147").to_i
+    base_port + 2000
+  end
+
   # ── McpServer ─────────────────────────────────────────────────────
   class McpServer
     attr_reader :path, :name, :version

data/lib/tina4/messenger.rb

@@ -36,13 +36,14 @@ module Tina4
   #
   class Messenger
     attr_reader :host, :port, :username, :from_address, :from_name,
-                :imap_host, :imap_port, :use_tls, :encryption
+                :imap_host, :imap_port, :use_tls, :encryption,
+                :imap_encryption, :imap_use_tls
 
     # Initialize with SMTP config.
     # Priority: constructor params > ENV (TINA4_MAIL_*) > sensible defaults
     def initialize(host: nil, port: nil, username: nil, password: nil,
                    from_address: nil, from_name: nil, encryption: nil, use_tls: nil,
-                   imap_host: nil, imap_port: nil)
+                   imap_host: nil, imap_port: nil, imap_encryption: nil)
       @host         = host         || ENV["TINA4_MAIL_HOST"]     || "localhost"
       @port         = (port        || ENV["TINA4_MAIL_PORT"]     || 587).to_i
       @username     = username     || ENV["TINA4_MAIL_USERNAME"]
@@ -53,7 +54,7 @@ module Tina4
 
       @from_name    = from_name    || ENV["TINA4_MAIL_FROM_NAME"] || ""
 
-      # Encryption: constructor > .env > backward-compat use_tls > default "tls"
+      # SMTP encryption: constructor > .env > backward-compat use_tls > default "tls"
       env_encryption = encryption  || ENV["TINA4_MAIL_ENCRYPTION"]
       if env_encryption
         @encryption = env_encryption.downcase
@@ -66,6 +67,12 @@ module Tina4
 
       @imap_host    = imap_host    || ENV["TINA4_MAIL_IMAP_HOST"] || @host
       @imap_port    = (imap_port   || ENV["TINA4_MAIL_IMAP_PORT"] || 993).to_i
+
+      # IMAP encryption: dedicated env var TINA4_MAIL_IMAP_ENCRYPTION (tls/starttls/none).
+      # Defaults to "tls" — IMAPS over implicit TLS on port 993 is the safe industry norm.
+      env_imap_enc = imap_encryption || ENV["TINA4_MAIL_IMAP_ENCRYPTION"]
+      @imap_encryption = (env_imap_enc && !env_imap_enc.to_s.empty?) ? env_imap_enc.to_s.downcase : "tls"
+      @imap_use_tls    = %w[tls starttls ssl].include?(@imap_encryption)
     end
 
     # Send email using Ruby's Net::SMTP
@@ -387,7 +394,7 @@ module Tina4
     # ── IMAP helpers ─────────────────────────────────────────────────────
 
     def imap_connect(&block)
-      imap = Net::IMAP.new(@imap_host, port: @imap_port, ssl: @use_tls)
+      imap = Net::IMAP.new(@imap_host, port: @imap_port, ssl: @imap_use_tls)
       imap.login(@username, @password)
       result = block.call(imap)
       imap.logout

data/lib/tina4/response_cache.rb

@@ -3,6 +3,17 @@
 module Tina4
   # Multi-backend response cache for GET requests.
   #
+  # Public surface (parity with Python tina4_python.cache):
+  #   - Tina4::ResponseCache — middleware class
+  #   - Tina4.cache_stats     — module function returning cache stats
+  #   - Tina4.clear_cache     — module function flushing all cached entries
+  #   - Tina4.cache_get / cache_set / cache_delete — module-level KV API
+  #
+  # The internal lookup/store of GET responses is performed by the middleware
+  # hooks (before_cache, after_cache) and is NOT exposed publicly. Use the
+  # middleware by attaching ResponseCache to your route, not by calling
+  # the (private) internal_lookup / internal_store directly.
+  #
   # Backends are selected via the TINA4_CACHE_BACKEND env var:
   #   memory — in-process LRU cache (default, zero deps)
   #   redis  — Redis / Valkey (uses `redis` gem or raw RESP over TCP)
@@ -14,16 +25,6 @@ module Tina4
   #   TINA4_CACHE_TTL           — default TTL in seconds  (default: 0 = disabled)
   #   TINA4_CACHE_MAX_ENTRIES   — maximum cache entries   (default: 1000)
   #
-  # Usage:
-  #   cache = Tina4::ResponseCache.new(ttl: 60, max_entries: 1000)
-  #   cache.cache_response("GET", "/api/users", 200, "application/json", '{"users":[]}')
-  #   hit = cache.get("GET", "/api/users")
-  #
-  #   # Direct API (same across all 4 languages)
-  #   cache.cache_set("key", {"data" => "value"}, ttl: 120)
-  #   value = cache.cache_get("key")
-  #   cache.cache_delete("key")
-  #
   class ResponseCache
     CacheEntry = Struct.new(:body, :content_type, :status_code, :expires_at)
 
@@ -57,94 +58,75 @@ module Tina4
       @ttl > 0
     end
 
-    # Build a cache key from method and URL.
-    #
-    # @param method [String]
-    # @param url [String]
-    # @return [String]
-    def cache_key(method, url)
-      "#{method}:#{url}"
-    end
-
-    # Retrieve a cached response. Returns nil on miss or expired entry.
-    #
-    # @param method [String]
-    # @param url [String]
-    # @return [CacheEntry, nil]
-    def get(method, url)
-      return nil unless enabled?
-      return nil unless method == "GET"
+    # ── Middleware hooks ────────────────────────────────────────────
 
-      key = cache_key(method, url)
-      entry = backend_get(key)
+    # Middleware hook — checks for a cached entry before the route handler runs.
+    # If a cached entry exists for this GET request, short-circuits by replacing
+    # the response. Otherwise tags the request so after_cache can capture the
+    # response.
+    def before_cache(request, response)
+      return [request, response] unless enabled?
 
-      if entry.nil?
-        @mutex.synchronize { @misses += 1 }
-        return nil
-      end
+      method = (request.respond_to?(:method) ? request.method : "GET").to_s.upcase
+      return [request, response] unless method == "GET"
 
-      # 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)
-          @mutex.synchronize { @misses += 1 }
-          return nil
+      url = request.respond_to?(:url) ? request.url : (request.respond_to?(:path) ? request.path : "/")
+      hit = internal_lookup(method, url)
+      if hit
+        if response.respond_to?(:call)
+          new_response = response.call(hit.body, hit.status_code, hit.content_type)
+          return [request, new_response]
         end
-        @mutex.synchronize { @hits += 1 }
-        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(
-          entry["body"] || entry[:body],
-          entry["content_type"] || entry[:content_type],
-          entry["status_code"] || entry[:status_code],
-          expires_at
-        )
       end
-    end
-
-    # Store a response in the cache.
-    #
-    # @param method [String]
-    # @param url [String]
-    # @param status_code [Integer]
-    # @param content_type [String]
-    # @param body [String]
-    # @param ttl [Integer, nil] override default TTL
-    def cache_response(method, url, status_code, content_type, body, ttl: nil)
-      return unless enabled?
-      return unless method == "GET"
-      return unless @status_codes.include?(status_code)
-
-      effective_ttl = ttl || @ttl
-      key = cache_key(method, url)
-      expires_at = Time.now.to_f + effective_ttl
-
-      entry_data = {
-        "body" => body,
-        "content_type" => content_type,
-        "status_code" => status_code,
-        "expires_at" => expires_at
-      }
 
-      case @backend_name
-      when "memory"
-        @mutex.synchronize do
-          if @store.size >= @max_entries && !@store.key?(key)
-            oldest_key = @store.keys.first
-            @store.delete(oldest_key)
-          end
-          @store[key] = CacheEntry.new(body, content_type, status_code, expires_at)
-        end
+      # Tag for after_cache
+      if request.respond_to?(:[]=)
+        request[:_cache_method] = method
+        request[:_cache_url] = url
       else
-        backend_set(key, entry_data, effective_ttl)
+        request.instance_variable_set(:@_cache_method, method)
+        request.instance_variable_set(:@_cache_url, url)
       end
+      [request, response]
+    end
+
+    # Middleware hook — captures the response body and stores it after the
+    # route handler runs.
+    def after_cache(request, response)
+      return [request, response] unless enabled?
+
+      method = if request.respond_to?(:[])
+                 request[:_cache_method]
+               else
+                 request.instance_variable_get(:@_cache_method)
+               end
+      url = if request.respond_to?(:[])
+              request[:_cache_url]
+            else
+              request.instance_variable_get(:@_cache_url)
+            end
+      return [request, response] if method.nil? || url.nil?
+
+      status = if response.respond_to?(:status_code)
+                 response.status_code
+               elsif response.respond_to?(:status)
+                 response.status
+               else
+                 200
+               end
+      content_type = if response.respond_to?(:content_type)
+                       response.content_type
+                     else
+                       "application/json"
+                     end
+      body = if response.respond_to?(:body)
+               response.body.to_s
+             else
+               response.to_s
+             end
+
+      internal_store(method, url, status.to_i, content_type.to_s, body)
+      [request, response]
     end
 
     # ── Direct Cache API (same across all 4 languages) ──────────
@@ -297,8 +279,95 @@ module Tina4
       @backend_name
     end
 
+    # @internal Test seam — exercises the same path the middleware uses.
+    # Public for parity tests only; do not use in application code.
+    def _internal_lookup(method, url)
+      internal_lookup(method, url)
+    end
+
+    # @internal Test seam — exercises the same path the middleware uses.
+    # Public for parity tests only; do not use in application code.
+    def _internal_store(method, url, status_code, content_type, body, ttl: nil)
+      internal_store(method, url, status_code, content_type, body, ttl: ttl)
+    end
+
     private
 
+    # Build a cache key from method and URL.
+    def cache_key(method, url)
+      "#{method}:#{url}"
+    end
+
+    # Internal: retrieve a cached response. Used by middleware hooks only.
+    def internal_lookup(method, url)
+      return nil unless enabled?
+      return nil unless method == "GET"
+
+      key = cache_key(method, url)
+      entry = backend_get(key)
+
+      if entry.nil?
+        @mutex.synchronize { @misses += 1 }
+        return nil
+      end
+
+      # 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)
+          @mutex.synchronize { @misses += 1 }
+          return nil
+        end
+        @mutex.synchronize { @hits += 1 }
+        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(
+          entry["body"] || entry[:body],
+          entry["content_type"] || entry[:content_type],
+          entry["status_code"] || entry[:status_code],
+          expires_at
+        )
+      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)
+      return unless enabled?
+      return unless method == "GET"
+      return unless @status_codes.include?(status_code)
+
+      effective_ttl = ttl || @ttl
+      key = cache_key(method, url)
+      expires_at = Time.now.to_f + effective_ttl
+
+      entry_data = {
+        "body" => body,
+        "content_type" => content_type,
+        "status_code" => status_code,
+        "expires_at" => expires_at
+      }
+
+      case @backend_name
+      when "memory"
+        @mutex.synchronize do
+          if @store.size >= @max_entries && !@store.key?(key)
+            oldest_key = @store.keys.first
+            @store.delete(oldest_key)
+          end
+          @store[key] = CacheEntry.new(body, content_type, status_code, expires_at)
+        end
+      else
+        backend_set(key, entry_data, effective_ttl)
+      end
+    end
+
     # ── Backend initialization ─────────────────────────────────
 
     def init_backend
@@ -519,15 +588,17 @@ module Tina4
     end
   end
 
-  # ── Module-level convenience (singleton) ───────────────────────
+  # ── Module-level convenience (singleton, parity with Python) ───
 
   @default_cache = nil
 
   class << self
+    # Lazy module-level singleton for cache_stats / clear_cache.
     def cache_instance
       @default_cache ||= ResponseCache.new(ttl: ENV["TINA4_CACHE_TTL"] ? ENV["TINA4_CACHE_TTL"].to_i : 60)
     end
 
+    # Module-level KV API (parity with Python tina4_python.cache).
     def cache_get(key)
       cache_instance.cache_get(key)
     end
@@ -540,12 +611,19 @@ module Tina4
       cache_instance.cache_delete(key)
     end
 
-    def cache_clear
+    # Module-level cache stats (parity with Python tina4_python.cache.cache_stats()).
+    def cache_stats
+      cache_instance.cache_stats
+    end
+
+    # Module-level cache clear (parity with Python tina4_python.cache.clear_cache()).
+    def clear_cache
       cache_instance.clear_cache
     end
 
-    def cache_stats
-      cache_instance.cache_stats
+    # Backward-compat alias for cache_clear (deprecated — use clear_cache).
+    def cache_clear
+      cache_instance.clear_cache
     end
   end
 end

data/lib/tina4/router.rb

@@ -328,6 +328,14 @@ module Tina4
         nil
       end
 
+      # When TINA4_TRAILING_SLASH_REDIRECT is truthy, the rack app uses this
+      # to detect whether the *original* (un-stripped) path differed from the
+      # canonical form so it can issue a 301 redirect. Default false — silent
+      # match keeps backward compatibility.
+      def trailing_slash_redirect?
+        %w[true 1 yes on].include?(ENV.fetch("TINA4_TRAILING_SLASH_REDIRECT", "").to_s.strip.downcase)
+      end
+
       # Find a route matching method + path. Returns [route, params] or nil.
       # match(method, path) — consistent with Python, PHP, and Node.
       def match(method, path)

data/lib/tina4/session.rb

@@ -16,6 +16,11 @@ module Tina4
 
     def initialize(env, options = {})
       @options = DEFAULT_OPTIONS.merge(options)
+      # TINA4_SESSION_NAME — overrides cookie_name unless caller explicitly passed one.
+      env_name = ENV["TINA4_SESSION_NAME"]
+      if !options.key?(:cookie_name) && env_name && !env_name.empty?
+        @options[:cookie_name] = env_name
+      end
       @options[:secret] ||= ENV["TINA4_SECRET"] || "tina4-default-secret"
       @handler = create_handler
       @id = extract_session_id(env) || SecureRandom.hex(32)
@@ -151,7 +156,17 @@ module Tina4
     def cookie_header(cookie_name = nil)
       name = cookie_name || @options[:cookie_name]
       samesite = ENV["TINA4_SESSION_SAMESITE"] || "Lax"
-      "#{name}=#{@id}; Path=/; HttpOnly; SameSite=#{samesite}; Max-Age=#{@options[:max_age]}"
+      # HttpOnly defaults to true (existing behaviour); flip off only when explicitly false.
+      httponly = !%w[false 0 no off].include?((ENV["TINA4_SESSION_HTTPONLY"] || "true").to_s.strip.downcase)
+      # Secure defaults to false; flip on with truthy env var.
+      secure = %w[true 1 yes on].include?((ENV["TINA4_SESSION_SECURE"] || "false").to_s.strip.downcase)
+
+      parts = ["#{name}=#{@id}", "Path=/"]
+      parts << "HttpOnly" if httponly
+      parts << "Secure" if secure
+      parts << "SameSite=#{samesite}"
+      parts << "Max-Age=#{@options[:max_age]}"
+      parts.join("; ")
     end
 
     private

data/lib/tina4/swagger.rb

@@ -13,16 +13,44 @@ module Tina4
         spec
       end
 
+      # TINA4_SWAGGER_ENABLED — defaults to TINA4_DEBUG. When false, callers
+      # can choose to skip mounting /swagger entirely in production.
+      def enabled?
+        explicit = ENV["TINA4_SWAGGER_ENABLED"]
+        if explicit && !explicit.empty?
+          return %w[true 1 yes on].include?(explicit.to_s.strip.downcase)
+        end
+        %w[true 1 yes on].include?(ENV.fetch("TINA4_DEBUG", "").to_s.strip.downcase)
+      end
+
       private
 
       def base_spec
+        info = {
+          "title" => ENV["TINA4_SWAGGER_TITLE"] || ENV["PROJECT_NAME"] || "Tina4 API",
+          "version" => ENV["TINA4_SWAGGER_VERSION"] || Tina4::VERSION,
+          "description" => ENV["TINA4_SWAGGER_DESCRIPTION"] || "Auto-generated API documentation"
+        }
+
+        # Optional contact block — only emitted when at least one field is set.
+        contact_email = ENV["TINA4_SWAGGER_CONTACT_EMAIL"]
+        contact_team  = ENV["TINA4_SWAGGER_CONTACT_TEAM"] || ENV["SWAGGER_CONTACT_TEAM"]
+        contact_url   = ENV["TINA4_SWAGGER_CONTACT_URL"]  || ENV["SWAGGER_CONTACT_URL"]
+        contact = {}
+        contact["email"] = contact_email if contact_email && !contact_email.empty?
+        contact["name"]  = contact_team  if contact_team  && !contact_team.empty?
+        contact["url"]   = contact_url   if contact_url   && !contact_url.empty?
+        info["contact"] = contact unless contact.empty?
+
+        # Optional license block — TINA4_SWAGGER_LICENSE is the SPDX name (e.g. "MIT").
+        license_name = ENV["TINA4_SWAGGER_LICENSE"]
+        if license_name && !license_name.empty?
+          info["license"] = { "name" => license_name }
+        end
+
         {
           "openapi" => "3.0.3",
-          "info" => {
-            "title" => ENV["TINA4_SWAGGER_TITLE"] || ENV["PROJECT_NAME"] || "Tina4 API",
-            "version" => ENV["TINA4_SWAGGER_VERSION"] || Tina4::VERSION,
-            "description" => ENV["TINA4_SWAGGER_DESCRIPTION"] || "Auto-generated API documentation"
-          },
+          "info" => info,
           "servers" => [
             { "url" => "/" }
           ],

data/lib/tina4/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Tina4
-  VERSION = "3.12.2"
+  VERSION = "3.12.4"
 end

data/lib/tina4/webserver.rb

@@ -2,10 +2,16 @@
 
 module Tina4
   class WebServer
-    def initialize(app, host: "0.0.0.0", port: 7147)
+    DEFAULT_HOST = "0.0.0.0"
+    DEFAULT_PORT = 7147
+
+    # TINA4_HOST overrides the bind address when caller doesn't pass `host:`.
+    def initialize(app, host: nil, port: nil)
       @app = app
-      @host = host
-      @port = port
+      env_host = ENV["TINA4_HOST"]
+      @host = host || (env_host && !env_host.empty? ? env_host : DEFAULT_HOST)
+      env_port = ENV["TINA4_PORT"] || ENV["PORT"]
+      @port = port || (env_port && !env_port.empty? ? env_port.to_i : DEFAULT_PORT)
     end
 
     # Kill whatever process is listening on *port*.

data/lib/tina4/websocket.rb

@@ -105,12 +105,16 @@ module Tina4
 
     # ── Rooms ──────────────────────────────────────────────────
 
-    def join_room_for(conn_id, room_name)
+    # Internal: add connection ID to a room (called by WebSocketConnection#join_room).
+    # Mirrors Python's WebSocketManager._join_room — not part of the public API.
+    def _join_room(conn_id, room_name)
       @rooms[room_name] ||= Set.new
       @rooms[room_name].add(conn_id)
     end
 
-    def leave_room_for(conn_id, room_name)
+    # Internal: remove connection ID from a room (called by WebSocketConnection#leave_room).
+    # Mirrors Python's WebSocketManager._leave_room — not part of the public API.
+    def _leave_room(conn_id, room_name)
       @rooms[room_name]&.delete(conn_id)
     end
 
@@ -251,12 +255,12 @@ module Tina4
 
     def join_room(room_name)
       @rooms.add(room_name)
-      @ws_server&.join_room_for(@id, room_name)
+      @ws_server&._join_room(@id, room_name)
     end
 
     def leave_room(room_name)
       @rooms.delete(room_name)
-      @ws_server&.leave_room_for(@id, room_name)
+      @ws_server&._leave_room(@id, room_name)
     end
 
     def broadcast_to_room(room_name, message, exclude_self: false)

data/lib/tina4.rb

@@ -119,6 +119,9 @@ module Tina4
     attr_accessor :root_dir, :database
 
     def print_banner(host: "0.0.0.0", port: 7147, server_name: nil)
+      # TINA4_SUPPRESS — short-circuit ALL banner output for headless / CI runs.
+      return if Tina4::Env.is_truthy(ENV["TINA4_SUPPRESS"])
+
       is_tty = $stdout.respond_to?(:isatty) && $stdout.isatty
       color = is_tty ? "\e[31m" : ""
       reset = is_tty ? "\e[0m" : ""

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tina4ruby
 version: !ruby/object:Gem::Version
-  version: 3.12.2
+  version: 3.12.4
 platform: ruby
 authors:
 - Tina4 Team
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-05 00:00:00.000000000 Z
+date: 2026-05-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack