yt 0.12.2 → 0.13.0

data/lib/yt/actions/delete_all.rb

@@ -1,6 +1,6 @@
 # encoding: UTF-8
 require 'yt/actions/list'
-require 'yt/models/request'
+require 'yt/request'
 
 module Yt
   module Actions

data/lib/yt/actions/insert.rb

@@ -1,5 +1,6 @@
-require 'yt/models/request'
+require 'yt/request'
 require 'yt/actions/base'
+require 'yt/config'
 
 module Yt
   module Actions
@@ -9,20 +10,27 @@ module Yt
     private
 
       def do_insert(extra_insert_params = {})
-        request = Yt::Request.new insert_params.deep_merge(extra_insert_params)
-        response = request.run
+        response = insert_request(extra_insert_params).run
         @items = []
         new_item extract_data_from(response)
       end
 
+      def insert_request(params = {})
+        Yt::Request.new(insert_params.deep_merge params).tap do |request|
+          print "#{request.as_curl}\n" if Yt.configuration.developing?
+        end
+      end
+
       def insert_params
         path = "/youtube/v3/#{self.class.to_s.demodulize.camelize :lower}"
 
         {}.tap do |params|
           params[:path] = path
+          params[:host] = 'www.googleapis.com'
           params[:method] = :post
           params[:auth] = @auth
           params[:expected_response] = Net::HTTPOK
+          params[:api_key] = Yt.configuration.api_key if Yt.configuration.api_key
         end
       end
 

data/lib/yt/actions/list.rb

@@ -1,6 +1,7 @@
-require 'yt/models/request'
+require 'yt/request'
 require 'yt/models/iterator'
 require 'yt/errors/no_items'
+require 'yt/config'
 
 module Yt
   module Actions
@@ -9,7 +10,7 @@ module Yt
         :size, to: :list
 
       def first!
-        first.tap{|item| raise Errors::NoItems, last_request unless item}
+        first.tap{|item| raise Errors::NoItems, error_message unless item}
       end
 
     private
@@ -38,7 +39,7 @@ module Yt
       # iterate through all the pages, which can results in many requests.
       # To avoid this, +total_results+ is provided as a good size estimation.
       def total_results
-        response = request(list_params).run
+        response = list_request(list_params).run
         total_results = response.body.fetch('pageInfo', {})['totalResults']
         total_results ||= response.body.fetch(items_key, []).size
       end
@@ -87,18 +88,23 @@ module Yt
       end
 
       def fetch_page(params = {})
-        response = request(params).run
-        token = response.body['nextPageToken']
-        items = response.body.fetch items_key, []
+        @last_response = list_request(params).run
+        token = @last_response.body['nextPageToken']
+        items = @last_response.body.fetch items_key, []
         {items: items, token: token}
       end
 
-      def request(params = {})
-        @last_request = Yt::Request.new params
+      def list_request(params = {})
+        @list_request = Yt::Request.new(params).tap do |request|
+          print "#{request.as_curl}\n" if Yt.configuration.developing?
+        end
       end
 
-      def last_request
-        @last_request.request_error_message if @last_request
+      def error_message
+        {}.tap do |message|
+          message[:request_curl] = @list_request.as_curl
+          message[:response_body] = JSON(@last_response.body)
+        end.to_json if @list_request && @last_response
       end
 
       def list_params
@@ -106,9 +112,11 @@ module Yt
 
         {}.tap do |params|
           params[:method] = :get
+          params[:host] = 'www.googleapis.com'
           params[:auth] = @auth
           params[:path] = path
           params[:exptected_response] = Net::HTTPOK
+          params[:api_key] = Yt.configuration.api_key if Yt.configuration.api_key
         end
       end
 

data/lib/yt/actions/modify.rb

@@ -1,5 +1,6 @@
-require 'yt/models/request'
+require 'yt/request'
 require 'yt/actions/base'
+require 'yt/config'
 
 module Yt
   module Actions
@@ -10,18 +11,25 @@ module Yt
     private
 
       def do_modify(params = {})
-        request = Yt::Request.new params
-        response = request.run
+        response = modify_request(params).run
         yield response.body if block_given?
       end
 
+      def modify_request(params = {})
+        Yt::Request.new(params).tap do |request|
+          print "#{request.as_curl}\n" if Yt.configuration.developing?
+        end
+      end
+
       def modify_params
         path = "/youtube/v3/#{self.class.to_s.demodulize.pluralize.camelize :lower}"
 
         {}.tap do |params|
           params[:path] = path
           params[:auth] = @auth
