Class: BSV::Auth::AuthFetch

Inherits:
Object
  • Object
show all
Defined in:
lib/bsv/auth/auth_fetch.rb

Overview

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.

Examples:

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

Constant Summary collapse

DEFAULT_TIMEOUT = 
30
DEFAULT_PAYMENT_RETRIES = 
3
PAYMENT_RETRY_DELAY_MS = 
250
PAYMENT_PROTOCOL_ID = 
[2, '3241645161d8'].freeze
SUPPORTED_PAYMENT_VERSION = 
'1.0'

Instance Method Summary collapse

Constructor Details

#initialize(wallet:, requested_certificates: nil, session_manager: nil, payment_max_retries: DEFAULT_PAYMENT_RETRIES) ⇒ AuthFetch

Returns a new instance of AuthFetch.

Parameters:

  • wallet (BSV::Wallet::Interface) —

    wallet for crypto operations

  • requested_certificates (Hash, nil) (defaults to: nil) —

    certificate set to request from peers

  • session_manager (SessionManager, nil) (defaults to: nil) —

    optional shared session store

  • payment_max_retries (Integer) (defaults to: DEFAULT_PAYMENT_RETRIES) —

    maximum number of payment retry attempts (default 3)



40
41
42
43
44
45
46
47
 
# File 'lib/bsv/auth/auth_fetch.rb', line 40

def initialize(wallet:, requested_certificates: nil, session_manager: nil, payment_max_retries: DEFAULT_PAYMENT_RETRIES)
  @wallet                 = wallet
  @requested_certificates = requested_certificates
  @session_manager        = session_manager
  @payment_max_retries    = payment_max_retries
  @peers                  = {}
  @peers_mutex            = Mutex.new
end

Instance Method Details

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

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).

Parameters:

  • url (String) —

    full URL including scheme, host, optional port, path, and query

  • method (String) (defaults to: 'GET') —

    HTTP method (default ‘GET’)

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

    request headers; only content-type, authorization, and x-bsv-* (excluding x-bsv-auth-*) are allowed

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

    request body

  • timeout (Integer) (defaults to: DEFAULT_TIMEOUT) —

    seconds to wait for the authenticated response (default 30)

Returns:

Raises:

  • (ArgumentError) —

    if disallowed headers are provided

  • (Timeout::Error) —

    if no response arrives within timeout seconds

  • (AuthError) —

    if 402 payment handling fails or max retries are exceeded



68
69
70
71
 
# File 'lib/bsv/auth/auth_fetch.rb', line 68

def fetch(url, method: 'GET', headers: {}, body: nil, timeout: DEFAULT_TIMEOUT)
  do_fetch(url, method: method, headers: headers, body: body, timeout: timeout,
                retry_count: 0, payment_context: nil)
end