Help us shape the future of Go! Take the 2026 Go Developer Survey

http

package
v0.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 28, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	MethodGet    = gohttp.MethodGet
	MethodPost   = gohttp.MethodPost
	MethodPut    = gohttp.MethodPut
	MethodDelete = gohttp.MethodDelete
)

The request methods this repository sends, re-exported so that a caller of DoRequest needs no second import for them. Add one here when a caller starts sending it.

Variables

This section is empty.

Functions

This section is empty.

Types

type Authorization 

type Authorization interface {
	GetBearerToken(ctx context.Context) (BearerToken, error)

	// RefreshBearerToken returns the token that replaces the rejected one. Returning the
	// rejected token unchanged tells the caller that there is nothing new to try.
	RefreshBearerToken(ctx context.Context, rejected BearerToken) (BearerToken, error)

	// Scope names what meshStack grants access by, so that a 403 says it. Empty names nothing.
	Scope() string
}

Authorization produces the bearer token for each request. An implementation renews the token it holds once that token is close to expiry, so that AuthorizedClient.DoRequest only has to handle the 401 a token lost earlier than expected.

type AuthorizedClient 

type AuthorizedClient struct {
	Client

	Authorization Authorization
}

func (AuthorizedClient) Authorize added in v0.4.0 

func (c AuthorizedClient) Authorize(r *gohttp.Request) error

Authorize is for a request that this client does not send itself, such as one a reverse proxy passes on. Such a request gets no second try after a 401.

func (AuthorizedClient) DoRequest 

func (c AuthorizedClient) DoRequest[R any](ctx context.Context, method string, url *url.URL, options ...RequestOption) (R, error)

type BearerToken 

type BearerToken string

BearerToken is both the token Authorization produces and an Authorization of its own, for a caller that holds one static token.

func (BearerToken) GetBearerToken 

func (token BearerToken) GetBearerToken(_ context.Context) (BearerToken, error)

func (BearerToken) RefreshBearerToken 

func (token BearerToken) RefreshBearerToken(_ context.Context, _ BearerToken) (BearerToken, error)

func (BearerToken) Scope added in v0.4.0 

func (token BearerToken) Scope() string

type Client 

type Client struct {
	*gohttp.Client

	UserAgent UserAgent
}

func NewClient 

func NewClient(userAgent UserAgent) Client

NewClient panics on a UserAgent that does not validate, as a request has to name its front end.

func (Client) DoRequest 

func (c Client) DoRequest[R any](ctx context.Context, method string, url *url.URL, options ...RequestOption) (result R, err error)

DoRequest sends one request and parses the answer as JSON, or returns it as it came, empty included, for an R of []byte. A non-2xx status is an Error that carries the response body, because an OIDC endpoint answers a refusal with an error document and that document is the only thing saying which refusal it was.

func (Client) Download added in v0.3.0 

func (c Client) Download(ctx context.Context, url *url.URL, path string, options ...DownloadOption) (wait func(), err error)

Download waits at most waitForNewerDownload for a newer document where path holds one already. After that, the caller reads the stored document, and wait lets the download finish for the next command.

func (Client) WithAuthorization 

func (c Client) WithAuthorization(auth Authorization) AuthorizedClient

type DownloadOption added in v0.3.0 

type DownloadOption func(opts *downloadOptions)

func WithConditionalGet added in v0.3.0 

func WithConditionalGet(conditionalGet bool) DownloadOption

WithConditionalGet asks for a newer document on every download. Without it, Download asks once per downloadCheckInterval, to save the round trip.

type Error 

type Error struct {
	StatusCode   int
	ResponseBody []byte
}

func (Error) Error 

func (e Error) Error() string

func (Error) IsClientError added in v0.3.0 

func (e Error) IsClientError() bool

func (Error) IsConflict 

func (e Error) IsConflict() bool

func (Error) IsForbidden 

func (e Error) IsForbidden() bool

func (Error) IsLocked added in v0.4.0 

func (e Error) IsLocked() bool

func (Error) IsNotFound 

func (e Error) IsNotFound() bool

func (Error) IsUnauthorized 

func (e Error) IsUnauthorized() bool

type ExponentialBackoff 

type ExponentialBackoff struct {
	MinWait, MaxWait time.Duration
}

func (ExponentialBackoff) Calculate 

func (b ExponentialBackoff) Calculate(attempt int) time.Duration

type RequestOption 

type RequestOption func(opts *requestOptions)

func Retryable 

func Retryable() RequestOption

Retryable declares that replaying this request cannot do harm, which is the only way a method other than GET is ever retried. meshStack's /api/login is the case it exists for: it mints a token and invalidates nothing, so a replay after a gateway 503 costs one token.

Never put it on an OIDC refresh grant: that grant rotates the refresh token, and keycloak ends the whole session when a rotated token is used twice.

func WithAccept 

func WithAccept(accept string) RequestOption

func WithBody added in v0.3.0 

func WithBody(body []byte) RequestOption

WithBody sends the bytes as they are, so the caller names their type in a Content-Type header.

func WithFormPayload 

func WithFormPayload(payload any) RequestOption

WithFormPayload sends the values as an url-encoded form body — converted from a struct or a map as WithUrlQuery describes — and asks for JSON in return, which is what an OIDC grant expects.

func WithHeaders added in v0.3.0 

func WithHeaders(header gohttp.Header) RequestOption

func WithJsonPayload 

func WithJsonPayload(payload any, contentType string) RequestOption

WithJsonPayload sends a value as a JSON body, and both sends and asks for the given content type. The type is a parameter because meshStack names a meshObject's kind and version in it.

func WithUrlQuery 

func WithUrlQuery(query any) RequestOption

WithUrlQuery sends each field of query as a query parameter named by its `json` tag. A struct passed by value leaves out every field that has the zero value, so an unset filter needs neither a pointer nor `omitempty`. A map is sent as given, so a deliberate zero such as page=0 stays. Each value is sent as the JSON literal it marshals to, with a string unquoted, and an array as the parameter repeated. Nested objects are not supported.

type RetryBackoff 

type RetryBackoff interface {
	Calculate(attempt int) time.Duration
}

type RetryOptions 

type RetryOptions struct {
	MaxRetries int
	Backoff    RetryBackoff
}

func (RetryOptions) ApplyTo 

func (options RetryOptions) ApplyTo(c *gohttp.Client)

ApplyTo makes the given client retry a GET on its own, and any other method only where the caller marked the request with Retryable.

type UserAgent added in v0.4.0 

type UserAgent struct {
	// GitHubRepo is "<org>/<repo>", whose releases are checked for a newer one.
	GitHubRepo string
	Version    string
}

UserAgent names the front end that sends a request, as "<repo>/<version>", such as meshstack-cli/v0.9.0.

func (UserAgent) String added in v0.4.0 

func (u UserAgent) String() string

func (UserAgent) Validate added in v0.4.0 

func (u UserAgent) Validate() error

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.