shared

Documentation

Index

• Constants
• Variables
• func ClientOrDefault(client *http.Client, headerTimeout time.Duration) *http.Client
• func CloneHTTPTransport(headerTimeout time.Duration) http.RoundTripper
• func DoWithRetry(ctx context.Context, client *http.Client, policy RetryPolicy, ...) (*http.Response, error)
• func IsEventStreamContentType(contentType string) bool
• func NewHTTPClient(headerTimeout time.Duration) *http.Client
• func NewIdempotencyKey() (string, error)
• func RejectCrossOriginRedirect(req *http.Request, via []*http.Request) error
• func RetryableStatus(status int) bool
• type Event
• type Reader
  • func NewReader(body io.Reader) *Reader
  • func (r *Reader) Next() (Event, error)
• type RetryPolicy

Constants

const (
	// MaxSSELineBytes caps one physical line.
	MaxSSELineBytes = 8 << 20
	// MaxSSEFrameBytes and MaxSSEFrameLines bound aggregate multi-line events.
	MaxSSEFrameBytes = 16 << 20
	MaxSSEFrameLines = 4096
)

Variables

var ErrCrossOriginRedirect = errors.New("http: cross-origin redirect rejected")

ErrCrossOriginRedirect is returned when an HTTP client refuses to follow a redirect to a different host or scheme. Custom headers such as x-api-key are not stripped by net/http on cross-origin redirects.

Functions

func ClientOrDefault

func ClientOrDefault(client *http.Client, headerTimeout time.Duration) *http.Client

ClientOrDefault returns client when non-nil, otherwise a streaming-safe default. Zero-value drivers that bypass New() must not fall back to http.DefaultClient (no timeouts).

func CloneHTTPTransport

func CloneHTTPTransport(headerTimeout time.Duration) http.RoundTripper

CloneHTTPTransport copies http.DefaultTransport when it is a *http.Transport; otherwise it builds a conservative default. A custom DefaultTransport that is not a *http.Transport is used as-is so New cannot panic at startup.

func DoWithRetry

func DoWithRetry(ctx context.Context, client *http.Client, policy RetryPolicy, build func() (*http.Request, error)) (*http.Response, error)

DoWithRetry issues the request produced by build via client, retrying transport errors and RetryableStatus responses with exponential backoff (honoring a numeric Retry-After header up to the policy cap). build runs once per attempt so request bodies stay re-readable. The final attempt's response or error is returned unmodified, so callers keep their own status handling; failed retryable bodies are drained and closed before the next attempt.

func IsEventStreamContentType

func IsEventStreamContentType(contentType string) bool

IsEventStreamContentType reports whether contentType is text/event-stream.

func NewHTTPClient

func NewHTTPClient(headerTimeout time.Duration) *http.Client

NewHTTPClient returns a streaming-safe client: no overall Timeout (the stream may be long-lived), a response-header timeout on the transport, and a CheckRedirect that refuses cross-origin hops so API keys cannot follow a 3xx off-origin.

func NewIdempotencyKey

func NewIdempotencyKey() (string, error)

NewIdempotencyKey returns an opaque key callers can retain across transport retries of one logical request.

func RejectCrossOriginRedirect

func RejectCrossOriginRedirect(req *http.Request, via []*http.Request) error

RejectCrossOriginRedirect is an http.Client.CheckRedirect that allows same-origin hops and rejects everything else.

func RetryableStatus

func RetryableStatus(status int) bool

RetryableStatus reports whether an HTTP status is a rate limit or server failure. Client errors other than 429 are deterministic request failures and must not be replayed.

Types

type Event

type Event struct {
	Name    string
	Data    string
	ID      string
	Comment string
}

Event represents a parsed Server-Sent Event frame.

type Reader

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

Reader incrementally parses SSE frames from a text stream.

func NewReader

func NewReader(body io.Reader) *Reader

func (*Reader) Next

func (r *Reader) Next() (Event, error)

Next reads and returns the next SSE frame. It properly handles:

• multi-line data: concatenated with '\n'
• event: and id: fields
• comment lines starting with ':' (used for keepalive heartbeats)
• incremental/incomplete frames buffered across scanner reads

type RetryPolicy

type RetryPolicy struct {
	// MaxAttempts is the total attempt count including the first call.
	// 0 means the default of 3; negative disables retrying.
	MaxAttempts int
	// BaseDelay is the wait before the first retry; it doubles on each
	// subsequent retry. 0 means 500ms.
	BaseDelay time.Duration
	// MaxDelay caps both the exponential backoff and any honored
	// Retry-After header. 0 means 4s.
	MaxDelay time.Duration
	// Jitter transforms each exponential delay before a server Retry-After
	// minimum is applied. Nil applies equal jitter in [delay/2, delay].
	// Use an identity function for deterministic delays.
	Jitter func(time.Duration) time.Duration
}

RetryPolicy bounds DoWithRetry. The zero value retries transient failures up to 3 total attempts with equal jitter over an exponential 500ms base delay, capped at 4s. MaxAttempts < 0 disables retrying entirely (a single attempt); values above 10 are clamped to prevent retry storms.