tina4ruby 3.13.94 → 3.13.97

data/lib/tina4/session.rb

@@ -8,11 +8,47 @@ module Tina4
       secret: nil,
       max_age: 3600,
       handler: :file,
-      handler_options: {}
+      handler_options: {},
+      # Opt-in, and OFF for every direct caller. See the construction guard in
+      # #initialize: only the live REQUEST PATH degrades when the storage
+      # handler cannot be built; boot, the CLI, a spec and app code that call
+      # Session.new themselves still get the loud raise they rely on.
+      degrade_on_backend_failure: false
     }.freeze
 
     attr_reader :id, :data
 
+    # A session id is OPAQUE — an unguessable lookup token and nothing else. It
+    # is never a filename, a path, a SQL fragment or a Redis key fragment, so the
+    # only characters it may contain are the ones every backend treats as inert.
+    #
+    # The alphabet is the RFC 4648 base64url set, which is exactly what all four
+    # frameworks already mint: Ruby SecureRandom.hex(32), Python
+    # secrets.token_urlsafe(32), PHP/Node hex(16). Validation is therefore
+    # non-breaking for every id the family has ever issued, while rejecting the
+    # "." and "/" that turn a cookie into a path traversal.
+    #
+    # The constraint is the ALPHABET, not the length. There is deliberately NO
+    # entropy floor: unguessability comes from the framework MINTING the id
+    # (SecureRandom.hex(32)), never from inspecting one an app passed on purpose,
+    # so a floor would close no attack while breaking trusted callers that manage
+    # their own short programmatic ids (start("my-session-id")). An
+    # attacker-supplied id is stopped by strict mode (see #adopt_or_mint), not by
+    # its length. The 128-character ceiling just bounds what can be pushed
+    # through a backend key.
+    #
+    # \A and \z, NEVER ^ and $: Ruby's ^/$ match LINE boundaries, so a "^...$"
+    # anchor would accept "legitimate_looking_id\n../../etc/passwd".
+    SESSION_ID_PATTERN = /\A[A-Za-z0-9_-]{1,128}\z/
+
+    # True when session_id is a well-formed opaque session identifier.
+    #
+    # Callers pass UNTRUSTED input here (the session cookie is attacker-chosen),
+    # so anything that is not a String of the opaque alphabet is rejected.
+    def self.valid_session_id?(session_id)
+      session_id.is_a?(String) && SESSION_ID_PATTERN.match?(session_id)
+    end
+
     # The session cookie name — the SINGLE source of truth shared by the WRITE
     # side (#cookie_header) and the READ side (#extract_session_id AND RackApp's
     # incoming-cookie parse), so a cookie written under a renamed name is read
@@ -49,6 +85,13 @@ module Tina4
         ttl_env = ENV["TINA4_SESSION_TTL"]
         @options[:max_age] = Integer(ttl_env) if ttl_env && !ttl_env.strip.empty?
       end
+      # The BACKEND lifetime, resolved once and forwarded to handler#write on
+      # every save (parity with Python's Session._ttl, which flows the same way).
+      # #save used to call safe_write(@id, @data) with NO ttl, so the cookie said
+      # Max-Age=900 while the stored record lived for the handler's own default -
+      # a silent disagreement between what the browser was told and what the
+      # store actually did. One resolver, both directions.
+      @ttl = (options[:ttl] || ENV["TINA4_SESSION_TTL"] || 3600).to_i
       # TINA4_SESSION_BACKEND — selects the storage handler unless the caller
       # explicitly passed :handler (same precedence as :cookie_name above; an
       # explicit option always wins over the environment). Without this the
@@ -66,10 +109,47 @@ module Tina4
       # session cookie for an encrypted request must never be sent in the clear.
       # Uses the SAME detector as Request#url so the two never disagree (issue #31).
       @request_secure = Tina4::Request.secure_scheme?(env || {})
