tina4ruby 3.13.93 → 3.13.96

data/lib/tina4/session_handlers/file_handler.rb

@@ -1,13 +1,36 @@
 # frozen_string_literal: true
 require "json"
 require "fileutils"
+require "digest"
 
 module Tina4
   module SessionHandlers
     class FileHandler
+      # TINA4_SESSION_PATH selects the session directory, with the SAME
+      # precedence the other three frameworks use: an explicit option wins, then
+      # the environment, then "data/sessions".
+      #
+      # Ruby read NO env var here and hard-defaulted to <cwd>/sessions, so it
+      # drifted on BOTH halves of ADR-0024: the documented variable did nothing
+      # (example/.env.example has advertised "TINA4_SESSION_PATH=data/sessions"
+      # the whole time), and the default location differed from Python
+      # (session/__init__.py FileSessionHandler), PHP (Session.php:128) and Node
+      # (session.ts:184) - all three of which resolve
+      # `path || TINA4_SESSION_PATH || "data/sessions"`. Pointing the file
+      # backend at a mounted volume worked in three frameworks and was silently
+      # ignored in the fourth, which is the exact "one env var and nothing else"
+      # promise ADR-0024 makes.
+      #
+      # The default stays RELATIVE, exactly as the other three leave it, so all
+      # four resolve the same path against the same working directory.
       def initialize(options = {})
-        @dir = options[:dir] || File.join(Dir.pwd, "sessions")
-        @ttl = options[:ttl] || 86400
+        @dir = options[:dir] || ENV["TINA4_SESSION_PATH"] || File.join("data", "sessions")
+        # TINA4_SESSION_TTL is the ONE session-lifetime variable, and it must
+        # reach EVERY backend (ADR-0024). This used to be a hard-coded 86400,
+        # so an operator setting a 15-minute session got 24 hours here and got
+        # it right only on memcached - the one handler that read the variable.
+        # 3600 is the default in Python (the master), PHP and Node.
+        @ttl = (options[:ttl] || ENV["TINA4_SESSION_TTL"] || 3600).to_i
         FileUtils.mkdir_p(@dir)
       end
 
@@ -15,21 +38,40 @@ module Tina4
         path = session_path(session_id)
         return nil unless File.exist?(path)
 
-        # Check expiry
-        if File.mtime(path) + @ttl < Time.now
+        stored = JSON.parse(File.read(path))
+        if expired?(stored, path)
           File.delete(path)
           return nil
         end
 
-        data = File.read(path)
-        JSON.parse(data)
+        unwrap(stored)
       rescue JSON::ParserError
         nil
       end
 
-      def write(session_id, data)
-        path = session_path(session_id)
-        File.write(path, JSON.generate(data))
+      # Write session data.
+      #
+      # The ttl is consumed HERE, at write time, and baked into an ABSOLUTE
+      # deadline stored beside the payload, so nothing at read time needs to know
+      # what the ttl was. That is what makes a per-call ttl durable: a reader with
+      # a different ttl can no longer judge someone else's record.
+      #
+      # A ttl of 0 (or negative) means NEVER EXPIRES, matching the Python master,
+      # Node, and every mainstream implementation measured. It previously fell
+      # through to the mtime comparison, where `mtime + 0 < Time.now` made ttl: 0
+      # mean "expire immediately" - the opposite meaning, and the only backend in
+      # any of the four frameworks that read it that way.
+      #
+      # @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)
+        effective_ttl = ttl.to_i.positive? ? ttl.to_i : @ttl
+        expires_at = effective_ttl.positive? ? Time.now.to_f + effective_ttl : 0.0
+        File.write(
+          session_path(session_id),
+          JSON.generate({ "_data" => data, "_expires" => expires_at })
+        )
       end
 
       def destroy(session_id)
@@ -38,29 +80,79 @@ module Tina4
       end
 
       def cleanup
-        return unless Dir.exist?(@dir)
-        Dir.glob(File.join(@dir, "sess_*")).each do |file|
-          File.delete(file) if File.mtime(file) + @ttl < Time.now
-        end
+        sweep
       end
 
       # Garbage-collect expired sessions. Matches the Python interface.
