Skip to content

Class BSV::Auth::AuthFetch

Inherits: Object

BRC-104 high-level client for authenticated HTTP requests.

Manages a pool of {Peer} instances (one per base URL) and serialises HTTP requests as BRC-104 binary payloads. The handshake is initiated automatically on the first request to each base URL.

When the server responds with HTTP 402 Payment Required, AuthFetch automatically constructs a BSV payment transaction via the wallet and retries the original request with an x-bsv-payment header attached.

Thread safety: the +@peers+ hash is protected by a mutex. Each in-flight request uses its own Queue to receive exactly the matching response.

@example 

client = BSV::Auth::AuthFetch.new(wallet: my_wallet)
response = client.fetch('https://api.example.com/resource')
puts response.status   # => 200
puts response.body     # => "..."

Constants

DEFAULT_PAYMENT_RETRIES

Not documented.

DEFAULT_TIMEOUT

Not documented.

PAYMENT_PROTOCOL_ID

Not documented.

PAYMENT_RETRY_DELAY_MS

Not documented.

SUPPORTED_PAYMENT_VERSION

Not documented.

Public Instance Methods

fetch(url, method: = 'GET', headers: = {}, body: = nil, timeout: = DEFAULT_TIMEOUT)

Sends an authenticated HTTP request to url.

The first request to a new base URL performs a BRC-103 mutual-auth handshake automatically. Subsequent requests reuse the cached peer.

If the server responds with 402, a BSV payment is created and the request is retried with an x-bsv-payment header (up to payment_max_retries times). - @param url [String] full URL including scheme, host, optional port, path, and query - @param method [String] HTTP method (default 'GET') - @param headers [Hash] request headers; only +content-type+, +authorization+, and +x-bsv-+ (excluding +x-bsv-auth-+) are allowed - @param body [String, Hash, nil] request body - @param timeout [Integer] seconds to wait for the authenticated response (default 30) - @raise [ArgumentError] if disallowed headers are provided - @raise [Timeout::Error] if no response arrives within +timeout+ seconds - @raise [AuthError] if 402 payment handling fails or max retries are exceeded - @return [AuthResponse]

initialize(wallet:, requested_certificates: = nil, session_manager: = nil, payment_max_retries: = DEFAULT_PAYMENT_RETRIES)

  • @param wallet [BSV::Wallet::Interface] wallet for crypto operations
  • @param requested_certificates [Hash, nil] certificate set to request from peers
  • @param session_manager [SessionManager, nil] optional shared session store
  • @param payment_max_retries [Integer] maximum number of payment retry attempts (default 3)
  • @return [AuthFetch] a new instance of AuthFetch