tina4ruby 3.2.1 → 3.10.0

data/lib/tina4/validator.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Tina4
+  # Request body validator with chainable rules.
+  #
+  # Usage:
+  #   validator = Tina4::Validator.new(request.body)
+  #   validator.required("name", "email")
+  #            .email("email")
+  #            .min_length("name", 2)
+  #            .max_length("name", 100)
+  #            .integer("age")
+  #            .min("age", 0)
+  #            .max("age", 150)
+  #            .in_list("role", ["admin", "user", "guest"])
+  #            .regex("phone", /^\+?[\d\s\-]+$/)
+  #
+  #   unless validator.is_valid?
+  #     return response.error("VALIDATION_FAILED", validator.errors.first[:message], 400)
+  #   end
+  #
+  class Validator
+    attr_reader :validation_errors
+
+    EMAIL_REGEX = /\A[a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}\z/
+
+    def initialize(data = {})
+      @data = data.is_a?(Hash) ? data : {}
+      # Normalise keys to strings for consistent lookup
+      @data = @data.transform_keys(&:to_s) unless @data.empty?
+      @validation_errors = []
+    end
+
+    # Check that one or more fields are present and non-empty.
+    def required(*fields)
+      fields.each do |field|
+        key = field.to_s
+        value = @data[key]
+        if value.nil? || (value.is_a?(String) && value.strip.empty?)
+          @validation_errors << { field: key, message: "#{key} is required" }
+        end
+      end
+      self
+    end
+
+    # Check that a field contains a valid email address.
+    def email(field)
+      key = field.to_s
+      value = @data[key]
+      return self if value.nil?
+
+      unless value.is_a?(String) && value.match?(EMAIL_REGEX)
+        @validation_errors << { field: key, message: "#{key} must be a valid email address" }
+      end
+      self
+    end
+
+    # Check that a string field has at least +length+ characters.
+    def min_length(field, length)
+      key = field.to_s
+      value = @data[key]
+      return self if value.nil?
+
+      unless value.is_a?(String) && value.length >= length
+        @validation_errors << { field: key, message: "#{key} must be at least #{length} characters" }
+      end
+      self
+    end
+
+    # Check that a string field has at most +length+ characters.
+    def max_length(field, length)
+      key = field.to_s
+      value = @data[key]
+      return self if value.nil?
+
+      unless value.is_a?(String) && value.length <= length
+        @validation_errors << { field: key, message: "#{key} must be at most #{length} characters" }
+      end
+      self
+    end
+
+    # Check that a field is an integer (or can be parsed as one).
+    def integer(field)
+      key = field.to_s
+      value = @data[key]
+      return self if value.nil?
+
+      if value.is_a?(Integer)
+        return self
+      end
+
+      begin
+        Integer(value)
+      rescue ArgumentError, TypeError
+        @validation_errors << { field: key, message: "#{key} must be an integer" }
+      end
+      self
+    end
+
+    # Check that a numeric field is >= +minimum+.
+    def min(field, minimum)
+      key = field.to_s
+      value = @data[key]
+      return self if value.nil?
+
+      begin
+        num = Float(value)
+      rescue ArgumentError, TypeError
+        return self
+      end
+
+      if num < minimum
+        @validation_errors << { field: key, message: "#{key} must be at least #{minimum}" }
+      end
+      self
+    end
+
+    # Check that a numeric field is <= +maximum+.
+    def max(field, maximum)
+      key = field.to_s
+      value = @data[key]
+      return self if value.nil?
+
+      begin
+        num = Float(value)
+      rescue ArgumentError, TypeError
+        return self
+      end
+
+      if num > maximum
+        @validation_errors << { field: key, message: "#{key} must be at most #{maximum}" }
+      end
+      self
+    end
+
+    # Check that a field's value is one of the allowed values.
+    def in_list(field, allowed)
+      key = field.to_s
+      value = @data[key]
+      return self if value.nil?
+
+      unless allowed.include?(value)
+        @validation_errors << { field: key, message: "#{key} must be one of #{allowed}" }
+      end
+      self
+    end
+
+    # Check that a field matches a regular expression.
+    def regex(field, pattern)
+      key = field.to_s
+      value = @data[key]
+      return self if value.nil?
+
+      regexp = pattern.is_a?(Regexp) ? pattern : Regexp.new(pattern)
+      unless value.is_a?(String) && value.match?(regexp)
+        @validation_errors << { field: key, message: "#{key} does not match the required format" }
+      end
+      self
+    end
+
+    # Return the list of validation errors (empty if valid).
+    def errors
+      @validation_errors.dup
+    end
+
+    # Return true if no validation errors have been recorded.
+    def is_valid?
+      @validation_errors.empty?
+    end
+
+    # Alias for is_valid? (Ruby convention)
+    alias_method :valid?, :is_valid?
+  end
+end

