Class: ConvertSdk::HttpClient

Inherits:
Object
  • Object
show all
Defined in:
lib/convert_sdk/http_client.rb

Overview

The single hardened HTTP port every SDK request flows through.

HttpClient is the only file in the gem that touches Net::HTTP (a cheap architectural regression test asserts this). Every request it sends carries the ConvertAgent wire invariant and bounded timeouts, and every failure it encounters is converted into a failed Response rather than raised — the port NEVER raises to callers, so the config fetch (Story 2.5) and event delivery (Story 4.1) consumers degrade gracefully on a failed response.

The ConvertAgent wire invariant

The metrics endpoint's bot filter silently DROPS server-side events whose User-Agent is not ConvertAgent/1.0. The header is therefore applied LAST, after every header merge, so it cannot be overridden by an integrator-supplied User-Agent. Without it, tracking events would vanish silently in production. (JS/PHP precedent: set unconditionally after merge.)

Bounded timeouts

Both open_timeout and read_timeout are set explicitly on EVERY request (a deliberate improvement over the JS SDK, which sets none). The SDK can never hang a host thread waiting on a slow or dead endpoint.

TLS / Bearer / proxies

HTTPS endpoints use TLS with verification ON (+verify_mode+ is never VERIFY_NONE). An Authorization: Bearer ... header is stripped (and a warning logged) on any non-HTTPS endpoint so the SDK key secret never crosses the wire in plaintext. Proxies are honoured through the standard Net::HTTP environment conventions (+http_proxy+/+https_proxy+/+no_proxy+).

JSON boundary

Callers pass and receive Ruby hashes; JSON encode/decode happens only here. A request body hash is rendered with JSON.generate; a response body is parsed with JSON.parse (string keys). A parse failure is logged and yields body: nil on an otherwise intact response.

All logging goes through the injected LogManager (never puts), so the Redactor masks secrets and strips URL query strings from every line.

Defined Under Namespace

Classes: Response

Constant Summary collapse

USER_AGENT =

The mandatory wire User-Agent. Applied LAST so it is unoverridable.

"ConvertAgent/1.0"
FAILURE_STATUS =

The status used for a failed Response when no HTTP response was received (network error / timeout). Callers MUST use Response#success?, never compare the status integer, for error detection.

0

Instance Method Summary collapse

Constructor Details

#initialize(log_manager:, open_timeout:, read_timeout:) ⇒ HttpClient

Returns a new instance of HttpClient.

Parameters:

  • log_manager (LogManager) —

    the injected logging surface. All output flows through it so the Redactor applies.

  • open_timeout (Numeric) —

    connection-establishment timeout (seconds).

  • read_timeout (Numeric) —

    response-read timeout (seconds).



86
87
88
89
90
 
# File 'lib/convert_sdk/http_client.rb', line 86

def initialize(log_manager:, open_timeout:, read_timeout:)
  @log_manager = log_manager
  @open_timeout = open_timeout
  @read_timeout = read_timeout
end

Instance Method Details

#request(method:, url:, headers: {}, body: nil) ⇒ Response

Send one HTTP request and return a frozen Response. Never raises: any transport failure is logged and returned as a failed response.

Parameters:

  • method (Symbol) —

    :get / :post / etc.

  • url (String) —

    the absolute request URL.

  • headers (Hash{String=>String}) (defaults to: {}) —

    caller headers (merged before the wire invariant is applied last).

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

    a request body; JSON-encoded if present.

Returns:

  • (Response) —

    frozen; success? is the only valid error check.



101
102
103
104
105
106
107
108
109
110
111
 
# File 'lib/convert_sdk/http_client.rb', line 101

def request(method:, url:, headers: {}, body: nil)
  uri = URI.parse(url)
  https = uri.scheme == "https"
  wire_headers = build_headers(headers, https)
  @log_manager.debug("HttpClient#request: #{method.to_s.upcase} #{url}")

  perform(method, uri, https, wire_headers, body)
rescue StandardError => e
  @log_manager.error("HttpClient#request: request failed (#{e.class}: #{e.message})")
  failed_response
end