-      @handler = create_handler
-      @id = extract_session_id(env) || SecureRandom.hex(32)
-      @data = load_session
-      @modified = false
+      # LOG LOUD, THEN DEGRADE (ADR-0021) - for handler CONSTRUCTION too.
+      #
+      # The read/write/destroy/gc policy further down has always been right, but
+      # it sat BELOW this line: create_handler ran bare. A handler whose
+      # constructor touches the network - the database backend opens its
+      # connection and issues DDL in #initialize - raised straight out of
+      # Session.new, out of Request#session, and into RackApp's 500 handler, so
+      # an unreachable backend took the whole REQUEST down instead of degrading
+      # it, and TINA4_SESSION_STRICT was INERT because the non-strict path
+      # already produced the identical 500.
+      #
+      # WHO DEGRADES, AND WHO STILL RAISES. Only the caller that opts in, which
+      # is the live request path (Request#session, RackApp.enforce_route_auth).
+      # Every other caller keeps the loud raise, deliberately: an unknown
+      # TINA4_SESSION_BACKEND is a CONFIGURATION error, not an outage, and the
+      # owner decision of 2026-07-31 (session_backend_validation_spec.rb, all
+      # four frameworks) is that it must fail fast where a human can fix it
+      # rather than serve on the wrong storage. This is the same split the
+      # Python master makes: its Session raises, and core/server.py's request
+      # path is what logs and degrades.
+      #
+      # A DEGRADED SESSION IS AN IN-MEMORY-ONLY SESSION: no handler, so nothing
+      # is read from or written to any store. The route still receives a working
+      # Session object - Ruby cannot hand back Python's `request.session = None`
+      # without turning every `session[...]` into a NoMethodError, which would
+      # 500 the very request this is saving - so reads yield an empty session
+      # and #save returns false, which is exactly the contract. The failure is
+      # logged ONCE, here, where it happened; see #degraded? for why not again.
+      @handler = nil
+      begin
+        @handler = create_handler
+      rescue StandardError => e
+        raise unless @options[:degrade_on_backend_failure]
+
+        log_backend_error("handler construction", e)
+        raise if @strict
+      end
+      # The cookie is the live server's session-id source and is fully
+      # attacker-controlled, so it goes through the same strict-mode funnel as
+      # an explicit #start.
+      adopt_or_mint(extract_session_id(env))
     end
 
     def [](key)
@@ -98,9 +178,13 @@ module Tina4
     # Persist the session if dirty. On a backend write failure the error is
     # logged and false is returned — the @modified (dirty) flag is RETAINED so
     # a later save can retry. Returns true on a successful (or no-op) write.
+    #
+    # A cleared id (@id nil, e.g. after #destroy) is a no-op: there is nothing
+    # to persist, and a write would re-create the just-destroyed record. Mirrors
+    # the Python master's `if self._session_id and self._dirty`.
     def save
-      return true unless @modified
-      if safe_write(@id, @data)
+      return true unless @id && @modified
+      if safe_write(@id, @data, @ttl)
         @modified = false
         true
       else
@@ -108,16 +192,36 @@ module Tina4
       end
     end
 
-    # Destroy the current session. Should be called right after login or any
-    # privilege change to defend against session fixation (see #regenerate).
+    # Destroy the current session. ENDS the session: the stored record is
+    # removed and the id is CLEARED (@id = nil), so a later set()+save() with no
+    # new #start has no id to persist under and cannot RESURRECT the just-
+    # destroyed record. Mirrors the Python master (nulls _session_id) and Node
+    # (nulls sessionId). A fresh session needs a new #start, which mints a new id.
     def destroy
-      safe_destroy(@id)
+      safe_destroy(@id) if @id
+      @id = nil
       @data = {}
+      @modified = false
     end
 
