tina4ruby 3.13.94 → 3.13.96

data/lib/tina4/session_handlers/mongo_wire_client.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module Tina4
+  module SessionHandlers
+    # A MongoDB command that came back with `ok != 1`, or a transport failure,
+    # surfaced as an exception so the handler can tell a real error apart from a
+    # genuine miss (an empty firstBatch). Same split RespError makes for RESP.
+    class MongoWireError < StandardError; end
+
+    # Zero-dependency synchronous MongoDB client speaking the wire protocol
+    # (OP_MSG, opcode 2013) over a TCP socket, with a minimal BSON codec.
+    #
+    # WHY IT EXISTS (session_contract.json #6, ADR-0024). Python, PHP and Node
+    # have always shipped a raw OP_MSG fallback for the mongodb SESSION backend;
+    # Ruby alone hard-required the `mongo` gem and RAISED without it. The same
+    # .env therefore worked in three frameworks and failed in the fourth, which
+    # breaks the zero-dependency promise ASYMMETRICALLY - worse than breaking it
+    # consistently, because nothing about the configuration hints at it. This is
+    # the missing fourth transport, ported from the proven Python master
+    # (tina4_python/session_handlers/mongodb_handler.py) rather than invented.
+    #
+    # It is deliberately NOT a general Mongo driver. It implements exactly the
+    # four operations the session handler performs - find_one by _id, upsert by
+    # _id, delete_one by _id, and delete_many for gc - and it mirrors the SHAPE
+    # of the `mongo` gem's Collection for those four so the handler's read,
+    # write, destroy and gc bodies are IDENTICAL on both transports. That is not
+    # cosmetic: a branch inside each operation is a branch that can be wrong on
+    # one path only, and this fallback would then ship untested behind a
+    # condition nobody exercises.
+    #
+    # HARD-WON DETAILS, preserved from the three siblings:
+    #   * The COMMAND NAME comes FIRST in the document and `$db` LAST. Reversed,
+    #     the server reads `$db` as the command name and answers CommandNotFound.
+    #   * BSON is little-endian throughout, string lengths are BYTE counts (not
+    #     character counts), and a Time is encoded as BSON UTC datetime (0x09,
+    #     int64 milliseconds) so a document written here is byte-identical in
+    #     shape to one the gem writes.
+    #   * An OP_MSG reply can arrive split across TCP segments, so the body is
+    #     read by its exact declared byte count rather than one recv().
+    #
+    # NO NETWORK I/O IN A CONSTRUCTOR (ADR-0021, session_contract.json #4): the
+    # socket is opened on the FIRST command, inside the log-loud-and-degrade
+    # policy, never here.
+    class MongoWireClient
+      OP_MSG = 2013
+
+      # BSON element type bytes, named so the codec reads as the spec does.
+      TYPE_DOUBLE    = 0x01
+      TYPE_STRING    = 0x02
+      TYPE_DOCUMENT  = 0x03
+      TYPE_ARRAY     = 0x04
+      TYPE_BINARY    = 0x05
+      TYPE_OBJECT_ID = 0x07
+      TYPE_BOOLEAN   = 0x08
+      TYPE_DATETIME  = 0x09
+      TYPE_NULL      = 0x0A
+      TYPE_INT32     = 0x10
+      TYPE_TIMESTAMP = 0x11
+      TYPE_INT64     = 0x12
+
+      INT32_MIN = -2_147_483_648
+      INT32_MAX = 2_147_483_647
+
+      def initialize(host:, port:, database:, collection:, timeout: 10)
+        @host = host
+        @port = port
+        @database = database
+        @collection = collection
+        @timeout = timeout
+        @socket = nil
+        @request_id = 0
+      end
+
+      # Documents matching +filter+, capped at one.
+      #
+      # Returns an ARRAY so the caller can write `find(...).first` exactly as it
+      # does against the gem's Collection, which answers a lazy view. One shared
+      # call site, two transports.
+      def find(filter)
+        reply = command("find" => @collection, "filter" => filter, "limit" => 1, "$db" => @database)
+        reply.dig("cursor", "firstBatch") || []
+      end
+
+      # Apply +update+ (an operator document such as `{"$set" => {...}}`, or a
+      # full replacement) to the single document matching +filter+.
+      def update_one(filter, update, upsert: false)
+        command(
+          "update" => @collection,
+          "updates" => [{ "q" => filter, "u" => update, "upsert" => upsert }],
+          "$db" => @database
+        )
+      end
+
+      def delete_one(filter)
+        delete(filter, 1)
+      end
+
+      def delete_many(filter)
+        delete(filter, 0)
+      end
+
+      def close
+        @socket&.close
+      rescue StandardError
+        nil # already closed / never opened - nothing to do
+      ensure
+        @socket = nil
+      end
+
+      private
+
+      def delete(filter, limit)
+        command(
+          "delete" => @collection,
+          "deletes" => [{ "q" => filter, "limit" => limit }],
+          "$db" => @database
+        )
+      end
+
+      # Send one OP_MSG command and return the decoded reply document.
+      #
+      # RAISES MongoWireError on a transport failure or on `ok != 1`, so the
+      # Session boundary can log loud and degrade. A genuine MISS is not a
+      # failure and comes back as an empty firstBatch, never as an exception -
+      # collapsing the two is how a dead backend silently logs everyone out.
+      #
+      # The `ok` check lives HERE, outside the transport, on purpose. Folding it
+      # into #exchange would need a `rescue MongoWireError; raise` guard to stop
+      # a command error being relabelled as a transport failure, and that guard
+      # would also skip the socket drop for a genuine half-read reply - leaving
+      # a poisoned socket for the next caller to trip over.
+      def command(document)
+        reply = exchange(document)
+        return reply if reply["ok"].to_f == 1.0
+
+        raise MongoWireError, "MongoDB command failed: #{reply["errmsg"] || reply.inspect}"
+      end
+
+      # One request, one reply, on the shared socket. ANY failure in here is a
+      # transport failure, so the socket is dropped and the next command
+      # reconnects rather than inheriting the damage.
+      def exchange(document)
+        socket = connection
+        @request_id += 1
+        body = "\x00\x00\x00\x00".b + "\x00".b + encode_document(document) # flagBits(4) + section kind 0
+        header = [16 + body.bytesize, @request_id, 0, OP_MSG].pack("V4")
+        socket.write(header + body)
+        read_reply(socket)
+      rescue StandardError => e
+        close
+        raise MongoWireError, "MongoDB transport failed: #{e.message}"
+      end
+
+      def connection
+        @socket ||= begin
+          socket = Socket.tcp(@host, @port, connect_timeout: @timeout)
+          socket.setsockopt(Socket::SOL_SOCKET, Socket::SO_RCVTIMEO, [@timeout, 0].pack("l_2"))
+          socket
+        end
+      end
+
+      def read_reply(socket)
+        header = read_exact(socket, 16)
+        message_length = header.unpack1("V")
+        payload = read_exact(socket, message_length - 16)
+        # OP_MSG payload: flagBits(4) + section kind(1), then the body document.
+        decode_document(payload, [5])
+      end
+
+      def read_exact(socket, count)
+        buffer = +"".b
+        while buffer.bytesize < count
+          chunk = socket.read(count - buffer.bytesize)
+          raise MongoWireError, "connection closed mid-reply" if chunk.nil? || chunk.empty?
+
+          buffer << chunk
+        end
+        buffer
+      end
+
+      # ── Minimal BSON encoder ────────────────────────────────────────────
+
+      def encode_document(document)
+        body = +"".b
+        document.each { |key, value| body << encode_element(key.to_s, value) }
+        body << "\x00".b
+        [body.bytesize + 4].pack("V") + body
+      end
+
+      def encode_element(key, value)
+        ckey = key.b + "\x00".b
+
+        case value
+        when nil          then TYPE_NULL.chr + ckey
+        when true, false  then TYPE_BOOLEAN.chr + ckey + (value ? "\x01".b : "\x00".b)
+        when Integer      then encode_integer(ckey, value)
+        when Float        then TYPE_DOUBLE.chr + ckey + [value].pack("E")
+        when Time         then TYPE_DATETIME.chr + ckey + [(value.to_f * 1000).round].pack("q<")
+        when Hash         then TYPE_DOCUMENT.chr + ckey + encode_document(value)
+        when Array        then TYPE_ARRAY.chr + ckey + encode_document(indexed(value))
+        else                   encode_string(ckey, value.to_s)
+        end
+      end
+
+      def encode_integer(ckey, value)
+        return TYPE_INT32.chr + ckey + [value].pack("l<") if value.between?(INT32_MIN, INT32_MAX)
+
+        TYPE_INT64.chr + ckey + [value].pack("q<")
+      end
+
+      # A BSON string is a BYTE count followed by the bytes and a terminator, so
+      # the length must be bytesize - a UTF-8 payload counted in characters
+      # under-reports and the server rejects the document.
+      #
+      # This is also the catch-all for the encoder: a String, a Symbol and
+      # anything else this codec has no BSON type for all become strings, which
+      # is what Python, PHP and Node all do at the same point.
+      def encode_string(ckey, value)
+        bytes = value.b
+        TYPE_STRING.chr + ckey + [bytes.bytesize + 1].pack("V") + bytes + "\x00".b
+      end
+
+      # A BSON array is a document whose keys are the string indexes.
+      def indexed(array)
+        array.each_with_index.to_h { |value, index| [index.to_s, value] }
+      end
+
+      # ── Minimal BSON decoder ────────────────────────────────────────────
+      #
+      # +position+ is a single-element array used as a shared cursor, matching
+      # the Python master's `pos = [0]` - nested documents advance the one
+      # cursor rather than each level tracking its own offset.
+
+      def decode_document(data, position)
+        document_length = data[position[0], 4].unpack1("V")
+        position[0] += 4
+        finish = position[0] + document_length - 5
+
+        document = {}
+        while position[0] < finish
+          type = data.getbyte(position[0])
+          position[0] += 1
+
+          key_end = data.index("\x00".b, position[0])
+          key = data[position[0]...key_end].force_encoding(Encoding::UTF_8)
+          position[0] = key_end + 1
+
+          document[key] = decode_value(data, position, type, finish)
+        end
+
+        position[0] += 1 # document terminator
+        document
+      end
+
+      def decode_value(data, position, type, finish)
+        case type
+        when TYPE_DOUBLE    then take(data, position, 8).unpack1("E")
+        when TYPE_STRING    then decode_string(data, position)
+        when TYPE_DOCUMENT  then decode_document(data, position)
+        when TYPE_ARRAY     then decode_document(data, position).values
+        when TYPE_BINARY    then decode_binary(data, position)
+        when TYPE_OBJECT_ID then take(data, position, 12).unpack1("H*")
+        when TYPE_BOOLEAN   then take(data, position, 1).getbyte(0) != 0
+        when TYPE_DATETIME  then Time.at(take(data, position, 8).unpack1("q<") / 1000.0)
+        when TYPE_NULL      then nil
+        when TYPE_INT32     then take(data, position, 4).unpack1("l<")
+        when TYPE_TIMESTAMP then take(data, position, 8).unpack1("Q<")
+        when TYPE_INT64     then take(data, position, 8).unpack1("q<")
+        else
+          # An unknown type cannot be sized, so its length cannot be skipped.
+          # Stop at the document boundary rather than loop forever on a byte
+          # this codec does not understand.
+          position[0] = finish
+          nil
+        end
+      end
+
+      def decode_string(data, position)
+        length = take(data, position, 4).unpack1("V")
+        value = data[position[0], length - 1].force_encoding(Encoding::UTF_8)
+        position[0] += length
+        value
+      end
+
+      def decode_binary(data, position)
+        length = take(data, position, 4).unpack1("V")
+        position[0] += 1 # subtype
+        take(data, position, length)
+      end
+
+      def take(data, position, count)
+        slice = data[position[0], count]
+        position[0] += count
+        slice
+      end
+    end
+  end
+end

