tina4ruby 3.13.93 → 3.13.96

data/lib/tina4/env.rb

@@ -92,32 +92,38 @@ module Tina4
       "TINA4_LOG_LEVEL" => "[TINA4_LOG_ALL]"
     }.freeze
 
-    # Typed env-var coercion — parity with tina4_python's Env class,
-    # tina4-php's Tina4\Env, and tina4-nodejs's Env. Truthy values
-    # (case-insensitive after strip): "1", "true", "on", "yes", "y", "t".
-    # Falsy: "0", "false", "off", "no", "n", "f", empty string. Anything
-    # else falls through to default.
-    TRUTHY = %w[1 true on yes y t].freeze
-    FALSY  = %w[0 false off no n f].freeze
+    # The ONE env truthiness table. Every env boolean in every Tina4 framework
+    # answers from this set (case-insensitive after strip):
+    #
+    #   truthy: "true", "1", "yes", "on"     falsy: everything else
+    #
+    # BREAKING (parity): "y", "t", "n" and "f" were accepted here and NOWHERE
+    # ELSE — not by Ruby's own Log/Mcp checks, and not by Python, PHP or Node.
+    # So TINA4_LOG_FUNC=y switched function logging ON while TINA4_DEBUG=y left
+    # debug OFF, in the same process, from the same .env. Single letters are
+    # dropped rather than spread: systemd's boolean set is 1/yes/true/on with no
+    # letters, and YAML 1.2 removed y/n precisely because a bare letter reads as
+    # a value (the Norway problem). Use "true"/"false".
+    # There is deliberately NO falsy table. Falsy is "not in TRUTHY", so there
+    # is exactly one list to keep correct. A second table is a second thing
+    # that can drift, and it is what let `bool` and `is_truthy` disagree.
+    TRUTHY = %w[true 1 yes on].freeze
 
     # Check if a value is truthy for env boolean checks.
     #
     # Accepts: "true", "True", "TRUE", "1", "yes", "Yes", "YES", "on", "On", "ON".
     # Everything else is falsy (including empty string, nil, not set).
     def self.is_truthy(val)
-      %w[true 1 yes on].include?(val.to_s.strip.downcase)
+      TRUTHY.include?(val.to_s.strip.downcase)
     end
 
-    # Read an env var and coerce to Boolean. Returns +default+ when the
-    # var is unset or holds a value outside the TRUTHY/FALSY tables.
-    # Never raises — bad input falls through to default.
+    # Read an env var and coerce to Boolean. Returns +default+ only when the
+    # var is UNSET — a value that IS set is answered by the one truthiness
+    # table, never quietly replaced by the default. Never raises.
     def self.bool(name, default: false)
       raw = ENV[name.to_s]
       return default if raw.nil?
-      token = raw.strip.downcase
-      return true  if TRUTHY.include?(token)
-      return false if FALSY.include?(token) || token.empty?
-      default
+      is_truthy(raw)
     end
 
     # Read an env var and coerce to Integer. Logs a warning via Tina4::Log
@@ -174,8 +180,11 @@ module Tina4
         # gitignored .env.local (e.g. a stale auto-generated dev secret) must
         # not override an explicitly-set real TINA4_SECRET. The ensure-dev-secret
         # bootstrap runs AFTER this (only mints a secret if still unset in dev).
-        load_local_env(root_dir)
-        parse_env_file(env_file)
+        local = load_local_env(root_dir)
+        # .env.local WINS on a duplicate key, so it merges last. Both hashes
+        # already report the value in effect, so a real env var that beat both
+        # is what a caller reads back either way.
+        parse_env_file(env_file).merge(local)
       end
 
       # Load .env.local with first-wins semantics (override=false). A real
@@ -184,7 +193,8 @@ module Tina4
       # > .env). No-op when the file is absent (common for fresh checkouts).
       def load_local_env(root_dir = Dir.pwd)
         local_file = File.join(root_dir, ".env.local")
-        parse_env_file(local_file) if File.exist?(local_file)
+        return {} unless File.exist?(local_file)
+        parse_env_file(local_file)
       end
 
       # Get an env var value, with optional default
@@ -203,11 +213,28 @@ module Tina4
       end
 
       # Raise if any of the given keys are missing from ENV
