tina4ruby 3.13.36 → 3.13.38

data/lib/tina4/session.rb

@@ -21,7 +21,16 @@ module Tina4
       if !options.key?(:cookie_name) && env_name && !env_name.empty?
         @options[:cookie_name] = env_name
       end
-      @options[:secret] ||= ENV["TINA4_SECRET"] || "tina4-default-secret"
+      # No guessable built-in secret. The session never signs with this value
+      # (IDs are SecureRandom.hex(32)), so we resolve it from TINA4_SECRET only
+      # — nil when unset. This honours the framework's blank-secret discipline
+      # (Auth.ensure_dev_secret never uses a guessable default); Python/Node
+      # sessions carry no secret field at all.
+      @options[:secret] ||= ENV["TINA4_SECRET"]
+      # Backend-failure policy strict flag (parity with Python's
+      # TINA4_SESSION_STRICT). When truthy, read/write/destroy/gc failures
+      # RE-RAISE instead of logging + degrading.
+      @strict = Tina4::Env.is_truthy(ENV["TINA4_SESSION_STRICT"])
       @handler = create_handler
       @id = extract_session_id(env) || SecureRandom.hex(32)
       @data = load_session
@@ -51,14 +60,23 @@ module Tina4
       @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.
     def save
-      return unless @modified
-      @handler.write(@id, @data)
-      @modified = false
+      return true unless @modified
+      if safe_write(@id, @data)
+        @modified = false
+        true
+      else
+        false # dirty flag retained for retry
+      end
     end
 
+    # Destroy the current session. Should be called right after login or any
+    # privilege change to defend against session fixation (see #regenerate).
     def destroy
-      @handler.destroy(@id)
+      safe_destroy(@id)
       @data = {}
     end
 
@@ -104,12 +122,17 @@ module Tina4
       result.nil? ? default : result
     end
 
-    # Regenerate the session ID while preserving data — returns new ID
+    # Regenerate the session ID while preserving data — returns the new ID.
+    # Call this right after login or any privilege change to defend against
+    # 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.
     def regenerate
       old_id = @id
       @id = SecureRandom.hex(32)
-      @handler.destroy(old_id)
+      safe_destroy(old_id)
       @modified = true
+      save
       @id
     end
 
@@ -133,24 +156,27 @@ module Tina4
     end
 
     # Reads raw session data for a given session ID from backend storage.
-    # Returns the data hash or nil.
+    # Returns the data hash, or {} on a backend failure (logged + degraded).
     def read(session_id)
-      @handler.read(session_id)
+      safe_read(session_id)
     end
 
     # Writes raw session data for a given session ID to backend storage.
+    # Returns true on success, false on a backend failure (logged + degraded).
     def write(session_id, data, ttl = nil)
-      if ttl
-        @handler.write(session_id, data, ttl)
-      else
-        @handler.write(session_id, data)
-      end
+      safe_write(session_id, data, ttl)
     end
 
-    # Garbage collection: remove expired sessions from the handler
+    # Garbage collection: remove expired sessions from the handler.
+    # A backend failure is logged and swallowed (never crashes the request).
     def gc(max_lifetime = nil)
+      return unless @handler.respond_to?(:gc)
       max_lifetime ||= @options[:max_age]
-      @handler.gc(max_lifetime) if @handler.respond_to?(:gc)
+      @handler.gc(max_lifetime)
+    rescue StandardError => e
+      log_backend_error("gc", e)
+      raise if @strict
+      nil
     end
 
     def cookie_header(cookie_name = nil)
@@ -181,8 +207,59 @@ module Tina4
     end
 
     def load_session
-      existing = @handler.read(@id)
+      safe_read(@id)
+    end
+
+    # ── Backend-failure policy (parity with Python's Session boundary) ──
+    #
+    # Centralised here, NOT in each handler, so every backend (file, redis,
+    # valkey, mongo, database) shares one policy. The rule:
+    #   read   failure → log + return {} (empty session, never a 500)
+    #   write  failure → log + return false (caller retains dirty for retry)
+    #   destroy failure → log + swallow (return false)
+    #   gc     failure → log + swallow (see #gc)
+    # A genuinely-empty but HEALTHY backend (handler returns nil/{} WITHOUT
+    # raising) is NOT a failure and logs nothing. TINA4_SESSION_STRICT=true
+    # re-raises instead of degrading.
+
+    def safe_read(session_id)
+      existing = @handler.read(session_id)
       existing || {}
