akamai_api 0.2.0 → 0.3.0

data/lib/akamai_api/ccu/error.rb

@@ -0,0 +1,38 @@
+require "akamai_api/error"
+
+module AkamaiApi::CCU
+  # Error received after a request done through the Akamai CCU interface.
+  class Error < AkamaiApi::Error
+    # @return [Hash<String, Object>] raw Raw object describing the error.
+    attr_reader :raw
+
+    # @param [Hash<String, Object>] raw Raw object describing the error.
+    def initialize raw
+      @raw = raw
+      super raw['title'] || raw['detail']
+    end
+
+    # @return [String] Reference provided to Customer Care when needed.
+    def support_id
+      raw['supportId']
+    end
+
+    # @return [String] Specific detail about the error
+    def detail
+      raw['detail']
+    end
+
+    alias_method :title, :message
+
+    # @return [Fixnum] Response HTTP Status Code describing the error
+    def code
+      raw['httpStatus']
+    end
+    alias_method :http_status, :code
+
+    # @return [String] URI pointing to a verbose error description
+    def described_by
+      raw['describedBy']
+    end
+  end
+end

data/lib/akamai_api/ccu/purge/request.rb

@@ -1,4 +1,19 @@
-module AkamaiApi::Ccu::Purge
+require "httparty"
+
+require 'active_support'
+require 'active_support/core_ext/array'
+
+require "akamai_api/unauthorized"
+require "akamai_api/ccu/unrecognized_option"
+require "akamai_api/ccu/purge/response"
+
+module AkamaiApi::CCU::Purge
+  # {AkamaiApi::CCU::Purge} encapsulates the behavior needed to purge a resource from Akamai via CCU.
+  #
+  # @example Remove a single ARL
+  #     AkamaiApi::CCU::Purge::Request.new.execute('http://foo.bar/t.txt')
+  # @example Invalidate multiple CPCodes
+  #     AkamaiApi::CCU::Purge::Request.new(:invalidate, :cpcode).execute(12345, 12346)
   class Request
     include HTTParty
     format :json
@@ -7,37 +22,64 @@ module AkamaiApi::Ccu::Purge
 
     attr_reader :type, :action, :domain
 
-    def initialize action = 'remove', type = 'arl', args = {}
+    # @param [String] action type of clean action. See {#action} for allowed values
+    # @param [String] type resource type. See {#type} for allowed values
+    # @param [Hash<Symbol, String>] args   optional arguments
+    # @option args [String] :domain (:production) Domain type. See {#domain} for allowed values
+    def initialize action = :remove, type=:arl, args = {}
       self.action = action
       self.type   = type
-      self.domain = args[:domain] || 'production'
+      self.domain = args[:domain] || :production
     end
 
+    # @!attribute [rw] action
+    #   Clean action type.
+    #   @return [:invalidate] when you want to simply mark resources as invalid
+    #   @return [:remove] when you want to force resources removal
+    #   @raise [AkamaiApi::CCU::UnrecognizedOption] if an invalid value is provided
     def action= value
       raise_unrecognized_action(value) unless valid_action?(value)
       @action = value
     end
 
+    # @!attribute [rw] type
+    #   Resource type.
+    #   @return [:cpcode] when request targets entire CPCode(s)
+    #   @return [:arl] when request targets single ARL(s)
+    #   @raise [AkamaiApi::CCU::UnrecognizedOption] if an invalid value is provided
     def type= value
       raise_unrecognized_type(value) unless valid_type?(value)
       @type = value
     end
 
+    # @!attribute [rw] domain
+    #   Domain type to target.
+    #   @return [:production] production environment
+    #   @return [:staging] staging environment
+    #   @raise [AkamaiApi::CCU::UnrecognizedOption] if an invalid value is provided
     def domain= value
       raise_unrecognized_domain(value) unless valid_domain?(value)
       @domain = value
     end
 
