Class: WorkOS::BaseClient

Inherits:
Object
  • Object
show all
Defined in:
lib/workos/base_client.rb

Overview

Instance-scoped HTTP runtime that implements request execution, retry policy with exponential backoff + jitter, error translation, and per-request option overrides.

Examples:

Create a client with custom settings

client = WorkOS::Client.new(
  api_key: "sk_...",
  client_id: "client_...",
  timeout: 60,
  max_retries: 3,
  logger: Logger.new($stdout),
  log_level: :info
)

Shut down connections before forking

client.shutdown

Direct Known Subclasses

Client

Constant Summary collapse

DEFAULT_BASE_URL = 
"https://api.workos.com"
DEFAULT_TIMEOUT = 
30
DEFAULT_MAX_RETRIES = 
2
RETRYABLE_STATUSES = 
[408, 409, 429, 500, 502, 503, 504].freeze
MAX_CACHED_CONNECTIONS = 
8
RETRY_BACKOFF_BASE = 
0.5
LOG_SEVERITY = 
{debug: 0, info: 1, warn: 2, error: 3, unknown: 4}.freeze
USER_AGENT = 
[
  "WorkOS",
  "#{defined?(::RUBY_ENGINE) ? ::RUBY_ENGINE : "ruby"}/#{RUBY_VERSION}",
  RUBY_PLATFORM,
  "v#{WorkOS::VERSION}"
].join("; ").freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key: nil, base_url: DEFAULT_BASE_URL, client_id: nil, timeout: DEFAULT_TIMEOUT, max_retries: DEFAULT_MAX_RETRIES, logger: nil, log_level: nil, jwt_issuer: nil, random: Random.new) ⇒ BaseClient

Returns a new instance of BaseClient.

Parameters:

  • jwt_issuer (String, Array<String>, nil) (defaults to: nil) —

    Expected iss claim of session access tokens (one issuer or a list of accepted issuers). When nil, the issuer is not validated.



49
50
51
52
53
54
55
56
57
58
59
60
61
 
# File 'lib/workos/base_client.rb', line 49

def initialize(api_key: nil, base_url: DEFAULT_BASE_URL, client_id: nil,
  timeout: DEFAULT_TIMEOUT, max_retries: DEFAULT_MAX_RETRIES,
  logger: nil, log_level: nil, jwt_issuer: nil, random: Random.new)
  @api_key = api_key
  @base_url = base_url
  @client_id = client_id
  @timeout = timeout
  @max_retries = max_retries
  @logger = logger
  @log_level = log_level
  @jwt_issuer = jwt_issuer
  @random = random
end

Instance Attribute Details

#api_key ⇒ Object (readonly)

Returns the value of attribute api_key.



44
45
46
 
# File 'lib/workos/base_client.rb', line 44

def api_key
  @api_key
end

#base_url ⇒ Object (readonly)

Returns the value of attribute base_url.



44
45
46
 
# File 'lib/workos/base_client.rb', line 44

def base_url
  @base_url
end

#client_id ⇒ Object (readonly)

Returns the value of attribute client_id.



44
45
46
 
# File 'lib/workos/base_client.rb', line 44

def client_id
  @client_id
end

#jwt_issuer ⇒ Object (readonly)

Returns the value of attribute jwt_issuer.



44
45
46
 
# File 'lib/workos/base_client.rb', line 44

def jwt_issuer
  @jwt_issuer
end

#log_level ⇒ Object (readonly)

Returns the value of attribute log_level.



44
45
46
 
# File 'lib/workos/base_client.rb', line 44

def log_level
  @log_level
end

#logger ⇒ Object (readonly)

Returns the value of attribute logger.



44
45
46
 
# File 'lib/workos/base_client.rb', line 44

def logger
  @logger
end

#max_retries ⇒ Object (readonly)

Returns the value of attribute max_retries.



44
45
46
 
# File 'lib/workos/base_client.rb', line 44

def max_retries
  @max_retries
end

#timeout ⇒ Object (readonly)

Returns the value of attribute timeout.



44
45
46
 
# File 'lib/workos/base_client.rb', line 44

def timeout
  @timeout
end

Instance Method Details

#delete_request(path:, auth: false, body: nil, params: {}, request_options: nil) ⇒ Object 



97
98
99
100
101
102
103
104
105
 
# File 'lib/workos/base_client.rb', line 97

def delete_request(path:, auth: false, body: nil, params: {}, request_options: nil)
  req = build_request(Net::HTTP::Delete, append_query(path, params),
    auth: auth, request_options: request_options)
  if body
    req.body = body.to_json
    req["Content-Type"] = "application/json"
  end
  req
end

#execute_request(request:, request_options: nil) ⇒ Object

-- Execution --------------------------------------------------------



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
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
 
# File 'lib/workos/base_client.rb', line 133