-    # Get a session value with optional default
+    # Get a session value with optional default.
+    #
+    # The default is returned for an ABSENT key, never for a stored FALSE. This
+    # was `@data[key.to_s] || default`, which handed back the caller's default
+    # for any falsy stored value — so a feature flag stored as false read back
+    # as the caller's `true` default. Python (`dict.get`), PHP (`??`) and Node
+    # (`??`) all return the stored false, so Ruby was the 1-of-4 outlier.
+    #
+    # Deliberately the `nil?` form and NOT `@data.key?(k) ? @data[k] : default`:
+    # both fix the false case, but the key? form would ALSO flip a stored nil
+    # from the default to nil. Ruby currently agrees with PHP and Node there
+    # (stored nil -> default) and only Python disagrees (stored None -> None),
+    # so changing it is a cross-framework decision, not a side effect of this
+    # fix. This form is exactly PHP's `??` and Node's `??`. Same idiom as
+    # #get_flash below.
     def get(key, default = nil)
-      @data[key.to_s] || default
+      value = @data[key.to_s]
+      value.nil? ? default : value
     end
 
     # Set a session value
@@ -171,18 +275,15 @@ module Tina4
       @id
     end
 
-    # Start or resume a session. If session_id is given, load that session;
-    # otherwise generate a new ID. Returns the session ID string.
+    # Start or resume a session. Returns the session ID string.
+    #
+    # session_id is UNTRUSTED, so it goes through #adopt_or_mint: it is resumed
+    # only when it is a well-formed opaque id AND one the backend already holds a
+    # session under (strict mode). Otherwise a genuinely NEW session is started
+    # under a fresh SecureRandom.hex(32). A session already in flight keeps both
+    # its id and its data.
     def start(session_id = nil)
-      if session_id
-        @id = session_id
-        @data = load_session
-      else
-        @id = SecureRandom.hex(32)
-        @data = {}
-      end
-      @modified = false
-      @id
+      adopt_or_mint(session_id)
     end
 
     # Returns the current session ID string.
@@ -238,6 +339,9 @@ module Tina4
 
     private
 
+    # The session id carried on the incoming cookie, or nil. A pure parser —
+    # every caller funnels through #adopt_or_mint, which is where the value is
+    # judged.
     def extract_session_id(env)
       cookie_str = env["HTTP_COOKIE"] || ""
       cookie_str.split(";").each do |pair|
@@ -247,8 +351,58 @@ module Tina4
       nil
     end
 
-    def load_session
-      safe_read(@id)
+    # Adopt session_id, or mint a fresh one — the SINGLE decision both entry
+    # points (the constructor's cookie path and #start) go through, so neither
+    # can drift from the rule or skip it.
+    #
+    # STRICT SESSION MODE (OWASP; PHP's session.use_strict_mode=1). session_id is
+    # UNTRUSTED: it comes from the session cookie or a caller, both of which the
+    # client controls. It is adopted ONLY when it is BOTH
+    #   (a) a well-formed opaque id (see valid_session_id?), and
+    #   (b) an id the backend already holds a session under.
+    # Anything else — malformed, or well-formed but never issued — is DISCARDED
+    # and a fresh SecureRandom.hex(32) minted. Adopting either one is session
+    # fixation: an attacker plants a cookie, the victim logs in under it, and the
+    # attacker already holds the authenticated session id. A malformed id also
+    # used to steer a filesystem path.
+    #
+    # Sets @id/@data/@modified and returns the resolved id.
+    def adopt_or_mint(session_id)
+      session_id = nil unless self.class.valid_session_id?(session_id)
+      data = session_id.nil? ? nil : existing_session_data(session_id)
+      if data.nil?
+        session_id = SecureRandom.hex(32)
+        data = {}
+      end
+      @id = session_id
+      @data = data
+      @modified = false
+      @id
+    end
+
+    # The stored data for session_id when the backend HOLDS a session under it,
+    # else nil — strict mode's signal to mint a fresh id rather than adopt one
+    # the client chose.
+    #
+    # nil AND empty both count as "no session": the handlers disagree (file,
+    # redis, valkey, mongo and database return nil for a missing session, while
+    # memcached returns {}), and strict mode must not silently no-op on one
+    # backend. An empty STORED session cannot arise anyway — #save is a no-op
+    # until something is actually written.
+    #
+    # A backend FAILURE is deliberately NOT "no session": it logs and returns {},
+    # so the id is still adopted. Reading an outage as "unknown" would rotate
+    # every id and log the entire userbase out on a single Redis blip — the
+    # opposite of the log-loud + degrade policy below.
+    def existing_session_data(session_id)
+      return nil if degraded?
+
+      data = @handler.read(session_id)
+      data.nil? || (data.respond_to?(:empty?) && data.empty?) ? nil : data
+    rescue StandardError => e
+      log_backend_error("read", e)
+      raise if @strict
+      {}
     end
 
     # ── Backend-failure policy (parity with Python's Session boundary) ──