+    rescue StandardError => e
+      log_backend_error("read", e)
+      raise if @strict
+      {}
+    end
+
+    def safe_write(session_id, data, ttl = nil)
+      if ttl
+        @handler.write(session_id, data, ttl)
+      else
+        @handler.write(session_id, data)
+      end
+      true
+    rescue StandardError => e
+      log_backend_error("write", e)
+      raise if @strict
+      false
+    end
+
+    def safe_destroy(session_id)
+      @handler.destroy(session_id)
+      true
+    rescue StandardError => e
+      log_backend_error("destroy", e)
+      raise if @strict
+      false
+    end
+
+    # Single source of the backend-failure log line. Names the operation and
+    # the concrete handler class so ops can see WHICH backend failed.
+    def log_backend_error(operation, error)
+      handler_class = @handler.class.name
+      Tina4::Log.error("Session #{operation} failed (#{handler_class}): #{error.message}")
+    rescue StandardError
+      warn("Session #{operation} failed: #{error.message}")
     end
 
     def create_handler

data/lib/tina4/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Tina4
-  VERSION = "3.13.36"
+  VERSION = "3.13.38"
 end

data/lib/tina4/websocket.rb

@@ -4,15 +4,44 @@ require "digest"
 require "base64"
 require "json"
 require "set"
+require "securerandom"
 
 module Tina4
   WEBSOCKET_GUID = "258EAFA5-E914-47DA-95CA-5AB5DC11AD37"
 
+  # Shared pub/sub channel name + envelope shape for the WebSocket backplane.
+  # MUST stay byte-identical across all four frameworks (Python/PHP/Ruby/Node)
+  # so a broadcast published by one framework's instance is relayed by another.
+  WEBSOCKET_BACKPLANE_CHANNEL = "tina4:ws"
+
   # Compute Sec-WebSocket-Accept from Sec-WebSocket-Key per RFC 6455.
   def self.compute_accept_key(key)
     Base64.strict_encode64(Digest::SHA1.digest("#{key}#{WEBSOCKET_GUID}"))
   end
 
+  # Return true if the request's Origin is permitted to upgrade to a WebSocket.
+  #
+  # Controlled by TINA4_WS_ALLOWED_ORIGINS (comma-separated exact origins, e.g.
+  # "https://app.example.com,https://admin.example.com").
+  #
+  # Empty/unset = allow ALL origins (current behaviour, non-breaking). When set,
+  # only requests whose Origin exactly matches a listed value are allowed; a
+  # missing Origin header is rejected once the allow-list is active.
+  #
+  # +headers+ is a Hash. The Origin is looked up case-insensitively across both
+  # the Rack-style "HTTP_ORIGIN" key and a plain "origin"/"Origin" key so the
+  # same helper serves the rack_app upgrade path and direct callers/tests.
+  def self.websocket_origin_allowed?(headers)
+    raw = (ENV["TINA4_WS_ALLOWED_ORIGINS"] || "").strip
+    return true if raw.empty? # No allow-list configured — permit everything.
+
+    allowed = raw.split(",").map(&:strip).reject(&:empty?)
+    return true if allowed.empty?
+
+    origin = headers["HTTP_ORIGIN"] || headers["origin"] || headers["Origin"]
+    allowed.include?(origin)
+  end
+
   # Build a WebSocket frame (server→client, never masked).
   def self.build_frame(opcode, data, fin: true)
     first_byte = (fin ? 0x80 : 0x00) | opcode
@@ -44,8 +73,24 @@ module Tina4
         error: []
       }
       @rooms = {}  # room_name => Set of conn_ids
