tina4ruby 3.13.38 → 3.13.40

data/lib/tina4/migration.rb

@@ -179,10 +179,12 @@ module Tina4
           rescue
             # Generator may already exist
           end
+          # migration_name is UNIQUE: a migration is "applied" iff a success row
+          # exists, so a re-applied name must never duplicate a tracking row.
           @db.execute(<<~SQL)
             CREATE TABLE #{TRACKING_TABLE} (
               id INTEGER NOT NULL PRIMARY KEY,
-              migration_name VARCHAR(500) NOT NULL,
+              migration_name VARCHAR(500) NOT NULL UNIQUE,
               description VARCHAR(500) DEFAULT '',
               batch INTEGER NOT NULL DEFAULT 1,
               executed_at VARCHAR(50) DEFAULT CURRENT_TIMESTAMP,
@@ -190,10 +192,12 @@ module Tina4
             )
           SQL
         else
+          # migration_name is UNIQUE: a migration is "applied" iff a success row
+          # exists, so a re-applied name must never duplicate a tracking row.
           @db.execute(<<~SQL)
             CREATE TABLE #{TRACKING_TABLE} (
               id INTEGER PRIMARY KEY,
-              migration_name VARCHAR(255) NOT NULL,
+              migration_name VARCHAR(255) NOT NULL UNIQUE,
               description VARCHAR(255) DEFAULT '',
               batch INTEGER NOT NULL DEFAULT 1,
               executed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
@@ -224,22 +228,37 @@ module Tina4
       return [] unless Dir.exist?(@migrations_dir)
 
       completed = completed_migrations
-      # Support both .rb and .sql migration files
-      # Accept both 000001_name.sql (sequential) and YYYYMMDDHHMMSS_name.sql (timestamp) patterns
-      Dir.glob(File.join(@migrations_dir, "*.{rb,sql}"))
-         .reject { |f| f.end_with?(".down.sql") }
-         .sort_by { |f| migration_sort_key(File.basename(f)) }
-         .reject { |f| completed.include?(File.basename(f)) }
+      # Support both .rb and .sql migration files. Accept both 000001_name.sql
+      # (sequential) and YYYYMMDDHHMMSS_name.sql (timestamp) patterns. Sort by a
+      # leading numeric/timestamp prefix (numeric-aware) so `9_*` applies before
+      # `10_*` — a plain lexical sort misorders unpadded prefixes ("10" < "9").
+      # Files with no numeric prefix sort after the numbered ones, lexically.
+      files = Dir.glob(File.join(@migrations_dir, "*.{rb,sql}"))
+                 .reject { |f| f.end_with?(".down.sql") }
+                 .sort_by { |f| migration_sort_key(File.basename(f)) }
+
+      # Warn about filenames without a recognized NNNNNN_/timestamp prefix —
+      # their ordering relative to numbered migrations is undefined, a silent
+      # out-of-order-apply footgun.
+      unprefixed = files.map { |f| File.basename(f) }.reject { |n| n =~ /\A\d+[_-]/ }
+      unless unprefixed.empty?
+        Tina4::Log.warning(
+          "Migration file(s) without a numeric/timestamp prefix may apply out of order: " +
+          unprefixed.join(", ")
+        )
+      end
+
+      files.reject { |f| completed.include?(File.basename(f)) }
     end
 
-    # Sort key that handles both 000001_name.sql and 20240315120000_name.sql patterns.
-    # Both are zero-padded numeric prefixes so alphabetical sorting works, but we
-    # extract the prefix explicitly to guarantee correct ordering when mixed.
+    # Numeric-aware sort key so `9_name.sql` sorts before `10_name.sql` (plain
+    # lexical sort puts "10" before "9"). Files with a leading numeric/timestamp
+    # prefix sort first by that number; the rest sort after, lexically.
     def migration_sort_key(filename)
       if filename =~ /\A(\d+)/
-        [$1.to_i, filename]
+        [0, $1.to_i, filename]
       else
-        [0, filename]
+        [1, 0, filename]
       end
     end
 
@@ -247,16 +266,27 @@ module Tina4
       name = File.basename(file)
       Tina4::Log.info("Running migration: #{name}")
       begin
