tina4ruby 3.13.23 → 3.13.24

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: baf95ed43a14f3bcfb80f371cfca547bb0605d7da81ec519c6d32d58287ad754
-  data.tar.gz: afafda038012638d1a98da325e03c42ac4d0517693abf3832f3e313ad414982a
+  metadata.gz: 6453444cbb2ebb4df4715ae2033881f8ba8cc24560a4e652d829db21c00a305a
+  data.tar.gz: be65f8fe81474f6c6946c1712192ba1040d417383477e52a4ba32477356b52dd
 SHA512:
-  metadata.gz: 6126339d81995e6d7199af287d4a8e909dd57f02f0ba58993f87e842c25716d40e80bad1af5a00a9c910a35e1025b7b5483986b29e57e983ee90ba4552b35540
-  data.tar.gz: a5fe6d009ccc270ecb27075da49ed1a8361a1ef59cffcaa4634f9b39a84896caf52e064b2129210c25d683c2a7b40048145a61e8ef206906b9cdc26a2e2c2af5
+  metadata.gz: 50d0ce089a2c0d587839bfd1c6e9f4a59935fdcb46635ceb56151d78f64fde012a165e3eb74b050eacf96b820828e2f94af34ab5aba4fb818256abc9135cb5e0
+  data.tar.gz: 3c1410b3a134988fd5e1f3deff3d087dee14cb2555431eeac9a3de0bb6fefa72903965c23616090f6b44cad0765f59596d915044dae91e40b0043e39b186c257

data/lib/tina4/cache_backends/base_backend.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Tina4
+  module CacheBackends
+    # Abstract cache backend (parity with Python _CacheBackend).
+    #
+    # A backend is a key/value store with TTL semantics and stats. Values are
+    # arbitrary JSON-serialisable objects; backends round-trip them through JSON
+    # for the network/file/db tiers so a value stored by one process can be read
+    # by another. The factory (Tina4::CacheBackends.create_backend) picks the
+    # right implementation from env vars and falls back to the file backend when
+    # a configured network/driver backend is unreachable.
+    class BaseBackend
+      # @param key [String]
+      # @return [Object, nil] cached value or nil on miss/expiry
+      def get(_key)
+        raise NotImplementedError
+      end
+
+      # @param key [String]
+      # @param value [Object]
+      # @param ttl [Integer] seconds; <= 0 means no expiry
+      def set(_key, _value, _ttl)
+        raise NotImplementedError
+      end
+
+      # @param key [String]
+      # @return [Boolean] true if the key existed
+      def delete(_key)
+        raise NotImplementedError
+      end
+
+      # Remove all entries owned by this cache.
+      def clear
+        raise NotImplementedError
+      end
+
+      # @return [Hash] { hits:, misses:, size:, backend: }
+      def stats
+        raise NotImplementedError
+      end
+
+      # @return [String] backend name reported in stats
+      def name
+        raise NotImplementedError
+      end
+
+      # Whether this backend is actually usable (driver present + service
+      # reachable). Local backends are always available; network/driver backends
+      # override this so the factory can fall back to the file backend.
+      #
+      # @return [Boolean]
+      def available?
+        true
+      end
+    end
+  end
+end

