tina4ruby 3.13.94 → 3.13.97

data/lib/tina4/cache_backends/memcached_backend.rb

@@ -13,6 +13,12 @@ module Tina4
     # auth, so credentials are ignored.
     class MemcachedBackend < BaseBackend
       PREFIX = "tina4:cache:"
+      # The SHARED namespace generation counter. clear bumps it; every real key
+      # carries it, so a bump invalidates every instance at once.
+      GENERATION_KEY = "#{PREFIX}generation".freeze
+      # memcached reads the `set` exptime field as RELATIVE seconds at or below
+      # 30 days, and as an ABSOLUTE unix timestamp above it.
+      MAX_RELATIVE_EXPTIME = 2_592_000
 
       def initialize(url: "memcached://localhost:11211", max_entries: 1000)
         cleaned = url.sub(%r{^memcached://}, "").sub(%r{^memcache://}, "")
@@ -46,30 +52,81 @@ module Tina4
 
       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"
+        k = mc_key(key)
+        payload = "set #{k} 0 #{exptime(ttl)} #{data.bytesize}\r\n#{data}\r\n"
         command(payload, "\r\n")
+        # Keys THIS backend wrote, mapped to the moment each expires (0 = never).
+        #
+        # This uses the RAW ttl, never the converted exptime. exptime(ttl)
+        # returns an ABSOLUTE unix timestamp past the 30-day cliff, and feeding
+        # that to Time.now.to_f + ... computes now + (now + ttl) - roughly twice
+        # the current epoch, a date in 2076. It fails SILENTLY: the shadow map
+        # would never expire anything, so the local bookkeeping stops matching
+        # what the server holds and stats reports expired entries as live
+        # forever.
+        @own ||= {}
+        @own[k] = ttl > 0 ? (Time.now.to_f + ttl) : 0.0
       end
 
       def delete(key)
-        command("delete #{mc_key(key)}\r\n", "\r\n").start_with?("DELETED")
+        k = mc_key(key)
+        result = command("delete #{k}\r\n", "\r\n").start_with?("DELETED")
+        (@own ||= {}).delete(k)
+        result
       end
 
+      # Invalidate EVERY entry this cache can serve, on EVERY instance.
+      #
+      # Two wrong answers were shipped before this one. +flush_all+ wipes EVERY
+      # key on the instance including every other application's - cache_clear is
+      # public API, so calling it destroyed other tenants' data. Deleting only
+      # the keys THIS process wrote fixed that but broke the contract the other
+      # way: a second instance kept serving rows the first had just invalidated,
+      # because it had never seen those keys.
+      #
+      # The namespace generation does both. Bumping the shared counter orphans
+      # every previously-written entry for every instance at once, and touches
+      # nothing outside our own prefix. The orphans are reclaimed by memcached's
+      # own TTL and LRU - unreachable is what "removed" means for a cache.
+      #
+      # The local write log is still cleared so stats reports honestly, and its
+      # keys are deleted eagerly so the space comes back immediately rather than
+      # waiting for eviction.
       def clear
         @hits = 0
         @misses = 0
-        command("flush_all\r\n", "\r\n")
+        (@own || {}).each_key { |k| command("delete #{k}\r\n", "\r\n") }
+        @own = {}
+        # incr is atomic, so two instances clearing at once still both advance.
+        return if command("incr #{GENERATION_KEY} 1\r\n", "\r\n").strip.match?(/\A\d+\z/)
+
+        # No counter yet: create it. `add` fails harmlessly if another instance
+        # created it in the gap, and the incr then applies.
+        command("add #{GENERATION_KEY} 0 0 1\r\n1\r\n", "\r\n")
+        command("incr #{GENERATION_KEY} 1\r\n", "\r\n")
       end
 
+      # Report OUR entries, not the whole server's.
+      #
+      # This used to read memcached's +curr_items+, which is a GLOBAL counter:
+      # it includes every key written by every other tenant of that server. On a
+      # shared memcached (the normal deployment) +size+ was reporting somebody
+      # else's data, and every other backend here is scoped - memory counts its
+      # own hash, redis/valkey scan their own prefix, file counts its own
+      # directory, mongo its own collection, database its own table. Memcached
+      # was the only one leaking.
+      #
+      # It cannot be fixed by asking the server: memcached has no KEYS or
+      # prefix-scan command. So the count comes from our own write log, filtered
+      # by the TTLs we set. That is exact for the keys this process wrote; a key
+      # EVICTED early under memory pressure is invisible to us and would be
+      # over-counted, which is a far smaller and more honest error than counting
+      # another application's keys.
       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" }
+        now = Time.now.to_f
+        # Drop the expired ones so the log cannot grow without bound.
+        @own = (@own || {}).select { |_k, expires| expires.zero? || expires > now }
+        { hits: @hits, misses: @misses, size: @own.size, backend: "memcached" }
       end
 
       def name
@@ -78,8 +135,62 @@ module Tina4
 
       private
 
+      # Read the SHARED namespace generation from the server.
+      #
+      # memcached has no KEYS scan and no prefix delete, so the only way to
+      # invalidate globally without destroying other tenants is the documented
+      # namespace idiom: every real key carries a generation, and clear bumps
+      # it. Every instance then computes a different key and the old entries
+      # become unreachable at once, expiring under the server's own TTL/LRU.
+      #
+      # The generation is read from the server on every operation, deliberately.
+      # Caching it in-process would reintroduce exactly the bug this fixes: an
+      # instance holding a stale generation keeps computing the OLD key, and the
+      # old key still holds the old value, so it serves a stale hit after
+      # another instance cleared. One extra round trip on a sub-millisecond
+      # local service is the price of cross-instance invalidation.
+      def generation
+        resp = command("get #{GENERATION_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
+            return rest[0, nbytes] if rest
+          rescue StandardError
+            nil
+          end
+        end
+        "0"
+      end
+
+      # Hash to a safe, bounded key (memcached keys: no spaces/control, <= 250
+      # chars). The generation sits IN the key so a clear on ANY instance
+      # orphans it for every instance at once.
       def mc_key(key)
-        PREFIX + Digest::SHA256.hexdigest(key)
+        "#{PREFIX}#{generation}:#{Digest::SHA256.hexdigest(key)}"
+      end
+
+      # Translate a Tina4 ttl (always RELATIVE seconds) into memcached's exptime
+      # field, which changes meaning at 30 days.
+      #
+      # Above MAX_RELATIVE_EXPTIME the server reads the field as an ABSOLUTE
+      # unix timestamp, so a raw ttl of, say, 60 days was read as a date in 1970
+      # and the entry vanished the instant it landed. memcached still answers
+      # STORED, so the symptom was a 100% miss rate with nothing logged - a
+      # cache that looks like it is working and never returns a hit.
+      #
+      # CONVERT, never CLAMP. Clamping a too-large ttl down to the cliff also
+      # makes the entry survive, and is ALSO wrong: it silently discards more
+      # than half the lifetime the operator explicitly configured, which is the
+      # same class of silent-wrong-answer as the bug it replaces.
+      #
+      # @param ttl [Integer] relative seconds; <= 0 means no expiry
+      # @return [Integer] the exptime field to send
+      def exptime(ttl)
+        return 0 if ttl <= 0
+        return Time.now.to_i + ttl if ttl > MAX_RELATIVE_EXPTIME
+
+        ttl
       end
 
       def command(payload, terminator)

data/lib/tina4/cache_backends/memory_backend.rb

@@ -71,6 +71,21 @@ module Tina4
         "memory"
       end
 
+      # Evict expired entries and return how many went.
+      #
+      # An entry stored with ttl <= 0 has expires_at nil - the no-expiry
+      # sentinel - and the nil check is what keeps a permanent entry off the
+      # eviction list. Dropping it would evict every permanent entry on the
+      # first sweep, silently, and report it as a successful reclaim.
+      def sweep
+        @mutex.synchronize do
+          now = monotonic
+          before = @store.size
+          @store.reject! { |_k, (_value, expires_at)| expires_at && now > expires_at }
+          before - @store.size
+        end
+      end
+
       private
 
       def monotonic

data/lib/tina4/cache_backends/redis_backend.rb

@@ -109,29 +109,40 @@ module Tina4
         end
       end
 
+      # Remove EVERY entry this cache can serve - on BOTH transports.
+      #
+      # The raw RESP path used to be an empty branch with a comment: "no easy
+      # pattern delete, rely on TTL". That made clear() a no-op on the
+      # ZERO-DEPENDENCY default install, so a write never invalidated the
+      # persistent DB query cache and every instance kept serving pre-write rows
+      # until the TTL ran out (ADR-0024 rule 4: the default provider counts
+      # double).
+      #
+      # SCAN, not KEYS: clear() runs on every write in persistent DB-cache mode,
+      # and KEYS is O(N) and blocks the whole server for its duration. Redis's
+      # own documentation says to prefer SCAN in production.
+      #
+      # The scan is scoped to our prefix, so another application sharing the
+      # server is untouched. FLUSHALL/FLUSHDB would take their data with it and
+      # is never used here.
       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
+        return scan_delete_with_client if @client
+        return unless @use_raw
+
+        scan_delete_with_raw_resp
       end
 
+      # Report OUR entries, counted with a scoped SCAN.
+      #
+      # size used to be a hardcoded 0 unless the `redis` GEM was loaded, so on
+      # the ZERO-DEPENDENCY raw RESP transport - the default install - stats
+      # reported 0 no matter how many entries were cached. Anything reading that
+      # number (a dashboard, db.cache_stats, an operator checking whether a
+      # clear worked) was reading a constant.
       def stats
-        size = 0
-        if @client
-          begin
-            size = @client.keys("#{PREFIX}*").size
-          rescue StandardError
-          end
-        end
-        { hits: @hits, misses: @misses, size: size, backend: @name }
+        { hits: @hits, misses: @misses, size: scan_count, backend: @name }
       end
 
       def name
@@ -173,58 +184,168 @@ module Tina4
         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"
+      # Encode one command as a RESP array of bulk strings.
+      def resp_encode(*args)
+        out = +"*#{args.size}\r\n"
         args.each do |arg|
-          s = arg.to_s
-          cmd << "$#{s.bytesize}\r\n#{s}\r\n"
+          value = arg.to_s
+          out << "$#{value.bytesize}\r\n#{value}\r\n"
         end
+        out
+      end
 
+      # Read ONE complete RESP reply and return String | nil | Array.
+      #
+      # Reads through the socket's BUFFERED gets/read so a reply larger than one
+      # socket read is assembled in full. The previous implementation did a
+      # single recv(65536) and string-split the result, which silently truncated
+      # any bulk value or multi-bulk reply bigger than that buffer - so a large
+      # cached entry came back corrupt and a key scan came back short.
+      def resp_read(sock)
+        line = sock.gets("\r\n")
+        return nil if line.nil?
+
+        prefix = line[0]
+        body = line[1..].to_s.chomp
+        case prefix
+        when "+", ":" then body
+        when "-" then nil
+        when "$" then resp_read_bulk(sock, body.to_i)
+        when "*" then resp_read_array(sock, body.to_i)
+        else body
+        end
+      end
+
+      # A bulk string: exactly `length` bytes, then the trailing CRLF.
+      def resp_read_bulk(sock, length)
+        return nil if length.negative?
+
+        payload = sock.read(length + 2)
+        return nil if payload.nil?
+
+        payload[0, length].to_s.force_encoding(Encoding::UTF_8)
+      end
+
+      # A multi-bulk array: `count` complete replies, read recursively.
+      def resp_read_array(sock, count)
+        return nil if count.negative?
+
+        Array.new(count) { resp_read(sock) }
+      end
+
+      # Open an authenticated RESP socket. The caller closes it.
+      #
+      # Kept separate from resp_command so a multi-step conversation (the SCAN
+      # cursor loop in clear) runs over ONE connection instead of reconnecting
+      # per command.
+      def resp_session
         sock = TCPSocket.new(@host, @port)
+        # SO_RCVTIMEO bounds the raw syscalls; IO#timeout (Ruby 3.2+) is the one
+        # that bounds the BUFFERED gets/read this class now uses, so a server
+        # that accepts the connection and never replies cannot hang a request.
         sock.setsockopt(Socket::SOL_SOCKET, Socket::SO_RCVTIMEO, [5, 0].pack("l_2"))
+        sock.timeout = 5 if sock.respond_to?(:timeout=)
 
         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.write(@username ? resp_encode("AUTH", @username, @password) : resp_encode("AUTH", @password))
+          unless resp_read(sock) == "OK"
             sock.close
-            return nil
+            raise IOError, "redis AUTH rejected"
           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)
+          sock.write(resp_encode("SELECT", @db))
+          resp_read(sock)
         end
+        sock
+      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")
+      # Send one command using the raw RESP protocol over TCP. Returns the
+      # decoded reply: a String for simple/bulk/integer replies, nil for a nil
+      # reply or an error, and an Array for a multi-bulk reply.
+      def resp_command(*args)
+        sock = nil
+        begin
+          sock = resp_session
+          sock.write(resp_encode(*args))
+          resp_read(sock)
+        rescue StandardError
           nil
-        elsif response.start_with?("$")
-          lines = response.split("\r\n")
-          lines[1]
-        elsif response.start_with?(":")
-          response[1..].strip
-        elsif response.start_with?("-")
+        ensure
+          close_quietly(sock)
+        end
+      end
+
+      # Walk every key under our PREFIX with a scoped SCAN cursor loop over ONE
+      # raw RESP connection, yielding each non-empty batch along with the open
+      # socket so a caller can act on the batch without reconnecting.
+      #
+      # SCAN, not KEYS: clear runs on every write in persistent DB-cache mode,
+      # and KEYS is O(N) and blocks the whole server for its duration. Redis's
+      # own documentation says to prefer SCAN.
+      def each_prefixed_key_batch
+        sock = nil
+        begin
+          sock = resp_session
+          cursor = "0"
+          loop do
+            sock.write(resp_encode("SCAN", cursor, "MATCH", "#{PREFIX}*", "COUNT", "500"))
+            reply = resp_read(sock)
+            break unless reply.is_a?(Array) && reply.size == 2
+
+            cursor, keys = reply
+            yield(sock, keys) if keys.is_a?(Array) && !keys.empty?
+            break if cursor.nil? || cursor == "0"
+          end
+        rescue StandardError
           nil
-        else
-          response.strip
+        ensure
+          close_quietly(sock)
         end
+      end
+
+      # The same scoped walk over the `redis` gem client. scan(), not keys(),
+      # for the reason above.
+      def each_prefixed_key_batch_with_client
+        cursor = "0"
+        loop do
+          cursor, keys = @client.scan(cursor, match: "#{PREFIX}*", count: 500)
+          yield(keys) if keys && !keys.empty?
+          break if cursor.nil? || cursor.to_s == "0"
+        end
+      rescue StandardError
+        nil
+      end
+
+      def scan_delete_with_client
+        each_prefixed_key_batch_with_client { |keys| @client.del(*keys) }
+      end
+
+      def scan_delete_with_raw_resp
+        each_prefixed_key_batch do |sock, keys|
+          sock.write(resp_encode("DEL", *keys))
+          resp_read(sock)
+        end
+      end
+
+      def scan_count
+        return scan_count_with_client if @client
+        return 0 unless @use_raw
+
+        total = 0
+        each_prefixed_key_batch { |_sock, keys| total += keys.size }
+        total
+      end
+
+      def scan_count_with_client
+        total = 0
+        each_prefixed_key_batch_with_client { |keys| total += keys.size }
+        total
+      end
+
+      def close_quietly(sock)
+        sock&.close
       rescue StandardError
         nil
       end

data/lib/tina4/cache_backends.rb

@@ -69,8 +69,17 @@ module Tina4
         when "file"
           dir = cache_dir || ENV.fetch("TINA4_CACHE_DIR", "data/cache")
           return FileBackend.new(cache_dir: dir, max_entries: max_entries)
-        else
+        when "memory", ""
           return MemoryBackend.new(max_entries: max_entries)
+        else
+          # An UNRECOGNISED name RAISES, naming the bad value and the valid
+          # ones -- the contract the session layer already settled on. Falling
+          # through to memory turned a typo (TINA4_CACHE_BACKEND=redsi) into a
+          # running app with a per-process cache while the operator believed it
+          # was Redis.
+          raise ArgumentError,
+                "Unknown cache backend '#{backend}'. Valid backends: " \
+                "memory, file, redis, valkey, memcached, mongodb, database."
         end
 
       return be if be.available?

data/lib/tina4/cli.rb

@@ -529,36 +529,14 @@ module Tina4
 
       # Use Puma only when explicitly requested via --production flag
       # WEBrick is used for development (supports dev toolbar/reload)
-      if options[:production]
-        begin
-          require "puma"
-          require "puma/configuration"
-          require "puma/launcher"
-
-          puma_host = options[:host]
-          puma_port = options[:port]
-
-          config = Puma::Configuration.new do |user_config|
-            user_config.bind "tcp://#{puma_host}:#{puma_port}"
-            user_config.app app
-            user_config.threads 0, 16
-            user_config.workers 0
-            user_config.environment "production"
-            user_config.log_requests false
-            user_config.quiet
-          end
-
-          Tina4::Log.info("Production server: puma")
-
-          # Setup graceful shutdown (Puma manages its own signals, but we handle DB cleanup)
-          Tina4::Shutdown.setup
-
-          launcher = Puma::Launcher.new(config)
-          launcher.run
-          return
-        rescue LoadError
-          # Puma not installed, fall through to WEBrick
-        end
+      # Same production server, same shutdown contract as Tina4.run! - one
+      # implementation, so the two entry points cannot drift again (the old
+      # copy here claimed "we handle DB cleanup" and did no cleanup at all).
+      # TINA4_DEFAULT_WEBSERVER=TRUE pins the built-in server even with
+      # --production.
+      if options[:production] && !Tina4.builtin_webserver_pinned? && Tina4.puma_available?
+        Tina4.start_puma_server(app, host: options[:host], port: options[:port])
+        return
       end
 
       Tina4::Log.info("Development server: WEBrick")
@@ -1145,18 +1123,22 @@ module Tina4
         exit 2
       end
 
-      result = Tina4::Metrics.offenders(path, top)
-      summary = result["summary"]
-      found = result["offenders"]
-
-      if summary.key?("error")
-        puts "  metrics error: #{summary['error']}"
+      # ONE engine run. Ask for every offender and slice for display: the gate
+      # must read the FULL set, not the printed top-N, and the old second call
+      # re-ran the whole analysis (its "full_analysis is cached" comment stopped
+      # being true when the in-process analyzer and its cache were deleted).
+      # An Integer, not Float::INFINITY -- Array#first demands an Integer.
+      every_offender = 2**31
+      begin
+        result = Tina4::Metrics.offenders(path, every_offender)
+      rescue Tina4::MetricsEngineError => e
+        warn "  metrics error: #{e.message}"
         exit 2
       end
+      summary = result["summary"]
+      all_offenders = result["offenders"]
+      found = all_offenders.first(top)
 
-      # Decide exit code from the FULL offender set, not just the printed top-N.
-      # full_analysis is cached, so this reuses the same analysis.
-      all_offenders = Tina4::Metrics.offenders(path, [summary["total_offenders"], 1].max)["offenders"]
       severities = all_offenders.map { |o| o["severity"] }.to_set
       exit_code = 0
       if fail_on == "warn" && !(severities & %w[warn error]).empty?
@@ -3177,6 +3159,7 @@ module Tina4
           .keys/
           logs/
           sessions/
+          data/queue/
           .queue/
           *.db
           vendor/
@@ -3249,6 +3232,7 @@ module Tina4
           .keys/
           logs/
           sessions/
+          data/queue/
           .queue/
           *.db
           *.gem