tina4ruby 3.13.140 → 3.13.142

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68bda3e81c456588a9a4db6501cb402b1eaa570d5f2bfbee0efb83bd9cb61beb
-  data.tar.gz: 61271a97c34bf49f68fcaf605d955d6e4f932f72fa370c884f4f0e91ef432e91
+  metadata.gz: 7e0e60af31fb00e8d35480634176d6bf978963f0d2e0609ebc9468204d8852d0
+  data.tar.gz: c34fbf17ba63d2295c13071cdc82cf1eca291bd7fafa4a1e8d6510083bd95ba1
 SHA512:
-  metadata.gz: 847b4f0439265406da7152292469d91b081a04e468f177b78980c9b669c96e60cca17ac06820bbdb5c66034802145ff64b294c7949136e2392236575170aeb3e
-  data.tar.gz: f690d2726ce41de740e44b6db7cc0cd3104ac40cace6c30dc5a4a94eef832f7e09128608b9cfaebf6e167687403917ca14c156d5f4b94bd65b8c46930d191bce
+  metadata.gz: 4a290825e4873802ac5311a665c67d19fcb618d77048299601f4bb6d9368a389cb093ce1039eaf7b071f30f1b7f0d7d3d2e297617947198ad9e81912909acb23
+  data.tar.gz: 287309debcce829752205d6bafedd17e2849b20726c27e151e69503e31a7656bfb420511946512e6f12b11953ec68e4ed01a1628dbf173d1ad9cdee605e1e49e

data/CHANGELOG.md

@@ -6,6 +6,31 @@ number means the same thing everywhere.
 **The authoritative release notes for every shipped version live in the documentation:**
 https://tina4.com/ruby/36-releases
 
