faraday-multipart 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7bd6e0b4dcb4d5905af5f8ee93c61a77858f13d1bfbbc00c3b9ea24091ef6af9
+  data.tar.gz: fd8d9f6e6cad9ad03e98e2b756be32c6862b23798552149d93568a6902bc6f19
+SHA512:
+  metadata.gz: b5644f53bad5e159723fbb174164270dc4de8668eac04d278004c9b11608337771f73295e73160125c954dd6a36b0af702bada137c4f9894a935517c3afc06e7
+  data.tar.gz: 37613553511b02097c04d4524e13fe1c3fc946b2549a07dc2b76e9519a570fa88f6f7717964c0cdbcf9425b09b46565cd8b8b73cd3cb8707ee597480d0c67f4b

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## Unreleased
+
+*   Initial release.

data/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 The Faraday Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,111 @@
+# Faraday Multipart
+
+[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/lostisland/faraday-multipart/ci)](https://github.com/lostisland/faraday-multipart/actions?query=branch%3Amain)
+[![Gem](https://img.shields.io/gem/v/faraday-multipart.svg?style=flat-square)](https://rubygems.org/gems/faraday-multipart)
+[![License](https://img.shields.io/github/license/lostisland/faraday-multipart.svg?style=flat-square)](LICENSE.md)
+
+The `Multipart` middleware converts a `Faraday::Request#body` Hash of key/value pairs into a multipart form request, but
+only under these conditions:
+
+* 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::Multipart::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::Multipart::ParamPart` wraps a String value with a Content-Type, and optionally a Content-ID.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'faraday-multipart'
+```
+
+And then execute:
+
+```shell
+bundle install
+```
+
+Or install it yourself as:
+
+```shell
+gem install faraday-multipart
+```
+
+## Usage
+
+First of all, you'll need to add the multipart middleware to your Faraday connection:
+
+```ruby
+require 'faraday/multipart'
+
+conn = Faraday.new(...) do |f|
+  f.request :multipart
+  # ...
+end
+```
+
+Payload can be a mix of POST data and multipart values.
+
+```ruby
+# regular POST form value
+payload = { string: 'value' }
+
+# filename for this value is File.basename(__FILE__)
+payload[:file] = Faraday::Multipart::FilePart.new(__FILE__, 'text/x-ruby')
+
+# specify filename because IO object doesn't know it
+payload[:file_with_name] = Faraday::Multipart::FilePart.new(
+  File.open(__FILE__),
+  'text/x-ruby',
+  File.basename(__FILE__)
+)
+
+# Sets a custom Content-Disposition:
+# nil filename still defaults to File.basename(__FILE__)
+payload[:file_with_header] = Faraday::Multipart::FilePart.new(
+  __FILE__,
+  'text/x-ruby',
+  nil,
+  'Content-Disposition' => 'form-data; foo=1'
+)
+
+# Upload raw json with content type
+payload[:raw_data] = Faraday::Multipart::ParamPart.new(
+  { a: 1 }.to_json,
+  'application/json'
+)
+
+# optionally sets Content-ID too
+payload[:raw_with_id] = Faraday::Multipart::ParamPart.new(
+  { a: 1 }.to_json,
+  'application/json',
+  'foo-123'
+)
+
+conn.post('/', payload)
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies.
+
+Then, run `bin/test` to run the tests.
+
+To install this gem onto your local machine, run `rake build`.
+
+To release a new version, make a commit with a message such as "Bumped to 0.0.2" and then run `rake release`. See how it
+works [here](https://bundler.io/guides/creating_gem.html#releasing-the-gem).
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/lostisland/faraday-multipart).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/faraday/multipart/file_part.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'stringio'
+
+# multipart-post gem
+require 'composite_io'
+require 'parts'
+
+module Faraday
+  module Multipart
+    # Multipart value used to POST a binary data from a file or
+    #
+    # @example
+    #   payload = { file: Faraday::FilePart.new("file_name.ext", "content/type") }
+    #   http.post("/upload", payload)
+    #
+
+    # @!method initialize(filename_or_io, content_type, filename = nil, opts = {})
+    #
+    #   @param filename_or_io [String, IO] Either a String filename to a local
+    #     file or an open IO object.
+    #   @param content_type [String] String content type of the file data.
+    #   @param filename [String] Optional String filename, usually to add context
+    #     to a given IO object.
+    #   @param opts [Hash] Optional Hash of String key/value pairs to describethis
+    #     this uploaded file. Expected Header keys include:
+    #     * Content-Transfer-Encoding - Defaults to "binary"
+    #     * Content-Disposition - Defaults to "form-data"
+    #     * Content-Type - Defaults to the content_type argument.
+    #     * Content-ID - Optional.
+    #
+    # @return [Faraday::FilePart]
+    #
+    # @!attribute [r] content_type
+    # The uploaded binary data's content type.
+    #
+    # @return [String]
+    #
+    # @!attribute [r] original_filename
+    # The base filename, taken either from the filename_or_io or filename
+    # arguments in #initialize.
+    #
+    # @return [String]
+    #
+    # @!attribute [r] opts
+    # Extra String key/value pairs to make up the header for this uploaded file.
+    #
+    # @return [Hash]
+    #
+    # @!attribute [r] io
+    # The open IO object for the uploaded file.
+    #
+    # @return [IO]
+    FilePart = ::UploadIO
+
+    Parts = ::Parts
+
+    # Similar to, but not compatible with CompositeReadIO provided by the
+    # multipart-post gem.
+    # https://github.com/nicksieger/multipart-post/blob/master/lib/composite_io.rb
+    class CompositeReadIO
+      def initialize(*parts)
+        @parts = parts.flatten
+        @ios = @parts.map(&:to_io)
+        @index = 0
+      end
+
+      # @return [Integer] sum of the lengths of all the parts
+      def length
+        @parts.inject(0) { |sum, part| sum + part.length }
+      end
+
+      # Rewind each of the IOs and reset the index to 0.
+      #
+      # @return [void]
+      def rewind
+        @ios.each(&:rewind)
+        @index = 0
+      end
+
+      # Read from IOs in order until `length` bytes have been received.
+      #
+      # @param length [Integer, nil]
+      # @param outbuf [String, nil]
+      def read(length = nil, outbuf = nil)
+        got_result = false
+        outbuf = outbuf ? (+outbuf).replace('') : +''
+
+        while (io = current_io)
+          if (result = io.read(length))
+            got_result ||= !result.nil?
+            result.force_encoding('BINARY') if result.respond_to?(:force_encoding)
+            outbuf << result
+            length -= result.length if length
+            break if length&.zero?
+          end
+          advance_io
+        end
+        !got_result && length ? nil : outbuf
+      end
+
+      # Close each of the IOs.
+      #
+      # @return [void]
+      def close
+        @ios.each(&:close)
+      end
+
+      def ensure_open_and_readable
+        # Rubinius compatibility
+      end
+
+      private
+
+      def current_io
+        @ios[@index]
+      end
+
+      def advance_io
+        @index += 1
+      end
+    end
+  end
+end

data/lib/faraday/multipart/middleware.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Faraday
+  module Multipart
+    # Middleware for supporting multi-part requests.
+    class Middleware < Faraday::Request::UrlEncoded
+      DEFAULT_BOUNDARY_PREFIX = '-----------RubyMultipartPost'
+
+      self.mime_type = 'multipart/form-data'
+
+      def initialize(app = nil, options = {})
+        super(app)
+        @options = options
+      end
+
+      # Checks for files in the payload, otherwise leaves everything untouched.
+      #
+      # @param env [Faraday::Env]
+      def call(env)
+        match_content_type(env) do |params|
+          env.request.boundary ||= unique_boundary
+          env.request_headers[CONTENT_TYPE] +=
+            "; boundary=#{env.request.boundary}"
+          env.body = create_multipart(env, params)
+        end
+        @app.call env
+      end
+
+      # @param env [Faraday::Env]
+      def process_request?(env)
+        type = request_type(env)
+        env.body.respond_to?(:each_key) && !env.body.empty? && (
+          (type.empty? && has_multipart?(env.body)) ||
+            (type == self.class.mime_type)
+        )
+      end
+
+      # Returns true if obj is an enumerable with values that are multipart.
+      #
+      # @param obj [Object]
+      # @return [Boolean]
+      def has_multipart?(obj)
+        if obj.respond_to?(:each)
+          (obj.respond_to?(:values) ? obj.values : obj).each do |val|
+            return true if val.respond_to?(:content_type) || has_multipart?(val)
+          end
+        end
+        false
+      end
+
+      # @param env [Faraday::Env]
+      # @param params [Hash]
+      def create_multipart(env, params)
+        boundary = env.request.boundary
+        parts = process_params(params) do |key, value|
+          part(boundary, key, value)
+        end
+        parts << Faraday::Multipart::Parts::EpiloguePart.new(boundary)
+
+        body = Faraday::Multipart::CompositeReadIO.new(parts)
+        env.request_headers[Faraday::Env::ContentLength] = body.length.to_s
+        body
+      end
+
+      def part(boundary, key, value)
+        if value.respond_to?(:to_part)
+          value.to_part(boundary, key)
+        else
+          Faraday::Multipart::Parts::Part.new(boundary, key, value)
+        end
+      end
+
+      # @return [String]
+      def unique_boundary
+        "#{DEFAULT_BOUNDARY_PREFIX}-#{SecureRandom.hex}"
+      end
+
+      # @param params [Hash]
+      # @param prefix [String]
+      # @param pieces [Array]
+      def process_params(params, prefix = nil, pieces = nil, &block)
+        params.inject(pieces || []) do |all, (key, value)|
+          if prefix
+            key = @options[:flat_encode] ? prefix.to_s : "#{prefix}[#{key}]"
+          end
+
+          case value
+          when Array
+            values = value.inject([]) { |a, v| a << [nil, v] }
+            process_params(values, key, all, &block)
+          when Hash
+            process_params(value, key, all, &block)
+          else
+            all << block.call(key, value) # rubocop:disable Performance/RedundantBlockCall
+          end
+        end
+      end
+    end
+  end
+end

data/lib/faraday/multipart/param_part.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Faraday
+  module Multipart
+    # Multipart value used to POST data with a content type.
+    class ParamPart
+      # @param value [String] Uploaded content as a String.
+      # @param content_type [String] String content type of the value.
+      # @param content_id [String] Optional String of this value's Content-ID.
+      #
+      # @return [Faraday::ParamPart]
+      def initialize(value, content_type, content_id = nil)
+        @value = value
+        @content_type = content_type
+        @content_id = content_id
+      end
+
+      # Converts this value to a form part.
+      #
+      # @param boundary [String] String multipart boundary that must not exist in
+      #   the content exactly.
+      # @param key [String] String key name for this value.
+      #
+      # @return [Faraday::Parts::Part]
+      def to_part(boundary, key)
+        Faraday::Multipart::Parts::Part.new(boundary, key, value, headers)
+      end
+
+      # Returns a Hash of String key/value pairs.
+      #
+      # @return [Hash]
+      def headers
+        {
+          'Content-Type' => content_type,
+          'Content-ID' => content_id
+        }
+      end
+
+      # The content to upload.
+      #
+      # @return [String]
+      attr_reader :value
+
+      # The value's content type.
+      #
+      # @return [String]
+      attr_reader :content_type
+
+      # The value's content ID, if given.
+      #
+      # @return [String, nil]
+      attr_reader :content_id
+    end
+  end
+end

data/lib/faraday/multipart/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Faraday
+  module Multipart
+    VERSION = '1.0.0'
+  end
+end

data/lib/faraday/multipart.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require_relative 'multipart/file_part'
+require_relative 'multipart/param_part'
+require_relative 'multipart/middleware'
+require_relative 'multipart/version'
+
+module Faraday
+  # Main Faraday::Multipart module.
+  module Multipart
+    Faraday::Request.register_middleware(multipart: Faraday::Multipart::Middleware)
+  end
+end

metadata

@@ -0,0 +1,208 @@
+--- !ruby/object:Gem::Specification
+name: faraday-multipart
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Mattia Giuffrida
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2022-01-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: multipart-post
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.21.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.21.0
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.21.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.21.0
+- !ruby/object:Gem::Dependency
+  name: rubocop-packaging
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: 'Perform multipart-post requests using Faraday.
+
+  '
+email:
+- giuffrida.mattia@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.md
+- README.md
+- lib/faraday/multipart.rb
+- lib/faraday/multipart/file_part.rb
+- lib/faraday/multipart/middleware.rb
+- lib/faraday/multipart/param_part.rb
+- lib/faraday/multipart/version.rb
+homepage: https://github.com/lostisland/faraday-multipart
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/lostisland/faraday-multipart/issues
+  changelog_uri: https://github.com/lostisland/faraday-multipart/blob/v1.0.0/CHANGELOG.md
+  documentation_uri: http://www.rubydoc.info/gems/faraday-multipart/1.0.0
+  homepage_uri: https://github.com/lostisland/faraday-multipart
+  source_code_uri: https://github.com/lostisland/faraday-multipart
+  wiki_uri: https://github.com/lostisland/faraday-multipart/wiki
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: '4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key: 
+specification_version: 4
+summary: Perform multipart-post requests using Faraday.
+test_files: []