tina4ruby 3.13.93 → 3.13.96

data/lib/tina4.rb

@@ -9,7 +9,10 @@ require_relative "tina4/env"
 require_relative "tina4/router"
 require_relative "tina4/request"
 require_relative "tina4/response"
+require_relative "tina4/dispatch_pipeline"
 require_relative "tina4/rack_app"
+require_relative "tina4/database_adapter"
+require_relative "tina4/database_url"
 require_relative "tina4/database"
 require_relative "tina4/database_result"
 require_relative "tina4/field_types"
@@ -53,6 +56,51 @@ require_relative "tina4/mcp"
 require_relative "tina4/realtime"
 
 module Tina4
+  # Bind address, with the framework name winning over the bare one.
+  #
+  # TINA4_HOST > HOST (deprecated) > default. See resolve_bind_port.
+  def self.resolve_bind_host(default = "0.0.0.0")
+    tina4_host = ENV["TINA4_HOST"]
+    return tina4_host if tina4_host && !tina4_host.empty?
+
+    legacy = ENV["HOST"]
+    if legacy && !legacy.empty?
+      warn_deprecated_bind_var("HOST", "TINA4_HOST", legacy)
+      return legacy
+    end
+    default
+  end
+
+  # Bind port, with the framework name winning over the bare one.
+  #
+  # TINA4_PORT > PORT (deprecated) > default. Bare PORT is a name anything can
+  # set - a shared CI runner, a PaaS, another tool - and it should never
+  # outrank the framework's own variable. It is still honoured so no deployment
+  # breaks; the warning is what drives the move. Removal is 3.14.
+  def self.resolve_bind_port(default = 7147)
+    tina4_port = ENV["TINA4_PORT"]
+    return tina4_port.to_i if tina4_port && tina4_port.match?(/\A\d+\z/)
+
+    legacy = ENV["PORT"]
+    if legacy && legacy.match?(/\A\d+\z/)
+      warn_deprecated_bind_var("PORT", "TINA4_PORT", legacy)
+      return legacy.to_i
+    end
+    default
+  end
+
+  # Warn ONCE per variable. Repeated on every call it is noise people filter.
+  def self.warn_deprecated_bind_var(old_name, new_name, value)
+    @warned_bind_vars ||= {}
+    return if @warned_bind_vars[old_name]
+
+    @warned_bind_vars[old_name] = true
+    Tina4::Log.warning(
+      "#{old_name} is deprecated and will be removed in 3.14 - use " \
+      "#{new_name} instead (using #{value} from #{old_name})"
+    )
+  end
+
   # ── Lazy-loaded: database drivers ─────────────────────────────────────
   module Drivers
     autoload :SchemaSplit,    File.expand_path("tina4/drivers/schema_split", __dir__)
@@ -71,6 +119,7 @@ module Tina4
     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 :MemcachedHandler, File.expand_path("tina4/session_handlers/memcached_handler", __dir__)
     autoload :DatabaseHandler, File.expand_path("tina4/session_handlers/database_handler", __dir__)
   end
 
@@ -127,10 +176,148 @@ module Tina4
   autoload :Messenger,           File.expand_path("tina4/messenger", __dir__)
   autoload :MessengerError,      File.expand_path("tina4/messenger", __dir__)
   autoload :MessengerConnectionError, File.expand_path("tina4/messenger", __dir__)