@@ -263,7 +417,19 @@ module Tina4
     # raising) is NOT a failure and logs nothing. TINA4_SESSION_STRICT=true
     # re-raises instead of degrading.
 
+    # True when handler construction failed and this session is in-memory only
+    # (see #initialize). Every store operation below short-circuits to its
+    # degraded answer WITHOUT logging: the outage was already logged once, at
+    # the point it actually happened, and re-logging the same fact on every
+    # read/write would multiply one dead backend into a line per operation and
+    # bury it - the same blindness this whole policy exists to cure.
+    def degraded?
+      @handler.nil?
+    end
+
     def safe_read(session_id)
+      return {} if degraded?
+
       existing = @handler.read(session_id)
       existing || {}
     rescue StandardError => e
@@ -273,6 +439,8 @@ module Tina4
     end
 
     def safe_write(session_id, data, ttl = nil)
+      return false if degraded?
+
       if ttl
         @handler.write(session_id, data, ttl)
       else
@@ -286,6 +454,8 @@ module Tina4
     end
 
     def safe_destroy(session_id)
+      return false if degraded?
+
       @handler.destroy(session_id)
       true
     rescue StandardError => e
@@ -295,14 +465,48 @@ module Tina4
     end
 
     # Single source of the backend-failure log line. Names the operation and
-    # the concrete handler class so ops can see WHICH backend failed.
+    # the concrete handler class so ops can see WHICH backend failed. When
+    # CONSTRUCTION is what failed there is no handler yet, so it falls back to
+    # the CONFIGURED backend name - which is the thing the operator has to fix
+    # ("redsi", "database"), and strictly more useful than "NilClass".
     def log_backend_error(operation, error)
-      handler_class = @handler.class.name
+      handler_class = @handler ? @handler.class.name : @options[:handler].to_s
       Tina4::Log.error("Session #{operation} failed (#{handler_class}): #{error.message}")
     rescue StandardError
       warn("Session #{operation} failed: #{error.message}")
     end
 
+    # Every accepted backend name, aliases included. Byte-identical membership in
+    # all four frameworks. Written once here so the case below and the error
+    # message can never disagree.
+    VALID_BACKENDS = %w[
+      file filesystem
+      redis
+      valkey
+      mongodb mongo
+      memcached memcache
+      database db
+    ].freeze
+
+    # Canonical name of each backend, for the error message. Listing every alias
+    # would make it longer without making it clearer.
+    CANONICAL_BACKENDS = %w[file redis valkey mongodb memcached database].freeze
+
+    # Reject a backend name that is not a known backend.
+    #
+    # Never sees a blank name: create_handler normalises blank to "file" first,
+    # in one place. Blank must NOT be an error - an env var set to "" is a SET
+    # variable, so rejecting it would break every deployment that clears the var
+    # to fall back to the default.
+    def validate_backend!(name)
+      return if VALID_BACKENDS.include?(name)
+
+      raise ArgumentError,
+            "Unknown session backend \"#{name}\". " \
+            "Valid backends: #{CANONICAL_BACKENDS.join(', ')}. " \
+            "Leave TINA4_SESSION_BACKEND unset for the file default."
+    end
+
     # The configured TINA4_SESSION_BACKEND name, or nil when unset/blank (so the
     # caller keeps the DEFAULT_OPTIONS handler). The value is normalised at
     # dispatch in #create_handler, not here.