+
+      # ── Backplane (multi-instance scaling) ──────────────────────
+      # Lazily wired on first broadcast (see ensure_backplane). Each instance
+      # owns a stable id so it can ignore its own echoes coming back over the
+      # shared pub/sub channel (the origin guard). The backplane listener runs
+      # in its own Ruby thread, so the connections structure is guarded by a
+      # mutex shared with the broadcast path.
+      @backplane = nil
+      @backplane_started = false
+      @instance_id = SecureRandom.hex(8)
+      @backplane_channel = Tina4::WEBSOCKET_BACKPLANE_CHANNEL
+      @conn_mutex = Mutex.new
     end
 
+    # Stable per-process id used as the backplane envelope "src" so an instance
+    # drops its own echoes. Exposed for tests / introspection.
+    attr_reader :instance_id, :backplane_channel
+
     def on(event, &block)
       @handlers[event.to_sym] << block if @handlers.key?(event.to_sym)
     end
@@ -86,16 +131,31 @@ module Tina4
     end
 
     def broadcast(message, exclude: nil, path: nil)
-      @connections.each do |id, conn|
-        next if exclude && id == exclude
-        next if path && conn.path != path
-        conn.send_text(message)
+      ensure_backplane
+      targets = @conn_mutex.synchronize do
+        @connections.select do |id, conn|
+          !(exclude && id == exclude) && !(path && conn.path != path)
+        end.values
       end
+      deliver_resilient(targets, message)
+      publish_envelope(path ? "path" : "all", message, path: path, exclude: exclude)
+    end
+
+    # Send to ALL connections (no path filter). Resilient + backplane-fanned.
+    def broadcast_all(message, exclude: nil)
+      ensure_backplane
+      targets = @conn_mutex.synchronize do
+        @connections.reject { |id, _| exclude && id == exclude }.values
+      end
+      deliver_resilient(targets, message)
+      publish_envelope("all", message, exclude: exclude)
     end
 
     def send_to(conn_id, message)
-      conn = @connections[conn_id]
-      conn&.send_text(message)
+      conn = @conn_mutex.synchronize { @connections[conn_id] }
+      return unless conn
+
+      prune(conn) unless safe_send(conn, message)
     end
 
     def close(conn_id, code: 1000, reason: "")
@@ -136,12 +196,250 @@ module Tina4
     end
 
     def broadcast_to_room(room_name, message, exclude: nil)