+## 3.13.142 — 2026-09-30
+
+A release led by real fixes for anyone on WebSockets, sessions, or the gallery queue, then a round of internal tidying and a new metrics gate that holds the line on complexity. The framework still carries no required runtime dependencies.
+
+### Fixes
+- WebSocket now delivers a fragmented message whole. A client that splits a payload across continuation frames (RFC 6455 §5.4) used to have each fragment handed over on its own, so the handler saw pieces instead of the message. The frames are reassembled and delivered once, complete (#87).
+- `session.regenerate` mid-request re-emits the session cookie, so a login that rotates the id keeps the browser in step instead of dropping it on the next request. Parity with the same fix in the php framework (tina4-php#253) (#90).
+- The gallery queue reads a bounded batch instead of draining without limit, and the NATS backplane keeper stops busy-polling and blocks for work instead. Less wheel-spinning, the same behaviour (#89).
+- A flaky serve-debug spec now polls `/__dev` for real readiness and retries a transient boot, so the suite stops tripping over its own startup timing (#91).
+
+### Refactors
+- Cyclomatic complexity comes down across the flagged modules, and all six cross-file duplicate blocks in `lib/tina4` are gone, each one characterised first so the behaviour cannot shift (#86, #88).
+
+### Chore
+- `TINA4_TEST_NATS_URL` joins the canonical test-env set (ADR-0038), so the NATS URL is named the same way everywhere.
+- The nats-pure dependency and its transitive gems were licence-reviewed, unblocking the release-package workflow.
+- CI wires the `tina4 metrics --fail-on-regression` ratchet gate with a committed baseline (ADR-0002), so a new complexity offender fails the build instead of drifting in unseen (#92).
+
+## 3.13.141 — 2026-09-29
+
+A hardening release. The sibling php framework shipped committed absolute symlinks that broke `composer install` on Windows, so every framework now refuses a committed symlink up front. Ruby carries no such link today, so this guard is preventive parity: it keeps the door shut before anything can wander in. The framework still carries no required runtime dependencies.
+
+### Security
+- A new `scripts/check-no-symlinks.sh` gate refuses any committed symlink (git mode 120000). A committed symlink breaks Windows and Composer extraction and is a supply-chain risk. The gate runs first in the test workflow, and a real RSpec spec proves it by mutation — it stages a symlink in a throwaway git repo, watches the guard go red, then removes it and watches it go green.
+
 ## 3.13.140 — 2026-09-28
 
 A housekeeping release that tightens the guards and dedups the SQLite plumbing. The CLAUDE.md doc-drift gate now watches this repo, so a doc that names a Tina4 method the code no longer has fails loudly instead of drifting on quietly. The SQLite path resolver learnt some manners: an escaping relative path is refused, and it creates the parent folders itself at 0775 (ADR-0086). The framework still carries no required runtime dependencies.

data/lib/tina4/crud.rb

@@ -407,14 +407,12 @@ module Tina4
         }
       end
 
-      # Escape HTML special characters
+      # Escape HTML special characters. Delegates to the framework's one
+      # canonical escaper (Frond.escape_html, single-pass, byte-identical
+      # & < > " ' -> &amp; &lt; &gt; &quot; &#39;) so CRUD and the error
+      # overlay never carry their own private copy of the HTML escape table.
       def h(text)
-        text.to_s
-          .gsub("&", "&amp;")
-          .gsub("<", "&lt;")
-          .gsub(">", "&gt;")
-          .gsub('"', "&quot;")
-          .gsub("'", "&#39;")
+        Tina4::Frond.escape_html(text)
       end
 
       # Pretty label from a column name: "user_name" => "User Name"

data/lib/tina4/error_overlay.rb

@@ -169,13 +169,11 @@ module Tina4
         key.to_s.match?(SENSITIVE_KEY_RE) ? REDACTED : value
       end
 
+      # Delegates to the framework's one canonical escaper (Frond.escape_html,
+      # single-pass, byte-identical & < > " ' -> &amp; &lt; &gt; &quot; &#39;)
+      # rather than keeping a private copy of the escape table here.
       def esc(text)
-        text.to_s
-            .gsub("&", "&amp;")
-            .gsub("<", "&lt;")
-            .gsub(">", "&gt;")
-            .gsub('"', "&quot;")
-            .gsub("'", "&#39;")
+        Tina4::Frond.escape_html(text)
       end
 
       def parse_backtrace_line(line)

data/lib/tina4/gallery/queue/src/routes/api/gallery_queue.rb

@@ -39,6 +39,13 @@ end
 
 GALLERY_QUEUE_MAX_RETRIES = 3
 
+# The next message to consume or fail: the highest-priority pending one whose
+# delay has passed. LIMIT 1 keeps the database from sorting and returning every
+# pending row when the demo only ever wants the first (Carbonah E003).
+GALLERY_QUEUE_NEXT_PENDING_SQL =
+  "SELECT * FROM tina4_queue WHERE topic = ? AND status = 'pending' " \
+  "AND available_at <= ? ORDER BY priority DESC, id ASC LIMIT 1"
+
 GALLERY_QUEUE_HTML = <<~'HTML'
 <!DOCTYPE html>
 <html lang="en">
@@ -273,7 +280,7 @@ Tina4::Router.post("/api/gallery/queue/consume") do |request, response|
   now = _gallery_queue_now
 
   row = db.fetch_one(
-    "SELECT * FROM tina4_queue WHERE topic = ? AND status = 'pending' AND available_at <= ? ORDER BY priority DESC, id ASC",
+    GALLERY_QUEUE_NEXT_PENDING_SQL,
     ["gallery-tasks", now]
   )
 
@@ -295,7 +302,7 @@ Tina4::Router.post("/api/gallery/queue/fail") do |request, response|
   now = _gallery_queue_now
 
   row = db.fetch_one(
-    "SELECT * FROM tina4_queue WHERE topic = ? AND status = 'pending' AND available_at <= ? ORDER BY priority DESC, id ASC",
+    GALLERY_QUEUE_NEXT_PENDING_SQL,
     ["gallery-tasks", now]
   )
 

data/lib/tina4/job.rb

@@ -13,6 +13,23 @@ module Tina4
     attr_reader :id, :topic, :payload, :created_at, :priority, :available_at
     attr_accessor :status, :attempts, :error, :queue
 
+    # Rebuild a Job from a parsed queue payload (a Hash with string keys, as
+    # produced by #to_json and read back off the wire). attempts and error MUST
+    # ride along: rebuilding from topic/payload/id alone reset attempts to 0 on
+    # every redelivery, so fail()'s attempts >= max_retries check could never
+    # trip and a poison job would be retried forever instead of dead-lettering.
+    # Shared by the broker backends (kafka, rabbitmq) whose wire format is this
+    # JSON.
+    def self.from_payload(data)
+      new(
+        topic: data["topic"],
+        payload: data["payload"],
+        id: data["id"],
+        attempts: data["attempts"] || 0,
+        error: data["error"]
+      )
+    end
+
     def initialize(topic:, payload:, id: nil, priority: 0, available_at: nil,
                    attempts: 0, created_at: nil, error: nil, queue: nil)
       @id = id || SecureRandom.uuid

data/lib/tina4/migration.rb

@@ -492,56 +492,23 @@ module Tina4
 
         # Block comment /* … */ — stripped.
         if ch == "/" && i + 1 < n && sql[i + 1] == "*"
-          endpos = sql.index("*/", i + 2)
-          i = endpos ? endpos + 2 : n
+          i = skip_block_comment(sql, i, n)
           next
         end
 
         # Line comment -- … — stripped to end of line; the newline is left for the
         # next iteration so line structure (and NEXT-line boundaries) survive.
         if ch == "-" && i + 1 < n && sql[i + 1] == "-"
-          endpos = sql.index("\n", i + 2)
-          i = endpos || n
+          i = skip_line_comment(sql, i, n)
           next
         end
 
-        # Single-quoted string literal — '' escapes a quote. Copied verbatim.
-        if ch == "'"
-          current << "'"
-          i += 1
-          while i < n
-            if sql[i] == "'" && i + 1 < n && sql[i + 1] == "'"
-              current << "''"
-              i += 2
-            elsif sql[i] == "'"
-              current << "'"
-              i += 1
-              break
-            else
-              current << sql[i]
-              i += 1
-            end
-          end
-          next
-        end
-
-        # Double-quoted identifier — "" escapes a quote. Same verbatim handling.
-        if ch == '"'
-          current << '"'
-          i += 1
-          while i < n
-            if sql[i] == '"' && i + 1 < n && sql[i + 1] == '"'
-              current << '""'
-              i += 2
-            elsif sql[i] == '"'
-              current << '"'
-              i += 1
-              break
-            else
-              current << sql[i]
-              i += 1
-            end
-          end
+        # '…' single-quoted string or "…" double-quoted identifier — copied
+        # verbatim, honouring the SQL doubled-quote escape ('' / ""). A ;, -- or
+        # /* inside a literal is data, not a delimiter or comment.
+        if ch == "'" || ch == '"'
+          literal, i = read_quoted_literal(sql, i, ch)
+          current << literal
           next
         end
 
@@ -592,6 +559,47 @@ module Tina4
       m && m[1]
     end
 
+    # Skip a /* … */ block comment that opens at +start_index+. Returns the index
+    # just past the closing "*/", or +length+ when the comment is unterminated.
+    def skip_block_comment(sql, start_index, length)
+      endpos = sql.index("*/", start_index + 2)
+      endpos ? endpos + 2 : length
+    end
+
+    # Skip a -- … line comment that opens at +start_index+. Returns the index of
+    # the terminating newline (left for the next iteration so line structure
+    # survives), or +length+ when the comment runs to the end of the script.
+    def skip_line_comment(sql, start_index, length)
+      sql.index("\n", start_index + 2) || length
+    end
+
+    # Read a '…' string literal or "…" quoted identifier that opens at the
+    # +quote+ at +start_index+. A doubled quote ('' or "") is an escaped quote,
+    # not a terminator, so it is copied and scanning continues. An unterminated
+    # literal is read to the end of the script (matching the raw scan it replaces).
+    #
+    # @return [Array(String, Integer)] the verbatim literal (both quotes included)
+    #   and the index just past the closing quote.
+    def read_quoted_literal(sql, start_index, quote)
+      n = sql.length
+      literal = quote.dup
+      i = start_index + 1
+      while i < n
+        if sql[i] == quote && i + 1 < n && sql[i + 1] == quote
+          literal << quote << quote
+          i += 2
+        elsif sql[i] == quote
+          literal << quote
+          i += 1
+          break
+        else
+          literal << sql[i]
+          i += 1
+        end
+      end
+      [literal, i]
+    end
+
     def execute_sql_file(file)
       sql = File.read(file)
       statements = split_sql_statements(sql)

data/lib/tina4/queue_backends/kafka_backend.rb

@@ -7,10 +7,15 @@
 
 
 require_relative "../parse_json"
+require_relative "republish_retry_policy"
 
 module Tina4
   module QueueBackends
     class KafkaBackend
+      # Shared at-least-once fail() (ADR-0022): re-publish carrying the new
+      # attempt count, dead-letter at the limit, ack last. See RabbitmqBackend.
+      include RepublishRetryPolicy
+
       def initialize(options = {})
         require "rdkafka"
         @brokers = options[:brokers] || "localhost:9092"
@@ -131,17 +136,10 @@ module Tina4
         data = Tina4.parse_json(msg.payload)
         @last_message = msg
 
-        # attempts and error MUST be carried back. Rebuilding from
-        # topic/payload/id alone reset attempts to 0 on every redelivery, so
-        # fail()'s attempts >= max_retries check could never trip and a poison
-        # record would be re-produced forever instead of dead-lettering.
-        Tina4::Job.new(
-          topic: data["topic"],
-          payload: data["payload"],
-          id: data["id"],
-          attempts: data["attempts"] || 0,
-          error: data["error"]
-        )
+        # attempts and error MUST be carried back (Job.from_payload does this);
+        # rebuilding from topic/payload/id alone reset attempts to 0 on every
+        # redelivery, so a poison record would be re-produced forever.
+        Tina4::Job.from_payload(data)
       rescue Rdkafka::RdkafkaError
         nil
       end
@@ -186,26 +184,9 @@ module Tina4
         acknowledge(message)
       end
 
-      # Record a failed attempt, then retry it or dead-letter it.
-      #
-      # This did not exist. Job#fail guarded on respond_to?(:fail) and silently
-      # degraded to in-memory bookkeeping, so job.fail() NEVER reached Kafka:
-      # the offset was never committed and no dead letter was produced.
-      #
-      # A retry RE-PRODUCES a record carrying the new count, because a Kafka
-      # record is immutable and carries no delivery counter. The offset is
-      # committed LAST so a crash in between redelivers rather than loses -
-      # at-least-once, which is the contract.
-      def fail(job, error = "")
-        job.attempts += 1
-        job.error = error
-        if job.attempts >= @max_retries
-          dead_letter(job)
-        else
-          enqueue(job)
-        end
-        acknowledge(job)
-      end
+      # fail() comes from RepublishRetryPolicy (re-produce carrying the new
+      # count, dead-letter at the limit, commit the offset LAST). Kafka's
+      # +complete+ is +acknowledge+, so the terminal ack commits the offset.
 
       def retry(job, delay_seconds: 0)
         if delay_seconds.to_f > 0

data/lib/tina4/queue_backends/rabbitmq_backend.rb

@@ -7,10 +7,15 @@
 
 
 require_relative "../parse_json"
+require_relative "republish_retry_policy"
 
 module Tina4
   module QueueBackends
     class RabbitmqBackend
+      # Shared at-least-once fail() (ADR-0022): re-publish carrying the new
+      # attempt count, dead-letter at the limit, ack last. See KafkaBackend.
+      include RepublishRetryPolicy
+
       def initialize(options = {})
         require "bunny"
         @connection = Bunny.new(
@@ -71,17 +76,10 @@ module Tina4
         return nil unless payload
 
         data = Tina4.parse_json(payload)
-        # attempts and error MUST be carried back. Rebuilding the Job from
-        # topic/payload/id alone reset attempts to 0 on every redelivery, so
-        # fail()'s attempts >= max_retries check could never trip and a poison
-        # job would be retried forever instead of dead-lettering.
-        msg = Tina4::Job.new(
-          topic: data["topic"],
-          payload: data["payload"],
-          id: data["id"],
-          attempts: data["attempts"] || 0,
-          error: data["error"]
-        )
+        # attempts and error MUST be carried back (Job.from_payload does this);
+        # rebuilding from topic/payload/id alone reset attempts to 0 on every
+        # redelivery, so a poison job would be retried forever.
+        msg = Tina4::Job.from_payload(data)
         @last_delivery_tag = delivery_info.delivery_tag
         msg
       end
@@ -108,32 +106,12 @@ module Tina4
         dlq.publish(message.to_json, persistent: true)
       end
 
-      # Record a failed attempt, then retry it or dead-letter it.
-      #
-      # This did not exist. Job#fail guarded on respond_to?(:fail) and silently
-      # degraded to in-memory bookkeeping, so job.fail() NEVER reached the
-      # broker: the delivery stayed unacked, no dead letter was written, and
-      # both failed() and dead_letters() reported nothing. The job was lost as
-      # far as the application could see.
-      #
-      # AMQP basic.nack(requeue=true) returns the ORIGINAL body unmodified --
-      # the protocol carries no delivery counter -- so a retry RE-PUBLISHES a
-      # body carrying the new count instead. That is what every AMQP client
-      # that counts attempts does (Celery, Spring AMQP's
-      # RepublishMessageRecoverer, laravel-queue-rabbitmq).
-      def fail(job, error = "")
-        job.attempts += 1
-        job.error = error
-        if job.attempts >= @max_retries
-          dead_letter(job)
-        else
-          enqueue(job)
-        end
-        # Ack LAST: the re-publish (or dead-letter) is durable before the
-        # original leaves the queue, so a crash in between redelivers rather
-        # than loses. That is at-least-once, which is the contract.
-        complete(job)
-      end
+      # fail() comes from RepublishRetryPolicy. AMQP basic.nack(requeue=true)
+      # returns the ORIGINAL body unmodified -- the protocol carries no delivery
+      # counter -- so the shared policy RE-PUBLISHES a body carrying the new
+      # count, then complete() acks LAST. That is what every AMQP client that
+      # counts attempts does (Celery, Spring AMQP's RepublishMessageRecoverer,
+      # laravel-queue-rabbitmq).
 
       # Explicit re-queue requested by the caller (job.retry). Always
       # re-enqueues regardless of the retry limit -- a manual override,

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/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

data/lib/tina4/session_handlers/valkey_handler.rb

@@ -7,14 +7,19 @@
 
 require "json"
 require_relative "resp_client"
+require_relative "resp_session_handler"
 
 module Tina4
   module SessionHandlers
     # Valkey-backed session handler. Valkey speaks the RESP protocol, so it works
     # through the `redis` gem when installed (parity with Python/Node); otherwise
     # it speaks raw RESP over a TCP socket via RespClient — zero dependencies.
-    # Same as RedisHandler but reads VALKEY-prefixed configuration variables.
+    # Same behaviour as RedisHandler (read/write/destroy/cleanup and the
+    # gem-client build come from the shared RespSessionHandler) but reads
+    # VALKEY-prefixed configuration variables.
     class ValkeyHandler
+      include RespSessionHandler
+
       def initialize(options = {})
         @prefix = options[:prefix] || ENV["TINA4_SESSION_VALKEY_PREFIX"] || "tina4:session:"
         # TINA4_SESSION_VALKEY_TTL stays as the valkey-specific override, but it
@@ -29,56 +34,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
-        # Valkey handles TTL automatically (same as Redis)
-      end
-
-      private
-
-      # Use the official `redis` gem (RESP-compatible with Valkey) only when the
-      # REAL gem is loadable; otherwise nil so the caller falls back to raw RESP.
-      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/version.rb

@@ -7,5 +7,5 @@
 
 
 module Tina4
-  VERSION = "3.13.140"
+  VERSION = "3.13.142"
 end

data/lib/tina4/websocket.rb

@@ -691,6 +691,11 @@ module Tina4
 
       Thread.new do
         begin
+          # A large message (a pasted image in a chat, base64 inside JSON) arrives as a first frame with FIN clear,
+          # then CONTINUATION frames (RFC 6455 section 5.4); control frames may come in between. The first piece used
+          # to be emitted as the whole message and the rest ignored. Same design as the Python master (_handle_frame).
+          fragments = nil
+          fragment_opcode = nil
           loop do
             frame = connection.read_frame
             break unless frame
@@ -698,8 +703,26 @@ module Tina4
             connection.touch # mark activity for the idle reaper
 
             case frame[:opcode]
+            when 0x0 # Continuation - a stray one (no message started) is dropped
+              next unless fragments
+              fragments << frame[:data]
+              if frame[:fin]
+                emit(:message, connection, fragments) if fragment_opcode == 0x1
+                fragments = nil
+                fragment_opcode = nil
+              end
             when 0x1 # Text
-              emit(:message, connection, frame[:data])
+              if frame[:fin]
+                emit(:message, connection, frame[:data])
+              else
+                fragments = frame[:data].dup
+                fragment_opcode = 0x1
+              end
+            when 0x2 # Binary - not delivered (as before), but its pieces are one message, never text
+              unless frame[:fin]
+                fragments = frame[:data].dup
+                fragment_opcode = 0x2
+              end
             when 0x8 # Close
               break
             when 0x9 # Ping
@@ -867,6 +890,7 @@ module Tina4
       first_byte = @socket.getbyte
       return nil unless first_byte
 
+      fin = (first_byte & 0x80) != 0
       opcode = first_byte & 0x0F
       second_byte = @socket.getbyte
       return nil unless second_byte
@@ -887,7 +911,7 @@ module Tina4
         data = data.bytes.each_with_index.map { |b, i| b ^ mask_key[i % 4] }.pack("C*")
       end
 
-      { opcode: opcode, data: data }
+      { fin: fin, opcode: opcode, data: data }
     rescue IOError, EOFError
       nil
     end

data/lib/tina4/websocket_backplane.rb

@@ -175,25 +175,28 @@ module Tina4
 
     def subscribe(channel, &block)
       @mutex.synchronize do
-        sid = @nats.subscribe(channel) do |msg|
+        # NATS::Client#subscribe returns a NATS::Subscription. The client's own
+        # #unsubscribe is private in nats-pure 2.x, so we tear a subscription
+        # down through the subscription object, not the client (see #unsubscribe).
+        subscription = @nats.subscribe(channel) do |msg|
           block.call(msg.data) if @running
         end
-        @subs[channel] = sid
-
-        # Run NATS event processing in a background thread
-        @threads[channel] ||= Thread.new do
-          loop do
-            break unless @running
-            sleep 0.01
-          end
-        end
+        @subs[channel] = subscription
+
+        # The NATS client dispatches subscription callbacks on its own reader
+        # thread, so this keeper thread only has to stay alive until unsubscribe
+        # or close kills it. It blocks on an empty queue - nothing is ever
+        # pushed - so it waits at zero CPU. Before, it woke a hundred times a
+        # second on `sleep 0.01` just to re-check @running, burning energy to do
+        # nothing (Carbonah E004).
+        @threads[channel] ||= Thread.new { Thread::Queue.new.pop }
       end
     end
 
     def unsubscribe(channel)
       @mutex.synchronize do
-        sid = @subs.delete(channel)
-        @nats.unsubscribe(sid) if sid
+        subscription = @subs.delete(channel)
+        subscription&.unsubscribe
         thread = @threads.delete(channel)
         thread&.kill
       end
@@ -202,7 +205,7 @@ module Tina4
     def close
       @running = false
       @mutex.synchronize do
-        @subs.each_value { |sid| @nats.unsubscribe(sid) rescue nil }
+        @subs.each_value { |subscription| subscription.unsubscribe rescue nil }
         @subs.clear
         @threads.each_value { |t| t.kill }
         @threads.clear

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tina4ruby
 version: !ruby/object:Gem::Version
-  version: 3.13.140
+  version: 3.13.142
 platform: ruby
 authors:
 - Tina4 Team
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-28 00:00:00.000000000 Z
+date: 2026-09-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sqlite3
@@ -311,6 +311,7 @@ files:
 - lib/tina4/queue_backends/lite_backend.rb
 - lib/tina4/queue_backends/mongo_backend.rb
 - lib/tina4/queue_backends/rabbitmq_backend.rb
+- lib/tina4/queue_backends/republish_retry_policy.rb
 - lib/tina4/rack_app.rb
 - lib/tina4/rate_limiter.rb
 - lib/tina4/realtime.rb
@@ -340,6 +341,7 @@ files:
 - lib/tina4/session_handlers/mongo_wire_client.rb
 - lib/tina4/session_handlers/redis_handler.rb
 - lib/tina4/session_handlers/resp_client.rb
+- lib/tina4/session_handlers/resp_session_handler.rb
 - lib/tina4/session_handlers/valkey_handler.rb
 - lib/tina4/shutdown.rb
 - lib/tina4/smtp_client.rb