api

package module
v0.0.53 Latest Latest
Warning

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

 Go to latest Published: Sep 30, 2024 License: MPL-2.0 Imports: 26 Imported by: 6

Documentation

Index

Constants

View Source 
const (
	EnvBoundaryAddr          = "BOUNDARY_ADDR"
	EnvBoundaryCACert        = "BOUNDARY_CACERT"
	EnvBoundaryCAPath        = "BOUNDARY_CAPATH"
	EnvBoundaryClientCert    = "BOUNDARY_CLIENT_CERT"
	EnvBoundaryClientKey     = "BOUNDARY_CLIENT_KEY"
	EnvBoundaryClientTimeout = "BOUNDARY_CLIENT_TIMEOUT"
	EnvBoundaryTLSInsecure   = "BOUNDARY_TLS_INSECURE"
	EnvBoundaryTLSServerName = "BOUNDARY_TLS_SERVER_NAME"
	EnvBoundaryMaxRetries    = "BOUNDARY_MAX_RETRIES"
	EnvBoundaryToken         = "BOUNDARY_TOKEN"
	EnvBoundaryRateLimit     = "BOUNDARY_RATE_LIMIT"
	EnvBoundarySRVLookup     = "BOUNDARY_SRV_LOOKUP"

	AsciiCastMimeType = "application/x-asciicast"
	StreamChunkSize   = 1024 * 64 // stream chuck buffer size
)
View Source 
const (
	ErrOutputStringRequest = "output a string, please"
)

Variables

View Source 
var (
	ErrNotFound         = &Error{Kind: codes.NotFound.String(), response: &Response{resp: &http.Response{StatusCode: http.StatusNotFound}}}
	ErrInvalidArgument  = &Error{Kind: codes.InvalidArgument.String(), response: &Response{resp: &http.Response{StatusCode: http.StatusBadRequest}}}
	ErrPermissionDenied = &Error{Kind: codes.PermissionDenied.String(), response: &Response{resp: &http.Response{StatusCode: http.StatusForbidden}}}
	ErrUnauthorized     = &Error{Kind: codes.Unauthenticated.String(), response: &Response{resp: &http.Response{StatusCode: http.StatusUnauthorized}}}
	// internal/daemon/controller/handlers/errors.go detects status.Code(inErr) == codes.Unimplemented
	// and sets http status http.StatusMethodNotAllowed
	ErrUnimplemented    = &Error{Kind: codes.Unimplemented.String(), response: &Response{resp: &http.Response{StatusCode: http.StatusMethodNotAllowed}}}
	ErrInvalidListToken = &Error{Kind: "invalid list token", response: &Response{resp: &http.Response{StatusCode: http.StatusBadRequest}}}
)

Functions

func RateLimitLinearJitterBackoff added in v0.0.44 

func RateLimitLinearJitterBackoff(min, max time.Duration, attemptNum int, resp *http.Response) time.Duration

RateLimitLinearJitterBackoff wraps the retryablehttp.LinearJitterBackoff. It first checks if the response status code is http.StatusTooManyRequests (HTTP Code 429) or http.StatusServiceUnavailable (HTTP Code 503). If it is and the response contains a Retry-After response header, it will wait the amount of time specified by the header. Otherwise, this calls LinearJitterBackoff. See: https://pkg.go.dev/github.com/hashicorp/go-retryablehttp#LinearJitterBackoff

Types

type Client 

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

Client is the client to the Boundary API. Create a client with NewClient.

func NewClient 

func NewClient(c *Config) (*Client, error)

NewClient returns a new client for the given configuration.

If the configuration is nil, Boundary will use configuration from DefaultConfig(), which is the recommended starting configuration.

If the environment variable `BOUNDARY_TOKEN` is present, the token will be automatically added to the client. Otherwise, you must manually call `SetToken()`.

func (*Client) Addr 

func (c *Client) Addr() string

Addr returns the current (parsed) address

func (*Client) Clone 

func (c *Client) Clone() *Client

Clone creates a new client with the same configuration. Note that the same underlying http.Client is used; modifying the client from more than one goroutine at once may not be safe, so modify the client as needed and then clone.

func (*Client) Do 

func (c *Client) Do(r *retryablehttp.Request, opt ...Option) (*Response, error)

Do takes a properly configured request and applies client configuration to it, returning the response.

func (*Client) NewRequest 

func (c *Client) NewRequest(ctx context.Context, method, requestPath string, body any, opt ...Option) (*retryablehttp.Request, error)

NewRequest creates a new raw request object to query the Boundary controller configured for this client. This is an advanced method and generally doesn't need to be called externally.

func (*Client) RecoveryKmsWrapper 

