tina4ruby 3.13.38 → 3.13.39

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

@@ -920,7 +920,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, {}, []]

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)

data/lib/tina4/version.rb

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

data/lib/tina4/websocket.rb

@@ -42,6 +42,79 @@ module Tina4
     allowed.include?(origin)
   end
 
+  # Extract a bearer token from a WebSocket upgrade handshake.
+  #
+  # Order (mirrors Python's tina4_python.websocket.ws_token):
+  #   1. the Authorization: Bearer <jwt> header (server/CLI/mobile clients)
+  #   2. the Sec-WebSocket-Protocol subprotocol in the form "bearer, <jwt>"
+  #      (the only way a *browser* can pass a token — new WebSocket() cannot set
+  #      headers, but it CAN offer subprotocols)
+  #   3. a ?token=<jwt> query-string param
+  # Returns the token String, or nil.
+  #
+  # +headers+ is a Hash. Lookups are case-insensitive across both the Rack-style
+  # "HTTP_AUTHORIZATION"/"HTTP_SEC_WEBSOCKET_PROTOCOL" keys and plain
+  # "authorization"/"Authorization"/"sec-websocket-protocol" keys so the same
+  # helper serves the rack_app upgrade path and direct callers/tests.
+  def self.ws_token(headers, query_string = "", subprotocol = "")
+    headers ||= {}
+    auth = headers["HTTP_AUTHORIZATION"] || headers["authorization"] || headers["Authorization"] || ""
+    if auth[0, 7].to_s.downcase == "bearer "
+      tok = auth[7..].to_s.strip
+      return tok.empty? ? nil : tok
+    end
+
+    proto = subprotocol.to_s
+    proto = headers["HTTP_SEC_WEBSOCKET_PROTOCOL"] || headers["sec-websocket-protocol"] ||
+            headers["Sec-WebSocket-Protocol"] || "" if proto.empty?
+    parts = proto.to_s.split(",").map(&:strip).reject(&:empty?)
+    if parts.length >= 2 && parts[0].downcase == "bearer"
+      return parts[1].empty? ? nil : parts[1]
+    end
+
+    qs = query_string.to_s
+    qs = headers["QUERY_STRING"].to_s if qs.empty?
+    unless qs.empty?
+      tok = qs.split("&").each_with_object(nil) do |pair, _acc|
+        k, v = pair.split("=", 2)
+        break v if k == "token"
+      end
+      return tok unless tok.nil? || tok.to_s.empty?
+    end
+
+    nil
+  end
+
+  # Per-route WebSocket authentication, checked on the upgrade.
+  #
+  # A route is secured when it requires auth (the WebSocketRoute's #auth_required
+  # is truthy — set by .secure on the route or by Tina4.secure_websocket). Public
+  # routes (the default) always pass. A secured route needs a valid JWT via the
+  # Authorization header, the "bearer" subprotocol, or ?token=.
+  #
+  # Returns [payload, ok] — the verified token payload (or nil) and whether the
+  # upgrade may proceed. Mirrors Python's ws_authorized.
+  def self.ws_authorized(auth_required, headers, query_string = "", subprotocol = "")
+    return [nil, true] unless auth_required
+
+    token = ws_token(headers, query_string, subprotocol)
+    return [nil, false] unless token
+
+    payload = Tina4::Auth.valid_token(token)
+    [payload, !payload.nil?]
+  end
+
+  # Whether the client offered the "bearer" subprotocol — in which case the
+  # handshake response must echo "bearer" as the accepted subprotocol (browsers
+  # reject a 101 that doesn't echo back a subprotocol they offered).
+  def self.ws_bearer_subprotocol_offered?(headers)
+    headers ||= {}
+    proto = headers["HTTP_SEC_WEBSOCKET_PROTOCOL"] || headers["sec-websocket-protocol"] ||
+            headers["Sec-WebSocket-Protocol"] || ""
+    parts = proto.to_s.split(",").map(&:strip).reject(&:empty?)
+    !parts.empty? && parts[0].downcase == "bearer"
+  end
+
   # Build a WebSocket frame (server→client, never masked).
   def self.build_frame(opcode, data, fin: true)
     first_byte = (fin ? 0x80 : 0x00) | opcode
@@ -451,7 +524,9 @@ module Tina4
     #     conn.on_close   { puts "bye" }
     #   end
     #
