tina4ruby 3.0.0 → 3.9.2

data/lib/tina4/response_cache.rb

@@ -1,18 +1,28 @@
 # frozen_string_literal: true
 
 module Tina4
-  # In-memory response cache for GET requests.
+  # Multi-backend response cache for GET requests.
   #
-  # Caches serialized responses by method + URL.
-  # Designed to be used as Rack middleware or integrated into the Tina4 middleware chain.
+  # Backends are selected via the TINA4_CACHE_BACKEND env var:
+  #   memory — in-process LRU cache (default, zero deps)
+  #   redis  — Redis / Valkey (uses `redis` gem or raw RESP over TCP)
+  #   file   — JSON files in data/cache/
+  #
+  # Environment:
+  #   TINA4_CACHE_BACKEND      — memory | redis | file  (default: memory)
+  #   TINA4_CACHE_URL           — redis://localhost:6379  (redis only)
+  #   TINA4_CACHE_TTL           — default TTL in seconds  (default: 0 = disabled)
+  #   TINA4_CACHE_MAX_ENTRIES   — maximum cache entries   (default: 1000)
   #
   # Usage:
   #   cache = Tina4::ResponseCache.new(ttl: 60, max_entries: 1000)
   #   cache.cache_response("GET", "/api/users", 200, "application/json", '{"users":[]}')
   #   hit = cache.get("GET", "/api/users")
   #
-  # Environment:
-  #   TINA4_CACHE_TTL -- default TTL in seconds (default: 0 = disabled)
+  #   # Direct API (same across all 4 languages)
+  #   cache.cache_set("key", {"data" => "value"}, ttl: 120)
+  #   value = cache.cache_get("key")
+  #   cache.cache_delete("key")
   #
   class ResponseCache
     CacheEntry = Struct.new(:body, :content_type, :status_code, :expires_at)
@@ -20,12 +30,24 @@ module Tina4
     # @param ttl [Integer] default TTL in seconds (0 = disabled)
     # @param max_entries [Integer] maximum cache entries
     # @param status_codes [Array<Integer>] only cache these status codes
-    def initialize(ttl: nil, max_entries: 1000, status_codes: [200])
+    # @param backend [String, nil] cache backend: memory|redis|file
+    # @param cache_url [String, nil] Redis URL
+    # @param cache_dir [String, nil] File cache directory
+    def initialize(ttl: nil, max_entries: nil, status_codes: [200],
+                   backend: nil, cache_url: nil, cache_dir: nil)
       @ttl = ttl || (ENV["TINA4_CACHE_TTL"] ? ENV["TINA4_CACHE_TTL"].to_i : 0)
-      @max_entries = max_entries
+      @max_entries = max_entries || (ENV["TINA4_CACHE_MAX_ENTRIES"] ? ENV["TINA4_CACHE_MAX_ENTRIES"].to_i : 1000)
       @status_codes = status_codes
+      @backend_name = backend || ENV.fetch("TINA4_CACHE_BACKEND", "memory").downcase.strip
+      @cache_url = cache_url || ENV.fetch("TINA4_CACHE_URL", "redis://localhost:6379")
+      @cache_dir = cache_dir || ENV.fetch("TINA4_CACHE_DIR", "data/cache")
       @store = {}
       @mutex = Mutex.new
+      @hits = 0
+      @misses = 0
+
+      # Initialize backend
+      init_backend
     end
 
     # Check if caching is enabled.
@@ -54,16 +76,36 @@ module Tina4
       return nil unless method == "GET"
 
       key = cache_key(method, url)
-      @mutex.synchronize do
-        entry = @store[key]
-        return nil unless entry
+      entry = backend_get(key)
+
+      if entry.nil?
+        @mutex.synchronize { @misses += 1 }
+        return nil
+      end
 
+      # For memory backend, entry is a CacheEntry; for others, reconstruct
+      if entry.is_a?(CacheEntry)
         if Time.now.to_f > entry.expires_at
-          @store.delete(key)
+          backend_delete(key)
+          @mutex.synchronize { @misses += 1 }
           return nil
         end
-
+        @mutex.synchronize { @hits += 1 }
         entry
+      elsif entry.is_a?(Hash)
+        expires_at = entry["expires_at"] || entry[:expires_at] || 0
+        if Time.now.to_f > expires_at
+          backend_delete(key)
+          @mutex.synchronize { @misses += 1 }
+          return nil
+        end
+        @mutex.synchronize { @hits += 1 }
+        CacheEntry.new(
+          entry["body"] || entry[:body],
+          entry["content_type"] || entry[:content_type],
+          entry["status_code"] || entry[:status_code],
+          expires_at
+        )
       end
     end
 
