Class: Nfe::Http::Request

Inherits:
Data
  • Object
show all
Defined in:
lib/nfe/http/request.rb,
sig/nfe/http/request.rbs

Overview

Immutable value object describing a single outbound HTTP request.

A Request is transport-agnostic: it carries everything a transport needs to perform one HTTP call, including its own base_url (enabling multi-host routing) and optional per-call timeout overrides. Headers, query, and body are supplied verbatim; the transport is responsible for wire encoding.

request = Nfe::Http::Request.new(
method: "GET",
base_url: "https://api.nfse.io",
path: "/v2/companies/abc/productinvoices",
query: { environment: "Production", limit: 50 }
)
request.url # => ".../productinvoices?environment=Production&limit=50"

The method member intentionally exposes the HTTP verb as request.method; it shadows Object#method, which the value object never relies on.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(method:, base_url:, path:, headers: {}, query: {}, body: nil, open_timeout: nil, read_timeout: nil, idempotency_key: nil) ⇒ Request

Returns a new instance of Request.

Parameters:

  • method (String) —

    HTTP method (e.g. "GET", "POST").

  • base_url (String) —

    origin + optional prefix (e.g. "https://api.nfse.io").

  • path (String) —

    request path (e.g. "/v2/companies").

  • headers (Hash) (defaults to: {}) —

    request headers, sent verbatim by the transport.

  • query (Hash) (defaults to: {}) —

    query parameters; array values become repeated keys.

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

    raw request body, or nil.

  • open_timeout (Numeric, nil) (defaults to: nil) —

    per-call connect timeout override.

  • read_timeout (Numeric, nil) (defaults to: nil) —

    per-call read timeout override.

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

    optional key; makes a POST retry-eligible.



37
38
39
40
 
# File 'lib/nfe/http/request.rb', line 37

def initialize(method:, base_url:, path:, headers: {}, query: {}, body: nil,
               open_timeout: nil, read_timeout: nil, idempotency_key: nil)
  super
end

Instance Attribute Details

#base_url ⇒ String (readonly)

Returns the value of attribute base_url.

Returns:

  • (String) 


5
6
7
 
# File 'sig/nfe/http/request.rbs', line 5

def base_url
  @base_url
end

#body ⇒ String? (readonly)

Returns the value of attribute body.

Returns:

  • (String, nil) 


9
10
11
 
# File 'sig/nfe/http/request.rbs', line 9

def body
  @body
end

#headers ⇒ Hash[String, untyped] (readonly)

Returns the value of attribute headers.

Returns:

  • (Hash[String, untyped]) 


7
8
9
 
# File 'sig/nfe/http/request.rbs', line 7

def headers
  @headers
end

#idempotency_key ⇒ String? (readonly)

Returns the value of attribute idempotency_key.

Returns:

  • (String, nil) 


12
13
14
 
# File 'sig/nfe/http/request.rbs', line 12

def idempotency_key
  @idempotency_key
end

#method ⇒ String (readonly)

Returns the value of attribute method.

Returns:

  • (String) 


4
5
6
 
# File 'sig/nfe/http/request.rbs', line 4

def method
  @method
end

#open_timeout ⇒ Numeric? (readonly)

Returns the value of attribute open_timeout.

Returns:

  • (Numeric, nil) 


10
11
12
 
# File 'sig/nfe/http/request.rbs', line 10

def open_timeout
  @open_timeout
end

#path ⇒ String (readonly)

Returns the value of attribute path.

Returns:

  • (String) 


6
7
8
 
# File 'sig/nfe/http/request.rbs', line 6

def path
  @path
end

#query ⇒ Hash[untyped, untyped] (readonly)

Returns the value of attribute query.

Returns:

  • (Hash[untyped, untyped]) 


8
9
10
 
# File 'sig/nfe/http/request.rbs', line 8

def query
  @query
end

#read_timeout ⇒ Numeric? (readonly)

Returns the value of attribute read_timeout.

Returns:

  • (Numeric, nil) 


11
12
13
 
# File 'sig/nfe/http/request.rbs', line 11

def read_timeout
  @read_timeout
end

Class Method Details

.new ⇒ Object 



14
 
# File 'sig/nfe/http/request.rbs', line 14

def self.new: (

Instance Method Details

#idempotent? ⇒ Boolean

Whether this request is safe to retry.

Returns:

  • (Boolean) —

    true for GET/HEAD/PUT/DELETE (case-insensitive) or any request carrying a non-nil idempotency_key.



61
62
63
64
65
 
# File 'lib/nfe/http/request.rb', line 61

def idempotent?
  return true unless idempotency_key.nil?

  %w[GET HEAD PUT DELETE].include?(method.to_s.upcase)
end

#url ⇒ String

Composes the final URL from base_url, path, and the URL-encoded query.

A trailing slash on base_url is stripped. When query is non-empty the encoded form is appended with "?" (or "&" when path already contains a "?"). Array query values are emitted as repeated keys.

Returns:

  • (String) 


49
50
51
52
53
54
55
 
# File 'lib/nfe/http/request.rb', line 49

def url
  base = base_url.chomp("/") + path
  return base if query.nil? || query.empty?

  separator = base.include?("?") ? "&" : "?"
  "#{base}#{separator}#{URI.encode_www_form(query)}"
end