data/lib/tina4/version.rb

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

data/lib/tina4/websocket.rb

@@ -44,7 +44,8 @@ module Tina4
       socket.write(response)
 
       conn_id = SecureRandom.hex(16)
-      connection = WebSocketConnection.new(conn_id, socket)
+      ws_path = env["REQUEST_PATH"] || env["PATH_INFO"] || "/"
+      connection = WebSocketConnection.new(conn_id, socket, ws_server: self, path: ws_path)
       @connections[conn_id] = connection
 
       emit(:open, connection)
@@ -74,9 +75,10 @@ module Tina4
       end
     end
 
-    def broadcast(message, exclude: nil)
+    def broadcast(message, exclude: nil, path: nil)
       @connections.each do |id, conn|
         next if exclude && id == exclude
+        next if path && conn.path != path
         conn.send_text(message)
       end
     end
@@ -90,13 +92,28 @@ module Tina4
 
   class WebSocketConnection
     attr_reader :id
+    attr_accessor :params, :path
 
-    def initialize(id, socket)
+    def initialize(id, socket, ws_server: nil, path: "/")
       @id = id
       @socket = socket
+      @params = {}
+      @ws_server = ws_server
+      @path = path
     end
 
-    def send_text(message)
+    # Broadcast a message to all other connections on the same path
+    def broadcast(message, include_self: false)
+      return unless @ws_server
+
+      @ws_server.connections.each do |cid, conn|
+        next if !include_self && cid == @id
+        next if conn.path != @path
+        conn.send_text(message)
+      end
+    end
+
+    def send(message)
       data = message.encode("UTF-8")
       frame = build_frame(0x1, data)
       @socket.write(frame)
@@ -104,6 +121,8 @@ module Tina4
       # Connection closed
     end
 
+    alias_method :send_text, :send
+
     def send_pong(data)
       frame = build_frame(0xA, data || "")
       @socket.write(frame)

data/lib/tina4/websocket_backplane.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+# WebSocket Backplane Abstraction for Tina4 Ruby.
+#
+# Enables broadcasting WebSocket messages across multiple server instances
+# using a shared pub/sub channel (e.g. Redis). Without a backplane configured,
+# broadcast() only reaches connections on the local process.
+#
+# Configuration via environment variables:
+#   TINA4_WS_BACKPLANE     — Backend type: "redis", "nats", or "" (default: none)
+#   TINA4_WS_BACKPLANE_URL — Connection string (default: redis://localhost:6379)
+#
+# Usage:
+#   backplane = Tina4::WebSocketBackplane.create
+#   if backplane
+#     backplane.subscribe("chat") { |msg| relay_to_local(msg) }
+#     backplane.publish("chat", '{"user":"A","text":"hello"}')
+#   end
+
+module Tina4
+  # Base backplane interface for scaling WebSocket broadcast across instances.
+  #
+  # Subclasses implement publish/subscribe over a shared message bus so that
+  # every server instance receives every broadcast, not just the originator.
+  class WebSocketBackplane
+    # Publish a message to all instances listening on +channel+.
+    def publish(channel, message)
+      raise NotImplementedError, "#{self.class}#publish not implemented"
+    end
+
+    # Subscribe to +channel+. The block is called with each incoming message.
+    # Runs in a background thread.
+    def subscribe(channel, &block)
+      raise NotImplementedError, "#{self.class}#subscribe not implemented"
+    end
+
+    # Stop listening on +channel+.
+    def unsubscribe(channel)
+      raise NotImplementedError, "#{self.class}#unsubscribe not implemented"
+    end
+
+    # Tear down connections and background threads.
+    def close
+      raise NotImplementedError, "#{self.class}#close not implemented"
+    end
+
+    # Factory that reads TINA4_WS_BACKPLANE and returns the appropriate
+    # backplane instance, or +nil+ if no backplane is configured.
+    #
+    # This keeps backplane usage entirely optional — callers simply check
+    # +if backplane+ before publishing.
+    def self.create(url: nil)
+      backend = ENV.fetch("TINA4_WS_BACKPLANE", "").strip.downcase
+
+      case backend
+      when "redis"
+        RedisBackplane.new(url: url)
+      when "nats"
+        raise NotImplementedError, "NATS backplane is on the roadmap but not yet implemented."
+      when ""
+        nil
+      else
+        raise ArgumentError, "Unknown TINA4_WS_BACKPLANE value: '#{backend}'"
+      end
+    end
+  end
+
+  # Redis pub/sub backplane.
+  #
+  # Requires the +redis+ gem (+gem install redis+). The require is deferred
+  # so the rest of Tina4 works fine without it installed — an error is raised
+  # only when this class is actually instantiated.
+  class RedisBackplane < WebSocketBackplane
+    def initialize(url: nil)
+      begin
+        require "redis"
+      rescue LoadError
+        raise LoadError,
+          "The 'redis' gem is required for RedisBackplane. " \
+          "Install it with: gem install redis"
+      end
+
+      @url = url || ENV.fetch("TINA4_WS_BACKPLANE_URL", "redis://localhost:6379")
+      @redis = Redis.new(url: @url)
+      @subscriber = Redis.new(url: @url)
+      @threads = {}
+      @running = true
+    end
+
+    def publish(channel, message)
+      @redis.publish(channel, message)
+    end
+
+    def subscribe(channel, &block)
+      @threads[channel] = Thread.new do
+        @subscriber.subscribe(channel) do |on|
+          on.message do |_chan, msg|
+            block.call(msg) if @running
+          end
+        end
+      end
+    end
+
+    def unsubscribe(channel)
+      @subscriber.unsubscribe(channel)
+      thread = @threads.delete(channel)
+      thread&.join(1)
+    end
+
+    def close
+      @running = false
+      @threads.each_value { |t| t.kill }
+      @threads.clear
+      @subscriber.close
+      @redis.close
+    end
+  end
+end

