tina4ruby 3.12.13 → 3.13.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65d79f819e3ac62c1e8d3447409b8c75530c239db2bb6a7df9066de4104495ed
-  data.tar.gz: d0b0af5dd0e914b880cc64a7b9aca29e6f46de65dcec3104b18e01ad174509b8
+  metadata.gz: eb13055e35412e98279f173f9cda3b6dc3e5a2c6766db1c2439b74e9de3354e2
+  data.tar.gz: 907a9ba2b3a732927dfd965cb41a212fcb4e245688fa6fab2ae805728e71489f
 SHA512:
-  metadata.gz: 2e59eac2e37d78d1f7752cd26680338ff404794f6ff23dbe9ab2a1570ce3f458200fd5f488fefb8ef6f5f0b1764aa355def94dbed13a50149df30b4ea798059a
-  data.tar.gz: 7021e0596f5275b4daf0969f0690400e99222fe10f30547b31fc8ee747f266c88086fb577927953813ac53b52dad9d8ce95a7ecb7ae48bfd2c1aa50fa8ff5e47
+  metadata.gz: b261fd27af0fed8f591599c2acf376c0333286910d302773e228fe92cae1e24201260a240081f26bb9abba86f731e9c7790d8c1f26b86dff857d1a87d0b938b0
+  data.tar.gz: 821cb969b8b9822b39d9b6b8d0e2b0ca4a74c7a35febcb277b6e8b119df38dfb09af5acaf88fbcda1b3793a44f4477c636bc5b7223a14214029dbbd8eb9f4cce

data/lib/tina4/api.rb

@@ -8,13 +8,33 @@ module Tina4
   class API
     attr_reader :base_url, :headers
 
-    def initialize(base_url, headers: {}, timeout: 30)
+    # 3.13.1: added ergonomic kwargs (bearer_token, username, password,
+    # verify_ssl) so callers no longer need three follow-up setter calls.
+    # Cross-framework parity with the Python tina4_python.api.Api kwargs.
+    #
+    #     api = Tina4::API.new("https://api.example.com", bearer_token: "sk-abc")
+    #     api = Tina4::API.new("https://api.example.com", username: "u", password: "p")
+    #     api = Tina4::API.new("https://api.example.com", headers: {"X-Tenant" => "acme"})
+    #     api = Tina4::API.new("https://self-signed.local", verify_ssl: false)
+    #
+    # Bearer wins over basic-auth when both are passed.
+    def initialize(base_url, headers: {}, timeout: 30,
+                   bearer_token: nil, username: nil, password: nil,
+                   verify_ssl: nil)
       @base_url = base_url.chomp("/")
       @headers = {
         "Content-Type" => "application/json",
         "Accept" => "application/json"
       }.merge(headers)
       @timeout = timeout
+      @verify_ssl = verify_ssl
+
+      # Bearer wins over basic-auth when both passed
+      if bearer_token
+        set_bearer_token(bearer_token)
+      elsif username && password
+        set_basic_auth(username, password)
+      end
     end
 
     def get(path, params: {})

data/lib/tina4/auth.rb

@@ -109,19 +109,25 @@ module Tina4
       end
 
 
-      def valid_token(token) # -> bool
+      # Verify a JWT signature + expiry.
+      #
+      # 3.13.0: return type changed from `Boolean` to `Hash | nil`. The
+      # decoded payload is returned on success, nil on failure. Matches
+      # firebase/jwt-ruby and Python's Auth.valid_token in 3.13.0.
+      #
+      # Legacy `if Tina4::Auth.valid_token(t)` patterns keep working
+      # because a non-empty Hash is truthy and nil is falsy.
+      def valid_token(token)
         if use_hmac?
-          !hmac_decode(token, hmac_secret).nil?
+          hmac_decode(token, hmac_secret) # returns Hash payload or nil
         else
           ensure_keys
           require "jwt"
-          JWT.decode(token, public_key, true, algorithm: "RS256")
-          true
+          decoded = JWT.decode(token, public_key, true, algorithm: "RS256")
+          decoded[0] # firebase/jwt-ruby returns [payload, header]
         end
-      rescue JWT::ExpiredSignature
-        false
-      rescue JWT::DecodeError
-        false
+      rescue JWT::ExpiredSignature, JWT::DecodeError
+        nil
       end
 
       def valid_token_detail(token)

