Class: ConnectWise::Configuration

Inherits:
Object
  • Object
show all
Defined in:
lib/connect_wise/configuration.rb

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize {|_self| ... } ⇒ Configuration

Returns a new instance of Configuration.

Yields:

  • (_self)

Yield Parameters:



132
133
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
 
# File 'lib/connect_wise/configuration.rb', line 132

def initialize
  @scheme = 'http'
  @host = 'cloud.na.myconnectwise.net'
  @base_path = '/v4_6_development/apis/3.0'
  @server_operation_index = {}
  @server_variables = {}
  @server_operation_variables = {}
  @api_key = {}
  @api_key_prefix = {}
  @client_side_validation = true
  @ssl_verify = true
  @ssl_verify_mode = nil
  @ssl_ca_file = nil
  @ssl_client_cert = nil
  @ssl_client_key = nil
  @middlewares = Hash.new { |h, k| h[k] = [] }
  @timeout = 60
  # return data as binary instead of file
  @return_binary_data = false
  @params_encoder = nil
  @debugging = false
  @inject_format = false
  @force_ending_format = false
  @logger = defined?(Rails) ? Rails.logger : Logger.new(STDOUT)

  yield(self) if block_given?
end

Instance Attribute Details

#access_token ⇒ Object

Defines the access token (Bearer) used with OAuth2.



58
59
60
 
# File 'lib/connect_wise/configuration.rb', line 58

def access_token
  @access_token
end

#api_key ⇒ Hash

Defines API keys used with API Key authentications.

Examples:

parameter name is “api_key”, API key is “xxx” (e.g. “api_key=xxx” in query string)

config.api_key['api_key'] = 'xxx'

Returns:

  • (Hash) —

    key: parameter name, value: parameter value (API key)



37
38
39
 
# File 'lib/connect_wise/configuration.rb', line 37

def api_key
  @api_key
end

#api_key_prefix ⇒ Hash

Defines API key prefixes used with API Key authentications.

Examples:

parameter name is “Authorization”, API key prefix is “Token” (e.g. “Authorization: Token xxx” in headers)

config.api_key_prefix['api_key'] = 'Token'

Returns:

  • (Hash) —

    key: parameter name, value: API key prefix



45
46
47
 
# File 'lib/connect_wise/configuration.rb', line 45

def api_key_prefix
  @api_key_prefix
end

#base_path ⇒ Object

Defines url base path



20
21
22
 
# File 'lib/connect_wise/configuration.rb', line 20

def base_path
  @base_path
end

#client_side_validation ⇒ true, false

Set this to false to skip client side validation in the operation. Default to true.

Returns:

  • (true, false) 


87
88
89
 
# File 'lib/connect_wise/configuration.rb', line 87

def client_side_validation
  @client_side_validation
end

#debugging ⇒ true, false

Set this to enable/disable debugging. When enabled (set to true), HTTP request/response details will be logged with logger.debug (see the logger attribute). Default to false.

Returns:

  • (true, false) 


65
66
67
 
# File 'lib/connect_wise/configuration.rb', line 65

def debugging
  @debugging
end

#force_ending_format ⇒ Object

Returns the value of attribute force_ending_format.



130
131
132
 
# File 'lib/connect_wise/configuration.rb', line 130

def force_ending_format
  @force_ending_format
end

#host ⇒ Object

Defines url host



17
18
19
 
# File 'lib/connect_wise/configuration.rb', line 17

def host
  @host
end

#inject_format ⇒ Object

Returns the value of attribute inject_format.



130
131
132
 
# File 'lib/connect_wise/configuration.rb', line 130

def inject_format
  @inject_format
end

#logger ⇒ #debug

Defines the logger used for debugging. Default to Rails.logger (when in Rails) or logging to STDOUT.