data/lib/tina4/session_handlers/redis_handler.rb

@@ -5,7 +5,9 @@ require_relative "resp_client"
 module Tina4
   module SessionHandlers
     # Redis-backed session handler. Prefers the `redis` gem when it is installed
-    # (parity with the Python redis-py and Node redis-npm handlers); otherwise
+    # (parity with Python, which prefers redis-py the same way, INSIDE this one
+    # handler rather than as a separate backend name — Node's `redis-npm`
+    # backend did the latter and was retired 2026-07-31 as drift); otherwise
     # speaks raw RESP over a TCP socket via RespClient — zero dependencies, so a
     # Tina4 app stores sessions in Redis with no extra gem.
     class RedisHandler
@@ -14,8 +16,10 @@ module Tina4
       # TINA4_SESSION_BACKEND=redis can actually be pointed at a server by env.
       # An explicit constructor option always wins over the environment.
       def initialize(options = {})
-        @prefix = options[:prefix] || "tina4:session:"
-        @ttl = options[:ttl] || 86400
+        @prefix = options[:prefix] || ENV["TINA4_SESSION_REDIS_PREFIX"] || "tina4:session:"
+        # TINA4_SESSION_TTL reaches every backend (ADR-0024); was a hard-coded
+        # 86400. 3600 matches Python (the master), PHP and Node.
+        @ttl = (options[:ttl] || ENV["TINA4_SESSION_TTL"] || 3600).to_i
         @host = options[:host] || ENV["TINA4_SESSION_REDIS_HOST"] || "localhost"
         @port = options[:port] || (ENV["TINA4_SESSION_REDIS_PORT"] ? ENV["TINA4_SESSION_REDIS_PORT"].to_i : 6379)
         @db = options[:db] || (ENV["TINA4_SESSION_REDIS_DB"] ? ENV["TINA4_SESSION_REDIS_DB"].to_i : 0)