-  autoload :DevMessengerProxy,   File.expand_path("tina4/messenger", __dir__)
+
+  # Factory for a Messenger configured from the environment.
+  #
+  # Defined HERE, eagerly, and not in messenger.rb: `autoload` only fires on a
+  # CONSTANT reference, and a module function is not a constant. A cold
+  # `require "tina4"; Tina4.create_messenger` therefore raised NoMethodError until
+  # something else happened to touch Tina4::Messenger first -- the documented entry
+  # point was unreachable on a fresh process. Naming the constant below is what
+  # triggers the autoload.
+  def self.create_messenger(**options)
+    Tina4::Messenger.create_messenger(**options)
+  end
+
+  # ── dotenv surface, at the top level ──────────────────────────────
+  #
+  # Python, PHP and Node all expose these as plain module/namespace functions.
+  # Ruby had them only as Tina4::Env.*, so the obvious cross-framework call
+  # (Tina4.load_env) raised NoMethodError - a parity defect by the audit's rule
+  # that a concept carries one name in all four, differing only in casing.
+  #
+  # These are thin delegators, defined EAGERLY for the same reason
+  # create_messenger above is: `autoload` fires on a CONSTANT reference, and a
+  # module function is not a constant, so a cold `require "tina4"` would
+  # otherwise leave the documented entry point unreachable until something else
+  # happened to touch Tina4::Env first. Naming Tina4::Env inside each body is
+  # what triggers the autoload.
+  #
+  # Tina4::Env.* stays as the implementation namespace (PHP keeps Env:: the same
+  # way). Neither is an alias of the other - one is the surface, one is the home.
+
+  # Load .env.local then .env from a ROOT DIRECTORY (canonical in all four).
+  def self.load_env(root = nil)
+    root.nil? ? Tina4::Env.load_env : Tina4::Env.load_env(root)
+  end
+
+  def self.get_env(key, default = nil)
+    Tina4::Env.get_env(key, default)
+  end
+
+  # Raises KeyError naming EVERY missing variable; returns the requested map.
+  def self.require_env(*keys)
+    Tina4::Env.require_env(*keys)
+  end
+
+  def self.has_env?(key)
+    Tina4::Env.has_env?(key)
+  end
+
+  def self.all_env
+    Tina4::Env.all_env
+  end
+
+  def self.reset_env
+    Tina4::Env.reset_env
+  end
+
+  def self.truthy?(value)
+    Tina4::Env.is_truthy(value)
+  end
+
+  # Parsed TINA4_TRUSTED_PROXIES, cached on the raw env string so a change is
+  # picked up but the parse does not run per request. [raw_value, networks]
+  @trusted_proxy_cache = [nil, [].freeze]
+
+  # The configured trusted-proxy networks, from TINA4_TRUSTED_PROXIES.
+  #
+  # Comma-separated exact addresses and/or CIDR ranges, IPv4 and IPv6:
+  # "10.0.0.0/8, 192.168.1.5, ::1, fd00::/8". Empty or unset means trust
+  # NOTHING, which is the secure default: X-Forwarded-For is then ignored
+  # entirely and the raw socket peer identifies the client. See ADR-0019.
+  def self.trusted_proxy_networks
+    raw = ENV["TINA4_TRUSTED_PROXIES"].to_s
+    cached_raw, cached_networks = @trusted_proxy_cache
+    return cached_networks if raw == cached_raw
+
+    networks = []
+    raw.split(",").each do |entry|
+      entry = normalise_ip(entry)
+      next if entry.empty?
+
+      begin
+        networks << IPAddr.new(entry)
+      rescue IPAddr::Error, ArgumentError
+        # Loud, and exactly once per distinct config value (the cache below
+        # means this parse runs once). A silently-skipped entry would leave a
+        # real proxy untrusted, which looks like the app over-limiting every
+        # client - a very expensive typo to debug.
+        Tina4::Log.error(
+          "TINA4_TRUSTED_PROXIES: ignoring invalid entry '#{entry}' - " \
+          "expected an IP address or CIDR range, e.g. 10.0.0.0/8 or 192.168.1.5"
+        )
+      end
+    end
+    @trusted_proxy_cache = [raw, networks.freeze]
+    @trusted_proxy_cache[1]
+  end
+
+  # Is this address a configured trusted proxy?
+  def self.trusted_proxy?(address)
+    networks = trusted_proxy_networks
+    return false if networks.empty?
+
+    address = normalise_ip(address)
+    return false if address.empty?
+
+    begin
+      parsed = IPAddr.new(address)
+    rescue IPAddr::Error, ArgumentError
+      return false
+    end
+    # A peer arriving as ::ffff:10.0.0.1 must match an allow-list entry of
+    # 10.0.0.0/8 - dual-stack listeners hand out the mapped form routinely.
+    parsed = parsed.native if parsed.ipv4_mapped?
+    networks.any? { |network| network.include?(parsed) }
+  end
+
+  # Strip the decorations a peer address can arrive with: the "[::1]" bracket
+  # form and an IPv6 zone id ("fe80::1%eth0").
+  def self.normalise_ip(value)
+    value = value.to_s.strip
+    value = value[1...value.index("]")].to_s if value.start_with?("[") && value.include?("]")
+    value = value.split("%", 2).first.to_s if value.include?("%")
+    value
+  end
+
+  def self.env_bool(name, default: false)
+    Tina4::Env.bool(name, default: default)
+  end
+
+  def self.env_int(name, default: 0)
+    Tina4::Env.int(name, default: default)
+  end
+
+  def self.env_float(name, default: 0.0)
+    Tina4::Env.float(name, default: default)
+  end
+
+  def self.env_str(name, default: "")
+    Tina4::Env.str(name, default: default)
+  end
   autoload :IMAP_CONNECTION_ERRORS, File.expand_path("tina4/messenger", __dir__)
   autoload :DocStore,            File.expand_path("tina4/docstore", __dir__)
