tina4ruby 3.13.94 → 3.13.96

data/lib/tina4/sql_translator.rb

@@ -153,6 +153,116 @@ module Tina4
         raw = params ? "#{sql}|#{params.inspect}" : sql
         "query:#{Digest::SHA256.hexdigest(raw)}"
       end
+
+      # Collapse a row-at-a-time INSERT batch into chunked multi-row VALUES.
+      #
+      # A batch that loops one INSERT per row pays a full network round-trip per
+      # row, and the round-trip - not SQL building - is the entire cost of a
+      # batch write. Measured over 500 rows: PostgreSQL 9848ms row-at-a-time
+      # against 15.8ms as a single multi-row statement (625x), MySQL 216x,
+      # MSSQL 121x.
+      #
+      # PURE: no I/O and no engine contact, so the chunking rules are checkable
+      # without a database. The live-engine runners prove the rows land.
+      #
+      # @param sql [String] the single-row INSERT the batch would loop
+      # @param params_list [Array<Array>] one entry per row
+      # @param engine [String] engine name as the driver reports it (aliases ok)
+      # @return [Array<Array(String, Array)>] statements to run INSTEAD of the
+      #   loop, or an EMPTY array meaning "not collapsible - keep looping",
+      #   which is always correct.
+      # Normalise a collapsed batch's last id to the LAST row's id.
+      #
+      # A row-at-a-time batch reports the last row's id simply because the last
+      # statement inserted the last row. Collapsing rows into one statement
+      # changes that on any engine that reports the FIRST generated id, so this
+      # restores the contract instead of quietly redefining it.
+      #
+      # Verified live, not assumed: a 3-row insert into a fresh MySQL table
+      # reports 1 while MAX(id) is 3. SQLite, PostgreSQL and MSSQL already
+      # report the last and are left alone. The ids in one statement are
+      # consecutive, so the last is +first + rows - 1+.
+      def batch_last_id(reported_id, rows_in_chunk, engine)
+        name = engine.to_s.downcase
+        name = ENGINE_ALIASES.fetch(name, name)
+        return reported_id unless FIRST_ID_ENGINES.include?(name)
+        return reported_id unless reported_id.is_a?(Integer) || reported_id.to_s.match?(/\A-?\d+\z/)
+
+        reported_id.to_i + [rows_in_chunk.to_i, 1].max - 1
+      end
+
+      def build_batch_inserts(sql, params_list, engine)
+        rows = params_list || []
+        return [] if rows.length < 2
+
+        name = engine.to_s.downcase
+        name = ENGINE_ALIASES.fetch(name, name)
+        cap = MAX_BIND_PARAMS.fetch(name, 0)
+        # Firebird has no multi-row VALUES syntax; ODBC's real ceiling depends on
+        # the driver behind it. Emitting SQL the engine cannot parse to save a
+        # round-trip is not a trade worth making.
+        return [] if cap <= 0
+
+        upper = sql.upcase
+        # A collapsed statement returns N rows where the caller expects one, and
+        # conflict arbitration changes once rows share a statement.
+        return [] if upper.include?("RETURNING") ||
+                     upper.include?("ON CONFLICT") ||
+                     upper.include?("ON DUPLICATE KEY")
+
+        match = INSERT_VALUES.match(sql)
+        return [] if match.nil?
+
+        # Every slot must be a bare placeholder. `now()` repeated per row inside
+        # one statement is not the same write as `now()` evaluated per statement.
+        slots = match[1].split(",").map(&:strip)
+        return [] if slots.empty? || slots.any? { |slot| slot != "?" }
+
+        columns = slots.length
+        return [] if rows.any? { |params| params.length != columns }
+
+        chunk_rows = [1, cap / columns].max
+        return [] if chunk_rows < 2
+
+        head = sql[0...(match.begin(1) - 1)].rstrip
+        one_row = "(#{Array.new(columns, '?').join(', ')})"
+
+        rows.each_slice(chunk_rows).map do |chunk|
+          ["#{head} #{Array.new(chunk.length, one_row).join(', ')}", chunk.flatten(1)]
+        end
+      end
     end
