protocol-multipart 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa90f615454830d99794083234b6004921aba4eaa2846c6977fa4e871fbba1f8
-  data.tar.gz: 1aac98c2b5492345559aa76abd036ae30055e6a614e42a04936e0852649ad519
+  metadata.gz: '07498e70d64dd8df616ae6c73a9c00a71901707c81b3c5223cd8bb855fbe0d65'
+  data.tar.gz: 7ce3e69f8afac4da7339c3d953640e5e1144612cb7f7f12868eaab1aa360b733
 SHA512:
-  metadata.gz: 0234a8d2cd90bdb27d77136d7decdb2f841090590dec28ca4b8e4d43eb729bd7f79dfa386bcf93a83ee401450c6add28743aa95ed2fa8261bcfc50cd9d3b7fbb
-  data.tar.gz: 5a04aaec79f48cc4c9e3dcf0ead6517b10c1aa74f084d5f5ec3c5d31e1b9b2856400ac305091bda7ec87596eccc6320b0eee0f69322eb17fcb7d9c8ae3e51922
+  metadata.gz: 0fbe8ff1c95cc58a7548b14f0da442ca3715fa825fe56a395e792a0fc3b83249571d1b63a5f3d4ba0ecb544446d9f138fe811ae46220652d2f0d961a20684541
+  data.tar.gz: e5e7bbf1d0c7dac99f934429d251d190877b1f807f76dfe4eeebdcd2dbc0117df53b185aedbe4b63c9c203811bb0361a124b54aa83a62e64982e64e282cc0600

data/lib/protocol/multipart/form_data.rb

@@ -8,6 +8,7 @@ require_relative "parser"
 require_relative "string_part"
 require_relative "escape"
 require_relative "byte_limit"
+require_relative "readable"
 
 module Protocol
 	module Multipart
@@ -27,6 +28,8 @@ module Protocol
 			
 			# A file upload yielded while parsing form data.
 			class Upload
+				include Readable
+				
 				# Initialize a streamed file upload.
 				# @parameter part [Parser::Part] The underlying multipart part.
 				# @parameter filename [String] The submitted filename.

data/lib/protocol/multipart/parser.rb

@@ -6,6 +6,7 @@
 require "io/stream"
 require_relative "error"
 require_relative "headers"
+require_relative "readable"
 
 module Protocol
 	module Multipart
@@ -29,6 +30,8 @@ module Protocol
 			
 			# Represents a single part within a multipart message.
 			class Part
+				include Readable
+				
 				# Initialize a new part with a readable stream, headers, and a boundary string.
 				#
 				# @parameter readable [IO::Stream] The readable stream that contains the part's data.

data/lib/protocol/multipart/readable.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Protocol
+	module Multipart
+		# Common operations for streaming readable multipart content.
+		module Readable
+			# Copy the content to a writable object.
+			# @parameter output [#write] The writable destination.
+			# @parameter chunk_size [Integer] The maximum chunk size.
+			# @returns [Integer] The number of bytes copied.
+			def copy_to(output, chunk_size = 8192)
+				size = 0
+				
+				each(chunk_size) do |chunk|
+					offset = 0
+					
+					# A writable object may consume only part of a chunk:
+					while offset < chunk.bytesize
+						written = output.write(chunk.byteslice(offset, chunk.bytesize - offset))
+						
+						unless written && written > 0
+							raise IOError, "Could not make progress while copying multipart content!"
+						end
+						
+						offset += written
+					end
+					
+					size += chunk.bytesize
+				end
+				
+				return size
+			end
+			
+			# Save the content to a new local file.
+			# @parameter path [String, #to_path] The destination path, which must not exist.
+			# @parameter permissions [Integer] The permissions for the new file.
+			# @parameter chunk_size [Integer] The maximum chunk size.
+			# @returns [Integer] The number of bytes saved.
+			def save(path, permissions: 0o600, chunk_size: 8192)
+				flags = File::WRONLY | File::CREAT | File::EXCL
+				created = false
+				
+				begin
+					File.open(path, flags, permissions) do |file|
+						created = true
+						file.binmode
+						return copy_to(file, chunk_size)
+					end
+				rescue
+					# Remove a partial destination created by this operation:
+					if created
+						File.unlink(path)
+					end
+					
+					raise
+				end
+			end
+		end
+	end
+end

data/lib/protocol/multipart/version.rb

@@ -5,6 +5,6 @@
 
 module Protocol
 	module Multipart
-		VERSION = "0.6.0"
+		VERSION = "0.7.0"
 	end
 end

data/lib/protocol/multipart.rb

@@ -7,6 +7,7 @@ require_relative "multipart/version"
 require_relative "multipart/error"
 require_relative "multipart/byte_limit"
 require_relative "multipart/headers"
+require_relative "multipart/readable"
 require_relative "multipart/parser"
 require_relative "multipart/mixed"
 require_relative "multipart/part"

data/readme.md

@@ -6,6 +6,10 @@
 
 Please see the [project releases](https://socketry.github.io/protocol-multipart/releases/index) for all releases.
 
+### v0.7.0
+
+  - Add `copy_to` and secure local `save` operations for readable multipart parts and form-data uploads.
+
 ### v0.6.0
 
   - Rename `Protocol::Multipart::FormData::Parser::CONTENT_TYPE` to `MEDIA_TYPE`.

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## v0.7.0
+
+  - Add `copy_to` and secure local `save` operations for readable multipart parts and form-data uploads.
+
 ## v0.6.0
 
   - Rename `Protocol::Multipart::FormData::Parser::CONTENT_TYPE` to `MEDIA_TYPE`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-multipart
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -99,6 +99,7 @@ files:
 - lib/protocol/multipart/mixed.rb
 - lib/protocol/multipart/parser.rb
 - lib/protocol/multipart/part.rb
+- lib/protocol/multipart/readable.rb
 - lib/protocol/multipart/string_part.rb
 - lib/protocol/multipart/version.rb
 - license.md