-      # @param max_age [Integer] maximum session age in seconds
-      def gc(max_age)
+      # @param max_age [Integer] accepted for interface parity; expiry is absolute
+      #   and already baked into the stored deadline, so it is used only for legacy
+      #   records that carry no deadline of their own.
+      def gc(max_age = nil)
+        sweep(max_age)
+      end
+
+      private
+
+      # Delete every genuinely-expired record. An absent or zero deadline means
+      # never expires, so such a record is never a sweep candidate.
+      def sweep(max_age = nil)
         return unless Dir.exist?(@dir)
-        now = Time.now
+
         Dir.glob(File.join(@dir, "sess_*")).each do |file|
-          File.delete(file) if File.mtime(file) + max_age < now
+          stored = begin
+            JSON.parse(File.read(file))
+          rescue JSON::ParserError
+            nil
+          end
+          File.delete(file) if stored && expired?(stored, file, max_age)
         rescue StandardError
-          # Corrupt or locked file — skip
+          # Corrupt or locked file - skip
         end
       end
 
-      private
+      # Decide whether a stored record has expired.
+      #
+      # THE CONTRACT: an ABSENT or ZERO deadline means "never expires". It is
+      # guarded OUT of the comparison, never fed INTO it. Verified against real
+      # mainstream implementations - PHP's native files handler, express-session,
+      # Django, Laravel, connect-redis and connect-mongo - none of which deletes a
+      # record carrying no expiry.
+      #
+      # A LEGACY record (a bare payload written before the envelope existed) has no
+      # deadline of its own, so it keeps the original mtime comparison. Without
+      # that fallback every already-stored session would become immortal on
+      # upgrade, which trades data loss for a security bug.
+      def expired?(stored, path, max_age = nil)
+        if stored.is_a?(Hash) && stored.key?("_expires")
+          expires_at = stored["_expires"].to_f
+          return expires_at.positive? && expires_at < Time.now.to_f
+        end
+
+        lifetime = (max_age || @ttl).to_i
+        lifetime.positive? && File.mtime(path) + lifetime < Time.now
+      end
+
+      # Return the caller's payload. A legacy bare payload is returned as-is, so a
+      # record written by an older version still reads correctly.
+      def unwrap(stored)
+        return stored["_data"] if stored.is_a?(Hash) && stored.key?("_expires")
+
+        stored
+      end
 
+      # SHA-256 of the id. A session id can therefore never become a path
+      # component, AND two distinct ids can never collide.
+      #
+      # The previous gsub(/[^a-zA-Z0-9_-]/, "") was traversal-safe but LOSSY: it
+      # collapsed "a/b" and "ab" onto the same sess_ab.json, so two different
+      # sessions shared one record and one user's data surfaced under another
+      # user's id. Parity with the Python master's FileSessionHandler._file
+      # (hashlib.sha256(session_id.encode()).hexdigest()).
+      #
+      # The sess_ prefix is kept deliberately so #cleanup and #gc keep matching
+      # with their Dir.glob("sess_*").
       def session_path(session_id)
-        safe_id = session_id.gsub(/[^a-zA-Z0-9_-]/, "")
-        File.join(@dir, "sess_#{safe_id}.json")
+        File.join(@dir, "sess_#{Digest::SHA256.hexdigest(session_id.to_s)}.json")
       end
     end
   end

