jsonclient

Documentation

Index

• Variables
• func ExtractBearerToken(h *http.Header) (string, error)
• func GetHTTPStatusCode(err error) int
• func RegisterLogger(l Logger)
• type Client
  • func New(url string, opts ...Option) *Client
  • func (c *Client) Apply(opts ...Option)
  • func (c *Client) CreateIfNotExists(ctx context.Context, path string, body, response interface{}, opts ...Option) (bool, uuid.UUID, error)
  • func (c *Client) Delete(ctx context.Context, path string, body interface{}, opts ...Option) error
  • func (c *Client) Get(ctx context.Context, path string, response interface{}, opts ...Option) error
  • func (c *Client) GetBearerToken() (string, error)
  • func (c *Client) Patch(ctx context.Context, path string, body, response interface{}, opts ...Option) error
  • func (c *Client) Post(ctx context.Context, path string, body, response interface{}, opts ...Option) error
  • func (c *Client) Put(ctx context.Context, path string, body, response interface{}, opts ...Option) error
  • func (c *Client) ValidateBearerTokenHeader() error
• type DecodeFunc
• type Error
  • func (e Error) Code() int
  • func (e Error) Error() string
  • func (e Error) Friendly() string
  • func (e Error) FriendlyStructure() interface{}
• type HeaderFunc
• type Logger
• type Option
  • func BypassRouting() Option
  • func ClientCredentialsTokenSource(tokenURL, clientID, clientSecret string, customAudiences []string) Option
  • func Cookie(cookie http.Cookie) Option
  • func CustomDecoder(f DecodeFunc) Option
  • func Header(k, v string) Option
  • func ParseOAuthError() Option
  • func PassthroughAuthorization(r *http.Request) Option
  • func PerRequestHeader(f HeaderFunc) Option
  • func RetryNetworkErrors() Option
  • func StopLogging() Option
  • func TokenSource(ts oidc.TokenSource) Option
  • func UnmarshalOnError() Option
• type RequestRouter
• type SDKStructuredError
  • func GetDetailedErrorInfo(err error) *SDKStructuredError

Variables

var ErrIncorrectUsernamePassword = oAuthError{
	ErrorType: "invalid_grant",
	ErrorDesc: "incorrect username or password",
	Code:      http.StatusBadRequest,
}

ErrIncorrectUsernamePassword indicates a bad username or password.

Functions

func ExtractBearerToken

func ExtractBearerToken(h *http.Header) (string, error)

ExtractBearerToken extracts a bearer token from an HTTP request or returns an error if none is found or if it's malformed. NOTE: this doesn't enforce that it's a JWT, much less a valid one.

func GetHTTPStatusCode

func GetHTTPStatusCode(err error) int

GetHTTPStatusCode returns the underlying HTTP status code or -1 if no code could be extracted.

func RegisterLogger

func RegisterLogger(l Logger)

RegisterLogger registers a logger to be used by jsonclient. Note this could eventually be extended to allow multiple etc, but right now this just allows us to break the uclog/jsonclient dependency

Types

type Client

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

Client defines a JSON-focused HTTP client TODO: someday this should use a custom http.Client etc

func New

func New(url string, opts ...Option) *Client

New returns a new Client

func (*Client) Apply

func (c *Client) Apply(opts ...Option)

Apply applies options to an existing client (useful for updating a header/cookie/etc on an existing client).

func (*Client) CreateIfNotExists

func (c *Client) CreateIfNotExists(ctx context.Context, path string, body, response interface{}, opts ...Option) (bool, uuid.UUID, error)

CreateIfNotExists does a POST and handles the 409 conflict error for the caller

func (*Client) Delete

func (c *Client) Delete(ctx context.Context, path string, body interface{}, opts ...Option) error

Delete makes an HTTP delete using this client

func (*Client) Get

func (c *Client) Get(ctx context.Context, path string, response interface{}, opts ...Option) error

Get makes an HTTP get using this client TODO: need to support query params soon :)

func (*Client) GetBearerToken

func (c *Client) GetBearerToken() (string, error)

GetBearerToken returns the bearer token associated with this client, if one exists, or an error otherwise.

func (*Client) Patch

func (c *Client) Patch(ctx context.Context, path string, body, response interface{}, opts ...Option) error

Patch makes an HTTP patch using this client If response is nil, the response isn't decoded and merely the success or failure is returned

func (*Client) Post

func (c *Client) Post(ctx context.Context, path string, body, response interface{}, opts ...Option) error

Post makes an HTTP post using this client If response is nil, the response isn't decoded and merely the success or failure is returned

func (*Client) Put

func (c *Client) Put(ctx context.Context, path string, body, response interface{}, opts ...Option) error

Put makes an HTTP put using this client If response is nil, the response isn't decoded and merely the success or failure is returned