+          params[:host] = 'www.googleapis.com'
           params[:expected_response] = Net::HTTPNoContent
+          params[:api_key] = Yt.configuration.api_key if Yt.configuration.api_key
         end
       end
     end

data/lib/yt/associations/has_authentication.rb

@@ -51,7 +51,7 @@ module Yt
 
       # Obtains a new access token.
       # Returns true if the new access token is different from the previous one
-      def refresh
+      def refreshed_access_token?
         old_access_token = authentication.access_token
         @authentication = @access_token = @refreshed_authentications = nil
         old_access_token != authentication.access_token

data/lib/yt/collections/annotations.rb

@@ -17,7 +17,7 @@ module Yt
       #   a video, so we use an "old-style" URL that YouTube still maintains.
       def list_params
         super.tap do |params|
-          params[:format] = :xml
+          params[:response_format] = :xml
           params[:host] = 'www.youtube.com'
           params[:path] = '/annotations_invideo'
           params[:params] = {video_id: @parent.id}
@@ -30,7 +30,9 @@ module Yt
       # @note Annotations overwrites +next_page+ since the list of annotations
       #   is not paginated API-style, but in its own custom way.
       def next_page
-        request = Yt::Request.new list_params
+        request = Yt::Request.new(list_params).tap do |request|
+          print "#{request.as_curl}\n" if Yt.configuration.developing?
+        end
         response = request.run
         @page_token = nil
 

data/lib/yt/collections/authentications.rb

@@ -17,7 +17,7 @@ module Yt
         super.tap do |params|
           params[:host] = 'accounts.google.com'
           params[:path] = '/o/oauth2/token'
-          params[:body_type] = :form
+          params[:request_format] = :form
           params[:method] = :post
           params[:auth] = nil
           params[:body] = auth_params
@@ -30,7 +30,9 @@ module Yt
       end
 
       def next_page
-        request = Yt::Request.new list_params
+        request = Yt::Request.new(list_params).tap do |request|
+          print "#{request.as_curl}\n" if Yt.configuration.developing?
+        end
         Array.wrap request.run.body
       rescue Yt::Error => error
         expected?(error) ? [] : raise(error)

data/lib/yt/collections/ownerships.rb

@@ -26,7 +26,7 @@ module Yt
       # @private
       # @note Ownerships overwrites +fetch_page+ since it’s a get.
       def fetch_page(params = {})
-        response = request(params).run
+        response = list_request(params).run
         {items: [response.body], token: nil}
       end
     end

data/lib/yt/collections/reports.rb

@@ -5,9 +5,17 @@ module Yt
     class Reports < Base
       attr_writer :metric
 
-      def within(days_range)
+      def within(days_range, try_again = true)
         @days_range = days_range
         Hash[*flat_map{|daily_value| daily_value}]
+      # NOTE: Once in a while, YouTube responds with 400 Error and the message
+      # "Invalid query. Query did not conform to the expectations."; in this
+      # case running the same query after one second fixes the issue. This is
+      # not documented by YouTube and hardly testable, but trying again the
+      # same query is a workaround that works and can hardly cause any damage.
+      # Similarly, once in while YouTube responds with a random 503 error.
+      rescue Yt::Error => e
+        try_again && rescue?(e) ? sleep(3) && within(days_range, false) : raise
       end
 
     private
@@ -47,6 +55,10 @@ module Yt
       def items_key
         'rows'
       end
+
+      def rescue?(error)
+        'badRequest'.in?(error.reasons) && error.to_s =~ /did not conform/
+      end
     end
   end
 end

data/lib/yt/collections/resumable_sessions.rb

@@ -18,12 +18,14 @@ module Yt
       # @option options [String] :title The video’s title.
       # @option options [String] :description The video’s description.
       # @option options [Array<String>] :title The video’s tags.
+      # @option options [Integer] :category_id The video’s category ID.
       # @option options [String] :privacy_status The video’s privacy status.
       def insert(content_length, options = {})
         @headers = headers_for content_length
         body = {}
 
-        snippet = options.slice :title, :description, :tags
+        snippet = options.slice :title, :description, :tags, :category_id
+        snippet[:categoryId] = snippet.delete(:category_id) if snippet[:category_id]
         body[:snippet] = snippet if snippet.any?
 
         status = options[:privacy_status]
