api2convert 10.2.1 → 10.3.0

data/lib/api2convert/resource/stats.rb

@@ -4,7 +4,8 @@ module Api2Convert
   module Resource
     # API usage statistics. The response shape is free-form (returned as-is).
     #
-    # +filter+ is either an API key to scope to, or `"all"`.
+    # +filter+ is "single" (only the calling API key) or "all" (every key on the account, the default).
+    # The request is scoped by the X-Api2convert-Api-Key header, so never pass a key as +filter+.
     class Stats
       def initialize(transport)
         @transport = transport

data/lib/api2convert/result.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "tempfile"
 
 module Api2Convert
   module Result
@@ -24,11 +25,11 @@ module Api2Convert
       end
 
       # Stream the file to disk. +path_or_dir+ is a file path, or a directory (the
-      # API filename is used). The body is streamed straight to the file
-      # chunk-by-chunk (never buffered whole in memory), so an arbitrarily large
-      # output cannot exhaust memory. A mid-stream failure removes the partial file
-      # so a truncated download never masquerades as a complete result. Returns the
-      # path written to.
+      # API filename is used). The body is streamed chunk-by-chunk to a sibling temp
+      # file (never buffered whole in memory), then atomically renamed over the
+      # target only after a clean write+close — so an arbitrarily large output cannot
+      # exhaust memory and a mid-stream failure never truncates the target nor
+      # destroys a pre-existing complete file at that path. Returns the path written.
       def save(path_or_dir, download_password = nil)
         target = resolve_target(path_or_dir.to_s)
         parent = File.dirname(target)
@@ -48,7 +49,7 @@ module Api2Convert
       def contents(download_password = nil)
         password = resolve_password(download_password)
         # A passwordless download follows storage redirects; a password-protected
-        # one must not (the X-Oc-Download-Password header could leak on a redirect).
+        # one must not (the X-Api2convert-Download-Password header could leak on a redirect).
         @transport.download(@output.uri, headers(password), follow_redirects: password.nil?)
       end
 
@@ -65,30 +66,60 @@ module Api2Convert
       private
 
       def stream_to_file(target, password)
-        success = false
+        parent = File.dirname(target)
+        parent = "." if parent.empty?
+        # Stream to a sibling temp file and rename over the target only after a clean
+        # write+close. This never truncates the target up front and never destroys a
+        # pre-existing complete file on a mid-stream failure — a download either fully
+        # replaces the target or leaves it untouched.
+        temp = create_temp(parent, target)
+
+        committed = false
         begin
-          File.open(target, "wb") do |file|
-            @transport.download(
-              @output.uri, headers(password), follow_redirects: password.nil?, sink: file
-            )
-            success = true
-          end
-        rescue SystemCallError
-          raise Api2Convert::Error, "Could not open file for writing: #{target}"
+          @transport.download(
+            @output.uri, headers(password), follow_redirects: password.nil?, sink: temp
+          )
+          # Flush + close BEFORE the rename so a truncated-on-close write can never be
+          # committed as a complete file, and a close/flush fault surfaces here rather
+          # than being swallowed on the success path.
+          temp.close
+          File.rename(temp.path, target)
+          committed = true
+        rescue SystemCallError => e
+          # A network read failure mid-stream is already a (non-retryable) NetworkError
+          # raised by the sender, which is NOT a SystemCallError and so passes straight
+          # through; reaching this rescue means a write / flush / rename fault — a
+          # genuine filesystem error.
+          raise Api2Convert::Error, "Could not write file: #{target}: #{e.message}"
         ensure
-          # Any failure (open error, network break, a refused-redirect NetworkError,
-          # a mid-stream break) leaves a partial or empty file — remove it so a
-          # truncated download can never masquerade as a complete result.
-          FileUtils.rm_f(target) unless success
+          # On any failure (network break, refused-redirect NetworkError, write/close/
+          # rename fault) only the temp file is removed; the target is never touched
+          # unless the rename already committed a complete download.
+          unless committed
+            begin
+              temp.close unless temp.closed?
+            rescue SystemCallError
+              nil
+            end
+            FileUtils.rm_f(temp.path)
+          end
         end
       end
 
+      def create_temp(parent, target)
+        temp = Tempfile.create([".a2c-download-", ".part"], parent)
+        temp.binmode
+        temp
+      rescue SystemCallError
+        raise Api2Convert::Error, "Could not open file for writing: #{target}"
+      end
+
       def resolve_password(download_password)
         download_password.nil? ? @download_password : download_password
       end
 
       def headers(password)
-        password.nil? ? {} : { "X-Oc-Download-Password" => password }
+        password.nil? ? {} : { "X-Api2convert-Download-Password" => password }
       end
 
       def resolve_target(path_or_dir)

data/lib/api2convert/support/data.rb

@@ -36,10 +36,17 @@ module Api2Convert
         end
         if value.is_a?(String)
           begin
-            return Float(value).to_i
+            parsed = Float(value)
           rescue ArgumentError, TypeError
             return nil
           end
+          # A numeric string that overflows Float to +/-Infinity (e.g. "1e400")
+          # must fall back to nil, not raise: Float::INFINITY.to_i / NAN.to_i throw
+          # FloatDomainError, and this helper must NEVER raise on a hostile payload
+          # (mirrors the Float branch's finite? guard above).
+          return nil unless parsed.finite?
+
+          return parsed.to_i
         end
         nil
       end

