Documentation
¶
Index ¶
Constants ¶
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)
}
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
}
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)
type Client ¶
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. 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) WithAuthorization ¶
func (c Client) WithAuthorization(auth Authorization) AuthorizedClient
type Error ¶
Error represents an HTTP error response with status code. This error is returned when an HTTP request fails with a non-2XX status code.
func (Error) IsConflict ¶
IsConflict returns true if the error is a 409 Conflict response.
func (Error) IsForbidden ¶
IsForbidden returns true if the error is a 403 Forbidden response.
func (Error) IsNotFound ¶
IsNotFound returns true if the error is a 404 Not Found response.
func (Error) IsUnauthorized ¶
IsUnauthorized returns true if the error is a 401 Unauthorized response.
type ExponentialBackoff ¶
ExponentialBackoff increases the backoff exponentially: minWait * 2^(attempt-1).
type RequestOption ¶
type RequestOption func(opts *requestOptions)
RequestOption is a functional option for configuring HTTP requests.
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 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 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 adds URL query parameters from a query value.
The given value is JSON-marshalled and decoded into a flat map, so each field becomes a query param named by its `json` tag. A struct passed by value is the common case: its zero-value fields are dropped (an implicit `omitempty`), so an unset filter needs neither a pointer nor an `omitempty` tag and a zero-value struct adds no params at all. A map[string]string / map[string]any is taken verbatim — every entry is sent, including deliberate zero values such as page=0.
A value goes in as the JSON literal it marshalled to, with a string unquoted; nested objects or arrays are not supported.
type RetryBackoff ¶
RetryBackoff calculates the duration to wait before the next retry attempt.
type RetryOptions ¶
type RetryOptions struct {
// MaxRetries limits the attempts to retries. If zero, retries will never be attempted.
MaxRetries int
// Backoff to use when retrying. If nil, retries will never be attempted.
Backoff RetryBackoff
}
Source Files