tina4ruby 3.13.141 → 3.13.143

data/lib/tina4/queue_backends/republish_retry_policy.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+module Tina4
+  module QueueBackends
+    # The at-least-once fail policy (ADR-0022) shared by the broker backends
+    # whose protocol carries no delivery counter (kafka, rabbitmq). A Kafka
+    # record and an AMQP body are both immutable, so recording a failed attempt
+    # means RE-PUBLISHING a body that carries the incremented count rather than
+    # mutating the message in place.
+    #
+    # Increment attempts, record the error, dead-letter at the retry limit else
+    # re-enqueue, then ack LAST -- so a crash between the re-publish and the ack
+    # redelivers the job rather than losing it, which is the contract.
+    #
+    # The host backend must define +enqueue+, +dead_letter+, +complete+ (its
+    # terminal ack) and an +@max_retries+.
+    module RepublishRetryPolicy
+      def fail(job, error = "")
+        job.attempts += 1
+        job.error = error
+        if job.attempts >= @max_retries
+          dead_letter(job)
+        else
+          enqueue(job)
+        end
+        complete(job)
+      end
+    end
+  end
+end

data/lib/tina4/rack_app.rb

@@ -103,6 +103,11 @@ module Tina4
       # on the response whatever outcome the pipeline produced (200/404/500/413).
       request_id = Tina4::Log.sanitize_request_id(env["HTTP_X_REQUEST_ID"]) || SecureRandom.hex(4)
       Tina4::Log.set_request_id(request_id)
+      # One CSP nonce per request, published on the thread-local (ADR-0088) so the
+      # inline HTML body and the security middleware's CSP header name the SAME
+      # value. Cleared in `ensure`, exactly like the request id (an overlapping
+      # request on another thread never shares it).
+      Tina4::Csp.set_current_nonce(Tina4::Csp.generate_nonce)
 
       begin
         result = dispatch_pipeline(env)
@@ -112,8 +117,10 @@ module Tina4
         # The request pipeline installs the id before its first log and
         # clears it in `finally`/`ensure` after its last (Decision 12 /
         # LOG-Q03), so an overlapping request on another thread can never
-        # observe a stale id from a request that already finished.
+        # observe a stale id from a request that already finished. The CSP
+        # nonce has the same lifetime.
         Tina4::Log.clear_request_id
+        Tina4::Csp.clear_current_nonce
       end
     end
 
@@ -374,6 +381,10 @@ module Tina4
       # zero-dependency — no vendored ~1.4MB swagger-ui-dist). Air-gapped
       # deployments point TINA4_SWAGGER_UI_CDN at a self-hosted mirror.
       cdn = (ENV["TINA4_SWAGGER_UI_CDN"] || "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5").sub(%r{/+\z}, "")
+      # ADR-0088: nonce the inline bootstrap <script> so it runs under the strict
+      # default CSP. The external <script src>/<link> need none ('self' allows
+      # same-origin; a CDN still needs TINA4_CSP to list its host).
+      nonce = Tina4::Csp.current_nonce
       html = <<~HTML
         <!DOCTYPE html>
         <html lang="en">
@@ -385,7 +396,7 @@ module Tina4
         <body>
           <div id="swagger-ui"></div>
           <script src="#{cdn}/swagger-ui-bundle.js"></script>
-          <script>
+          <script nonce="#{nonce}">
             SwaggerUIBundle({ url: '/swagger/openapi.json', dom_id: '#swagger-ui' });
           </script>
         </body>
@@ -554,6 +565,12 @@ module Tina4
 
     def render_landing_page
       port = ENV["PORT"] || "7145"
+      # One CSP nonce for this response (ADR-0088): the <style>/<script> below
+      # carry it, and the security middleware names the SAME value in the CSP
+      # header. No inline style=/onclick= — a nonce covers a <style>/<script>
+      # ELEMENT but never a style or event-handler ATTRIBUTE, so every style
+      # lives in a class and every handler is bound with addEventListener.
+      nonce = Tina4::Csp.current_nonce
 
       # Check deployed state for each gallery item
       project_src = File.join(@root_dir, "src")
@@ -569,13 +586,13 @@ module Tina4
 
       gallery_cards = gallery_items.map do |item|
         deployed = File.file?(File.join(project_src, item[:file_check]))