@@ -313,13 +517,23 @@ module Tina4
 
     # Build the storage handler for the resolved backend name.
     #
-    # The accepted names — and the aliases — mirror Python's
+    # The accepted names - and the aliases - mirror Python's
     # Session._resolve_handler exactly: file|filesystem, redis, valkey,
-    # mongodb|mongo, database|db. The name is normalised (downcase + strip) so
-    # "Redis" / " mongodb " from a .env line resolve, and an UNKNOWN value falls
-    # back to the file handler SILENTLY (never raises) — same as Python.
+    # mongodb|mongo, memcached|memcache, database|db. The name is normalised
+    # (downcase + strip) so "Redis" / " mongodb " from a .env line resolve.
+    #
+    # An UNKNOWN value RAISES. It used to fall back to the file handler
+    # silently, and the comment here described that as correct parity with
+    # Python - it was, and both were wrong. A typo in TINA4_SESSION_BACKEND
+    # ("redsi") produced a running app writing sessions to local disk while the
+    # operator believed they were in Redis: nothing logged, nothing failed, and
+    # the symptom surfaced later as users being logged out whenever a request
+    # landed on another instance.
     def create_handler
-      case @options[:handler].to_s.downcase.strip.to_sym
+      name = @options[:handler].to_s.downcase.strip
+      name = "file" if name.empty?
+      validate_backend!(name)
+      case name.to_sym
       when :file, :filesystem
         Tina4::SessionHandlers::FileHandler.new(@options[:handler_options])
       when :redis
@@ -328,6 +542,8 @@ module Tina4
         Tina4::SessionHandlers::MongoHandler.new(@options[:handler_options])
       when :valkey
         Tina4::SessionHandlers::ValkeyHandler.new(@options[:handler_options])
+      when :memcached, :memcache
+        Tina4::SessionHandlers::MemcachedHandler.new(@options[:handler_options])
       when :database, :db
         # Parity with Python: the database backend "uses whatever DB is
         # connected", so reuse the single ORM resolver (named binding → global
@@ -339,7 +555,14 @@ module Tina4
           { db: Tina4::ORM.db }.merge(@options[:handler_options] || {})
         )
       else
-        Tina4::SessionHandlers::FileHandler.new(@options[:handler_options])
+        # Unreachable for a user's typo - validate_backend! already rejected it.
+        # Only a name that IS in VALID_BACKENDS but has no branch above can land
+        # here, which is a bug in this method rather than a configuration error,
+        # so it must not be swallowed into a file handler either.
+        raise ArgumentError,
+              "Session backend #{name.inspect} is listed in VALID_BACKENDS but " \
+              "has no handler branch. This is a framework bug, not a " \
+              "configuration error."
       end
     end
   end

data/lib/tina4/session_handlers/database_handler.rb

@@ -7,22 +7,120 @@ module Tina4
     class DatabaseHandler
       TABLE_NAME = "tina4_session"
 