+
+    # Hard per-statement bind-parameter ceiling per engine. 0 = never collapse.
+    # Sourced from spec/fixtures/batch_write_contract.json, byte-identical in
+    # all four frameworks.
+    MAX_BIND_PARAMS = {
+      "sqlite" => 999,
+      "postgres" => 65_535,
+      "mysql" => 65_535,
+      "mssql" => 2_100,
+      "firebird" => 0,
+      "odbc" => 0,
+      "mongodb" => 0
+    }.freeze
+
+    # The four frameworks do not agree on what an engine calls itself - Python
+    # and PHP report "postgresql", Ruby and Node report "postgres". Without
+    # normalising, the cap lookup misses and the collapse silently does nothing
+    # on the engine with the largest win.
+    ENGINE_ALIASES = {
+      "postgresql" => "postgres",
+      "pgsql" => "postgres",
+      "sqlite3" => "sqlite",
+      "sqlserver" => "mssql",
+      "sqlsrv" => "mssql",
+      "mariadb" => "mysql"
+    }.freeze
+
+    INSERT_VALUES = /\A\s*INSERT\s+INTO\s+.+?\s+VALUES\s*\(([^()]*)\)\s*\z/im
+
+    # Engines whose last_insert_id reports the FIRST generated id of a multi-row
+    # INSERT rather than the last. Verified live against MySQL.
+    FIRST_ID_ENGINES = %w[mysql].freeze
   end
 end

data/lib/tina4/swagger.rb

@@ -87,8 +87,14 @@ module Tina4
       def base_spec
         info = {
           "title" => ENV["TINA4_SWAGGER_TITLE"] || ENV["PROJECT_NAME"] || "Tina4 API",
-          "version" => ENV["TINA4_SWAGGER_VERSION"] || Tina4::VERSION,
-          "description" => ENV["TINA4_SWAGGER_DESCRIPTION"] || "Auto-generated API documentation"
+          # info.version is the APPLICATION's API version, not the framework's.
+          # Defaulting to Tina4::VERSION made an undocumented app claim API
+          # v3.13.x; "1.0.0" is the settled cross-framework default (Python/PHP).
+          # TINA4_SWAGGER_VERSION still overrides.
+          "version" => ENV["TINA4_SWAGGER_VERSION"] || "1.0.0",
+          # Empty by default (parity) — a canned "Auto-generated..." blurb is
+          # noise in a real API's docs. Set TINA4_SWAGGER_DESCRIPTION to fill it.
+          "description" => ENV["TINA4_SWAGGER_DESCRIPTION"] || ""
         }
 
         # Optional contact block — only emitted when at least one field is set.
@@ -228,6 +234,8 @@ module Tina4
         tags = meta[:tags] || [extract_tag(route.path)]
         tags.each { |t| ctx[:used_tags] << t unless ctx[:used_tags].include?(t) }
 
+        security = resolve_security(meta, route, ctx[:schemes])
+
         spec["paths"][path] ||= {}
         operation = {
           "operationId" => unique_operation_id(method, path, ctx[:seen_ids]),
@@ -239,10 +247,18 @@ module Tina4
         }
 
         operation["deprecated"] = true if meta[:deprecated]
-
-        security = resolve_security(meta, route, ctx[:schemes])
         operation["security"] = security unless security.nil?
 
+        # A route emits 401 WHEN AND ONLY WHEN it is documented as secured (a
+        # non-empty security requirement). An undecorated route carries only
+        # 200; nothing invents 400/404/500, and an explicitly public route
+        # (security == []) gets no 401. Mirrors PHP; drops the old
+        # default_responses that stamped 200/400/401/404/500 on every operation
+        # including a public GET.
+        if security && !security.empty? && !operation["responses"].key?("401")
+          operation["responses"]["401"] = { "description" => "Unauthorized" }
+        end
+
         if %w[post put patch].include?(method)
           operation["requestBody"] = build_request_body(method, meta, ref, ctx)
         end
@@ -259,7 +275,18 @@ module Tina4
           return reqs.empty? ? [] : sanitize_security(reqs, schemes)
         end
 
-        return sanitize_security([{ default_scheme => [] }], schemes) if route.auth_handler
+        # auth_required is what DISPATCH enforces: true by default on
+        # POST/PUT/PATCH/DELETE, flipped by `.secure` / `.no_auth`. This branch
+        # read `auth_handler` instead, which defaults to nil and is set only by
+        # the `auth:` keyword or the secure_* helpers - so every write route
+        # registered the ordinary way was enforced-secured and documented
+        # PUBLIC, and `.secure` on a GET never reached the document at all.
+        # MEASURED: POST /api/items answered 401 while its operation carried no
+        # security key, in the framework's own AutoCrud output too.
+        #
+        # Both flags are honoured. A custom auth_handler protects a route even
+        # when auth_required is false for its method, so it is still documented.
+        return sanitize_security([{ default_scheme => [] }], schemes) if route.auth_required || route.auth_handler
 
         nil
       end
@@ -364,8 +391,13 @@ module Tina4
         end
       end
 
+      # A route's success response. An undecorated route emits ONLY 200
+      # (description-only); with a model ref the 200 carries the schema. The
+      # 401-on-secured addition happens in add_route_to_spec, not here.
       def model_or_default_responses(ref, model_list)
