Docs / Reference / API

API reference

This is the canonical reference for Pebble's public API. For a more discursive introduction, see the Quick start.

Client

type Client struct { /* unexported */ }

// New constructs a Client with the supplied Options. Any zero-valued
// fields in opts are filled with sensible defaults; see Defaults.
func New(opts Options) *Client

A Client is safe for concurrent use by multiple goroutines. The zero value is not useful; always construct one with New.

Options

type Options struct {
    // Timeout is the maximum total duration of a single request,
    // including all retries. Zero means use DefaultTimeout (30s).
    Timeout time.Duration

    // MaxRetries is the maximum number of retry attempts on
    // transient failures. Zero means no retries. Default is 3.
    MaxRetries int

    // BackoffStrategy controls how delays are computed between
    // retries. Nil means use DefaultBackoff (exponential with jitter).
    BackoffStrategy BackoffStrategy

    // Transport is the underlying http.RoundTripper. If nil, a
    // sensibly-configured *http.Transport is used.
    Transport http.RoundTripper

    // EnableTracing turns on OpenTelemetry instrumentation.
    // Default is false.
    EnableTracing bool

    // Logger is the structured logger for client-level events.
    // If nil, logging is disabled.
    Logger Logger
}

Methods

Get

func (c *Client) Get(ctx context.Context, url string) (*http.Response, error)

Performs a GET request with the configured retry, timeout, and tracing behaviour. The returned *http.Response has the same semantics as net/http; the caller is responsible for closing the body.

Post

func (c *Client) Post(ctx context.Context, url string, body io.Reader, contentType string) (*http.Response, error)

Posts the supplied body with the given content type. Retries are subject to the request being idempotent; by default, POST is not retried on transient failures. See Retries and backoff.

Do

func (c *Client) Do(req *http.Request) (*http.Response, error)

Executes an arbitrary request. The request's Context must be set; Pebble does not use a default context. This is the lowest-level method on the Client.

Errors

Pebble defines structured error types in the pebbleerrors subpackage. All errors returned by Client methods can be unwrapped to one of these types using errors.As:

• *pebbleerrors.TimeoutError — the request did not complete within the configured timeout.
• *pebbleerrors.RetryExhaustedError — the request failed after all retry attempts.
• *pebbleerrors.HTTPError — the server returned a non-2xx response that we couldn't or wouldn't retry.
• *pebbleerrors.TransportError — a lower-level transport-layer error (DNS, connection refused, etc.).

Each error type includes structured fields suitable for logging and metrics. See the Error handling guide for examples.