-        deployed_badge = deployed ? '<span style="position:absolute;top:0.75rem;right:0.75rem;background:#22c55e;color:#fff;font-size:0.65rem;padding:0.15rem 0.5rem;border-radius:0.25rem;font-weight:600;">DEPLOYED</span>' : ''
+        deployed_badge = deployed ? '<span class="deployed-badge">DEPLOYED</span>' : ''
         try_btn = if deployed
                     %(<a href="#{item[:try_url]}" class="gbtn gbtn-try" target="_blank">Try It</a>)
                   else
-                    %(<button class="gbtn gbtn-deploy" onclick="deployGallery('#{item[:id]}','#{item[:try_url]}')">Deploy &amp; Try</button>)
+                    %(<button class="gbtn gbtn-deploy" data-gallery-deploy data-id="#{item[:id]}" data-try-url="#{item[:try_url]}">Deploy &amp; Try</button>)
                   end
-        view_btn = %(<button class="gbtn gbtn-view" onclick="viewGallery('#{item[:id]}')">View</button>)
+        view_btn = %(<button class="gbtn gbtn-view" data-gallery-view data-id="#{item[:id]}">View</button>)
 
         <<~CARD
           <div class="gallery-card">
@@ -584,7 +601,7 @@ module Tina4
               <div class="icon">#{item[:icon]}</div>
               <h3>#{item[:name]}</h3>
               <p>#{item[:desc]}</p>
-              <div style="display:flex;gap:0.5rem;margin-top:0.75rem;">#{try_btn}#{view_btn}</div>
+              <div class="gallery-card-actions">#{try_btn}#{view_btn}</div>
           </div>
         CARD
       end.join
@@ -596,7 +613,7 @@ module Tina4
         <meta charset="utf-8">
         <meta name="viewport" content="width=device-width, initial-scale=1">
         <title>Tina4Ruby</title>
-        <style>
+        <style nonce="#{nonce}">
         *{margin:0;padding:0;box-sizing:border-box}
         body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;background:#0f172a;color:#e2e8f0;min-height:100vh;display:flex;flex-direction:column;align-items:center;position:relative}
         .bg-watermark{position:fixed;bottom:-5%;right:-5%;width:45%;opacity:0.04;pointer-events:none;z-index:0}