@@ -84,51 +126,426 @@ module Tina4
       key = cache_key(method, url)
       expires_at = Time.now.to_f + effective_ttl
 
-      @mutex.synchronize do
-        # Evict oldest if at capacity
-        if @store.size >= @max_entries && !@store.key?(key)
-          oldest_key = @store.keys.first
-          @store.delete(oldest_key)
+      entry_data = {
+        "body" => body,
+        "content_type" => content_type,
+        "status_code" => status_code,
+        "expires_at" => expires_at
+      }
+
+      case @backend_name
+      when "memory"
+        @mutex.synchronize do
+          if @store.size >= @max_entries && !@store.key?(key)
+            oldest_key = @store.keys.first
+            @store.delete(oldest_key)
+          end
+          @store[key] = CacheEntry.new(body, content_type, status_code, expires_at)
         end
+      else
+        backend_set(key, entry_data, effective_ttl)
+      end
+    end
+
+    # ── Direct Cache API (same across all 4 languages) ──────────
 
-        @store[key] = CacheEntry.new(body, content_type, status_code, expires_at)
+    # Get a value from the cache by key.
+    #
+    # @param key [String]
+    # @return [Object, nil]
+    def cache_get(key)
+      full_key = "direct:#{key}"
+      raw = backend_get(full_key)
+
+      if raw.nil?
+        @mutex.synchronize { @misses += 1 }
+        return nil
       end
+
+      if raw.is_a?(Hash)
+        expires_at = raw["expires_at"] || raw[:expires_at] || 0
+        if expires_at > 0 && Time.now.to_f > expires_at
+          backend_delete(full_key)
+          @mutex.synchronize { @misses += 1 }
+          return nil
+        end
+        @mutex.synchronize { @hits += 1 }
+        raw["value"] || raw[:value]
+      else
+        @mutex.synchronize { @hits += 1 }
+        raw
+      end
+    end
+
+    # Store a value in the cache with optional TTL.
+    #
+    # @param key [String]
+    # @param value [Object]
+    # @param ttl [Integer] TTL in seconds (0 uses default)
+    def cache_set(key, value, ttl: 0)
+      effective_ttl = ttl > 0 ? ttl : @ttl
+      effective_ttl = 60 if effective_ttl <= 0 # fallback for direct API
+      full_key = "direct:#{key}"
+      entry = {
+        "value" => value,
+        "expires_at" => Time.now.to_f + effective_ttl
+      }
+      backend_set(full_key, entry, effective_ttl)
+    end
+
+    # Delete a key from the cache.
+    #
+    # @param key [String]
+    # @return [Boolean]
+    def cache_delete(key)
+      backend_delete("direct:#{key}")
     end
 
     # Get cache statistics.
     #
-    # @return [Hash] with :size and :keys
+    # @return [Hash] with :hits, :misses, :size, :backend, :keys
     def cache_stats
       @mutex.synchronize do
-        { size: @store.size, keys: @store.keys.dup }
+        case @backend_name
+        when "memory"
+          now = Time.now.to_f
+          @store.reject! { |_k, v| v.is_a?(CacheEntry) && now > v.expires_at }
+          { hits: @hits, misses: @misses, size: @store.size, backend: @backend_name, keys: @store.keys.dup }
+        when "file"
+          sweep
+          files = Dir.glob(File.join(@cache_dir, "*.json"))
+          { hits: @hits, misses: @misses, size: files.size, backend: @backend_name, keys: [] }
+        when "redis"
+          size = 0
+          if @redis_client
+            begin
+              keys = @redis_client.keys("tina4:cache:*")
+              size = keys.size
+            rescue StandardError
+            end
+          end
+          { hits: @hits, misses: @misses, size: size, backend: @backend_name, keys: [] }
+        else
+          { hits: @hits, misses: @misses, size: @store.size, backend: @backend_name, keys: @store.keys.dup }
+        end
       end
     end
 
     # Clear all cached responses.
     def clear_cache
-      @mutex.synchronize { @store.clear }
+      @mutex.synchronize do
+        @hits = 0
+        @misses = 0
+
+        case @backend_name
+        when "memory"
+          @store.clear
+        when "file"
+          Dir.glob(File.join(@cache_dir, "*.json")).each { |f| File.delete(f) rescue nil }
+        when "redis"
+          if @redis_client
+            begin
+              keys = @redis_client.keys("tina4:cache:*")
+              @redis_client.del(*keys) unless keys.empty?
+            rescue StandardError
+            end
+          end
+        end
+      end
     end
 
     # Remove expired entries.
     #
     # @return [Integer] number of entries removed
     def sweep