data/lib/tina4/session_handlers/memcached_handler.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "socket"
+
+module Tina4
+  module SessionHandlers
+    # Memcached session handler - zero-dependency text protocol over TCP.
+    #
+    # Memcached was already one of the seven CACHE backends in all four
+    # frameworks but was NOT a session backend in any of them, even though it is
+    # the classic PHP session store. This closes that gap.
+    #
+    # Speaks the memcached TEXT protocol directly over a socket, so there is no
+    # gem dependency - the same zero-dependency choice the Redis/Valkey handlers
+    # make.
+    #
+    # BACKEND-FAILURE POLICY. A genuine key miss returns +{}+ silently (no
+    # session yet is normal). A TRANSPORT failure - server unreachable,
+    # connection dropped mid-reply, a protocol error - RAISES, so the Session
+    # layer can log-loud and degrade. Collapsing the two is how a dead cache
+    # silently logs every user out.
+    #
+    # Memcached has no persistence and no replication: a restart drops every
+    # session. That is a deliberate trade (it is a cache), and it is why
+    # file/database remain the defaults.
+    #
+    # Environment variables:
+    #   TINA4_SESSION_MEMCACHED_HOST   - hostname (default: localhost)
+    #   TINA4_SESSION_MEMCACHED_PORT   - port (default: 11211)
+    #   TINA4_SESSION_MEMCACHED_PREFIX - key prefix (default: tina4:session:)
+    #   TINA4_SESSION_TTL              - session TTL in seconds (default: 3600)
+    class MemcachedHandler
+      # Memcached rejects a key over 250 bytes or containing a space/control
+      # character. A key that could break either rule is HASHED rather than
+      # truncated - truncating would let two different sessions collide on one
+      # key, handing one user another user's session.
+      MAX_KEY_BYTES = 250
+
+      # memcached's exptime field changes meaning at 30 days: at or below this
+      # it is RELATIVE seconds, above it the server reads an ABSOLUTE UNIX
+      # TIMESTAMP. See #exptime for why we convert instead of clamping.
+      MAX_RELATIVE_EXPTIME = 2_592_000
+
+      def initialize(options = {})
+        options ||= {}
+        @host = options[:host] || ENV["TINA4_SESSION_MEMCACHED_HOST"] || "localhost"
+        @port = (options[:port] || ENV["TINA4_SESSION_MEMCACHED_PORT"] || 11_211).to_i
+        @prefix = options[:prefix] || ENV["TINA4_SESSION_MEMCACHED_PREFIX"] || "tina4:session:"
+        @ttl = (options[:ttl] || ENV["TINA4_SESSION_TTL"] || 3600).to_i
+        @timeout = (options[:timeout] || 5).to_f
+      end
+
+      # Read a session. Returns {} for a genuine miss; RAISES on a transport
+      # failure so an outage is never mistaken for "no session yet".
+      def read(session_id)
+        resp = command("get #{key(session_id)}\r\n", ["END\r\n"])
+        return {} unless resp.start_with?("VALUE")
+
+        header, rest = resp.split("\r\n", 2)
+        return {} if rest.nil?
+
+        bytes = header.split[3].to_i
+        parsed = JSON.parse(rest[0, bytes])
+        parsed.is_a?(Hash) ? parsed : {}
+      rescue JSON::ParserError
+        # A corrupt value is treated as no session rather than crashing the
+        # request; the next write replaces it.
+        {}
+      end
+
+      # Write a session with a TTL (0 falls back to the configured default).
+      def write(session_id, data, ttl = 0)
+        effective_ttl = exptime(ttl.to_i.positive? ? ttl.to_i : @ttl)
+        payload = JSON.generate(data)
+        cmd = "set #{key(session_id)} 0 #{effective_ttl} #{payload.bytesize}\r\n"
+        resp = command("#{cmd}#{payload}\r\n",
+                       ["STORED\r\n", "ERROR\r\n", "SERVER_ERROR", "CLIENT_ERROR"])
+        return if resp.start_with?("STORED")
+
+        raise "Memcached did not store the session: #{resp[0, 80].inspect}"
+      end
+
+      # Delete a session. A session that was already gone is not an error.
+      def destroy(session_id)
+        command("delete #{key(session_id)}\r\n", ["DELETED\r\n", "NOT_FOUND\r\n", "ERROR\r\n"])
+        nil
+      end
+
+      # No-op - memcached expires its own keys via the TTL set on write.
+      def cleanup
+        nil
+      end
+
+      # Garbage-collect expired sessions. Memcached expires its own keys via the
+      # TTL set on write, so there is genuinely nothing to sweep - but the
+      # ARGUMENT still has to be accepted, because Session#gc calls
+      # handler.gc(max_lifetime) with exactly one argument.
+      #
+      # This was `alias gc cleanup`, and #cleanup takes ZERO arguments, so
+      # MemcachedHandler#gc.arity was 0 and EVERY session GC against a memcached
+      # backend raised ArgumentError "wrong number of arguments (given 1,
+      # expected 0)". Session#gc's rescue then reported it as a BACKEND failure -
+      # "Session gc failed (...MemcachedHandler): wrong number of arguments" -
+      # so an internal arity bug was misattributed to the operator's memcached,
+      # and a perfectly healthy server logged an ERROR on every sweep.
+      # FileHandler#gc(max_age = nil) and DatabaseHandler#gc(max_age) both take
+      # the argument; memcached was the odd one out.
+      #
+      # @param max_age [Integer, nil] accepted for interface parity; memcached
+      #   owns its own expiry, so nothing here consults it.
+      def gc(_max_age = nil)
+        cleanup
+      end
+
+      private
+
+      # Convert a ttl in SECONDS to memcached's dual-meaning exptime field.
+      #
+      # memcached documents exptime as RELATIVE seconds up to 2592000 (30 days),
+      # and as an ABSOLUTE UNIX TIMESTAMP for anything larger. Sending a raw ttl
+      # of 2592001 therefore does not mean "30 days and one second" - it means
+      # 1970-01-31, which is already past, so the item expires the instant it is
+      # stored. memcached still replies STORED, so the write looks fine and the
+      # very next read is a miss: a silent logout on every request.
+      #
+      # Measured against real memcached 1.6.45: ttl=2592000 survives, ttl=2592001
+      # vanishes instantly.
+      #
+      # We CONVERT rather than CLAMP. Clamping a 60-day session down to 30 days
+      # would silently shorten a lifetime the operator explicitly asked to be
+      # longer, which is the same class of lie in the other direction.
+      def exptime(ttl)
+        return Time.now.to_i + ttl if ttl > MAX_RELATIVE_EXPTIME
+
+        ttl
+      end
+
+      def key(session_id)
+        candidate = "#{@prefix}#{session_id}"
+        return candidate unless candidate.bytesize > MAX_KEY_BYTES || candidate.match?(/[\x00-\x20\x7f]/)
+
+        "#{@prefix}#{Digest::SHA256.hexdigest(session_id.to_s)}"
+      end
+
+      # Run one memcached command and return the raw reply.
+      #
+      # RAISES on any transport failure. The cache backend swallows these and
+      # returns an empty string - correct for a cache (a miss and an outage are
+      # both "not cached"), wrong for a session, where an outage must be
+      # distinguishable from "no session yet".
+      def command(payload, terminators)
+        sock = Socket.tcp(@host, @port, connect_timeout: @timeout)
+        begin
+          sock.write(payload)
+          buffer = +""
+          until terminators.any? { |t| buffer.include?(t) }
+            chunk = begin
+              sock.read_nonblock(4096)
+            rescue IO::WaitReadable
+              raise "timed out waiting for a reply" unless sock.wait_readable(@timeout)
+
+              retry
+            end
+            raise "connection closed before a complete reply" if chunk.nil? || chunk.empty?
+
+            buffer << chunk
+          end
+          buffer
+        ensure
+          begin
+            sock&.close
+          rescue IOError, SystemCallError
+            nil
+          end
+        end
+      rescue StandardError => e
+        raise "Memcached session backend at #{@host}:#{@port} failed: #{e.message}"
+      end
+    end
+  end
+end

