tina4ruby 3.13.23 → 3.13.26

data/lib/tina4/cache_backends/redis_backend.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+require "json"
+require "socket"
+require "uri"
+require_relative "base_backend"
+
+module Tina4
+  module CacheBackends
+    # Redis / Valkey backend (parity with Python _RedisBackend). Uses the
+    # `redis` gem if it is installed, otherwise falls back to the raw RESP
+    # protocol over a TCP socket — so it works with zero runtime dependencies.
+    #
+    # URL form: scheme://[user[:password]@]host[:port][/db]. Credentials may
+    # also be supplied via TINA4_CACHE_USERNAME / TINA4_CACHE_PASSWORD (parity
+    # with TINA4_DATABASE_USERNAME / TINA4_DATABASE_PASSWORD). Wrong credentials
+    # cause available? to return false, so the factory falls back to file.
+    class RedisBackend < BaseBackend
+      PREFIX = "tina4:cache:"
+
+      def initialize(url: "redis://localhost:6379", max_entries: 1000, name: "redis")
+        @max_entries = max_entries
+        @name = name
+        @hits = 0
+        @misses = 0
+        @client = nil
+        @use_raw = false
+
+        parse_url(url)
+
+        # Try the redis gem first.
+        begin
+          require "redis"
+          kwargs = { host: @host, port: @port, db: @db, timeout: 5 }
+          kwargs[:password] = @password if @password
+          kwargs[:username] = @username if @username
+          @client = Redis.new(**kwargs)
+          @client.ping
+          @available = true
+        rescue LoadError, StandardError
+          @client = nil
+          @use_raw = true
+          # No gem — usable only if the server answers (and authenticates).
+          @available = probe
+        end
+      end
+
+      def available?
+        @available
+      end
+
+      def get(key)
+        full_key = PREFIX + key
+        raw = if @client
+                begin
+                  @client.get(full_key)
+                rescue StandardError
+                  nil
+                end
+              elsif @use_raw
+                resp_command("GET", full_key)
+              end
+
+        if raw.nil?
+          @misses += 1
+          return nil
+        end
+        @hits += 1
+        begin
+          JSON.parse(raw)
+        rescue JSON::ParserError, TypeError
+          raw
+        end
+      end
+
+      def set(key, value, ttl)
+        full_key = PREFIX + key
+        serialized = JSON.generate(value)
+        if @client
+          begin
+            if ttl > 0
+              @client.setex(full_key, ttl, serialized)
+            else
+              @client.set(full_key, serialized)
+            end
+          rescue StandardError
+          end
+        elsif @use_raw
+          if ttl > 0
+            resp_command("SETEX", full_key, ttl.to_s, serialized)
+          else
+            resp_command("SET", full_key, serialized)
+          end
+        end
+      end
+
+      def delete(key)
+        full_key = PREFIX + key
+        if @client
+          begin
+            @client.del(full_key) > 0
+          rescue StandardError
+            false
+          end
+        elsif @use_raw
+          resp_command("DEL", full_key) == "1"
+        else
+          false
+        end
+      end
+
+      def clear
+        @hits = 0
+        @misses = 0
+        if @client
+          begin
+            keys = @client.keys("#{PREFIX}*")
+            @client.del(*keys) unless keys.empty?
+          rescue StandardError
+          end
+        elsif @use_raw
+          # Raw RESP doesn't support pattern delete easily; rely on TTL.
+        end
+      end
+
+      def stats
+        size = 0
+        if @client
+          begin
+            size = @client.keys("#{PREFIX}*").size
+          rescue StandardError
+          end
+        end
+        { hits: @hits, misses: @misses, size: size, backend: @name }
+      end
+
+      def name
+        @name
+      end
+
+      private
+
+      def parse_url(url)
+        url = "redis://#{url}" unless url.include?("://")
+        # Normalise valkey:// → redis:// so URI parses host/port/userinfo.
+        normalised = url.sub(%r{^valkey://}, "redis://")
+        uri = URI.parse(normalised)
+        @host = uri.host || "localhost"
+        @port = uri.port || 6379
+        db_path = (uri.path || "").sub(%r{^/}, "")
+        @db = db_path =~ /\A\d+\z/ ? db_path.to_i : 0
+        url_user = uri.user && !uri.user.empty? ? URI.decode_www_form_component(uri.user) : nil
+        url_pass = uri.password && !uri.password.empty? ? URI.decode_www_form_component(uri.password) : nil
+        @username = url_user || (env_nonempty("TINA4_CACHE_USERNAME"))
+        @password = url_pass || (env_nonempty("TINA4_CACHE_PASSWORD"))
+      rescue URI::InvalidURIError
+        @host = "localhost"
+        @port = 6379
+        @db = 0
+        @username = env_nonempty("TINA4_CACHE_USERNAME")
+        @password = env_nonempty("TINA4_CACHE_PASSWORD")
+      end
+
+      def env_nonempty(key)
+        v = ENV[key]
+        v && !v.empty? ? v : nil
+      end
+
+      # Real AUTH+PING handshake so wrong credentials also fall back to file.
+      def probe
+        resp_command("PING") == "PONG"
+      rescue StandardError
+        false
+      end
+
+      # Send a command using the raw RESP protocol over TCP. Returns the simple
+      # string / bulk string / integer as a String, or nil on miss/error.
+      def resp_command(*args)
+        cmd = +"*#{args.size}\r\n"
+        args.each do |arg|
+          s = arg.to_s
+          cmd << "$#{s.bytesize}\r\n#{s}\r\n"
+        end
+
+        sock = TCPSocket.new(@host, @port)
+        sock.setsockopt(Socket::SOL_SOCKET, Socket::SO_RCVTIMEO, [5, 0].pack("l_2"))
+
+        if @password
+          auth = if @username
+                   "*3\r\n$4\r\nAUTH\r\n$#{@username.bytesize}\r\n#{@username}\r\n" \
+                   "$#{@password.bytesize}\r\n#{@password}\r\n"
+                 else
+                   "*2\r\n$4\r\nAUTH\r\n$#{@password.bytesize}\r\n#{@password}\r\n"
+                 end
+          sock.write(auth)
+          unless sock.recv(1024).start_with?("+")
+            sock.close
+            return nil
+          end
+        end
+
+        if @db != 0
+          select_cmd = "*2\r\n$6\r\nSELECT\r\n$#{@db.to_s.bytesize}\r\n#{@db}\r\n"
+          sock.write(select_cmd)
+          sock.recv(1024)
+        end
+
+        sock.write(cmd)
+        response = sock.recv(65_536)
+        sock.close
+
+        if response.nil? || response.empty?
+          nil
+        elsif response.start_with?("+")
+          response[1..].strip
+        elsif response.start_with?("$-1")
+          nil
+        elsif response.start_with?("$")
+          lines = response.split("\r\n")
+          lines[1]
+        elsif response.start_with?(":")
+          response[1..].strip
+        elsif response.start_with?("-")
+          nil
+        else
+          response.strip
+        end
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/tina4/cache_backends/valkey_backend.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "redis_backend"
+
+module Tina4
+  module CacheBackends
+    # Valkey backend (parity with Python _ValkeyBackend). Valkey speaks the
+    # Redis wire protocol, so it reuses the Redis client / raw-RESP transport
+    # and only reports a different name.
+    class ValkeyBackend < RedisBackend
+      def initialize(url: "valkey://localhost:6379", max_entries: 1000)
+        super(url: url.sub(%r{^valkey://}, "redis://"), max_entries: max_entries, name: "valkey")
+      end
+    end
+  end
+end

data/lib/tina4/cache_backends.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative "cache_backends/base_backend"
+require_relative "cache_backends/memory_backend"
+require_relative "cache_backends/file_backend"
+require_relative "cache_backends/redis_backend"
+require_relative "cache_backends/valkey_backend"
+require_relative "cache_backends/memcached_backend"
+require_relative "cache_backends/mongo_backend"
+require_relative "cache_backends/database_backend"
+
+module Tina4
+  # Unified cache backend family (parity with Python tina4_python.cache).
+  #
+  # Backends are key/value stores with TTL semantics, selected via env vars:
+  #
+  #   memory    — in-process LRU cache (default, zero deps)
+  #   file      — JSON files in data/cache/
+  #   redis     — Redis (redis gem or raw RESP over TCP)
+  #   valkey    — Valkey (Redis wire protocol; reports "valkey")
+  #   memcached — Memcached (zero-dep text protocol over TCP)
+  #   mongodb   — MongoDB TTL collection (requires the mongo gem)
+  #   database  — tina4_cache table in any Tina4-supported database
+  #
+  # Environment:
+  #   TINA4_CACHE_BACKEND     — memory|file|redis|valkey|memcached|mongodb|database
+  #   TINA4_CACHE_URL         — connection URL (redis/valkey/memcached/mongo) OR
+  #                             SQL URL for database (falls back to TINA4_DATABASE_URL)
+  #   TINA4_CACHE_TTL         — default TTL in seconds (default: 60)
+  #   TINA4_CACHE_MAX_ENTRIES — max cached entries (default: 1000)
+  #   TINA4_CACHE_DIR         — file backend directory (default: data/cache)
+  #   TINA4_CACHE_USERNAME / TINA4_CACHE_PASSWORD — credentials when not in the URL
+  module CacheBackends
+    module_function
+
+    # Create a cache backend from explicit params or env vars.
+    #
+    # Graceful degradation: if the configured backend's driver is missing or its
+    # service is unreachable, the factory logs a warning and falls back to the
+    # file backend (persistent, zero-dep, always available) — never a silent
+    # no-op cache.
+    #
+    # @param backend [String, nil]
+    # @param url [String, nil]
+    # @param max_entries [Integer, nil]
+    # @param cache_dir [String, nil]
+    # @return [Tina4::CacheBackends::BaseBackend]
+    def create_backend(backend: nil, url: nil, max_entries: nil, cache_dir: nil)
+      backend ||= ENV.fetch("TINA4_CACHE_BACKEND", "memory")
+      max_entries ||= (ENV["TINA4_CACHE_MAX_ENTRIES"] || "1000").to_i
+      backend = backend.to_s.downcase.strip
+
+      be =
+        case backend
+        when "redis"
+          RedisBackend.new(url: url || ENV.fetch("TINA4_CACHE_URL", "redis://localhost:6379"),
+                           max_entries: max_entries)
+        when "valkey"
+          ValkeyBackend.new(url: url || ENV.fetch("TINA4_CACHE_URL", "valkey://localhost:6379"),
+                            max_entries: max_entries)
+        when "memcached", "memcache"
+          MemcachedBackend.new(url: url || ENV.fetch("TINA4_CACHE_URL", "memcached://localhost:11211"),
+                               max_entries: max_entries)
+        when "mongodb", "mongo"
+          MongoBackend.new(url: url || ENV.fetch("TINA4_CACHE_URL", "mongodb://localhost:27017"),
+                           max_entries: max_entries)
+        when "database", "db"
+          DatabaseBackend.new(url: url, max_entries: max_entries)
+        when "file"
+          dir = cache_dir || ENV.fetch("TINA4_CACHE_DIR", "data/cache")
+          return FileBackend.new(cache_dir: dir, max_entries: max_entries)
+        else
+          return MemoryBackend.new(max_entries: max_entries)
+        end
+
+      return be if be.available?
+
+      # Configured backend unusable — degrade to the file backend.
+      begin
+        Tina4::Log.warning(
+          "Cache backend '#{backend}' is unavailable " \
+          "(driver missing or service unreachable) — falling back to 'file'."
+        )
+      rescue StandardError
+        # Logging must never break cache construction.
+      end
+      dir = cache_dir || ENV.fetch("TINA4_CACHE_DIR", "data/cache")
+      FileBackend.new(cache_dir: dir, max_entries: max_entries)
+    end
+  end
+end

data/lib/tina4/database.rb

@@ -223,6 +223,25 @@ module Tina4
       @cache_misses = 0
       @cache_mutex = Mutex.new
 
+      # Persistent mode may route through the unified CacheBackend (redis/
+      # valkey/memcached/mongodb/database via TINA4_DB_CACHE_BACKEND) so
+      # multiple instances can share one cache with global write-invalidation.
+      # Request-scoped mode always stays in-process (the @query_cache dict).
+      # The DatabaseResult is serialized to a JSON-friendly Hash before storing
+      # and reconstructed on read so shared backends work cross-instance.
+      @cache_backend = nil
+      if @cache_persistent
+        begin
+          @cache_backend = Tina4::CacheBackends.create_backend(
+            backend: ENV["TINA4_DB_CACHE_BACKEND"] || "memory",
+            url: ENV["TINA4_DB_CACHE_URL"],
+            max_entries: 1000
+          )
+        rescue StandardError
+          @cache_backend = nil # fall back to the in-process dict
+        end
+      end
+
       # Register this connection so Tina4::Database.reset_request_caches can
       # clear its request-scoped entries at the start of every HTTP request.
       Tina4::Database.register_instance(self)
@@ -289,6 +308,19 @@ module Tina4
     # ── Query Cache ──────────────────────────────────────────────
 
     def cache_stats
+      if @cache_backend
+        bs = @cache_backend.stats
+        return {
+          enabled: @cache_enabled,
+          mode: cache_mode,
+          hits: @cache_hits,
+          misses: @cache_misses,
+          size: bs[:size],
+          backend: bs[:backend] || @cache_backend.name,
+          ttl: @cache_ttl
+        }
+      end
+
       @cache_mutex.synchronize do
         {
           enabled: @cache_enabled,
@@ -303,6 +335,7 @@ module Tina4
     end
 
     def cache_clear
+      @cache_backend.clear if @cache_backend
       @cache_mutex.synchronize do
         @query_cache.clear
         @cache_hits = 0
@@ -762,6 +795,13 @@ module Tina4
     end
 
     def cache_get(key)
+      # Shared backend (persistent + TINA4_DB_CACHE_BACKEND) — reconstruct the
+      # DatabaseResult from the serialized Hash so cross-instance reads work.
+      if @cache_backend
+        raw = @cache_backend.get(key)
+        return raw.is_a?(Hash) ? deserialize_result(raw) : nil
+      end
+
       @cache_mutex.synchronize do
         entry = @query_cache[key]
         return nil unless entry
@@ -774,6 +814,11 @@ module Tina4
     end
 
     def cache_set(key, value)
+      if @cache_backend
+        @cache_backend.set(key, serialize_result(value), @cache_ttl)
+        return
+      end
+
       @cache_mutex.synchronize do
         @query_cache[key] = {
           expires_at: Process.clock_gettime(Process::CLOCK_MONOTONIC) + @cache_ttl,
@@ -783,9 +828,59 @@ module Tina4
     end
 
     def cache_invalidate
+      @cache_backend.clear if @cache_backend
       @cache_mutex.synchronize { @query_cache.clear }
     end
 
+    # Flatten a DatabaseResult (or a single fetch_one Hash) into a JSON-friendly
+    # Hash for shared backends. fetch_one stores a plain Hash row, so we tag the
+    # shape so deserialize can return the right thing.
+    def serialize_result(value)
+      if value.is_a?(Tina4::DatabaseResult)
+        {
+          "kind" => "result",
+          "records" => value.records,
+          "count" => value.count,
+          "limit" => value.limit,
+          "offset" => value.offset,
+          "affected_rows" => value.affected_rows,
+          "last_id" => value.last_id
+        }
+      else
+        # fetch_one row (Hash) or nil
+        { "kind" => "row", "row" => value }
+      end
+    end
+
+    # Reconstruct from a backend-cached Hash. JSON round-trips string keys, so
+    # accept both string and symbol keys. Records are re-symbolised so a cached
+    # result is byte-for-byte equivalent to an uncached fetch (driver rows use
+    # symbol keys) regardless of which backend stored it.
+    def deserialize_result(data)
+      kind = data["kind"] || data[:kind]
+      if kind == "row"
+        row = data["row"] || data[:row]
+        symbolize_row(row)
+      else
+        records = (data["records"] || data[:records] || []).map { |r| symbolize_row(r) }
+        Tina4::DatabaseResult.new(
+          records,
+          count: data["count"] || data[:count] || 0,
+          limit: data["limit"] || data[:limit] || 0,
+          offset: data["offset"] || data[:offset] || 0,
+          affected_rows: data["affected_rows"] || data[:affected_rows] || 0,
+          last_id: data["last_id"] || data[:last_id]
+        )
+      end
+    end
+
+    # Driver rows use symbol keys; re-key a JSON-round-tripped Hash to match.
+    def symbolize_row(row)
+      return row unless row.is_a?(Hash)
+
+      row.each_with_object({}) { |(k, v), h| h[k.to_sym] = v }
+    end
+
     def detect_driver(conn)
       case conn.to_s.downcase
       when /\.db$/, /\.sqlite/, /sqlite/