scanii-ruby 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e3c62870b928231999c133d889594f002682b74b34769c5741dbfe9a9c12693
-  data.tar.gz: a1673812fa7c2e46fa12657a3898fb01fdf56399c04146e95dfdf048d12ef185
+  metadata.gz: '0418285adf3f56f3389b379b9eedadd5b281591cd2c7e62ad05092a8e8b22595'
+  data.tar.gz: a61ce21d24bc78f557e09394868fc0c50b9fb2777b8649dce59b017a7d6a427c
 SHA512:
-  metadata.gz: 1afa93f5a49873f5813dbf9701d5886b173a3e3d5dbdda9d214690308eb77d92b8ff96bde66b6fa78b2f455af32d317bf8e1ce1338824fa0a5801f2dbe4786cd
-  data.tar.gz: 6ed39afbb9846cec5916f8a77c8119a717f6e5c6e6da81dd17756a456fa069735063a20762a772090400d09b1e4fd85c883a92176beecf36479fe10d38ae7bd4
+  metadata.gz: 504165ee4f450fa8266675e1eb9d43d54a44e76547a5a8fe870865b4123c1563a4d9bf693df893855ecef9197288beb0e5da3425bf3a4524aa76cc1d02bbec25
+  data.tar.gz: 897b47ed149ea571105dde92462e61d69f43fd496f20a50200dc64d0bce2e2ab7b52ade2837de7d5d6ac5a0f25f5de93f98f0d0ad5781f474b076d8c76c874e0