+    # Clean the requested resources.
+    # @param [Array<String>] items One or more resources to clean
+    # @return [Response] an object representing the received response
+    # @raise [AkamaiApi::CCU::Error] when there is an error in the request
+    # @raise [AkamaiApi::Unauthorized] when login credentials are invalid
+    # @example Clean a single resource
+    #   request.execute 'http://foo.bar/t.txt'
+    # @example Clean multiple resources
+    #   request.execute '12345', '12346'
     def execute *items
       items = Array.wrap(items.first) if items.length == 1
-      response = self.class.post('/', basic_auth: auth, body: request_body(items))
+      response = self.class.post('/', basic_auth: AkamaiApi.auth, body: request_body(items))
       parse_response response
     end
 
-    def auth
-      AkamaiApi::Ccu.auth
-    end
-
+    # Request body to send to the API.
+    # @param [Array<String>] items resources to clean
+    # @return [String] request body in JSON format
     def request_body items
       { type: type, action: action, domain: domain, objects: items }.to_json
     end
@@ -46,19 +88,20 @@ module AkamaiApi::Ccu::Purge
 
     def parse_response response
       raise ::AkamaiApi::Unauthorized if response.code == 401
+      raise AkamaiApi::CCU::Error.new response.parsed_response unless successful_response? response
       Response.new response.parsed_response
     end
 
     def raise_unrecognized_action bad_action
-      raise ::AkamaiApi::Ccu::UnrecognizedOption, "Unknown action '#{bad_action}' (allowed values: invalidate, remove)"
+      raise ::AkamaiApi::CCU::UnrecognizedOption, "Unknown action '#{bad_action}' (allowed values: invalidate, remove)"
     end
 
     def raise_unrecognized_type bad_type
-      raise ::AkamaiApi::Ccu::UnrecognizedOption, "Unknown type '#{bad_type}' (allowed values: arl, cpcode)"
+      raise ::AkamaiApi::CCU::UnrecognizedOption, "Unknown type '#{bad_type}' (allowed values: arl, cpcode)"
     end
 
     def raise_unrecognized_domain bad_domain
-      raise ::AkamaiApi::Ccu::UnrecognizedOption, "Unknown domain '#{bad_domain}' (allowed_values: production, staging)"
+      raise ::AkamaiApi::CCU::UnrecognizedOption, "Unknown domain '#{bad_domain}' (allowed_values: production, staging)"
     end
 
     def valid_action? action
@@ -72,5 +115,9 @@ module AkamaiApi::Ccu::Purge
     def valid_domain? domain
       %w(production staging).include? domain.to_s
     end
+
+    def successful_response? response
+      (200...300).include? response.parsed_response['httpStatus']
+    end
   end
 end

data/lib/akamai_api/ccu/purge/response.rb

@@ -1,31 +1,37 @@
-module AkamaiApi::Ccu::Purge
-  class Response < ::AkamaiApi::Ccu::Response
-    def described_by
-      raw['describedBy']
-    end
-
-    def title
-      raw['title']
-    end
+require "akamai_api/ccu/base_response"
 
+module AkamaiApi::CCU::Purge
+  # This class represents the response received after a successful purge request
+  class Response < AkamaiApi::CCU::BaseResponse
+    # @return [Fixnum] Suggested time to wait (in seconds) before asking the status again
     def time_to_wait
       raw['pingAfterSeconds']
     end
+    alias_method :ping_after_seconds, :time_to_wait
 
+    # Purge Request identifier
+    # @return [String] Purge Request identifier
     def purge_id
       raw['purgeId']
     end
 
+    # Message detailing the response
+    # @return [String] message detailing the response.
     def message
       raw['detail']
     end
+    alias_method :detail, :message
 
+    # @return [Fixnum] Estimated time (in seconds) for the operation to be completed
     def estimated_time
       raw['estimatedSeconds']
     end
+    alias_method :estimated_seconds, :estimated_time
 
+    # @return [String] URI to use to check the status of the request
     def uri
       raw['progressUri']
     end
+    alias_method :progress_uri, :uri
   end
 end

data/lib/akamai_api/ccu/purge.rb

