tina4ruby 3.13.37 → 3.13.39

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
 
@@ -425,17 +458,20 @@ module Tina4
         translator_engine = %w[postgres postgresql].include?(engine) ? "postgresql" : engine
         sql = SQLTranslator.auto_increment_syntax(sql, translator_engine)
 
-        # Don't claim success when the DDL failed. db.execute() swallows the
-        # driver error into get_error() and returns false, so a bad type (or
-        # any DDL error) used to leave create_table returning true while no
-        # table was actually created.
-        ok = db.execute(sql)
-        db.commit
-        if ok == false
-          Tina4::Log.error("create_table failed for #{table_name}: #{db.get_error}", { sql: sql })
-          return false
+        # Don't claim success when the DDL failed. db.execute() now RAISES on a
+        # SQL error (it no longer swallows it into get_error() and returns
+        # false), so a bad type (or any DDL error) surfaces here as an
+        # exception. create_table keeps its documented bool contract: catch the
+        # raise, log the cause, and return false so callers that test the return
+        # still see a clean failure instead of a thrown error.
+        begin
+          db.execute(sql)
+          db.commit
+          true
+        rescue => e
+          Tina4::Log.error("create_table failed for #{table_name}: #{db.get_error || e.message}", { sql: sql })
+          false
         end
-        true
       end
 
       def scope(name, filter_sql, params = [])
@@ -470,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
@@ -533,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"}')
@@ -563,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)
-
-      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)
+      pk_opts = self.class.field_definitions[pk] || {}
+      auto_increment = pk_opts[:auto_increment]
+
+      # 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
@@ -700,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

@@ -351,9 +351,12 @@ module Tina4
       env["tina4.request"] = request  # Store for session save after response
       response = Tina4::Response.new
 
-      # Run global middleware (block-based + class-based before_* methods)
+      # Run global middleware (block-based + class-based before_* methods).
+      # M2 — AFTER-ON-4xx RULE: when a before_* short-circuits (4xx/skip) or
+      # throws (clean 500), the after-pass STILL runs so after_* can add
+      # headers/logging — consistent across all 4 frameworks.
       unless Tina4::Middleware.run_before(Tina4::Middleware.global_middleware, request, response)
-        # Middleware halted the request -- return whatever response was set
+        Tina4::Middleware.run_after(Tina4::Middleware.global_middleware, request, response)
         return response.to_rack
       end
 
@@ -885,18 +888,23 @@ module Tina4
       # Wire the route handler into the WebSocket engine events
       handler = ws_route.handler
 
-      # Create a dedicated WebSocket engine for this route so handlers stay isolated
+      # Create a dedicated WebSocket *event* engine for this route so each
+      # upgrade keeps its own isolated open/message/close handlers (the engine's
+      # on() appends handlers, so a single shared event engine would cross-wire
+      # routes).
       ws = Tina4::WebSocket.new
 
-      # The dev-reload channel is held by a process-wide shared manager so a
-      # broadcast from POST /__dev/api/reload reaches every browser, not just
-      # the connections of this one isolated per-socket engine. Mirrors
-      # Python's single _ws_manager keyed on the /__dev_reload path.
+      # The connection itself is OWNED by a process-wide shared manager so that
+      # broadcasts, rooms, the multi-instance backplane and the idle reaper span
+      # every route's connections — not just this one per-socket event engine.
+      # Mirrors Python's single WebSocketManager. The dev-reload channel uses its
+      # own shared manager (Tina4::DevReload) so POST /__dev/api/reload reaches
+      # every browser.
       dev_reload = ws_route.path == "/__dev_reload"
+      manager = dev_reload ? Tina4::DevReload.manager : @websocket_engine
 
       ws.on(:open) do |connection|
         connection.params = ws_params
-        Tina4::DevReload.add(connection) if dev_reload
         handler.call(connection, :open, nil)
       end
 
@@ -905,7 +913,6 @@ module Tina4
       end
 
       ws.on(:close) do |connection|
-        Tina4::DevReload.remove(connection) if dev_reload
         handler.call(connection, :close, nil)
       end
 
@@ -913,7 +920,12 @@ module Tina4
         Tina4::Log.error("WebSocket error on #{ws_route.path}: #{error.message}")
       end
 
-      ws.handle_upgrade(env, socket)
+      # 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, {}, []]

data/lib/tina4/response.rb

@@ -347,18 +347,38 @@ module Tina4
         gen = @_stream_generator
         blk = @_stream_block
         body = Enumerator.new do |yielder|