-      def require_env!(*keys)
-        missing = keys.map(&:to_s).reject { |k| ENV.key?(k) }
+      # Validate that required env vars exist, and return them.
+      #
+      # RENAMED from require_env! on 2026-07-31. The bang was Ruby-idiomatic for
+      # "raises", but the concept is named require_env in the other three, and
+      # the surface-table rule is one name per concept with idiomatic CASING
+      # only. An alias would paper over the mismatch instead of fixing it, so
+      # the primary is renamed. Breaking for anyone calling require_env!.
+      #
+      # Returns a hash of every requested key to its value, matching Python,
+      # PHP and Node - it used to return nothing, so a caller could validate but
+      # not read in one step.
+      #
+      # Reports every missing name in one raise rather than the first: an
+      # operator fixing a deployment wants the whole list, not one name per
+      # restart.
+      def require_env(*keys)
+        names = keys.flatten.map(&:to_s)
+        missing = names.reject { |k| ENV.key?(k) }
         unless missing.empty?
-          raise KeyError, "Missing required env vars: #{missing.join(', ')}"
+          raise KeyError, "Missing required environment variables: #{missing.join(', ')}"
         end
+        names.to_h { |k| [k, ENV[k]] }
       end
 
       # Reset: clear all env vars that were loaded (restore to process defaults)
@@ -250,23 +277,138 @@ module Tina4
       # override=true: `ENV[key] = value` — unconditional set. NOT used by the
       # boot load sequence; kept only as an explicit opt-in for callers that
       # genuinely need to force values.
+      # Returns a hash of the keys this file declared, mapped to the value that
+      # WON - not the value the file declared. The two differ exactly when the
+      # real environment beat the file, which is the case an operator most needs
+      # to see: reporting the file's value there would return "from_local" while
+      # the process is actually running on the real env var. A map that
+      # disagrees with ENV is worse than no map, because it looks authoritative.
       def parse_env_file(path, override: false)