func (c *Client) RecoveryKmsWrapper() wrapping.Wrapper

RecoveryKmsWrapper gets the configured recovery KMS wrapper.

func (*Client) SetAddr 

func (c *Client) SetAddr(addr string) error

Sets the address of Boundary in the client. The format of address should be "<Scheme>://<Host>:<Port>". Setting this on a client will override the value of the BOUNDARY_ADDR environment variable.

func (*Client) SetBackoff 

func (c *Client) SetBackoff(backoff retryablehttp.Backoff)

SetBackoff sets the backoff function to be used for future requests.

func (*Client) SetCheckRetry 

func (c *Client) SetCheckRetry(checkRetry retryablehttp.CheckRetry)

SetCheckRetry sets the CheckRetry function to be used for future requests.

func (*Client) SetClientTimeout 

func (c *Client) SetClientTimeout(timeout time.Duration)

SetClientTimeout sets the client request timeout

func (*Client) SetHeaders 

func (c *Client) SetHeaders(headers http.Header)

SetHeaders clears all previous headers and uses only the given ones going forward.

func (*Client) SetLimiter 

func (c *Client) SetLimiter(rateLimit float64, burst int)

SetLimiter will set the rate limiter for this client. This method is thread-safe. rateLimit and burst are specified according to https://godoc.org/golang.org/x/time/rate#NewLimiter

func (*Client) SetMaxRetries 

func (c *Client) SetMaxRetries(retries int)

SetMaxRetries sets the number of retries that will be used in the case of certain errors

func (*Client) SetOutputCurlString 

func (c *Client) SetOutputCurlString(curl bool)

func (*Client) SetRecoveryKmsWrapper 

func (c *Client) SetRecoveryKmsWrapper(wrapper wrapping.Wrapper)

SetRecoveryKmsWrapper sets the wrapper used for the recovery workflow

func (*Client) SetTLSConfig 

func (c *Client) SetTLSConfig(conf *TLSConfig) error

SetTLSConfig sets the TLS parameters to use and calls ConfigureTLS

func (*Client) SetToken 

func (c *Client) SetToken(token string)

SetToken sets the token directly. This won't perform any auth verification, it simply sets the token properly for future requests.

func (*Client) Token 

func (c *Client) Token() string

Token gets the configured token.

type Config 

type Config struct {
	// Addr is the address of the Boundary controller. This should be a
	// complete URL such as "http://boundary.example.com". If you need a custom
	// SSL cert or want to enable insecure mode, you need to specify a custom
	// HttpClient.
	Addr string

	// Token is the client token that reuslts from authentication and can be
	// used to make calls into Boundary
	Token string

	// RecoveryKmsWrapper is a wrapper used in the recovery KMS authentication
	// flow. If set, this will always be used to generate a new token value
	// per-call, regardless of any value set in Token.
	RecoveryKmsWrapper wrapping.Wrapper

	// HttpClient is the HTTP client to use. Boundary sets sane defaults for the
	// http.Client and its associated http.Transport created in DefaultConfig.
	// If you must modify Boundary's defaults, it is suggested that you start
	// with that client and modify as needed rather than start with an empty
	// client (or http.DefaultClient). Currently if the client is cloned the
	// same HttpClient is used.
	HttpClient *http.Client

	// TLSConfig contains TLS configuration information. After modifying these
	// values, ConfigureTLS should be called.
	TLSConfig *TLSConfig

	// Headers contains extra headers that will be added to any request
	Headers http.Header

	// MaxRetries controls the maximum number of times to retry when a 5xx
	// error occurs. Set to 0 to disable retrying. Defaults to 2 (for a total
	// of three tries).
	MaxRetries int

	// Timeout is for setting custom timeout parameter in the HttpClient
	Timeout time.Duration

	// The Backoff function to use; a default is used if not provided
	Backoff retryablehttp.Backoff

	// The CheckRetry function to use; a default is used if not provided
	CheckRetry retryablehttp.CheckRetry

	// Limiter is the rate limiter used by the client. If this pointer is nil,
	// then there will be no limit set. In contrast, if this pointer is set,
	// even to an empty struct, then that limiter will be used. Note that an
	// empty Limiter is equivalent blocking all events. Currently if the client
	// is cloned the same limiter is used.
	Limiter *rate.Limiter

	// OutputCurlString causes the actual request to return an error of type
	// *OutputStringError. Type asserting the error message will allow
	// fetching a cURL-compatible string for the operation.
	OutputCurlString bool

	// SRVLookup enables the client to lookup the host through DNS SRV lookup
	SRVLookup bool
}

Config is used to configure the creation of the client

func DefaultConfig 

func DefaultConfig() (*Config, error)