-      (get_room_connections(room_name)).each do |conn|
-        next if exclude && conn.id == exclude
-        conn.send_text(message)
+      ensure_backplane
+      targets = get_room_connections(room_name).reject { |conn| exclude && conn.id == exclude }
+      deliver_resilient(targets, message)
+      publish_envelope("room", message, room: room_name, exclude: exclude)
+    end
+
+    # Register an open connection on this manager (thread-safe).
+    def register_connection(connection)
+      @conn_mutex.synchronize { @connections[connection.id] = connection }
+    end
+
+    # Drop a connection on close (thread-safe) and remove it from all rooms.
+    def unregister_connection(conn_id)
+      @conn_mutex.synchronize { @connections.delete(conn_id) }
+      remove_from_all_rooms(conn_id)
+    end
+
+    # ── Broadcast resilience ──────────────────────────────────
+    #
+    # One dead/slow client must never abort delivery to the rest. deliver_resilient
+    # walks the target list, wraps each send, logs+prunes anything that throws,
+    # and keeps going.
+
+    # Send to ONE connection without letting a single dead client abort a
+    # broadcast loop. Returns true if delivered, false if the connection looks
+    # dead (the caller then prunes it). A failed send is logged, never silent.
+    # A connection whose own #send swallowed a write error and flipped #closed?
+    # is treated as dead too (mirrors Python's `return not ws._closed`).
+    def safe_send(conn, message)
+      conn.send_text(message)
+      # If the connection's own #send swallowed a write error it flips #closed?;
+      # treat that as dead. Probe defensively so a stub/double that doesn't
+      # define #closed? is simply treated as alive.
+      dead = begin
+        conn.respond_to?(:closed?) && conn.closed?
+      rescue StandardError
+        false
+      end
+      !dead
+    rescue StandardError => e
+      Tina4::Log.warning("WebSocket send to #{conn.id} failed, pruning: #{e.message}") if defined?(Tina4::Log)
+      false
+    end
+
+    # Deliver +message+ to every connection in +targets+, pruning any that fail.
+    def deliver_resilient(targets, message)
+      dead = targets.reject { |conn| safe_send(conn, message) }
+      dead.each { |conn| prune(conn) }
+    end
+
+    # Remove a (presumed dead) connection from the manager + all rooms.
+    def prune(conn)
+      id = conn.respond_to?(:id) ? conn.id : nil
+      return unless id
+
+      @conn_mutex.synchronize { @connections.delete(id) }
+      remove_from_all_rooms(id)
+    end
+
+    # ── Idle reaper ───────────────────────────────────────────
+    #
+    # Opt-in via TINA4_WS_IDLE_TIMEOUT (seconds; 0/unset = disabled = current
+    # behaviour). Tracks last_activity per connection (bumped on every inbound
+    # frame in handle_upgrade); reap_idle closes/prunes anything idle past the
+    # timeout.
+
+    # Close connections whose last inbound frame is older than +timeout+ seconds.
+    # Returns the number reaped. timeout <= 0 is a no-op. Connections without a
+    # last_activity are skipped.
+    def reap_idle(timeout)
+      return 0 if timeout.to_f <= 0
+
+      now = Time.now.to_f
+      stale = @conn_mutex.synchronize do
+        @connections.values.select do |conn|
+          la = conn.respond_to?(:last_activity) ? conn.last_activity : nil
+          la && (now - la) > timeout
+        end
+      end
+      stale.each do |conn|
+        conn.close(code: 1001, reason: "idle timeout") rescue nil
+        prune(conn)
+      end
+      Tina4::Log.info("WebSocket idle reaper closed #{stale.size} connection(s)") if stale.any? && defined?(Tina4::Log)
+      stale.size
+    end
+
+    # Read the configured idle timeout (seconds). 0 = disabled.
+    def idle_timeout
+      Float(ENV["TINA4_WS_IDLE_TIMEOUT"] || "0")
+    rescue ArgumentError, TypeError
+      0.0
+    end
+
+    # Spin up a background reaper thread when an idle timeout is configured.
+    # Opt-in and non-breaking — unset/0 means no thread is created.
+    def start_idle_reaper
+      timeout = idle_timeout
+      return if timeout <= 0 || @reaper_thread&.alive?
+
+      interval = [1.0, timeout / 2.0].max
+      @reaper_running = true
+      @reaper_thread = Thread.new do
+        while @reaper_running
+          sleep interval
+          begin
+            reap_idle(timeout)
+          rescue StandardError => e
+            Tina4::Log.error("WebSocket idle reaper sweep failed: #{e.message}") if defined?(Tina4::Log)
+          end
+        end
+      end
+    end
+
+    def stop_idle_reaper
+      @reaper_running = false
+      @reaper_thread&.kill
+      @reaper_thread = nil
+    end
+
+    # ── Backplane (multi-instance scaling) ────────────────────
+    #
+    # When TINA4_WS_BACKPLANE is configured, every broadcast is ALSO published
+    # to a shared pub/sub channel so sibling instances relay it to their own
+    # local connections. Flow:
+    #
+    #   instance A: broadcast → deliver locally → publish_envelope → channel
+    #                                                                   │
+    #   instance B: backplane bg-THREAD → on_backplane_message ─────────┘
+    #                 │ (origin guard drops A's echoes by src id)
+    #                 └→ relay_local → B's LOCAL connections only (no re-publish)
+    #
+    # The subscribe callback runs in the backplane's background Ruby thread, so
+    # it touches @connections under @conn_mutex (shared with the broadcast path).
+    # The relay NEVER re-publishes (that would loop the cluster).
+
+    # Lazily wire the configured backplane. Idempotent and best-effort — a
+    # failure logs and leaves the manager local-only; it must NEVER crash a
+    # broadcast.
+    def ensure_backplane
+      return if @backplane_started
+
+      # Set immediately so we only ever attempt the wiring once, even on failure
+      # (no retry storm on every broadcast).
+      @backplane_started = true
+      begin
+        backplane = Tina4::WebSocketBackplane.create_backplane
+        return if backplane.nil? # No backplane configured — stay local-only.
+
+        @backplane = backplane
+        @backplane.subscribe(@backplane_channel) { |raw| on_backplane_message(raw) }
+        Tina4::Log.info("WebSocket backplane active (instance #{@instance_id}, channel '#{@backplane_channel}')") if defined?(Tina4::Log)
+      rescue StandardError => e
+        @backplane = nil
+        Tina4::Log.error("WebSocket backplane wiring failed, continuing local-only: #{e.message}") if defined?(Tina4::Log)
+      end
+    end
+
+    # Receive a raw envelope from the backplane. Runs in the backplane's
+    # BACKGROUND THREAD.
+    def on_backplane_message(raw)
+      env = begin
+        JSON.parse(raw)
+      rescue JSON::ParserError, TypeError
+        return
+      end
+      return unless env.is_a?(Hash)
+
+      # Origin guard: ignore our own broadcasts echoed back over the channel.
+      # We already delivered them locally; relaying again would double-send.
+      return if env["src"] == @instance_id
+
+      relay_local(env)
+    end
+
+    # Deliver a remote-originated envelope to LOCAL connections only. NEVER
+    # re-publishes (that would loop the message around the cluster). Dispatches
+    # by "kind": room / path / all.
+    def relay_local(env)
+      message = decode_envelope_message(env)
+      return if message.nil?
+
+      exclude = env["exclude"]
+      targets =
+        case env["kind"]
+        when "room"
+          room = env["room"]
+          room ? get_room_connections(room) : []
+        when "path"
+          path = env["path"]
+          path ? @conn_mutex.synchronize { @connections.values.select { |c| c.path == path } } : []
+        else # "all" (and anything unknown) → every local connection
+          @conn_mutex.synchronize { @connections.values }
+        end
+      targets = targets.reject { |conn| exclude && conn.id == exclude }
+      deliver_resilient(targets, message)
+    end
+
+    # Publish a broadcast to the shared channel for sibling instances. No-op
+    # when no backplane is configured. Best-effort — a publish failure logs and
+    # is swallowed so the local broadcast that already happened is never undone
+    # by a flaky message bus.
+    def publish_envelope(kind, message, room: nil, path: nil, exclude: nil)
+      return unless @backplane
+
+      envelope = {
+        "src" => @instance_id,
+        "kind" => kind,
+        "exclude" => exclude,
+        "room" => room,
+        "path" => path
+      }
+      # JSON can't carry raw bytes — encode binary as base64, text as text.
+      if binary_payload?(message)
+        envelope["b64"] = Base64.strict_encode64(message.b)
+      else
+        envelope["text"] = message
+      end
+      begin
+        @backplane.publish(@backplane_channel, JSON.generate(envelope))
+      rescue StandardError => e
+        Tina4::Log.warning("WebSocket backplane publish failed: #{e.message}") if defined?(Tina4::Log)
       end
     end
 
