tina4ruby 3.10.76 → 3.10.84

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8be724e92f1d0078e9677ae08fa89545dcacf6bc1145ba6db2b86e86da307b3f
-  data.tar.gz: ba5369ac9f262e7991af7433291559715ce92e18fcbd0c9a40a641683bd8b607
+  metadata.gz: 85d4f3e7d47f44f07e2ab8780a19dd082dcc05e0ba7551e3e8df4b486faa151e
+  data.tar.gz: d8662f6770852844ff213be6f1d57329bec5cc243f2d02f2690a04f248c11bf3
 SHA512:
-  metadata.gz: 32d9308387bd2c508f6bf504c7af27252c31280f6cc53e7fc1da14891f6a0c59497fa232cff6517c12d52925bf6e58601cd43206fd12f5928317465a8641559d
-  data.tar.gz: 53644965ad58260075a26c35cc6f8d2cc1044e168077e6145ca21cd44cf0d797232dd0aba3e895eaffa5b6b33abe9f601e79dd5f465499dae1c205608751a532
+  metadata.gz: 3955df89a811694cbadb74f30c8f0cebed30e9626b735a4cc6ad172c08acaf2e0b33458593c3700416b11a9b453e76d604a0a34a09b2fff46ec0610d0f58043f
+  data.tar.gz: '0103297c9fe0bcde8be0d82b5c71a9fef458f467c16d9ee654c5d806ae4ea82bff69430ca438da5cee7d12c7d33c721bd0bc6e819e06bd8f6de7e85ab0e1141c'

data/lib/tina4/auth.rb

@@ -12,7 +12,7 @@ module Tina4
       def setup(root_dir = Dir.pwd)
         @keys_dir = File.join(root_dir, KEYS_DIR)
         FileUtils.mkdir_p(@keys_dir)
-        ensure_keys unless use_hmac?
+        ensure_keys
       end
 
       # ── HS256 helpers (stdlib only, no gem) ──────────────────────
@@ -107,19 +107,19 @@ module Tina4
       end
 
 
-      def valid_token(token)
+      def valid_token(token) # -> bool
         if use_hmac?
-          hmac_decode(token, hmac_secret)
+          !hmac_decode(token, hmac_secret).nil?
         else
           ensure_keys
           require "jwt"
-          decoded = JWT.decode(token, public_key, true, algorithm: "RS256")
-          decoded[0]
+          JWT.decode(token, public_key, true, algorithm: "RS256")
+          true
         end
       rescue JWT::ExpiredSignature
-        nil
+        false
       rescue JWT::DecodeError
-        nil
+        false
       end
 
       def valid_token_detail(token)
@@ -174,9 +174,10 @@ module Tina4
       end
 
       def refresh_token(token, expires_in: 60)
-        payload = valid_token(token)
-        return nil unless payload
+        return nil unless valid_token(token)
 
+        payload = get_payload(token)
+        return nil unless payload
         payload = payload.reject { |k, _| %w[iat exp nbf].include?(k) }
         get_token(payload, expires_in: expires_in)
       end
@@ -193,7 +194,7 @@ module Tina4
           return { "api_key" => true }
         end
 
-        valid_token(token)
+        valid_token(token) ? get_payload(token) : nil
       end
 
       def validate_api_key(provided, expected: nil)
@@ -227,9 +228,8 @@ module Tina4
             return true
           end
 
-          payload = valid_token(token)
-          if payload
-            env["tina4.auth"] = payload
+          if valid_token(token)
+            env["tina4.auth"] = get_payload(token)
             true
           else
             false
@@ -258,8 +258,6 @@ module Tina4
       private
 
       def ensure_keys
-        return if use_hmac?
-
         @keys_dir ||= File.join(Dir.pwd, KEYS_DIR)
         FileUtils.mkdir_p(@keys_dir)
         unless File.exist?(private_key_path) && File.exist?(public_key_path)
@@ -289,7 +287,7 @@ module Tina4
         return true if auth_header.empty?
 
         if auth_header =~ /\ABearer\s+(.+)\z/i
-          !valid_token(Regexp.last_match(1)).nil?
+          valid_token(Regexp.last_match(1))
         else
           false
         end

data/lib/tina4/auto_crud.rb

