Class: Camdram::HTTP

Inherits:
Object
  • Object
show all
Extended by:
Multiton
Defined in:
lib/camdram/http.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(key) ⇒ HTTP

Returns a new instance of HTTP.


14
# File 'lib/camdram/http.rb', line 14

def initialize(key); end

Instance Attribute Details

#access_tokenObject (readonly)

Returns the value of attribute access_token.


12
13
14
# File 'lib/camdram/http.rb', line 12

def access_token
  @access_token
end

#modeObject (readonly)

Returns the value of attribute mode.


12
13
14
# File 'lib/camdram/http.rb', line 12

def mode
  @mode
end

Instance Method Details

#access_token_expiring_soon?Boolean

Returns true if the access token is expiring in the next 30 seconds

Returns:

  • (Boolean)

111
112
113
114
115
116
117
# File 'lib/camdram/http.rb', line 111

def access_token_expiring_soon?
  # If setup in read-only mode then just return immediately
  return false if (@access_token.token == "")
  # By default, Camdram access tokens are valid for one hour.
  # We factor in a thirty second safety margin.
  Time.now.to_i + 30 >= @access_token.expires_at if @access_token
end

#auth_code(token_hash, app_id, app_secret, &block) ⇒ Object

Setup the API backend to use the authorisation code OAuth2 strategy

Parameters:

  • token_hash (Hash)

    A hash of the access token, refresh token and expiry Unix time.

  • app_id (String)

    The API client application identifier.

  • app_secret (String)

    The API client application secret.

  • block (Proc)

    The Faraday connection builder.


44
45
46
47
48
49
# File 'lib/camdram/http.rb', line 44

def auth_code(token_hash, app_id, app_secret, &block)
  self.client_credentials(app_id, app_secret, &block)
  @access_token = OAuth2::AccessToken.from_hash(@client, token_hash)
  @mode = :auth_code
  nil
end

#base_urlString

Returns the root URL that each API request is sent to

Returns:

  • (String)

    The hostname & protocol to send API requests to.


79
80
81
# File 'lib/camdram/http.rb', line 79

def base_url
  @client.site
end

#base_url=(url) ⇒ String

Sets the API URL that each HTTP request is sent to

Parameters:

  • url (String)

    The API hostname to send requests to.

Returns:

  • (String)

    The url itself.


72
73
74
# File 'lib/camdram/http.rb', line 72

def base_url=(url)
  @client.site = url
end

#client_credentials(app_id, app_secret, &block) ⇒ Object

Setup the API backend to use the client credentials OAuth2 strategy

Parameters:

  • app_id (String)

    The API client application identifier.

  • app_secret (String)

    The API client application secret.

  • block (Proc)

    The Faraday connection builder.


21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
# File 'lib/camdram/http.rb', line 21

def client_credentials(app_id, app_secret, &block)
  opts = { site: ::Camdram.base_url,
    authorize_url: "/oauth/v2/auth",
    token_url: "/oauth/v2/token",
    connection_opts: {
      headers: {
        user_agent: "Camdram Ruby v#{Camdram.version}"
      }
    },
    max_redirects: 3
  }
  @client = ::OAuth2::Client.new(app_id, app_secret, opts, &block)
  @access_token = nil
  @mode = :client_credentials
  nil
end

#disable_auto_token_renewalObject

Disables automatic renewal of expired API access tokens.


84
85
86
# File 'lib/camdram/http.rb', line 84

def disable_auto_token_renewal
  @auto_renew_disabled = true
end

#get(url_slug) ⇒ OAuth2::Response

Sends a HTTP-get request to the Camdram API

Parameters:

  • url_slug (String)

    The URL slug to send the request to.

Returns:

  • (OAuth2::Response)

    The OAuth2 response object from the Camdram API.

Raises:


92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
# File 'lib/camdram/http.rb', line 92

def get(url_slug)
  raise Camdram::Error::Misconfigured.new('Camdram OAuth client not setup correctly') unless @client
  if (!@access_token && @mode == :client_credentials)
    handle_exceptions do
      @access_token = @client.client_credentials.get_token
    end
  end
  if !@auto_renew_disabled && access_token_expiring_soon?
    warn 'refreshing expired access token' unless @mode == :client_credentials
    self.refresh!
  end
  handle_exceptions do
    @access_token.get(url_slug, parse: :json)
  end
end

#handle_exceptionsObject


134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
# File 'lib/camdram/http.rb', line 134

def handle_exceptions
  begin
    yield
  rescue OAuth2::Error => e
    raise Camdram::Error::GenericException.new, e unless e.code.is_a? Hash
    http_status = e.code['code']
    raise Camdram::Error::GenericException.new, e unless http_status.is_a? Integer
    if http_status.between?(400, 499)
      raise Camdram::Error::ClientError.new, e
    elsif http_status.between?(500, 599)
      raise Camdram::Error::ServerError.new, e
    else
      raise Camdram::Error::GenericException.new, e
    end
  rescue Faraday::TimeoutError => e
    raise Camdram::Error::Timeout.new, e
  rescue Faraday::ConnectionFailed => e
    if e.wrapped_exception.class == Net::OpenTimeout
      raise Camdram::Error::Timeout.new, e
    else
      raise Camdram::Error::GenericException.new, e
    end
  rescue => e
    raise Camdram::Error::GenericException.new, e
  end
end

#refresh!OAuth2::AccessToken

Refreshes the Camdram OAuth access token

Returns:

  • (OAuth2::AccessToken)

    The new access token.


122
123
124
125
126
127
128
129
130
131
132
# File 'lib/camdram/http.rb', line 122

def refresh!
  handle_exceptions do
    if (@mode == :client_credentials)
      new_token = @client.client_credentials.get_token
      @access_token = new_token
    else
      new_token = @access_token.refresh!
      @access_token = new_token
    end
  end
end

#user_agentString

Returns the user agent HTTP header sent with each API request

Returns:

  • (String)

    The user agent header to send with API requests.


64
65
66
# File 'lib/camdram/http.rb', line 64

def user_agent
  @client.options[:connection_opts][:headers][:user_agent]
end

#user_agent=(agent) ⇒ String

Sets the user agent header sent in each HTTP request

Parameters:

  • agent (String)

    The user agent header to send with HTTP requests.

Returns:

  • (String)

    The agent string itself.


55
56
57
58
59
# File 'lib/camdram/http.rb', line 55

def user_agent=(agent)
  @client.connection = nil
  @client.options[:connection_opts] = {headers: {user_agent: agent}}
  agent
end