google-api-client 0.8.6 → 0.9

data/lib/google/apis/core/multipart.rb

@@ -0,0 +1,187 @@
+# Copyright 2015 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'hurley'
+
+module Google
+  module Apis
+    module Core
+      # Part of a multipart request for holding JSON data
+      #
+      # @private
+      class JsonPart
+        include Hurley::Multipart::Part
+
+        # @return [Fixnum]
+        #   Length of part
+        attr_reader :length
+
+        # @param [String] boundary
+        #   Multipart boundary
+        # @param [String] value
+        #   JSON content
+        def initialize(boundary, value, header = {})
+          @part = build_part(boundary, value)
+          @length = @part.bytesize
+          @io = StringIO.new(@part)
+        end
+
+        private
+
+        # Format the part
+        #
+        # @param [String] boundary
+        #   Multipart boundary
+        # @param [String] value
+        #   JSON content
+        # @return [String]
+        def build_part(boundary, value)
+          part = ''
+          part << "--#{boundary}\r\n"
+          part << "Content-Type: application/json\r\n"
+          part << "\r\n"
+          part << "#{value}\r\n"
+        end
+      end
+
+      # Part of a multipart request for holding arbitrary content. Modified
+      # from Hurley::Multipart::FilePart to remove Content-Disposition
+      #
+      # @private
+      class FilePart
+        include Hurley::Multipart::Part
+
+        # @return [Fixnum]
+        #   Length of part
+        attr_reader :length
+
+        # @param [String] boundary
+        #   Multipart boundary
+        # @param [Google::Apis::Core::UploadIO] io
+        #   IO stream
+        # @param [Hash] header
+        #   Additional headers
+        def initialize(boundary, io, header = {})
+          file_length = io.respond_to?(:length) ? io.length : File.size(io.local_path)
+
+          @head = build_head(boundary, io.content_type, file_length,
+                             io.respond_to?(:opts) ? io.opts.merge(header) : header)
+
+          @length = @head.bytesize + file_length + FOOT.length
+          @io = Hurley::CompositeReadIO.new(@length, StringIO.new(@head), io, StringIO.new(FOOT))
+        end
+
+        private
+
+        # Construct the header for the part
+        #
+        # @param [String] boundary
+        #  Multipart boundary
+        # @param [String] type
+        #  Content type for the part
+        # @param [Fixnum] content_len
+        #  Length of the part
+        # @param [Hash] header
+        #  Headers for the part
+        def build_head(boundary, type, content_len, header)
+          content_id = ''
+          if header[:content_id]
+            content_id = sprintf(CID_FORMAT, header[:content_id])
+          end
+          sprintf(HEAD_FORMAT,
+                  boundary,
+                  content_len.to_i,
+                  content_id,
+                  header[:content_type] || type,
+                  header[:content_transfer_encoding] || DEFAULT_TR_ENCODING)
+        end
+
+        DEFAULT_TR_ENCODING = 'binary'.freeze
+        FOOT = "\r\n".freeze
+        CID_FORMAT = "Content-ID: %s\r\n"
+        HEAD_FORMAT = <<-END
+--%s\r
+Content-Length: %d\r
+%sContent-Type: %s\r
+Content-Transfer-Encoding: %s\r
+\r
+        END
+      end
+
+      # Helper for building multipart requests
+      class Multipart
+        MULTIPART_RELATED = 'multipart/related'
+        DEFAULT_BOUNDARY = 'RubyApiClientMultiPart'
+
+        # @return [String]
+        #  Content type header
+        attr_reader :content_type
+
+        # @param [String] content_type
+        #  Content type for the multipart request
+        # @param [String] boundary
+        #  Part delimiter
+
+        def initialize(content_type: MULTIPART_RELATED, boundary: nil)
+          @parts = []
+          @boundary = boundary || DEFAULT_BOUNDARY
+          @content_type = "#{content_type}; boundary=#{boundary}"
+        end
+
+        # Append JSON data part
+        #
+        # @param [String] body
+        #   JSON text
+        # @param [String] content_id
+        #   Optional unique ID of this part
+        # @return [self]
+        def add_json(body, content_id: nil)
+          header = { :content_id => content_id }
+          @parts << Google::Apis::Core::JsonPart.new(@boundary, body, header)
+          self
+        end
+
+        # Append arbitrary data as a part
+        #
+        # @param [Google::Apis::Core::UploadIO] upload_io
+        #   IO stream
+        # @param [String] content_id
+        #   Optional unique ID of this part
+        # @return [self]
+        def add_upload(upload_io, content_id: nil)
+          header = { :content_id => content_id }
+          @parts << Google::Apis::Core::FilePart.new(@boundary,
+                                                     upload_io,
+                                                     header)
+          self
+        end
+
+        # Assemble the multipart requests
+        #
+        # @return [IO]
+        #  IO stream
+        def assemble
+          @parts << Hurley::Multipart::EpiloguePart.new(@boundary)
+          ios = []
+          len = 0
+          @parts.each do |part|
+            len += part.length
+            ios << part.to_io
+          end
+          Hurley::CompositeReadIO.new(len, *ios)
+        end
+      end
+    end
+  end
+end