@@ -638,6 +655,21 @@ module Tina4
         .view-modal-close:hover{color:#e2e8f0}
         @keyframes wiggle{0%{transform:rotate(0deg)}15%{transform:rotate(14deg)}30%{transform:rotate(-10deg)}45%{transform:rotate(8deg)}60%{transform:rotate(-4deg)}75%{transform:rotate(2deg)}100%{transform:rotate(0deg)}}
         .star-wiggle{display:inline-block;transform-origin:center}
+        .tagline-sub{font-size:0.95rem;margin-top:-1rem}
+        .deployed-badge{position:absolute;top:0.75rem;right:0.75rem;background:#22c55e;color:#fff;font-size:0.65rem;padding:0.15rem 0.5rem;border-radius:0.25rem;font-weight:600}
+        .gallery-card-actions{display:flex;gap:0.5rem;margin-top:0.75rem}
+        .gallery-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(280px,1fr));gap:1rem}
+        .view-modal-title{margin-bottom:1rem;color:#e2e8f0}
+        .vm-intro{color:#94a3b8;margin-bottom:1rem}
+        .vm-file-list{list-style:none;padding:0}
+        .vm-file{padding:0.25rem 0;color:#4ade80;font-family:monospace;font-size:0.85rem}
+        .vm-tryurl{color:#94a3b8;margin-top:1rem}
+        .vm-code{color:#38bdf8}
+        .tok-comment{color:#64748b}
+        .tok-kw{color:#c084fc}
+        .tok-str{color:#4ade80}
+        .tok-fn{color:#38bdf8}
+        .tok-dec{color:#fbbf24}
         </style>
         </head>
         <body>
@@ -646,7 +678,7 @@ module Tina4
             <img src="/images/tina4-logo-icon.webp" class="logo" alt="Tina4">
             <h1>Tina4Ruby</h1>
             <p class="tagline">The Intelligent Native Application 4ramework</p>
-            <p class="tagline" style="font-size:0.95rem;margin-top:-1rem">Simple. Fast. Human. &nbsp;|&nbsp; Built for AI. Built for you.</p>
+            <p class="tagline tagline-sub">Simple. Fast. Human. &nbsp;|&nbsp; Built for AI. Built for you.</p>
             <div class="actions">
                 <a href="https://tina4.com/ruby" class="btn" target="_blank">Website</a>
                 <a href="/__dev" class="btn">Dev Admin</a>
@@ -664,33 +696,32 @@ module Tina4
         <div class="section">
             <div class="card">
                 <h2>Getting Started</h2>
-                <pre class="code-block"><code><span style="color:#64748b"># app.rb</span>
-        <span style="color:#c084fc">require</span> <span style="color:#4ade80">"tina4"</span>
+                <pre class="code-block"><code><span class="tok-comment"># app.rb</span>
+        <span class="tok-kw">require</span> <span class="tok-str">"tina4"</span>
 
-        Tina4::Router.<span style="color:#38bdf8">get</span>(<span style="color:#4ade80">"/hello"</span>) <span style="color:#c084fc">do</span> |request, response|
-          response.<span style="color:#38bdf8">json</span>({ <span style="color:#fbbf24">message:</span> <span style="color:#4ade80">"Hello World!"</span> })
-        <span style="color:#c084fc">end</span>
+        Tina4::Router.<span class="tok-fn">get</span>(<span class="tok-str">"/hello"</span>) <span class="tok-kw">do</span> |request, response|
+          response.<span class="tok-fn">json</span>({ <span class="tok-dec">message:</span> <span class="tok-str">"Hello World!"</span> })
+        <span class="tok-kw">end</span>
 
-        Tina4::WebServer.new(<span style="color:#fbbf24">port:</span> <span style="color:#38bdf8">7145</span>).start  <span style="color:#64748b"># starts on port 7145</span></code></pre>
+        Tina4::WebServer.new(<span class="tok-dec">port:</span> <span class="tok-fn">7145</span>).start  <span class="tok-comment"># starts on port 7145</span></code></pre>
             </div>
         </div>
         <div class="gallery">
             <h2 id="gallery">Gallery</h2>
-            <div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(280px,1fr));gap:1rem;">
+            <div class="gallery-grid">
                 #{gallery_cards}
             </div>
         </div>
         <div class="view-modal" id="viewModal">
             <div class="view-modal-content">
-                <button class="view-modal-close" onclick="document.getElementById('viewModal').classList.remove('active')">&times;</button>
-                <h3 id="viewModalTitle" style="margin-bottom:1rem;color:#e2e8f0;"></h3>
+                <button class="view-modal-close" data-modal-close>&times;</button>
+                <h3 id="viewModalTitle" class="view-modal-title"></h3>
                 <div id="viewModalBody"></div>
             </div>
         </div>
-        <script>
-        function deployGallery(name, tryUrl) {
+        <script nonce="#{nonce}">
+        function deployGallery(btn, name, tryUrl) {
             if (!confirm('Deploy the "' + name + '" gallery example into your project?')) return;
-            var btn = event.target;
             btn.disabled = true;
             btn.textContent = 'Deploying...';
             fetch('/__dev/api/gallery/deploy', {
@@ -733,18 +764,34 @@ module Tina4
                 var title = document.getElementById('viewModalTitle');
                 var body = document.getElementById('viewModalBody');
                 title.textContent = item.name + ' — ' + item.description;
-                var html = '<p style="color:#94a3b8;margin-bottom:1rem;">Files that will be deployed:</p><ul style="list-style:none;padding:0;">';
+                var html = '<p class="vm-intro">Files that will be deployed:</p><ul class="vm-file-list">';
                 (item.files || []).forEach(function(f) {
-                    html += '<li style="padding:0.25rem 0;color:#4ade80;font-family:monospace;font-size:0.85rem;">src/' + f + '</li>';
+                    html += '<li class="vm-file">src/' + f + '</li>';
                 });
                 html += '</ul>';
                 if (item.try_url) {
-                    html += '<p style="color:#94a3b8;margin-top:1rem;">Try URL: <code style="color:#38bdf8;">' + item.try_url + '</code></p>';
+                    html += '<p class="vm-tryurl">Try URL: <code class="vm-code">' + item.try_url + '</code></p>';
                 }
                 body.innerHTML = html;
                 document.getElementById('viewModal').classList.add('active');
             });
         }
+        // CSP-clean wiring: no inline onclick handlers — bind every gallery
+        // button from its data-* attributes (a nonce covers script elements, not
+        // event-handler attributes).
+        document.querySelectorAll('[data-gallery-deploy]').forEach(function(btn){
+            btn.addEventListener('click', function(){
+                deployGallery(btn, btn.dataset.id, btn.dataset.tryUrl);
+            });
+        });
+        document.querySelectorAll('[data-gallery-view]').forEach(function(btn){
+            btn.addEventListener('click', function(){ viewGallery(btn.dataset.id); });
+        });
+        document.querySelectorAll('[data-modal-close]').forEach(function(btn){
+            btn.addEventListener('click', function(){
+                document.getElementById('viewModal').classList.remove('active');
+            });
+        });
         document.getElementById('viewModal').addEventListener('click', function(e) {
             if (e.target === this) this.classList.remove('active');
         });

data/lib/tina4/response.rb

@@ -63,7 +63,7 @@ module Tina4
     TEXT_CONTENT_TYPE = "text/plain; charset=utf-8"
     XML_CONTENT_TYPE  = "application/xml; charset=utf-8"
 
-    attr_accessor :status_code, :headers, :body, :cookies
+    attr_accessor :status_code, :headers, :body, :cookies, :csp_nonce
 
     # ADR-0068: a header name must be an RFC 9110 token, and a header value,
     # redirect location or cookie attribute may never carry CR, LF or NUL (a
@@ -89,6 +89,11 @@ module Tina4
       @body = ""
       @cookies = nil  # Lazy -- most responses have no cookies
       @content_type_from_header = false
+      # Per-response CSP nonce (ADR-0088). RackApp#call mints one per request on
+      # the thread-local, so every Response built during that request reads the
+      # SAME value the security middleware names in the Content-Security-Policy
+      # header and the framework's inline <style>/<script> stamp on themselves.
+      @csp_nonce = Tina4::Csp.current_nonce
     end
 
     # Chainable status setter

data/lib/tina4/session.rb

@@ -175,23 +175,72 @@ module Tina4
     def clear
       @data = {}
       @modified = true
+      @cleared = true
     end
 
     def to_hash
       @data.dup
     end
 
-    # 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.
+    # Persist this request's session. On a backend 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`.
+    # to persist, and a write would re-create the just-destroyed record.
+    #
+    # Another request may have changed or ended this session since this one
+    # loaded it: a logout, a #regenerate, a set that took a privilege away.
+    # Writing back the whole snapshot loaded at the start undid all of those, so
+    # a request in flight across a logout logged the user straight back in. The
+    # save therefore re-reads the stored record and writes only what THIS
+    # request changed onto it, and never re-creates a record another request
+    # removed: it ends the session for this request instead, so no cookie goes
+    # out for it.
+    #
+    # SLIDING EXPIRY (ADR-0087): a started session the store already holds is
+    # re-written on EVERY save, even when this request changed nothing. That
+    # write re-stamps the backend deadline to now + TINA4_SESSION_TTL, so expiry
+    # is measured from the last request that TOUCHED the session, not from its
+    # last change — a user actively reading pages stays logged in. The re-write
+    # is the SAME re-read, merged record the concurrent-save contract computes,
+    # so sliding never clobbers a concurrent change. PHP is the reference. The
+    # guards above take precedence over the slide: no id → nothing to slide;
+    # a record another request ended → forget + end, never re-created; a failed
+    # read → deadline untouched, dirty kept for a retry; TINA4_SESSION_TTL=0 →
+    # the slide re-stamps a zero (immortal) deadline (ADR-0027).
+    #
+    # The slide is scoped to @stored — an id the STORE actually holds (adopted,
+    # not freshly minted). ADR-0087's own guard: "a request with no session (no
+    # id issued, OR THE ID WAS NEVER ADOPTED) writes nothing — there is no
+    # deadline to move." A brand-new, unmodified session (minted id, @stored
+    # false) therefore still no-ops, exactly as before; a modified session of
+    # any kind still writes.
     def save
-      return true unless @id && @modified
-      if safe_write(@id, @data, @ttl)
+      return true unless @id && (@modified || @stored)
+
+      record = @data
+      if @stored
+        current, failed = current_record
+        # Whether the record still exists is unknown, so nothing is written;
+        # the dirty flag is kept for a later retry.
+        return false if failed
+
+        if current.nil?
+          forget
+          @ended = true
+          return true
+        end
+        record = merged(current) unless @cleared
+      end
+      if safe_write(@id, record, @ttl)
         @modified = false
+        # An empty record is no session (#start never adopts one), so the next
+        # save writes whole rather than take this request's own empty write for
+        # a logout.
+        @stored = !record.empty?
+        @cleared = false
+        @loaded = fingerprints(@data)
         true
       else
         false # dirty flag retained for retry
@@ -205,9 +254,7 @@ module Tina4
     # (nulls sessionId). A fresh session needs a new #start, which mints a new id.
     def destroy
       safe_destroy(@id) if @id
-      @id = nil
-      @data = {}
-      @modified = false
+      forget
     end
 
     # Get a session value with optional default.
@@ -272,11 +319,32 @@ module Tina4
     # session fixation (a pre-auth session ID must not survive into the
     # authenticated session). Destroys the old backend record (best-effort)
     # and persists under the new ID.
+    #
+    # What is carried is the session as it is stored now with this request's
+    # own changes applied, the same merge #save does. If another request ended
+    # the session after this one loaded it (a logout, or a regenerate of its
+    # own), it stays ended: nothing is carried, no id is minted and nil is
+    # returned, so no cookie goes out to replace the one that request sent.
     def regenerate
+      return nil if @ended
+
       old_id = @id
+      if old_id && @stored
+        current, failed = current_record
+        unless failed
+          if current.nil?
+            forget
+            @ended = true
+            return nil
+          end
+          @data.replace(merged(current)) unless @cleared
+        end
+      end
       @id = SecureRandom.hex(32)
       safe_destroy(old_id)
       @modified = true
+      # Nothing is stored under the new id yet, so the save writes it whole.
+      @stored = false
       save
       @id
     end
@@ -383,9 +451,76 @@ module Tina4
       @id = session_id
       @data = data
       @modified = false
+      # @stored: this request is working on a record the store holds, so a save
+      # must never re-create it once it has gone. An empty record does not
+      # count: it is no session. A failed read adopts the id with {}
+      # (#existing_session_data): not a record this request has seen, so its
+      # first save writes whole.
+      @stored = !data.empty?
+      # @loaded: one fingerprint per key of what this request last saw stored;
+      # #save compares the live data against it to find what THIS request
+      # changed. @cleared: #clear ran since the last save, so the save replaces
+      # the stored record instead of merging into it.
+      @loaded = @stored ? fingerprints(@data) : {}
+      @cleared = false
+      # @ended: this request found its session ended by another request (the
+      # record it loaded is gone). It stays ended for the rest of the request:
+      # #regenerate mints nothing either.
+      @ended = false
       @id
     end
 
+    # Forget the session in memory: no data, no id, nothing left to save. What
+    # #destroy does after removing the record, and what #save does when it
+    # finds another request already removed it.
+    def forget
+      @id = nil
+      @data = {}
+      @modified = false
+      @stored = false
+      @cleared = false
+      @loaded = {}
+    end
+
+    # The record as stored right now, as [data, failed]. nil and empty both mean
+    # "no session", exactly as in #existing_session_data.
+    def current_record
+      return [nil, true] if degraded?
+
+      data = @handler.read(@id)
+      [data.nil? || (data.respond_to?(:empty?) && data.empty?) ? nil : data, false]
+    rescue StandardError => e
+      log_backend_error("read", e)
+      raise if @strict
+      [nil, true]
+    end
+
+    # The stored record with only this request's own changes applied to it: the
+    # keys it set or changed since it last loaded or saved, minus the keys it
+    # removed. Every other key keeps the value the store holds now.
+    def merged(current)
+      record = current.dup
+      @data.each do |key, value|
+        now = fingerprint(value)
+        record[key] = value if now.nil? || @loaded[key] != now
+      end
+      @loaded.each_key { |key| record.delete(key) unless @data.key?(key) }
+      record
+    end
+
+    def fingerprints(data)
+      data.each_with_object({}) { |(key, value), prints| prints[key] = fingerprint(value) }
+    end
+
+    # The stored form of a value, for telling whether a request changed it.
+    # nil when it cannot be serialised: that always counts as changed, because
+    # writing a value again is harmless and missing a change is not.
+    def fingerprint(value)
+      JSON.generate(value)
+    rescue StandardError
+      nil
+    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.

data/lib/tina4/session_handlers/redis_handler.rb

@@ -7,6 +7,7 @@
 
 require "json"
 require_relative "resp_client"
+require_relative "resp_session_handler"
 
 module Tina4
   module SessionHandlers
@@ -16,7 +17,13 @@ module Tina4
     # 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.
+    #
+    # read/write/destroy/cleanup and the gem-client build come from
+    # RespSessionHandler (shared byte-for-byte with ValkeyHandler); only the
+    # env-var namespace below differs.
     class RedisHandler
+      include RespSessionHandler
+
       # Connection is configured from TINA4_SESSION_REDIS_* env vars (parity with
       # Python's RedisSessionHandler and the Ruby ValkeyHandler shape) so
       # TINA4_SESSION_BACKEND=redis can actually be pointed at a server by env.
@@ -33,57 +40,6 @@ module Tina4
         @redis = build_gem_client
         @resp = @redis ? nil : RespClient.new(host: @host, port: @port, password: @password, db: @db)
       end
-
-      def read(session_id)
-        key = "#{@prefix}#{session_id}"
-        data = @redis ? @redis.get(key) : @resp.get(key)
-        return nil unless data
-        JSON.parse(data)
-      rescue JSON::ParserError
-        nil
-      end
-
-      # 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, effective_ttl, payload)
-        else
-          @resp.setex(key, effective_ttl, payload)
-        end
-      end
-
-      def destroy(session_id)
-        key = "#{@prefix}#{session_id}"
-        @redis ? @redis.del(key) : @resp.del(key)
-      end
-
-      def cleanup
-        # Redis handles TTL automatically
-      end
-
-      private
-
-      # Use the official `redis` gem only when the REAL gem is loadable (guard
-      # against an in-test fake `Redis` constant that has no VERSION). Returns nil
-      # when the gem is absent so the caller falls back to the raw RESP client.
-      def build_gem_client
-        require "redis"
-        return nil unless defined?(::Redis::VERSION)
-        Redis.new(host: @host, port: @port, db: @db, password: @password)
-      rescue LoadError
-        nil
-      end
     end
   end
 end

data/lib/tina4/session_handlers/resp_session_handler.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+require "json"
+
+module Tina4
+  module SessionHandlers
+    # Shared RESP-protocol session storage. Redis and Valkey speak the same RESP
+    # wire protocol, so reading, writing, destroying and cleaning up a session --
+    # and building the optional `redis`-gem client -- are byte-identical between
+    # them. Only the env-var namespace differs (TINA4_SESSION_REDIS_* vs
+    # TINA4_SESSION_VALKEY_*), which each handler sets in its own initialize.
+    #
+    # A handler includes this and, in initialize, sets @prefix, @ttl, @host,
+    # @port, @db, @password, @redis (the gem client or nil) and @resp (the raw
+    # RespClient fallback, used when @redis is nil).
+    module RespSessionHandler
+      def read(session_id)
+        key = "#{@prefix}#{session_id}"
+        data = @redis ? @redis.get(key) : @resp.get(key)
+        return nil unless data
+        JSON.parse(data)
+      rescue JSON::ParserError
+        nil
+      end
+
+      # 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, effective_ttl, payload)
+        else
+          @resp.setex(key, effective_ttl, payload)
+        end
+      end
+
+      def destroy(session_id)
+        key = "#{@prefix}#{session_id}"
+        @redis ? @redis.del(key) : @resp.del(key)
+      end
+
+      def cleanup
+        # Redis/Valkey expire keys by TTL automatically -- nothing to sweep.
+      end
+
+      private
+
+      # Use the official `redis` gem (RESP-compatible with both Redis and
+      # Valkey) only when the REAL gem is loadable (guard against an in-test fake
+      # `Redis` constant that has no VERSION). Returns nil when the gem is absent
+      # so the caller falls back to the raw RESP client.
+      def build_gem_client
+        require "redis"
+        return nil unless defined?(::Redis::VERSION)
+        Redis.new(host: @host, port: @port, db: @db, password: @password)
+      rescue LoadError
+        nil
+      end
+    end
+  end
+end