DefaultConfig returns a default configuration for the client. It is safe to modify the return value of this function.

The default Addr is http://127.0.0.1:9200, but this can be overridden by setting the `BOUNDARY_ADDR` environment variable.

If an error is encountered, this will return nil.

func (*Config) ConfigureTLS 

func (c *Config) ConfigureTLS() error

ConfigureTLS takes a set of TLS configurations and applies those to the the HTTP client.

func (*Config) ReadEnvironment 

func (c *Config) ReadEnvironment() error

ReadEnvironment reads configuration information from the environment. If there is an error, no configuration value is updated.

type Duration added in v0.0.37 

type Duration struct {
	time.Duration
}

Duration represents a time.Duration and supports marshaling/unmarshaling from a json string

func (Duration) MarshalJSON added in v0.0.37 

func (d Duration) MarshalJSON() ([]byte, error)

func (*Duration) UnmarshalJSON added in v0.0.37 

func (d *Duration) UnmarshalJSON(b []byte) error

type Error 

type Error struct {
	Kind    string        `json:"kind,omitempty"`
	Op      string        `json:"op,omitempty"`
	Message string        `json:"message,omitempty"`
	Details *ErrorDetails `json:"details,omitempty"`
	// contains filtered or unexported fields
}

func AsServerError 

func AsServerError(in error) *Error

AsServerError returns an api *Error from the provided error. If the provided error is not an api Error nil is returned instead.

func (*Error) Error 

func (e *Error) Error() string

Error satisfies the error interface.

func (*Error) Is 

func (e *Error) Is(target error) bool

Errors are considered the same iff they are both api.Errors and their statuses are the same.

func (*Error) Response added in v0.0.7 

func (e *Error) Response() *Response

Response returns the API response associated with the error

type ErrorDetails 

type ErrorDetails struct {
	RequestFields []*FieldError   `json:"request_fields,omitempty"`
	WrappedErrors []*WrappedError `json:"wrapped_errors,omitempty"`
}

type FieldError 

type FieldError struct {
	Name        string `json:"name,omitempty"`
	Description string `json:"description,omitempty"`
}

type Option 

type Option func(*options)

Option - how Options are passed as arguments

func WithSkipCurlOutput added in v0.0.4 

func WithSkipCurlOutput(skip bool) Option

WithSkipCurlOutput tells the API to not use the current call for cURL output. Useful for when we need to look up versions.

type OutputStringError 

type OutputStringError struct {
	*retryablehttp.Request
	// contains filtered or unexported fields
}
var LastOutputStringError *OutputStringError

func NewOutputDomainSocketCurlStringError added in v0.0.44 

func NewOutputDomainSocketCurlStringError(req *retryablehttp.Request, socketAddr string) *OutputStringError

func (*OutputStringError) CurlString 

func (d *OutputStringError) CurlString() string

func (*OutputStringError) Error 

func (d *OutputStringError) Error() string

type Response 

type Response struct {
	Body *bytes.Buffer
	Map  map[string]any
	// contains filtered or unexported fields
}

Response is a custom response that wraps an HTTP response. Body will be populated with a buffer containing the response body after Decode is called; it will be nil if the response was a 204.

func NewResponse added in v0.0.44 

func NewResponse(r *http.Response) *Response

NewResponse returns a new *Response based on the provided http.Response. Just as when constructing the Response directly, Body and Map will be populated after Decode is called.

func (*Response) Decode 

func (r *Response) Decode(inStruct any) (*Error, error)

func (*Response) HttpResponse 

func (r *Response) HttpResponse() *http.Response

HttpResponse returns the underlying HTTP response

func (*Response) StatusCode added in v0.0.7 

func (r *Response) StatusCode() int

StatusCode returns the underlying HTTP status code

type TLSConfig 

type TLSConfig struct {
	// CACert is the path to a PEM-encoded CA cert file to use to verify the
	// Boundary server SSL certificate.
	CACert string

	// CAPath is the path to a directory of PEM-encoded CA cert files to verify
	// the Boundary server SSL certificate.
	CAPath string

	// ClientCert is the path to the certificate for Boundary communication
	ClientCert string

	// ClientKey is the path to the private key for Boundary communication
	ClientKey string

	// ServerName, if set, is used to set the SNI host when connecting via
	// TLS.
	ServerName string

	// Insecure enables or disables SSL verification
	Insecure bool
}

TLSConfig contains the parameters needed to configure TLS on the HTTP client used to communicate with Boundary.

type WrappedError added in v0.0.3 

type WrappedError struct {
	Op      string `json:"op,omitempty"`
	Message string `json:"message,omitempty"`
}

Source Files

View all Source files

Directories

Path Synopsis

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.