@@ -33,13 +37,23 @@ module Tina4
         nil
       end
 
-      def write(session_id, data)
+      # Write session data. A per-call +ttl+ WINS over the handler default, so
+      # asking for a 60s session really gets 60s; 0 uses the default. Every
+      # handler in every Tina4 framework takes this third argument -- Session#write
+      # passes it, and a handler that did not accept it raised ArgumentError,
+      # which safe_write swallowed into a silent STALE write.
+      #
+      # @param session_id [String] the session id
+      # @param data [Hash] the payload to store
+      # @param ttl [Integer] per-call lifetime in seconds; 0 uses the handler default
+      def write(session_id, data, ttl = 0)
         key = "#{@prefix}#{session_id}"
         payload = JSON.generate(data)
+        effective_ttl = ttl.to_i.positive? ? ttl.to_i : @ttl
         if @redis
-          @redis.setex(key, @ttl, payload)
+          @redis.setex(key, effective_ttl, payload)
         else
-          @resp.setex(key, @ttl, payload)
+          @resp.setex(key, effective_ttl, payload)
         end
       end
 

data/lib/tina4/session_handlers/valkey_handler.rb

@@ -11,7 +11,11 @@ module Tina4
     class ValkeyHandler
       def initialize(options = {})
         @prefix = options[:prefix] || ENV["TINA4_SESSION_VALKEY_PREFIX"] || "tina4:session:"
