Class: Dinie::Internal::RequestOptions

Inherits:
Object
  • Object
show all
Defined in:
lib/dinie/runtime/request_options.rb,
sig/dinie/runtime/request_options.rbs

Overview

Normalized per-call options, the trailing request_options: Hash every public method accepts (architecture §12, RB5). Validates types up front and freezes; the actual header merge against the client defaults (where a nil value removes a default) and the timeout/retry wiring happen in the transport (story 003).

Examples:

Dinie::Internal::RequestOptions.coerce(timeout: 5, headers: { "x-trace" => "abc" })

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(timeout: nil, idempotency_key: nil, headers: nil, max_retries: nil) ⇒ RequestOptions

Returns a new instance of RequestOptions.

Parameters:

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

    seconds; must be a non-negative Numeric

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

    values must be String or nil

  • max_retries (Integer, nil) (defaults to: nil) —

    must be a non-negative Integer

  • timeout: (Numeric, nil) (defaults to: nil)
  • idempotency_key: (String, nil) (defaults to: nil)
  • headers: (Hash[untyped, untyped], nil) (defaults to: nil)
  • max_retries: (Integer, nil) (defaults to: nil)

Raises:

  • (ArgumentError) —

    on an invalid value type



39
40
41
42
43
44
45
 
# File 'lib/dinie/runtime/request_options.rb', line 39

def initialize(timeout: nil, idempotency_key: nil, headers: nil, max_retries: nil)
  @timeout = validate_timeout(timeout)
  @idempotency_key = validate_string(idempotency_key, :idempotency_key)
  @headers = validate_headers(headers)
  @max_retries = validate_max_retries(max_retries)
  freeze
end

Instance Attribute Details

#headers ⇒ Hash{String => String, nil}? (readonly)

Returns per-call header overrides (a nil value removes a default).

Returns:

  • (Hash{String => String, nil}, nil) —

    per-call header overrides (a nil value removes a default)



18
19
20
 
# File 'lib/dinie/runtime/request_options.rb', line 18

def headers
  @headers
end

#idempotency_key ⇒ String? (readonly)

Returns explicit idempotency key (overrides the auto-generated one).

Returns:

  • (String, nil) —

    explicit idempotency key (overrides the auto-generated one)



16
17
18
 
# File 'lib/dinie/runtime/request_options.rb', line 16

def idempotency_key
  @idempotency_key
end

#max_retries ⇒ Integer? (readonly)

Returns per-call retry budget override.

Returns:

  • (Integer, nil) —

    per-call retry budget override



20
21
22
 
# File 'lib/dinie/runtime/request_options.rb', line 20

def max_retries
  @max_retries
end

#timeout ⇒ Numeric? (readonly)

Returns per-call timeout, in seconds.

Returns:

  • (Numeric, nil) —

    per-call timeout, in seconds



14
15
16
 
# File 'lib/dinie/runtime/request_options.rb', line 14

def timeout
  @timeout
end

Class Method Details

.coerce(value) ⇒ RequestOptions

Pass a RequestOptions through, or build one from a Hash (string/symbol keys; nil → empty). Param is untyped: the body branches on value.is_a?(self), which Steep cannot narrow on a union, so a precise union would mis-type the Hash branch.

Parameters:

  • value (Object)

Returns:



28
29
30
31
32
 
# File 'lib/dinie/runtime/request_options.rb', line 28

def self.coerce(value)
  return value if value.is_a?(self)

  new(**(value || {}).transform_keys(&:to_sym))
end

Instance Method Details

#==(other) ⇒ Boolean Also known as: eql?

Parameters:

  • other (Object)

Returns:

  • (Boolean) 


55
56
57
 
# File 'lib/dinie/runtime/request_options.rb', line 55

def ==(other)
  other.is_a?(RequestOptions) && other.to_h == to_h
end

#hash ⇒ Integer

Returns:

  • (Integer) 


61
62
63
 
# File 'lib/dinie/runtime/request_options.rb', line 61

def hash
  to_h.hash
end

#to_h ⇒ Hash{Symbol => Object} Also known as: to_hash

Returns the normalized options.

Returns:

  • (Hash{Symbol => Object}) —

    the normalized options



48
49
50
 
# File 'lib/dinie/runtime/request_options.rb', line 48

def to_h
  { timeout: timeout, idempotency_key: idempotency_key, headers: headers, max_retries: max_retries }
end

#validate_headers(value) ⇒ Hash[String, String?]?

Parameters:

  • value (Object)

Returns:

  • (Hash[String, String?], nil)

Raises:

  • (ArgumentError) 


96
97
98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/dinie/runtime/request_options.rb', line 96

def validate_headers(value)
  return nil if value.nil?
  raise ArgumentError, "request_options[:headers] must be a Hash, got #{value.inspect}" unless value.is_a?(Hash)

  value.each_with_object({}) do |(key, header_value), acc|
    unless header_value.nil? || header_value.is_a?(String)
      raise ArgumentError,
            "request_options[:headers] values must be String or nil (nil removes a default), " \
            "got #{header_value.inspect} for #{key.inspect}"
    end

    acc[key.to_s] = header_value
  end
end

#validate_max_retries(value) ⇒ Integer?

Parameters:

  • value (Object)

Returns:

  • (Integer, nil) 


77
78
79
80
81
82
83
84
 
# File 'lib/dinie/runtime/request_options.rb', line 77

def validate_max_retries(value)
  return nil if value.nil?
  unless value.is_a?(Integer) && !value.negative?
    raise ArgumentError, "request_options[:max_retries] must be a non-negative Integer, got #{value.inspect}"
  end

  value
end

#validate_string(value, key) ⇒ String?

Parameters:

  • value (Object)
  • key (Symbol)

Returns:

  • (String, nil) 


86
87
88
89
90
91
92
93
94
 
# File 'lib/dinie/runtime/request_options.rb', line 86

def validate_string(value, key)
  return nil if value.nil?
  unless value.is_a?(String)
    raise ArgumentError,
          "request_options[:#{key}] must be a String, got #{value.inspect}"
  end

  value
end

#validate_timeout(value) ⇒ Numeric?

Parameters:

  • value (Object)

Returns:

  • (Numeric, nil) 


67
68
69
70
71
72
73
74
75
 
# File 'lib/dinie/runtime/request_options.rb', line 67

def validate_timeout(value)
  return nil if value.nil?
  unless value.is_a?(Numeric) && !value.negative?
    raise ArgumentError,
          "request_options[:timeout] must be a non-negative Numeric (seconds), got #{value.inspect}"
  end

  value
end