data/lib/tina4.rb

@@ -22,6 +22,7 @@ require_relative "tina4/database"
 require_relative "tina4/database_result"
 require_relative "tina4/field_types"
 require_relative "tina4/orm"
+require_relative "tina4/query_builder"
 require_relative "tina4/migration"
 require_relative "tina4/auto_crud"
 require_relative "tina4/database/sqlite3_adapter"
@@ -63,7 +64,8 @@ module Tina4
     autoload :FileHandler,  File.expand_path("tina4/session_handlers/file_handler", __dir__)
     autoload :RedisHandler, File.expand_path("tina4/session_handlers/redis_handler", __dir__)
     autoload :MongoHandler,  File.expand_path("tina4/session_handlers/mongo_handler", __dir__)
-    autoload :ValkeyHandler, File.expand_path("tina4/session_handlers/valkey_handler", __dir__)
+    autoload :ValkeyHandler,   File.expand_path("tina4/session_handlers/valkey_handler", __dir__)
+    autoload :DatabaseHandler, File.expand_path("tina4/session_handlers/database_handler", __dir__)
   end
 
   # ── Lazy-loaded: queue backends ───────────────────────────────────────
@@ -71,6 +73,7 @@ module Tina4
     autoload :LiteBackend,     File.expand_path("tina4/queue_backends/lite_backend", __dir__)
     autoload :RabbitmqBackend, File.expand_path("tina4/queue_backends/rabbitmq_backend", __dir__)
     autoload :KafkaBackend,    File.expand_path("tina4/queue_backends/kafka_backend", __dir__)
+    autoload :MongoBackend,    File.expand_path("tina4/queue_backends/mongo_backend", __dir__)
   end
 
   # ── Lazy-loaded: web server ───────────────────────────────────────────
@@ -174,12 +177,61 @@ module Tina4
     #   Tina4.initialize!(__dir__)
     #   Tina4.run!
     # Or combined: Tina4.run!(__dir__)
-    def run!(root_dir = Dir.pwd)
+    def find_available_port(start, max_tries = 10)
+      require "socket"
+      max_tries.times do |offset|
+        port = start + offset
+        begin
+          server = TCPServer.new("127.0.0.1", port)
+          server.close
+          return port
+        rescue Errno::EADDRINUSE, Errno::EACCES
+          next
+        end
+      end
+      start
+    end
+
+    def open_browser(url)
+      require "rbconfig"
+      Thread.new do
+        sleep 2
+        case RbConfig::CONFIG["host_os"]
+        when /darwin/i then system("open", url)
+        when /mswin|mingw/i then system("start", url)
+        else system("xdg-open", url)
+        end
+      end
+    end
+
+    def run!(root_dir = nil, port: nil, host: nil, debug: nil)
+      # Handle legacy call: run!(port: 7147) where root_dir receives the hash
+      if root_dir.is_a?(Hash)
+        port ||= root_dir[:port]
+        host ||= root_dir[:host]
+        debug = root_dir[:debug] if debug.nil? && root_dir.key?(:debug)
+        root_dir = nil
+      end
+      root_dir ||= Dir.pwd
+
+      ENV["PORT"] = port.to_s if port
+      ENV["HOST"] = host.to_s if host
+      ENV["TINA4_DEBUG"] = debug.to_s unless debug.nil?
+
       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
 