data/lib/tina4/cache_backends/database_backend.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "base_backend"
+
+module Tina4
+  module CacheBackends
+    # Database backend (parity with Python _DatabaseBackend) — stores entries in
+    # a tina4_cache table in any Tina4-supported database. Zero extra
+    # infrastructure; reuses the Database layer. Its own connection has query
+    # caching disabled to avoid recursion (a cache lookup must not itself try to
+    # cache through this same backend).
+    class DatabaseBackend < BaseBackend
+      def initialize(url: nil, max_entries: 1000)
+        @max_entries = max_entries
+        @hits = 0
+        @misses = 0
+        @db = nil
+        @available = false
+
+        # The database backend reads TINA4_CACHE_URL (interpreted as a SQL URL),
+        # falling back to the app's own TINA4_DATABASE_URL — cache in the DB you
+        # already run, no extra connection var needed.
+        url ||= env_nonempty("TINA4_CACHE_URL") ||
+                env_nonempty("TINA4_DATABASE_URL") ||
+                "sqlite://data/tina4.db"
+
+        # The cache's own DB connection must not itself cache (no recursion).
+        prev_auto = ENV["TINA4_AUTO_CACHING"]
+        prev_db = ENV["TINA4_DB_CACHE"]
+        ENV["TINA4_AUTO_CACHING"] = "false"
+        ENV["TINA4_DB_CACHE"] = "false"
+        begin
+          @db = Tina4::Database.new(url)
+          @db.execute(
+            "CREATE TABLE IF NOT EXISTS tina4_cache " \
+            "(cache_key VARCHAR(255) PRIMARY KEY, value TEXT, expires_at DOUBLE PRECISION)"
+          )
+          @available = true
+        rescue StandardError
+          @available = false
+        ensure
+          restore_env("TINA4_AUTO_CACHING", prev_auto)
+          restore_env("TINA4_DB_CACHE", prev_db)
+        end
+      end
+
+      def available?
+        @available
+      end
+
+      def get(key)
+        row = @db.fetch_one("SELECT value, expires_at FROM tina4_cache WHERE cache_key = ?", [key])
+        unless row
+          @misses += 1
+          return nil
+        end
+        exp = row["expires_at"] || row[:expires_at]
+        if exp && exp.to_f > 0 && Time.now.to_f > exp.to_f
+          @db.execute("DELETE FROM tina4_cache WHERE cache_key = ?", [key])
+          @misses += 1
+          return nil
+        end
+        @hits += 1
+        raw = row["value"] || row[:value]
+        begin
+          JSON.parse(raw)
+        rescue JSON::ParserError, TypeError
+          raw
+        end
+      end
+
+      def set(key, value, ttl)
+        exp = ttl > 0 ? Time.now.to_f + ttl : 0
+        serialized = JSON.generate(value)
+        @db.execute("DELETE FROM tina4_cache WHERE cache_key = ?", [key])
+        @db.execute(
+          "INSERT INTO tina4_cache (cache_key, value, expires_at) VALUES (?, ?, ?)",
+          [key, serialized, exp]
+        )
+      end
+
+      def delete(key)
+        existed = !@db.fetch_one("SELECT 1 AS x FROM tina4_cache WHERE cache_key = ?", [key]).nil?
+        @db.execute("DELETE FROM tina4_cache WHERE cache_key = ?", [key])
+        existed
+      end
+
+      def clear
+        @hits = 0
+        @misses = 0
+        @db.execute("DELETE FROM tina4_cache")
+      end
+
+      def stats
+        row = @db.fetch_one("SELECT COUNT(*) AS c FROM tina4_cache")
+        c = row ? (row["c"] || row[:c]) : 0
+        { hits: @hits, misses: @misses, size: c.to_i, backend: "database" }
+      end
+
+      def name
+        "database"
+      end
+
+      private
+
+      def env_nonempty(key)
+        v = ENV[key]
+        v && !v.empty? ? v : nil
+      end
+
+      def restore_env(key, value)
+        if value.nil?
+          ENV.delete(key)
+        else
+          ENV[key] = value
+        end
+      end
+    end
+  end
+end

