Class: Anthropic::APIRequest

Inherits:
Object
  • Object
show all
Defined in:
lib/anthropic/middleware.rb

Overview

The per-attempt request object a middleware sees.

Fields mirror what resource methods pass to ‘BaseClient#request` (see `RequestComponents`), with `path`/`query` resolved to a `URI::Generic`, headers fully normalized, and `retry_count`/`metadata` added.

‘body` is the canonical Anthropic request body — for JSON endpoints (`POST /v1/messages` etc.) a `Hash` like `messages:, max_tokens:`, `nil` for body-less methods. It is not a serialized `String`: JSON encoding, 3p-provider rewrite (Bedrock/Vertex), and request signing all happen inside `nxt.call`, so a middleware that edits `body` via `req.with(body: …)` does not need to re-serialize.

Instances are frozen and the ‘headers`/`body`/`url`/`options` values the SDK supplies are deep-frozen — mutating them or any nested `Hash`/`Array` (e.g. `body`) raises. Use #with to derive a copy. `metadata` is the one intentionally shared, mutable scratchpad that persists across retry attempts.

Constant Summary collapse

MEMBERS =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

[:method, :url, :headers, :body, :stream, :cast_to, :unwrap, :options, :retry_count, :metadata].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(method:, url:, headers:, body:, stream:, cast_to:, unwrap:, options:, retry_count:, metadata:) ⇒ APIRequest

Returns a new instance of APIRequest.

Parameters:

  • method (Symbol)
  • url (URI::Generic)
  • headers (Hash{String=>String})
  • body (Object, nil)
  • stream (Class, nil)
  • cast_to (Anthropic::Internal::Type::Converter::Input, nil)
  • unwrap (Symbol, Integer, Array<Symbol, Integer>, Proc, nil)
  • options (Hash{Symbol=>Object})
  • retry_count (Integer)
  • metadata (Hash{Symbol=>Object}) 


76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/anthropic/middleware.rb', line 76

def initialize(
  method:,
  url:,
  headers:,
  body:,
  stream:,
  cast_to:,
  unwrap:,
  options:,
  retry_count:,
  metadata:
)
  @method = method
  @url = url
  @headers = headers
  @body = body
  @stream = stream
  @cast_to = cast_to
  @unwrap = unwrap
  @options = options
  @retry_count = retry_count
  @metadata = metadata
  freeze
end

Instance Attribute Details

#body ⇒ Object? (readonly)

Returns the canonical request body — usually a ‘HashSymbol=>Object` for JSON endpoints, `nil` for body-less, but may be a `String`/`IO` for upload paths (see class doc; deep-frozen where structurally copyable).

Returns:

  • (Object, nil) —

    the canonical request body — usually a ‘HashSymbol=>Object` for JSON endpoints, `nil` for body-less, but may be a `String`/`IO` for upload paths (see class doc; deep-frozen where structurally copyable)



40
41
42
 
# File 'lib/anthropic/middleware.rb', line 40

def body
  @body
end

#cast_to ⇒ Anthropic::Internal::Type::Converter::Input? (readonly)

Returns the model class the response body will be coerced to; ‘nil` for paginated requests.

Returns:

  • (Anthropic::Internal::Type::Converter::Input, nil) —

    the model class the response body will be coerced to; ‘nil` for paginated requests



49
50
51
 
# File 'lib/anthropic/middleware.rb', line 49

def cast_to
  @cast_to
end

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

Returns normalized request headers (deep-frozen).

Returns:

  • (Hash{String=>String}) —

    normalized request headers (deep-frozen)



34
35
36
 
# File 'lib/anthropic/middleware.rb', line 34

def headers
  @headers
end

#metadata ⇒ Hash{Symbol=>Object} (readonly)

Returns mutable cross-attempt scratchpad shared between retries.

Returns:

  • (Hash{Symbol=>Object}) —

    mutable cross-attempt scratchpad shared between retries



64
65
66
 
# File 'lib/anthropic/middleware.rb', line 64

def metadata
  @metadata
end

#method ⇒ Symbol (readonly)

Returns the HTTP method (‘:get`, `:post`, …).

Returns:

  • (Symbol) —

    the HTTP method (‘:get`, `:post`, …)