-      CREATE_TABLE_SQL = <<~SQL
-        CREATE TABLE IF NOT EXISTS #{TABLE_NAME} (
-            session_id VARCHAR(255) PRIMARY KEY,
-            data TEXT NOT NULL,
-            expires_at REAL NOT NULL
-        )
-      SQL
+      # CREATE TABLE per engine. This is the ONLY genuinely per-engine SQL in
+      # this file - every other statement is written once with `?` placeholders
+      # and rewritten for the driver by the Database layer.
+      #
+      # The COLUMNS are identical on every engine (session_id, data,
+      # expires_at) because the table is a CROSS-FRAMEWORK CONTRACT: a
+      # tina4_session table written by tina4-python must be readable by
+      # tina4-ruby. Only the type spellings and the "create it only if absent"
+      # idiom differ. Ported from the Node reference under ADR-0004
+      # (tina4-nodejs/packages/core/src/sessionHandlers/databaseHandler.ts).
+      #
+      # WHAT WAS WRONG. This used to be ONE generic string for every engine,
+      # opening with CREATE TABLE IF NOT EXISTS. That clause is not T-SQL, so
+      # the whole statement was a SYNTAX ERROR on SQL Server and the database
+      # session backend did not work on MSSQL AT ALL - the identical defect
+      # measured and fixed in PHP. Firebird rejected the same string twice
+      # over: it has no IF NOT EXISTS clause AND no TEXT type.
+      CREATE_TABLE_SQL = {
+        # Behaviour-identical to the generic DDL this replaces, so an EXISTING
+        # deployment is untouched. IF NOT EXISTS makes the statement a no-op
+        # against a table that is already there, so a live tina4_session keeps
+        # exactly the columns it was created with; and on a FRESH database the
+        # storage classes are the same ones the old spelling produced, because
+        # SQLite resolves VARCHAR(255) to TEXT affinity and DOUBLE PRECISION to
+        # REAL affinity. Only the declared type string in sqlite_master
+        # changes, and nothing reads that.
+        "sqlite" => <<~SQL,
+          CREATE TABLE IF NOT EXISTS #{TABLE_NAME} (
+              session_id TEXT PRIMARY KEY,
+              data TEXT NOT NULL,
+              expires_at REAL NOT NULL
+          )
+        SQL
+        "postgres" => <<~SQL,
+          CREATE TABLE IF NOT EXISTS #{TABLE_NAME} (
+              session_id VARCHAR(255) PRIMARY KEY,
+              data TEXT NOT NULL,
+              expires_at DOUBLE PRECISION NOT NULL
+          )
+        SQL
+        "mysql" => <<~SQL,
+          CREATE TABLE IF NOT EXISTS #{TABLE_NAME} (
+              session_id VARCHAR(255) PRIMARY KEY,
+              data TEXT NOT NULL,
+              expires_at DOUBLE NOT NULL
+          )
+        SQL
+        # T-SQL has no CREATE TABLE IF NOT EXISTS. Node guards this statement
+        # with `IF OBJECT_ID(N'tina4_session', N'U') IS NULL`; that guard is
+        # deliberately NOT carried over, because it is CHECK-THEN-ACT and has a
+        # window - two connections can both see NULL and both CREATE, and the
+        # loser gets `Msg 2714: There is already an object named
+        # 'tina4_session'`, measured on live SQL Server. This takes Node's
+        # TYPES and pairs them with PHP's RESCUE in ensure_table below, which
+        # is strictly better than either alone: Node's types make the statement
+        # legal on this engine, and PHP's rescue closes the window Node's
+        # catalog check leaves open.
+        "mssql" => <<~SQL,
+          CREATE TABLE #{TABLE_NAME} (
+              session_id NVARCHAR(255) NOT NULL PRIMARY KEY,
+              data NVARCHAR(MAX) NOT NULL,
+              expires_at FLOAT NOT NULL
+          )
+        SQL
+        # Firebird has neither IF NOT EXISTS nor a TEXT type, so the catalog
+        # check goes in an EXECUTE BLOCK and the payload is a VARCHAR. That
+        # caps a session payload at 8191 characters ON THIS ENGINE ALONE, which
+        # is the deliberate price of not using BLOB SUB_TYPE TEXT: a driver
+        # hands a blob back as a reader rather than a string, which the read
+        # path here would not understand.
+        #
+        # VERIFIED AT THE SQL LEVEL ONLY (Firebird 5.0.4, via isql, measured on
+        # the lab container): CREATE TABLE IF NOT EXISTS fails -104 "Token
+        # unknown ... NOT", a TEXT column fails -607 "Specified domain or
+        # source column TEXT does not exist", DOUBLE PRECISION is accepted, and
+        # this EXECUTE BLOCK creates the table and is idempotent on a second
+        # run. That idempotence is check-then-act inside one block, so it is
+        # NOT a race guard - a bare CREATE with the table present gives
+        # SQLSTATE 42S01, so the rescue below is required here exactly as on
+        # mssql.
+        "firebird" => <<~SQL
+          EXECUTE BLOCK AS BEGIN
+            IF (NOT EXISTS(SELECT 1 FROM RDB$RELATIONS WHERE RDB$RELATION_NAME = '#{TABLE_NAME.upcase}')) THEN
+              EXECUTE STATEMENT 'CREATE TABLE #{TABLE_NAME.upcase} (SESSION_ID VARCHAR(255) NOT NULL PRIMARY KEY, DATA VARCHAR(8191) NOT NULL, EXPIRES_AT DOUBLE PRECISION NOT NULL)';
+          END
+        SQL
+      }.freeze
 