@@ -1,5 +1,16 @@
-require File.expand_path '../purge/request', __FILE__
-require File.expand_path '../purge/response', __FILE__
+require "akamai_api/ccu/purge/request"
 
-module AkamaiApi::Ccu::Purge
+# This module encapsulates classes aiming to purge resources using the Akamai CCU interface.
+#
+# @example Handling a purge response
+#   begin
+#     req = AkamaiApi::CCU::Purge::Request.new
+#     res = req.execute 'http://foo.bar/a.txt', 'http://www.foo.bar/a.txt'
+#     puts "Request #{res.purge_id} was successful (#{res.message})"
+#   rescue AkamaiApi::CCU::Error
+#     puts "Error #{$!.code} - #{$!.message}"
+#   rescue AkamaiApi::Unauthorized
+#     puts "Invalid login"
+#   end
+module AkamaiApi::CCU::Purge
 end

data/lib/akamai_api/ccu/purge_status/not_found.rb

@@ -0,0 +1,18 @@
+require "akamai_api/ccu/error"
+
+module AkamaiApi::CCU::PurgeStatus
+  # {NotFound} is raised when the requested resource cannot be found
+  class NotFound < AkamaiApi::CCU::Error
+    # @return [String] URI to use to check the status of the request
+    def progress_uri
+      raw['progressUri']
+    end
+    alias_method :uri, :progress_uri
+
+    # @return [Fixnum] Suggested time to wait (in seconds) before asking the status again
+    def time_to_wait
+      raw['pingAfterSeconds']
+    end
+    alias_method :ping_after_seconds, :time_to_wait
+  end
+end

data/lib/akamai_api/ccu/purge_status/request.rb

@@ -1,23 +1,53 @@
-module AkamaiApi::Ccu::PurgeStatus
+require "httparty"
+
+require "akamai_api/unauthorized"
+require "akamai_api/ccu/error"
+require "akamai_api/ccu/purge_status/response"
+require "akamai_api/ccu/purge_status/not_found"
+
+module AkamaiApi::CCU::PurgeStatus
+  # {Request} is used to check the status of a purge request using Akamai CCU.
+  #
+  # @example Check using {AkamaiApi::CCU::Purge::Response#purge_id}
+  #     purge_id # => "12345678-1234-5678-1234-123456789012"
+  #     AkamaiApi::CCU::PurgeStatus::Request.execute(purge_id)
+  # @example Check using {AkamaiApi::CCU::Purge::Response#progress_uri}
+  #     progress_uri # => "/CCU/v2/purges/12345678-1234-5678-1234-123456789012"
+  #     AkamaiApi::CCU::PurgeStatus::Request.execute(progress_uri)
   class Request
     include HTTParty
     format :json
     base_uri 'https://api.ccu.akamai.com'
 
-    def execute progress_uri
-      response = self.class.get normalize_progress_uri(progress_uri), basic_auth: auth
-      parse_response response
+    # Checks the status of the requested associated with the given argument
+    # @param [String] purge_id_or_progress_uri a purge request ID or URI
+    # @return [Response] an object detailing the response
+    # @raise [AkamaiApi::CCU::PurgeStatus::NotFound] when the request cannot be found
+    # @raise [AkamaiApi::CCU::Error] when there is an error in the request
+    # @raise [AkamaiApi::Unauthorized] when login credentials are invalid
+    def self.execute purge_id_or_progress_uri
+      new.execute purge_id_or_progress_uri
     end
 
-    def auth
-      AkamaiApi::Ccu.auth
+    # Checks the status of the requested associated with the given argument
+    # @return [Response] an object detailing the response
+    # @raise [AkamaiApi::CCU::PurgeStatus::NotFound] when the request cannot be found
+    # @raise [AkamaiApi::CCU::Error] when there is an error in the request
+    # @raise [AkamaiApi::Unauthorized] when login credentials are invalid
+    def execute purge_id_or_progress_uri
+      purge_id_or_progress_uri = normalize_progress_uri purge_id_or_progress_uri
+      response = self.class.get purge_id_or_progress_uri, basic_auth: AkamaiApi.auth
+      parse_response response
     end
 
     private
 
     def parse_response response
       raise AkamaiApi::Unauthorized if response.code == 401