-      @mutex.synchronize do
+      case @backend_name
+      when "memory"
+        @mutex.synchronize do
+          now = Time.now.to_f
+          keys_to_remove = @store.select { |_k, v| v.is_a?(CacheEntry) && now > v.expires_at }.keys
+          keys_to_remove += @store.select { |_k, v| v.is_a?(Hash) && (v["expires_at"] || 0) > 0 && now > (v["expires_at"] || 0) }.keys
+          keys_to_remove.each { |k| @store.delete(k) }
+          keys_to_remove.size
+        end
+      when "file"
+        removed = 0
         now = Time.now.to_f
-        keys_to_remove = @store.select { |_k, v| now > v.expires_at }.keys
-        keys_to_remove.each { |k| @store.delete(k) }
-        keys_to_remove.size
+        Dir.glob(File.join(@cache_dir, "*.json")).each do |f|
+          begin
+            data = JSON.parse(File.read(f))
+            if data["expires_at"] && now > data["expires_at"]
+              File.delete(f)
+              removed += 1
+            end
+          rescue StandardError
+          end
+        end
+        removed
+      else
+        0
       end
     end
 
     # Current TTL setting.
-    #
-    # @return [Integer]
     attr_reader :ttl
 
     # Maximum entries setting.
-    #
-    # @return [Integer]
     attr_reader :max_entries