-  autoload :ScssCompiler,        File.expand_path("tina4/scss_compiler", __dir__)
   autoload :FakeData,            File.expand_path("tina4/seeder", __dir__)
   autoload :WSDL,                File.expand_path("tina4/wsdl", __dir__)
   # Validator is a counted framework feature and belongs on the main
@@ -245,8 +432,19 @@ module Tina4
       # (.env.local loads first, both first-wins, so a real env var always wins).
       Tina4::Env.load_env(root_dir)
 
-      # Setup debug logging
-      Tina4::Log.configure(root_dir)
+      # Setup debug logging.
+      #
+      # No argument here, deliberately (ADR-0041). This used to pass `root_dir`,
+      # and since Ruby correctly lets an explicit argument beat the environment,
+      # that had two measured consequences in every booted Ruby app:
+      # TINA4_LOG_DIR was ENTIRELY DEAD -- the documented variable could not
+      # move the logs anywhere -- and because root_dir is an existing directory
+      # it became the log directory itself, so tina4.log and error.log were
+      # written into the PROJECT ROOT rather than the documented logs/.
+      # root_dir is the framework's default, not a user instruction, so it
+      # belongs below the environment. Resolution is now TINA4_LOG_DIR, then
+      # logs/, matching Python and Node.
+      Tina4::Log.configure
       Tina4::Log.info("Tina4 Ruby v#{VERSION} initializing...")
 
       # Fail-safe dev secret: in dev (and NOT CI/prod) mint a per-machine
@@ -267,6 +465,13 @@ module Tina4
       # Connect database if configured
       setup_database
 
+      # Framework routes FIRST, then the app's. Routes resolve in registration
+      # order, so anything registered later cannot shadow these - and an app
+      # with an ordinary catch-all (`any("/{slug}")`) would otherwise swallow
+      # /__health, which is exactly what a container health check probes.
+      # Python registers its built-ins first for the same reason.
+      register_builtin_routes!
+
       # Auto-discover routes
       auto_discover(root_dir)
 
@@ -333,16 +538,30 @@ module Tina4
 
       initialize!(root_dir) unless @root_dir
 
-      # Built-in routes. These used to be registered ONLY by the CLI's
-      # cmd_start, so an app booted the documented way -- `Tina4.run!` from
-      # app.rb, which is exactly what `tina4 init ruby` scaffolds -- served 404
-      # on /health while the identical code under `tina4ruby serve` served 200.
-      # A container health check pointed at /health therefore failed against a
-      # perfectly healthy app.
+      # Built-in routes now register inside initialize!, BEFORE route discovery,
+      # so they cannot be shadowed by an app catch-all. Kept here as a safety net
+      # for a caller that reaches run! without initialize! having run (the guard
+      # above skips it when @root_dir is already set). register! is idempotent
+      # and Router.add replaces in place, so a second call is a no-op.
+      #
+      # They used to be registered ONLY by the CLI's cmd_start, so an app booted
+      # the documented way -- `Tina4.run!` from app.rb, which is what
+      # `tina4 init ruby` scaffolds -- served 404 on /health while the identical
+      # code under `tina4ruby serve` served 200.
       register_builtin_routes!
 
