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.


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

def initialize(key); end

Instance Attribute Details

#access_tokenObject (readonly)

Returns the value of attribute access_token


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

def access_token
  @access_token
end

#modeObject (readonly)

Returns the value of attribute mode


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

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)

102
103
104
105
106
107
108
# File 'lib/camdram/http.rb', line 102

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.


39
40
41
42
43
44
# File 'lib/camdram/http.rb', line 39

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.


74
75
76
# File 'lib/camdram/http.rb', line 74

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.


67
68
69
# File 'lib/camdram/http.rb', line 67

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.


20
21
22
23
24
25
26
27
28
29
30
31
# File 'lib/camdram/http.rb', line 20

def client_credentials(app_id, app_secret, &block)
  @client = OAuth2::Client.new(app_id, app_secret,
    { 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
    }, &block)
  @access_token = nil
  @mode = :client_credentials
  nil
end

#disable_auto_token_renewalObject

Disables automatic renewal of expired API access tokens.


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

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:


87
88
89
90
91
92
93
94
95
96
97
# File 'lib/camdram/http.rb', line 87

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

#refresh!OAuth2::AccessToken

Refreshes the Camdram OAuth access token

Returns:

  • (OAuth2::AccessToken)

    The new access token.


113
114
115
116
117
118
119
120
121
# File 'lib/camdram/http.rb', line 113

def refresh!
  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

#user_agentString

Returns the user agent HTTP header sent with each API request

Returns:

  • (String)

    The user agent header to send with API requests.


59
60
61
# File 'lib/camdram/http.rb', line 59

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.


50
51
52
53
54
# File 'lib/camdram/http.rb', line 50

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