data/lib/tina4/database.rb

@@ -101,6 +101,29 @@ module Tina4
           pool: pool)
     end
 
+    # Open a database connection — convention name matching SQLAlchemy
+    # engine.connect() and the cross-framework Database.get_connection()
+    # surface shipped in 3.13.x.
+    #
+    # The first argument may be either a URL (containing `://` or `sqlite:`)
+    # or an env-var name. Falls back to in-memory SQLite when no URL
+    # resolves — matches Python tina4_python's default behaviour.
+    #
+    #   db = Tina4::Database.get_connection                     # from TINA4_DATABASE_URL
+    #   db = Tina4::Database.get_connection("sqlite::memory:")  # explicit URL
+    #   db = Tina4::Database.get_connection("postgres://...", username: "u", password: "p")
+    def self.get_connection(url_or_env_key = "TINA4_DATABASE_URL", username: nil, password: nil, pool: nil)
+      if url_or_env_key.include?("://") || url_or_env_key.start_with?("sqlite:")
+        return new(url_or_env_key, username: username, password: password, pool: pool)
+      end
+
+      db = from_env(env_key: url_or_env_key, pool: pool)
+      return db if db
+
+      # Fallback: in-memory SQLite — matches Python parity.
+      new("sqlite::memory:", username: username, password: password, pool: pool)
+    end
+
     def initialize(connection_string = nil, username: nil, password: nil, driver_name: nil, pool: nil)
       @connection_string = connection_string || ENV["TINA4_DATABASE_URL"]
       @username = username || ENV["TINA4_DATABASE_USERNAME"]
@@ -213,6 +236,19 @@ module Tina4
       end
     end
 
+    # Fetch rows and return the records array directly.
+    #
+    # Symmetric with fetch_one. Cross-framework parity with Python
+    # db.fetch_all() / PHP $db->fetchAll() / Node db.fetchAll().
+    #
+    #   rows = db.fetch_all("SELECT * FROM users WHERE active = ?", [1])
+    #   rows.each { |row| puts row["name"] }
+    #
+    # Returns [] (not nil) when no rows match.
+    def fetch_all(sql, params = [], limit: 100, offset: nil)
+      fetch(sql, params, limit: limit, offset: offset).records
+    end
+
     def fetch(sql, params = [], limit: 100, offset: nil)
       offset ||= 0
       drv = current_driver

data/lib/tina4/graphql.rb

@@ -853,9 +853,103 @@ module Tina4
       !%w[false 0 no off].include?(val)
     end
 
+    # ── Class-level resolver registry — 3.13.1 ────────────────────────
+    #
+    # Resolvers registered via Tina4::GraphQL.resolve("Type", "field")
+    # accumulate here BEFORE any GraphQL instance exists. When `new` runs,
+    # the instance drains the registry into its schema. This is what makes
+    # the documented decorator-style pattern work at app-startup time:
+    # modules `Tina4::GraphQL.resolve(...)` at load time and register
+    # before the singleton is even constructed. Cross-framework parity
+    # with Python @GraphQL.resolve and PHP GraphQL::resolve.
+    @class_resolvers = {}
+    @default_instance = nil
+
+    class << self
+      attr_accessor :default_instance
+
+      def class_resolvers
+        @class_resolvers ||= {}
+      end
+
+      # Decorator-style resolver registration.
+      #
+      #     Tina4::GraphQL.resolve("Query", "products") do |root, args, ctx|
+      #       Product.all
+      #     end
+      #
+      #     Tina4::GraphQL.resolve("Mutation", "createProduct") do |root, args, ctx|
+      #       Product.create(args["input"])
+      #     end
+      #
+      #     Tina4::GraphQL.resolve("Product", "reviews") do |product, args, ctx|
+      #       Review.where("product_id = ?", [product["id"]])
+      #     end
+      #
+      # Resolvers registered before any GraphQL instance accumulate in a
+      # class-level registry. new GraphQL drains them into its schema.
+      # Resolvers registered after .default_instance is set wire into
+      # the live schema immediately.
+      def resolve(type_name, field_name, &block)
+        class_resolvers[type_name] ||= {}
+        class_resolvers[type_name][field_name] = block
+
+        # If a default instance is active, attach immediately so post-startup
+        # registrations take effect without re-instantiation.
+        if @default_instance
+          @default_instance.send(:attach_resolver, type_name, field_name, block)
+        end
+        block
+      end
+
+      # Test-only — clear the class-level registry. Used by parity tests
+      # to avoid bleed-over between cases.
+      def _clear_class_resolvers!
+        @class_resolvers = {}
+        @default_instance = nil
+      end
+    end
+
     def initialize(schema = nil)
       @schema = schema || GraphQLSchema.new
       @executor = GraphQLExecutor.new(@schema)