-      host = ENV.fetch("HOST", ENV.fetch("TINA4_HOST", "0.0.0.0"))
-      port = ENV.fetch("PORT", ENV.fetch("TINA4_PORT", "7147")).to_i
+      # TINA4_HOST/TINA4_PORT BEFORE the bare names, not after.
+      #
+      # This had both the wrong way round: ENV.fetch("PORT", ...) returns PORT
+      # whenever it is set, so a stray OS-level HOST or PORT outranked the
+      # framework's own variable - the one the CLI documents and prefers, and
+      # the one Tina4::WebServer a few files away already reads first. Two code
+      # paths in one framework disagreeing about the same variable.
+      #
+      # Bare HOST/PORT stay honoured so nothing breaks, and warn so the
+      # migration happens. Removal is 3.14.
+      host = Tina4.resolve_bind_host
+      port = Tina4.resolve_bind_port(7147)
 
       actual_port = find_available_port(port)
       if actual_port != port
@@ -357,32 +576,10 @@ module Tina4
       is_debug = Tina4::Env.is_truthy(ENV["TINA4_DEBUG"])
 
       # Try Puma first (production-grade), fall back to WEBrick
-      if !is_debug
-        begin
-          require "puma"
-          require "puma/configuration"
-          require "puma/launcher"
-
-          config = Puma::Configuration.new do |user_config|
-            user_config.bind "tcp://#{host}:#{port}"
-            user_config.app app
-            user_config.threads 0, 16
-            user_config.workers 0
-            user_config.environment "production"
-            user_config.log_requests false
-            user_config.quiet
-          end
-
-          Tina4::Log.info("Production server: puma")
-          Tina4::Shutdown.setup
-
-          open_browser(url)
-          launcher = Puma::Launcher.new(config)
-          launcher.run
-          return
-        rescue LoadError
-          # Puma not installed, fall through to WEBrick
-        end
+      if !is_debug && !builtin_webserver_pinned? && puma_available?
+        open_browser(url)
+        start_puma_server(app, host: host, port: port)
+        return
       end
 
       Tina4::Log.info("Development server: WEBrick")
@@ -391,6 +588,72 @@ module Tina4
       server.start
     end
 