+        # Wrap each migration FILE in its own transaction so a multi-statement
+        # file that fails midway rolls back as a unit. Truly atomic only on
+        # engines with transactional DDL (PostgreSQL); MySQL/Firebird/SQLite
+        # auto-commit DDL, so earlier statements may persist there — keep one
+        # logical change per file.
+        @db.start_transaction
         if file.end_with?(".rb")
           execute_ruby_migration(file, :up)
         else
           execute_sql_file(file)
         end
+        # ROW-EXISTENCE tracking: only a SUCCESS row is ever written. A
+        # migration is "applied" iff a success row exists — failures are never
+        # recorded, nothing is deleted, the file rolls back and we surface the
+        # error. Fix the bad file and re-run.
         _record_migration(name, batch, passed: 1)
+        @db.commit
         { name: name, status: "success" }
       rescue => e
+        @db.rollback rescue nil
         Tina4::Log.error("Migration failed: #{name} - #{e.message}")
-        _record_migration(name, batch, passed: 0)
         { name: name, status: "failed", error: e.message }
       end
     end
@@ -296,6 +326,26 @@ module Tina4
       migration.__send__(direction, @db)
     end
 
+    # Smart/curly quotes — editors, word processors, docs and chat apps silently
+    # convert a straight " to “ ” and a straight ' to ‘ ’ (plus primes ′ ″). Those
+    # characters are NOT valid SQL string/identifier delimiters, so a pasted-in
+    # migration fails to run ("syntax error near …"). Map them back to straight
+    # ASCII quotes. (Real string CONTENTS are unaffected by intent — we only swap
+    # the lookalike code points for their ASCII equivalents.)
+    SMART_QUOTES = {
+      "“" => '"', "”" => '"', "„" => '"', "‟" => '"', "″" => '"', # “ ” „ ‟ ″
+      "‘" => "'", "’" => "'", "‚" => "'", "‛" => "'", "′" => "'"  # ‘ ’ ‚ ‛ ′
+    }.freeze
+    SMART_QUOTE_RE = Regexp.union(SMART_QUOTES.keys)
+
+    # Replace smart/curly quotes with straight ASCII quotes so migration SQL
+    # authored or pasted from an editor/doc actually runs (those code points are
+    # not valid SQL delimiters). Already-straight quotes and ordinary content are
+    # returned byte-for-byte unchanged.
+    def normalize_quotes(sql)
+      sql.gsub(SMART_QUOTE_RE, SMART_QUOTES)
+    end
+
     # Split SQL into individual statements, handling:
     # - $$ delimited stored procedure blocks
     # - // delimited blocks
@@ -303,6 +353,10 @@ module Tina4
     # - Line comments -- ...
     # Matches the Python/Node.js approach: extract blocks first, split on ;, restore blocks.
     def split_sql_statements(sql, delimiter = ";")
+      # Normalize smart/curly quotes to straight ASCII first, so SQL pasted from
+      # an editor/doc (which converts " → “ ” and ' → ‘ ’) actually runs.
+      sql = normalize_quotes(sql)
+
       blocks = []
 
       # Extract $$ ... $$ blocks (stored procedures, triggers, etc.)
@@ -311,8 +365,12 @@ module Tina4
         "__BLOCK_#{blocks.length - 1}__"
       end
 