+      @field_resolvers = {}
+
+      # Drain any resolvers registered via the class-level GraphQL.resolve()
+      # BEFORE this instance was constructed.
+      self.class.class_resolvers.each do |type_name, fields|
+        fields.each do |field_name, resolver|
+          attach_resolver(type_name, field_name, resolver)
+        end
+      end
+    end
+
+    # Wire a single resolver into the live schema.
+    def attach_resolver(type_name, field_name, resolver)
+      if type_name == "Query"
+        existing = @schema.queries[field_name] || {}
+        existing[:resolve] = resolver
+        existing[:args] ||= {}
+        existing[:type] ||= "String"
+        @schema.queries[field_name] = existing
+      elsif type_name == "Mutation"
+        existing = @schema.mutations[field_name] || {}
+        existing[:resolve] = resolver
+        existing[:args] ||= {}
+        existing[:type] ||= "String"
+        @schema.mutations[field_name] = existing
+      else
+        # Object-type field resolver — stash for the executor.
+        @field_resolvers[type_name] ||= {}
+        @field_resolvers[type_name][field_name] = resolver
+      end
+    end
+    private :attach_resolver
+
+    # Get the field resolver registered for an object type, if any.
+    # Used by the executor during nested field resolution.
+    def field_resolver(type_name, field_name)
+      @field_resolvers.dig(type_name, field_name)
     end
 
     # Execute a query string directly

data/lib/tina4/service.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# Tina4 — The Intelligent Native Application 4ramework
+# Copyright 2007 - current Tina4
+# License: MIT https://opensource.org/licenses/MIT
+
+module Tina4
+  # Base class for class-based background services managed by
+  # {Tina4::ServiceRunner}. Cross-framework parity with PHP `Tina4\Service`
+  # and the same shape the documentation has long taught.
+  #
+  #     class EmailQueueWorker < Tina4::Service
+  #       def run
+  #         until should_stop?
+  #           process_next_job
+  #           sleep 1
+  #         end
+  #       end
+  #     end
+  #
+  #     Tina4::ServiceRunner.register_service("emails", EmailQueueWorker.new)
+  #     Tina4::ServiceRunner.start
+  #
+  # Subclasses MUST override #run. Optionally override #stop for custom
+  # shutdown behaviour but always call `super` so the internal flag
+  # gets set — the default #should_stop? reads from it.
+  class Service
+    def initialize
+      @running = true
+    end
+
+    # Main work loop — subclasses MUST override.
+    def run
+      raise NotImplementedError, "#{self.class}#run must be implemented by the subclass"
+    end
+
+    # Signal this service to stop. The next `should_stop?` check returns true.
+    def stop
+      @running = false
+    end
+
+    # Returns true once #stop has been called. Use inside #run loops as
+    # the exit condition:
+    #
+    #     def run
+    #       until should_stop?
+    #         # do work
+    #       end
+    #     end
+    def should_stop?
+      !@running
+    end
+
+    # Return a callable that ServiceRunner can register. Used by
+    # ServiceRunner.register_service under the hood.
+    def to_proc
+      method(:run).to_proc
+    end
+  end
+end

data/lib/tina4/service_runner.rb

@@ -48,6 +48,41 @@ module Tina4
         Tina4::Log.debug("Service registered: #{name}")
       end
 