-        @ttl = options[:ttl] || (ENV["TINA4_SESSION_VALKEY_TTL"] ? ENV["TINA4_SESSION_VALKEY_TTL"].to_i : 86400)
+        # TINA4_SESSION_VALKEY_TTL stays as the valkey-specific override, but it
+        # now falls back to TINA4_SESSION_TTL - the ONE session-lifetime variable
+        # every backend must honour (ADR-0024) - instead of a hard-coded 86400.
+        # 3600 matches Python (the master), PHP and Node.
+        @ttl = (options[:ttl] || ENV["TINA4_SESSION_VALKEY_TTL"] || ENV["TINA4_SESSION_TTL"] || 3600).to_i
         @host = options[:host] || ENV["TINA4_SESSION_VALKEY_HOST"] || "localhost"
         @port = options[:port] || (ENV["TINA4_SESSION_VALKEY_PORT"] ? ENV["TINA4_SESSION_VALKEY_PORT"].to_i : 6379)
         @db = options[:db] || (ENV["TINA4_SESSION_VALKEY_DB"] ? ENV["TINA4_SESSION_VALKEY_DB"].to_i : 0)
@@ -29,13 +33,23 @@ module Tina4
         nil
       end
 
-      def write(session_id, data)
+      # Write session data. A per-call +ttl+ WINS over the handler default, so
+      # asking for a 60s session really gets 60s; 0 uses the default. Every
+      # handler in every Tina4 framework takes this third argument -- Session#write
+      # passes it, and a handler that did not accept it raised ArgumentError,
+      # which safe_write swallowed into a silent STALE write.
+      #
+      # @param session_id [String] the session id
+      # @param data [Hash] the payload to store
+      # @param ttl [Integer] per-call lifetime in seconds; 0 uses the handler default
+      def write(session_id, data, ttl = 0)
         key = "#{@prefix}#{session_id}"
         payload = JSON.generate(data)