data/lib/tina4/cache_backends/file_backend.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "digest"
+require_relative "base_backend"
+
+module Tina4
+  module CacheBackends
+    # File-based cache — stores entries as JSON files in data/cache/ (parity
+    # with Python _FileBackend). Always available; used as the graceful-degrade
+    # target when a configured network backend is unreachable.
+    class FileBackend < BaseBackend
+      def initialize(cache_dir: "data/cache", max_entries: 1000)
+        @dir = cache_dir
+        @max_entries = max_entries
+        @mutex = Mutex.new
+        @hits = 0
+        @misses = 0
+        FileUtils.mkdir_p(@dir)
+      end
+
+      def get(key)
+        path = key_path(key)
+        @mutex.synchronize do
+          unless File.exist?(path)
+            @misses += 1
+            return nil
+          end
+          begin
+            data = JSON.parse(File.read(path))
+            expires_at = data["expires_at"]
+            if expires_at && Time.now.to_f > expires_at
+              File.delete(path) rescue nil
+              @misses += 1
+              return nil
+            end
+            @hits += 1
+            data["value"]
+          rescue JSON::ParserError, SystemCallError
+            @misses += 1
+            nil
+          end
+        end
+      end
+
+      def set(key, value, ttl)
+        expires_at = ttl > 0 ? Time.now.to_f + ttl : nil
+        entry = { "key" => key, "value" => value, "expires_at" => expires_at }
+        @mutex.synchronize do
+          FileUtils.mkdir_p(@dir)
+          begin
+            files = Dir.glob(File.join(@dir, "*.json")).sort_by { |f| File.mtime(f) }
+            while files.size >= @max_entries
+              File.delete(files.shift) rescue nil
+            end
+          rescue SystemCallError
+          end
+          begin
+            File.write(key_path(key), JSON.generate(entry))
+          rescue SystemCallError
+          end
+        end
+      end
+
+      def delete(key)
+        path = key_path(key)
+        @mutex.synchronize do
+          if File.exist?(path)
+            File.delete(path) rescue nil
+            true
+          else
+            false
+          end
+        end
+      end
+
+      def clear
+        @mutex.synchronize do
+          @hits = 0
+          @misses = 0
+          Dir.glob(File.join(@dir, "*.json")).each { |f| File.delete(f) rescue nil }
+        end
+      end
+
+      def stats
+        @mutex.synchronize do
+          now = Time.now.to_f
+          count = 0
+          Dir.glob(File.join(@dir, "*.json")).each do |f|
+            begin
+              data = JSON.parse(File.read(f))
+              exp = data["expires_at"]
+              if exp && now > exp
+                File.delete(f) rescue nil
+              else
+                count += 1
+              end
+            rescue JSON::ParserError, SystemCallError
+            end
+          end
+          { hits: @hits, misses: @misses, size: count, backend: "file" }
+        end
+      end
+
+      def name
+        "file"
+      end
+
+      # Actively delete expired entries and return the number removed.
+      # (The file backend is the only one that supports an explicit sweep —
+      # network/db backends expire lazily via TTL.)
+      #
+      # @return [Integer]
+      def sweep
+        removed = 0
+        now = Time.now.to_f
+        @mutex.synchronize do
+          Dir.glob(File.join(@dir, "*.json")).each do |f|
+            begin
+              data = JSON.parse(File.read(f))
+              if data["expires_at"] && now > data["expires_at"]
+                File.delete(f) rescue nil
+                removed += 1
+              end
+            rescue JSON::ParserError, SystemCallError
+            end
+          end
+        end
+        removed
+      end
+
+      private
+
+      def key_path(key)
+        File.join(@dir, "#{Digest::SHA256.hexdigest(key)}.json")
+      end
+    end
+  end
+end