-      # Extract // ... // blocks
-      processed = processed.gsub(/\/\/(.*?)\/\//m) do
+      # Extract // ... // blocks (stored procedures, triggers, etc.). The `//`
+      # delimiters must NOT be preceded by a colon, so a URL scheme
+      # (`https://…`) or other `://` literal inside a migration is never
+      # captured as an opaque stored-proc block (it would otherwise swallow
+      # everything between two `//` occurrences and skip statement splitting).
+      processed = processed.gsub(/(?<!:)\/\/(.*?)(?<!:)\/\//m) do
         blocks << $~.to_s
         "__BLOCK_#{blocks.length - 1}__"
       end
@@ -348,10 +406,11 @@ module Tina4
       sql = File.read(file)
       statements = split_sql_statements(sql)
       statements.each do |stmt|
-        # Firebird lacks IF NOT EXISTS for ALTER TABLE ADD.
-        # Pre-check the system catalogue so duplicate columns are
-        # silently skipped instead of raising an error.
-        skip_reason = should_skip_for_firebird(stmt)
+        # Idempotency on engines lacking IF NOT EXISTS: Firebird ALTER-TABLE-ADD
+        # (pre-check the system catalogue for a duplicate column), and CREATE
+        # TABLE on Firebird/MSSQL (pre-check the table exists). Only a genuine
+        # already-exists is skipped — every other error still raises.
+        skip_reason = should_skip_for_firebird(stmt) || should_skip_create_table(stmt)
         if skip_reason
           Tina4::Log.info("Migration #{File.basename(file)}: #{skip_reason}")
           next
@@ -398,6 +457,34 @@ module Tina4
       end
     end
 
+    # CREATE TABLE <name> — name may be quoted ("x"), bracketed ([x] MSSQL), or bare.
+    CREATE_TABLE_RE = /\A\s*CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?(?:"([^"]+)"|\[([^\]]+)\]|(\w+))/i
+
+    # Make CREATE TABLE idempotent on engines lacking IF NOT EXISTS.
+    #
+    # Firebird and MSSQL do not support `CREATE TABLE IF NOT EXISTS`, so a raw
+    # CREATE in a re-run migration raises "object already exists". When the
+    # target table already exists on those engines, returns a skip reason so the
+    # statement is skipped (mirrors the Firebird ALTER-TABLE-ADD idempotency
+    # guard). SQLite/MySQL/PostgreSQL support IF NOT EXISTS and are left to the
+    # engine. Only a genuine already-exists is skipped — every other error still
+    # raises. Returns nil if the statement should execute normally.
+    def should_skip_create_table(stmt)
+      engine = @db.get_database_type rescue nil
+      return nil unless %w[firebird mssql].include?(engine)
+
+      m = stmt.match(CREATE_TABLE_RE)
+      return nil unless m
+
+      table = m[1] || m[2] || m[3]
+      begin
+        return "Table #{table} already exists, skipping CREATE TABLE" if @db.table_exists?(table)
+      rescue
+        return nil
+      end
+      nil
+    end
+
     def _record_migration(name, batch, passed: 1)
       # Extract description from filename (strip numeric prefix and extension)
       stem = File.basename(name, File.extname(name))

data/lib/tina4/orm.rb

@@ -13,6 +13,26 @@ module Tina4
     name.to_s.gsub(/([A-Z])/) { "_#{$1.downcase}" }.sub(/^_/, "")
   end
 
+  # Singularize a plural relationship name to derive a class name.
+  #
+  # has_many :posts → "Post", has_many :categories → "Category". The old
+  # derivation was a naive sub(/s$/) that turned "categories" into
+  # "Categorie" — a NameError waiting to happen. This handles the common
+  # English plural endings before falling back to stripping a trailing "s".
+  # (When class_name: is passed explicitly, this is never consulted.)
+  def self.singularize(word)
+    s = word.to_s
+    if s =~ /ies\z/i
+      s.sub(/ies\z/i, "y")
+    elsif s =~ /(ss|sh|ch|x|z)es\z/i
+      s.sub(/es\z/i, "")
+    elsif s =~ /s\z/i && s !~ /ss\z/i
+      s.sub(/s\z/i, "")
+    else
+      s
+    end
+  end
+
   class ORM
     include Tina4::FieldTypes
 
@@ -144,7 +164,12 @@ module Tina4
       def has_many(name, class_name: nil, foreign_key: nil)
         relationship_definitions[name] = {
           type: :has_many,
-          class_name: class_name || name.to_s.sub(/s$/, "").split("_").map(&:capitalize).join,
+          # Derive the target class from the (plural) relationship name via a
+          # proper singularizer — "posts" → "Post", "categories" → "Category"
+          # — instead of the naive sub(/s$/) that produced "Categorie". The FK
+          # auto-wire path (foreign_key_field) always passes class_name:
+          # explicitly, so this default only applies to a hand-written has_many.
+          class_name: class_name || Tina4.singularize(name).split("_").map(&:capitalize).join,
           foreign_key: foreign_key
         }
 
@@ -326,9 +351,17 @@ module Tina4
         result[:cnt].to_i
       end
 
+      # Create a new instance, save it, and return it.
+      #
+      # Returns the saved instance on success. v3.13.39: if the underlying #save
+      # fails (validation errors or a driver error), create returns false — it
+      # does NOT hand back a possibly-unsaved instance, so a failed insert can
+      # never masquerade as a success. The failure cause is logged and available
+      # on the (discarded) instance's #get_error via the same path save uses.
+      # Parity with the Python master.
       def create(attributes = {})
         instance = new(attributes)
-        instance.save
+        return false if instance.save == false
         instance
       end
 
@@ -473,6 +506,17 @@ module Tina4
         select_one(sql, [id])
       end
 
+      # Return true if a record with the given primary key exists.
+      #
+      # Cross-framework parity with Python's MyModel.exists(pk_value),
+      # PHP's Model::exists($id), and Node's Model.exists(pk). Honours the
+      # soft-delete filter the same way find_by_id does (it routes through it).
+      # Used by #save to decide INSERT vs UPDATE for natural (non-auto-increment)
+      # primary keys — see the note on #save.
+      def exists(id)
+        !find_by_id(id).nil?
+      end
+
       # Clear the relationship cache on all loaded instances (class-level helper).
       # Useful after bulk operations when you want to force relationship re-loads.
       def clear_rel_cache # -> nil
@@ -536,6 +580,11 @@ module Tina4
     def initialize(attributes = {})
       @persisted = false
       @errors = []
+      # Cause of the most recent failed #save (validation message or DB error).
+      # nil when the most recent save succeeded. Mirrors db.get_error so a caller
+      # that checks `return false unless model.save` can still recover the real
+      # cause via #get_error / #last_error — the failure never vanishes silently.
+      @last_error = nil
       @relationship_cache = {}
       # Accept a JSON object string (parity with Python/PHP/Node):
       #   Widget.new('{"id":1,"name":"alpha"}')
@@ -566,42 +615,137 @@ module Tina4
       end
     end
 
+    # Insert or update. Returns self on success (fluent), false on failure.
+    #
+    # Fails loud, never silent (the same principle db.execute already follows
+    # by raising). On *any* failure path save returns false — keeping the
+    # contract callers rely on (`return false unless model.save`) — but it also
+    # (a) logs the real cause via Tina4::Log.error with model/table context and
+    # (b) records the cause on a retrievable per-model error (#last_error /
+    # #get_error, mirroring db.get_error) plus #errors, so a caller can recover
+    # it after the fact. It never raises and never changes the self/false
+    # return shape. On success it returns self (was `true` pre-v3.13.39 — Ruby
+    # was the sole framework returning a bare boolean here) and clears the
+    # error.
+    #
+    # Two distinct failure paths, both loud:
+    #
+    #   * Validation (v3.13.39): #validate runs FIRST. If it returns errors,
+    #     save records them on @errors + @last_error, logs them, and returns
+    #     false WITHOUT touching the database — an invalid model never reaches
+    #     the driver. (Ruby already enforced validate-on-save; this adds the
+    #     loud log + recoverable last_error to the failure path.)
+    #   * Database (v3.13.39): a driver error (NOT NULL, duplicate PK, missing
+    #     table, …) is rolled back by db.transaction, then captured (db.get_error
+    #     falling back to the exception text) onto @last_error, logged with
+    #     model/table context, and returns false — the cause is no longer
+    #     swallowed silently.
+    #
+    # INSERT vs UPDATE (bug B, parity with the Python master): for a NATURAL
+    # (non-auto-increment) primary key that is set, the decision is made on
+    # whether the ROW EXISTS (via self.class.exists), not on @persisted alone.
+    # Pre-v3.13.39 a re-save of a manually-PK'd record that had @persisted set
+    # would UPDATE — but a freshly built (not-yet-persisted) natural-key record
+    # whose row already existed could double-INSERT, or a `new`-then-`save` of a
+    # natural key would INSERT then a second save UPDATE a phantom. Probing
+    # existence makes the choice correct regardless of @persisted. Auto-increment
+    # PKs keep the legacy @persisted-based decision (a nil PK means "new row,
+    # let the engine assign an id").
     def save
       @errors = []
       @relationship_cache = {} # Clear relationship cache on save
-      validate_fields
-      return false unless @errors.empty?
+
+      # ── validate() is ENFORCED. An invalid model never reaches the driver —
+      # fail loud (record + log), return false. ──
+      validation_errors = validate
+      unless validation_errors.empty?
+        @errors = validation_errors
+        @last_error = validation_errors.join("; ")
+        Tina4::Log.error(
+          "#{self.class.name}.save refused: validation failed — #{@last_error}"
+        )
+        return false
+      end
 
       data = to_db_hash(exclude_nil: true)
       pk = self.class.primary_key_field || :id
       pk_value = __send__(pk)
+      pk_opts = self.class.field_definitions[pk] || {}
+      auto_increment = pk_opts[:auto_increment]
 
-      self.class.db.transaction do |db|
-        if @persisted && pk_value
-          filter = { pk => pk_value }
-          data.delete(pk)
-          # Remove mapped primary key too
-          mapped_pk = self.class.field_mapping[pk.to_s]
-          data.delete(mapped_pk.to_sym) if mapped_pk
-          db.update(self.class.table_name, data, filter)
+      # Decide INSERT vs UPDATE.
+      is_update =
+        if pk_value.nil?
+          false
+        elsif auto_increment
+          # Auto-increment: legacy behaviour — a set PK on a persisted instance
+          # means UPDATE.
+          @persisted ? true : false
         else
-          result = db.insert(self.class.table_name, data)
-          if result[:last_id] && respond_to?("#{pk}=")
-            __send__("#{pk}=", result[:last_id])
+          # Natural key: probe row existence so a re-save never double-inserts
+          # and a first save of a never-seen key still inserts. If the probe
+          # itself fails (e.g. table missing), fall back to INSERT so the caller
+          # sees the real driver error rather than a silent no-op UPDATE.
+          begin
+            self.class.exists(pk_value)
+          rescue StandardError
+            false
           end
-          @persisted = true
         end
+
+      begin
+        self.class.db.transaction do |db|
+          if is_update
+            filter = { pk => pk_value }
+            data.delete(pk)
+            # Remove mapped primary key too
+            mapped_pk = self.class.field_mapping[pk.to_s]
+            data.delete(mapped_pk.to_sym) if mapped_pk
+            db.update(self.class.table_name, data, filter)
+          else
+            result = db.insert(self.class.table_name, data)
+            # Only adopt the engine-assigned id for an auto-increment PK. A
+            # natural-key PK was set by the caller; don't overwrite it with the
+            # driver's last_insert_id (which may be a sequence value that
+            # doesn't apply here).
+            if auto_increment && result[:last_id] && respond_to?("#{pk}=")
+              __send__("#{pk}=", result[:last_id])
+            end
+          end
+        end
+      rescue => e
+        # ── Fail loud, never silent. db.transaction already rolled back and
+        # re-raised. Keep the false return contract, but capture the REAL cause
+        # (prefer db.get_error, which insert/update/execute populate, falling
+        # back to the exception text) on @last_error + @errors so it survives,
+        # and log it with model/table context. ──
+        cause = (self.class.db.get_error rescue nil) || e.message
+        @last_error = cause
+        @errors = [cause]
+        Tina4::Log.error(
+          "#{self.class.name}.save failed for table " \
+          "'#{self.class.table_name}': #{cause}"
+        )
+        return false
       end
-      true
-    rescue => e
-      @errors << e.message
-      false
+
+      @persisted = true
+      @last_error = nil
+      self
     end
 
+    # Delete this record (soft or hard).
+    #
+    # v3.13.39 (bug D): RAISES on a missing primary key, matching #force_delete
+    # (which already raised). Previously delete returned false on a nil PK while
+    # force_delete raised — an inconsistent contract where "couldn't delete" and
+    # "deleted nothing" were indistinguishable on one path but loud on the other.
+    # Both now fail loud: deleting a record with no PK is a programmer error, not
+    # a quiet no-op. Returns true on a successful delete.
     def delete
       pk = self.class.primary_key_field || :id
       pk_value = __send__(pk)
-      return false unless pk_value
+      raise "Cannot delete: no primary key value" unless pk_value
 
       self.class.db.transaction do |db|
         if self.class.soft_delete
@@ -703,6 +847,23 @@ module Tina4
       @errors
     end
 
+    # Cause of the most recent failed #save (validation message or DB error),
+    # or nil when the last save succeeded.
+    def last_error
+      @last_error
+    end
+
+    # Return the cause of the most recent failed #save, or nil.
+    #
+    # Mirrors db.get_error. After save returns false — whether from validation
+    # or a driver error — the real cause is retrievable here (and on
+    # #last_error) so a caller using the `return false unless model.save`
+    # contract can still surface it. Cleared to nil on a successful save.
+    # Cross-framework parity with Python/PHP/Node get_error().
+    def get_error
+      @last_error
+    end
+
     # Convert to hash using Ruby attribute names.
     # Optionally include relationships via the include keyword.
     # case: "camel" converts snake_case keys to camelCase (parity with

data/lib/tina4/query_builder.rb

@@ -155,6 +155,14 @@ module Tina4
 
     # Execute the query and return the database result.
     #
+    # v3.13.39: with no `.limit()` set, get returns ALL matching rows. It
+    # previously applied a silent default `LIMIT 100` — a data-loss-on-read
+    # footgun where the 101st row vanished without a trace. An explicit
+    # `.limit(n)` is still honoured; `to_sql` never injects a default LIMIT
+    # either. When no limit was requested we pass `limit: nil` to db.fetch —
+    # its "no truncation" sentinel (fetch only appends LIMIT when `limit` is
+    # truthy and the SQL doesn't already carry one).
+    #
     # @return [Object] The result from db.fetch.
     def get
       ensure_db!
@@ -164,7 +172,7 @@ module Tina4
       @db.fetch(
         sql,
         all_params.empty? ? [] : all_params,
-        limit: @limit_val || 100,
+        limit: @limit_val,
         offset: @offset_val || 0
       )
     end
@@ -322,8 +330,19 @@ module Tina4
         return [{ field => { mongo_op => val } }, param_index + 1]
       end
 
-      # Fallback
-      [{ "$where" => cond }, param_index]
+      # v3.13.39: no silent $where fallback. Previously an unparseable
+      # condition was wrapped as `{ "$where" => <raw condition string> }` — a
+      # raw-JS sink that is both injection-shaped (the WHERE string runs as
+      # JavaScript on the server) and silently different semantics from the
+      # SQL the caller wrote. Fail loud instead: name the clause so the caller
+      # fixes it rather than shipping a surprise $where.
+      raise ArgumentError,
+            "QueryBuilder#to_mongo: cannot translate WHERE clause to a " \
+            "MongoDB filter: #{cond.inspect}. Supported forms: " \
+            "'<field> <op> ?' (=, !=, <>, >, >=, <, <=), '<field> LIKE ?', " \
+            "'<field> [NOT] IN (?)', '<field> IS [NOT] NULL'. " \
+            "Rewrite the condition in one of those forms (to_mongo will not " \
+            "silently emit a raw $where JavaScript expression)."
     end
 
     # Merge multiple single-field mongo condition hashes into one.

data/lib/tina4/queue_backends/kafka_backend.rb

@@ -8,9 +8,11 @@ module Tina4
         @brokers = options[:brokers] || "localhost:9092"
         @group_id = options[:group_id] || "tina4_consumer_group"
 
+        security = self.class._security_config
+
         producer_config = {
           "bootstrap.servers" => @brokers
-        }
+        }.merge(security)
         @producer = Rdkafka::Config.new(producer_config).producer
 
         consumer_config = {
@@ -18,13 +20,48 @@ module Tina4
           "group.id" => @group_id,
           "auto.offset.reset" => "earliest",
           "enable.auto.commit" => "false"
-        }
+        }.merge(security)
         @consumer = Rdkafka::Config.new(consumer_config).consumer
         @subscribed_topics = []
       rescue LoadError
         raise "Kafka backend requires the 'rdkafka' gem. Install with: gem install rdkafka"
       end
 