def execute_request(request:, request_options: nil)
  opts = (request_options || {}).transform_keys(&:to_sym)
  base = opts[:base_url] || @base_url
  timeout = opts[:timeout] || @timeout
  retries = opts[:max_retries] || @max_retries
  attempt = 0

  loop do
    loggable_path = redact_path(request.path)
    log(:debug, "request start", method: request.method, path: loggable_path, attempt: attempt + 1)
    http = connection_for(base, timeout)
    request_completed = false
    begin
      response = http.request(request)
      request_completed = true
    ensure
      # Any exit from #request other than a returned response can leave
      # the socket mid-stream: a connection error the rescue below knows
      # about, one it doesn't (OpenSSL::SSL::SSLError,
      # Net::HTTPBadResponse), or a non-local exit such as an
      # application-level Timeout.timeout or Thread#kill. A half-read
      # socket handed back to the pool desyncs the *next* request on this
      # thread, so drop it here rather than in the rescue.
      evict_connection(base) unless request_completed
    end
    return response if response.is_a?(Net::HTTPSuccess)

    if attempt < retries && retryable?(response)
      attempt += 1
      inject_retry_idempotency_key(request)
      log(:info, "request retry", method: request.method, path: loggable_path, attempt: attempt + 1, status: response.code.to_i)
      sleep(retry_delay(response, attempt))
      next
    end
    log(:warn, "request error", method: request.method, path: loggable_path, status: response.code.to_i, request_id: response["x-request-id"] || response["X-Request-Id"])
    handle_error_response(response)
  rescue Net::OpenTimeout, Net::ReadTimeout,
    Errno::ECONNRESET, Errno::ECONNREFUSED,
    IOError, Errno::EPIPE => e
    evict_connection(base)
    if attempt < retries
      attempt += 1
      inject_retry_idempotency_key(request)
      log(:info, "request retry", method: request.method, path: loggable_path, attempt: attempt + 1, error: e.class.name)
      sleep(retry_delay(nil, attempt))
      next
    end
    log(:warn, "connection error", method: request.method, path: loggable_path, error: e.class.name, message: e.message)
    raise WorkOS::APIConnectionError.new(message: e.message)
  end
end

#get_request(path:, auth: false, params: {}, request_options: nil) ⇒ Object

-- Request builders -------------------------------------------------



65
66
67
68
 
# File 'lib/workos/base_client.rb', line 65

def get_request(path:, auth: false, params: {}, request_options: nil)
  build_request(Net::HTTP::Get, append_query(path, params),
    auth: auth, request_options: request_options)
end

#patch_request(path:, auth: false, body: {}, params: {}, request_options: nil) ⇒ Object 



88
89
90
91
92
93
94
95
 
# File 'lib/workos/base_client.rb', line 88

def patch_request(path:, auth: false, body: {}, params: {}, request_options: nil)
  req = build_request(Net::HTTP::Patch, append_query(path, params),
    auth: auth, request_options: request_options)
  req.body = body.nil? ? "" : body.to_json
  req["Content-Type"] = "application/json"
  inject_idempotency_key(req, request_options)
  req
end

#post_request(path:, auth: false, body: {}, params: {}, request_options: nil) ⇒ Object 



70
71
72
73
74
75
76
77
 
# File 'lib/workos/base_client.rb', line 70

def post_request(path:, auth: false, body: {}, params: {}, request_options: nil)
  req = build_request(Net::HTTP::Post, append_query(path, params),
    auth: auth, request_options: request_options)
  req.body = body.nil? ? "" : body.to_json
  req["Content-Type"] = "application/json"
  inject_idempotency_key(req, request_options)
  req
end

#put_request(path:, auth: false, body: {}, params: {}, request_options: nil) ⇒ Object 



79
80
81
82
83
84
85
86
 
# File 'lib/workos/base_client.rb', line 79

def put_request(path:, auth: false, body: {}, params: {}, request_options: nil)
  req = build_request(Net::HTTP::Put, append_query(path, params),
    auth: auth, request_options: request_options)
  req.body = body.nil? ? "" : body.to_json
  req["Content-Type"] = "application/json"
  inject_idempotency_key(req, request_options)
  req
end

#request(method:, path:, auth: true, params: {}, body: nil, request_options: {}) ⇒ Object

Unified request helper: builds the verb-specific request and executes it in a single call, removing the need for callers to pass request_options twice.

Raises:

  • (ArgumentError) 


112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
 
# File 'lib/workos/base_client.rb', line 112

def request(method:, path:, auth: true, params: {}, body: nil, request_options: {})
  raise ArgumentError, "unsupported method" unless %i[get post put patch delete].include?(method)
  request_options = (request_options || {}).transform_keys(&:to_sym)

  req = case method
  when :get
    get_request(path: path, auth: auth, params: params, request_options: request_options)
  when :post
    post_request(path: path, auth: auth, body: body, params: params, request_options: request_options)
  when :put
    put_request(path: path, auth: auth, body: body, params: params, request_options: request_options)
  when :patch
    patch_request(path: path, auth: auth, body: body, params: params, request_options: request_options)
  when :delete
    delete_request(path: path, auth: auth, body: body, params: params, request_options: request_options)
  end
  execute_request(request: req, request_options: request_options)
end

#shutdown ⇒ void

This method returns an undefined value.

Close all persistent connections cached by this client on the current thread.

Call this before forking (e.g. in a Puma on_worker_boot block) to avoid sharing Net::HTTP sockets across processes.



192
193
194
195
196
 
# File 'lib/workos/base_client.rb', line 192

def shutdown
  connections = thread_connections.values
  thread_connections.clear
  connections.each { |connection| connection.finish if connection.started? }
end