tina4ruby 3.13.68 → 3.13.70

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2df4dd4df920f7515ff0d958f4974886d74eacb4ead581b42a913b54ac3124e4
-  data.tar.gz: cec0373181fc77921ce01a8bc19e08492ca17bc10635ea534a273c62ee7b3684
+  metadata.gz: 87f4e1923c2fc20dbfdce286957c5e0505ccc37091e51ea6b0286041a342dacc
+  data.tar.gz: be4a0fc97b935313a27f8b5f53941cff0e939c10d73a5fbca081409a010db210
 SHA512:
-  metadata.gz: 0ffb3bd3d71c9a404486a4b74d03a361b7c74d80d15b120923c326295f97bc629effc52666477098aeada3ffc592d32e5caee38760e3781695a0c3bc5a9b84de
-  data.tar.gz: 6df31ce14a217e7c73ff4fd92a6ad16c7ee3587bdf6c1b730cb794488ec8dadbaeb9b4420c23a7b7467ea687f73f5cb3c59dab91758e6d59f2cc199f4d9669e7
+  metadata.gz: 44806d41e9bcbc45e4666a484a026ac7bb7c90babb8d7e5e031cd5316995f5faa7f9b303760e3339d67a2540aaddcd1fc29f1ca553593f15788c86048c8f8c8b
+  data.tar.gz: a4c84561d96968f9ca8c5eafaebb4cfd480a3693a88b63d7c694d64bedc9a4fa232e87c405f1a0e72693751c8a273d5969606fe115dfd879e9e8b60d7033e6af

data/lib/tina4/api.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
+
 require "net/http"
 require "openssl"
 require "uri"
 require "json"
 require "base64"
+require "securerandom"
 
 module Tina4
   # Statuses that warrant an automatic retry when max_retries > 0: rate-limit
@@ -12,6 +14,51 @@ module Tina4
   # master's _RETRY_STATUSES.
   API_RETRY_STATUSES = [429, 500, 502, 503, 504].freeze
 
+  # Streaming download reads/writes this many bytes per chunk so a multi-megabyte
+  # body never lands in memory in one piece. Parity with the Python master's
+  # _DOWNLOAD_CHUNK_SIZE.
+  API_DOWNLOAD_CHUNK_SIZE = 64 * 1024
+
+  # Redirect codes we follow (301/302/303/307/308). Net::HTTP does NOT auto-follow,
+  # so the client follows them itself in a bounded loop (see #network_call).
+  API_REDIRECT_STATUSES = [301, 302, 303, 307, 308].freeze
+
+  # Upper bound on redirect hops before we stop following and return the last
+  # 3xx response. Matches urllib's default (Python master).
+  API_MAX_REDIRECTS = 10
+
+  # Headers dropped when a redirect crosses to a different origin — a bearer
+  # token or a session cookie must never be handed to a host you didn't
+  # authenticate to. Compared case-insensitively. Parity with the Python
+  # master's _STRIP_ON_CROSS_ORIGIN.
+  API_STRIP_ON_CROSS_ORIGIN = %w[authorization cookie].freeze
+
+  # A curated extension -> MIME map for guessing a multipart part's Content-Type
+  # from its filename (Ruby core ships no mimetypes db, and pulling one in would
+  # break the zero-dependency promise). tina4: a small built-in map covering the
+  # common upload types; anything unlisted falls back to application/octet-stream.
+  # Mirrors the guess-with-fallback the Python master gets from mimetypes.
+  API_MIME_BY_EXTENSION = {
+    "png" => "image/png", "jpg" => "image/jpeg", "jpeg" => "image/jpeg",
+    "gif" => "image/gif", "webp" => "image/webp", "svg" => "image/svg+xml",
+    "bmp" => "image/bmp", "ico" => "image/x-icon", "tif" => "image/tiff",
+    "tiff" => "image/tiff",
+    "pdf" => "application/pdf", "json" => "application/json",
+    "xml" => "application/xml", "zip" => "application/zip",
+    "gz" => "application/gzip", "tar" => "application/x-tar",
+    "csv" => "text/csv", "txt" => "text/plain", "html" => "text/html",
+    "htm" => "text/html", "css" => "text/css", "js" => "text/javascript",
+    "md" => "text/markdown",
+    "mp3" => "audio/mpeg", "wav" => "audio/wav", "ogg" => "audio/ogg",
+    "mp4" => "video/mp4", "mov" => "video/quicktime", "webm" => "video/webm",
+    "doc" => "application/msword",
+    "docx" => "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    "xls" => "application/vnd.ms-excel",
+    "xlsx" => "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    "ppt" => "application/vnd.ms-powerpoint",
+    "pptx" => "application/vnd.openxmlformats-officedocument.presentationml.presentation"
+  }.freeze
+
   class API
     attr_reader :base_url, :headers
 