-    def self.route(path, &block)
+    # PUBLIC by default (mirrors GET). Pass secure: true to require a valid JWT
+    # on the upgrade (or chain .secure on the returned route).
+    def self.route(path, secure: false, &block)
       @route_handlers ||= {}
       @route_handlers[path] = block
 
@@ -467,7 +542,7 @@ module Tina4
         end
       end
 
-      Tina4::Router.websocket(path, &adapter)
+      Tina4::Router.websocket(path, secure: secure, &adapter)
     end
 
     # Upgrade a raw socket to a WebSocket connection and run its frame loop.
@@ -477,7 +552,7 @@ module Tina4
     # (Rack) mode the rack_app passes a process-wide shared engine here so that
     # broadcasts, rooms and the backplane span every route's connections even
     # though each upgrade keeps its own isolated event handlers on +self+.
-    def handle_upgrade(env, socket, manager: self)
+    def handle_upgrade(env, socket, manager: self, auth_required: false)
       key = env["HTTP_SEC_WEBSOCKET_KEY"]
       return unless key
 
@@ -490,11 +565,30 @@ module Tina4
         return
       end
 
+      # Per-route auth — checked AFTER the origin allow-list and BEFORE we accept
+      # the handshake. A PUBLIC route (the default, mirrors GET) always passes; a
+      # secured route (auth_required) needs a valid JWT via the Authorization
+      # header, the "bearer" subprotocol, or ?token=. Missing/invalid → reject
+      # the upgrade with a 401 (close code 1008 equivalent) and never accept.
+      payload, ok = Tina4.ws_authorized(auth_required, env, env["QUERY_STRING"].to_s)
+      unless ok
+        socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n") rescue nil
+        socket.close rescue nil
+        return
+      end
+
       accept = Tina4.compute_accept_key(key)
 
+      # When the client offered the "bearer" subprotocol (the browser transport,
+      # since new WebSocket() can't set headers), echo "bearer" back as the
+      # accepted subprotocol — browsers reject a 101 that doesn't echo a
+      # subprotocol they offered. Mirrors Python's accept-subprotocol behaviour.
+      subproto_header = Tina4.ws_bearer_subprotocol_offered?(env) ? "Sec-WebSocket-Protocol: bearer\r\n" : ""
+
       response = "HTTP/1.1 101 Switching Protocols\r\n" \
                  "Upgrade: websocket\r\n" \
                  "Connection: Upgrade\r\n" \
+                 "#{subproto_header}" \
                  "Sec-WebSocket-Accept: #{accept}\r\n\r\n"
 
       socket.write(response)
@@ -502,6 +596,9 @@ module Tina4
       conn_id = SecureRandom.hex(16)
       ws_path = env["REQUEST_PATH"] || env["PATH_INFO"] || "/"
       connection = WebSocketConnection.new(conn_id, socket, ws_server: manager, path: ws_path)
+      # Expose the verified token payload on the connection (nil on public
+      # routes). Mirrors Python's connection.auth = payload.
+      connection.auth = payload
       manager.register_connection(connection)
 
       # Start the idle reaper lazily once we actually have a connection (opt-in
@@ -548,7 +645,8 @@ module Tina4
 
   class WebSocketConnection
     attr_reader :id, :rooms, :last_activity
-    attr_accessor :params, :path, :on_message_handler, :on_close_handler, :on_error_handler
+    attr_accessor :params, :path, :on_message_handler, :on_close_handler, :on_error_handler,
+                  :auth
 
     def initialize(id, socket, ws_server: nil, path: "/")
       @id = id
@@ -556,6 +654,9 @@ module Tina4
       @params = {}
       @ws_server = ws_server
       @path = path
+      # Verified JWT payload on a secured WS route, else nil (public route).
+      # Mirrors Python's connection.auth.
+      @auth = nil
       @rooms = Set.new
       @on_message_handler = nil
       @on_close_handler = nil

data/lib/tina4.rb

@@ -212,6 +212,10 @@ module Tina4
       # Auto-discover routes
       auto_discover(root_dir)
 
+      # Apply pending DB migrations on startup (non-breaking — see method doc).
+      # Runs AFTER route discovery / DB bind, BEFORE serving.
+      auto_migrate_on_startup!(root_dir)
+
       Tina4::Log.info("Tina4 initialized successfully")
     end
 