Returns:

  • (#debug) 


71
72
73
 
# File 'lib/connect_wise/configuration.rb', line 71

def logger
  @logger
end

#params_encoder ⇒ Object

Set this to customize parameters encoder of array parameter. Default to nil. Faraday uses NestedParamsEncoder when nil.

github.com/lostisland/faraday/tree/main/lib/faraday/encoders

See Also:

  • params_encoder option of Faraday. Related source code:


128
129
130
 
# File 'lib/connect_wise/configuration.rb', line 128

def params_encoder
  @params_encoder
end

#password ⇒ String

Defines the password used with HTTP basic authentication.

Returns:

  • (String) 


55
56
57
 
# File 'lib/connect_wise/configuration.rb', line 55

def password
  @password
end

#proxy ⇒ Object

Proxy setting HTTP Proxy settings



121
122
123
 
# File 'lib/connect_wise/configuration.rb', line 121

def proxy
  @proxy
end

#scheme ⇒ Object

Defines url scheme



14
15
16
 
# File 'lib/connect_wise/configuration.rb', line 14

def scheme
  @scheme
end

#server_operation_index ⇒ Object

Define server operation configuration index



23
24
25
 
# File 'lib/connect_wise/configuration.rb', line 23

def server_operation_index
  @server_operation_index
end

#server_operation_variables ⇒ Object

Default server operation variables



29
30
31
 
# File 'lib/connect_wise/configuration.rb', line 29

def server_operation_variables
  @server_operation_variables
end

#server_variables ⇒ Object

Default server variables



26
27
28
 
# File 'lib/connect_wise/configuration.rb', line 26

def server_variables
  @server_variables
end

#ssl_ca_file ⇒ String

TLS/SSL setting Set this to customize the certificate file to verify the peer.

Returns:

  • (String) —

    the path to the certificate file



109
110
111
 
# File 'lib/connect_wise/configuration.rb', line 109

def ssl_ca_file
  @ssl_ca_file
end

#ssl_client_cert ⇒ Object

TLS/SSL setting Client certificate file (for client certificate)



113
114
115
 
# File 'lib/connect_wise/configuration.rb', line 113

def ssl_client_cert
  @ssl_client_cert
end

#ssl_client_key ⇒ Object

TLS/SSL setting Client private key file (for client certificate)



117
118
119
 
# File 'lib/connect_wise/configuration.rb', line 117

def ssl_client_key
  @ssl_client_key
end

#ssl_verify ⇒ true, false

Note:

Do NOT set it to false in production code, otherwise you would face multiple types of cryptographic attacks.

TLS/SSL setting Set this to false to skip verifying SSL certificate when calling API from https server. Default to true.

Returns:

  • (true, false) 


96
97
98
 
# File 'lib/connect_wise/configuration.rb', line 96

def ssl_verify
  @ssl_verify
end

#ssl_verify_mode ⇒ Object

Note:

Do NOT set it to false in production code, otherwise you would face multiple types of cryptographic attacks.

TLS/SSL setting Any OpenSSL::SSL:: constant (see ruby-doc.org/stdlib-2.5.1/libdoc/openssl/rdoc/OpenSSL/SSL.html)



103
104
105
 
# File 'lib/connect_wise/configuration.rb', line 103

def ssl_verify_mode
  @ssl_verify_mode
end

#temp_folder_path ⇒ String

Defines the temporary folder to store downloaded files (for API endpoints that have file response). Default to use Tempfile.

Returns:

  • (String) 


78
79
80
 
# File 'lib/connect_wise/configuration.rb', line 78

def temp_folder_path
  @temp_folder_path
end

#timeout ⇒ Object

The time limit for HTTP request in seconds. Default to 0 (never times out).



82
83
84
 
# File 'lib/connect_wise/configuration.rb', line 82

def timeout
  @timeout
end

#username ⇒ String

Defines the username used with HTTP basic authentication.

Returns:

  • (String) 


50
51
52
 
# File 'lib/connect_wise/configuration.rb', line 50

def username
  @username
end

Class Method Details

.default ⇒ Object

The default Configuration object.



161
162
163
 
# File 'lib/connect_wise/configuration.rb', line 161

def self.default
  @@default ||= Configuration.new
end

Instance Method Details

#api_key_with_prefix(param_name, param_alias = nil) ⇒ Object

Gets API key (with prefix if set).

Parameters:

  • param_name (String) —

    the parameter name of API key auth



192
193
194
195
196
197
198
199
200
 
# File 'lib/connect_wise/configuration.rb', line 192

def api_key_with_prefix(param_name, param_alias = nil)
  key = @api_key[param_name]
  key = @api_key.fetch(param_alias, key) unless param_alias.nil?
  if @api_key_prefix[param_name]
    "#{@api_key_prefix[param_name]} #{key}"
  else
    key
  end
end

#auth_settings ⇒ Object

Returns Auth Settings hash for api client.



208
209
210
211
212
213
214
215
216
217
218
 
# File 'lib/connect_wise/configuration.rb', line 208

def auth_settings
  {
    'basicAuth' =>
      {
        type: 'basic',
        in: 'header',
        key: 'Authorization',
        value: basic_auth_token
      }
  }
end

#base_url(_operation = nil) ⇒ Object

Returns base URL for specified operation based on server settings



186
187
188
 
# File 'lib/connect_wise/configuration.rb', line 186

def base_url(_operation = nil)
  "#{scheme}://#{[host, base_path].join('/').squeeze('/')}".sub(%r{/+\z}, '')
end

#basic_auth_token ⇒ Object

Gets Basic Auth token string



203
204
205
 
# File 'lib/connect_wise/configuration.rb', line 203

def basic_auth_token
  'Basic ' + ["#{username}:#{password}"].pack('m').delete("\r\n")
end

#configure {|_self| ... } ⇒ Object

Yields:

  • (_self)

Yield Parameters:



165
166
167
 
# File 'lib/connect_wise/configuration.rb', line 165

def configure
  yield(self) if block_given?
end

#configure_middleware(connection) ⇒ Object

Set up middleware on the connection



302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
 
# File 'lib/connect_wise/configuration.rb', line 302

def configure_middleware(connection)
  return if @middlewares.empty?

  i[request response use insert insert_before insert_after swap].each do |operation|
    next unless @middlewares.key?(operation)

    @middlewares[operation].each do |key, args, block|
      connection.builder.send(operation, key, *args, &block)
    end
  end

  return unless @middlewares.key?(:delete)

  @middlewares[:delete].each do |key, _args, _block|
    connection.builder.delete(key)
  end
end

#operation_server_settings ⇒ Object 



230
231
232
 
# File 'lib/connect_wise/configuration.rb', line 230

def operation_server_settings
  {}
end

#request(*middleware) ⇒ Object

Adds request middleware to the stack



271
272
273
 
# File 'lib/connect_wise/configuration.rb', line 271

def request(*middleware)
  set_faraday_middleware(:request, *middleware)
end

#response(*middleware) ⇒ Object

Adds response middleware to the stack



276
277
278
 
# File 'lib/connect_wise/configuration.rb', line 276

def response(*middleware)
  set_faraday_middleware(:response, *middleware)
end

#server_settings ⇒ Object

Returns an array of Server setting



221
222
223
224
225
226
227
228
 
# File 'lib/connect_wise/configuration.rb', line 221

def server_settings
  [
    {
      url: 'http://cloud.na.myconnectwise.net/v4_6_development/apis/3.0',
      description: 'No description provided'
    }
  ]
end

#server_url(index, variables = {}, servers = nil) ⇒ Object

Returns URL based on server settings

Parameters:

  • index —

    array index of the server settings

  • variables (defaults to: {}) —

    hash of variable and the corresponding value

Raises:

  • (ArgumentError) 


238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
 
# File 'lib/connect_wise/configuration.rb', line 238

def server_url(index, variables = {}, servers = nil)
  servers = server_settings if servers.nil?

  # check array index out of bound
  raise ArgumentError, "Invalid index #{index} when selecting the server. Must be less than #{servers.size}" if index < 0 || index >= servers.size

  server = servers[index]
  url = server[:url]

  return url unless server.key? :variables

  # go through variable and assign a value
  server[:variables].each do |name, _variable|
    if variables.key?(name)
      raise ArgumentError, "The variable `#{name}` in the server URL has invalid value #{variables[name]}. Must be #{server[:variables][name][:enum_values]}." unless !server[:variables][name].key?(:enum_values) || server[:variables][name][:enum_values].include?(variables[name])

      url.gsub! '{' + name.to_s + '}', variables[name]

    else
      # use default value
      url.gsub! '{' + name.to_s + '}', server[:variables][name][:default_value]
    end
  end

  url
end

#set_faraday_middleware(operation, key, *args, &block) ⇒ Object

Adds Faraday middleware setting information to the stack

Examples:

Use the set_faraday_middleware method to set middleware information

config.set_faraday_middleware(:request, :retry, max: 3, methods: [:get, :post], retry_statuses: [503])
config.set_faraday_middleware(:response, :logger, nil, { bodies: true, log_level: :debug })
config.set_faraday_middleware(:use, Faraday::HttpCache, store: Rails.cache, shared_cache: false)
config.set_faraday_middleware(:insert, 0, FaradayMiddleware::FollowRedirects, { standards_compliant: true, limit: 1 })
config.set_faraday_middleware(:swap, 0, Faraday::Response::Logger)
config.set_faraday_middleware(:delete, Faraday::Multipart::Middleware)

See Also:



291
292
293
294
295
296
297
298
 
# File 'lib/connect_wise/configuration.rb', line 291

def set_faraday_middleware(operation, key, *args, &block)
  unless i[request response use insert insert_before insert_after swap delete].include?(operation)
    raise ArgumentError, "Invalid faraday middleware operation #{operation}. Must be" \
                         ' :request, :response, :use, :insert, :insert_before, :insert_after, :swap or :delete.'
  end

  @middlewares[operation] << [key, args, block]
end

#use(*middleware) ⇒ Object

Adds middleware to the stack



266
267
268
 
# File 'lib/connect_wise/configuration.rb', line 266

def use(*middleware)
  set_faraday_middleware(:use, *middleware)
end