+      # Register a class-based service (subclass of {Tina4::Service}) by name.
+      #
+      # Wraps the Service's #run method as the handler callable that
+      # ServiceRunner.start invokes. The service's #stop is also wired
+      # up so ServiceRunner.stop(name) shuts it down cleanly.
+      #
+      #   class EmailQueueWorker < Tina4::Service
+      #     def run
+      #       until should_stop?
+      #         # process work
+      #       end
+      #     end
+      #   end
+      #
+      #   Tina4::ServiceRunner.register_service("emails", EmailQueueWorker.new)
+      #   Tina4::ServiceRunner.start
+      #
+      # Default options set daemon: true because Service subclasses manage
+      # their own loop inside #run. Override via `options`.
+      def register_service(name, service, options = {})
+        raise ArgumentError, "service must be a Tina4::Service instance" unless service.is_a?(Tina4::Service)
+
+        options = { daemon: true }.merge(options)
+        callable = service.method(:run)
+
+        @mutex.synchronize do
+          @registry[name.to_s] = {
+            handler:  callable,
+            options:  options,
+            instance: service,
+          }
+        end
+        Tina4::Log.debug("Service registered (class-based): #{name}")
+      end
+
       # Auto-discover service files from a directory.
       # Each file should call Tina4.service or Tina4::ServiceRunner.register.
       def discover(service_dir = nil)

data/lib/tina4/test.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+# Tina4 — The Intelligent Native Application 4ramework
+# Copyright 2007 - current Tina4
+# License: MIT https://opensource.org/licenses/MIT
+
+module Tina4
+  # Tina4 xUnit-style test base class — class-based test suites with HTTP
+  # helpers and positional assertions. Zero external dependencies.
+  #
+  # Documentation chapter 18 has long described:
+  #
+  #     class UserApiTest < Tina4::Test
+  #       def test_health
+  #         resp = get("/health")
+  #         assert_equal_value(resp.status, 200)
+  #       end
+  #     end
+  #
+  # Until 3.13.0 this class did not exist — examples crashed with
+  # "uninitialized constant Tina4::Test". Ruby parity of the
+  # Python `tina4_python.test.Test` and PHP `Tina4\Test` classes.
+  #
+  # The class has a built-in runner (no Minitest/RSpec required):
+  #
+  #     results = Tina4::Test.run_all          # discovers all subclasses
+  #     # => { passed: 12, failed: 0, errors: 0, details: [...] }
+  #
+  # Or run a single suite class:
+  #
+  #     UserApiTest.run!
+  #
+  # HTTP helpers (get/post/put/patch/delete) delegate to TestClient.
+  # Positional assertions match the Python (actual, expected, message)
+  # shape used throughout the cross-framework docs.
+  class Test
+    # Class-level registry so run_all can discover every subclass without
+    # filesystem scanning.
+    @subclasses = []
+
+    class << self
+      attr_reader :subclasses
+
+      def inherited(subclass)
+        super
+        Test.subclasses << subclass
+      end
+
+      # Run every test method (`test_*`) on the calling subclass. Returns
+      # a hash with passed/failed/errors counts and per-test details.
+      def run!
+        instance_methods(false).grep(/\Atest_/).sort.each_with_object(
+          { passed: 0, failed: 0, errors: 0, details: [] }
+        ) do |method, results|
+          suite = new
+          begin
+            suite.send(:set_up)
+            suite.send(method)
+            suite.send(:tear_down)
+            results[:passed] += 1
+            results[:details] << { suite: name, test: method, status: "passed" }
+          rescue AssertionError => e
+            results[:failed] += 1
+            results[:details] << { suite: name, test: method, status: "failed", message: e.message }
+          rescue StandardError => e
+            results[:errors] += 1
+            results[:details] << { suite: name, test: method, status: "error", message: "#{e.class}: #{e.message}" }
+          end
+        end
+      end
+
+      # Discover and run every Tina4::Test subclass.
+      def run_all(quiet: false)
+        results = { passed: 0, failed: 0, errors: 0, details: [] }
+        Test.subclasses.each do |klass|
+          out = klass.run!
+          results[:passed] += out[:passed]
+          results[:failed] += out[:failed]
+          results[:errors] += out[:errors]
+          results[:details].concat(out[:details])
+        end
+        unless quiet
+          puts "Tina4 Test results: #{results[:passed]} passed, #{results[:failed]} failed, #{results[:errors]} errors"
+        end
+        results
+      end
+    end
+
+    # ── Lifecycle hooks ──────────────────────────────────────────────
+    # snake_case Tina4 idiom; override in subclasses.
+
+    def set_up
+    end
+
+    def tear_down
+    end
+
+    # ── HTTP test client (lazy) ───────────────────────────────────────
+
+    def test_client
+      @test_client ||= Tina4::TestClient.new
+    end
+
+    def get(path, headers: nil)
+      test_client.get(path, headers: headers)
+    end
+
+    def post(path, json: nil, body: nil, headers: nil)
+      test_client.post(path, json: json, body: body, headers: headers)
+    end
+
+    def put(path, json: nil, body: nil, headers: nil)
+      test_client.put(path, json: json, body: body, headers: headers)
+    end
+
+    def patch(path, json: nil, body: nil, headers: nil)
+      test_client.patch(path, json: json, body: body, headers: headers)
+    end
+
+    def delete(path, headers: nil)
+      test_client.delete(path, headers: headers)
+    end
+
+    # ── Positional assertions — (actual, expected, message) shape ─────
+
+    def assert_equal_value(actual, expected, message = nil)
+      return if actual == expected
+
+      raise AssertionError, message || "Expected #{expected.inspect}, got #{actual.inspect}"
+    end
+
+    def assert_not_equal_value(actual, expected, message = nil)
+      return unless actual == expected
+
+      raise AssertionError, message || "Expected #{actual.inspect} != #{expected.inspect}, but they are equal"
+    end
+
+    def assert_true(value, message = nil)
+      return if value
+
+      raise AssertionError, message || "Expected truthy, got #{value.inspect}"
+    end
+
+    def assert_false(value, message = nil)
+      return unless value
+
+      raise AssertionError, message || "Expected falsy, got #{value.inspect}"
+    end
+
+    def assert_nil_value(value, message = nil)
+      return if value.nil?
+
+      raise AssertionError, message || "Expected nil, got #{value.inspect}"
+    end
+
+    def assert_not_nil_value(value, message = nil)
+      return unless value.nil?
+
+      raise AssertionError, message || "Expected non-nil, got nil"
+    end
+
+    def assert_raises(expected_class, message = nil)
+      raise ArgumentError, "Block required" unless block_given?
+
+      begin
+        yield
+      rescue StandardError => e
+        return if e.is_a?(expected_class)
+
+        raise AssertionError,
+              message || "Expected #{expected_class}, got #{e.class}: #{e.message}"
+      end
+      raise AssertionError, message || "Expected #{expected_class} to be raised, but nothing was"
+    end
+  end
+
+  # AssertionError raised by Tina4::Test assertion helpers on failure.
+  class AssertionError < StandardError; end
+end