@@ -40,7 +42,7 @@ module Yt
 
       def insert_params
         super.tap do |params|
-          params[:format] = nil
+          params[:response_format] = nil
           params[:path] = '/upload/youtube/v3/videos'
           params[:params] = {part: 'snippet,status', uploadType: 'resumable'}
         end

data/lib/yt/collections/user_infos.rb

@@ -22,7 +22,9 @@ module Yt
       # so @page_token has to be explcitly set to nil, and the result wrapped
       # in an Array.
       def next_page
-        request = Yt::Request.new list_params
+        request = Yt::Request.new(list_params).tap do |request|
+          print "#{request.as_curl}\n" if Yt.configuration.developing?
+        end
         response = request.run
         @page_token = nil
 

data/lib/yt/models/account.rb

@@ -9,7 +9,7 @@ module Yt
       # @!attribute [r] channel
       #   @return [Yt::Models::Channel] the account’s channel.
       has_one :channel
-      delegate :playlists, :create_playlist, :delete_playlists,
+      delegate :playlists, :delete_playlists,
         :subscribed_channels, to: :channel
 
       # @!attribute [r] user_info
@@ -42,6 +42,10 @@ module Yt
       #     by the account.
       has_many :content_owners
 
+      # @!attribute [r] playlists
+      #   @return [Yt::Collections::Playlists] the account’s playlists.
+      has_many :playlists
+
       # Uploads a video
       # @param [String] path_or_url the video to upload. Can either be the
       #   path of a local file or the URL of a remote file.
@@ -57,6 +61,10 @@ module Yt
         session.upload_video file
       end
 
+      def create_playlist(params = {})
+        playlists.insert params
+      end
+
       # @private
       # Tells `has_many :videos` that account.videos should return all the
       # videos *owned by* the account (public, private, unlisted).

data/lib/yt/models/channel.rb

@@ -131,10 +131,6 @@ module Yt
         end
       end
 
-      def create_playlist(params = {})
-        playlists.insert params
-      end
-
       def delete_playlists(attrs = {})
         playlists.delete_all attrs
       end

data/lib/yt/models/resource.rb

@@ -52,7 +52,7 @@ module Yt
       # @see https://developers.google.com/youtube/v3/docs/videos/update
       def update_params
         super.tap do |params|
-          params[:body_type] = :json
+          params[:request_format] = :json
           params[:expected_response] = Net::HTTPOK
         end
       end

data/lib/yt/models/resumable_session.rb

@@ -34,7 +34,7 @@ module Yt
       #   To be sure to include both cases, HTTPSuccess is used
       def update_params
         super.tap do |params|
-          params[:body_type] = :file
+          params[:request_format] = :file
           params[:host] = @uri.host
           params[:path] = @uri.path
           params[:expected_response] = Net::HTTPSuccess

data/lib/yt/request.rb