+        effective_ttl = ttl.to_i.positive? ? ttl.to_i : @ttl
         if @redis
-          @redis.setex(key, @ttl, payload)
+          @redis.setex(key, effective_ttl, payload)
         else
-          @resp.setex(key, @ttl, payload)
+          @resp.setex(key, effective_ttl, payload)
         end
       end
 

data/lib/tina4/shutdown.rb

@@ -1,21 +1,49 @@
 # frozen_string_literal: true
 
 module Tina4
+  # Graceful shutdown on SIGTERM / SIGINT.
+  #
+  # The order is the contract, identical in all four Tina4 frameworks:
+  #
+  #   1. Stop accepting FIRST. The listening socket closes before anything is
+  #      drained, so a connection arriving after the signal gets a clean
+  #      CONNECTION REFUSED - not a 503, not a TCP reset.
+  #   2. Tell live WebSocket peers we are going away (RFC 6455 close code 1001).
+  #   3. Drain in-flight requests, bounded by TINA4_SHUTDOWN_TIMEOUT.
+  #   4. Stop background tasks, close database connections, exit 0.
+  #
+  # SIGHUP is deliberately NOT trapped: the Rust CLI owns file watching and
+  # production logs go to stdout, so neither Puma's log-reopen nor gunicorn's
+  # config-reload use for SIGHUP is a Tina4 need.
   module Shutdown
+    # Matches Kubernetes' default terminationGracePeriodSeconds and Gunicorn's
+    # graceful_timeout, and is the same default in Python, PHP and Node.
     DEFAULT_TIMEOUT = 30 # seconds
 
     class << self
       attr_reader :in_flight_count
 
-      def setup(server: nil, timeout: nil)
+      # The resolved TINA4_SHUTDOWN_TIMEOUT. Public because the production path
+      # does not drain in Ruby at all - it maps this onto Puma's own
+      # force_shutdown_after so the documented env var means the same thing
+      # whichever server owns the socket.
+      attr_reader :timeout
+
+      # trap_signals: false when another server owns INT/TERM (Puma does). A
+      # Tina4 trap on that path would be installed but never usefully serviced:
+      # there is no listener to close and nothing calls track_request, so if the
+      # other server's own trap install ever failed, ours would swallow the
+      # default terminate and do nothing - the process would survive the signal.
+      def setup(server: nil, timeout: nil, trap_signals: true)
         @server = server
-        @timeout = (timeout || ENV["TINA4_SHUTDOWN_TIMEOUT"] || DEFAULT_TIMEOUT).to_i
+        @timeout = resolve_timeout(timeout)
         @shutting_down = false
