Class: Ruqqus::Token

Inherits:
Object
  • Object
show all
Defined in:
lib/ruqqus/token.rb

Overview

Represents a Ruqqus OAuth2 access token.

Constant Summary collapse

REFRESH_THRESHOLD =

The minimum number of seconds that can remain before the token refreshes itself.

60

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client_id, client_secret, code, persist = true) ⇒ Token

Grants access to a user account and returns an a newly created Ruqqus::Token to use as authentication for it.

Parameters:

  • client_id (String) —

    the ID of client application.

  • client_secret (String) —

    the secret of the client application.

  • code (String) —

    the code received in the redirect response when the user requested API access.

  • persist (Boolean) (defaults to: true) —

    true if token will be reusable, otherwise false.

Raises:



40
41
42
43
44
45
46
47
 
# File 'lib/ruqqus/token.rb', line 40

def initialize(client_id, client_secret, code, persist = true)
  headers = { 'User-Agent': Client::USER_AGENT, 'Accept': 'application/json', 'Content-Type': 'application/json' }
  params = { code: code, client_id: client_id, client_secret: client_secret, grant_type: 'code', permanent: persist }
  resp = RestClient.post('https://ruqqus.com/oauth/grant', params, headers )
  @data = JSON.parse(resp.body, symbolize_names: true)

  raise(Ruqqus::Error, 'failed to grant access for token') if @data[:oauth_error]
end

Instance Attribute Details

#access_token ⇒ String (readonly)

Returns the access token value.

Returns:

  • (String) —

    the access token value.




# File 'lib/ruqqus/token.rb', line 11

#expires ⇒ Time (readonly)

Returns the time the token expires and will require a refresh.

Returns:

  • (Time) —

    the time the token expires and will require a refresh.




# File 'lib/ruqqus/token.rb', line 19

#refresh_token ⇒ String (readonly)

Returns the refresh token value.

Returns:

  • (String) —

    the refresh token value.




# File 'lib/ruqqus/token.rb', line 15

#scopes ⇒ Array<Symbol> (readonly)

Returns an array of scopes this token authorizes.

Returns:

  • (Array<Symbol>) —

    an array of scopes this token authorizes.




# File 'lib/ruqqus/token.rb', line 27

#type ⇒ String (readonly)

Returns the token type to specify in the HTTP header.

Returns:

  • (String) —

    the token type to specify in the HTTP header.




# File 'lib/ruqqus/token.rb', line 23

Class Method Details

.from_json(payload) ⇒ Object

Loads the object from a JSON-formatted string.

Parameters:

  • json (String, Hash) —

    a JSON string representing the object, or the parsed Hash of the JSON (symbol keys).

Returns:

  • (Object) —

    the loaded object.



128
129
130
131
132
133
 
# File 'lib/ruqqus/token.rb', line 128

def self.from_json(payload)
  data = payload.is_a?(Hash) ? payload: JSON.parse(payload, symbolize_names: true)
  token = allocate
  token.instance_variable_set(:@data, data)
  token
end

.load_json(filename) ⇒ Token

Loads a token in JSON format from a file.

Parameters:

  • filename (String) —

    the path to a file where the token is written to.

Returns:



118
119
120
 
# File 'lib/ruqqus/token.rb', line 118

def self.load_json(filename)
  from_json(File.read(filename))
end

Instance Method Details

#expired? ⇒ Boolean

Returns true if token is expired, otherwise false.

Returns:

  • (Boolean) —

    true if token is expired, otherwise false.



86
87
88
 
# File 'lib/ruqqus/token.rb', line 86

def expired?
  expires <= Time.now
end

#need_refresh? ⇒ Boolean

Returns true if remaining lifetime is within the REFRESH_THRESHOLD, otherwise false.

Returns:

  • (Boolean) —

    true if remaining lifetime is within the REFRESH_THRESHOLD, otherwise false.



92
93
94
 
# File 'lib/ruqqus/token.rb', line 92

def need_refresh?
  (expires - Time.now) < REFRESH_THRESHOLD
end

#refresh(client_id, client_secret) ⇒ void

This method returns an undefined value.

Refreshes the access token and resets its time of expiration.

Raises:



73
74
75
76
77
78
79
80
81
82
 
# File 'lib/ruqqus/token.rb', line 73

def refresh(client_id, client_secret)
  headers = { 'User-Agent': Client::USER_AGENT, Authorization: "Bearer #{access_token}" }
  params = { client_id: client_id, client_secret: client_secret, refresh_token: refresh_token, grant_type: 'refresh' }
  resp = RestClient.post('https://ruqqus.com/oauth/grant', params, headers )

  data = JSON.parse(resp.body, symbolize_names: true)
  raise(Ruqqus::Error, 'failed to refresh authentication token') unless resp.code == 200 || data[:oauth_error]
  @data.merge!(data)
  sleep(1) # TODO: Test. Get internment 401 error when token needs refreshed
end

#save_json(filename) ⇒ Integer

Note:

Security Alert: The token is essentially the equivalent to login credentials in regards to security, so it is important to not share or store it somewhere that it can be easily compromised.

Saves this token in JSON format to the specified file.

Parameters:

  • filename (String) —

    the path to a file where the token will be written to.

Returns:

  • (Integer) —

    the number of bytes written.



109
110
111
 
# File 'lib/ruqqus/token.rb', line 109

def save_json(filename)
  File.open(filename, 'wb') { |io| io.write(to_json) }
end

#to_json(*_unused_) ⇒ String

Returns the object as a JSON-formatted string.

Returns:

  • (String) —

    the object as a JSON-formatted string.



98
99
100
 
# File 'lib/ruqqus/token.rb', line 98

def to_json(*_unused_)
  @data.to_json
end