+      # NO NETWORK I/O IN A CONSTRUCTOR (ADR-0021, session_contract.json #4).
+      # Both lines this constructor used to run were real traffic:
+      #
+      #   Tina4::Database.new(...)  - #initialize ends in `connect` for a
+      #     single-connection database (database.rb:405), so the driver DIALS.
+      #     MEASURED against a real counting TCP listener: 1 accepted connection.
+      #   ensure_table              - a CREATE TABLE IF NOT EXISTS, real DDL on
+      #     that connection.
+      #
+      # And because the request path builds a Session per request, that ran on
+      # EVERY request. Both sat OUTSIDE the log-loud-and-degrade policy, so an
+      # unreachable database took the app down at construction instead of
+      # degrading per request as designed. Connection and table are now resolved
+      # on FIRST USE, inside that policy.
       def initialize(options = {})
-        @ttl = options[:ttl] || 86400
-        @db = options[:db] || Tina4::Database.new(ENV["TINA4_DATABASE_URL"])
-        ensure_table
+        # 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
+        @db_option = options[:db]
+        @db = nil
+        @table_ready = false
       end
 
       def read(session_id)
-        row = @db.fetch_one("SELECT data, expires_at FROM #{TABLE_NAME} WHERE session_id = ?", [session_id])
+        ensure_table
+        row = db.fetch_one("SELECT data, expires_at FROM #{TABLE_NAME} WHERE session_id = ?", [session_id])
         return nil unless row
 
         expires_at = (row[:expires_at] || row["expires_at"]).to_f
@@ -36,36 +134,103 @@ module Tina4
         nil
       end
 
-      def write(session_id, data)
-        expires_at = @ttl > 0 ? Time.now.to_f + @ttl : 0.0
+      # Write session data. A per-call +ttl+ WINS over the handler default; 0 means
+      # never expires and is stored as the 0 that read guards out.
+      #
+      # @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)
+        ensure_table
+        effective_ttl = ttl.to_i.positive? ? ttl.to_i : @ttl
+        expires_at = effective_ttl.positive? ? Time.now.to_f + effective_ttl : 0.0
         json_data = JSON.generate(data)
 
-        existing = @db.fetch_one("SELECT session_id FROM #{TABLE_NAME} WHERE session_id = ?", [session_id])
+        existing = db.fetch_one("SELECT session_id FROM #{TABLE_NAME} WHERE session_id = ?", [session_id])
         if existing
-          @db.execute("UPDATE #{TABLE_NAME} SET data = ?, expires_at = ? WHERE session_id = ?", [json_data, expires_at, session_id])
+          db.execute("UPDATE #{TABLE_NAME} SET data = ?, expires_at = ? WHERE session_id = ?", [json_data, expires_at, session_id])
         else
-          @db.execute("INSERT INTO #{TABLE_NAME} (session_id, data, expires_at) VALUES (?, ?, ?)", [session_id, json_data, expires_at])
+          db.execute("INSERT INTO #{TABLE_NAME} (session_id, data, expires_at) VALUES (?, ?, ?)", [session_id, json_data, expires_at])
         end
       end
 
       def destroy(session_id)
