Documentation
¶
Index ¶
- Constants
- type Authorization
- type AuthorizedClient
- type BearerToken
- type Client
- func (c Client) DoRequest[R any](ctx context.Context, method string, url *url.URL, options ...RequestOption) (result R, err error)
- func (c Client) Download(ctx context.Context, url *url.URL, path string, options ...DownloadOption) (wait func(), err error)
- func (c Client) WithAuthorization(auth Authorization) AuthorizedClient
- type DownloadOption
- type Error
- type ExponentialBackoff
- type RequestOption
- func Retryable() RequestOption
- func WithAccept(accept string) RequestOption
- func WithBody(body []byte) RequestOption
- func WithFormPayload(payload any) RequestOption
- func WithHeaders(header gohttp.Header) RequestOption
- func WithJsonPayload(payload any, contentType string) RequestOption
- func WithUrlQuery(query any) RequestOption
- type RetryBackoff
- type RetryOptions
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, 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 ¶
func (Error) IsClientError ¶ added in v0.3.0
func (Error) IsConflict ¶
func (Error) IsForbidden ¶
func (Error) IsNotFound ¶
func (Error) IsUnauthorized ¶
type ExponentialBackoff ¶
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 RetryOptions ¶
type RetryOptions struct {
MaxRetries int
Backoff RetryBackoff
}
Source Files