-        return unless File.exist?(path)
-        File.readlines(path).each do |line|
-          line = line.strip
-          next if line.empty? || line.start_with?("#")
-          if (match = line.match(/\A([A-Za-z_][A-Za-z0-9_]*)=["']?(.*)["']?\z/))
-            key = match[1]
-            value = match[2].gsub(/["']\z/, "")
-            if override
-              ENV[key] = value
-            else
-              ENV[key] ||= value
+        effective = {}
+        return effective unless File.exist?(path)
+        warned_refs = {}
+        File.readlines(path).each_with_index do |raw, index|
+          key, value = parse_env_line(raw, path, index + 1, warned_refs)
+          next if key.nil?
+          if override
+            ENV[key] = value
+          else
+            ENV[key] ||= value
+          end
+          @loaded_keys ||= []
+          @loaded_keys << key
+          effective[key] = ENV[key]
+        end
+        effective
+      end
+
+      # Parse ONE dotenv line into [key, value], or [nil, nil] for a line that
+      # sets nothing (blank, comment, or malformed).
+      #
+      # The rules are the cross-framework behaviour table (feature 1 of the
+      # feature audit): identical in Python, PHP, Ruby and Node, driven off one
+      # committed fixture. Ruby used to differ on two of them, silently.
+      def parse_env_line(raw, path, line_no, warned_refs)
+        line = raw.strip
+        return [nil, nil] if line.empty? || line.start_with?("#")
+
+        # Rule 2: a shell-style `export FOO=bar` is valid input, not an error.
+        # Ruby used to fall straight through this line, leaving the variable
+        # UNSET with no warning -- so a .env copied out of a shell profile lost
+        # keys, and the failure surfaced somewhere unrelated (a blank
+        # TINA4_SECRET, a missing database URL).
+        line = line.sub(/\Aexport\s+/, "")
+
+        # Rule 3: split on the FIRST `=` only. A line with no `=` is skipped
+        # with a warning naming the line -- never in silence.
+        eq = line.index("=")
+        if eq.nil?
+          warn_env("#{path}:#{line_no}: no '=' in \"#{line}\", line skipped")
+          return [nil, nil]
+        end
+
+        key = line[0...eq].strip
+        # Rule 4: reject a key that is not a valid identifier, by name and line.
+        unless key.match?(/\A[A-Za-z_][A-Za-z0-9_]*\z/)
+          warn_env("#{path}:#{line_no}: invalid key #{key.inspect}, line skipped")
+          return [nil, nil]
+        end
+
+        [key, parse_env_value(line[(eq + 1)..].to_s.strip, path, line_no, warned_refs)]
+      end
+
+      # Rule 5 + 6: quoting decides escapes AND interpolation, in that order.
+      def parse_env_value(value, path, line_no, warned_refs)
+        # A QUOTED value ends at its CLOSING QUOTE, and anything after it is a
+        # comment. Testing the LAST character instead was wrong: a trailing
+        # comment makes the last character non-quote, so `PW="s3cret" # note`
+        # fell through to the unquoted branch below, which strips only the ` #`
+        # and left the QUOTE CHARACTERS in the value -- a credential handed to a
+        # driver as "\"s3cret\"". PHP already scanned for the terminator; this is
+        # that mechanism, and the scan SKIPS a quote preceded by a backslash so
+        # an escaped \" cannot end the value early.
+        if !value.empty? && (value.start_with?("'") || value.start_with?('"'))
+          quote = value[0]
+          i = 1
+          while i < value.length
+            if value[i] == "\\" && quote == '"' && i + 1 < value.length
+              i += 2
+              next
             end
-            @loaded_keys ||= []
-            @loaded_keys << key
+            break if value[i] == quote
+            i += 1
+          end
+
+          if i < value.length
+            inner = value[1...i]
+            # Single quotes are verbatim: no escapes, no interpolation. Shell
+            # semantics, and the documented way to keep a literal ${...}.
+            return inner if quote == "'"
+
+            inner = inner.gsub("\\n", "\n")
+                         .gsub("\\r", "\r")
+                         .gsub("\\t", "\t")
+                         .gsub('\\"', '"')
+                         .gsub("\\\\", "\\")
+            return interpolate_env(inner, path, line_no, warned_refs)
           end
         end
+
+        # Rule 5: an unquoted value is truncated at the first SPACE-HASH, then
+        # trimmed. Ruby used to keep the whole line, so `FOO=value # note`
+        # became "value # note" -- a wrong value rather than an absent one,
+        # which is the harder kind to notice.
+        hash = value.index(" #")
+        value = value[0...hash] if hash
+        interpolate_env(value.rstrip, path, line_no, warned_refs)
+      end
+
+      # Rule 6: expand ${VAR} against already-loaded keys plus the real
+      # environment. An unresolved name is left LITERAL and warned about once
+      # per name, so a typo is visible without breaking the load.
+      def interpolate_env(value, path, line_no, warned_refs)
+        value.gsub(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/) do
+          name = Regexp.last_match(1)
+          if ENV.key?(name)
+            ENV[name]
+          else
+            unless warned_refs[name]
+              warned_refs[name] = true
+              warn_env("#{path}:#{line_no}: ${#{name}} is not set, left as-is")
+            end
+            "${#{name}}"
+          end
+        end
+      end
+
+      # One place to emit a parse warning. Routed through Tina4::Log when it is
+      # loaded (env.rb is required before the logger during boot), else $stderr.
+      def warn_env(message)
+        if defined?(Tina4::Log) && Tina4::Log.respond_to?(:warning)
+          Tina4::Log.warning(message)
+        else
+          $stderr.puts("[tina4] #{message}")
+        end
       end
     end
   end

data/lib/tina4/field_types.rb

@@ -15,6 +15,18 @@ module Tina4
         @primary_key_field
       end
 
+      # EVERY primary-key field name, in declaration order.
+      #
+      # A key may span several columns. +primary_key_field+ returns only ONE and
+      # is kept for the auto-increment paths, which are single-column by
+      # definition. Anything that ADDRESSES a row must use this: keying on one
+      # column of a composite key matches every row sharing that value, which is
+      # the data-loss shape feature 4 removed from the raw write path below.
+      def primary_key_fields
+        keys = field_definitions.select { |_n, o| o[:primary_key] }.keys
+        keys.empty? ? [:id] : keys
+      end
+
       def table_name(name = nil)
         if name
           @table_name = name

data/lib/tina4/frond.rb

@@ -163,6 +163,29 @@ module Tina4
       elif else elseif endautoescape endblock endcache endfor endif endlive
       endmacro endraw endset endspaceless
     ].freeze
+
+    # Author-written tags the sandbox allow-list governs. Mirrors Python's
+    # _GATEABLE_TAGS and PHP's GATEABLE_TAGS. A tag absent from this list is
+    # structural, not an author capability, and is never gated -- `block` and
+    # `extends` are template inheritance, and `raw` is consumed by the tokenizer.
+    # Both spellings of set ({% set x = 1 %} and {% set x %}...{% endset %})
+    # dispatch under "set", so one entry covers the pair.
+    GATEABLE_TAGS = %w[
+      autoescape cache for from if import include live macro set spaceless
+    ].freeze
+
+    # Gateable tags that OWN A BODY, mapped to the terminator closing it. A
+    # denied tag has to consume its body -- see skip_block.
+    BLOCK_TAG_ENDS = {
+      "autoescape" => "endautoescape",
+      "cache" => "endcache",
+      "for" => "endfor",
+      "if" => "endif",
+      "live" => "endlive",
+      "macro" => "endmacro",
+      "set" => "endset",
+      "spaceless" => "endspaceless"
+    }.freeze
     AUTOESCAPE_RE   = /\Aautoescape\s+(false|true)/
     STRIPTAGS_RE    = /<[^>]+>/
     THOUSANDS_RE    = /(\d)(?=(\d{3})+(?!\d))/
@@ -444,6 +467,28 @@ module Tina4
       self
     end
 
+    # May this filter RUN under the current sandbox?
+    #
+    # The escaping decision has to ask this rather than read the filter name out
+    # of the source: a denied `raw` that still marked its value safe made the
+    # allow-list entry governing XSS escaping inert.
+    def filter_permitted?(name)
+      return true unless @sandbox && @allowed_filters
+
+      @allowed_filters.include?(name.to_s)
+    end
+
+    # May this tag run under the current sandbox?
+    #
+    # One gate for every tag, so the allow-list governs the whole tag vocabulary
+    # instead of whichever names somebody remembered to check individually.
+    def tag_permitted?(tag)
+      return true unless @sandbox && @allowed_tags
+      return true unless GATEABLE_TAGS.include?(tag)
+
+      @allowed_tags.include?(tag)
+    end
+
     # Utility: HTML escape
     def self.escape_html(str)
       str.to_s.gsub(HTML_ESCAPE_RE, HTML_ESCAPE_MAP)
@@ -692,6 +737,43 @@ module Tina4
     # Token renderer
     # -----------------------------------------------------------------------
 
+    # Consume a denied tag WITHOUT running it, returning the index past its body.
+    #
+    # Ruby walks a token stream, so a denied tag cannot simply be dropped the way
+    # an AST node can. Advancing by one token would leave the body's tokens to
+    # render at the TOP level, leaking exactly the content the sandbox denied.
+    # Running the handler and discarding its output is no better: handle_set binds
+    # its variable before it returns. Consuming the block gives all three
+    # properties at once -- no output, no side effects, correct index.
+    def skip_block(tokens, i, tag, content)
+      terminator = BLOCK_TAG_ENDS[tag]
+      # {% set x = 1 %} is an assignment and owns no body; {% set x %}...{% endset %}
+      # captures one. Same exact-"=" test the dispatch uses.
+      terminator = nil if tag == "set" && content.include?("=")
+      return i + 1 if terminator.nil?
+
+      depth = 1
+      j = i + 1
+      while j < tokens.length
+        if tokens[j][0] == BLOCK
+          inner = strip_tag(tokens[j][1])[0]
+          case inner.split[0]
+          when tag
+            # A nested assignment-form set opens no body, so it must not nest.
+            depth += 1 unless tag == "set" && inner.include?("=")
+          when terminator
+            depth -= 1
+            return j + 1 if depth.zero?
+          end
+        end
+        j += 1
+      end
+
+      # Unterminated block: consume to the end. Nothing renders, which is the
+      # safe answer -- the alternative leaks the body of a denied tag.
+      tokens.length
+    end
+
     def render_tokens(tokens, context)
       output = []
       i = 0
@@ -725,6 +807,18 @@ module Tina4
 
           tag = content.split[0] || ""
 
+          # ONE sandbox gate for the whole tag vocabulary. Previously only
+          # `include` was checked, so every other tag ignored the allow-list --
+          # {% autoescape false %} could switch escaping off from inside a
+          # sandbox whose tags were restricted to something else entirely.
+          unless tag_permitted?(tag)
+            i = skip_block(tokens, i, tag, content)
+            if strip_a && i < tokens.length && tokens[i][0] == TEXT
+              tokens[i] = [TEXT, tokens[i][1].lstrip]
+            end
+            next
+          end
+
           case tag
           when "if"
             result, i = handle_if(tokens, i, context)
@@ -745,12 +839,8 @@ module Tina4
               i = handle_set_block(tokens, i, context)
             end
           when "include"
-            if @sandbox && @allowed_tags && !@allowed_tags.include?("include")
-              i += 1
-            else
-              output << handle_include(content, context)
-              i += 1
-            end
+            output << handle_include(content, context)
+            i += 1
           when "macro"
             i = handle_macro(tokens, i, context)
           when "import"
@@ -913,14 +1003,16 @@ module Tina4
       is_safe = false
       filters.each do |fname, args|
         if fname == "raw" || fname == "safe"
-          is_safe = true
+          # Decide from what was permitted to RUN, not from what the source
+          # asked for. Marking the value safe here regardless meant a DENIED
+          # raw produced byte-identical output to an allowed one -- the
+          # allow-list entry that governs XSS escaping did nothing at all.
+          is_safe = true if filter_permitted?(fname)
           next
         end
 
         # Sandbox: check filter access
-        if @sandbox && @allowed_filters && !@allowed_filters.include?(fname)
-          next
-        end
+        next if @sandbox && @allowed_filters && !@allowed_filters.include?(fname)
 
         # Filter + property-access chain: `first.groupSummary` — apply
         # the filter, then traverse the path on the result. Done BEFORE

data/lib/tina4/health.rb

@@ -6,29 +6,45 @@ module Tina4
   module Health
     START_TIME = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
+    # The path used when TINA4_HEALTH_PATH is unset. Identical in all four
+    # frameworks; the under-prefix keeps it clear of an application route that
+    # happens to be called /health.
+    DEFAULT_PATH = "/__health"
+
+    # Always registered as well, whatever the configured path, so a probe
+    # written before TINA4_HEALTH_PATH existed keeps working. Setting the env
+    # var adds a path, it never takes one away.
+    LEGACY_PATH = "/health"
+
     class << self
       # Return the configured health endpoint path.
-      # TINA4_HEALTH_PATH overrides the default "/__health" — kept consistent across all 4 frameworks.
+      # TINA4_HEALTH_PATH overrides the default, kept consistent across all 4 frameworks.
       def path
         configured = ENV["TINA4_HEALTH_PATH"]
-        return "/__health" if configured.nil? || configured.empty?
+        return DEFAULT_PATH if configured.nil? || configured.empty?
         configured.start_with?("/") ? configured : "/#{configured}"
       end
 
       def register!
-        # Idempotent by ASKING THE ROUTER, not by remembering. run! and the CLI
-        # both call this, and it can run more than once per process. A boolean
-        # flag looked equivalent and was not: Router.clear! (every spec, and
-        # any re-init) wipes the routes while the flag stays true, so /health
-        # silently vanishes for the rest of the run. Querying the router is
-        # self-healing -- cleared routes re-register, present ones don't
-        # duplicate.
-        return if Tina4::Router.find_route("/health", "GET")
-
-        # Register at the configured path. The legacy "/health" path stays
-        # registered for backward-compat.
+        # Unconditional, and idempotent for free: Router.add REPLACES a repeated
+        # (method, path) in place rather than appending, so calling this twice
+        # cannot duplicate and a Router.clear! is self-healing on the next call.
+        #
+        # There used to be a guard here -- `return if find_route("/health",
+        # "GET")` -- whose arguments were swapped: the signature is
+        # find_route(METHOD, PATH). It usually matched nothing and did nothing,
+        # but an ANY route matches any path, so an app with an ordinary
+        # catch-all made the guard fire and health was never registered at all.
+        # A probe then received the application's catch-all response instead of
+        # the health payload. Correcting the order would not have fixed it,
+        # because find_route("GET", path) matches that catch-all too; asking the
+        # router "does something answer here" can never distinguish "health is
+        # registered" from "something else happens to match".
+        #
+        # The legacy "/health" is always registered alongside the configured
+        # path so an existing probe keeps working when TINA4_HEALTH_PATH is set.
         Tina4::Router.add("GET", path, method(:handle))
-        Tina4::Router.add("GET", "/health", method(:handle)) unless path == "/health"
+        Tina4::Router.add("GET", LEGACY_PATH, method(:handle)) unless path == LEGACY_PATH
       end
 
 

data/lib/tina4/job.rb

@@ -86,14 +86,24 @@ module Tina4
     # queue.dead_letters returns it. No manual retry_failed is required.
     def fail(reason = "")
       @error = reason
-      if @queue && @queue.backend.respond_to?(:fail)
-        @queue.backend.fail(self, reason)
-        @status = @attempts >= @queue.max_retries ? :dead : :pending
-      else
-        # No backend reference — degrade to in-memory bookkeeping only.
+      # A job with no queue is a detached value object (built by hand, or read
+      # out of a serialised payload) — in-memory bookkeeping is all there is.
+      unless @queue
         @attempts += 1
         @status = :failed
+        return self
       end
+
+      # NO respond_to?(:fail) GUARD. It used to fall through to the same
+      # in-memory branch when the backend had no fail method, which is exactly
+      # what rabbitmq and kafka were: job.fail() bumped a counter in this
+      # process and the BROKER WAS NEVER TOLD. No dead letter was written, the
+      # delivery stayed unacked, and failed()/dead_letters() both reported
+      # nothing — the job was lost as far as the application could see. A
+      # backend that cannot record a failure must say so (invariant 6), and a
+      # backend missing the method must fail loudly here rather than pretend.
+      @queue.backend.fail(self, reason)
+      @status = @attempts >= @queue.max_retries ? :dead : :pending
       self
     end