-          if gen
-            if gen.respond_to?(:each)
-              # Enumerator / array / any Enumerable of string chunks
-              gen.each { |chunk| yielder << chunk }
-            elsif gen.respond_to?(:call)
-              # Callable that receives the yielder, like the block form
-              gen.call(yielder)
-            else
-              yielder << gen.to_s
+          # SSE hardening: a streaming source that raises mid-stream (a
+          # generator/block error, or the client disconnecting and the server
+          # tearing the body down) must NEVER crash the worker. We catch the
+          # error, log it, and end the stream cleanly — the chunks emitted
+          # before the failure are still delivered.
+          #
+          # A client disconnect surfaces in a hijack/Puma streaming body as a
+          # write-side IOError/Errno on the socket; that is propagated up as a
+          # normal stop and re-raised so Rack/Puma can close the connection,
+          # while a *source* error is swallowed after logging.
+          begin
+            if gen
+              if gen.respond_to?(:each)
+                # Enumerator / array / any Enumerable of string chunks
+                gen.each { |chunk| yielder << chunk }
+              elsif gen.respond_to?(:call)
+                # Callable that receives the yielder, like the block form
+                gen.call(yielder)
+              else
+                yielder << gen.to_s
+              end
+            elsif blk
+              blk.call(yielder)
             end
-          elsif blk
-            blk.call(yielder)
+          rescue IOError, Errno::EPIPE, Errno::ECONNRESET => e
+            # Client disconnected mid-stream — stop cleanly, do not crash, and
+            # do not log loudly (a normal browser closing an SSE stream).
+            Tina4::Log.debug("SSE/stream client disconnected: #{e.class}: #{e.message}") if defined?(Tina4::Log)
+          rescue StandardError => e
+            # The source (generator/block) itself raised mid-stream. Log it and
+            # end the stream cleanly rather than crashing the handler/worker.
+            Tina4::Log.error("SSE/stream source error: #{e.class}: #{e.message}") if defined?(Tina4::Log)
           end
         end
         return [@status_code, final_headers, body]

data/lib/tina4/router.rb

@@ -214,15 +214,33 @@ module Tina4
   # A registered WebSocket route with path pattern matching (reuses Route's compile logic)
   class WebSocketRoute
     attr_reader :path, :handler, :path_regex, :param_names
+    # PUBLIC by default (mirrors GET). Flip to true with #secure (or via
+    # Tina4.secure_websocket) to require a valid JWT on the upgrade. Mirrors the
+    # HTTP Route's auth_required so the upgrade path enforces it identically.
+    attr_accessor :auth_required
 
-    def initialize(path, handler)
+    def initialize(path, handler, auth_required: false)
       @path = normalize_path(path).freeze
       @handler = handler
+      @auth_required = auth_required
       @param_names = []
       @path_regex = compile_pattern(@path)
       @param_names.freeze
     end
 
+    # Mark this WebSocket route as requiring bearer-token auth on the upgrade.
+    # Returns self for chaining: Tina4::Router.websocket("/chat") { ... }.secure
+    def secure
+      @auth_required = true
+      self
+    end
+
+    # Opt back out (the default). Returns self for chaining.
+    def no_auth
+      @auth_required = false
+      self
+    end
+
     # Returns params hash if matched, false otherwise
     def match?(request_path)
       match = @path_regex.match(request_path)
@@ -295,13 +313,25 @@ module Tina4
       #   connection — WebSocketConnection with #send, #broadcast, #close, #params
       #   event      — :open, :message, or :close
       #   data       — String payload for :message, nil for :open/:close
-      def websocket(path, &block)
-        ws_route = WebSocketRoute.new(path, block)
+      #
+      # PUBLIC by default (mirrors GET). Pass secure: true (the declarative way)
+      # OR chain .secure on the returned route (the imperative way) to require a
+      # valid JWT on the upgrade — both set the same auth_required flag, exactly
+      # like the HTTP routes support both a decorator/docblock and .secure.
+      def websocket(path, secure: false, &block)
+        ws_route = WebSocketRoute.new(path, block, auth_required: secure)
         ws_routes << ws_route
-        Tina4::Log.debug("WebSocket route registered: #{path}")
+        Tina4::Log.debug("WebSocket route registered: #{path}#{secure ? ' (secured)' : ''}")
         ws_route
       end
 
+      # Register a SECURED WebSocket route (auth required on the upgrade). The
+      # declarative sibling of Tina4::Router.websocket(...).secure — mirrors the
+      # secure_get/secure_post pair for HTTP routes.
+      def secure_websocket(path, &block)
+        websocket(path, secure: true, &block)
+      end
+
       # Find a matching WebSocket route for a given path.
       # Returns [ws_route, params] or nil.
       def find_ws_route(path)