+    # Reconstruct the original str/bytes message from an envelope. JSON can't
+    # carry bytes, so text → {"text": ...} and bytes → {"b64": base64(...)}.
+    def decode_envelope_message(env)
+      return env["text"] if env.key?("text")
+      return Base64.strict_decode64(env["b64"]).b if env.key?("b64")
+
+      nil
+    end
+
+    # A message is "binary" when it is an ASCII-8BIT (BINARY-encoded) string.
+    # Ruby has no separate bytes type, so a caller's choice of the BINARY
+    # encoding is the signal to treat the payload as bytes: it goes through
+    # base64 so it survives the JSON envelope AND arrives with its binary
+    # encoding intact on the relaying instance (a JSON "text" value would come
+    # back as UTF-8, silently re-encoding binary data).
+    def binary_payload?(message)
+      message.is_a?(String) && message.encoding == Encoding::ASCII_8BIT
+    end
+
     # Register a WebSocket handler for a path (class method, matching Python's
     # WebSocketServer.route). The block receives a WebSocketConnection and should
     # call conn.on_message / conn.on_close to wire up event callbacks.
@@ -172,10 +470,26 @@ module Tina4
       Tina4::Router.websocket(path, &adapter)
     end
 
-    def handle_upgrade(env, socket)
+    # Upgrade a raw socket to a WebSocket connection and run its frame loop.
+    #
+    # +manager+ is the engine that should OWN the connection (its @connections /
+    # rooms / backplane / idle reaper). It defaults to +self+. In integrated
+    # (Rack) mode the rack_app passes a process-wide shared engine here so that
+    # broadcasts, rooms and the backplane span every route's connections even
+    # though each upgrade keeps its own isolated event handlers on +self+.
+    def handle_upgrade(env, socket, manager: self)
       key = env["HTTP_SEC_WEBSOCKET_KEY"]
       return unless key
 
