Class: Fluence::Gateway::Client

Inherits:

Object

• Object
• Fluence::Gateway::Client

Extended by:

Forwardable

Includes:

Singleton

Defined in:

lib/fluence/gateway/http_client.rb

Overview

Singleton HTTP client for the Fluence API gateway.

Handles OAuth2 client_credentials authentication transparently: the service token is fetched on the first request and refreshed on demand. End-user Bearer tokens can be forwarded per call or for an entire block, and the target service can be encoded into the URL via the service: kwarg or the #with_service block helper.

All HTTP verbs (get, post, put, patch, delete) are defined on both the singleton instance and the class (class-level delegation), so callers never need to reference .instance explicitly.

Thread-safety: token refresh is guarded by a Mutex; per-block scopes (#with_user_token, #with_service) are stored in Thread.current and restored when the block exits, including on exception.

Examples:

Configure once, call anywhere

Fluence::Gateway.configure do |c|
  c.client_id     = ENV.fetch('GATEWAY_CLIENT_ID')
  c.client_secret = ENV.fetch('GATEWAY_CLIENT_SECRET')
end

Fluence::Gateway::Client.get('/api/v1/valuations', service: :base_valeur)
# → GET /backend/base-valeur/api/v1/valuations

Forward the end-user token for a whole block

Fluence::Gateway::Client.with_user_token(current_user.token) do
  Fluence::Gateway::Client.get('/api/v1/me', service: :base_valeur)
end

Scope multiple calls to the same service

Fluence::Gateway::Client.with_service(:base_valeur) do
  Fluence::Gateway::Client.get('/api/v1/valuations')
  Fluence::Gateway::Client.post('/api/v1/valuations', body: { asset_id: 42 })
end

See Also:

• Configuration
• AuthenticationError
• ConnectionError

Class Method Summary

• .delete(path, user_token: nil, service: nil, **opts) ⇒ Hash, Array

  The parsed JSON response.

• .get(path, user_token: nil, service: nil, **opts) ⇒ Hash, Array

  The parsed JSON response.

• .patch(path, user_token: nil, service: nil, body: nil, **opts) ⇒ Hash, Array

  The parsed JSON response.

• .post(path, user_token: nil, service: nil, body: nil, **opts) ⇒ Hash, Array

  The parsed JSON response.

• .put(path, user_token: nil, service: nil, body: nil, **opts) ⇒ Hash, Array

  The parsed JSON response.

• .with_service(service, &block) ⇒ Object

  The block's return value.

• .with_user_token(token, &block) ⇒ Object

  The block's return value.

Instance Method Summary

• #delete(path, user_token: nil, service: nil, **opts) ⇒ Hash, Array

  Performs a DELETE request on the gateway.

• #get(path, user_token: nil, service: nil, **opts) ⇒ Hash, Array

  Performs a GET request on the gateway.

• #patch(path, user_token: nil, service: nil, body: nil, **opts) ⇒ Hash, Array

  Performs a PATCH request on the gateway.

• #post(path, user_token: nil, service: nil, body: nil, **opts) ⇒ Hash, Array

  Performs a POST request on the gateway.

• #put(path, user_token: nil, service: nil, body: nil, **opts) ⇒ Hash, Array

  Performs a PUT request on the gateway.

• #with_service(service) { ... } ⇒ Object

  Scopes a block of gateway calls to the given backend service.

• #with_user_token(token) { ... } ⇒ Object

  Scopes a block of gateway calls to forward token as the end-user Bearer instead of the cached service token.

Class Method Details

.delete(path, user_token: nil, service: nil, **opts) ⇒ Hash, Array

Returns the parsed JSON response.

Returns:

• (Hash, Array) —

  the parsed JSON response

See Also:

• #delete

.get(path, user_token: nil, service: nil, **opts) ⇒ Hash, Array

Returns the parsed JSON response.

Returns:

• (Hash, Array) —

  the parsed JSON response

See Also:

• #get

.patch(path, user_token: nil, service: nil, body: nil, **opts) ⇒ Hash, Array

Returns the parsed JSON response.

Returns:

• (Hash, Array) —

  the parsed JSON response

See Also:

• #patch

.post(path, user_token: nil, service: nil, body: nil, **opts) ⇒ Hash, Array

Returns the parsed JSON response.

Returns:

• (Hash, Array) —

  the parsed JSON response

See Also:

• #post

.put(path, user_token: nil, service: nil, body: nil, **opts) ⇒ Hash, Array

Returns the parsed JSON response.

Returns:

• (Hash, Array) —

  the parsed JSON response

See Also:

• #put

.with_service(service, &block) ⇒ Object

Returns the block's return value.

Returns:

• (Object) —

  the block's return value

See Also:

• #with_service

.with_user_token(token, &block) ⇒ Object

Returns the block's return value.

Returns:

• (Object) —

  the block's return value

See Also:

• #with_user_token

Instance Method Details

#delete(path, user_token: nil, service: nil, **opts) ⇒ Hash, Array

Performs a DELETE request on the gateway.

Parameters:

• path (String) —

  the resource path (leading slash optional)

• user_token (String, nil) (defaults to: nil) —

  optional end-user Bearer token to forward

• service (Symbol, String, nil) (defaults to: nil) —

  optional target service (see #get)

• opts (Hash) —

  extra options forwarded to OAuth2::AccessToken#delete

Returns:

• (Hash, Array) —

  the parsed JSON response

Raises:

• (AuthenticationError) —

  if the OAuth2 token flow fails

• (ConnectionError) —

  if the gateway is unreachable

#get(path, user_token: nil, service: nil, **opts) ⇒ Hash, Array

Performs a GET request on the gateway.

Parameters:

• path (String) —

  the resource path (leading slash optional)

• user_token (String, nil) (defaults to: nil) —

  optional end-user Bearer token to forward instead of the service client_credentials token

• service (Symbol, String, nil) (defaults to: nil) —

  optional target service. When set, the path is rewritten as /backend/<service>/<path>. Symbols have their underscores converted to dashes (:base_valeur → base-valeur); strings are used as-is. Overrides any #with_service block in scope.

• opts (Hash) —

  extra options forwarded to OAuth2::AccessToken#get

Returns:

• (Hash, Array) —

  the parsed JSON response

Raises:

• (AuthenticationError) —

  if the OAuth2 token flow fails

• (ConnectionError) —

  if the gateway is unreachable

#patch(path, user_token: nil, service: nil, body: nil, **opts) ⇒ Hash, Array

Performs a PATCH request on the gateway.

Parameters:

• path (String) —

  the resource path (leading slash optional)

• user_token (String, nil) (defaults to: nil) —

  optional end-user Bearer token to forward

• service (Symbol, String, nil) (defaults to: nil) —

  optional target service (see #get)

• body (Hash) (defaults to: nil) —

  the request body (serialized as JSON)

• opts (Hash) —

  extra options forwarded to OAuth2::AccessToken#patch

Returns:

• (Hash, Array) —

  the parsed JSON response

Raises:

• (AuthenticationError) —

  if the OAuth2 token flow fails

• (ConnectionError) —

  if the gateway is unreachable

#post(path, user_token: nil, service: nil, body: nil, **opts) ⇒ Hash, Array

Performs a POST request on the gateway.

Parameters:

• path (String) —

  the resource path (leading slash optional)

• user_token (String, nil) (defaults to: nil) —

  optional end-user Bearer token to forward

• service (Symbol, String, nil) (defaults to: nil) —

  optional target service (see #get)

• body (Hash) (defaults to: nil) —

  the request body (serialized as JSON)

• opts (Hash) —

  extra options forwarded to OAuth2::AccessToken#post

Returns:

• (Hash, Array) —

  the parsed JSON response

Raises:

• (AuthenticationError) —

  if the OAuth2 token flow fails

• (ConnectionError) —

  if the gateway is unreachable

#put(path, user_token: nil, service: nil, body: nil, **opts) ⇒ Hash, Array

Performs a PUT request on the gateway.

Parameters:

• path (String) —

  the resource path (leading slash optional)

• user_token (String, nil) (defaults to: nil) —

  optional end-user Bearer token to forward

• service (Symbol, String, nil) (defaults to: nil) —

  optional target service (see #get)

• body (Hash) (defaults to: nil) —

  the request body (serialized as JSON)

• opts (Hash) —

  extra options forwarded to OAuth2::AccessToken#put

Returns:

• (Hash, Array) —

  the parsed JSON response

Raises:

• (AuthenticationError) —

  if the OAuth2 token flow fails

• (ConnectionError) —

  if the gateway is unreachable

#with_service(service) { ... } ⇒ Object

Scopes a block of gateway calls to the given backend service.

Paths issued inside the block are automatically prefixed with /backend/<service>/. When service is a Symbol, underscores are converted to dashes (:base_valeur → base-valeur); when it is a String, it is used as-is. The scope is stored in Thread.current and restored when the block exits, including on exception. A service: kwarg on a call site always wins over the value set here.

Examples:

Avoid repeating service: on every call

Fluence::Gateway::Client.with_service(:base_valeur) do
  Fluence::Gateway::Client.get('/api/v1/valuations')
  Fluence::Gateway::Client.post('/api/v1/valuations', body: { asset_id: 42 })
end

Parameters:

• service (Symbol, String) —

  the target service name

Yields:

• block in which gateway calls are scoped to service

Returns:

• (Object) —

  the block's return value

#with_user_token(token) { ... } ⇒ Object

Scopes a block of gateway calls to forward token as the end-user Bearer instead of the cached service token.

The token is stored in Thread.current so it survives nested calls on the same thread but does not leak to other threads. Any explicit user_token: kwarg on a call site always wins over the value set here. The previous value (if any) is restored when the block exits, including on exception.

Examples:

Forward the current user's token for all calls in a block

Fluence::Gateway::Client.with_user_token(current_user.access_token) do
  Fluence::Gateway::Client.get('/api/v1/me', service: :base_valeur)
  Fluence::Gateway::Client.post('/api/v1/things', service: :base_valeur,
                                body: { name: 'x' })
end

Parameters:

• token (String) —

  the end-user Bearer token

Yields:

• block in which gateway calls forward token

Returns:

• (Object) —

  the block's return value