data/lib/tina4/session_handlers/mongo_handler.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 require "json"
+require_relative "mongo_wire_client"
 
 module Tina4
   module SessionHandlers
@@ -10,56 +11,272 @@ module Tina4
       # TINA4_SESSION_MONGO_URL is a legacy alias. The database default is
       # "tina4" (Python's default — Ruby previously drifted to "tina4_sessions").
       # An explicit constructor option always wins over the environment.
+      # NO NETWORK I/O IN A CONSTRUCTOR (ADR-0021, session_contract.json #4).
+      # `require "mongo"` is a pure load and costs nothing on the wire;
+      # Mongo::Client.new is NOT - it starts SDAM topology monitoring and
+      # handshakes the server immediately, and ensure_ttl_index then issues a
+      # createIndexes round trip (dropping and recreating the index on an
+      # IndexOptionsConflict).
+      #
+      # MEASURED against a REAL counting TCP listener before this change:
+      # constructing this handler accepted THREE connections. That traffic sat
+      # OUTSIDE the log-loud-and-degrade policy, so an unreachable MongoDB took
+      # the app down at construction instead of degrading per request - the one
+      # place the policy cannot protect being the FIRST thing that runs.
+      #
+      # The client, the collection and the TTL index are all built on FIRST USE.
+      #
+      # TWO TRANSPORTS, ONE RESOLUTION POINT (session_contract.json #6,
+      # ADR-0024). The `mongo` gem is used when it is installed; when it is NOT,
+      # this handler speaks the MongoDB wire protocol directly over a socket via
+      # MongoWireClient - zero dependencies, exactly as Python, PHP and Node have
+      # always done. This line USED to be a bare `require "mongo"` whose
+      # `rescue LoadError` re-raised "MongoDB session handler requires the
+      # 'mongo' gem", so TINA4_SESSION_BACKEND=mongodb worked in three
+      # frameworks and blew up in the fourth on identical configuration.
+      # MEASURED at v3 HEAD in a real subprocess with no gems resolvable at all:
+      # file, redis, valkey and memcached all round-tripped a session and
+      # mongodb raised at Session construction.
+      #
+      # The probe stays a PURE LOAD - `require` opens no socket - so ADR-0021
+      # (no network I/O in a constructor) still holds. Guarding on
+      # ::Mongo::VERSION rather than on `require` alone is the same defence
+      # RedisHandler#build_gem_client uses: a bare `Mongo` constant defined by
+      # something else must not be mistaken for the real driver.
       def initialize(options = {})
