tina4ruby 3.0.0 → 3.2.1

data/lib/tina4/messenger.rb

@@ -1,38 +1,80 @@
 # frozen_string_literal: true
 
-require "net/smtp"
-require "net/imap"
+begin
+  require "net/smtp"
+rescue LoadError
+  # net-smtp gem needed on Ruby >= 4.0: gem install net-smtp
+end
+begin
+  require "net/imap"
+rescue LoadError
+  # net-imap gem needed on Ruby >= 4.0: gem install net-imap
+end
 require "base64"
 require "securerandom"
 require "time"
 
 module Tina4
+  # Tina4 Messenger — Email sending (SMTP) and reading (IMAP).
+  #
+  # Unified .env-driven configuration with constructor override.
+  # Priority: constructor params > .env (TINA4_MAIL_* with SMTP_* fallback) > sensible defaults
+  #
+  #   # .env
+  #   TINA4_MAIL_HOST=smtp.gmail.com
+  #   TINA4_MAIL_PORT=587
+  #   TINA4_MAIL_USERNAME=user@gmail.com
+  #   TINA4_MAIL_PASSWORD=app-password
+  #   TINA4_MAIL_FROM=noreply@myapp.com
+  #   TINA4_MAIL_ENCRYPTION=tls
+  #   TINA4_MAIL_IMAP_HOST=imap.gmail.com
+  #   TINA4_MAIL_IMAP_PORT=993
+  #
+  #   mail = Messenger.new                                        # reads from .env
+  #   mail = Messenger.new(host: "smtp.office365.com", port: 587) # override
+  #   mail.send(to: "user@test.com", subject: "Welcome", body: "<h1>Hello!</h1>", html: true, text: "Hello!")
+  #
   class Messenger
     attr_reader :host, :port, :username, :from_address, :from_name,
-                :imap_host, :imap_port, :use_tls
+                :imap_host, :imap_port, :use_tls, :encryption
 
-    # Initialize with SMTP config, falls back to ENV vars
+    # Initialize with SMTP config.
+    # Priority: constructor params > ENV (TINA4_MAIL_* with SMTP_* fallback) > sensible defaults
     def initialize(host: nil, port: nil, username: nil, password: nil,
-                   from_address: nil, from_name: nil, use_tls: true,
+                   from_address: nil, from_name: nil, encryption: nil, use_tls: nil,
                    imap_host: nil, imap_port: nil)
-      @host         = host         || ENV["SMTP_HOST"] || "localhost"
-      @port         = (port        || ENV["SMTP_PORT"] || 587).to_i
-      @username     = username     || ENV["SMTP_USERNAME"]
-      @password     = password     || ENV["SMTP_PASSWORD"]
-      @from_address = from_address || ENV["SMTP_FROM"] || @username
-      @from_name    = from_name    || ENV["SMTP_FROM_NAME"] || ""
-      @use_tls      = use_tls
-      @imap_host    = imap_host    || ENV["IMAP_HOST"] || @host
-      @imap_port    = (imap_port   || ENV["IMAP_PORT"] || 993).to_i
+      @host         = host         || ENV["TINA4_MAIL_HOST"]     || ENV["SMTP_HOST"]     || "localhost"
+      @port         = (port        || ENV["TINA4_MAIL_PORT"]     || ENV["SMTP_PORT"]     || 587).to_i
+      @username     = username     || ENV["TINA4_MAIL_USERNAME"] || ENV["SMTP_USERNAME"]
+      @password     = password     || ENV["TINA4_MAIL_PASSWORD"] || ENV["SMTP_PASSWORD"]
+
+      resolved_from = from_address || ENV["TINA4_MAIL_FROM"]     || ENV["SMTP_FROM"]
+      @from_address = resolved_from || @username || "noreply@localhost"
+
+      @from_name    = from_name    || ENV["TINA4_MAIL_FROM_NAME"] || ENV["SMTP_FROM_NAME"] || ""
+
+      # Encryption: constructor > .env > backward-compat use_tls > default "tls"
+      env_encryption = encryption  || ENV["TINA4_MAIL_ENCRYPTION"]
+      if env_encryption
+        @encryption = env_encryption.downcase
+      elsif !use_tls.nil?
+        @encryption = use_tls ? "tls" : "none"
+      else
+        @encryption = "tls"
+      end
+      @use_tls = %w[tls starttls].include?(@encryption)
+
+      @imap_host    = imap_host    || ENV["TINA4_MAIL_IMAP_HOST"] || ENV["IMAP_HOST"] || @host
+      @imap_port    = (imap_port   || ENV["TINA4_MAIL_IMAP_PORT"] || ENV["IMAP_PORT"] || 993).to_i
     end
 
     # Send email using Ruby's Net::SMTP
     # Returns { success: true/false, message: "...", id: "..." }