+
+    # Active backend name.
+    def backend_name
+      @backend_name
+    end
+
+    private
+
+    # ── Backend initialization ─────────────────────────────────
+
+    def init_backend
+      case @backend_name
+      when "redis"
+        init_redis
+      when "file"
+        init_file_dir
+      end
+    end
+
+    def init_redis
+      @redis_client = nil
+      begin
+        require "redis"
+        parsed = parse_redis_url(@cache_url)
+        @redis_client = Redis.new(host: parsed[:host], port: parsed[:port], db: parsed[:db], timeout: 5)
+        @redis_client.ping
+      rescue LoadError, StandardError
+        @redis_client = nil
+      end
+    end
+
+    def parse_redis_url(url)
+      cleaned = url.sub(%r{^redis://}, "")
+      parts = cleaned.split(":")
+      host = parts[0].empty? ? "localhost" : parts[0]
+      port_and_db = parts[1] ? parts[1].split("/") : ["6379"]
+      port = port_and_db[0].to_i
+      port = 6379 if port == 0
+      db = port_and_db[1] ? port_and_db[1].to_i : 0
+      { host: host, port: port, db: db }
+    end
+
+    def init_file_dir
+      require "json"
+      require "fileutils"
+      FileUtils.mkdir_p(@cache_dir)
+    end
+
+    # ── Backend operations ─────────────────────────────────────
+
+    def backend_get(key)
+      case @backend_name
+      when "memory"
+        @mutex.synchronize { @store[key] }
+      when "redis"
+        redis_get(key)
+      when "file"
+        file_get(key)
+      else
+        @mutex.synchronize { @store[key] }
+      end
+    end
+
+    def backend_set(key, entry, ttl)
+      case @backend_name
+      when "memory"
+        @mutex.synchronize do
+          if @store.size >= @max_entries && !@store.key?(key)
+            oldest_key = @store.keys.first
+            @store.delete(oldest_key)
+          end
+          @store[key] = entry
+        end
+      when "redis"
+        redis_set(key, entry, ttl)
+      when "file"
+        file_set(key, entry)
+      end
+    end
+
+    def backend_delete(key)
+      case @backend_name
+      when "memory"
+        @mutex.synchronize do
+          !@store.delete(key).nil?
+        end
+      when "redis"
+        redis_delete(key)
+      when "file"
+        file_delete(key)
+      end
+    end
+
+    # ── Redis operations ───────────────────────────────────────
+
+    def redis_get(key)
+      full_key = "tina4:cache:#{key}"
+      if @redis_client
+        begin
+          raw = @redis_client.get(full_key)
+          return nil if raw.nil?
+          JSON.parse(raw)
+        rescue StandardError
+          nil
+        end
+      else
+        resp_get(full_key)
+      end
+    end
+
+    def redis_set(key, entry, ttl)
+      full_key = "tina4:cache:#{key}"
+      serialized = JSON.generate(entry)
+      if @redis_client
+        begin
+          if ttl > 0
+            @redis_client.setex(full_key, ttl, serialized)
+          else
+            @redis_client.set(full_key, serialized)
+          end
+        rescue StandardError
+        end
+      else
+        if ttl > 0
+          resp_command("SETEX", full_key, ttl.to_s, serialized)
+        else
+          resp_command("SET", full_key, serialized)
+        end
+      end
+    end
+
+    def redis_delete(key)
+      full_key = "tina4:cache:#{key}"
+      if @redis_client
+        begin
+          @redis_client.del(full_key) > 0
+        rescue StandardError
+          false
+        end
+      else
+        result = resp_command("DEL", full_key)
+        result == "1"
+      end
+    end
+
+    def resp_get(key)
+      result = resp_command("GET", key)
+      return nil if result.nil?
+      JSON.parse(result) rescue nil
+    end
+
+    def resp_command(*args)
+      parsed = parse_redis_url(@cache_url)
+      cmd = "*#{args.size}\r\n"
+      args.each { |arg| s = arg.to_s; cmd += "$#{s.bytesize}\r\n#{s}\r\n" }
+
+      sock = TCPSocket.new(parsed[:host], parsed[:port])
+      sock.setsockopt(Socket::SOL_SOCKET, Socket::SO_RCVTIMEO, [5, 0].pack("l_2"))
+      if parsed[:db] > 0
+        select_cmd = "*2\r\n$6\r\nSELECT\r\n$#{parsed[:db].to_s.bytesize}\r\n#{parsed[:db]}\r\n"
+        sock.write(select_cmd)
+        sock.recv(1024)
+      end
+      sock.write(cmd)
+      response = sock.recv(65536)
+      sock.close
+
+      if 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
+      else
+        nil
+      end
+    rescue StandardError
+      nil
+    end
+
+    # ── File operations ────────────────────────────────────────
+
+    def file_key_path(key)
+      require "digest"
+      safe = Digest::SHA256.hexdigest(key)
+      File.join(@cache_dir, "#{safe}.json")
+    end
+
+    def file_get(key)
+      path = file_key_path(key)
+      return nil unless File.exist?(path)
+      begin
+        data = JSON.parse(File.read(path))
+        if data["expires_at"] && Time.now.to_f > data["expires_at"]
+          File.delete(path) rescue nil
+          return nil
+        end
+        data
+      rescue StandardError
+        nil
+      end
+    end
+
+    def file_set(key, entry)
+      init_file_dir
+      files = Dir.glob(File.join(@cache_dir, "*.json")).sort_by { |f| File.mtime(f) }
+      while files.size >= @max_entries
+        File.delete(files.shift) rescue nil
+      end
+      path = file_key_path(key)
+      File.write(path, JSON.generate(entry))
+    rescue StandardError
+    end
+
+    def file_delete(key)
+      path = file_key_path(key)
+      if File.exist?(path)
+        File.delete(path) rescue nil
+        true
+      else
+        false
+      end
+    end
+  end
+
+  # ── Module-level convenience (singleton) ───────────────────────
+
+  @default_cache = nil
+
+  class << self
+    def cache_instance
+      @default_cache ||= ResponseCache.new(ttl: ENV["TINA4_CACHE_TTL"] ? ENV["TINA4_CACHE_TTL"].to_i : 60)
+    end
+
+    def cache_get(key)
+      cache_instance.cache_get(key)
+    end
+
+    def cache_set(key, value, ttl: 0)
+      cache_instance.cache_set(key, value, ttl: ttl)
+    end
+
+    def cache_delete(key)
+      cache_instance.cache_delete(key)
+    end
+
+    def cache_clear
+      cache_instance.clear_cache
+    end
+
+    def cache_stats
+      cache_instance.cache_stats
+    end
   end
 end

data/lib/tina4/router.rb

@@ -4,6 +4,7 @@ module Tina4
   class Route
     attr_reader :method, :path, :handler, :auth_handler, :swagger_meta,
                 :path_regex, :param_names, :middleware, :template
+    attr_accessor :auth_required, :cached
 
     def initialize(method, path, handler, auth_handler: nil, swagger_meta: {}, middleware: [], template: nil)
       @method = method.to_s.upcase.freeze
@@ -13,11 +14,34 @@ module Tina4
       @swagger_meta = swagger_meta
       @middleware = middleware.freeze
       @template = template&.freeze
+      @auth_required = %w[POST PUT PATCH DELETE].include?(@method)
+      @cached = false
       @param_names = []
       @path_regex = compile_pattern(@path)
       @param_names.freeze
     end
 
+    # Mark this route as requiring bearer-token authentication.
+    # Returns self for chaining: Router.get("/path") { ... }.secure
+    def secure
+      @auth_required = true
+      self
+    end
+
+    # Opt out of the secure-by-default auth on write routes.
+    # Returns self for chaining: Router.post("/login") { ... }.no_auth
+    def no_auth
+      @auth_required = false
+      self
+    end
+
+    # Mark this route as cacheable.
+    # Returns self for chaining: Router.get("/path") { ... }.cache
+    def cache
+      @cached = true
+      self
+    end
+
     # Returns params hash if matched, false otherwise
     def match?(request_path, request_method = nil)
       return false if request_method && @method != "ANY" && @method != request_method.to_s.upcase
@@ -105,12 +129,98 @@ module Tina4
     end
   end
 
+  # A registered WebSocket route with path pattern matching (reuses Route's compile logic)
+  class WebSocketRoute
+    attr_reader :path, :handler, :path_regex, :param_names
+
+    def initialize(path, handler)
+      @path = normalize_path(path).freeze
+      @handler = handler
+      @param_names = []
+      @path_regex = compile_pattern(@path)
+      @param_names.freeze
+    end
+
+    # Returns params hash if matched, false otherwise
+    def match?(request_path)
+      match = @path_regex.match(request_path)
+      return false unless match
+
+      if @param_names.empty?
+        {}
+      else
+        params = {}
+        @param_names.each_with_index do |param_def, i|
+          raw_value = match[i + 1]
+          params[param_def[:name]] = raw_value
+        end
+        params
+      end
+    end
+
+    private
+
+    def normalize_path(path)
+      p = path.to_s.gsub("\\", "/")
+      p = "/#{p}" unless p.start_with?("/")
+      p = p.chomp("/") unless p == "/"
+      p
+    end
+
+    def compile_pattern(path)
+      return Regexp.new("\\A/\\z") if path == "/"
+
+      parts = path.split("/").reject(&:empty?)
+      regex_parts = parts.map do |part|
+        if part =~ /\A\{(\w+)\}\z/
+          name = Regexp.last_match(1)
+          @param_names << { name: name.to_sym }
+          '([^/]+)'
+        else
+          Regexp.escape(part)
+        end
+      end
+      Regexp.new("\\A/#{regex_parts.join("/")}\\z")
+    end
+  end
+
   module Router
     class << self
       def routes
         @routes ||= []
       end
 
+      # Registered WebSocket routes
+      def ws_routes
+        @ws_routes ||= []
+      end
+
+      # Register a WebSocket route.
+      # The handler block receives (connection, event, data) where:
+      #   connection — WebSocketConnection with #send, #broadcast, #close, #params
+      #   event      — :open, :message, or :close
+      #   data       — String payload for :message, nil for :open/:close
+      def websocket(path, &block)
+        ws_route = WebSocketRoute.new(path, block)
+        ws_routes << ws_route
+        Tina4::Log.debug("WebSocket route registered: #{path}")
+        ws_route
+      end
+
+      # Find a matching WebSocket route for a given path.
+      # Returns [ws_route, params] or nil.
+      def find_ws_route(path)
+        normalized = path.gsub("\\", "/")
+        normalized = "/#{normalized}" unless normalized.start_with?("/")
+        normalized = normalized.chomp("/") unless normalized == "/"
+
+        ws_routes.each do |ws_route|
+          params = ws_route.match?(normalized)
+          return [ws_route, params] if params
+        end
+        nil
+      end
+
       # Routes indexed by HTTP method for O(1) method lookup
       def method_index
         @method_index ||= Hash.new { |h, k| h[k] = [] }
@@ -169,9 +279,26 @@ module Tina4
         nil
       end
 
+      # Register a class-based middleware globally.
+      # The class should define static before_* and/or after_* methods.
+      # Example:
+      #   class AuthMiddleware
+      #     def self.before_auth(request, response)
+      #       unless request.headers["authorization"]
+      #         return [request, response.json({ error: "Unauthorized" }, 401)]
+      #       end
+      #       [request, response]
+      #     end
+      #   end
+      #   Tina4::Router.use(AuthMiddleware)
+      def use(klass)
+        Tina4::Middleware.use(klass)
+      end
+
       def clear!
         @routes = []
         @method_index = Hash.new { |h, k| h[k] = [] }
+        @ws_routes = []
       end
 
       def group(prefix, auth_handler: nil, middleware: [], &block)