+      # Build SSL/SASL client config from env (for a TLS broker/proxy).
+      #
+      # Mirrors tina4_python KafkaConnector._security_config: each setting is
+      # read from the Tina4-namespaced env var first (TINA4_KAFKA_<NAME>) and
+      # falls back to the bare librdkafka-convention name (KAFKA_<NAME>) that
+      # many Kafka deployments already set. Honours security.protocol (e.g. SSL,
+      # SASL_SSL), ssl.ca.location, and optional SASL (mechanism / username /
+      # password). Unset keys are omitted, leaving librdkafka's PLAINTEXT default.
+      def self._security_config
+        # rdkafka key -> env suffix (read as TINA4_KAFKA_<suffix>, then KAFKA_<suffix>)
+        mapping = {
+          "security.protocol" => "SECURITY_PROTOCOL",
+          "ssl.ca.location" => "SSL_CA_LOCATION",
+          "sasl.mechanism" => "SASL_MECHANISM",
+          "sasl.username" => "SASL_USERNAME",
+          "sasl.password" => "SASL_PASSWORD"
+        }
+        config = {}
+        mapping.each do |rdk, suffix|
+          value = env_value("TINA4_KAFKA_#{suffix}") || env_value("KAFKA_#{suffix}")
+          config[rdk] = value if value
+        end
+        config
+      end
+
+      # Read an env var, treating empty/blank values as unset (parity with
+      # Python's `os.environ.get(...) or ...` truthiness).
+      def self.env_value(name)
+        value = ENV[name]
+        return nil if value.nil? || value.empty?
+
+        value
+      end
+      private_class_method :env_value
+
       def enqueue(message)
         @producer.produce(
           topic: message.topic,

data/lib/tina4/rack_app.rb

@@ -454,17 +454,26 @@ module Tina4
     end
 
     def serve_swagger_ui
+      # Honour the documented production on/off switch (TINA4_SWAGGER_ENABLED,
+      # else TINA4_DEBUG) — before v3.13.40 this was never checked and /swagger
+      # (the full API surface) was served unconditionally in production.
+      return [404, { "content-type" => "text/plain" }, ["Not Found"]] unless Tina4::Swagger.enabled?
+
+      # The UI assets load from a CDN by default (keeps the framework
+      # zero-dependency — no vendored ~1.4MB swagger-ui-dist). Air-gapped
+      # deployments point TINA4_SWAGGER_UI_CDN at a self-hosted mirror.
+      cdn = (ENV["TINA4_SWAGGER_UI_CDN"] || "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5").sub(%r{/+\z}, "")
       html = <<~HTML
         <!DOCTYPE html>
         <html lang="en">
         <head>
           <meta charset="UTF-8">
           <title>API Documentation</title>
-          <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css">
+          <link rel="stylesheet" href="#{cdn}/swagger-ui.css">
         </head>
         <body>
           <div id="swagger-ui"></div>
-          <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+          <script src="#{cdn}/swagger-ui-bundle.js"></script>
           <script>
             SwaggerUIBundle({ url: '/swagger/openapi.json', dom_id: '#swagger-ui' });
           </script>
@@ -475,8 +484,11 @@ module Tina4
     end
 
     def serve_openapi_json
-      @openapi_json ||= JSON.generate(Tina4::Swagger.generate)
-      [200, { "content-type" => "application/json; charset=utf-8" }, [@openapi_json]]
+      return [404, { "content-type" => "application/json; charset=utf-8" }, ['{"error":"Not Found"}']] unless Tina4::Swagger.enabled?
+
+      # Regenerate per request — DevReload adds routes in-process (same PID), so
+      # a memoized spec would go stale until restart. Swagger.generate is cheap.
+      [200, { "content-type" => "application/json; charset=utf-8" }, [JSON.generate(Tina4::Swagger.generate)]]
     end
 
     def handle_403(path = "")
@@ -920,7 +932,12 @@ module Tina4
         Tina4::Log.error("WebSocket error on #{ws_route.path}: #{error.message}")
       end
 
-      ws.handle_upgrade(env, socket, manager: manager)
+      # Per-route auth on the upgrade: a secured WS route (auth_required) needs a
+      # valid JWT or the handshake is rejected (401, not accepted) by
+      # handle_upgrade — after the origin allow-list, before the handshake. The
+      # dev-reload channel is always public.
+      auth_required = !dev_reload && ws_route.respond_to?(:auth_required) && ws_route.auth_required
+      ws.handle_upgrade(env, socket, manager: manager, auth_required: auth_required)
 
       # Return async response (-1 signals Rack the response is handled via hijack)
       [-1, {}, []]