@@ -32,9 +79,33 @@ module Tina4
     # (429/5xx). A retried non-idempotent request (POST/PUT/PATCH/DELETE) may be
     # re-sent — retries are opt-in for exactly that reason. Parity with the
     # Python master.
+    #
+    # 3.13.69: +transport (an injectable seam) and +cookies (an opt-in per-client
+    # cookie jar), both parity with the Python master.
+    #
+    # `transport` (default nil = the real Net::HTTP network path) is an injectable
+    # seam so that APPLICATION developers can unit-test their own code without a
+    # live server. When supplied it must respond to #call with the signature
+    # `call(method, url, headers, body, timeout)` and return a Hash shaped like
+    # `{http_code:/status:, body:, headers:, error:}` (string or symbol keys). It
+    # fully REPLACES the network call. NOTE: Tina4's own suite must NEVER inject a
+    # fake/canned transport — the no-mock rule stands, so framework tests always
+    # exercise the real network path against a real local server. The seam exists
+    # purely for application-developer testing.
+    #
+    # `cookies` (default false = off, zero behaviour change) turns on a
+    # per-client, in-memory cookie jar: `Set-Cookie` headers on responses are
+    # parsed (leading name=value only, last write wins) and the accumulated
+    # `Cookie` header is sent on subsequent requests. Not persisted; scoped to
+    # this instance.
     def initialize(base_url, headers: {}, timeout: 30,
                    bearer_token: nil, username: nil, password: nil,
-                   verify_ssl: nil, max_retries: 0, retry_backoff: 0.5)
+                   verify_ssl: nil, max_retries: 0, retry_backoff: 0.5,
+                   transport: nil, cookies: false)
+      if !transport.nil? && !transport.respond_to?(:call)
+        raise ArgumentError, "transport must respond to #call(method, url, headers, body, timeout)"
+      end
+
       @base_url = base_url.chomp("/")
       @headers = {
         "Content-Type" => "application/json",
@@ -44,6 +115,9 @@ module Tina4
       @verify_ssl = verify_ssl
       @max_retries = [0, max_retries.to_i].max
       @retry_backoff = retry_backoff.to_f
+      @transport = transport
+      @cookies_enabled = cookies ? true : false
+      @cookies = {}
 
       # Bearer wins over basic-auth when both passed
       if bearer_token
@@ -101,19 +175,102 @@ module Tina4
       execute(uri, request)
     end
 
-    def upload(path, file_path, field_name: "file", extra_fields: {}, headers: {})
-      uri = build_uri(path)
-      boundary = "----Tina4Boundary#{SecureRandom.hex(16)}"
+    # POST a multipart/form-data body — a file plus optional text fields.
+    #
+    # BREAKING (3.13.69): reconciled to the canonical cross-framework shape.
+    # `file_path` was a REQUIRED positional; it is now a keyword. Two ways to
+    # supply the file, so a caller never needs a temp file:
+    #
+    #   - file_path: — a file on disk. filename: defaults to its basename.
+    #   - file_bytes: + filename: — an in-memory payload (String bytes).
+    #
+    # field_name: is the form field the file is sent under (default "file").
+    # extra_fields: (Hash) become additional text parts. headers: (Hash) are
+    # extra per-call headers merged onto the request. The part's Content-Type is
+    # guessed from the filename (falling back to application/octet-stream) — this
+    # replaces the old hard-coded application/octet-stream. The client's default
+    # headers (including any Authorization) are sent too, unlike the old upload().
+    #
+    # Returns an APIResponse. A missing file or no source given returns a clean
+    # error response (status 0, error set) — it does NOT raise, and nothing is
+    # sent over the wire.
+    #
+    #   api.upload("/avatars", file_path: "/tmp/me.png")
+    #   api.upload("/avatars", file_bytes: raw, filename: "me.png",
+    #              extra_fields: { "user_id" => "42" })
+    def upload(path, file_path: nil, field_name: "file", extra_fields: {},
+               headers: {}, file_bytes: nil, filename: nil)
+      unless file_bytes.nil?
+        content = file_bytes.is_a?(String) ? file_bytes : file_bytes.to_s
+        upload_name = filename || "upload.bin"
+      end
+
+      if content.nil? && file_path
+        return error_response("file not found: #{file_path}") unless File.file?(file_path)
+
+        begin
+          content = File.binread(file_path)
+        rescue SystemCallError => e
+          return error_response(e.message)
+        end
+        upload_name = filename || File.basename(file_path)
+      end
 
-      body = build_multipart_body(boundary, file_path, field_name, extra_fields)
+      return error_response("upload requires file_path or file_bytes") if content.nil?
 
+      part_content_type = guess_content_type(upload_name)
+      boundary = "----Tina4Boundary#{SecureRandom.hex(16)}"
+      body = build_multipart_body(boundary, field_name, upload_name, content,
+                                  part_content_type, extra_fields)
+
+      uri = build_uri(path)
       request = Net::HTTP::Post.new(uri)
       request.body = body
+      # Apply the client default headers (auth, etc.) FIRST, then force the
+      # multipart Content-Type so it wins over the default application/json,
+      # then any per-call headers last (parity with the Python master's order).
+      apply_headers(request, {})
       request["Content-Type"] = "multipart/form-data; boundary=#{boundary}"
-      headers.each { |k, v| request[k] = v }
+      headers.each { |key, value| request[key] = value }
       execute(uri, request)
     end
 
+    # Stream a GET response body to dest_path in chunks.
+    #
+    # The body is written to disk API_DOWNLOAD_CHUNK_SIZE bytes at a time instead
+    # of being buffered whole in memory — safe for large payloads. Follows
+    # redirects (with the same cross-origin auth/cookie strip as every verb) and
+    # honours verify_ssl.
+    #
+    # Returns an APIResponse carrying `path` (and no body — it went to disk).
+    # `path` is dest_path on success and nil on any error (missing dest, HTTP
+    # error status, or a transport failure); the destination file is not written
+    # on a pre-flight or HTTP-status error. status is 0 on a transport failure.
+    def download(path, dest_path: nil, params: {})
+      return error_response("download requires dest_path", path: nil) unless dest_path
+
+      uri = build_uri(path, params)
+      headers = @headers.dup
+      cookie = cookie_header
+      headers["Cookie"] = cookie if @cookies_enabled && cookie
+
+      return download_via_transport(uri, headers, dest_path) if @transport
+
+      begin
+        result = network_call("GET", uri, headers, nil, stream_to: dest_path)
+        code = result[:status]
+        if result[:path]
+          APIResponse.new(status: code, body: nil, headers: result[:headers],
+                          error: nil, path: result[:path])
+        else
+          APIResponse.new(status: code, body: nil, headers: result[:headers],
+                          error: "download failed (HTTP #{code})", path: nil)
+        end
+      rescue StandardError => e
+        APIResponse.new(status: 0, body: nil, headers: {}, error: e.message, path: nil)
+      end
+    end
+
     def set_basic_auth(username, password)
       @headers["Authorization"] = "Basic #{Base64.strict_encode64("#{username}:#{password}")}"
       self
@@ -179,59 +336,290 @@ module Tina4
       response
     end
 
-    # A single HTTP attempt. Returns the standardized APIResponse.
+    # A single HTTP attempt. Returns the standardized APIResponse. Dispatches to
+    # the injected transport seam when one is set, else the real network path.
     def attempt_request(uri, request)
-      http = Net::HTTP.new(uri.host, uri.port)
-      http.use_ssl = uri.scheme == "https"
-      # 3.13.39: honour verify_ssl: false (the dead-since-3.13.1 kwarg). Only
-      # disable verification when EXPLICITLY false — nil/true keep the secure
-      # default (OpenSSL::SSL::VERIFY_PEER).
-      http.verify_mode = OpenSSL::SSL::VERIFY_NONE if @verify_ssl == false
-      http.open_timeout = @timeout
-      http.read_timeout = @timeout
-
-      response = http.request(request)
+      method = request.method
+      headers = {}
+      request.each_header { |key, value| headers[key] = value }
+      cookie = cookie_header
+      headers["cookie"] = cookie if @cookies_enabled && cookie
+      body = request.body
 
-      APIResponse.new(
-        status: response.code.to_i,
-        body: response.body,
-        headers: response.to_hash
-      )
+      if @transport
+        transport_response(method, uri.to_s, headers, body)
+      else
+        result = network_call(method, uri, headers, body)
+        APIResponse.new(status: result[:status], body: result[:body] || "",
+                        headers: result[:headers], error: nil)
+      end
     rescue StandardError => e
+      APIResponse.new(status: 0, body: "", headers: {}, error: e.message)
+    end
+
+    # Perform a real HTTP round-trip via Net::HTTP, following redirects in a
+    # bounded loop and stripping Authorization/Cookie on a cross-origin hop.
+    # When stream_to is given, a 2xx body is streamed to that path in chunks
+    # (never buffered whole) and no file is written on a non-2xx status.
+    #
+    # Returns { status:, headers:, body:, path: } (body nil when streamed; path
+    # set only when a file was actually written). Raises on a transport failure
+    # (caller turns that into a status-0 error response).
+    def network_call(method, uri, headers, body, stream_to: nil)
+      remaining = API_MAX_REDIRECTS
+      current_method = method.to_s.upcase
+      current_uri = uri.is_a?(URI) ? uri : URI.parse(uri.to_s)
+      current_headers = headers.dup
+      current_body = body
+
+      loop do
+        http = Net::HTTP.new(current_uri.host, current_uri.port)
+        http.use_ssl = current_uri.scheme == "https"
+        # Only disable verification when EXPLICITLY false — nil/true keep the
+        # secure default (OpenSSL::SSL::VERIFY_PEER).
+        http.verify_mode = OpenSSL::SSL::VERIFY_NONE if @verify_ssl == false
+        http.open_timeout = @timeout
+        http.read_timeout = @timeout
+
+        request = build_net_request(current_method, current_uri, current_headers, current_body)
+
+        status = nil
+        resp_headers = {}
+        body_string = nil
+        wrote_file = false
+        location = nil
+        redirect_code = nil
+
+        http.start do |conn|
+          conn.request(request) do |response|
+            status = response.code.to_i
+            resp_headers = response.to_hash
+            if API_REDIRECT_STATUSES.include?(status) && remaining.positive? && response["location"]
+              response.read_body { |_chunk| } # drain (and discard) the redirect body
+              location = response["location"]
+              redirect_code = status
+            else
+              store_cookies(response.get_fields("Set-Cookie"))
+              if stream_to && (200..299).cover?(status)
+                # Stream to disk in API_DOWNLOAD_CHUNK_SIZE blocks. Net::HTTP's
+                # read_body block yields socket-buffer-sized chunks; we coalesce
+                # them and flush at the 64 KB threshold so the whole body never
+                # lands in memory at once (bounded to ~one chunk + 64 KB).
+                File.open(stream_to, "wb") do |file|
+                  buffer = String.new(encoding: Encoding::BINARY)
+                  response.read_body do |chunk|
+                    buffer << chunk
+                    if buffer.bytesize >= API_DOWNLOAD_CHUNK_SIZE
+                      file.write(buffer)
+                      buffer.clear
+                    end
+                  end
+                  file.write(buffer) unless buffer.empty?
+                end
+                wrote_file = true
+              elsif stream_to
+                response.read_body { |_chunk| } # error status on a download: drain, write nothing
+              else
+                body_string = String.new(encoding: Encoding::BINARY)
+                response.read_body { |chunk| body_string << chunk }
+              end
+            end
+          end
+        end
+
+        if location
+          new_uri = URI.join(current_uri.to_s, location)
+          current_headers = strip_cross_origin(current_headers) unless same_origin?(current_uri, new_uri)
+          # 301/302/303 downgrade a non-GET/HEAD to GET and drop the body
+          # (matches urllib); 307/308 preserve method + body.
+          if [301, 302, 303].include?(redirect_code) && !%w[GET HEAD].include?(current_method)
+            current_method = "GET"
+            current_body = nil
+          end
+          current_uri = new_uri
+          remaining -= 1
+          next
+        end
+
+        return { status: status, headers: resp_headers, body: body_string,
+                 path: (wrote_file ? stream_to : nil) }
+      end
+    end
+
+    # Build a Net::HTTP request object for one hop from a method/uri/headers/body.
+    def build_net_request(method, uri, headers, body)
+      klass = case method
+              when "GET"    then Net::HTTP::Get
+              when "POST"   then Net::HTTP::Post
+              when "PUT"    then Net::HTTP::Put
+              when "PATCH"  then Net::HTTP::Patch
+              when "DELETE" then Net::HTTP::Delete
+              when "HEAD"   then Net::HTTP::Head
+              else Net::HTTP::Get
+              end
+      request = klass.new(uri)
+      headers.each do |key, value|
+        request[key] = value.is_a?(Array) ? value.first : value
+      end
+      request.body = body if body && !%w[GET HEAD].include?(method)
+      request
+    end
+
+    # Invoke a user-injected transport and normalize its result into an
+    # APIResponse. The transport fully replaces the network call.
+    def transport_response(method, url, headers, body)
+      result = @transport.call(method, url, headers, body, @timeout)
+      result = {} unless result.is_a?(Hash)
+      store_cookies(set_cookie_values(result_value(result, :headers)))
       APIResponse.new(
-        status: 0,
-        body: "",
-        headers: {},
-        error: e.message
+        status: (result_value(result, :http_code, :status) || 0).to_i,
+        body: result_value(result, :body) || "",
+        headers: result_value(result, :headers) || {},
+        error: result_value(result, :error)
       )
     end
 
-    def build_multipart_body(boundary, file_path, field_name, extra_fields)
-      body = ""
-      extra_fields.each do |key, value|
-        body += "--#{boundary}\r\n"
-        body += "Content-Disposition: form-data; name=\"#{key}\"\r\n\r\n"
-        body += "#{value}\r\n"
+    # download() over the transport seam: the transport returns a buffered body,
+    # so write it out (only on a 2xx) instead of streaming. Mirrors the Python
+    # master's transport branch of download().
+    def download_via_transport(uri, headers, dest_path)
+      result = @transport.call("GET", uri.to_s, headers, nil, @timeout)
+      result = {} unless result.is_a?(Hash)
+      store_cookies(set_cookie_values(result_value(result, :headers)))
+      code = (result_value(result, :http_code, :status) || 0).to_i
+      error = result_value(result, :error)
+      resp_headers = result_value(result, :headers) || {}
+
+      if error.nil? && (200..299).cover?(code)
+        data = result_value(result, :body).to_s
+        begin
+          File.binwrite(dest_path, data)
+        rescue SystemCallError => e
+          return APIResponse.new(status: code, body: nil, headers: resp_headers, error: e.message, path: nil)
+        end
+        APIResponse.new(status: code, body: nil, headers: resp_headers, error: nil, path: dest_path)
+      else
+        APIResponse.new(status: code, body: nil, headers: resp_headers,
+                        error: error || "download failed (HTTP #{code})", path: nil)
       end
+    rescue StandardError => e
+      APIResponse.new(status: 0, body: nil, headers: {}, error: e.message, path: nil)
+    end
 
-      filename = File.basename(file_path)
-      body += "--#{boundary}\r\n"
-      body += "Content-Disposition: form-data; name=\"#{field_name}\"; filename=\"#{filename}\"\r\n"
-      body += "Content-Type: application/octet-stream\r\n\r\n"
-      body += File.binread(file_path)
-      body += "\r\n--#{boundary}--\r\n"
+    # Assemble a multipart/form-data body as raw bytes. Text fields come first,
+    # then the file part, then the closing delimiter — byte-identical to the
+    # Python master's _build_multipart_body so every framework produces the same
+    # layout. Built as a BINARY string so raw file bytes concatenate cleanly.
+    def build_multipart_body(boundary, field_name, filename, content, content_type, extra_fields)
+      crlf = "\r\n"
+      body = String.new(encoding: Encoding::BINARY)
+      (extra_fields || {}).each do |key, value|
+        body << "--#{boundary}#{crlf}".b
+        body << %(Content-Disposition: form-data; name="#{key}"#{crlf}#{crlf}).b
+        body << "#{value}#{crlf}".b
+      end
+      body << "--#{boundary}#{crlf}".b
+      body << %(Content-Disposition: form-data; name="#{field_name}"; filename="#{filename}"#{crlf}).b
+      body << "Content-Type: #{content_type}#{crlf}#{crlf}".b
+      body << content.b
+      body << crlf.b
+      body << "--#{boundary}--#{crlf}".b
       body
     end
+
+    # Guess a multipart part's Content-Type from a filename extension, falling
+    # back to application/octet-stream (parity with the Python master).
+    def guess_content_type(filename)
+      ext = File.extname(filename.to_s).delete_prefix(".").downcase
+      API_MIME_BY_EXTENSION[ext] || "application/octet-stream"
+    end
+
+    # True when two URLs share scheme + host + (effective) port.
+    def same_origin?(uri_a, uri_b)
+      a = uri_a.is_a?(URI) ? uri_a : URI.parse(uri_a.to_s)
+      b = uri_b.is_a?(URI) ? uri_b : URI.parse(uri_b.to_s)
+      defaults = { "http" => 80, "https" => 443 }
+      port_a = a.port || defaults[a.scheme]
+      port_b = b.port || defaults[b.scheme]
+      a.scheme == b.scheme && a.host == b.host && port_a == port_b
+    end
+
+    def strip_cross_origin(headers)
+      headers.reject { |key, _| API_STRIP_ON_CROSS_ORIGIN.include?(key.to_s.downcase) }
+    end
+
+    # Fetch a value from a Hash trying each key as both a symbol and a string.
+    def result_value(result, *keys)
+      keys.each do |key|
+        return result[key] if result.key?(key)
+
+        string_key = key.to_s
+        return result[string_key] if result.key?(string_key)
+      end
+      nil
+    end
+
+    # ── cookie jar (opt-in, in-memory, per-client) ─────────────────────────
+    # The accumulated Cookie request header, or nil when the jar is empty.
+    def cookie_header
+      return nil if @cookies.empty?
+
+      @cookies.map { |name, value| "#{name}=#{value}" }.join("; ")
+    end
+
+    # Parse Set-Cookie response header values into the jar (when enabled). Only
+    # the leading name=value pair of each Set-Cookie is kept (attributes like
+    # Path/HttpOnly/Expires are ignored); a later value for the same name
+    # overwrites an earlier one. Parity with the Python master's _store_cookies.
+    def store_cookies(values)
+      return unless @cookies_enabled
+
+      Array(values).each do |raw|
+        next if raw.nil? || raw.empty?
+
+        first_pair = raw.split(";", 2).first.to_s.strip
+        name, separator, value = first_pair.partition("=")
+        next if separator.empty?
+
+        name = name.strip
+        @cookies[name] = value.strip unless name.empty?
+      end
+    end
+
+    # Extract Set-Cookie values from a plain headers Hash (the transport seam
+    # returns a Hash, not a Net::HTTPResponse). Values may be a String or Array.
+    def set_cookie_values(headers)
+      return [] unless headers.is_a?(Hash)
+
+      values = []
+      headers.each do |key, value|
+        next unless key.to_s.downcase == "set-cookie"
+
+        Array(value).each { |item| values << item }
+      end
+      values
+    end
+
+    def error_response(message, path: :__none__)
+      if path == :__none__
+        APIResponse.new(status: 0, body: "", headers: {}, error: message)
+      else
+        APIResponse.new(status: 0, body: nil, headers: {}, error: message, path: path)
+      end
+    end
   end
 
   class APIResponse
-    attr_reader :status, :body, :headers, :error
+    attr_reader :status, :body, :headers, :error, :path
 
-    def initialize(status:, body:, headers:, error: nil)
+    # `path` (default nil) is populated by API#download — the on-disk path the
+    # streamed body was written to (nil on error). It is nil for every other verb.
+    def initialize(status:, body:, headers:, error: nil, path: nil)
       @status = status
       @body = body
       @headers = headers
       @error = error
+      @path = path
     end
 
     def success?
@@ -240,7 +628,7 @@ module Tina4
 
     def json
       @json ||= JSON.parse(@body)
-    rescue JSON::ParserError
+    rescue JSON::ParserError, TypeError
       {}
     end
 

data/lib/tina4/dev_admin.rb

@@ -969,6 +969,11 @@ module Tina4
         return { error: "No database configured" } unless db
 
         begin
+          # Force-load the seeder: Tina4.seed_table is defined in
+          # lib/tina4/seeder.rb, reachable only via the Tina4::FakeData autoload,
+          # which a bare Tina4.seed_table call never trips (mirrors Python's
+          # explicit `from tina4_python.seeder import seed_table`).
+          require_relative "seeder"
           # Delegate to the shared resilient seed_table helper so the endpoint
           # gets the exact same per-row wrap (P1) — no unhandled row failure can
           # crash the endpoint — plus clear/seed/strict (P2/P3). _normalize_columns

data/lib/tina4/drivers/firebird_driver.rb

@@ -76,7 +76,42 @@ module Tina4
         decoded.start_with?("/") ? decoded : "/#{decoded}"
       end
 
-      def connect(connection_string, username: nil, password: nil)
+      # Resolve the Firebird connection charset (#160, mirrors php #160 /
+      # the Python master's _resolve_firebird_charset).
+      #
+      # The driver used to pass NO charset to the `fb` gem, leaving it to the
+      # gem's own (non-UTF8) default — which double-encodes UTF-8 bytes stored
+      # under a legacy NONE database and diverges from the other frameworks.
+      # The charset is now resolved from, in precedence order:
+      #
+      #   1. the connection URL query — firebird://host:port/path?charset=NONE
+      #   2. an explicit charset: kwarg passed to #connect
+      #   3. the TINA4_DATABASE_CHARSET environment variable
+      #   4. the UTF8 default (canonical across all four frameworks)
+      #
+      # Pure config resolution over its inputs (URL string, kwarg, env) — it
+      # opens NO connection, so it is unit-testable without a live server. A
+      # blank value at any level is treated as absent (matching the Python
+      # master's falsy-string semantics) so `?charset=` / an empty env var falls
+      # through rather than connecting with an empty charset.
+      def self.resolve_charset(connection_string, kwarg_charset = nil)
+        require "uri"
+        url_charset = nil
+        query = begin
+          URI.parse(connection_string.to_s).query
+        rescue URI::InvalidURIError
+          nil
+        end
+        if query && !query.empty?
+          pair = URI.decode_www_form(query).find { |k, _| k == "charset" }
+          url_charset = pair[1] if pair && !pair[1].to_s.empty?
+        end
+        kwarg = kwarg_charset.to_s.empty? ? nil : kwarg_charset
+        env = ENV["TINA4_DATABASE_CHARSET"].to_s.empty? ? nil : ENV["TINA4_DATABASE_CHARSET"]
+        url_charset || kwarg || env || "UTF8"
+      end
+
+      def connect(connection_string, username: nil, password: nil, charset: nil)
         require "fb"
         require "uri"
         uri = URI.parse(connection_string)
@@ -115,6 +150,10 @@ module Tina4
         @connect_opts = { database: database }
         @connect_opts[:username] = db_user if db_user
         @connect_opts[:password] = db_pass if db_pass
+        # #160: honour ?charset= in the URL, an explicit charset: kwarg, and
+        # TINA4_DATABASE_CHARSET so a legacy NONE database isn't force-connected
+        # with the gem's default charset (double-encoding). Defaults to UTF8.
+        @connect_opts[:charset] = self.class.resolve_charset(connection_string, charset)
 
         open_connection
       rescue LoadError

data/lib/tina4/field_types.rb

@@ -187,8 +187,24 @@ module Tina4
         field_definitions[name] = { type: type }.merge(options)
         @primary_key_field = name if options[:primary_key]
 
-        # Define getter/setter
-        attr_accessor name
+        # Getter (plain reader) + an assignment-tracking setter.
+        #
+        # #165: save() must tell a column the caller EXPLICITLY set to nil
+        # (write it — an explicit nil becomes SQL NULL) from one left UNSET
+        # (omit it from the INSERT so a NOT NULL DEFAULT column gets its DB
+        # default instead of an explicit NULL). The setter records the field
+        # name in @assigned_fields on every caller assignment — via the
+        # constructor's attribute application, a from_hash/load populate, or a
+        # direct `model.field = x`. Field DEFAULTS are seeded in #initialize
+        # with instance_variable_set (bypassing this setter), so a default is
+        # never counted as a caller assignment. Mirrors the Python master's
+        # __setattr__ + object.__setattr__ default-seeding.
+        attr_reader name
+        define_method("#{name}=") do |value|
+          fields = (@assigned_fields ||= [])
+          fields << name unless fields.include?(name)
+          instance_variable_set("@#{name}", value)
+        end
       end
     end
   end

data/lib/tina4/mcp.rb

@@ -906,7 +906,9 @@ module Tina4
       # ── Template Tools ────────────────────────────────
       server.register_tool("template_render", lambda { |template:, data: "{}"|
         ctx = data.is_a?(String) ? JSON.parse(data) : data
-        Tina4::Template.render_string(template, ctx)
+        # render_string is an INSTANCE method of Frond (Tina4::Template has none).
+        # Mirrors Python tools.py: Frond("src/templates").render_string(...).
+        Tina4::Frond.new(template_dir: "src/templates").render_string(template, ctx)
       }, "Render a template string with data")
 
       # ── File Tools ────────────────────────────────────
@@ -1023,9 +1025,9 @@ module Tina4
           q = Tina4::Queue.new(topic: topic)
           {
             "topic"     => topic,
-            "pending"   => q.size("pending"),
-            "completed" => q.size("completed"),
-            "failed"    => q.size("failed")
+            "pending"   => q.size(status: "pending"),
+            "completed" => q.size(status: "completed"),
+            "failed"    => q.size(status: "failed")
           }
         rescue => e
           { "error" => e.message }
@@ -1107,10 +1109,15 @@ module Tina4
       # ── Data Tools ────────────────────────────────────
       server.register_tool("seed_table", lambda { |table:, count: 10|
         begin
+          # Tina4.seed_table lives in lib/tina4/seeder.rb, reachable only via the
+          # autoload of Tina4::FakeData — a bare Tina4.seed_table call never trips
+          # it. Force-load the seeder first (mirrors Python's explicit
+          # `from tina4_python.seeder import seed_table`).
+          require_relative "seeder"
           db = Tina4.database
           return { "error" => "No database connection" } if db.nil?
           inserted = Tina4.seed_table(table, db.columns(table), count: count.to_i)
-          { "table" => table, "inserted" => inserted }
+          { "table" => table, "inserted" => inserted.seeded, "failed" => inserted.failed }
         rescue => e
           { "error" => e.message }
         end

data/lib/tina4/orm.rb

@@ -625,6 +625,13 @@ module Tina4
       # cause via #get_error / #last_error — the failure never vanishes silently.
       @last_error = nil
       @relationship_cache = {}
+      # #165: field names the caller EXPLICITLY assigned (via the attribute loop
+      # below, a from_hash/load populate, or a later `model.field = x`). save()
+      # reads this to OMIT an unset column from an INSERT (so a NOT NULL DEFAULT
+      # column gets its DB default) while still writing NULL for a field the
+      # caller set to nil. The defaults seeded below use instance_variable_set,
+      # bypassing the tracking setter so they are NOT counted as assignments.
+      @assigned_fields = []
       # Accept a JSON object string (parity with Python/PHP/Node):
       #   Widget.new('{"id":1,"name":"alpha"}')
       attributes = JSON.parse(attributes) if attributes.is_a?(String)
@@ -654,7 +661,10 @@ module Tina4
           # a.meta must not leak into b.meta). Parity with the Python master,
           # which deepcopies a JSONField's dict/list default per instance.
           d = Marshal.load(Marshal.dump(d)) if d.is_a?(Hash) || d.is_a?(Array)
-          __send__("#{name}=", d)
+          # #165: seed the default straight into the ivar, BYPASSING the
+          # tracking setter, so a default is not recorded as a caller
+          # assignment (mirrors the Python master's object.__setattr__).
+          instance_variable_set("@#{name}", d)
         end
       end
     end
@@ -737,12 +747,15 @@ module Tina4
         end
 
       begin
-        # Built here (inside the rescue's reach) so a JSON column that can't be
-        # serialised (to_db_hash raises JSON::GeneratorError) fails loud through
-        # the same path as a driver error — rolled back, false, cause recorded.
-        data = to_db_hash(exclude_nil: true)
+        # The column hashes are built INSIDE this begin (via the transaction
+        # block below) so a JSON column that can't be serialised (to_db_hash /
+        # insert_db_hash raises JSON::GeneratorError) fails loud through the
+        # same path as a driver error — rolled back, false, cause recorded.
         self.class.db.transaction do |db|
           if is_update
+            # UPDATE is unchanged (#165 targets INSERT only): keep excluding nil
+            # so a save never nulls a column the caller didn't touch.
+            data = to_db_hash(exclude_nil: true)
             filter = { pk => pk_value }
             data.delete(pk)
             # Remove mapped primary key too
@@ -750,13 +763,32 @@ module Tina4
             data.delete(mapped_pk.to_sym) if mapped_pk
             db.update(self.class.table_name, data, filter)
           else
-            result = db.insert(self.class.table_name, data)
-            # Only adopt the engine-assigned id for an auto-increment PK. A
-            # natural-key PK was set by the caller; don't overwrite it with the
-            # driver's last_insert_id (which may be a sequence value that
-            # doesn't apply here).
-            if auto_increment && result[:last_id] && respond_to?("#{pk}=")
-              __send__("#{pk}=", result[:last_id])
+            # #165: OMIT a column the caller left unset (value nil, never
+            # assigned) so a NOT NULL DEFAULT column gets its DB default rather
+            # than an explicit NULL; a column the caller set to nil is KEPT and
+            # written as NULL (see #insert_db_hash).
+            insert_data = insert_db_hash
+            if insert_data.empty?
+              # Every insertable column is unset — let the engine apply ALL its
+              # column defaults instead of emitting explicit NULLs. DEFAULT
+              # VALUES is valid on SQLite / PostgreSQL / MSSQL / Firebird; MySQL
+              # spells the all-defaults insert () VALUES ().
+              table = self.class.table_name
+              engine = (self.class.db.respond_to?(:get_database_type) ? self.class.db.get_database_type : "").to_s.downcase
+              db.execute(engine == "mysql" ? "INSERT INTO #{table} () VALUES ()" : "INSERT INTO #{table} DEFAULT VALUES")
+              if auto_increment && respond_to?("#{pk}=")
+                last = db.get_last_id
+                __send__("#{pk}=", last) if last
+              end
+            else
+              result = db.insert(self.class.table_name, insert_data)
+              # Only adopt the engine-assigned id for an auto-increment PK. A
+              # natural-key PK was set by the caller; don't overwrite it with the
+              # driver's last_insert_id (which may be a sequence value that
+              # doesn't apply here).
+              if auto_increment && result[:last_id] && respond_to?("#{pk}=")
+                __send__("#{pk}=", result[:last_id])
+              end
             end
           end
         end
@@ -1007,6 +1039,41 @@ module Tina4
 
     private
 
+    # Build the column=>value hash for an INSERT (#165).
+    #
+    # Distinguishes a column the caller left UNSET from one the caller
+    # explicitly set to nil (tracked in @assigned_fields, populated by the field
+    # setters):
+    #
+    #   * value nil AND field NOT assigned  -> OMITTED (a DB DEFAULT applies, so
+    #       a NOT NULL DEFAULT column succeeds instead of taking an explicit NULL)
+    #   * value nil AND field assigned       -> KEPT as nil (written as SQL NULL;
+    #       a NOT NULL column rightly rejects it, so an explicit nil fails loud)
+    #   * any non-nil value (incl. a resolved ORM default) -> KEPT
+    #
+    # An unset auto-increment PK is skipped so the engine assigns the id. JSON
+    # columns serialise their Hash/Array exactly as #to_db_hash does. An empty
+    # result signals save() to emit the engine's all-defaults INSERT. Mirrors
+    # the Python master's INSERT omission (tina4_python.orm.model.save).
+    def insert_db_hash
+      hash = {}
+      mapping = self.class.field_mapping
+      assigned = @assigned_fields || []
+      self.class.field_definitions.each do |name, opts|
+        value = __send__(name)
+        # Skip an unset auto-increment PK — let the engine assign it.
+        next if opts[:auto_increment] && value.nil?
+        # Omit an unset-nil column so the DB DEFAULT applies.
+        next if value.nil? && !assigned.include?(name)
+        if opts[:type] == :json && !value.nil? && !value.is_a?(String)
+          value = JSON.generate(value)
+        end
+        db_col = mapping[name.to_s] || name
+        hash[db_col.to_sym] = value
+      end
+      hash
+    end
+
     # Convert to hash using DB column names (with field_mapping applied)
     def to_db_hash(exclude_nil: false)
       hash = {}

data/lib/tina4/test_client.rb

@@ -13,6 +13,8 @@
 #
 #   response = client.get("/api/users/1", headers: { "Authorization" => "Bearer token123" })
 #
+require "stringio" # rack.input is a StringIO; require it here so a clean `require "tina4"` boot never NameErrors
+
 module Tina4
   class TestResponse
     attr_reader :status, :body, :headers, :content_type

data/lib/tina4/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tina4ruby
 version: !ruby/object:Gem::Version
-  version: 3.13.68
+  version: 3.13.70
 platform: ruby
 authors:
 - Tina4 Team
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-10 00:00:00.000000000 Z
+date: 2026-07-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack