class Transloadit::Request

Wraps requests to the Transloadit API. Ensures all API requests return a parsed Transloadit::Response, and abstracts away finding a lightly-used instance on startup.

Constants

API_ENDPOINT

The default Transloadit API endpoint.

API_HEADERS

The default headers to send to the API.

HMAC_ALGORITHM

The HMAC algorithm used for calculation request signatures.

Attributes

secret[RW]

@return [String] the authentication secret to sign the request with

url[RW]

@return [String] the API endpoint for the request

Public Class Methods

new(url, secret = nil) click to toggle source

Prepares a request against an endpoint URL, optionally with an encryption secret. If only a path is passed, the API will automatically determine the best server to use. If a full URL is given, the host provided will be used.

@param [String] url the API endpoint @param [String] secret an optional secret with which to sign the request

# File lib/transloadit/request.rb, line 36
def initialize(url, secret = nil)
  self.url    = URI.parse(url.to_s)
  self.secret = secret
end

Private Class Methods

_hmac(key, message) click to toggle source

Computes an HMAC digest from the key and message.

@param [String] key the secret key to sign with @param [String] message the message to sign @return [String] the signature of the message

# File lib/transloadit/request.rb, line 194
def self._hmac(key, message)
  OpenSSL::HMAC.hexdigest HMAC_ALGORITHM, key, message
end

Public Instance Methods

delete(payload = {}) click to toggle source

Performs an HTTP DELETE to the request's URL. Takes an optional hash containing the form-encoded payload.

@param [Hash] payload the payload to form-encode along with the POST @return [Transloadit::Response] the response

# File lib/transloadit/request.rb, line 61
def delete(payload = {})
  self.request! do
    options = {:payload => self.to_payload(payload)}
    self.api(options = options)[url.path].delete(API_HEADERS)
  end
end
get(params = {}) click to toggle source

Performs an HTTP GET to the request's URL. Takes an optional hash of query params.

@param [Hash] params additional query parameters @return [Transloadit::Response] the response

# File lib/transloadit/request.rb, line 48
def get(params = {})
  self.request! do
    self.api[url.path + self.to_query(params)].get(API_HEADERS)
  end
end
inspect() click to toggle source

@return [String] a human-readable version of the prepared Request

# File lib/transloadit/request.rb, line 97
def inspect
  self.url.to_s.inspect
end
post(payload = {}) click to toggle source

Performs an HTTP POST to the request's URL. Takes an optional hash containing the form-encoded payload.

@param [Hash] payload the payload to form-encode along with the POST @return [Transloadit::Response] the response

# File lib/transloadit/request.rb, line 75
def post(payload = {})
  self.request! do
    self.api[url.path].post(self.to_payload(payload), API_HEADERS)
  end
end
put(payload = {}) click to toggle source

Performs an HTTP PUT to the request's URL. Takes an optional hash containing the form-encoded payload.

@param [Hash] payload the payload to form-encode along with the POST @return [Transloadit::Response] the response

# File lib/transloadit/request.rb, line 88
def put(payload = {})
  self.request! do
    self.api[url.path].put(self.to_payload(payload), API_HEADERS)
  end
end

Protected Instance Methods

api(options = {}) click to toggle source

Retrieves the current API endpoint. If the URL of the request contains a hostname, then the hostname is used as the base endpoint of the API. Otherwise uses the class-level API base.

@return [RestClient::Resource] the API endpoint for this instance

# File lib/transloadit/request.rb, line 112
def api(options = {})
  @api ||= begin
    case self.url.host
      when String then RestClient::Resource.new(self.url.host, options = options)
      else RestClient::Resource.new(API_ENDPOINT.host, options = options)
    end
  end
end
request!(&request) click to toggle source

Wraps a request's results in a Transloadit::Response, even if an exception is raised by RestClient.

# File lib/transloadit/request.rb, line 168
def request!(&request)
  Transloadit::Response.new request.call
rescue RestClient::Exception => e
  Transloadit::Response.new e.response
end
signature(params) click to toggle source

Computes the HMAC digest of the params hash, if a secret was given to the instance.

@param [String] params the JSON encoded payload to sign @return [String] the HMAC signature for the params

# File lib/transloadit/request.rb, line 181
def signature(params)
  self.class._hmac(self.secret, params) if self.secret.to_s.length > 0
end
to_payload(payload = nil) click to toggle source

Updates the POST payload passed to be compliant with the Transloadit API spec. JSONifies the value for the params key and signs the request with the instance's secret if it exists.

@param [Hash] the payload to update @return [Hash] the Transloadit-compliant POST payload

# File lib/transloadit/request.rb, line 129
def to_payload(payload = nil)
  return {} if payload.nil?
  return {} if payload.respond_to?(:empty?) and payload.empty?

  # TODO: refactor this, don't update a hash that's not ours
  payload.update :params    => MultiJson.dump(payload[:params])
  payload.update :signature => self.signature(payload[:params])
  payload.delete :signature if payload[:signature].nil?
  payload
end
to_query(params = nil) click to toggle source

Updates the GET/DELETE params hash to be compliant with the Transloadit API by URI escaping and encoding the params hash, and attaching a signature.

@param [Hash] params the params to encode @return [String] the URI-encoded and escaped query parameters

# File lib/transloadit/request.rb, line 148
def to_query(params = nil)
  return '' if params.nil?
  return '' if params.respond_to?(:empty?) and params.empty?

  escape    = Regexp.new("[^#{URI::PATTERN::UNRESERVED}]")
  params_in_json = MultiJson.dump(params)
  uri_params = URI.escape(params_in_json, escape)

  params    = {
    :params    => uri_params,
    :signature => self.signature(params_in_json)
  }

  '?' + params.map {|k,v| "#{k}=#{v}" if v }.compact.join('&')
end