data/lib/api2convert/support/redactor.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Api2Convert
+  module Support
+    # Credential redaction for cloud connectors.
+    #
+    # Cloud `credentials` ride in the plaintext request body, so they must never
+    # surface where a value object or an SDK-emitted string could leak them. This
+    # helper centralizes the masks the contract mandates:
+    #
+    # - the **whole `credentials` object** collapses to {MARKER} on every
+    #   object-inspection path (`#inspect` / `#to_s`);
+    # - any `parameters` leaf whose key contains a sensitive token
+    #   ({SENSITIVE_SUBSTRINGS}, case-insensitive substring) collapses to {MARKER};
+    # - the decoded error body is deep-walked ({redact_body}) as belt-and-
+    #   suspenders — the API only ever echoes field *names*, never a credential
+    #   *value*, but a future server/proxy change must not be able to leak one.
+    #
+    # Internal helper, not part of the public API.
+    module Redactor
+      module_function
+
+      # The fixed, fleet-wide redaction marker (D9).
+      MARKER = "[REDACTED]"
+
+      # Case-insensitive substrings that mark a key as carrying a secret. A key
+      # containing any of these has its whole value masked.
+      SENSITIVE_SUBSTRINGS = %w[
+        token password passwd secret key keyfile
+        credential passphrase sas sig signature
+      ].freeze
+
+      # Precompiled union: a key is sensitive iff it *contains* any substring
+      # above. Equivalent to `SENSITIVE_SUBSTRINGS.any? { |s| key.include?(s) }`
+      # but written as a regex so Style/ArrayIntersect can't rewrite the
+      # String#include? substring test into Array#intersect? (which would need an
+      # array argument and change the semantics).
+      SENSITIVE_PATTERN = Regexp.union(SENSITIVE_SUBSTRINGS).freeze
+
+      # Whether a key name marks its value as sensitive (case-insensitive
+      # substring match). Accepts String or Symbol keys.
+      def sensitive_key?(key)
+        SENSITIVE_PATTERN.match?(key.to_s.downcase)
+      end
+
+      # Mask sensitive leaves of a `parameters` map: any key matching
+      # {sensitive_key?} has its value replaced by {MARKER}; nested Hashes are
+      # walked recursively. Non-secret keys (`bucket`, `host`, `file`,
+      # `container`, `projectid`, …) are left untouched.
+      def parameters(params)
+        return params unless params.is_a?(Hash)
+
+        params.each_with_object({}) do |(key, value), out|
+          out[key] =
+            if sensitive_key?(key)
+              MARKER
+            elsif value.is_a?(Hash)
+              parameters(value)
+            else
+              value
+            end
+        end
+      end
+
+      # Deep-walk a decoded error body and mask the value of every sensitive key
+      # (including a flattened/dotted key like
+      # `input.0.credentials.secretaccesskey`) to {MARKER}. Nested Hashes and
+      # Arrays are walked; scalars pass through.
+      def redact_body(body)
+        case body
+        when Hash
+          body.each_with_object({}) do |(key, value), out|
+            out[key] = sensitive_key?(key) ? MARKER : redact_body(value)
+          end
+        when Array
+          body.map { |value| redact_body(value) }
+        else
+          body
+        end
+      end
+    end
+  end
+end

data/lib/api2convert/upload/file_uploader.rb

@@ -10,7 +10,7 @@ module Api2Convert
     # This step is intentionally hand-written — it is NOT described by the OpenAPI
     # spec. It posts a `multipart/form-data` body (field `file`) to
     # `{job.server}/upload-file/{job.id}` and authenticates with the per-job
-    # `X-Oc-Token` header — never the account API key. The body is streamed, so
+    # `X-Api2convert-Token` header — never the account API key. The body is streamed, so
     # large files are not read into memory. Internal.
     class FileUploader
       def initialize(transport)
@@ -39,7 +39,7 @@ module Api2Convert
           @transport.build_request(
             "POST", url,
             headers: {
-              "X-Oc-Token" => token,
+              "X-Api2convert-Token" => token,
               "Content-Type" => "multipart/form-data; boundary=#{boundary}"
             },
             body_stream: body_stream,

data/lib/api2convert/version.rb

@@ -4,5 +4,5 @@ module Api2Convert
   # The SDK version. Kept in lock-step with the sibling SDKs (PHP, Python, Java,
   # Node.js): all official ports implement the same `docs/SDK_CONTRACT.md` and
   # version together.
-  VERSION = "10.2.1"
+  VERSION = "10.3.0"
 end

data/lib/api2convert.rb

@@ -21,10 +21,14 @@ require_relative "api2convert/errors"
 require_relative "api2convert/config"
 require_relative "api2convert/support/data"
 require_relative "api2convert/support/secret"
+require_relative "api2convert/support/redactor"
 require_relative "api2convert/job_status"
 require_relative "api2convert/input_type"
+require_relative "api2convert/cloud_provider"
 
 require_relative "api2convert/model/status"
+require_relative "api2convert/model/output_target"
+require_relative "api2convert/model/cloud_input"
 require_relative "api2convert/model/conversion"
 require_relative "api2convert/model/input_file"
 require_relative "api2convert/model/output_file"