func (*Client) ValidateBearerTokenHeader

func (c *Client) ValidateBearerTokenHeader() error

ValidateBearerTokenHeader ensures that there is a non-expired bearer token specified directly OR that there's a valid token source to refresh it if not specified or expired.

type DecodeFunc

type DecodeFunc func(ctx context.Context, body io.ReadCloser) error

DecodeFunc is a callback used with the CustomDecoder option to control deserializing the response from an HTTP request. Instead of automatically deserializing into the response object provided to the method (which must be nil instead), this method is invoked.

type Error

type Error struct {
	StatusCode int    `json:"http_status_code"`
	Body       string `json:"response_body"`
}

Error defines a jsonclient error for non-2XX/3XX status codes TODO: decide how to handle 3XX results

func (Error) Code

func (e Error) Code() int

Code return the HTTP status code and implements private interface jsonapi.errorWithCode

func (Error) Error

func (e Error) Error() string

Error implements UCError

func (Error) Friendly

func (e Error) Friendly() string

Friendly implements UCError

func (Error) FriendlyStructure

func (e Error) FriendlyStructure() interface{}

FriendlyStructure implements UCError If the body is JSON, we'll convert it to map[string]interface{} so it gets preserved as something easily unmarshaled in the returned error.

type HeaderFunc

type HeaderFunc func(context.Context) (key string, value string)

HeaderFunc is a callback that's invoked on every request to generate a header This is useful when the header should change per-request based on the context used for that request, eg. a long-lived client that makes requests on behalf of numerous customers with different X-Forwarded-For IPs, etc Note that returning a blank key indicates "no header to add this request"

type Logger

type Logger interface {
	Debugf(ctx context.Context, format string, args ...interface{})
}

Logger specifies a minimal interface to allow jsonclient to log errors.

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option makes jsonclient extensible

func BypassRouting

func BypassRouting() Option

BypassRouting allows you to bypass our internal request rerouting system to test performance

func ClientCredentialsTokenSource

func ClientCredentialsTokenSource(tokenURL, clientID, clientSecret string, customAudiences []string) Option

ClientCredentialsTokenSource can be specified to enable support for RefreshBearerToken automatically refreshing the token if expired. TODO: deprecate this in favor of the more generic TokenSource option

func Cookie

func Cookie(cookie http.Cookie) Option

Cookie allows you to add cookies to jsonclient requests

func CustomDecoder

func CustomDecoder(f DecodeFunc) Option

CustomDecoder allows the caller to control deserializing the HTTP response. It is most useful when the exact structure of the response is not known ahead of time, and custom logic is required (e.g. for API compatibility).

func Header

func Header(k, v string) Option

Header allows you to add arbitrary headers to jsonclient requests

func ParseOAuthError

func ParseOAuthError() Option

ParseOAuthError allows deserializing & capturing the last call's error into an OAuthError object for deeper inspection. This is richer than a jsonclient.Error but only makes sense on a call that is expected to be OAuth/OIDC compliant.

func PassthroughAuthorization

func PassthroughAuthorization(r *http.Request) Option

PassthroughAuthorization allows you to pass the Authorization header through from an incoming request to an outgoing request. Note this will only work as an option in a request context (not a long-lived client) TODO: should we have a way to differentiate short- and long-lived options?

func PerRequestHeader

func PerRequestHeader(f HeaderFunc) Option

PerRequestHeader allows you to pass in a callback that takes a context and returns a header k,v that will be called on each request and a new header appended to the request

func RetryNetworkErrors

func RetryNetworkErrors() Option

RetryNetworkErrors causes the client to retry on underlying network errors TODO: is this a good idea? TODO: should we have a max retry count, backoff, etc config?

func StopLogging

func StopLogging() Option

StopLogging causes the client not to log failures

func TokenSource

func TokenSource(ts oidc.TokenSource) Option

TokenSource takes an arbitrary token source

func UnmarshalOnError

func UnmarshalOnError() Option

UnmarshalOnError causes the response struct to be deserialized if a HTTP 400+ code is returned. The default behavior is to not deserialize and to return an error.

type RequestRouter

type RequestRouter interface {
	Reroute(context.Context, *http.Request)
}

RequestRouter allows jsonclient to internally reroute requests to specific hosts / clusters / pods

var Router RequestRouter

Router is jsonclient's RequestRouter

type SDKStructuredError

type SDKStructuredError struct {
	Error     string    `json:"error"`
	ID        uuid.UUID `json:"id"`
	Identical bool      `json:"identical"`
}

SDKStructuredError is the standard structured error returned by our APIs for SDK clients to handle

func GetDetailedErrorInfo

func GetDetailedErrorInfo(err error) *SDKStructuredError

GetDetailedErrorInfo returns detailed information about the error if available and nil otherwise