Class: HttpResource::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/http_resource/client.rb

Overview

Net::HTTP transport for a single REST host. Resource-oriented: the verbs (get/post/patch/delete) are the primitives a Resource is built on, and also an escape hatch for endpoints not yet modelled.

client = HttpResource::Client.new(base_url: "https://api.example.org",
                                  auth: HttpResource::Auth.bearer(token))
client.get(["api", "contacts", id])         # GET, id escaped as one segment
client.post(["api", "actions"], { ... })    # POST a JSON body

Reads return parsed JSON (a Hash/Array, or nil on an empty body). Every call raises an HttpResource::ApiError subclass on a non-2xx response or a transport failure.

SECURITY — path segments are UNTRUSTED. When ‘path` is an Array, each segment is percent-encoded as a single RFC-3986 path component, so an id/email/token can never escape into a second segment, the host, a query or a header. A String `path` is sent VERBATIM (trusted) — NEVER interpolate untrusted input into a String path; pass an Array.

Constant Summary collapse

DEFAULT_OPEN_TIMEOUT = 
5
DEFAULT_READ_TIMEOUT = 
15

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(base_url:, auth: nil, username: nil, password: nil, open_timeout: DEFAULT_OPEN_TIMEOUT, read_timeout: DEFAULT_READ_TIMEOUT) ⇒ Client

Returns a new instance of Client.

Raises:



34
35
36
37
38
39
40
41
42
 
# File 'lib/http_resource/client.rb', line 34

def initialize(base_url:, auth: nil, username: nil, password: nil,
               open_timeout: DEFAULT_OPEN_TIMEOUT, read_timeout: DEFAULT_READ_TIMEOUT)
  raise ConfigurationError, "base_url is required" if blank?(base_url)

  @base_url = base_url.to_s.sub(%r{/+\z}, "")
  @auth = auth || default_auth(username, password)
  @open_timeout = open_timeout
  @read_timeout = read_timeout
end

Instance Attribute Details

#base_url ⇒ Object (readonly)

Returns the value of attribute base_url.



32
33
34
 
# File 'lib/http_resource/client.rb', line 32

def base_url
  @base_url
end

Instance Method Details

#delete(path, **timeouts) ⇒ Object 



60
61
62
 
# File 'lib/http_resource/client.rb', line 60

def delete(path, **timeouts)
  request(:delete, path, **timeouts)
end

#get(path, params: nil, **timeouts) ⇒ Object

Low-level REST verbs. ‘path` may be a String (“/api/foo”) sent verbatim, or an Array of segments ([“api”, “contacts”, email]) each individually escaped. Each verb accepts open_timeout:/read_timeout: to override the client’s budget for that one call (e.g. a short read_timeout on a synchronous read).



48
49
50
 
# File 'lib/http_resource/client.rb', line 48

def get(path, params: nil, **timeouts)
  request(:get, path, params:, **timeouts)
end

#patch(path, payload = nil, **timeouts) ⇒ Object 



56
57
58
 
# File 'lib/http_resource/client.rb', line 56

def patch(path, payload = nil, **timeouts)
  request(:patch, path, body: payload, **timeouts)
end

#post(path, payload = nil, **timeouts) ⇒ Object 



52
53
54
 
# File 'lib/http_resource/client.rb', line 52

def post(path, payload = nil, **timeouts)
  request(:post, path, body: payload, **timeouts)
end