28
29
30
 
# File 'lib/anthropic/middleware.rb', line 28

def method
  @method
end

#options ⇒ Hash{Symbol=>Object} (readonly)

Returns request options (‘:timeout`, …; deep-frozen).

Returns:

  • (Hash{Symbol=>Object}) —

    request options (‘:timeout`, …; deep-frozen)



57
58
59
 
# File 'lib/anthropic/middleware.rb', line 57

def options
  @options
end

#retry_count ⇒ Integer (readonly)

Returns number of prior attempts (‘0` on the first).

Returns:

  • (Integer) —

    number of prior attempts (‘0` on the first)



60
61
62
 
# File 'lib/anthropic/middleware.rb', line 60

def retry_count
  @retry_count
end

#stream ⇒ Class? (readonly)

Returns the SSE stream class to decode into; ‘nil` for non-streaming.

Returns:

  • (Class, nil) —

    the SSE stream class to decode into; ‘nil` for non-streaming



44
45
46
 
# File 'lib/anthropic/middleware.rb', line 44

def stream
  @stream
end

#unwrap ⇒ Symbol, ... (readonly)

Returns the envelope key(s) the SDK digs out of the decoded body before coercing.

Returns:

  • (Symbol, Integer, Array<Symbol, Integer>, Proc, nil) —

    the envelope key(s) the SDK digs out of the decoded body before coercing



53
54
55
 
# File 'lib/anthropic/middleware.rb', line 53

def unwrap
  @unwrap
end

#url ⇒ URI::Generic (readonly)

Returns the resolved request URL (deep-frozen).

Returns:

  • (URI::Generic) —

    the resolved request URL (deep-frozen)



31
32
33
 
# File 'lib/anthropic/middleware.rb', line 31

def url
  @url
end

Instance Method Details

#retry? ⇒ Boolean

Returns whether this is a retry attempt (‘retry_count > 0`).

Returns:

  • (Boolean) —

    whether this is a retry attempt (‘retry_count > 0`)



105
 
# File 'lib/anthropic/middleware.rb', line 105

def retry? = @retry_count.positive?

#streaming? ⇒ Boolean

Returns whether the SDK call is a streaming/SSE request.

Returns:

  • (Boolean) —

    whether the SDK call is a streaming/SSE request



102
 
# File 'lib/anthropic/middleware.rb', line 102

def streaming? = !@stream.nil?

#timeout ⇒ Float

Returns the request timeout in seconds. Informational only — the transport deadline is fixed when the SDK enters the middleware terminal, so deriving a request via ‘with(options: …)` does not change it. Time spent inside middleware does not count against it.

Returns:

  • (Float) —

    the request timeout in seconds. Informational only — the transport deadline is fixed when the SDK enters the middleware terminal, so deriving a request via ‘with(options: …)` does not change it. Time spent inside middleware does not count against it.



111
 
# File 'lib/anthropic/middleware.rb', line 111

def timeout = @options.to_h.fetch(:timeout, 0.0)

#to_h ⇒ Hash{Symbol=>Object}

Returns:

  • (Hash{Symbol=>Object}) 


136
 
# File 'lib/anthropic/middleware.rb', line 136

def to_h = MEMBERS.to_h { [_1, instance_variable_get(:"@#{_1}")] }

#with(**changes) ⇒ Anthropic::APIRequest

Derive a copy with the given members replaced.

Parameters:

  • method (Symbol)
  • url (URI::Generic)
  • headers (Hash{String=>String})
  • body (Object, nil)
  • stream (Class, nil)
  • cast_to (Anthropic::Internal::Type::Converter::Input, nil)
  • unwrap (Symbol, Integer, Array<Symbol, Integer>, Proc, nil)
  • options (Hash{Symbol=>Object})
  • retry_count (Integer)
  • metadata (Hash{Symbol=>Object})

Returns:



126
127
128
129
130
131
132
133
 
# File 'lib/anthropic/middleware.rb', line 126

def with(**changes)
  unknown = changes.keys - MEMBERS
  unless unknown.empty?
    raise ArgumentError,
          "unknown keyword#{'s' if unknown.length > 1}: #{unknown.map(&:inspect).join(', ')}"
  end
  self.class.new(**to_h, **changes)
end