-        require "mongo"
-        @ttl = options[:ttl] || 86400
+        # 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
         @uri = options[:uri] || ENV["TINA4_SESSION_MONGO_URI"] || ENV["TINA4_SESSION_MONGO_URL"] || "mongodb://localhost:27017"
         @database = options[:database] || ENV["TINA4_SESSION_MONGO_DB"] || "tina4"
         @collection_name = options[:collection] || ENV["TINA4_SESSION_MONGO_COLLECTION"] || "sessions"
-        client = Mongo::Client.new(@uri, database: @database)
-        @collection = client[@collection_name]
-        ensure_ttl_index
-      rescue LoadError
-        raise "MongoDB session handler requires the 'mongo' gem. Install with: gem install mongo"
-      rescue Mongo::Error => e
-        Tina4::Log.error("MongoDB session setup failed: #{e.message}")
+        @gem_available = gem_available?
+        @client = nil
+        @wire_client = nil
+        @collection = nil
+        @index_ready = false
+      end
+
+      # Release whichever transport was opened.
+      #
+      # Mongo::Client owns a pool of REAL sockets. Before the client was lazy it
+      # was a local variable in #initialize, reachable only through the
+      # collection, so every construction leaked a pool and nothing could give it
+      # back. Now the handler holds the client, so the handler can close it -
+      # parity with the Python master's MongoDBSessionHandler.close() and with
+      # Tina4::DocStore.close_doc_store, which already closes its Mongo clients
+      # the same way. The zero-dependency transport owns ONE raw socket and is
+      # closed the same way, so neither path leaks. Safe to call on a handler
+      # that never connected.
+      def close
+        # Each close is guarded on its own: a failure on one transport must not
+        # skip the other, and neither may mask the caller's work.
+        [@client, @wire_client].each do |transport|
+          transport&.close
+        rescue StandardError
+          nil
+        end
+      ensure
+        @client = nil
+        @wire_client = nil
+        @collection = nil
+        @index_ready = false
+      end
+
+      # Decide whether a stored document has expired, FROM THE DOCUMENT ALONE.
+      #
+      # THE CONTRACT: an ABSENT or ZERO expiry stamp means "never expires". It is
+      # guarded OUT of the comparison, never fed INTO it - so a document written
+      # by another framework, an older version, or a direct insert is returned
+      # rather than destroyed. Identical to the Python master's _has_expired.
+      def self.expired?(doc)
+        expires_at = doc["expires_at"].to_f
+        expires_at.positive? && expires_at < Time.now.to_f
       end
 
       def read(session_id)
-        doc = @collection.find(_id: session_id).first
+        doc = collection.find(_id: session_id).first
         return nil unless doc