@@ -97,7 +97,7 @@ module Tina4
         Tina4::Router.add_route("GET", "#{prefix}/#{table}/{id}", proc { |req, res|
           begin
             id = req.params["id"]
-            record = model_class.find(id.to_i)
+            record = model_class.find_by_id(id.to_i)
             if record
               res.json({ data: record.to_h })
             else
@@ -140,7 +140,7 @@ module Tina4
         Tina4::Router.add_route("PUT", "#{prefix}/#{table}/{id}", proc { |req, res|
           begin
             id = req.params["id"]
-            record = model_class.find(id.to_i)
+            record = model_class.find_by_id(id.to_i)
             unless record
               next res.json({ error: "Not found" }, status: 404)
             end
@@ -178,7 +178,7 @@ module Tina4
         Tina4::Router.add_route("DELETE", "#{prefix}/#{table}/{id}", proc { |req, res|
           begin
             id = req.params["id"]
-            record = model_class.find(id.to_i)
+            record = model_class.find_by_id(id.to_i)
             unless record
               next res.json({ error: "Not found" }, status: 404)
             end

data/lib/tina4/dev_admin.rb

@@ -631,16 +631,12 @@ module Tina4
 
           # Execute all statements (single write or multi-statement batch)
           total_affected = 0
-          db.start_transaction if db.respond_to?(:start_transaction)
-          begin
-            statements.each do |stmt|
-              result = db.execute(stmt)
-              total_affected += (result.respond_to?(:affected_rows) ? result.affected_rows : 0)
+          statements.each do |stmt|
+            result = db.execute(stmt)
+            if result == false
+              return { error: db.get_error || "Statement failed: #{stmt}" }
             end
-            db.commit if db.respond_to?(:commit)
-          rescue => e
-            db.rollback if db.respond_to?(:rollback)
-            return { error: e.message }
+            total_affected += (result.respond_to?(:affected_rows) ? result.affected_rows : 0)
           end
 
           { affected: total_affected, success: true }

data/lib/tina4/graphql.rb

@@ -130,7 +130,7 @@ module Tina4
       add_query(table_lower, type: type_name,
                 args: { pk_field => { type: "ID!" } },
                 description: "Fetch a single #{model_name} by #{pk_field}") do |_root, args, _ctx|
-        record = klass.find(args[pk_field])
+        record = klass.find_by_id(args[pk_field])
         record&.to_hash
       end
 
@@ -158,7 +158,7 @@ module Tina4
       add_mutation("update#{model_name}", type: type_name,
                    args: { pk_field => { type: "ID!" }, "input" => { type: "#{type_name}Input!" } },
                    description: "Update an existing #{model_name}") do |_root, args, _ctx|
-        record = klass.find(args[pk_field])
+        record = klass.find_by_id(args[pk_field])
         return nil unless record
         (args["input"] || {}).each { |k, v| record.send(:"#{k}=", v) if record.respond_to?(:"#{k}=") }
         record.save
@@ -169,7 +169,7 @@ module Tina4
       add_mutation("delete#{model_name}", type: "Boolean",
                    args: { pk_field => { type: "ID!" } },
                    description: "Delete a #{model_name} by #{pk_field}") do |_root, args, _ctx|
-        record = klass.find(args[pk_field])
+        record = klass.find_by_id(args[pk_field])
         return false unless record
         record.delete
         true
@@ -769,7 +769,7 @@ module Tina4
     end
 
     # Return schema as GraphQL SDL string.
-    def schema
+    def schema_sdl
       sdl = ""
       @schema.types.each do |name, type_obj|
         sdl += "type #{name} {\n"

data/lib/tina4/job.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+require "json"
+require "securerandom"
+
+module Tina4
+  class Job
+    attr_reader :id, :topic, :payload, :created_at, :attempts, :priority, :available_at
+    attr_accessor :status
+
+    def initialize(topic:, payload:, id: nil, priority: 0, available_at: nil, attempts: 0)
+      @id = id || SecureRandom.uuid
+      @topic = topic
+      @payload = payload
+      @created_at = Time.now
+      @attempts = attempts
+      @priority = priority
+      @available_at = available_at
+      @status = :pending
+    end
+
+    # Re-queue this message with incremented attempts.
+    # Delegates to the queue's backend via the queue reference.
+    def retry(queue:, delay_seconds: 0)
+      @attempts += 1
+      @status = :pending
+      @available_at = delay_seconds > 0 ? Time.now + delay_seconds : nil
+      queue.backend.enqueue(self)
+      self
+    end
+
+    def to_array
+      [@id, @topic, @payload, @priority, @attempts]
+    end
+
+    def to_hash
+      h = {
+        id: @id,
+        topic: @topic,
+        payload: @payload,
+        created_at: @created_at.iso8601,
+        attempts: @attempts,
+        status: @status,
+        priority: @priority
+      }
+      h[:available_at] = @available_at.iso8601 if @available_at
+      h
+    end
+
+    def to_json(*_args)
+      JSON.generate(to_hash)
+    end
+
+    def increment_attempts!
+      @attempts += 1
+    end
+
+    # Mark this job as completed.
+    def complete
+      @status = :completed
+    end
+
+    # Mark this job as failed with a reason.
+    def fail(reason = "")
+      @status = :failed
+      @error = reason
+      @attempts += 1
+    end
+
+    # Reject this job with a reason. Alias for fail().
+    def reject(reason = "")
+      fail(reason)
+    end
+
+    attr_reader :error
+  end
+end

data/lib/tina4/middleware.rb

@@ -307,8 +307,7 @@ module Tina4
         if auth_header.start_with?("Bearer ")
           bearer_token = auth_header[7..].strip
           unless bearer_token.empty?
-            payload = Tina4::Auth.valid_token(bearer_token)
-            return [request, response] if payload
+            return [request, response] if Tina4::Auth.valid_token(bearer_token)
           end
         end
 
@@ -344,14 +343,13 @@ module Tina4
         end
 
         # Validate the token
-        payload = Tina4::Auth.valid_token(token.to_s)
-
-        if payload.nil?
+        unless Tina4::Auth.valid_token(token.to_s)
           response.json({ error: "CSRF_INVALID", message: "Invalid or missing form token" }, 403)
           return [request, response]
         end
 
         # Session binding — if token has session_id, verify it matches
+        payload = Tina4::Auth.get_payload(token.to_s) || {}
         token_session_id = payload["session_id"]
         if token_session_id
           current_session_id = nil

data/lib/tina4/migration.rb

@@ -87,6 +87,23 @@ module Tina4
       filepath
     end
 
+    # Get list of applied migration records (public alias for completed_migrations)
+    def get_applied
+      completed_migrations
+    end
+
+    # Get list of pending migration filenames (public alias for pending_migrations)
+    def get_pending
+      pending_migrations.map { |f| File.basename(f) }
+    end
+
+    # Get all migration files on disk, excluding .down files
+    def get_files
+      migration_files = Dir.glob(File.join(@migrations_dir, "*.sql")).reject { |f| f.end_with?(".down.sql") }
+      migration_files += Dir.glob(File.join(@migrations_dir, "*.rb"))
+      migration_files.map { |f| File.basename(f) }.sort
+    end
+
     private
 
     # Resolve migrations directory: prefer src/migrations, fall back to migrations/
@@ -288,7 +305,10 @@ module Tina4
           Tina4::Log.info("Migration #{File.basename(file)}: #{skip_reason}")
           next
         end
-        @db.execute(stmt)
+        result = @db.execute(stmt)
+        if result == false
+          raise RuntimeError, @db.get_error || "SQL execution failed: #{stmt}"
+        end
       end
     end
 

data/lib/tina4/orm.rb

@@ -61,13 +61,25 @@ module Tina4
         @auto_map = val
       end
 
+      # Auto-CRUD flag: when set to true, registers this model for CRUD route generation
+      def auto_crud
+        @auto_crud || false
+      end
+
+      def auto_crud=(val)
+        @auto_crud = val
+        if val
+          Tina4::AutoCrud.register(self) if defined?(Tina4::AutoCrud)
+        end
+      end
+
       # Relationship definitions
       def relationship_definitions
         @relationship_definitions ||= {}
       end
 
       # has_one :profile, class_name: "Profile", foreign_key: "user_id"
-      def has_one(name, class_name: nil, foreign_key: nil)
+      def has_one(name, class_name: nil, foreign_key: nil) # -> nil
         relationship_definitions[name] = {
           type: :has_one,
           class_name: class_name || name.to_s.split("_").map(&:capitalize).join,
@@ -80,7 +92,7 @@ module Tina4
       end
 
       # has_many :posts, class_name: "Post", foreign_key: "user_id"
-      def has_many(name, class_name: nil, foreign_key: nil)
+      def has_many(name, class_name: nil, foreign_key: nil) # -> nil
         relationship_definitions[name] = {
           type: :has_many,
           class_name: class_name || name.to_s.sub(/s$/, "").split("_").map(&:capitalize).join,
@@ -93,7 +105,7 @@ module Tina4
       end
 
       # belongs_to :user, class_name: "User", foreign_key: "user_id"
-      def belongs_to(name, class_name: nil, foreign_key: nil)
+      def belongs_to(name, class_name: nil, foreign_key: nil) # -> nil
         relationship_definitions[name] = {
           type: :belongs_to,
           class_name: class_name || name.to_s.split("_").map(&:capitalize).join,
@@ -111,31 +123,46 @@ module Tina4
       #   results = User.query.where("active = ?", [1]).order_by("name").get
       #
       # @return [Tina4::QueryBuilder]
-      def query
+      def query # -> QueryBuilder
         QueryBuilder.from(table_name, db: db)
       end
 
-      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
-        # 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)
+      # Find records by filter dict. Always returns an array.
+      #
+      # Usage:
+      #   User.find(name: "Alice")                  → [User, ...]
+      #   User.find({age: 18}, limit: 10)           → [User, ...]
+      #   User.find(order_by: "name ASC")            → [User, ...]
+      #   User.find                                  → all records
+      #
+      # Use find_by_id(id) for single-record primary key lookup.
+      def find(filter = {}, limit: 100, offset: 0, order_by: nil, include: nil, **extra_filter) # -> list[Self]
+        # Integer or string-digit argument → primary key lookup (returns single record or nil)
+        return find_by_id(filter) if filter.is_a?(Integer)
+
+        # Merge keyword-style filters: find(name: "Alice") and find({name: "Alice"}) both work
+        filter = filter.merge(extra_filter) unless extra_filter.empty?
+        conditions = []
+        params = []
+
+        filter.each do |key, value|
+          col = field_mapping[key.to_s] || key
+          conditions << "#{col} = ?"
+          params << value
         end
 
-        if include_list && result
-          instances = result.is_a?(Array) ? result : [result]
-          eager_load(instances, include_list)
+        if soft_delete
+          conditions << "(#{soft_delete_field} IS NULL OR #{soft_delete_field} = 0)"
         end
-        result
+
+        sql = "SELECT * FROM #{table_name}"
+        sql += " WHERE #{conditions.join(' AND ')}" unless conditions.empty?
+        sql += " ORDER BY #{order_by}" if order_by
+
+        results = db.fetch(sql, params, limit: limit, offset: offset)
+        instances = results.map { |row| from_hash(row) }
+        eager_load(instances, include) if include
+        instances
       end
 
       # Eager load relationships for a collection of instances (prevents N+1).
@@ -216,7 +243,7 @@ module Tina4
         end
       end
 
-      def where(conditions, params = [], include: nil)
+      def where(conditions, params = [], include: nil) # -> list[Self]
         sql = "SELECT * FROM #{table_name}"
         if soft_delete
           sql += " WHERE (#{soft_delete_field} IS NULL OR #{soft_delete_field} = 0) AND (#{conditions})"
@@ -229,7 +256,7 @@ module Tina4
         instances
       end
 
-      def all(limit: nil, offset: nil, order_by: nil, include: nil)
+      def all(limit: nil, offset: nil, order_by: nil, include: nil) # -> list[Self]
         sql = "SELECT * FROM #{table_name}"
         if soft_delete
           sql += " WHERE #{soft_delete_field} IS NULL OR #{soft_delete_field} = 0"
@@ -241,19 +268,19 @@ module Tina4
         instances
       end
 
-      def select(sql, params = [], limit: nil, offset: nil, include: nil)
+      def select(sql, params = [], limit: nil, offset: nil, include: nil) # -> list[Self]
         results = db.fetch(sql, params, limit: limit, offset: offset)
         instances = results.map { |row| from_hash(row) }
         eager_load(instances, include) if include
         instances
       end
 
-      def select_one(sql, params = [], include: nil)
+      def select_one(sql, params = [], include: nil) # -> Self | nil
         results = select(sql, params, limit: 1, include: include)
         results.first
       end
 
-      def count(conditions = nil, params = [])
+      def count(conditions = nil, params = []) # -> int
         sql = "SELECT COUNT(*) as cnt FROM #{table_name}"
         where_parts = []
         if soft_delete
@@ -265,25 +292,48 @@ module Tina4
         result[:cnt].to_i
       end
 
-      def create(attributes = {})
+      def create(attributes = {}) # -> Self
         instance = new(attributes)
         instance.save
         instance
       end
 
-      def find_or_fail(id)
+      def find_or_fail(id) # -> Self
         result = find(id)
         raise "#{name} with #{primary_key_field || :id}=#{id} not found" if result.nil?
         result
       end
 
-      def with_trashed(conditions = "1=1", params = [], limit: 20, offset: 0)
+      # Return true if a record with the given primary key exists.
+      def exists(pk_value) # -> bool
+        find(pk_value) != nil
+      end
+
+      # SQL query with in-memory result caching.
+      # Results are cached by (class, sql, params, limit, offset) for +ttl+ seconds.
+      def cached(sql, params = [], ttl: 60, limit: 20, offset: 0, include: nil) # -> list[Self]
+        @_query_cache ||= Tina4::QueryCache.new(default_ttl: ttl, max_size: 500)
+        cache_key = Tina4::QueryCache.query_key("#{name}:#{sql}", params + [limit, offset])
+        hit = @_query_cache.get(cache_key)
+        return hit unless hit.nil?
+
+        results = select(sql, params, limit: limit, offset: offset, include: include)
+        @_query_cache.set(cache_key, results, ttl: ttl, tags: [name])
+        results
+      end
+
+      # Clear all cached query results for this model.
+      def clear_cache # -> nil
+        @_query_cache&.clear_tag(name)
+      end
+
+      def with_trashed(conditions = "1=1", params = [], limit: 20, offset: 0) # -> list[Self]
         sql = "SELECT * FROM #{table_name} WHERE #{conditions}"
         results = db.fetch(sql, params, limit: limit, offset: offset)
         results.map { |row| from_hash(row) }
       end
 
-      def create_table
+      def create_table # -> bool
         return true if db.table_exists?(table_name)
 
         type_map = {
@@ -324,7 +374,7 @@ module Tina4
         true
       end
 
-      def scope(name, filter_sql, params = [])
+      def scope(name, filter_sql, params = []) # -> nil
         define_singleton_method(name) do |limit: 20, offset: 0|
           where(filter_sql, params)
         end
@@ -343,6 +393,16 @@ module Tina4
         instance
       end
 
+      # Find a single record by primary key. Returns instance or nil.
+      def find_by_id(id) # -> Self | nil
+        pk = primary_key_field || :id
+        sql = "SELECT * FROM #{table_name} WHERE #{pk} = ?"
+        if soft_delete
+          sql += " AND (#{soft_delete_field} IS NULL OR #{soft_delete_field} = 0)"
+        end
+        select_one(sql, [id])
+      end
+
       private
 
       def auto_discover_db
@@ -352,15 +412,6 @@ module Tina4
         Tina4.database
       end
 
-      def find_by_id(id)
-        pk = primary_key_field || :id
-        sql = "SELECT * FROM #{table_name} WHERE #{pk} = ?"
-        if soft_delete
-          sql += " AND (#{soft_delete_field} IS NULL OR #{soft_delete_field} = 0)"
-        end
-        select_one(sql, [id])
-      end
-
       def find_by_filter(filter)
         where_parts = filter.keys.map { |k| "#{k} = ?" }
         sql = "SELECT * FROM #{table_name} WHERE #{where_parts.join(' AND ')}"
@@ -388,7 +439,7 @@ module Tina4
       end
     end
 
-    def save
+    def save # -> Self | bool
       @errors = []
       @relationship_cache = {} # Clear relationship cache on save
       validate_fields
@@ -414,13 +465,13 @@ module Tina4
           @persisted = true
         end
       end
-      self
+      true
     rescue => e
       @errors << e.message
       false
     end
 
-    def delete
+    def delete # -> bool
       pk = self.class.primary_key_field || :id
       pk_value = __send__(pk)
       return false unless pk_value
@@ -440,7 +491,7 @@ module Tina4
       true
     end
 
-    def force_delete
+    def force_delete # -> bool
       pk = self.class.primary_key_field || :id
       pk_value = __send__(pk)
       raise "Cannot delete: no primary key value" unless pk_value
@@ -452,7 +503,7 @@ module Tina4
       true
     end
 
-    def restore
+    def restore # -> bool
       raise "Model does not support soft delete" unless self.class.soft_delete
 
       pk = self.class.primary_key_field || :id
@@ -470,7 +521,7 @@ module Tina4
       true
     end
 
-    def validate
+    def validate # -> list[str]
       errors = []
       self.class.field_definitions.each do |name, opts|
         value = __send__(name)
@@ -483,8 +534,29 @@ module Tina4
 
     # Load a record into this instance via select_one.
     # Returns true if found and loaded, false otherwise.
-    def load(sql, params = [], include: nil)
+    # Load a record into this instance.
+    #
+    # Usage:
+    #   orm.id = 1; orm.load          — uses PK already set
+    #   orm.load("id = ?", [1])       — filter with params
+    #   orm.load("id = 1")            — filter string
+    #
+    # Returns true if a record was found, false otherwise.
+    def load(filter = nil, params = [], include: nil) # -> bool
       @relationship_cache = {}
+      table = self.class.table_name
+
+      if filter.nil?
+        pk = self.class.primary_key
+        pk_col = self.class.field_mapping[pk.to_s] || pk
+        pk_value = __send__(pk)
+        return false if pk_value.nil?
+        sql = "SELECT * FROM #{table} WHERE #{pk_col} = ?"
+        params = [pk_value]
+      else
+        sql = "SELECT * FROM #{table} WHERE #{filter}"
+      end
+
       result = self.class.select_one(sql, params, include: include)
       return false unless result
 
@@ -508,7 +580,7 @@ module Tina4
 
     # Convert to hash using Ruby attribute names.
     # Optionally include relationships via the include keyword.
-    def to_h(include: nil)
+    def to_h(include: nil) # -> dict
       hash = {}
       self.class.field_definitions.each_key do |name|
         hash[name] = __send__(name)
@@ -545,13 +617,13 @@ module Tina4
     alias to_assoc to_h
     alias to_object to_h
 
-    def to_array
+    def to_array # -> list
       to_h.values
     end
 
     alias to_list to_array
 
-    def to_json(include: nil, **_args)
+    def to_json(include: nil, **_args) # -> str
       JSON.generate(to_h(include: include))
     end
 
@@ -634,7 +706,7 @@ module Tina4
       fk_value = __send__(fk.to_sym) if respond_to?(fk.to_sym)
       return nil unless fk_value
 
-      @relationship_cache[name] = klass.find(fk_value)
+      @relationship_cache[name] = klass.find_by_id(fk_value)
     end
 
     public
@@ -671,7 +743,7 @@ module Tina4
       fk_value = respond_to?(fk.to_sym) ? __send__(fk.to_sym) : nil
       return nil unless fk_value
 
-      related_class.find(fk_value)
+      related_class.find_by_id(fk_value)
     end
 
     # Instance-level aliases matching Python/PHP/Node.js naming

data/lib/tina4/queue.rb

@@ -1,75 +1,9 @@
 # frozen_string_literal: true
 require "json"
 require "securerandom"
+require_relative "job"
 
 module Tina4
-  class QueueMessage
-    attr_reader :id, :topic, :payload, :created_at, :attempts, :priority, :available_at
-    attr_accessor :status
-
-    def initialize(topic:, payload:, id: nil, priority: 0, available_at: nil, attempts: 0)
-      @id = id || SecureRandom.uuid
-      @topic = topic
-      @payload = payload
-      @created_at = Time.now
-      @attempts = attempts
-      @priority = priority
-      @available_at = available_at
-      @status = :pending
-    end
-
-    # Re-queue this message with incremented attempts.
-    # Delegates to the queue's backend via the queue reference.
-    def retry(queue:, delay_seconds: 0)
-      @attempts += 1
-      @status = :pending
-      @available_at = delay_seconds > 0 ? Time.now + delay_seconds : nil
-      queue.backend.enqueue(self)
-      self
-    end
-
-    def to_hash
-      h = {
-        id: @id,
-        topic: @topic,
-        payload: @payload,
-        created_at: @created_at.iso8601,
-        attempts: @attempts,
-        status: @status,
-        priority: @priority
-      }
-      h[:available_at] = @available_at.iso8601 if @available_at
-      h
-    end
-
-    def to_json(*_args)
-      JSON.generate(to_hash)
-    end
-
-    def increment_attempts!
-      @attempts += 1
-    end
-
-    # Mark this job as completed.
-    def complete
-      @status = :completed
-    end
-
-    # Mark this job as failed with a reason.
-    def fail(reason = "")
-      @status = :failed
-      @error = reason
-      @attempts += 1
-    end
-
-    # Reject this job with a reason. Alias for fail().
-    def reject(reason = "")
-      fail(reason)
-    end
-
-    attr_reader :error
-  end
-
   # Queue — unified wrapper for queue management operations.
   # Auto-detects backend from TINA4_QUEUE_BACKEND env var.
   #
@@ -91,43 +25,61 @@ module Tina4
       @backend = resolve_backend_arg(backend)
     end
 
-    # Push a job onto the queue. Returns the QueueMessage.
+    # Push a job onto the queue. Returns the Job.
     # priority: higher-priority messages are dequeued first (default 0).
     # delay_seconds: delay before the message becomes available (default 0).
     def push(payload, priority: 0, delay_seconds: 0)
       available_at = delay_seconds > 0 ? Time.now + delay_seconds : nil
-      message = QueueMessage.new(topic: @topic, payload: payload, priority: priority, available_at: available_at)
+      message = Job.new(topic: @topic, payload: payload, priority: priority, available_at: available_at)
       @backend.enqueue(message)
       message
     end
 
-    # Pop the next available job. Returns QueueMessage or nil.
-    def pop
+    # Pop the next available job. Returns Job or nil.
+    def pop # -> Job|None
       @backend.dequeue(@topic)
     end
 
+    # Clear all pending jobs from this queue's topic. Returns count removed.
+    def clear # -> int
+      return 0 unless @backend.respond_to?(:clear)
+      @backend.clear(@topic)
+    end
+
+    # Get jobs that failed but are still eligible for retry (under max_retries).
+    def failed # -> list[dict]
+      return [] unless @backend.respond_to?(:failed)
+      @backend.failed(@topic, max_retries: @max_retries)
+    end
+
+    # Retry failed jobs on this queue's topic. Returns true if re-queued.
+    def retry(delay_seconds = 0) # -> bool
+      return false unless @backend.respond_to?(:retry_job)
+      @backend.retry_job(@topic, delay_seconds: delay_seconds)
+    end
+
     # Get dead letter jobs — messages that exceeded max retries.
-    def dead_letters
+    def dead_letters # -> list[dict]
       return [] unless @backend.respond_to?(:dead_letters)
       @backend.dead_letters(@topic, max_retries: @max_retries)
     end
 
     # Delete messages by status (completed, failed, dead).
-    def purge(status)
+    def purge(status) # -> int
       return 0 unless @backend.respond_to?(:purge)
       @backend.purge(@topic, status)
     end
 
     # Re-queue failed messages (under max_retries) back to pending.
     # Returns the number of jobs re-queued.
-    def retry_failed
+    def retry_failed # -> int
       return 0 unless @backend.respond_to?(:retry_failed)
       @backend.retry_failed(@topic, max_retries: @max_retries)
     end
 
     # Produce a message onto a topic. Convenience wrapper around push().
-    def produce(topic, payload)
-      message = QueueMessage.new(topic: topic, payload: payload)
+    def produce(topic, payload, priority = 0)
+      message = Job.new(topic: topic, payload: payload, priority: priority)
       @backend.enqueue(message)
       message
     end
@@ -156,7 +108,7 @@ module Tina4
     #   queue.consume("emails", poll_interval: 5) { |job| process(job) }
     #   queue.consume("emails", id: "abc-123") { |job| process(job) }
     #
-    def consume(topic = nil, id: nil, poll_interval: 1.0, &block)
+    def consume(topic = nil, id: nil, poll_interval: 1.0, iterations: 0, &block)
       topic ||= @topic
 
       if id
@@ -170,7 +122,9 @@ module Tina4
 
       # poll_interval=0 → single-pass drain (returns when empty)
       # poll_interval>0 → long-running poll (sleeps when empty, never returns)
+      # iterations>0    → stop after consuming N jobs
       if block_given?
+        consumed = 0
         loop do
           job = @backend.dequeue(topic)
           if job.nil?
@@ -179,9 +133,12 @@ module Tina4
             next
           end
           yield job
+          consumed += 1
+          break if iterations > 0 && consumed >= iterations
         end
       else
         Enumerator.new do |yielder|
+          consumed = 0
           loop do
             job = @backend.dequeue(topic)
             if job.nil?
@@ -190,15 +147,17 @@ module Tina4
               next
             end
             yielder << job
+            consumed += 1
+            break if iterations > 0 && consumed >= iterations
           end
         end
       end
     end
 
     # Pop a specific job by ID from the queue.
-    def pop_by_id(topic, id)
+    def pop_by_id(id)
       return nil unless @backend.respond_to?(:find_by_id)
-      @backend.find_by_id(topic, id)
+      @backend.find_by_id(@topic, id)
     end
 
     # Get the number of messages by status.

data/lib/tina4/queue_backends/kafka_backend.rb

@@ -45,7 +45,7 @@ module Tina4
         data = JSON.parse(msg.payload)
         @last_message = msg
 
-        Tina4::QueueMessage.new(
+        Tina4::Job.new(
           topic: data["topic"],
           payload: data["payload"],
           id: data["id"]
@@ -63,7 +63,7 @@ module Tina4
       end
 
       def dead_letter(message)
-        dead_msg = Tina4::QueueMessage.new(
+        dead_msg = Tina4::Job.new(
           topic: "#{message.topic}.dead_letter",
           payload: message.payload,
           id: message.id

data/lib/tina4/queue_backends/lite_backend.rb

@@ -52,7 +52,7 @@ module Tina4
           File.delete(chosen[:file])
           data = chosen[:data]
 
-          Tina4::QueueMessage.new(
+          Tina4::Job.new(
             topic: data["topic"] || topic.to_s,
             payload: data["payload"],
             id: data["id"],
@@ -176,7 +176,7 @@ module Tina4
           next if (data["attempts"] || 0) >= max_retries
 
           data["status"] = "pending"
-          msg = Tina4::QueueMessage.new(
+          msg = Tina4::Job.new(
             topic: data["topic"],
             payload: data["payload"],
             id: data["id"]
@@ -191,6 +191,61 @@ module Tina4
         count
       end
 
+      # Remove all pending jobs from a topic. Returns count removed.
+      def clear(topic)
+        dir = topic_path(topic)
+        return 0 unless Dir.exist?(dir)
+        count = 0
+        Dir.glob(File.join(dir, "*.json")).each do |file|
+          File.delete(file)
+          count += 1
+        end
+        count
+      end
+
+      # Get jobs that failed but are still eligible for retry (under max_retries).
+      def failed(topic, max_retries: 3)
+        return [] unless Dir.exist?(@dead_letter_dir)
+        jobs = []
+        Dir.glob(File.join(@dead_letter_dir, "*.json")).sort_by { |f| File.mtime(f) }.each do |file|
+          data = JSON.parse(File.read(file))
+          next unless data["topic"] == topic.to_s
+          next if (data["attempts"] || 0) >= max_retries
+          jobs << data
+        rescue JSON::ParserError
+          next
+        end
+        jobs
+      end
+
+      # Retry all dead letter jobs for this topic. Returns true if any were re-queued.
+      def retry_job(topic, delay_seconds: 0)
+        return false unless Dir.exist?(@dead_letter_dir)
+
+        available_at = delay_seconds > 0 ? Time.now + delay_seconds : nil
+        count = 0
+
+        Dir.glob(File.join(@dead_letter_dir, "*.json")).each do |file|
+          data = JSON.parse(File.read(file))
+          next unless data["topic"] == topic.to_s
+
+          msg = Tina4::Job.new(
+            topic: data["topic"],
+            payload: data["payload"],
+            id: data["id"],
+            attempts: (data["attempts"] || 0) + 1,
+            available_at: available_at
+          )
+          enqueue(msg)
+          File.delete(file)
+          count += 1
+        rescue JSON::ParserError
+          next
+        end
+
+        count > 0
+      end
+
       private
 
       def topic_path(topic)

data/lib/tina4/queue_backends/mongo_backend.rb

@@ -49,7 +49,7 @@ module Tina4
         )
         return nil unless doc
 
-        Tina4::QueueMessage.new(
+        Tina4::Job.new(
           topic: doc["topic"],
           payload: doc["payload"],
           id: doc["_id"]
@@ -82,7 +82,7 @@ module Tina4
 
       def dead_letters(topic, max_retries: 3)
         collection.find(topic: "#{topic}.dead_letter", status: "dead").map do |doc|
-          Tina4::QueueMessage.new(
+          Tina4::Job.new(
             topic: doc["topic"],
             payload: doc["payload"],
             id: doc["_id"]

data/lib/tina4/queue_backends/rabbitmq_backend.rb

@@ -31,7 +31,7 @@ module Tina4
         return nil unless payload
 
         data = JSON.parse(payload)
-        msg = Tina4::QueueMessage.new(
+        msg = Tina4::Job.new(
           topic: data["topic"],
           payload: data["payload"],
           id: data["id"]

data/lib/tina4/rack_app.rb

@@ -176,11 +176,10 @@ module Tina4
         if api_key && !api_key.empty? && token == api_key
           env["tina4.auth_payload"] = { "api_key" => true }
         elsif token
-          payload = Tina4::Auth.valid_token(token)
-          unless payload
+          unless Tina4::Auth.valid_token(token)
             return [401, { "content-type" => "application/json" }, [JSON.generate({ error: "Unauthorized" })]]
           end
-          env["tina4.auth_payload"] = payload
+          env["tina4.auth_payload"] = Tina4::Auth.get_payload(token)
         else
           return [401, { "content-type" => "application/json" }, [JSON.generate({ error: "Unauthorized" })]]
         end

data/lib/tina4/session.rb

@@ -114,9 +114,10 @@ module Tina4
       @handler.gc(max_age) if @handler.respond_to?(:gc)
     end
 
-    def cookie_header
+    def cookie_header(cookie_name = nil)
+      name = cookie_name || @options[:cookie_name]
       samesite = ENV["TINA4_SESSION_SAMESITE"] || "Lax"
-      "#{@options[:cookie_name]}=#{@id}; Path=/; HttpOnly; SameSite=#{samesite}; Max-Age=#{@options[:max_age]}"
+      "#{name}=#{@id}; Path=/; HttpOnly; SameSite=#{samesite}; Max-Age=#{@options[:max_age]}"
     end
 
     private
@@ -223,9 +224,9 @@ module Tina4
       @session.gc(max_age)
     end
 
-    def cookie_header
+    def cookie_header(cookie_name = nil)
       ensure_loaded
-      @session.cookie_header
+      @session.cookie_header(cookie_name)
     end
 
     def to_hash

data/lib/tina4/version.rb

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

data/lib/tina4/websocket.rb

@@ -2,6 +2,7 @@
 require "socket"
 require "digest"
 require "base64"
+require "set"
 
 module Tina4
   class WebSocket
@@ -17,6 +18,7 @@ module Tina4
         close: [],
         error: []
       }
+      @rooms = {}  # room_name => Set of conn_ids
     end
 
     def on(event, &block)
@@ -69,6 +71,7 @@ module Tina4
           emit(:error, connection, e)
         ensure
           @connections.delete(conn_id)
+          remove_from_all_rooms(conn_id)
           emit(:close, connection)
           socket.close rescue nil
         end
@@ -83,15 +86,46 @@ module Tina4
       end
     end
 
+    # ── Rooms ──────────────────────────────────────────────────
+
+    def join_room_for(conn_id, room_name)
+      @rooms[room_name] ||= Set.new
+      @rooms[room_name].add(conn_id)
+    end
+
+    def leave_room_for(conn_id, room_name)
+      @rooms[room_name]&.delete(conn_id)
+    end
+
+    def room_count(room_name)
+      (@rooms[room_name] || Set.new).size
+    end
+
+    def get_room_connections(room_name)
+      ids = @rooms[room_name] || Set.new
+      ids.filter_map { |id| @connections[id] }
+    end
+
+    def broadcast_to_room(room_name, message, exclude: nil)
+      (get_room_connections(room_name)).each do |conn|
+        next if exclude && conn.id == exclude
+        conn.send_text(message)
+      end
+    end
+
     private
 
     def emit(event, *args)
       @handlers[event]&.each { |h| h.call(*args) }
     end
+
+    def remove_from_all_rooms(conn_id)
+      @rooms.each_value { |members| members.delete(conn_id) }
+    end
   end
 
   class WebSocketConnection
-    attr_reader :id
+    attr_reader :id, :rooms
     attr_accessor :params, :path
 
     def initialize(id, socket, ws_server: nil, path: "/")
@@ -100,6 +134,24 @@ module Tina4
       @params = {}
       @ws_server = ws_server
       @path = path
+      @rooms = Set.new
+    end
+
+    def join_room(room_name)
+      @rooms.add(room_name)
+      @ws_server&.join_room_for(@id, room_name)
+    end
+
+    def leave_room(room_name)
+      @rooms.delete(room_name)
+      @ws_server&.leave_room_for(@id, room_name)
+    end
+
+    def broadcast_to_room(room_name, message, exclude_self: false)
+      return unless @ws_server
+
+      exclude = exclude_self ? @id : nil
+      @ws_server.broadcast_to_room(room_name, message, exclude: exclude)
     end
 
     # Broadcast a message to all other connections on the same path

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tina4ruby
 version: !ruby/object:Gem::Version
-  version: 3.10.76
+  version: 3.10.84
 platform: ruby
 authors:
 - Tina4 Team
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-07 00:00:00.000000000 Z
+date: 2026-04-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -324,6 +324,7 @@ files:
 - lib/tina4/graphql.rb
 - lib/tina4/health.rb
 - lib/tina4/html_element.rb
+- lib/tina4/job.rb
 - lib/tina4/localization.rb
 - lib/tina4/log.rb
 - lib/tina4/mcp.rb