-        @db.execute("DELETE FROM #{TABLE_NAME} WHERE session_id = ?", [session_id])
+        ensure_table
+        db.execute("DELETE FROM #{TABLE_NAME} WHERE session_id = ?", [session_id])
       end
 
       def cleanup
-        @db.execute("DELETE FROM #{TABLE_NAME} WHERE expires_at > 0 AND expires_at < ?", [Time.now.to_f])
+        ensure_table
+        db.execute("DELETE FROM #{TABLE_NAME} WHERE expires_at > 0 AND expires_at < ?", [Time.now.to_f])
       end
 
       # Garbage-collect expired sessions. Matches the Python interface.
       # @param max_age [Integer] maximum session age in seconds (unused — expiry is absolute)
       def gc(max_age)
-        @db.execute("DELETE FROM #{TABLE_NAME} WHERE expires_at > 0 AND expires_at < ?", [Time.now.to_f])
+        ensure_table
+        db.execute("DELETE FROM #{TABLE_NAME} WHERE expires_at > 0 AND expires_at < ?", [Time.now.to_f])
       end
 
       private
 
+      # The database connection, resolved on FIRST USE. An explicit :db option
+      # still wins; only the env-derived fallback has to be built, and building
+      # it CONNECTS (see #initialize), which is why it cannot happen earlier.
+      def db
+        @db ||= (@db_option || Tina4::Database.new(ENV["TINA4_DATABASE_URL"]))
+      end
+
+      # The CREATE TABLE this connection's engine understands.
+      #
+      # Tina4::Database#driver_name is the public accessor and it already holds
+      # the ALIAS-NORMALISED engine key ("postgres", not "postgresql"), the same
+      # value used to pick the driver class, so nothing here re-parses the
+      # connection string. An injected :db is an application-supplied object and
+      # therefore a trust boundary: one that cannot name its engine falls back
+      # to the generic ANSI shape, which is byte-for-byte what every engine used
+      # to get, so an app that duck-types a database is no worse off than before.
+      def create_table_sql
+        engine = db.respond_to?(:driver_name) ? db.driver_name.to_s : ""
+        CREATE_TABLE_SQL.fetch(engine, CREATE_TABLE_SQL["postgres"])
+      end
+
+      # Create the session table once, on first use rather than at construction.
+      # The flag is set BEFORE the DDL so an unreachable database is not
+      # re-probed on every call - the same ordering the Python master uses for
+      # _table_ready.
+      #
+      # THE CONCURRENT FIRST-USE RACE. Two workers booting together both reach
+      # this line and both issue the CREATE; one of them loses. IF NOT EXISTS
+      # settles that ENGINE-SIDE on sqlite, postgres and mysql, but T-SQL has no
+      # such clause and Firebird has none either, so on those two the loser
+      # raises and would take down the subsystem that decides whether anyone is
+      # logged in.
+      #
+      # The rescue below is the guard, ported from PHP. It RE-CHECKS whether the
+      # table exists rather than parsing the error message, because every engine
+      # spells "already exists" differently ("There is already an object named",
+      # "already exists", SQLSTATE 42S01) and a string match would rot the first
+      # time an engine reworded itself or ran under another locale.
       def ensure_table
-        @db.execute(CREATE_TABLE_SQL)
+        return if @table_ready
+
+        @table_ready = true
+        begin
+          db.execute(create_table_sql)
+        rescue StandardError
+          # A failed statement leaves PostgreSQL's transaction ABORTED, so
+          # without this the re-check would fail for the wrong reason and report
+          # a missing table that is right there. Best effort: an engine with no
+          # open transaction is entitled to object to being rolled back.
+          begin
+            db.rollback
+          rescue StandardError
+            nil
+          end
+          # Somebody else created it - that is the race, and it is a success.
+          # Anything else is a real failure and is re-raised untouched.
+          raise unless db.table_exists?(TABLE_NAME)
+        end
       end
     end
   end