+        @shutdown_complete = false
         @mutex = Mutex.new
         @in_flight_count = 0
         @in_flight_cv = ConditionVariable.new
 
-        install_signal_handlers
+        install_signal_handlers if trap_signals
       end
 
       def shutting_down?
@@ -40,51 +68,173 @@ module Tina4
         @shutting_down = true
         Tina4::Log.info("Shutdown signal received, stopping gracefully...")
 
-        # Wait for in-flight requests with timeout
+        stop_accepting
+        drained = wait_for_in_flight
+        release_resources
+
+        Tina4::Log.info("Shutdown complete")
+        @shutdown_complete = true
+        return if drained
+
+        # The deadline expired with requests still in flight. WEBrick's accept
+        # loop joins its worker threads with NO timeout of its own, so simply
+        # returning here would hang the process for as long as the slowest
+        # handler runs - exactly what TINA4_SHUTDOWN_TIMEOUT exists to prevent.
+        # Flush first: exit! runs no at_exit handlers and does not flush stdio,
+        # which would swallow the warning that explains the forced exit.
+        $stdout.flush
+        $stderr.flush
+        exit!(0)
+      end
+
+      # The teardown NO web server can do for us, because no web server knows
+      # these things exist: live WebSocket peers owed an RFC 6455 close frame,
+      # Tina4 background threads, and ORM-bound database connections.
+      #
+      # Public so the production path can run exactly the same teardown from an
+      # ensure around Puma's launcher: Puma owns the socket, the drain and the
+      # signals there, but a database connection it has never heard of would
+      # otherwise leak on every single shutdown.
+      def release_resources
+        close_websockets
+        stop_background_tasks
+        close_database
+      end
+
+      # Block until initiate_shutdown has finished every teardown step.
+      #
+      # stop_accepting unblocks WEBrick's accept loop immediately, so its #start
+      # returns as soon as the in-flight workers are joined - which can be while
+      # the signal handler's thread is still stopping background tasks and
+      # closing database connections. The server's main thread calls this so the
+      # process does not exit out from under that teardown.
+      def wait_for_completion(timeout = nil)
+        return unless @shutting_down
+
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) +
+                   (timeout || @timeout.to_f + 5)
+        until @shutdown_complete || Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+          sleep 0.02
+        end
+      end
+
+      private
+
+      # TINA4_SHUTDOWN_TIMEOUT in seconds (same name and default in all four
+      # frameworks). An unparseable or negative value warns and falls back to the
+      # default: `"abc".to_i` is 0, and a silent 0-second drain would force-close
+      # every in-flight request on the first signal. An explicit 0 is honoured -
+      # that is a deliberate choice, not a silent one.
+      def resolve_timeout(explicit)
+        raw = explicit || ENV["TINA4_SHUTDOWN_TIMEOUT"]
+        return DEFAULT_TIMEOUT if raw.nil? || raw.to_s.strip.empty?
+
+        seconds = Float(raw)
+        raise ArgumentError, "must not be negative" if seconds.negative?
+
+        seconds
+      rescue ArgumentError, TypeError
+        Tina4::Log.warning(
+          "TINA4_SHUTDOWN_TIMEOUT=#{raw.inspect} is not a non-negative number, using #{DEFAULT_TIMEOUT}s"
+        )
+        DEFAULT_TIMEOUT
+      end
+
+      # Close the listening socket BEFORE draining. WEBrick's #shutdown wakes its
+      # accept loop and closes the listeners; it does not touch the worker
+      # threads already running, which the loop's own ensure joins - so new
+      # connections are refused while in-flight requests still run to completion
+      # and write their full response. Measured on webrick 1.9.2 / Ruby 4.0.2:
+      # #shutdown returns in ~0.1ms, a connection attempted 0.3s later is
+      # ECONNREFUSED, and the 2s handler mid-flight still returns a full 200.
+      def stop_accepting
+        return unless @server.respond_to?(:shutdown)
+
+        @server.shutdown
+        Tina4::Log.info("Stopped accepting new connections")
+      rescue StandardError => e
+        Tina4::Log.error("Error closing the listening socket: #{e.message}")
+      end
+
+      # RFC 6455 close code 1001 "going away" is what a server sends when it is
+      # shutting down, so clients reconnect elsewhere instead of treating the
+      # drop as an error. Both live managers are covered: the process-wide route
+      # engine (Tina4::WebSocket.current, published by RackApp) and the
+      # dev-reload channel's own manager - the same pair DevAdmin#ws_managers
+      # enumerates.
+      def close_websockets
+        closed = 0
+        live_websocket_managers.each do |manager|
+          manager.connections.values.each do |connection|
+            connection.close(code: 1001, reason: "going away")
+            closed += 1
+          rescue StandardError => e
+            Tina4::Log.warning("Error closing WebSocket #{connection.id}: #{e.message}")
+          end
+        end
+        Tina4::Log.info("Closed #{closed} WebSocket connection(s) with 1001 going away") if closed.positive?
+      rescue StandardError => e
+        Tina4::Log.error("Error closing WebSocket connections: #{e.message}")
+      end
+
+      def live_websocket_managers
+        managers = []
+        return managers unless defined?(Tina4::WebSocket)
+
+        managers << Tina4::WebSocket.current if Tina4::WebSocket.current
+        managers << Tina4::DevReload.manager if defined?(Tina4::DevReload)
+        managers
+      end
+
+      # true when everything drained, false when the deadline expired.
+      def wait_for_in_flight
         deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @timeout
         @mutex.synchronize do
           while @in_flight_count > 0
             remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
             if remaining <= 0