-      AkamaiApi::Ccu::PurgeStatus.build_response response.parsed_response
+      parsed = response.parsed_response
+      raise AkamaiApi::CCU::Error.new parsed unless successful_response? parsed
+      raise AkamaiApi::CCU::PurgeStatus::NotFound.new parsed unless parsed['submissionTime']
+      AkamaiApi::CCU::PurgeStatus::Response.new(parsed)
     end
 
     def normalize_progress_uri progress_uri
@@ -28,5 +58,9 @@ module AkamaiApi::Ccu::PurgeStatus
         "/ccu/v2/purges#{progress_uri}"
       end
     end
+
+    def successful_response? parsed_response
+      (200...300).include? parsed_response['httpStatus']
+    end
   end
 end

data/lib/akamai_api/ccu/purge_status/response.rb

@@ -1,19 +1,65 @@
-module AkamaiApi::Ccu::PurgeStatus
-  class Response < ::AkamaiApi::Ccu::Response
+require "akamai_api/ccu/base_response"
+
+module AkamaiApi::CCU::PurgeStatus
+  # This class represents a successful response and details a purge request status
+  class Response < AkamaiApi::CCU::BaseResponse
+    # @return [String] URI to use to check the status of the request
     def progress_uri
       raw['progressUri']
     end
+    alias_method :uri, :progress_uri
 
+    # Purge Request identifier
+    # @return [String] Purge Request identifier
     def purge_id
       raw['purgeId']
     end
 
-    def status
+    # Status of the purge request
+    # @return ['In-Progress'] when the request is in progress
+    # @return ['Done'] when the request has been completed
+    # @return ['Unknown']
+    def purge_status
       raw['purgeStatus']
     end
+    alias_method :status, :purge_status
 
+    # @return [Fixnum] Suggested time to wait (in seconds) before asking the status again
     def time_to_wait
       raw['pingAfterSeconds']
     end
+    alias_method :ping_after_seconds, :time_to_wait
+
+    # @return [Fixnum] Estimated time (in seconds) for the operation to be completed, calculated when the request was submitted
+    def original_estimated_time
+      raw['originalEstimatedSeconds']
+    end
+    alias_method :original_estimated_seconds, :original_estimated_time
+
+    # @return [Fixnum] Number of jobs in queue, calculated when the request was submitted
+    def original_queue_length
+      raw['originalQueueLength']
+    end
+
+    # The time the request was completed
+    # @return [Time] the time the request was completed
+    # @return [nil] when the request has not been completed (= its status isn't 'Done')
+    def completed_at
+      raw['completionTime'] && Time.iso8601(raw['completionTime'])
+    end
+    alias_method :completion_time, :completed_at
+
+    # @return [String] The request author name
+    def submitted_by
+      raw['submittedBy']
+    end
+
+    # The time the request was accepted
+    # @return [Time] the time the request was accepted
+    # @return [nil] when the request is still not accepted (= its status is neither 'Done' nor 'In-Progress')
+    def submitted_at
+      raw['submissionTime'] && Time.iso8601(raw['submissionTime'])
+    end
+    alias_method :submission_time, :submitted_at
   end
 end

data/lib/akamai_api/ccu/purge_status.rb

@@ -1,10 +1,18 @@
-module AkamaiApi::Ccu::PurgeStatus
-  def self.build_response parsed_response
-    response_class = parsed_response['submittedBy'] ? SuccessfulResponse : NotFoundResponse
-    response_class.new parsed_response
-  end
-end
+require "akamai_api/ccu/purge_status/request"
 