data/lib/google/apis/core/upload.rb

@@ -0,0 +1,288 @@
+# Copyright 2015 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'google/apis/core/multipart'
+require 'google/apis/core/http_command'
+require 'google/apis/core/api_command'
+require 'google/apis/errors'
+require 'addressable/uri'
+require 'mime-types'
+
+module Google
+  module Apis
+    module Core
+      # Extension of Hurley's UploadIO to add length accessor
+      class UploadIO < Hurley::UploadIO
+        OCTET_STREAM_CONTENT_TYPE = 'application/octet-stream'
+
+        # Get the length of the stream
+        # @return [Fixnum]
+        def length
+          io.respond_to?(:length) ? io.length : File.size(local_path)
+        end
+
+        # Create a new instance given a file path
+        # @param [String, File] file_name
+        #  Path to file
+        # @param [String] content_type
+        #  Optional content type. If nil, will attempt to auto-detect
+        # @return [Google::Apis::Core::UploadIO]
+        def self.from_file(file_name, content_type: nil)
+          if content_type.nil?
+            type = MIME::Types.of(file_name)
+            content_type = type.first.content_type unless type.nil? || type.empty?
+          end
+          new(file_name, content_type || OCTET_STREAM_CONTENT_TYPE)
+        end
+
+        # Wraps an IO stream in UploadIO
+        # @param [#read] io
+        #  IO to wrap
+        # @param [String] content_type
+        #  Optional content type.
+        # @return [Google::Apis::Core::UploadIO]
+        def self.from_io(io, content_type: OCTET_STREAM_CONTENT_TYPE)
+          new(io, content_type)
+        end
+      end
+
+      # Base upload command. Not intended to be used directly
+      # @private
+      class BaseUploadCommand < ApiCommand
+        UPLOAD_PROTOCOL_HEADER = 'X-Goog-Upload-Protocol'
+        UPLOAD_CONTENT_TYPE_HEADER = 'X-Goog-Upload-Header-Content-Type'
+        UPLOAD_CONTENT_LENGTH = 'X-Goog-Upload-Header-Content-Length'
+
+        # File name or IO containing the content to upload
+        # @return [String, File, #read]
+        attr_accessor :upload_source
+
+        # Content type of the upload material
+        # @return [String]
+        attr_accessor :upload_content_type
+
+        # Content, as UploadIO
+        # @return [Google::Apis::Core::UploadIO]
+        attr_accessor :upload_io
+
+        # Ensure the content is readable and wrapped in an {{Google::Apis::Core::UploadIO}} instance.
+        #
+        # @return [void]
+        # @raise [Google::Apis::ClientError] if upload source is invalid
+        def prepare!
+          super
+          if streamable?(upload_source)
+            self.upload_io = UploadIO.from_io(upload_source, content_type: upload_content_type)
+            @close_io_on_finish = false
+          elsif upload_source.is_a?(String)
+            self.upload_io = UploadIO.from_file(upload_source, content_type: upload_content_type)
+            @close_io_on_finish = true
+          else
+            fail Google::Apis::ClientError, 'Invalid upload source'
+          end
+        end
+
+        # Close IO stream when command done. Only closes the stream if it was opened by the command.
+        def release!
+          upload_io.close if @close_io_on_finish
+        end
+
+        private
+
+        def streamable?(upload_source)
+          upload_source.is_a?(IO) || upload_source.is_a?(StringIO) || upload_source.is_a?(Tempfile)
+        end
+      end
+
+      # Implementation of the raw upload protocol
+      class RawUploadCommand < BaseUploadCommand
+        RAW_PROTOCOL = 'raw'
+
+        # Ensure the content is readable and wrapped in an {{Google::Apis::Core::UploadIO}} instance.
+        #
+        # @return [void]
+        # @raise [Google::Apis::ClientError] if upload source is invalid
+        def prepare!
+          super
+          self.body = upload_io
+          header[UPLOAD_PROTOCOL_HEADER] = RAW_PROTOCOL
+          header[UPLOAD_CONTENT_TYPE_HEADER] = upload_io.content_type
+        end
+      end
+
+      # Implementation of the multipart upload protocol
+      class MultipartUploadCommand < BaseUploadCommand
+        UPLOAD_BOUNDARY = 'RubyApiClientUpload'
+        MULTIPART_PROTOCOL = 'multipart'
+        MULTIPART_RELATED = 'multipart/related'
+
+        # Encode the multipart request
+        #
+        # @return [void]
+        # @raise [Google::Apis::ClientError] if upload source is invalid
+        def prepare!
+          super
+          @multipart = Multipart.new(boundary: UPLOAD_BOUNDARY, content_type: MULTIPART_RELATED)
+          @multipart.add_json(body)
+          @multipart.add_upload(upload_io)
+          self.body = @multipart.assemble
+          header[:content_type] = @multipart.content_type
+          header[UPLOAD_PROTOCOL_HEADER] = MULTIPART_PROTOCOL
+        end
+      end
+
+      # Implementation of the resumable upload protocol
+      class ResumableUploadCommand < BaseUploadCommand
+        UPLOAD_COMMAND_HEADER = 'X-Goog-Upload-Command'
+        UPLOAD_OFFSET_HEADER = 'X-Goog-Upload-Offset'
+        BYTES_RECEIVED_HEADER = 'X-Goog-Upload-Size-Received'
+        UPLOAD_URL_HEADER = 'X-Goog-Upload-URL'
+        UPLOAD_STATUS_HEADER = 'X-Goog-Upload-Status'
+        STATUS_ACTIVE = 'active'
+        STATUS_FINAL = 'final'
+        STATUS_CANCELLED = 'cancelled'
+        RESUMABLE = 'resumable'
+        START_COMMAND = 'start'
+        QUERY_COMMAND = 'query'
+        UPLOAD_COMMAND = 'upload, finalize'
+
+        # Reset upload to initial state.
+        #
+        # @return [void]
+        # @raise [Google::Apis::ClientError] if upload source is invalid
+        def prepare!
+          @state = :start
+          @upload_url = nil
+          @offset = 0
+          super
+        end
+
+        # Check the to see if the upload is complete or needs to be resumed.
+        #
+        # @param [Fixnum] status
+        #   HTTP status code of response
+        # @param [Hurley::Header] header
+        #   Response headers
+        # @param [String, #read] body
+        #  Response body
+        # @return [Object]
+        #   Response object
+        # @raise [Google::Apis::ServerError] An error occurred on the server and the request can be retried
+        # @raise [Google::Apis::ClientError] The request is invalid and should not be retried without modification
+        # @raise [Google::Apis::AuthorizationError] Authorization is required
+        def process_response(status, header, body)
+          @offset = Integer(header[BYTES_RECEIVED_HEADER]) if header.key?(BYTES_RECEIVED_HEADER)
+          @upload_url = header[UPLOAD_URL_HEADER] if header.key?(UPLOAD_URL_HEADER)
+          upload_status = header[UPLOAD_STATUS_HEADER]
+          logger.debug { sprintf('Upload status %s', upload_status) }
+          if upload_status == STATUS_ACTIVE
+            @state = :active
+          elsif upload_status == STATUS_FINAL
+            @state = :final
+          elsif upload_status == STATUS_CANCELLED
+            @state = :cancelled
+            fail Google::Apis::ClientError, body
+          end
+          super(status, header, body)
+        end
+
+        # Send the start command to initiate the upload
+        #
+        # @param [Hurley::Client] client
+        #   HTTP client
+        # @return [Hurley::Response]
+        # @raise [Google::Apis::ServerError] Unable to send the request
+        def send_start_command(client)
+          logger.debug { sprintf('Sending upload start command to %s', url) }
+          client.send(method, url, body) do |req|
+            apply_request_options(req)
+            req.header[UPLOAD_PROTOCOL_HEADER] = RESUMABLE
+            req.header[UPLOAD_COMMAND_HEADER] = START_COMMAND
+            req.header[UPLOAD_CONTENT_LENGTH] = upload_io.length.to_s
+            req.header[UPLOAD_CONTENT_TYPE_HEADER] = upload_io.content_type
+          end
+        rescue => e
+          raise Google::Apis::ServerError, e.message
+        end
+
+        # Query for the status of an incomplete upload
+        #
+        # @param [Hurley::Client] client
+        #   HTTP client
+        # @return [Hurley::Response]
+        # @raise [Google::Apis::ServerError] Unable to send the request
+        def send_query_command(client)
+          logger.debug { sprintf('Sending upload query command to %s', @upload_url) }
+          client.post(@upload_url, nil) do |req|
+            apply_request_options(req)
+            req.header[UPLOAD_COMMAND_HEADER] = QUERY_COMMAND
+          end
+        end
+
+        # Send the actual content
+        #
+        # @param [Hurley::Client] client
+        #   HTTP client
+        # @return [Hurley::Response]
+        # @raise [Google::Apis::ServerError] Unable to send the request
+        def send_upload_command(client)
+          logger.debug { sprintf('Sending upload command to %s', @upload_url) }
+          content = upload_io
+          content.pos = @offset
+          client.post(@upload_url, content) do |req|
+            apply_request_options(req)
+            req.header[UPLOAD_COMMAND_HEADER] = UPLOAD_COMMAND
+            req.header[UPLOAD_OFFSET_HEADER] = @offset.to_s
+          end
+        end
+
+        # Execute the upload request once. This will typically perform two HTTP requests -- one to initiate or query
+        # for the status of the upload, the second to send the (remaining) content.
+        #
+        # @private
+        # @param [Hurley::Client] client
+        #   HTTP client
+        # @yield [result, err] Result or error if block supplied
+        # @return [Object]
+        # @raise [Google::Apis::ServerError] An error occurred on the server and the request can be retried
+        # @raise [Google::Apis::ClientError] The request is invalid and should not be retried without modification
+        # @raise [Google::Apis::AuthorizationError] Authorization is required
+        def execute_once(client, &block)
+          case @state
+          when :start
+            response = send_start_command(client)
+            result = process_response(response.status_code, response.header, response.body)
+          when :active
+            response = send_query_command(client)
+            result = process_response(response.status_code, response.header, response.body)
+          when :cancelled, :final
+            error(@last_error, rethrow: true, &block)
+          end
+          if @state == :active
+            response = send_upload_command(client)
+            result = process_response(response.status_code, response.header, response.body)
+          end
+
+          success(result, &block) if @state == :final
+        rescue => e
+          # Some APIs like Youtube generate non-retriable 401 errors and mark
+          # the upload as finalized. Save the error just in case we get
+          # retried.
+          @last_error = e
+          error(e, rethrow: true, &block)
+        end
+      end
+    end
+  end
+end