-        return default_responses unless ref
+        unless ref
+          return { "200" => { "description" => "Successful response" } }
+        end
 
         schema = model_list ? { "type" => "array", "items" => { "$ref" => ref } } : { "$ref" => ref }
         {
@@ -393,9 +425,19 @@ module Tina4
         first
       end
 
+      # operationId is a generated client's METHOD NAME, so two distinct paths
+      # must produce two distinct ids. Preserve the path's own underscores —
+      # /__health -> get___health, /health -> get_health — instead of collapsing
+      # both to get_health and suffixing _2 onto whichever registered second
+      # (order-dependent). Mirrors the Python master: strip the outer slashes,
+      # turn internal "/" into "_", drop the {} around params, map a splat to
+      # "wildcard", and DO NOT collapse repeated underscores.
       def unique_operation_id(method, path, seen)
-        base = method + path.gsub(%r{[/{}*]}) { |c| c == "*" ? "wildcard" : "_" }
-        base = base.gsub(/_+/, "_").chomp("_")
+        clean = path.gsub(%r{\A/+|/+\z}, "")
+                    .gsub("/", "_")
+                    .delete("{}")
+                    .gsub("*", "wildcard")
+        base = clean.empty? ? method : "#{method}_#{clean}"
         oid = base
         n = 2
         while seen.include?(oid)
@@ -486,16 +528,6 @@ module Tina4
           nil
         end
       end
-
-      def default_responses
-        {
-          "200" => { "description" => "Successful response" },
-          "400" => { "description" => "Bad request" },
-          "401" => { "description" => "Unauthorized" },
-          "404" => { "description" => "Not found" },
-          "500" => { "description" => "Internal server error" }
-        }
-      end
     end
   end
 end

data/lib/tina4/version.rb

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

data/lib/tina4/webserver.rb

@@ -5,13 +5,16 @@ module Tina4
     DEFAULT_HOST = "0.0.0.0"
     DEFAULT_PORT = 7147
 
-    # TINA4_HOST overrides the bind address when caller doesn't pass `host:`.
+    # Bind address and port, when the caller does not pass host:/port:.
+    #
+    # Both go through Tina4.resolve_bind_* so this and Tina4.start! cannot
+    # drift apart - they already had: this file read TINA4_PORT first while
+    # tina4.rb read bare PORT first, so the same variable meant different
+    # things depending which entry point you came through.
     def initialize(app, host: nil, port: nil)
       @app = app
-      env_host = ENV["TINA4_HOST"]
-      @host = host || (env_host && !env_host.empty? ? env_host : DEFAULT_HOST)
-      env_port = ENV["TINA4_PORT"] || ENV["PORT"]
-      @port = port || (env_port && !env_port.empty? ? env_port.to_i : DEFAULT_PORT)
+      @host = host || Tina4.resolve_bind_host(DEFAULT_HOST)
+      @port = port || Tina4.resolve_bind_port(DEFAULT_PORT)
     end
 
     # Kill whatever process is listening on *port*.
@@ -130,7 +133,18 @@ module Tina4
         end
 
         define_method(:handle_request) do |webrick_req, webrick_res|
-          # Reject new requests during shutdown
+          # Belt-and-braces, NOT the primary mechanism. Shutdown closes the
+          # listening socket FIRST, so a connection arriving after the signal is
+          # refused by the kernel and never reaches here. What is left is a
+          # genuine race: WEBrick accepts a connection and parses its request in
+          # a worker thread, and the @shutting_down flag can flip in the gap
+          # before that worker reaches this line.
+          #
+          # Measured (macOS 26.5.2, Ruby 4.0.2, webrick 1.9.2, 48 threads
+          # hammering across a real SIGTERM): the window is the ~10-90ms between
+          # the flag flip and the listener actually closing, and 0-2 requests per
+          # run land in it out of ~2000. Every request after that is
+          # ECONNREFUSED. Rare, but reachable - so the guard stays.
           if Tina4::Shutdown.shutting_down?
             webrick_res.status = 503
             webrick_res.body = '{"error":"Service shutting down"}'
@@ -232,6 +246,8 @@ module Tina4
             end
 
             define_method(:handle_request) do |webrick_req, webrick_res|
+              # Same accepted-a-moment-before-the-listener-closed race as the
+              # main servlet above - see the comment there.
               if Tina4::Shutdown.shutting_down?
                 webrick_res.status = 503
                 webrick_res.body = '{"error":"Service shutting down"}'
@@ -299,6 +315,12 @@ module Tina4
       end
 
       @server.start
+
+      # Shutdown closes the listener FIRST, so #start returns as soon as the
+      # in-flight workers are joined - potentially while the signal handler's
+      # thread is still stopping background tasks and closing the database.
+      # Wait for that teardown instead of exiting out from under it.
+      Tina4::Shutdown.wait_for_completion
     end
 
     def stop