data/lib/tina4/cache_backends/memcached_backend.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "json"
+require "socket"
+require "digest"
+require_relative "base_backend"
+
+module Tina4
+  module CacheBackends
+    # Memcached backend using the zero-dependency text protocol over TCP
+    # (parity with Python _MemcachedBackend). Keys are SHA-256 hashed to stay
+    # within memcached's 250-char / no-space key constraints. Memcached has no
+    # auth, so credentials are ignored.
+    class MemcachedBackend < BaseBackend
+      PREFIX = "tina4:cache:"
+
+      def initialize(url: "memcached://localhost:11211", max_entries: 1000)
+        cleaned = url.sub(%r{^memcached://}, "").sub(%r{^memcache://}, "")
+        parts = cleaned.split("/").first.to_s.split(":")
+        @host = parts[0].nil? || parts[0].empty? ? "localhost" : parts[0]
+        @port = parts[1] && !parts[1].empty? ? parts[1].to_i : 11_211
+        @max_entries = max_entries
+        @hits = 0
+        @misses = 0
+        @available = command("version\r\n", "\r\n").start_with?("VERSION")
+      end
+
+      def available?
+        @available
+      end
+
+      def get(key)
+        resp = command("get #{mc_key(key)}\r\n", "END\r\n")
+        if resp.start_with?("VALUE")
+          begin
+            header, rest = resp.split("\r\n", 2)
+            nbytes = header.split[3].to_i
+            @hits += 1
+            return JSON.parse(rest[0, nbytes])
+          rescue StandardError
+          end
+        end
+        @misses += 1
+        nil
+      end
+
+      def set(key, value, ttl)
+        data = JSON.generate(value)
+        exptime = ttl > 0 ? ttl : 0
+        payload = "set #{mc_key(key)} 0 #{exptime} #{data.bytesize}\r\n#{data}\r\n"
+        command(payload, "\r\n")
+      end
+
+      def delete(key)
+        command("delete #{mc_key(key)}\r\n", "\r\n").start_with?("DELETED")
+      end
+
+      def clear
+        @hits = 0
+        @misses = 0
+        command("flush_all\r\n", "\r\n")
+      end
+
+      def stats
+        size = 0
+        resp = command("stats\r\n", "END\r\n")
+        resp.split("\r\n").each do |line|
+          if line.start_with?("STAT curr_items ")
+            size = line.split[2].to_i
+          end
+        end
+        { hits: @hits, misses: @misses, size: size, backend: "memcached" }
+      end
+
+      def name
+        "memcached"
+      end
+
+      private
+
+      def mc_key(key)
+        PREFIX + Digest::SHA256.hexdigest(key)
+      end
+
+      def command(payload, terminator)
+        sock = TCPSocket.new(@host, @port)
+        sock.setsockopt(Socket::SOL_SOCKET, Socket::SO_RCVTIMEO, [5, 0].pack("l_2"))
+        sock.write(payload)
+        buf = +""
+        until buf.include?(terminator)
+          chunk = sock.recv(4096)
+          break if chunk.nil? || chunk.empty?
+
+          buf << chunk
+        end
+        sock.close
+        buf
+      rescue StandardError
+        ""
+      end
+    end
+  end
+end

data/lib/tina4/cache_backends/memory_backend.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative "base_backend"
+
+module Tina4
+  module CacheBackends
+    # Thread-safe in-memory LRU cache with TTL (parity with Python
+    # _MemoryBackend). Default backend — zero dependencies.
+    class MemoryBackend < BaseBackend
+      def initialize(max_entries: 1000)
+        @max_entries = max_entries
+        @store = {} # key => [value, expires_at] ; Ruby Hash preserves insertion order
+        @mutex = Mutex.new
+        @hits = 0
+        @misses = 0
+      end
+
+      def get(key)
+        @mutex.synchronize do
+          entry = @store[key]
+          if entry.nil?
+            @misses += 1
+            return nil
+          end
+          value, expires_at = entry
+          if expires_at && monotonic > expires_at
+            @store.delete(key)
+            @misses += 1
+            return nil
+          end
+          @hits += 1
+          # Move to end (most recently used)
+          @store.delete(key)
+          @store[key] = entry
+          value
+        end
+      end
+
+      def set(key, value, ttl)
+        @mutex.synchronize do
+          expires_at = ttl > 0 ? monotonic + ttl : nil
+          @store.delete(key)
+          @store[key] = [value, expires_at]
+          while @store.size > @max_entries
+            @store.delete(@store.keys.first)
+          end
+        end
+      end
+
+      def delete(key)
+        @mutex.synchronize { !@store.delete(key).nil? }
+      end
+
+      def clear
+        @mutex.synchronize do
+          @store.clear
+          @hits = 0
+          @misses = 0
+        end
+      end
+
+      def stats
+        @mutex.synchronize do
+          now = monotonic
+          @store.reject! { |_k, (_v, exp)| exp && now > exp }
+          { hits: @hits, misses: @misses, size: @store.size, backend: "memory" }
+        end
+      end
+
+      def name
+        "memory"
+      end
+
+      private
+
+      def monotonic
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/tina4/cache_backends/mongo_backend.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+require_relative "base_backend"
+
+module Tina4
+  module CacheBackends
+    # MongoDB backend backed by a TTL collection (parity with Python
+    # _MongoBackend). Requires the `mongo` gem — reuses the same connection
+    # style as the Mongo session handler. The cache lives in collection
+    # tina4_cache with a TTL index on expires_at. The database name is taken
+    # from the URL path (mongodb://host:27017/<db>) or defaults to tina4_cache.
+    class MongoBackend < BaseBackend
+      def initialize(url: "mongodb://localhost:27017", max_entries: 1000)
+        @max_entries = max_entries
+        @hits = 0
+        @misses = 0
+        @coll = nil
+        begin
+          require "mongo"
+          Mongo::Logger.logger.level = Logger::FATAL if defined?(Mongo::Logger)
+          db_name = database_from_url(url)
+          client_opts = { server_selection_timeout: 5, database: db_name }
+          # Credentials from env when not embedded in the URL (parity with DB layer).
+          unless url.include?("@")
+            mu = env_nonempty("TINA4_CACHE_USERNAME")
+            mp = env_nonempty("TINA4_CACHE_PASSWORD")
+            client_opts[:user] = mu if mu
+            client_opts[:password] = mp if mp
+          end
+          client = Mongo::Client.new(url, **client_opts)
+          @coll = client[:tina4_cache]
+          @coll.indexes.create_one({ expires_at: 1 }, expire_after: 0)
+          client.database.command(ping: 1)
+        rescue LoadError, StandardError
+          @coll = nil
+        end
+      end
+
+      def available?
+        !@coll.nil?
+      end
+
+      def get(key)
+        if @coll.nil?
+          @misses += 1
+          return nil
+        end
+        begin
+          doc = @coll.find(_id: key).first
+          unless doc
+            @misses += 1
+            return nil
+          end
+          exp = doc["expires_at"]
+          if exp && exp < Time.now.utc
+            @coll.delete_one(_id: key)
+            @misses += 1
+            return nil
+          end
+          @hits += 1
+          JSON.parse(doc["value"])
+        rescue StandardError
+          @misses += 1
+          nil
+        end
+      end
+
+      def set(key, value, ttl)
+        return if @coll.nil?
+
+        begin
+          doc = { _id: key, value: JSON.generate(value) }
+          doc[:expires_at] = Time.now.utc + ttl if ttl > 0
+          @coll.replace_one({ _id: key }, doc, upsert: true)
+        rescue StandardError
+        end
+      end
+
+      def delete(key)
+        return false if @coll.nil?
+
+        begin
+          @coll.delete_one(_id: key).deleted_count > 0
+        rescue StandardError
+          false
+        end
+      end
+
+      def clear
+        @hits = 0
+        @misses = 0
+        return if @coll.nil?
+
+        begin
+          @coll.delete_many({})
+        rescue StandardError
+        end
+      end
+
+      def stats
+        size = 0
+        unless @coll.nil?
+          begin
+            size = @coll.count_documents({})
+          rescue StandardError
+          end
+        end
+        { hits: @hits, misses: @misses, size: size, backend: "mongodb" }
+      end
+
+      def name
+        "mongodb"
+      end
+
+      private
+
+      def env_nonempty(key)
+        v = ENV[key]
+        v && !v.empty? ? v : nil
+      end
+
+      def database_from_url(url)
+        uri = URI.parse(url)
+        path = (uri.path || "").sub(%r{^/}, "")
+        path.empty? ? "tina4_cache" : path
+      rescue URI::InvalidURIError
+        "tina4_cache"
+      end
+    end
+  end
+end