+    # TINA4_DEFAULT_WEBSERVER=TRUE pins Tina4's BUILT-IN server (WEBrick) even
+    # in production, where Puma would otherwise be chosen. Unset/FALSE keeps
+    # today's behaviour, so this is non-breaking.
+    #
+    # This is NOT the remedy for a production shutdown problem - an operator
+    # must never have to give up Puma to get their database connections closed.
+    # It exists so CI can pin the built-in server deterministically without
+    # having to switch TINA4_DEBUG on to get there.
+    def builtin_webserver_pinned?
+      Tina4::Env.is_truthy(ENV["TINA4_DEFAULT_WEBSERVER"])
+    end
+
+    # Is Puma loadable? Separate from start_puma_server so the caller can fall
+    # back to WEBrick BEFORE any side effect (opening a browser) happens.
+    def puma_available?
+      require "puma"
+      require "puma/configuration"
+      require "puma/launcher"
+      true
+    rescue LoadError
+      false
+    end
+
+    # Boot the production server (Puma) with Tina4's shutdown contract wired in.
+    #
+    # Feature 9's OUTCOMES are the framework's contract whichever server owns
+    # the socket; the MECHANISM differs per server. Puma already stops
+    # accepting and drains in-flight requests properly, so that is CONFIGURED,
+    # not reimplemented:
+    #
+    #   * TINA4_SHUTDOWN_TIMEOUT -> Puma's force_shutdown_after. Puma's default
+    #     is :forever, so before this the documented env var meant NOTHING on
+    #     the path operators actually run.
+    #   * raise_exception_on_sigterm false -> Puma's default is true, which
+    #     re-raises SignalException after the graceful stop and terminates the
+    #     process BY the signal. The contract is a clean exit 0.
+    #
+    # What Puma cannot know about is ours, and runs in the ensure: live
+    # WebSocket peers get RFC 6455 1001, background tasks stop, and every
+    # database connection is closed. Nothing but Tina4 knows those connections
+    # exist, so without this they leaked on every production shutdown.
+    def start_puma_server(app, host:, port:)
+      # Puma owns INT/TERM here, so Tina4 installs no handlers of its own.
+      Tina4::Shutdown.setup(trap_signals: false)
+      shutdown_timeout = Tina4::Shutdown.timeout
+
+      config = Puma::Configuration.new do |user_config|
+        user_config.bind "tcp://#{host}:#{port}"
+        user_config.app app
+        user_config.threads 0, 16
+        user_config.workers 0
+        user_config.environment "production"
+        user_config.log_requests false
+        user_config.quiet
+        user_config.force_shutdown_after shutdown_timeout
+        user_config.raise_exception_on_sigterm false
+      end
+
+      Tina4::Log.info("Production server: puma (TINA4_SHUTDOWN_TIMEOUT=#{shutdown_timeout}s)")
+      begin
+        Puma::Launcher.new(config).run
+      ensure
+        Tina4::Shutdown.release_resources
+      end
+    end
+
     # DSL methods for route registration
     # GET is public by default (matching tina4_python behavior)
     # POST/PUT/PATCH/DELETE are secured by default — use auth: false to make public

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tina4ruby
 version: !ruby/object:Gem::Version
-  version: 3.13.93
+  version: 3.13.96
 platform: ruby
 authors:
 - Tina4 Team
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-27 00:00:00.000000000 Z
+date: 2026-08-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -52,20 +52,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '6.0'
-- !ruby/object:Gem::Dependency
-  name: jwt
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.7'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.7'
 - !ruby/object:Gem::Dependency
   name: net-smtp
   requirement: !ruby/object:Gem::Requirement
@@ -206,6 +192,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.19'
+- !ruby/object:Gem::Dependency
+  name: bigdecimal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
 - !ruby/object:Gem::Dependency
   name: pg
   requirement: !ruby/object:Gem::Requirement
@@ -290,6 +290,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.50'
+- !ruby/object:Gem::Dependency
+  name: openapi3_parser
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
 description: 'TINA4: The Intelligent Native Application 4ramework for Ruby — Simple.
   Fast. Human. Built for AI. Built for you. 54 built-in features, minimal dependencies
   (Rack-based; the runtime gems are production-deployment essentials, not framework
@@ -330,11 +344,14 @@ files:
 - lib/tina4/crud.rb
 - lib/tina4/database.rb
 - lib/tina4/database/sqlite3_adapter.rb
+- lib/tina4/database_adapter.rb
 - lib/tina4/database_result.rb
+- lib/tina4/database_url.rb
 - lib/tina4/debug.rb
 - lib/tina4/dev.rb
 - lib/tina4/dev_admin.rb
 - lib/tina4/dev_mailbox.rb
+- lib/tina4/dispatch_pipeline.rb
 - lib/tina4/docs.rb
 - lib/tina4/docstore.rb
 - lib/tina4/drivers/firebird_driver.rb
@@ -434,14 +451,15 @@ files:
 - lib/tina4/scss/tina4css/base.scss
 - lib/tina4/scss/tina4css/colors.scss
 - 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
 - lib/tina4/session_handlers/file_handler.rb
+- lib/tina4/session_handlers/memcached_handler.rb
 - lib/tina4/session_handlers/mongo_handler.rb
+- lib/tina4/session_handlers/mongo_wire_client.rb
 - lib/tina4/session_handlers/redis_handler.rb
 - lib/tina4/session_handlers/resp_client.rb
 - lib/tina4/session_handlers/valkey_handler.rb