@@ -383,9 +387,17 @@ module Tina4
       Tina4::Router.group(prefix, auth_handler: auth, &block)
     end
 
-    # WebSocket route registration
-    def websocket(path, &block)
-      Tina4::Router.websocket(path, &block)
+    # WebSocket route registration. PUBLIC by default (mirrors GET). Pass
+    # secure: true OR chain .secure on the returned route to require a valid JWT
+    # on the upgrade.
+    def websocket(path, secure: false, &block)
+      Tina4::Router.websocket(path, secure: secure, &block)
+    end
+
+    # Register a SECURED WebSocket route — declarative sibling of
+    # Tina4.websocket(...).secure, mirroring secure_get/secure_post.
+    def secure_websocket(path, &block)
+      Tina4::Router.secure_websocket(path, &block)
     end
 
     # Middleware hooks
@@ -440,8 +452,73 @@ module Tina4
       Tina4::Container.get(name)
     end
 
+    # Apply pending DB migrations on startup — NON-BREAKING. Public so it can be
+    # called explicitly (and unit-tested) as `Tina4.auto_migrate_on_startup!`.
+    #
+    # When a migrations/ folder exists (with at least one .sql file) and
+    # TINA4_AUTO_MIGRATE is not disabled, pending migrations are applied during
+    # boot so the schema is current with no manual `tina4ruby migrate` step. A
+    # failure here is logged LOUD and the service STILL starts — a bad migration
+    # must never take the backend down. (The explicit `tina4ruby migrate` CLI
+    # stays fail-fast so CI still gets a non-zero exit.)
+    #
+    # Disable with TINA4_AUTO_MIGRATE=false (also 0/no/off) — e.g. multi-instance
+    # production that migrates as a separate deploy step (concurrent first-apply
+    # can race).
+    def auto_migrate_on_startup!(root_dir = Dir.pwd)
+      # Gate 1: a migrations folder with at least one .sql file must exist.
+      migrations_dir = resolve_startup_migrations_dir(root_dir)
+      return unless migrations_dir
+
+      # Gate 2: TINA4_AUTO_MIGRATE not disabled (default "true"; false/0/no/off off).
+      unless Tina4::Env.is_truthy(ENV.fetch("TINA4_AUTO_MIGRATE", "true"))
+        Tina4::Log.debug("TINA4_AUTO_MIGRATE is off — skipping startup migrations")
+        return
+      end
+
+      # Gate 3: a database must be resolvable.
+      db = Tina4.database
+      unless db
+        Tina4::Log.debug("Startup migrations skipped (no database configured)")
+        return
+      end
+
+      begin
+        migration = Tina4::Migration.new(db, migrations_dir: migrations_dir)
+        results = migration.run
+        applied = Array(results).count { |r| r[:status] == "success" }
+        Tina4::Log.info("Applied #{applied} pending migration(s) on startup") if applied.positive?
+        # A migration that records as "failed" surfaces in `run`'s results but
+        # does NOT raise from the runner; treat a recorded failure as loud-log too.
+        if Array(results).any? { |r| r[:status] == "failed" }
+          Tina4::Log.error(
+            "Startup auto-migration failed — the service is starting anyway. " \
+            "Run `tina4ruby migrate` to retry."
+          )
+        end
+      rescue => e
+        # NON-BREAKING: never re-raise out of the startup hook.
+        Tina4::Log.error(
+          "Startup auto-migration failed: #{e.message} — the service is starting " \
+          "anyway. Run `tina4ruby migrate` to retry."
+        )
+      end
+    end
+
     private
 
+    # Resolve the migrations directory for startup auto-migration, returning it
+    # only when it exists AND contains at least one .sql file. Prefers
+    # src/migrations, falls back to migrations/ (mirrors Migration#resolve_migrations_dir).
+    def resolve_startup_migrations_dir(root_dir)
+      %w[src/migrations migrations].each do |rel|
+        dir = File.join(root_dir, rel)
+        next unless Dir.exist?(dir)
+        return dir unless Dir.glob(File.join(dir, "*.sql")).empty?
+      end
+      nil
+    end
+
     # Resolve auth option for route registration
     # :default => use bearer auth (default for POST/PUT/PATCH/DELETE)
     # false    => no auth (public route)

metadata

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