+
+        # Expiry is checked HERE, at read time, against the document's own
+        # absolute deadline. Relying on the TTL index alone (as this handler used
+        # to) cannot honour a short TTL at all: mongod's TTL monitor sweeps once
+        # every 60 SECONDS, so a 2-second session stayed readable for up to a
+        # minute after it expired. The index is still created, but purely as the
+        # background reaper that keeps the collection from growing forever.
+        if self.class.expired?(doc)
+          destroy(session_id)
+          return nil
+        end
+
         doc["data"]
       end
 
-      def write(session_id, data)
-        @collection.update_one(
+      # Write session data. A per-call +ttl+ WINS over the handler default.
+      #
+      # The ttl is consumed HERE, at write time, and baked into an ABSOLUTE
+      # deadline (+expires_at+), so nothing at read time needs to know what the
+      # ttl was. That field name and meaning are the shape Python (the master),
+      # PHP and Node all store, so a session store SHARED between two frameworks
+      # carries one shape instead of four. +updated_at+ is still written to feed
+      # the TTL index.
+      #
+      # @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)
+        effective_ttl = ttl.to_i.positive? ? ttl.to_i : @ttl
+        now = Time.now
+        expires_at = effective_ttl.positive? ? now.to_f + effective_ttl : 0.0
+        collection.update_one(
           { _id: session_id },
-          { "$set" => { data: data, updated_at: Time.now } },
+          { "$set" => { data: data, expires_at: expires_at,
+                        updated_at: now - (@ttl - effective_ttl) } },
           upsert: true
         )
       end
 
       def destroy(session_id)
-        @collection.delete_one(_id: session_id)
+        collection.delete_one(_id: session_id)
       end
 
       def cleanup
-        # MongoDB TTL index handles cleanup
+        gc
+      end
+
+      # Garbage-collect expired sessions. Matches the Python master's
+      # MongoDBSessionHandler.gc and the FileHandler interface, and it is what
+      # Session#gc calls when a handler responds to it.
+      #
+      # THE REAPER IS NOT OPTIONAL ON THE ZERO-DEPENDENCY TRANSPORT. The TTL
+      # index below is created on the gem path only (creating it needs the gem's
+      # own index API), so without this sweep a wire-protocol deployment would
+      # keep every expired document forever. Expiry itself is unaffected either
+      # way - #read checks the document's own absolute deadline.
+      #
+      # Same contract as #read: only a stamp that is genuinely PRESENT and in
+      # the PAST makes a document a deletion candidate. `$gt: 0` is explicit so
+      # a document with a zero stamp is never swept, and one with no stamp at
+      # all cannot match the range predicate either.
+      #
+      # @param max_lifetime [Integer] accepted for interface parity; expiry is
+      #   absolute and already baked into expires_at at write time.
+      def gc(max_lifetime = nil)
+        _ = max_lifetime
+        collection.delete_many("expires_at" => { "$gt" => 0, "$lt" => Time.now.to_f })
       end
 
       private
 
+      # Whether the REAL `mongo` gem is loadable. A pure load - it opens no
+      # socket - so this is safe in a constructor (ADR-0021). Returns false when
+      # the gem is absent, which selects the zero-dependency wire transport.
+      def gem_available?
+        require "mongo"
+        defined?(::Mongo::VERSION) ? true : false
+      rescue LoadError
+        false
+      end
+
+      # The collection, built on FIRST USE rather than at construction, so every
+      # byte this handler puts on the wire happens inside the log-loud-and-degrade
+      # policy (see #initialize). Called by read/write/destroy/gc.
+      #
+      # THIS IS THE ONE PLACE THE TRANSPORT IS CHOSEN. read, write, destroy and
+      # gc have no branch of their own: whichever transport this returns answers
+      # find/update_one/delete_one/delete_many with the same shape, so the
+      # request path cannot take one transport while a directly-constructed
+      # handler takes the other. A per-operation branch is a branch that can be
+      # wrong on one path only - which is exactly how a fallback ships untested.
+      def collection
+        return @collection if @collection
+
+        if @gem_available
+          @client = Mongo::Client.new(@uri, database: @database)
+          @collection = @client[@collection_name]
+          ensure_ttl_index
+        else
+          @wire_client = build_wire_client
+          @collection = @wire_client
+        end
+        @collection
+      end
+
+      # The zero-dependency transport, pointed at the host and port parsed out of
+      # the configured URI. Opens nothing here - MongoWireClient connects on its
+      # first command.
+      #
+      # mongodb+srv:// is REFUSED here rather than half-supported. That scheme is
+      # not a host at all: it is a DNS SRV lookup that yields the real seed list,
+      # plus mandatory TLS. Parsing it as a hostname would dial
+      # "cluster0.example.mongodb.net:27017" in the clear, which does not exist,
+      # and the operator would get a bare connection-refused with nothing
+      # pointing at the cause. Before this fallback existed they got a clear
+      # "requires the 'mongo' gem"; they still get a clear message. Naming the
+      # remedy at the point of use is the framework's rule for a genuinely
+      # missing capability.
+      def build_wire_client
+        if @uri.to_s.start_with?("mongodb+srv://")
+          raise "mongodb+srv:// needs a DNS SRV lookup and TLS, which the zero-dependency " \
+                "MongoDB transport does not do. Install the 'mongo' gem (gem install mongo), " \
+                "or point TINA4_SESSION_MONGO_URI at an explicit mongodb://host:port."
+        end
+
+        host, port = parse_host_port(@uri)
+        MongoWireClient.new(host: host, port: port, database: @database, collection: @collection_name)
+      end
+
+      # Extract host and port from a MongoDB URI, mirroring the Python master's
+      # _parse_url: strip the scheme, strip any credentials, strip the path and
+      # query, then take the FIRST host of a seed list.
+      #
+      # URI.parse is deliberately not used: a perfectly ordinary replica-set URI
+      # ("mongodb://a:27017,b:27017/db") is not a valid RFC 3986 authority, so it
+      # raises - and defaulting to localhost there would silently dial the WRONG
+      # server, which is far worse than any parse error.
+      def parse_host_port(uri)
+        remainder = uri.to_s.sub(%r{\Amongodb://}, "")
+        remainder = remainder.split("@", 2).last.to_s   # credentials
+        remainder = remainder.split("/", 2).first.to_s  # path + query
+        remainder = remainder.split(",", 2).first.to_s  # first seed host
+        host, port = remainder.split(":", 2)
+        host = "localhost" if host.nil? || host.empty?
+        [host, port.nil? || port.empty? ? 27_017 : port.to_i]
+      end
+
       # Create the updated_at TTL index. An existing updated_at index with a
       # DIFFERENT expireAfterSeconds raises IndexOptionsConflict (code 85) — a
       # TTL index cannot be modified in place — so drop and recreate it with the
       # requested TTL. This makes re-init idempotent (no per-run error log) and
       # lets a changed session TTL take effect.
+      #
+      # GEM PATH ONLY - #collection calls it in that branch and nowhere else.
+      # Python, PHP and Node create no TTL index on any transport, so the
+      # zero-dependency path reaps with #gc instead and expiry itself is
+      # unchanged either way (#read checks the document's own deadline). It also
+      # could not run here: the rescues below name Mongo::Error, a constant that
+      # does not exist when the gem is absent, so evaluating them would raise
+      # NameError rather than the LoadError anyone would expect.
+      #
+      # Runs ONCE per handler (@index_ready), on the first operation. The flag is
+      # set BEFORE the round trip so an unreachable server is not re-probed on
+      # every read - the same ordering the Python master uses for _table_ready.
       def ensure_ttl_index
+        return if @index_ready
+
+        @index_ready = true
         @collection.indexes.create_one({ updated_at: 1 }, expire_after_seconds: @ttl)
       rescue Mongo::Error::OperationFailure => e
         raise unless e.code == 85 || e.message.include?("IndexOptionsConflict")
         @collection.indexes.drop_one("updated_at_1")
         @collection.indexes.create_one({ updated_at: 1 }, expire_after_seconds: @ttl)
+      rescue Mongo::Error => e
+        # The index is the background REAPER, not the expiry authority - #read
+        # checks expires_at on the document itself - so failing to create it must
+        # not break sessions. The constructor swallowed this the same way; the
+        # only change is WHERE it is swallowed. A genuinely unreachable server
+        # still surfaces on the read/write that follows, inside the policy.
+        Tina4::Log.error("MongoDB session setup failed: #{e.message}")
       end
     end
   end