Documentation
¶
Overview ¶
Package client provides an HTTP client with automatic 402 Payment Required handling.
Package client provides the generic HTTP 402 retry transport used by MPP payment methods.
Examples import this package by its bare name. The Tempo charge package uses the alias `charge`, so there is no conflict.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ChallengeCandidate ¶ added in v0.5.0
type ChallengeCandidate struct {
Challenge *mpp.Challenge
Method Method
// Quality is the payment preference q-value that ranked the Challenge.
Quality float64
}
ChallengeCandidate pairs an offered Challenge with a configured Method that can pay it.
func SelectChallengeCandidates ¶ added in v0.5.0
func SelectChallengeCandidates( challenges []mpp.Challenge, methods []Method, preferences PaymentPreferences, ) ([]ChallengeCandidate, error)
SelectChallengeCandidates returns the offered Challenges that methods can pay, ranked like the HTTP Transport ranks them: by payment preference, then in offer order. Expired Challenges, Challenges no method handles and Challenges with q=0 are left out. Transports other than HTTP, such as MCP, use it to pick the Challenge to pay. Unknown preference keys and invalid q-values return an error.
type ChallengeMatcher ¶ added in v0.4.0
ChallengeMatcher may be implemented by a Method that only handles some challenges for its method and intent. It allows multiple handlers for the same method and intent to select between method-specific request details.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is an HTTP client with automatic 402 payment handling.
func (*Client) Do ¶
Do sends an HTTP request, handling 402 responses automatically. If a 402 is received with a WWW-Authenticate: Payment header, it finds a matching method, creates credentials, and retries.
type Method ¶
type Method interface {
// Name returns the method name this handler supports (e.g., "tempo").
Name() string
// Intent returns the payment intent this handler supports (e.g., "charge").
Intent() string
// CreateCredential creates a payment credential for the given challenge.
CreateCredential(ctx context.Context, challenge *mpp.Challenge) (*mpp.Credential, error)
}
Method is the interface that payment methods must implement for client-side use.
type OnChallengeFunc ¶ added in v0.4.0
type OnChallengeFunc func( ctx context.Context, challenge *mpp.Challenge, createCredential func(ctx context.Context) (*mpp.Credential, error), ) (*mpp.Credential, error)
OnChallengeFunc is called when the transport has selected a 402 challenge it can pay, before any credential is created. It mirrors mppx's onChallenge.
createCredential creates a credential with the selected method; ctx can carry method-specific context for this request. It runs the method at most once per challenge: later calls return the first result. The hook can:
- return (nil, nil) to let the transport create the credential itself, or to use the one createCredential already made,
- return a credential, from createCredential or built another way, to send it,
- return an error to decline the payment: RoundTrip returns that error, wrapped, and does not pay.
It runs once per challenge: a credential the transport already created for the same challenge is reused without calling it again.
type Option ¶
type Option func(*Client)
Option configures the Client.
func WithHTTPClient ¶
WithHTTPClient sets a custom http.Client.
func WithOnChallenge ¶ added in v0.4.0
func WithOnChallenge(onChallenge OnChallengeFunc) Option
WithOnChallenge sets a hook that runs when Do receives a 402 challenge it can pay, before a credential is created. Use it to approve or decline a payment or to supply the credential. See OnChallengeFunc.
func WithPaymentPreferences ¶ added in v0.4.0
func WithPaymentPreferences(preferences PaymentPreferences) Option
WithPaymentPreferences sets client payment preferences. The preferences are advertised in Accept-Payment and used to rank server challenges. Unknown keys and invalid q-values cause Do to fail before sending the request.
func WithTrustedTempoProofRealm ¶ added in v0.4.0
WithTrustedTempoProofRealm pins the proof realm of a server at a known origin. Use this when the server's configured realm differs from its public hostname.
type PaymentOutcomeUnknownError ¶ added in v0.5.1
type PaymentOutcomeUnknownError struct {
// Challenge is the challenge the credential paid for. For a credential
// the caller set on the request, it holds the challenge fields the
// credential echoes (the request in RequestB64), or is nil when the
// credential cannot be parsed.
Challenge *mpp.Challenge
// Credential is the credential sent with the failed request, or nil
// when a caller-set credential cannot be parsed.
Credential *mpp.Credential
// Err is the error the paid request failed with.
Err error
}
PaymentOutcomeUnknownError is returned by Transport.RoundTrip, and so by Client.Do wrapped in a *url.Error, when the request carrying a payment credential failed without a response. That includes a credential the caller set on the request itself (any header whose value uses the Payment scheme). The server may have settled the payment, so do not blindly retry: reconcile it using Challenge and Credential. It matches mppx's PaymentOutcomeUnknownError.
When an http.Client with a Timeout times out, net/http replaces the RoundTrip error with its own timeout error, so a bare Transport inside such a client cannot preserve this type. client.Client restores it: its Do returns a *url.Error whose Err is a PaymentOutcomeUnknownError wrapping the timeout, and Timeout still reports true.
func (*PaymentOutcomeUnknownError) Error ¶ added in v0.5.1
func (e *PaymentOutcomeUnknownError) Error() string
func (*PaymentOutcomeUnknownError) Timeout ¶ added in v0.5.1
func (e *PaymentOutcomeUnknownError) Timeout() bool
Timeout reports whether the paid request failed because it timed out.
func (*PaymentOutcomeUnknownError) Unwrap ¶ added in v0.5.1
func (e *PaymentOutcomeUnknownError) Unwrap() error
Unwrap returns the error the paid request failed with.
type PaymentPreferences ¶ added in v0.4.0
PaymentPreferences assigns HTTP q-values to configured payment methods. Keys use the "method/intent" form. Omitted methods default to q=1.
type Transport ¶
type Transport struct {
// contains filtered or unexported fields
}
Transport is an http.RoundTripper that handles 402 Payment Required responses. It wraps an inner transport and automatically negotiates payment.
func NewTransport ¶
func NewTransport(methods []Method, inner http.RoundTripper, opts ...TransportOption) *Transport
NewTransport creates a payment-aware transport.
type TransportOption ¶ added in v0.4.0
type TransportOption func(*transportConfig)
TransportOption configures a Transport.
func WithTransportOnChallenge ¶ added in v0.4.0
func WithTransportOnChallenge(onChallenge OnChallengeFunc) TransportOption
WithTransportOnChallenge sets a hook that runs before the transport creates a credential for a 402 challenge. Client users should use WithOnChallenge.
func WithTransportPaymentPreferences ¶ added in v0.4.0
func WithTransportPaymentPreferences(preferences PaymentPreferences) TransportOption
WithTransportPaymentPreferences sets payment preferences on a standalone Transport. Client users should use WithPaymentPreferences instead. Unknown keys and invalid q-values cause RoundTrip to fail before sending the request.
func WithTransportTrustedProofRealm ¶ added in v0.4.0
func WithTransportTrustedProofRealm(origin, realm string) TransportOption
WithTransportTrustedProofRealm pins the Tempo proof realm for a known HTTP origin. The origin must include scheme and host (and port, when non-default).
Source Files