+      # Origin allow-list (opt-in via TINA4_WS_ALLOWED_ORIGINS). Unset = allow
+      # all, so this never breaks an existing deployment. When set, an upgrade
+      # from a non-listed Origin is refused with a 403 before the handshake.
+      unless Tina4.websocket_origin_allowed?(env)
+        socket.write("HTTP/1.1 403 Forbidden\r\n\r\n") rescue nil
+        socket.close rescue nil
+        return
+      end
+
       accept = Tina4.compute_accept_key(key)
 
       response = "HTTP/1.1 101 Switching Protocols\r\n" \
@@ -187,8 +501,12 @@ module Tina4
 
       conn_id = SecureRandom.hex(16)
       ws_path = env["REQUEST_PATH"] || env["PATH_INFO"] || "/"
-      connection = WebSocketConnection.new(conn_id, socket, ws_server: self, path: ws_path)
-      @connections[conn_id] = connection
+      connection = WebSocketConnection.new(conn_id, socket, ws_server: manager, path: ws_path)
+      manager.register_connection(connection)
+
+      # Start the idle reaper lazily once we actually have a connection (opt-in
+      # via TINA4_WS_IDLE_TIMEOUT; a no-op when unset/0).
+      manager.start_idle_reaper
 
       emit(:open, connection)
 
@@ -198,6 +516,8 @@ module Tina4
             frame = connection.read_frame
             break unless frame
 
+            connection.touch # mark activity for the idle reaper
+
             case frame[:opcode]
             when 0x1 # Text
               emit(:message, connection, frame[:data])
@@ -210,8 +530,7 @@ module Tina4
         rescue => e
           emit(:error, connection, e)
         ensure
-          @connections.delete(conn_id)
-          remove_from_all_rooms(conn_id)
+          manager.unregister_connection(conn_id)
           emit(:close, connection)
           socket.close rescue nil
         end
@@ -228,7 +547,7 @@ module Tina4
   end
 
   class WebSocketConnection
-    attr_reader :id, :rooms
+    attr_reader :id, :rooms, :last_activity
     attr_accessor :params, :path, :on_message_handler, :on_close_handler, :on_error_handler
 
     def initialize(id, socket, ws_server: nil, path: "/")
@@ -241,6 +560,14 @@ module Tina4
       @on_message_handler = nil
       @on_close_handler = nil
       @on_error_handler = nil
+      # Updated on every inbound frame; the idle reaper closes connections that
+      # have been silent longer than TINA4_WS_IDLE_TIMEOUT (opt-in).
+      @last_activity = Time.now.to_f
+    end
+
+    # Mark inbound activity for the idle reaper.
+    def touch
+      @last_activity = Time.now.to_f
     end
 
     # Register a message handler (decorator style, matching Python).
@@ -281,12 +608,21 @@ module Tina4
       end
     end
 
+    # True once a write has failed (broken pipe / closed socket). The manager's
+    # resilient broadcast path uses this to prune dead connections.
+    def closed?
+      @closed == true
+    end
+
     def send(message)
-      data = message.encode("UTF-8")
+      data = message.is_a?(String) ? message : message.to_s
+      # Text frames must be valid UTF-8; binary payloads are sent verbatim.
+      data = data.encode("UTF-8") if data.encoding != Encoding::ASCII_8BIT
       frame = build_frame(0x1, data)
       @socket.write(frame)
     rescue IOError
-      # Connection closed
+      # Connection closed — mark dead so the broadcast path prunes it.
+      @closed = true
     end
 
     alias_method :send_text, :send
@@ -301,7 +637,7 @@ module Tina4
       frame = build_frame(0xA, data || "")
       @socket.write(frame)
     rescue IOError
-      # Connection closed
+      @closed = true
     end
 
     def close(code: 1000, reason: "")