From 69f84493bfeb6f150451912748a7fb8b105abd9f Mon Sep 17 00:00:00 2001 From: rick olson Date: Wed, 11 Sep 2019 12:22:17 -0600 Subject: [PATCH 1/5] update multipart docs to mention ParamsPart class --- docs/middleware/request/multipart.md | 39 ++++++++++++++++++---------- 1 file changed, 26 insertions(+), 13 deletions(-) diff --git a/docs/middleware/request/multipart.md b/docs/middleware/request/multipart.md index 227246724..b683b33ca 100644 --- a/docs/middleware/request/multipart.md +++ b/docs/middleware/request/multipart.md @@ -11,11 +11,19 @@ top_name: Back to Middleware top_link: ./list --- -The `Multipart` middleware converts a `Faraday::Request#body` hash of key/value pairs into a multipart form request. -This only happens if the middleware finds an object in the request body that responds to `content_type`. -The middleware also automatically adds the boundary to the request body. -You can use `Faraday::UploadIO` or `Faraday::CompositeReadIO` to wrap your multipart parameters, -which are in turn wrappers of the equivalent classes from the [`multipart-post`][multipart_post] gem. +The `Multipart` middleware converts a `Faraday::Request#body` Hash of key/value +pairs into a multipart form request, but only under these conditions: + +* The Content-Type is "multipart/form-data" +* Content-Type is unspecified, AND one of the values in the Body responds to +`#content_type`. + +Faraday contains a couple helper classes for multipart values: + +* `Faraday::UploadIO` wraps file data with a Content-Type. The file data can be +specified with a String path to a local file, or an IO object. +* `Faraday::ParamsPart` wraps a String value with a Content-Type, and optionally +a Content-ID. ### Example Usage @@ -26,18 +34,23 @@ conn = Faraday.new(...) do |f| end ``` -Payload can be a mix of POST data and UploadIO objects. +Payload can be a mix of POST data and multipart values. ```ruby payload = { - file_name: 'multipart_example.rb', - file: Faraday::UploadIO.new(__FILE__, 'text/x-ruby') + string: "value", + file: Faraday::UploadIO.new(__FILE__, "text/x-ruby"), + + file_with_name: Faraday::UploadIO.new(__FILE__, "text/x-ruby", "copy.rb"), + + file_with_header: Faraday::UploadIO.new(__FILE__, "text/x-ruby", nil, + 'Content-Disposition' => 'form-data; foo=1'), + + raw_data: Faraday::ParamsPart.new({a: 1}.to_json, "application/json") + + raw_with_id: Faraday::ParamsPart.new({a: 1}.to_json, "application/json", + "foo-123") } conn.post('/', payload) -# POST with -# Content-Type: "multipart/form-data; boundary=-----------RubyMultipartPost-b7f5d9a9b5f201e7af7d7af730ac4bf4" -# Body: # ``` - -[multipart_post]: https://github.com/socketry/multipart-post \ No newline at end of file From c7cb95f624d581cbbdd38004996669e161e45f23 Mon Sep 17 00:00:00 2001 From: risk danger olson Date: Wed, 18 Sep 2019 14:39:35 -0600 Subject: [PATCH 2/5] Use newer "FilePart" name --- docs/middleware/request/multipart.md | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/docs/middleware/request/multipart.md b/docs/middleware/request/multipart.md index b683b33ca..4905d2159 100644 --- a/docs/middleware/request/multipart.md +++ b/docs/middleware/request/multipart.md @@ -14,17 +14,20 @@ top_link: ./list The `Multipart` middleware converts a `Faraday::Request#body` Hash of key/value pairs into a multipart form request, but only under these conditions: -* The Content-Type is "multipart/form-data" +* The request's Content-Type is "multipart/form-data" * Content-Type is unspecified, AND one of the values in the Body responds to `#content_type`. Faraday contains a couple helper classes for multipart values: -* `Faraday::UploadIO` wraps file data with a Content-Type. The file data can be -specified with a String path to a local file, or an IO object. -* `Faraday::ParamsPart` wraps a String value with a Content-Type, and optionally +* `Faraday::FilePart` wraps binary file data with a Content-Type. The file data +can be specified with a String path to a local file, or an IO object. +* `Faraday::ParamPart` wraps a String value with a Content-Type, and optionally a Content-ID. +Note: `Faraday::ParamPart` was added in Faraday v0.16.0. Before that, +`Faraday::FilePart` was called `Faraday::UploadIO`. + ### Example Usage ```ruby @@ -39,16 +42,17 @@ Payload can be a mix of POST data and multipart values. ```ruby payload = { string: "value", - file: Faraday::UploadIO.new(__FILE__, "text/x-ruby"), + file: Faraday::FilePart.new(__FILE__, "text/x-ruby"), - file_with_name: Faraday::UploadIO.new(__FILE__, "text/x-ruby", "copy.rb"), + file_with_name: Faraday::FilePart.new(__FILE__, "text/x-ruby", "copy.rb"), - file_with_header: Faraday::UploadIO.new(__FILE__, "text/x-ruby", nil, + file_with_header: Faraday::FilePart.new(File.open(__FILE__), "text/x-ruby", + File.basename(__FILE__), 'Content-Disposition' => 'form-data; foo=1'), - raw_data: Faraday::ParamsPart.new({a: 1}.to_json, "application/json") + raw_data: Faraday::ParamPart.new({a: 1}.to_json, "application/json") - raw_with_id: Faraday::ParamsPart.new({a: 1}.to_json, "application/json", + raw_with_id: Faraday::ParamPart.new({a: 1}.to_json, "application/json", "foo-123") } From 741827045706be3ee24e207ed4a024feae1ae618 Mon Sep 17 00:00:00 2001 From: risk danger olson Date: Thu, 19 Sep 2019 12:29:21 -0600 Subject: [PATCH 3/5] annotate example --- docs/middleware/request/multipart.md | 30 ++++++++++++++++++---------- 1 file changed, 19 insertions(+), 11 deletions(-) diff --git a/docs/middleware/request/multipart.md b/docs/middleware/request/multipart.md index 4905d2159..f333469a0 100644 --- a/docs/middleware/request/multipart.md +++ b/docs/middleware/request/multipart.md @@ -40,21 +40,29 @@ end Payload can be a mix of POST data and multipart values. ```ruby -payload = { - string: "value", - file: Faraday::FilePart.new(__FILE__, "text/x-ruby"), +# regular POST form value +payload = { string: 'value' } - file_with_name: Faraday::FilePart.new(__FILE__, "text/x-ruby", "copy.rb"), +# filename for this value is File.basename(__FILE__) +payload[:file] = Faraday::FilePart.new(__FILE__, 'text/x-ruby') - file_with_header: Faraday::FilePart.new(File.open(__FILE__), "text/x-ruby", - File.basename(__FILE__), - 'Content-Disposition' => 'form-data; foo=1'), +# specify filename because IO object doesn't know it +payload[:file_with_name] = Faraday::FilePart.new(File.open(__FILE__), + 'text/x-ruby', + File.basename(__FILE__)) - raw_data: Faraday::ParamPart.new({a: 1}.to_json, "application/json") +# Sets a custom Content-Disposition: +# nil filename still defaults to File.basename(__FILE__) +payload[:file_with_header] = Faraday::FilePart.new(__FILE__, + 'text/x-ruby', nil, + 'Content-Disposition' => 'form-data; foo=1') - raw_with_id: Faraday::ParamPart.new({a: 1}.to_json, "application/json", - "foo-123") -} +# Upload raw json with content type +payload[:raw_data] = Faraday::ParamPart.new({a: 1}.to_json, 'application/json') + +# optionally sets Content-ID too +payload[:raw_with_id] = Faraday::ParamPart.new({a: 1}.to_json, "application/json", + "foo-123") conn.post('/', payload) ``` From dd26c7c6836ac12b7396fdcdd555728d4450b917 Mon Sep 17 00:00:00 2001 From: risk danger olson Date: Thu, 19 Sep 2019 15:10:54 -0600 Subject: [PATCH 4/5] Consistently use single quotes --- docs/middleware/request/multipart.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/middleware/request/multipart.md b/docs/middleware/request/multipart.md index f333469a0..cc70dea76 100644 --- a/docs/middleware/request/multipart.md +++ b/docs/middleware/request/multipart.md @@ -61,8 +61,8 @@ payload[:file_with_header] = Faraday::FilePart.new(__FILE__, payload[:raw_data] = Faraday::ParamPart.new({a: 1}.to_json, 'application/json') # optionally sets Content-ID too -payload[:raw_with_id] = Faraday::ParamPart.new({a: 1}.to_json, "application/json", - "foo-123") +payload[:raw_with_id] = Faraday::ParamPart.new({a: 1}.to_json, 'application/json', + 'foo-123') conn.post('/', payload) ``` From 01566e9adcb48fcb4787d05fff2732577883d9c2 Mon Sep 17 00:00:00 2001 From: rick olson Date: Thu, 19 Sep 2019 17:42:46 -0600 Subject: [PATCH 5/5] remove last UploadIO reference --- docs/middleware/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/middleware/index.md b/docs/middleware/index.md index 7048fa99e..dc100eb34 100644 --- a/docs/middleware/index.md +++ b/docs/middleware/index.md @@ -44,7 +44,7 @@ Examples: ```ruby # uploading a file: -payload[:profile_pic] = Faraday::UploadIO.new('/path/to/avatar.jpg', 'image/jpeg') +payload[:profile_pic] = Faraday::FilePart.new('/path/to/avatar.jpg', 'image/jpeg') # "Multipart" middleware detects files and encodes with "multipart/form-data": conn.put '/profile', payload