transport

Documentation

Overview

Package transport is the HTTP plumbing shared by every gateway: JSON, form and raw calls with timeout, retry, logging and header handling.

It is internal on purpose. Applications configure it through github.com/amiranmanesh/payvand/core.Options and never import it.

Index

• func JoinURL(base, path string) string
• type Client
  • func New(opts *core.Options) *Client
  • func (c *Client) Do(ctx context.Context, method, endpoint string, body []byte, ...) (Response, error)
  • func (c *Client) Form(ctx context.Context, endpoint string, values url.Values, ...) (Response, error)
  • func (c *Client) JSON(ctx context.Context, method, endpoint string, body any, ...) (Response, error)
  • func (c *Client) NoRetry() *Client
• type Response
  • func (r Response) OK() bool

Functions

func JoinURL

func JoinURL(base, path string) string

JoinURL concatenates a base URL and a path without doubling the slash. It is how gateways honour core.Options.BaseURL overrides.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client performs the outgoing HTTP calls of a gateway.

func New

func New(opts *core.Options) *Client

New builds a client from the resolved options. When the caller did not supply an HTTP client, a dedicated one is created with the configured timeout and TLS settings.

func (*Client) Do

func (c *Client) Do(ctx context.Context, method, endpoint string, body []byte, headers map[string]string) (Response, error)

Do performs a single call with the configured retry policy and returns the raw response.

func (*Client) Form

func (c *Client) Form(ctx context.Context, endpoint string, values url.Values, headers map[string]string, out any) (Response, error)

Form sends values as application/x-www-form-urlencoded and decodes a JSON response into out when out is not nil.

func (*Client) JSON

func (c *Client) JSON(ctx context.Context, method, endpoint string, body any, headers map[string]string, out any) (Response, error)

JSON sends body as JSON and decodes the response into out when out is not nil. A non-2xx status is returned to the caller instead of being turned into an error, because several Iranian gateways carry their business errors in the body of a 4xx response.

func (*Client) NoRetry

func (c *Client) NoRetry() *Client

NoRetry returns a copy of the client that calls exactly once, whatever the retry policy says.

A retry is safe when the worst case is asking the same question twice, which is true of creating a payment token or verifying one: both are keyed by an order or a token the provider recognises. It is not true of moving money back. A reversal that succeeded and then lost its answer to a timeout would be sent a second time, and the providers that do not deduplicate reversals would return the payment twice.

type Response

type Response struct {
	// StatusCode is the HTTP status code.
	StatusCode int
	// Body is the raw response body.
	Body string
	// Header is the response header.
	Header http.Header
}

Response is the outcome of one call, kept as raw text so gateways can put it in core.PurchaseResponse.Raw for support and auditing.

func (Response) OK

func (r Response) OK() bool

OK reports whether the HTTP status is in the 2xx range.