data/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 All notable changes to `scanii-ruby` are documented here. Versions follow [SemVer](https://semver.org).
 
+## 1.1.0 — Streaming standardization
+
+Adds stream-based `process` and `process_async` methods, aligning scanii-ruby with the
+cross-SDK streaming standard. File content is now truly streamed to the socket via
+`Net::HTTP#body_stream=` rather than buffered into a single String.
+
+### New API
+
+- `Scanii::Client#process(io, filename:, content_type: nil, metadata: nil, callback: nil)` →
+  `Scanii::ProcessingResult` — accepts any IO-like object (anything responding to `read(n)`).
+  Both `File` (opened with `File.open(path, "rb")`) and `StringIO` work.
+- `Scanii::Client#process_file(path, metadata: nil, callback: nil)` →
+  `Scanii::ProcessingResult` — convenience wrapper that opens the file in binary mode and
+  delegates to `process`. This is the replacement for the old `process(path, ...)` form.
+- Same shapes for `process_async` / `process_async_file`.
+
+### Deprecations
+
+- `process(path_string, ...)` — passing a String path to `process` is deprecated; use
+  `process_file(path)` instead. The old form still works and emits a runtime `warn`. Will be
+  removed in a future major version.
+- `process_async(path_string, ...)` — same; use `process_async_file(path)`. Will be removed
+  in a future major version.
+
+### Internals
+
+- `Scanii::Multipart.stream_encode` replaces the old `encode`. Returns a `[ChainedIO,
+  content_type, content_length]` triple. `ChainedIO` reads prologue → caller IO → epilogue
+  without ever buffering the full body.
+
 ## 1.0.1 — Release infrastructure fix
 
 Wires up `bundler/gem_tasks` in the Rakefile so `bundle exec rake release` (invoked by `rubygems/release-gem@v1`) resolves correctly. v1.0.0 was tagged but never published to RubyGems because the release workflow failed at the `rake release` task lookup; v1.0.1 is functionally identical to that tag. No SDK behavior changes.

data/README.md

@@ -30,12 +30,23 @@ Targets Ruby 3.4+. Zero runtime dependencies.
 
 ## Quickstart
 
+Scan a file from disk:
+
 ```ruby
 require "scanii"
 
 client = Scanii::Client.new(key: "your-key", secret: "your-secret")
 
-result = client.process("./file.pdf")
+result = client.process_file("./file.pdf")
+puts "findings: #{result.findings.inspect}"
+```
+
+Scan content already in memory (no temp file needed):
+
+```ruby
+require "stringio"
+
+result = client.process(StringIO.new(bytes), filename: "upload.bin")
 puts "findings: #{result.findings.inspect}"
 ```
 
@@ -45,8 +56,10 @@ puts "findings: #{result.findings.inspect}"
 
 | Method | REST | Returns |
 |---|---|---|
-| `process(file_path, metadata:, callback:)` | `POST /files` | `Scanii::ProcessingResult` |
-| `process_async(file_path, metadata:, callback:)` | `POST /files/async` | `Scanii::PendingResult` |
+| `process(io, filename:, content_type:, metadata:, callback:)` | `POST /files` | `Scanii::ProcessingResult` |
+| `process_file(path, metadata:, callback:)` | `POST /files` | `Scanii::ProcessingResult` |
+| `process_async(io, filename:, content_type:, metadata:, callback:)` | `POST /files/async` | `Scanii::PendingResult` |
+| `process_async_file(path, metadata:, callback:)` | `POST /files/async` | `Scanii::PendingResult` |
 | `fetch(url, metadata:, callback:)` | `POST /files/fetch` | `Scanii::PendingResult` |
 | `retrieve(id)` | `GET /files/{id}` | `Scanii::ProcessingResult` |
 | `ping` | `GET /ping` | `true` |

data/lib/scanii/client.rb

@@ -13,10 +13,13 @@ module Scanii
   #
   # @see https://scanii.github.io/openapi/v22/
   #
-  # @example
+  # @example Scan a file from disk
   #   client = Scanii::Client.new(key: "your-key", secret: "your-secret")
-  #   result = client.process("./file.pdf")
+  #   result = client.process_file("./file.pdf")
   #   puts result.findings  # [] when clean
+  #
+  # @example Scan content already in memory
+  #   result = client.process(StringIO.new(bytes), filename: "upload.bin")
   class Client
     DEFAULT_ENDPOINT = "https://api.scanii.com".freeze
     DEFAULT_TIMEOUT  = 60
@@ -44,34 +47,111 @@ module Scanii
       @user_agent = user_agent && !user_agent.empty? ? "#{user_agent} #{USER_AGENT}" : USER_AGENT
     end
 
-    # Submit a file for synchronous scanning.
+    # Submit an IO-like object for synchronous scanning.
+    #
+    # +io+ is duck-typed: anything responding to +read(n)+ returning a String.
+    # Both +File+ (opened with +File.open(path, "rb")+) and +StringIO+ work.
+    # The body is streamed to the socket; file content is never fully buffered.
+    #
+    # Passing a String path is deprecated — use {#process_file} instead.
+    #
+    # @overload process(io, filename:, content_type: nil, metadata: nil, callback: nil)
+    #   @param io [#read] IO-like object
+    #   @param filename [String] filename sent in the multipart part
+    #   @param content_type [String, nil] content-type of the file part; guessed from filename when nil
+    #   @param metadata [Hash{String=>String}, nil] arbitrary key/value pairs attached to the result
+    #   @param callback [String, nil] URL to POST the result to on completion
     #
     # @see https://scanii.github.io/openapi/v22/  POST /files
     # @return [Scanii::ProcessingResult]
-    def process(file_path, metadata: nil, callback: nil)
-      assert_readable(file_path)
+    def process(first_arg, filename: nil, content_type: nil, metadata: nil, callback: nil)
+      if first_arg.is_a?(String)
+        # @deprecated Use {#process_file} instead. Will be removed in a future major version.
+        warn "[DEPRECATION] `Scanii::Client#process(path)` is deprecated; " \
+             "use `process_file(path)` instead. Will be removed in a future major version."
+        return process_file(first_arg, metadata: metadata, callback: callback)
+      end
+
+      raise ArgumentError, "io must respond to read" unless first_arg.respond_to?(:read)
+      raise ArgumentError, "filename: is required" if filename.nil? || filename.to_s.empty?
+
       fields = build_text_fields(metadata, callback)
-      body, content_type = Multipart.encode(fields, file_path)
-      status, resp_body, headers = post("/files", body: body, content_type: content_type)
+      stream, ct, length = Multipart.stream_encode(fields, first_arg, filename.to_s, content_type)
+      status, resp_body, headers = post("/files", body_stream: stream, content_type: ct,
+                                                  content_length: length)
       raise_for_status(status, resp_body, headers) unless status == 201
       ProcessingResult.from_response(resp_body, headers)
     end
 
-    # Submit a file for server-side asynchronous scanning. Returns a pending
-    # id; the final result is delivered to +callback+ (when supplied) or
-    # fetched via #retrieve.
+    # Submit a file path for synchronous scanning.
+    #
+    # Opens the file in binary mode, streams it to Scanii, and closes it.
+    # Delegates to {#process} with +filename+ set to the basename.
+    #
+    # @param file_path [String] path to the file to upload
+    # @param metadata [Hash{String=>String}, nil]
+    # @param callback [String, nil]
+    # @see https://scanii.github.io/openapi/v22/  POST /files
+    # @return [Scanii::ProcessingResult]
+    def process_file(file_path, metadata: nil, callback: nil)
+      assert_readable(file_path)
+      File.open(file_path.to_s, "rb") do |f|
+        process(f, filename: File.basename(file_path.to_s), metadata: metadata, callback: callback)
+      end
+    end
+
+    # Submit an IO-like object for server-side asynchronous scanning.
+    #
+    # Returns a pending id; the final result is delivered to +callback+ (when
+    # supplied) or fetched via {#retrieve}.
+    #
+    # Passing a String path is deprecated — use {#process_async_file} instead.
+    #
+    # @overload process_async(io, filename:, content_type: nil, metadata: nil, callback: nil)
+    #   @param io [#read] IO-like object
+    #   @param filename [String] filename sent in the multipart part
+    #   @param content_type [String, nil]
+    #   @param metadata [Hash{String=>String}, nil]
+    #   @param callback [String, nil]
     #
     # @see https://scanii.github.io/openapi/v22/  POST /files/async
     # @return [Scanii::PendingResult]
-    def process_async(file_path, metadata: nil, callback: nil)
-      assert_readable(file_path)
+    def process_async(first_arg, filename: nil, content_type: nil, metadata: nil, callback: nil)
+      if first_arg.is_a?(String)
+        # @deprecated Use {#process_async_file} instead. Will be removed in a future major version.
+        warn "[DEPRECATION] `Scanii::Client#process_async(path)` is deprecated; " \
+             "use `process_async_file(path)` instead. Will be removed in a future major version."
+        return process_async_file(first_arg, metadata: metadata, callback: callback)
+      end
+
+      raise ArgumentError, "io must respond to read" unless first_arg.respond_to?(:read)
+      raise ArgumentError, "filename: is required" if filename.nil? || filename.to_s.empty?
+
       fields = build_text_fields(metadata, callback)
-      body, content_type = Multipart.encode(fields, file_path)
-      status, resp_body, headers = post("/files/async", body: body, content_type: content_type)
+      stream, ct, length = Multipart.stream_encode(fields, first_arg, filename.to_s, content_type)
+      status, resp_body, headers = post("/files/async", body_stream: stream, content_type: ct,
+                                                        content_length: length)
       raise_for_status(status, resp_body, headers) unless status == 202
       PendingResult.from_response(resp_body, headers)
     end
 
+    # Submit a file path for server-side asynchronous scanning.
+    #
+    # Opens the file in binary mode and delegates to {#process_async}.
+    #
+    # @param file_path [String] path to the file to upload
+    # @param metadata [Hash{String=>String}, nil]
+    # @param callback [String, nil]
+    # @see https://scanii.github.io/openapi/v22/  POST /files/async
+    # @return [Scanii::PendingResult]
+    def process_async_file(file_path, metadata: nil, callback: nil)
+      assert_readable(file_path)
+      File.open(file_path.to_s, "rb") do |f|
+        process_async(f, filename: File.basename(file_path.to_s), metadata: metadata,
+                         callback: callback)
+      end
+    end
+
     # Ask Scanii to download a remote URL and scan it asynchronously.
     #
     # @see https://scanii.github.io/openapi/v22/  POST /files/fetch
@@ -190,14 +270,16 @@ module Scanii
       fields
     end
 
-    def post(path, body:, content_type:)
-      request("POST", path, body: body, content_type: content_type)
+    def post(path, body: nil, content_type: nil, body_stream: nil, content_length: nil)
+      request("POST", path, body: body, content_type: content_type,
+                            body_stream: body_stream, content_length: content_length)
     end
 
-    def request(method, path, body: nil, content_type: nil)
+    def request(method, path, body: nil, content_type: nil, body_stream: nil, content_length: nil)
       uri = URI.parse("#{@base_uri}#{path}")
 
-      req = build_request(method, uri, body, content_type)
+      req = build_request(method, uri, body: body, content_type: content_type,
+                                       body_stream: body_stream, content_length: content_length)
 
       Net::HTTP.start(uri.hostname, uri.port,
                       use_ssl: uri.scheme == "https",
@@ -211,7 +293,7 @@ module Scanii
       raise Scanii::Error, "transport error: #{e.class}: #{e.message}"
     end
 
-    def build_request(method, uri, body, content_type)
+    def build_request(method, uri, body: nil, content_type: nil, body_stream: nil, content_length: nil)
       klass = case method
               when "GET"    then Net::HTTP::Get
               when "POST"   then Net::HTTP::Post
@@ -224,7 +306,14 @@ module Scanii
       req["User-Agent"]    = @user_agent
       req["Accept"]        = "application/json"
       req["Content-Type"]  = content_type if content_type
-      req.body = body if body
+
+      if body_stream
+        req.body_stream = body_stream
+        req["Content-Length"] = content_length.to_s
+      elsif body
+        req.body = body
+      end
+
       req
     end
 

data/lib/scanii/multipart.rb

@@ -1,14 +1,11 @@
 require "securerandom"
+require "stringio"
 
 module Scanii
   # Hand-rolled multipart/form-data encoder (RFC 7578).
   #
   # Ruby's stdlib Net::HTTP does not bundle a multipart encoder; this is the
   # smallest viable implementation that covers the Scanii POST /files payload.
-  #
-  # Body is assembled as a single binary-encoded String -- file contents are
-  # read into memory rather than streamed. This matches the PHP SDK's approach;
-  # callers scanning very large files should be aware.
   module Multipart
     module_function
 
@@ -22,42 +19,45 @@ module Scanii
       "multipart/form-data; boundary=#{boundary}"
     end
 
-    # Encode a multipart body containing the bytes at file_path plus the given
-    # text fields.
+    # Encode a multipart body as a streaming ChainedIO.
+    #
+    # Builds the RFC 7578 prologue and epilogue as binary Strings, chains them
+    # around the caller's IO, and returns the triple required for
+    # Net::HTTP body_stream= uploads. The caller's IO is never read here --
+    # only when Net::HTTP reads from the returned ChainedIO.
     #
-    # @param fields [Hash{String=>String}] text form fields (e.g. metadata[k] => v, callback => url)
-    # @param file_path [String] path to the file to upload
+    # @param fields [Hash{String=>String}] text form fields (e.g. metadata[k]=v, callback)
+    # @param io [#read, #size] IO-like object (anything responding to read(n))
+    # @param filename [String] filename for the file part
+    # @param content_type [String, nil] content-type of the file part; falls back to extension lookup
     # @param file_field [String] name of the file form field; default "file"
-    # @return [Array(String, String)] tuple of [body, content_type]
-    def encode(fields, file_path, file_field: "file")
+    # @return [Array(ChainedIO, String, Integer)] [body_stream, content_type_header, content_length]
+    def stream_encode(fields, io, filename, content_type = nil, file_field: "file")
       boundary = make_boundary
+      ct = content_type || guess_content_type(filename)
 
-      filename = File.basename(file_path)
-      content_type = guess_content_type(file_path)
-      file_bytes = File.binread(file_path)
-
-      body = String.new(encoding: Encoding::BINARY)
-
+      prologue = String.new(encoding: Encoding::BINARY)
       fields.each do |name, value|
-        write_text_part(body, boundary, name.to_s, value.to_s)
+        write_text_part(prologue, boundary, name.to_s, value.to_s)
       end
+      prologue << "--#{boundary}\r\n".b
+      prologue << "Content-Disposition: form-data; name=\"#{file_field}\"; filename=\"#{filename}\"\r\n".b
+      prologue << "Content-Type: #{ct}\r\n\r\n".b
 
-      body << "--#{boundary}\r\n".b
-      body << "Content-Disposition: form-data; name=\"#{file_field}\"; filename=\"#{filename}\"\r\n".b
-      body << "Content-Type: #{content_type}\r\n\r\n".b
-      body << file_bytes.b
-      body << "\r\n".b
-      body << "--#{boundary}--\r\n".b
+      epilogue = "\r\n--#{boundary}--\r\n".b
 
-      [body, make_content_type(boundary)]
+      io_size = io_remaining_bytes(io)
+      total_length = prologue.bytesize + io_size + epilogue.bytesize
+
+      [ChainedIO.new(prologue, io, epilogue), make_content_type(boundary), total_length]
     end
 
-    # Best-effort content-type lookup by extension. Falls back to
+    # Best-effort content-type lookup by filename extension. Falls back to
     # application/octet-stream. The Scanii API does not require an accurate
     # content-type on the multipart part -- the server inspects the bytes -- so
     # a short table is sufficient.
-    def guess_content_type(path)
-      ext = File.extname(path).delete_prefix(".").downcase
+    def guess_content_type(filename)
+      ext = File.extname(filename.to_s).delete_prefix(".").downcase
       MIME_TYPES.fetch(ext, "application/octet-stream")
     end
 
@@ -96,5 +96,60 @@ module Scanii
       body << "\r\n".b
     end
     private_class_method :write_text_part
+
+    # Return the number of bytes remaining to be read from io.
+    # Requires io to respond to size (File and StringIO both do).
+    def io_remaining_bytes(io)
+      if io.respond_to?(:pos) && io.respond_to?(:size)
+        io.size - io.pos
+      elsif io.respond_to?(:size)
+        io.size
+      else
+        raise ArgumentError, "io must respond to size (File and StringIO do; got #{io.class})"
+      end
+    end
+    private_class_method :io_remaining_bytes
+
+    # Reads prologue_str, then io, then epilogue_str in sequence.
+    # Used as Net::HTTP body_stream for streaming multipart uploads.
+    class ChainedIO
+      def initialize(prologue, io, epilogue)
+        @parts = [StringIO.new(prologue), io, StringIO.new(epilogue)]
+        @idx   = 0
+      end
+
+      def read(length = nil, buf = nil)
+        result = length.nil? ? read_all : read_n(length)
+        return nil if result.nil?
+
+        buf ? buf.replace(result) : result
+      end
+
+      private
+
+      def read_all
+        result = String.new(encoding: Encoding::BINARY)
+        @parts[@idx..].each do |part|
+          chunk = part.read
+          result << chunk.b if chunk
+        end
+        @idx = @parts.size
+        result
+      end
+
+      def read_n(length)
+        result = String.new(encoding: Encoding::BINARY)
+        while result.bytesize < length && @idx < @parts.size
+          chunk = @parts[@idx].read(length - result.bytesize)
+          if chunk.nil? || chunk.empty?
+            @idx += 1
+          else
+            result << chunk.b
+          end
+        end
+        result.empty? ? nil : result
+      end
+    end
+    private_constant :ChainedIO
   end
 end

data/lib/scanii/version.rb

@@ -1,3 +1,3 @@
 module Scanii
-  VERSION = "1.0.1".freeze
+  VERSION = "1.1.0".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: scanii-ruby
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Scanii