-require File.expand_path '../purge_status/request', __FILE__
-require File.expand_path '../purge_status/successful_response', __FILE__
-require File.expand_path '../purge_status/not_found_response', __FILE__
+# This module encapsulates the classes you need to check the status of purge request
+# submitted using the Akamai CCU interface.
+#
+# @example Checking the status of a purge request
+#   purge_id_or_progress_uri # => "/CCU/v2/purges/12345678-1234-5678-1234-123456789012"
+#   begin
+#     res = AkamaiApi::CCU::PurgeStatus::Request.execute purge_id_or_progress_uri
+#     puts "Request status is '#{res.status}'"
+#     puts "Request has been completed on '#{res.completed_at}'" if res.completed_at
+#   rescue AkamaiApi::CCU::Error
+#     puts "Error #{$!.code} - #{$!.message}"
+#   rescue AkamaiApi::Unauthorized
+#     puts "Invalid login"
+#   end
+module AkamaiApi::CCU::PurgeStatus
+end

data/lib/akamai_api/ccu/status/request.rb

@@ -1,23 +1,36 @@
-module AkamaiApi::Ccu::Status
+require "httparty"
+require "akamai_api/unauthorized"
+require "akamai_api/ccu/status/response"
+
+module AkamaiApi::CCU::Status
+  # {Request} can be used to check the status of the Akamai CCU queue
   class Request
     include HTTParty
     format :json
     base_uri 'https://api.ccu.akamai.com/ccu/v2/queues/default'
 
+    # Checks the status of the Akamai CCU queue
+    # @return [Response] a response object describing the status of the Akamai CCU queue
+    # @raise [AkamaiApi::CCU::Error] when there is an error in the request
+    # @raise [AkamaiApi::Unauthorized] when login credentials are invalid
+    def self.execute
+      new.execute
+    end
+
+    # Checks the status of the Akamai CCU queue
+    # @return [Response] a response object describing the status of the Akamai CCU queue
+    # @raise [AkamaiApi::CCU::Error] when there is an error in the request
+    # @raise [AkamaiApi::Unauthorized] when login credentials are invalid
     def execute
-      response = self.class.get('/', basic_auth: auth)
+      response = self.class.get('/', basic_auth: AkamaiApi.auth)
       parse_response response
     end
 
     private
 
-    def auth
-      AkamaiApi::Ccu.auth
-    end
-
     def parse_response response
       raise AkamaiApi::Unauthorized if response.code == 401
-      AkamaiApi::Ccu::Status::Response.new response.parsed_response
+      AkamaiApi::CCU::Status::Response.new response.parsed_response
     end
   end
 end

data/lib/akamai_api/ccu/status/response.rb

@@ -1,11 +1,17 @@
-module AkamaiApi::Ccu::Status
-  class Response < ::AkamaiApi::Ccu::Response
+require "akamai_api/ccu/base_response"
+
+module AkamaiApi::CCU::Status
+  # This response class describes the status of the Akamai CCU Queue
+  class Response < AkamaiApi::CCU::BaseResponse
+    # @return [Fixnum] Number of jobs in queue
     def queue_length
       raw['queueLength']
     end
 
+    # @return [String] Message detailing the response
     def message
       raw['detail']
     end
+    alias_method :detail, :message
   end
 end

data/lib/akamai_api/ccu/status.rb

@@ -1,2 +1,13 @@
-require File.expand_path '../status/request', __FILE__
-require File.expand_path '../status/response', __FILE__
+require "akamai_api/ccu/status/request"
+
+# This module encapsulates the classes you need to check the status of the Akamai CCU queue,
+#
+# @example Checking the status of the Akamai CCU queue
+#   begin
+#     res = AkamaiApi::CCU::Status::Request.execute
+#     puts "There are #{res.queue_length} jobs in queue"
+#   rescue AkamaiApi::Unauthorized
+#     puts "Invalid login"
+#   end
+module AkamaiApi::CCU::Status
+end

data/lib/akamai_api/ccu/unrecognized_option.rb

@@ -0,0 +1,6 @@
+require "akamai_api/error"
+
+module AkamaiApi::CCU
+  # A simple subclass of {AkamaiApi::Error} representing an unrecognized option value provided to the CCU interface
+  class UnrecognizedOption < AkamaiApi::Error; end
+end