+      actual_port = find_available_port(port)
+      if actual_port != port
+        Tina4::Log.info("Port #{port} in use, using #{actual_port}")
+        port = actual_port
+      end
+
+      display_host = (host == "0.0.0.0" || host == "::") ? "localhost" : host
+      url = "http://#{display_host}:#{port}"
+
       app = Tina4::RackApp.new(root_dir: root_dir)
       is_debug = Tina4::Env.truthy?(ENV["TINA4_DEBUG"])
 
@@ -203,6 +255,7 @@ module Tina4
           Tina4::Log.info("Production server: puma")
           Tina4::Shutdown.setup
 
+          open_browser(url)
           launcher = Puma::Launcher.new(config)
           launcher.run
           return
@@ -212,6 +265,7 @@ module Tina4
       end
 
       Tina4::Log.info("Development server: WEBrick")
+      open_browser(url)
       server = Tina4::WebServer.new(app, host: host, port: port)
       server.start
     end
@@ -286,6 +340,11 @@ module Tina4
       Tina4::Router.group(prefix, auth_handler: auth, &block)
     end
 
+    # WebSocket route registration
+    def websocket(path, &block)
+      Tina4::Router.websocket(path, &block)
+    end
+
     # Middleware hooks
     def before(pattern = nil, &block)
       Tina4::Middleware.before(pattern, &block)
@@ -355,8 +414,9 @@ module Tina4
     end
 
     def auto_discover(root_dir)
-      route_dirs = %w[routes src/routes src/api api]
-      route_dirs.each do |dir|
+      # src/ prefixed directories take priority over root-level ones
+      discover_dirs = %w[src/routes routes src/api api src/orm orm]
+      discover_dirs.each do |dir|
         full_dir = File.join(root_dir, dir)
         next unless Dir.exist?(full_dir)
 

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tina4ruby
 version: !ruby/object:Gem::Version
-  version: 3.2.1
+  version: 3.10.0
 platform: ruby
 authors:
 - Tina4 Team
+autorequire:
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-03-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -319,11 +320,14 @@ files:
 - lib/tina4/public/js/frond.min.js
 - lib/tina4/public/js/tina4-dev-admin.min.js
 - lib/tina4/public/js/tina4.min.js
+- lib/tina4/public/js/tina4js.min.js
 - lib/tina4/public/swagger/index.html
 - lib/tina4/public/swagger/oauth2-redirect.html
+- lib/tina4/query_builder.rb
 - lib/tina4/queue.rb
 - lib/tina4/queue_backends/kafka_backend.rb
 - lib/tina4/queue_backends/lite_backend.rb
+- lib/tina4/queue_backends/mongo_backend.rb
 - lib/tina4/queue_backends/rabbitmq_backend.rb
 - lib/tina4/rack_app.rb
 - lib/tina4/rate_limiter.rb
@@ -351,6 +355,7 @@ files:
 - lib/tina4/seeder.rb
 - lib/tina4/service_runner.rb
 - lib/tina4/session.rb
+- lib/tina4/session_handlers/database_handler.rb
 - lib/tina4/session_handlers/file_handler.rb
 - lib/tina4/session_handlers/mongo_handler.rb
 - lib/tina4/session_handlers/redis_handler.rb
@@ -369,9 +374,11 @@ files:
 - lib/tina4/templates/errors/503.twig
 - lib/tina4/templates/errors/base.twig
 - lib/tina4/testing.rb
+- lib/tina4/validator.rb
 - lib/tina4/version.rb
 - lib/tina4/webserver.rb
 - lib/tina4/websocket.rb
+- lib/tina4/websocket_backplane.rb
 - lib/tina4/wsdl.rb
 - lib/tina4ruby.rb
 homepage: https://tina4.com
@@ -379,6 +386,7 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://tina4.com
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -393,7 +401,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 3.4.19
+signing_key:
 specification_version: 4
 summary: Simple. Fast. Human. This is not a framework.
 test_files: []