data/lib/tina4/version.rb

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

data/lib/tina4.rb

@@ -39,6 +39,7 @@ require_relative "tina4/background"
 require_relative "tina4/localization"
 require_relative "tina4/container"
 require_relative "tina4/queue"
+require_relative "tina4/service"
 require_relative "tina4/service_runner"
 require_relative "tina4/events"
 require_relative "tina4/plan"
@@ -54,6 +55,7 @@ require_relative "tina4/response_cache"
 require_relative "tina4/html_element"
 require_relative "tina4/error_overlay"
 require_relative "tina4/test_client"
+require_relative "tina4/test"
 require_relative "tina4/docs"
 require_relative "tina4/mcp"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tina4ruby
 version: !ruby/object:Gem::Version
-  version: 3.12.13
+  version: 3.13.1
 platform: ruby
 authors:
 - Tina4 Team
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-29 00:00:00.000000000 Z
+date: 2026-06-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -382,6 +382,7 @@ files:
 - lib/tina4/scss/tina4css/tina4.scss
 - lib/tina4/scss_compiler.rb
 - lib/tina4/seeder.rb
+- lib/tina4/service.rb
 - lib/tina4/service_runner.rb
 - lib/tina4/session.rb
 - lib/tina4/session_handlers/database_handler.rb
@@ -402,6 +403,7 @@ files:
 - lib/tina4/templates/errors/502.twig
 - lib/tina4/templates/errors/503.twig
 - lib/tina4/templates/errors/base.twig
+- lib/tina4/test.rb
 - lib/tina4/test_client.rb
 - lib/tina4/testing.rb
 - lib/tina4/validator.rb