tina4ruby 3.0.0 → 3.2.1

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/templates/errors/404.twig

@@ -3,7 +3,7 @@
 <head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
-<title>404 — Not Found</title>
+<title>404 - Not Found</title>
 <style>
 * { box-sizing: border-box; margin: 0; padding: 0; }
 body { font-family: system-ui, -apple-system, sans-serif; background: #0f172a; color: #e2e8f0; min-height: 100vh; display: flex; align-items: center; justify-content: center; }
@@ -20,7 +20,7 @@ body { font-family: system-ui, -apple-system, sans-serif; background: #0f172a; c
 <div class="error-card">
     <div class="error-code">404</div>
     <div class="error-title">Page Not Found</div>
-    <div class="error-msg">The page you're looking for doesn't exist or has been moved. Check the URL and try again.</div>
+    <div class="error-msg">The page you are looking for does not exist or has been moved. Check the URL and try again.</div>
     <div class="error-path">{{ path }}</div>
     <br>
     <a href="/" class="error-home">Go Home</a>

data/lib/tina4/templates/errors/500.twig

@@ -3,7 +3,7 @@
 <head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
-<title>500 — Server Error</title>
+<title>500 - Server Error</title>
 <style>
 * { box-sizing: border-box; margin: 0; padding: 0; }
 body { font-family: system-ui, -apple-system, sans-serif; background: #0f172a; color: #e2e8f0; min-height: 100vh; display: flex; align-items: center; justify-content: center; }

data/lib/tina4/version.rb

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

data/lib/tina4.rb

@@ -106,7 +106,7 @@ module Tina4
   class << self
     attr_accessor :root_dir, :database
 
-    def print_banner(host: "0.0.0.0", port: 7147)
+    def print_banner(host: "0.0.0.0", port: 7147, server_name: nil)
       is_tty = $stdout.respond_to?(:isatty) && $stdout.isatty
       color = is_tty ? "\e[31m" : ""
       reset = is_tty ? "\e[0m" : ""
@@ -115,10 +115,24 @@ module Tina4
       log_level = (ENV["TINA4_LOG_LEVEL"] || "[TINA4_LOG_ALL]").upcase
       display = (host == "0.0.0.0" || host == "::") ? "localhost" : host
 
+      # Auto-detect server name if not provided
+      if server_name.nil?
+        if is_debug
+          server_name = "WEBrick"
+        else
+          begin
+            require "puma"
+            server_name = "puma"
+          rescue LoadError
+            server_name = "WEBrick"
+          end
+        end
+      end
+
       puts "#{color}#{BANNER}#{reset}"
       puts "  Tina4 Ruby v#{VERSION} — This is not a framework"
       puts ""
-      puts "  Server:    http://#{display}:#{port}"
+      puts "  Server:    http://#{display}:#{port} (#{server_name})"
       puts "  Swagger:   http://localhost:#{port}/swagger"
       puts "  Dashboard: http://localhost:#{port}/__dev"
       puts "  Debug:     #{is_debug ? 'ON' : 'OFF'} (Log level: #{log_level})"
@@ -155,6 +169,53 @@ module Tina4
       Tina4::Log.info("Tina4 initialized successfully")
     end
 
+    # Initialize and start the web server.
+    # This is the primary entry point for app.rb files:
+    #   Tina4.initialize!(__dir__)
+    #   Tina4.run!
+    # Or combined: Tina4.run!(__dir__)
+    def run!(root_dir = Dir.pwd)
+      initialize!(root_dir) unless @root_dir
+
+      host = ENV.fetch("HOST", ENV.fetch("TINA4_HOST", "0.0.0.0"))
+      port = ENV.fetch("PORT", ENV.fetch("TINA4_PORT", "7147")).to_i
+
+      app = Tina4::RackApp.new(root_dir: root_dir)
+      is_debug = Tina4::Env.truthy?(ENV["TINA4_DEBUG"])
+
+      # Try Puma first (production-grade), fall back to WEBrick
+      if !is_debug
+        begin
+          require "puma"
+          require "puma/configuration"
+          require "puma/launcher"
+
+          config = Puma::Configuration.new do |user_config|
+            user_config.bind "tcp://#{host}:#{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")
+          Tina4::Shutdown.setup
+
+          launcher = Puma::Launcher.new(config)
+          launcher.run
+          return
+        rescue LoadError
+          # Puma not installed, fall through to WEBrick
+        end
+      end
+
+      Tina4::Log.info("Development server: WEBrick")
+      server = Tina4::WebServer.new(app, host: host, port: port)
+      server.start
+    end
+
     # DSL methods for route registration
     # GET is public by default (matching tina4_python behavior)
     # POST/PUT/PATCH/DELETE are secured by default — use auth: false to make public