-    def send(to:, subject:, body:, html: false, cc: [], bcc: [],
+    def send(to:, subject:, body:, html: false, text: nil, cc: [], bcc: [],
              reply_to: nil, attachments: [], headers: {})
       message_id = "<#{SecureRandom.uuid}@#{@host}>"
       raw = build_message(
-        to: to, subject: subject, body: body, html: html,
+        to: to, subject: subject, body: body, html: html, text: text,
         cc: cc, bcc: bcc, reply_to: reply_to,
         attachments: attachments, headers: headers,
         message_id: message_id
@@ -179,10 +221,12 @@ module Tina4
       end
     end
 
-    def build_message(to:, subject:, body:, html:, cc:, bcc:, reply_to:,
+    def build_message(to:, subject:, body:, html:, text: nil, cc:, bcc:, reply_to:,
                       attachments:, headers:, message_id:)
       boundary = "----=_Tina4_#{SecureRandom.hex(16)}"
+      alt_boundary = "----=_Tina4Alt_#{SecureRandom.hex(16)}"
       date = Time.now.strftime("%a, %d %b %Y %H:%M:%S %z")
+      has_text_alt = !text.nil? && html
 
       parts = []
       parts << "From: #{format_address(@from_address, @from_name)}"
@@ -196,28 +240,61 @@ module Tina4
 
       headers.each { |k, v| parts << "#{k}: #{v}" }
 
-      if attachments.empty?
-        content_type = html ? "text/html" : "text/plain"
-        parts << "Content-Type: #{content_type}; charset=UTF-8"
-        parts << "Content-Transfer-Encoding: base64"
-        parts << ""
-        parts << Base64.encode64(body)
-      else
+      if !attachments.empty?
         parts << "Content-Type: multipart/mixed; boundary=\"#{boundary}\""
         parts << ""
-        # Body part
-        content_type = html ? "text/html" : "text/plain"
         parts << "--#{boundary}"
-        parts << "Content-Type: #{content_type}; charset=UTF-8"
-        parts << "Content-Transfer-Encoding: base64"
-        parts << ""
-        parts << Base64.encode64(body)
+
+        # Body part (with optional text alternative)
+        if has_text_alt
+          parts << "Content-Type: multipart/alternative; boundary=\"#{alt_boundary}\""
+          parts << ""
+          parts << "--#{alt_boundary}"
+          parts << "Content-Type: text/plain; charset=UTF-8"
+          parts << "Content-Transfer-Encoding: base64"
+          parts << ""
+          parts << Base64.encode64(text)
+          parts << "--#{alt_boundary}"
+          parts << "Content-Type: text/html; charset=UTF-8"
+          parts << "Content-Transfer-Encoding: base64"
+          parts << ""
+          parts << Base64.encode64(body)
+          parts << "--#{alt_boundary}--"
+        else
+          content_type = html ? "text/html" : "text/plain"
+          parts << "Content-Type: #{content_type}; charset=UTF-8"
+          parts << "Content-Transfer-Encoding: base64"
+          parts << ""
+          parts << Base64.encode64(body)
+        end
+
         # Attachment parts
         attachments.each do |attachment|
           parts << "--#{boundary}"
           parts.concat(build_attachment_part(attachment))
         end
         parts << "--#{boundary}--"
+      elsif has_text_alt
+        # Text alternative without attachments
+        parts << "Content-Type: multipart/alternative; boundary=\"#{alt_boundary}\""
+        parts << ""
+        parts << "--#{alt_boundary}"
+        parts << "Content-Type: text/plain; charset=UTF-8"
+        parts << "Content-Transfer-Encoding: base64"
+        parts << ""
+        parts << Base64.encode64(text)
+        parts << "--#{alt_boundary}"
+        parts << "Content-Type: text/html; charset=UTF-8"
+        parts << "Content-Transfer-Encoding: base64"
+        parts << ""
+        parts << Base64.encode64(body)
+        parts << "--#{alt_boundary}--"
+      else
+        content_type = html ? "text/html" : "text/plain"
+        parts << "Content-Type: #{content_type}; charset=UTF-8"
+        parts << "Content-Transfer-Encoding: base64"
+        parts << ""
+        parts << Base64.encode64(body)
       end
 
       parts.join("\r\n")
@@ -440,7 +517,8 @@ module Tina4
   def self.create_messenger(**options)
     dev_mode = Tina4::Env.truthy?(ENV["TINA4_DEBUG"])
 
-    smtp_configured = ENV["SMTP_HOST"] && !ENV["SMTP_HOST"].empty?
+    smtp_configured = (ENV["TINA4_MAIL_HOST"] && !ENV["TINA4_MAIL_HOST"].empty?) ||
+                      (ENV["SMTP_HOST"] && !ENV["SMTP_HOST"].empty?)
 
     if dev_mode && !smtp_configured
       mailbox_dir = options.delete(:mailbox_dir) || ENV["TINA4_MAILBOX_DIR"]
@@ -457,8 +535,8 @@ module Tina4
 
     def initialize(mailbox, **options)
       @mailbox = mailbox
-      @from_address = options[:from_address] || ENV["SMTP_FROM"] || "dev@localhost"
-      @from_name    = options[:from_name]    || ENV["SMTP_FROM_NAME"] || "Dev Mailer"
+      @from_address = options[:from_address] || ENV["TINA4_MAIL_FROM"] || ENV["SMTP_FROM"] || "dev@localhost"
+      @from_name    = options[:from_name]    || ENV["TINA4_MAIL_FROM_NAME"] || ENV["SMTP_FROM_NAME"] || "Dev Mailer"
     end
 
     def send(to:, subject:, body:, html: false, cc: [], bcc: [],

data/lib/tina4/orm.rb

@@ -85,19 +85,108 @@ module Tina4
         end
       end
 
-      def find(id_or_filter = nil, filter = nil)
+      def find(id_or_filter = nil, filter = nil, **kwargs)
+        include_list = kwargs.delete(:include)
+
         # find(id) — find by primary key
         # find(filter_hash) — find by criteria
-        if id_or_filter.is_a?(Hash)
+        # find(name: "Alice") — keyword args as filter hash
+        result = if id_or_filter.is_a?(Hash)
           find_by_filter(id_or_filter)
         elsif filter.is_a?(Hash)
           find_by_filter(filter)
+        elsif !kwargs.empty?
+          find_by_filter(kwargs)
         else
           find_by_id(id_or_filter)
         end
+
+        if include_list && result
+          instances = result.is_a?(Array) ? result : [result]
+          eager_load(instances, include_list)
+        end
+        result
+      end
+
+      # Eager load relationships for a collection of instances (prevents N+1).
+      # include is an array of relationship names, supporting dot notation for nesting.
+      def eager_load(instances, include_list)
+        return if instances.nil? || instances.empty?
+
+        # Group includes: top-level and nested
+        top_level = {}
+        include_list.each do |inc|
+          parts = inc.to_s.split(".", 2)
+          rel_name = parts[0].to_sym
+          top_level[rel_name] ||= []
+          top_level[rel_name] << parts[1] if parts.length > 1
+        end
+
+        top_level.each do |rel_name, nested|
+          rel = relationship_definitions[rel_name]
+          next unless rel
+
+          klass = Object.const_get(rel[:class_name])
+          pk = primary_key_field || :id
+
+          case rel[:type]
+          when :has_one, :has_many
+            fk = rel[:foreign_key] || "#{name.split('::').last.downcase}_id"
+            pk_values = instances.map { |inst| inst.__send__(pk) }.compact.uniq
+            next if pk_values.empty?
+
+            placeholders = pk_values.map { "?" }.join(",")
+            sql = "SELECT * FROM #{klass.table_name} WHERE #{fk} IN (#{placeholders})"
+            results = klass.db.fetch(sql, pk_values)
+            related_records = results.map { |row| klass.from_hash(row) }
+
+            # Eager load nested
+            klass.eager_load(related_records, nested) unless nested.empty?
+
+            # Group by FK
+            grouped = {}
+            related_records.each do |record|
+              fk_val = record.__send__(fk.to_sym) if record.respond_to?(fk.to_sym)
+              (grouped[fk_val] ||= []) << record
+            end
+
+            instances.each do |inst|
+              pk_val = inst.__send__(pk)
+              records = grouped[pk_val] || []
+              if rel[:type] == :has_one
+                inst.instance_variable_get(:@relationship_cache)[rel_name] = records.first
+              else
+                inst.instance_variable_get(:@relationship_cache)[rel_name] = records
+              end
+            end
+
+          when :belongs_to
+            fk = rel[:foreign_key] || "#{rel_name}_id"
+            fk_values = instances.map { |inst|
+              inst.respond_to?(fk.to_sym) ? inst.__send__(fk.to_sym) : nil
+            }.compact.uniq
+            next if fk_values.empty?
+
+            related_pk = klass.primary_key_field || :id
+            placeholders = fk_values.map { "?" }.join(",")
+            sql = "SELECT * FROM #{klass.table_name} WHERE #{related_pk} IN (#{placeholders})"
+            results = klass.db.fetch(sql, fk_values)
+            related_records = results.map { |row| klass.from_hash(row) }
+
+            klass.eager_load(related_records, nested) unless nested.empty?
+
+            lookup = {}
+            related_records.each { |r| lookup[r.__send__(related_pk)] = r }
+
+            instances.each do |inst|
+              fk_val = inst.respond_to?(fk.to_sym) ? inst.__send__(fk.to_sym) : nil
+              inst.instance_variable_get(:@relationship_cache)[rel_name] = lookup[fk_val]
+            end
+          end
+        end
       end
 
-      def where(conditions, params = [])
+      def where(conditions, params = [], include: nil)
         sql = "SELECT * FROM #{table_name}"
         if soft_delete
           sql += " WHERE (#{soft_delete_field} IS NULL OR #{soft_delete_field} = 0) AND (#{conditions})"
@@ -105,10 +194,12 @@ module Tina4
           sql += " WHERE #{conditions}"
         end
         results = db.fetch(sql, params)
-        results.map { |row| from_hash(row) }
+        instances = results.map { |row| from_hash(row) }
+        eager_load(instances, include) if include
+        instances
       end
 
-      def all(limit: nil, offset: nil, skip: nil, order_by: nil)
+      def all(limit: nil, offset: nil, skip: nil, order_by: nil, include: nil)
         sql = "SELECT * FROM #{table_name}"
         if soft_delete
           sql += " WHERE #{soft_delete_field} IS NULL OR #{soft_delete_field} = 0"
@@ -116,12 +207,16 @@ module Tina4
         sql += " ORDER BY #{order_by}" if order_by
         effective_offset = offset || skip
         results = db.fetch(sql, [], limit: limit, skip: effective_offset)
-        results.map { |row| from_hash(row) }
+        instances = results.map { |row| from_hash(row) }
+        eager_load(instances, include) if include
+        instances
       end
 
-      def select(sql, params = [], limit: nil, skip: nil)
+      def select(sql, params = [], limit: nil, skip: nil, include: nil)
         results = db.fetch(sql, params, limit: limit, skip: skip)
-        results.map { |row| from_hash(row) }
+        instances = results.map { |row| from_hash(row) }
+        eager_load(instances, include) if include
+        instances
       end
 
       def count(conditions = nil, params = [])
@@ -255,6 +350,7 @@ module Tina4
 
     def save
       @errors = []
+      @relationship_cache = {} # Clear relationship cache on save
       validate_fields
       return false unless @errors.empty?
 
@@ -342,6 +438,7 @@ module Tina4
       pk = self.class.primary_key_field || :id
       id ||= __send__(pk)
       return false unless id
+      @relationship_cache = {} # Clear relationship cache on reload
 
       result = self.class.db.fetch_one(
         "SELECT * FROM #{self.class.table_name} WHERE #{pk} = ?", [id]
@@ -366,12 +463,37 @@ module Tina4
       @errors
     end
 
-    # Convert to hash using Ruby attribute names
-    def to_h
+    # Convert to hash using Ruby attribute names.
+    # Optionally include relationships via the include keyword.
+    def to_h(include: nil)
       hash = {}
       self.class.field_definitions.each_key do |name|
         hash[name] = __send__(name)
       end
+
+      if include
+        # Group includes: top-level and nested
+        top_level = {}
+        include.each do |inc|
+          parts = inc.to_s.split(".", 2)
+          rel_name = parts[0].to_sym
+          top_level[rel_name] ||= []
+          top_level[rel_name] << parts[1] if parts.length > 1
+        end
+
+        top_level.each do |rel_name, nested|
+          next unless self.class.relationship_definitions.key?(rel_name)
+          related = __send__(rel_name)
+          if related.nil?
+            hash[rel_name] = nil
+          elsif related.is_a?(Array)
+            hash[rel_name] = related.map { |r| r.to_h(include: nested.empty? ? nil : nested) }
+          else
+            hash[rel_name] = related.to_h(include: nested.empty? ? nil : nested)
+          end
+        end
+      end
+
       hash
     end
 
@@ -385,8 +507,8 @@ module Tina4
 
     alias to_list to_array
 
-    def to_json(*_args)
-      JSON.generate(to_h)
+    def to_json(include: nil, **_args)
+      JSON.generate(to_h(include: include))
     end
 
     def to_s

data/lib/tina4/queue.rb

@@ -38,7 +38,7 @@ module Tina4
 
   class Producer
     def initialize(backend: nil)
-      @backend = backend || Tina4::QueueBackends::LiteBackend.new
+      @backend = backend || Tina4::Queue.resolve_backend
     end
 
     def publish(topic, payload)
@@ -51,17 +51,44 @@ module Tina4
     def publish_batch(topic, payloads)
       payloads.map { |p| publish(topic, p) }
     end
+
+    # Unified push method matching the cross-framework API.
+    def push(topic, payload)
+      publish(topic, payload)
+    end
   end
 
-  # Queue — convenience wrapper for queue management operations.
-  # Provides dead letter inspection, purging, and retry capabilities.
+  # Queue — unified wrapper for queue management operations.
+  # Auto-detects backend from TINA4_QUEUE_BACKEND env var.
+  #
+  # Usage:
+  #   # Auto-detect from env (default: lite/file backend)
+  #   queue = Queue.new(topic: "tasks")
+  #
+  #   # Explicit backend
+  #   queue = Queue.new(topic: "tasks", backend: :rabbitmq)
+  #
+  #   # Or pass a backend instance directly (legacy)
+  #   queue = Queue.new(topic: "tasks", backend: my_backend)
   class Queue
     attr_reader :topic, :max_retries
 
     def initialize(topic:, backend: nil, max_retries: 3)
       @topic = topic
-      @backend = backend || Tina4::QueueBackends::LiteBackend.new
       @max_retries = max_retries
+      @backend = resolve_backend_arg(backend)
+    end
+
+    # Push a job onto the queue. Returns the QueueMessage.
+    def push(payload)
+      message = QueueMessage.new(topic: @topic, payload: payload)
+      @backend.enqueue(message)
+      message
+    end
+
+    # Pop the next available job. Returns QueueMessage or nil.
+    def pop
+      @backend.dequeue(@topic)
     end
 
     # Get dead letter jobs — messages that exceeded max retries.
@@ -87,12 +114,105 @@ module Tina4
     def size
       @backend.size(@topic)
     end
+
+    # Get the underlying backend instance.
+    def backend
+      @backend
+    end
+
+    # Resolve the default backend from env vars.
+    # Class method so Producer can also use it.
+    def self.resolve_backend(name = nil)
+      chosen = name || ENV.fetch("TINA4_QUEUE_BACKEND", "lite").downcase.strip
+
+      case chosen.to_s
+      when "lite", "file", "default"
+        Tina4::QueueBackends::LiteBackend.new
+      when "rabbitmq"
+        config = resolve_rabbitmq_config
+        Tina4::QueueBackends::RabbitmqBackend.new(config)
+      when "kafka"
+        config = resolve_kafka_config
+        Tina4::QueueBackends::KafkaBackend.new(config)
+      else
+        raise ArgumentError, "Unknown queue backend: #{chosen.inspect}. Use 'lite', 'rabbitmq', or 'kafka'."
+      end
+    end
+
+    private
+
+    def resolve_backend_arg(backend)
+      # If a backend instance is passed directly (legacy), use it
+      return backend if backend && !backend.is_a?(Symbol) && !backend.is_a?(String)
+      # If a symbol or string name is passed, resolve it
+      Queue.resolve_backend(backend)
+    end
+
+    def self.resolve_rabbitmq_config
+      config = {}
+      url = ENV["TINA4_QUEUE_URL"]
+      if url
+        config = parse_amqp_url(url)
+      end
+      config[:host] ||= ENV.fetch("TINA4_RABBITMQ_HOST", "localhost")
+      config[:port] ||= (ENV["TINA4_RABBITMQ_PORT"] || 5672).to_i
+      config[:username] ||= ENV.fetch("TINA4_RABBITMQ_USERNAME", "guest")
+      config[:password] ||= ENV.fetch("TINA4_RABBITMQ_PASSWORD", "guest")
+      config[:vhost] ||= ENV.fetch("TINA4_RABBITMQ_VHOST", "/")
+      config
+    end
+
+    def self.resolve_kafka_config
+      config = {}
+      url = ENV["TINA4_QUEUE_URL"]
+      if url
+        config[:brokers] = url.sub("kafka://", "")
+      end
+      brokers = ENV["TINA4_KAFKA_BROKERS"]
+      config[:brokers] = brokers if brokers
+      config[:brokers] ||= "localhost:9092"
+      config[:group_id] = ENV.fetch("TINA4_KAFKA_GROUP_ID", "tina4_consumer_group")
+      config
+    end
+
+    def self.parse_amqp_url(url)
+      config = {}
+      url = url.sub("amqp://", "").sub("amqps://", "")
+
+      if url.include?("@")
+        creds, rest = url.split("@", 2)
+        if creds.include?(":")
+          config[:username], config[:password] = creds.split(":", 2)
+        else
+          config[:username] = creds
+        end
+      else
+        rest = url
+      end
+
+      if rest.include?("/")
+        hostport, vhost = rest.split("/", 2)
+        config[:vhost] = vhost.start_with?("/") ? vhost : "/#{vhost}" if vhost && !vhost.empty?
+      else
+        hostport = rest
+      end
+
+      if hostport.include?(":")
+        host, port = hostport.split(":", 2)
+        config[:host] = host
+        config[:port] = port.to_i
+      elsif hostport && !hostport.empty?
+        config[:host] = hostport
+      end
+
+      config
+    end
   end
 
   class Consumer
     def initialize(topic:, backend: nil, max_retries: 3)
       @topic = topic
-      @backend = backend || Tina4::QueueBackends::LiteBackend.new
+      @backend = backend || Tina4::Queue.resolve_backend
       @max_retries = max_retries
       @handlers = []
       @running = false

data/lib/tina4/rack_app.rb

@@ -90,7 +90,7 @@ module Tina4
 
       rack_response
     rescue => e
-      handle_500(e)
+      handle_500(e, env)
     end
 
     private
@@ -112,8 +112,21 @@ module Tina4
         end
       end
 
-      # Execute handler
-      result = route.handler.call(request, response)
+      # Execute handler — support (), (response), (request), or (request, response) signatures
+      # When 1 param: if named :request or :req, pass request; otherwise pass response
+      result = case route.handler.arity
+      when 0
+        route.handler.call
+      when 1
+        param_name = route.handler.parameters.first&.last
+        if param_name == :request || param_name == :req
+          route.handler.call(request)
+        else
+          route.handler.call(response)
+        end
+      else
+        route.handler.call(request, response)
+      end
 
       # Template rendering: when a template is set and the handler returned a Hash,
       # render the template with the hash as data and return the HTML response.
@@ -388,12 +401,12 @@ module Tina4
       [200, { "content-type" => "text/html; charset=utf-8" }, [html]]
     end
 
-    def handle_500(error)
+    def handle_500(error, env = nil)
       Tina4::Log.error("500 Internal Server Error: #{error.message}")
       Tina4::Log.error(error.backtrace&.first(10)&.join("\n"))
       if dev_mode?
         # Rich error overlay with stack trace, source context, and line numbers
-        body = Tina4::ErrorOverlay.render(error)
+        body = Tina4::ErrorOverlay.render(error, request: env)
       else
         body = Tina4::Template.render_error(500, {
           "error_message" => "#{error.message}\n#{error.backtrace&.first(10)&.join("\n")}",