@@ -0,0 +1,267 @@
+require 'net/http' # for Net::HTTP.start
+require 'uri' # for URI.json
+require 'json' # for JSON.parse
+require 'active_support' # does not load anything by default  but is required
+require 'active_support/core_ext' # for Hash.from_xml, Hash.to_param
+
+require 'yt/errors/forbidden'
+require 'yt/errors/missing_auth'
+require 'yt/errors/request_error'
+require 'yt/errors/server_error'
+require 'yt/errors/unauthorized'
+
+module Yt
+  # A wrapper around Net::HTTP to send HTTP requests to any web API and
+  # return their result or raise an error if the result is unexpected.
+  # The basic way to use Request is by calling +run+ on an instance.
+  # @example List the most popular videos on YouTube.
+  #   host = ''www.googleapis.com'
+  #   path = '/youtube/v3/videos'
+  #   params = {chart: 'mostPopular', key: ENV['API_KEY'], part: 'snippet'}
+  #   response = Yt::Request.new(path: path, params: params).run
+  #   response.body['items'].map{|video| video['snippet']['title']}
+  #
+  class Request
+    # Initializes a Request object.
+    # @param [Hash] options the options for the request.
+    # @option options [String, Symbol] :method (:get) The HTTP method to use.
+    # @option options [Class] :expected_response (Net::HTTPSuccess) The class
+    #   of response that the request should obtain when run.
+    # @option options [String, Symbol] :response_format (:json) The expected
+    #   format of the response body. If passed, the response body will be
+    #   parsed according to the format before being returned.
+    # @option options [String] :host The host component of the request URI.
+    # @option options [String] :path The path component of the request URI.
+    # @option options [Hash] :params ({}) The params to use as the query
+    #   component of the request URI, for instance the Hash {a: 1, b: 2}
+    #   corresponds to the query parameters "a=1&b=2".
+    # @option options [Hash] :camelize_params (true) whether to transform
+    #   each key of params into a camel-case symbol before sending the
+    #   request. For instance, if set to true, the params {aBc: 1, d_e: 2,
+    #   'f' => 3} would be sent as {aBc: 1, dE: 2, f: 3}.
+    # @option options [Hash] :request_format (:json) The format of the
+    #   requesty body. If a request body is passed, it will be parsed
+    #   according to this format before sending it in the request.
+    # @option options [#size] :body The body component of the request.
+    # @option options [Hash] :headers ({}) The headers component of the
+    #   request.
+    # @option options [#access_token, #refreshed_access_token?] :auth The
+    #   authentication object. If set, must respond to +access_token+ and
+    #   return the OAuth token to make an authenticated request, and must
+    #   respond to +refreshed_access_token?+ and return whether the access
+    #   token can be refreshed if expired.
+    def initialize(options = {})
+      @method = options.fetch :method, :get
+      @expected_response = options.fetch :expected_response, Net::HTTPSuccess
+      @response_format = options.fetch :response_format, :json
+      @host = options[:host]
+      @path = options[:path]
+      @params = options.fetch :params, {}
+      # Note: This is to be invoked by auth-only YouTube APIs.
+      @params[:key] = options[:api_key] if options[:api_key]
+      # Note: This is to be invoked by all YouTube API except Annotations,
+      # Analyitics and Uploads
+      camelize_keys! @params if options.fetch(:camelize_params, true)
+      @request_format = options.fetch :request_format, :json
+      @body = options[:body]
+      @headers = options.fetch :headers, {}
+      @auth = options[:auth]
+    end
+
+    # Sends the request and returns the response.
+    # If the request fails once for a temporary server error or an expired
+    # token, tries the request again before eventually raising an error.
+    # @return [Net::HTTPResponse] if the request succeeds and matches the
+    #   expectations, the response with the body appropriately parsed.
+    # @raise [Yt::RequestError] if the request fails or the response does
+    #   not match the expectations.
+    def run
+      if matches_expectations?
+        response.tap{parse_response!}
+      elsif run_again?
+        run
+      else
+        raise response_error, error_message.to_json
+      end
+    end
+
+    # Returns the +cURL+ version of the request, useful to re-run the request
+    # in a shell terminal.
+    # @return [String] the +cURL+ version of the request.
+    def as_curl
+      'curl'.tap do |curl|
+        curl <<  " -X #{http_request.method}"
+        http_request.each_header{|k, v| curl << %Q{ -H "#{k}: #{v}"}}
+        curl << %Q{ -d '#{http_request.body}'} if http_request.body
+        curl << %Q{ "#{uri.to_s}"}
+      end
+    end
+
+  private
+
+    # @return [URI::HTTPS] the (memoized) URI of the request.
+    def uri
+      attributes = {host: @host, path: @path, query: @params.to_param}
+      @uri ||= URI::HTTPS.build attributes
+    end
+
+    # @return [Net::HTTPRequest] the full HTTP request object,
+    #   inclusive of headers of request body.
+    def http_request
+      net_http_class = "Net::HTTP::#{@method.capitalize}".constantize
+      @http_request ||= net_http_class.new(uri.request_uri).tap do |request|
+        set_request_body! request
+        set_request_headers! request
+      end
+    end
+
+    # Adds the request body to the request in the appropriate format.
+    # if the request body is a JSON Object, transform its keys into camel-case,
+    # since this is the common format for JSON APIs.
+    def set_request_body!(request)
+      case @request_format
+        when :json then request.body = (camelize_keys! @body).to_json
+        when :form then request.set_form_data @body
+        when :file then request.body_stream = @body
+      end if @body
+    end
+
+    # Destructively converts all the keys of hash to camel-case symbols.
+    # Note: This is to be invoked by all YouTube API except Accounts
+    def camelize_keys!(hash)
+      hash.keys.each do |key|
+        hash[key.to_s.camelize(:lower).to_sym] = hash.delete key
+      end if hash.is_a? Hash
+      hash
+    end
+
+    # Adds the request headers to the request in the appropriate format.
+    # The User-Agent header is also set to recognize the request, and to
+    # tell the server that gzip compression can be used, since Net::HTTP
+    # supports it and automatically sets the Accept-Encoding header.
+    def set_request_headers!(request)
+      case @request_format
+      when :json
+        request.initialize_http_header 'Content-Type' => 'application/json'
+        request.initialize_http_header 'Content-length' => '0' unless @body
+      when :file
+        request.initialize_http_header 'Content-Length' => @body.size.to_s
+        request.initialize_http_header 'Transfer-Encoding' => 'chunked'
+      end
+      @headers['User-Agent'] = 'Yt::Request (gzip)'
+      @headers['Authorization'] = "Bearer #{@auth.access_token}" if @auth
+      @headers.each{|name, value| request.add_field name, value}
+    end
+
+    # @return [Boolean] whether the class of response returned by running
+    #   the request matches the expected class of response.
+    def matches_expectations?
+      response.is_a? @expected_response
+    end
+
+    # Run the request and memoize the response or the server error received.
+    def response
+      @response ||= send_http_request
+    rescue *server_errors => e
+      @response ||= e
+    end
+
+    # Send the request to the server, allowing ActiveSupport::Notifications
+    # client to subscribe to the request.
+    def send_http_request
+      net_http_options = [uri.host, uri.port, use_ssl: true]
+      ActiveSupport::Notifications.instrument 'request.yt' do |payload|
+        payload[:method] = @method
+        payload[:request_uri] = uri
+        payload[:response] = Net::HTTP.start(*net_http_options) do |http|
+          http.request http_request
+        end
+      end
+    end
+
+    # Replaces the body of the response with the parsed version of the body,
+    # according to the format specified in the Request.
+    def parse_response!
+      response.body = case @response_format
+        when :xml then Hash.from_xml response.body
+        when :json then JSON response.body
+      end if response.body
+    end
+
+    # Returns whether it is worth to run a failed request again.
+    # There are two cases in which retrying a request might be worth:
+    # - when the server specifies that the request token has expired and
+    #   the user has to refresh the token in order to tryi again
+    # - when the server is unreachable, and waiting for a couple of seconds
+    #   might solve the connection issues.
+    def run_again?
+      refresh_token_and_retry? || server_error? && sleep_and_retry?
+    end
+
+    # Returns the list of server errors worth retrying the request once.
+    def server_errors
+      [
+        OpenSSL::SSL::SSLError,
+        Errno::ETIMEDOUT,
+        Errno::ENETUNREACH,
+        Errno::ECONNRESET,
+        Net::HTTPServerError
+      ]
+    end
+
+    # Sleeps for a while and returns true for the first +max_retries+ times,
+    # then returns false. Useful to try the same request again multiple
+    # times with a delay if a connection error occurs.
+    def sleep_and_retry?(max_retries = 1)
+      @retries_so_far ||= -1
+      @retries_so_far += 1
+      if (@retries_so_far < max_retries)
+        @response = @http_request = @uri = nil
+        sleep 3
+      end
+    end
+
+    # In case an authorized request responds with "Unauthorized", checks
+    # if the original access token can be refreshed. If that's the case,
+    # clears the memoized variables and returns true, so the request can
+    # be run again, otherwise raises an error.
+    def refresh_token_and_retry?
+      if unauthorized? && @auth && @auth.refreshed_access_token?
+        @response = @http_request = @uri = nil
+        true
+      end
+    rescue Errors::MissingAuth
+      false
+    end
+
+    # @return [Yt::RequestError] the error associated to the class of the
+    #   response.
+    def response_error
+      case response
+        when *server_errors then Errors::ServerError
+        when Net::HTTPUnauthorized then Errors::Unauthorized
+        when Net::HTTPForbidden then Errors::Forbidden
+        else Errors::RequestError
+      end
+    end
+
+    # @return [Boolean] whether the response matches any server error.
+    def server_error?
+      response_error == Errors::ServerError
+    end
+
+    # @return [Boolean] whether the request lacks proper authorization.
+    def unauthorized?
+      response_error == Errors::Unauthorized
+    end
+
+    # Return the elements of the request/response that are worth displaying
+    # as an error message if the request fails.
+    # If the response format is JSON, showing the parsed body is sufficient,
+    # otherwise the whole (inspected) response is worth looking at.
+    def error_message
+      response_body = JSON(response.body) rescue response.inspect
+      {request_curl: as_curl, response_body: response_body}
+    end
+  end
+end