-              Tina4::Log.warning("Shutdown timeout reached with #{@in_flight_count} requests still in flight")
-              break
+              Tina4::Log.warning(
+                "TINA4_SHUTDOWN_TIMEOUT=#{@timeout}s reached with #{@in_flight_count} " \
+                "request(s) still in flight, forcing close"
+              )
+              return false
             end
             @in_flight_cv.wait(@mutex, remaining)
           end
         end
+        true
+      end
 
-        # Stop background tasks
-        if defined?(Tina4::Background)
-          begin
-            Tina4::Background.stop_all
-            Tina4::Log.info("Background tasks stopped")
-          rescue => e
-            Tina4::Log.error("Error stopping background tasks: #{e.message}")
-          end
-        end
+      def stop_background_tasks
+        return unless defined?(Tina4::Background)
 
-        # Close database connections
-        if Tina4.database
-          begin
-            Tina4.database.close
-            Tina4::Log.info("Database connections closed")
-          rescue => e
-            Tina4::Log.error("Error closing database: #{e.message}")
-          end
-        end
+        Tina4::Background.stop_all
+        Tina4::Log.info("Background tasks stopped")
+      rescue StandardError => e
+        Tina4::Log.error("Error stopping background tasks: #{e.message}")
+      end
 
-        Tina4::Log.info("Shutdown complete")
+      # Close the DEFAULT connection and every NAMED one. Only closing
+      # Tina4.database leaked every connection registered with
+      # bind_database(db, name:) - a model pointed at a secondary database held
+      # its connection open through shutdown.
+      def close_database
+        connections = [Tina4.database, *Tina4.databases.values].compact.uniq(&:object_id)
+        return if connections.empty?
 
-        # Stop the server
-        @server&.shutdown if @server.respond_to?(:shutdown)
+        connections.each do |connection|
+          connection.close
+        rescue StandardError => e
+          Tina4::Log.error("Error closing database: #{e.message}")
+        end
+        Tina4::Log.info("Database connections closed (#{connections.size})")
       end
 
-      private
-
       def install_signal_handlers
         %w[INT TERM].each do |signal|
           Signal.trap(signal) do
-            # Signal handlers must be async-signal-safe; use Thread to do real work
+            # A trap context must stay async-signal-safe (no mutexes, no IO), so
+            # the real work happens on a thread.
             Thread.new { initiate_shutdown }
           end
         end