client

Documentation

Overview

Package client provides the underlying structures, interfaces and methods for peforming requests against KraftCloud's API.

Index

• Constants
• type APIHTTPError
• type APIResponseCommon
  • func (c APIResponseCommon) ErrorAttributes() APIResponseCommon
• type APIResponseDataEntry
• type ErrorResponse
• type ServiceClient
• type ServiceRequest
  • func NewServiceRequestFromDefaultOptions(opts *options.Options) *ServiceRequest
  • func (r *ServiceRequest) DoRequest(ctx context.Context, method, url string, body io.Reader, target any) error
  • func (r *ServiceRequest) DoWithAuth(req *http.Request) (*http.Response, error)
  • func (r *ServiceRequest) GetBearerToken() string
  • func (r *ServiceRequest) GetToken() string
  • func (r *ServiceRequest) Metro() string
  • func (r *ServiceRequest) Metrolink(path string) string
  • func (r *ServiceRequest) WithHTTPClient(hc httpclient.HTTPClient) *ServiceRequest
  • func (r *ServiceRequest) WithMetro(m string) *ServiceRequest
  • func (r *ServiceRequest) WithTimeout(to time.Duration) *ServiceRequest
• type ServiceResponse
  • func (r *ServiceResponse[T]) AllOrErr() ([]T, error)
  • func (r *ServiceResponse[T]) FirstOrErr() (*T, error)
  • func (r *ServiceResponse[T]) RawBody() []byte
• type ServiceResponseData
  • func (d *ServiceResponseData[T]) UnmarshalJSON(b []byte) error

Constants

const (
	// BaseURL defines the default location of the Kraftcloud API.
	BaseURL = "https://api." + DefaultMetro + ".kraft.cloud/v1"
	// BaseV1FormatURL defines the default location of the KraftCloud API which is
	// formatted to allow setting the metro.
	BaseV1FormatURL = "https://api.%s.kraft.cloud/v1"
	// DefaultPort is the port the instance will listen on externally by default.
	DefaultPort = 443
	// DefaultMetro is set to a default node based in Frankfurt.
	DefaultMetro = "fra0"
)

Types

type APIHTTPError

type APIHTTPError int

const (
	APIHTTPErrorUnknownError APIHTTPError = iota
	APIHTTPErrorNotSupported
	APIHTTPErrorWrongMethod
	APIHTTPErrorNoAPIEndpoint
	APIHTTPErrorFailNotAll
	APIHTTPErrorTooMany
	APIHTTPErrorUnknown
	APIHTTPErrorInvalid
	APIHTTPErrorNotFound
	APIHTTPErrorNoFree
	APIHTTPErrorFailedOperation
	APIHTTPErrorFailedWrongVMState
	APIHTTPErrorTimedOut
	APIHTTPErrorMissingID
	APIHTTPErrorNotAllowed
	APIHTTPErrorAttached
	APIHTTPErrorMalformedRequest
	APIHTTPErrorNotBoth
	APIHTTPErrorAddService
	APIHTTPErrorQuota
	APIHTTPErrorGuestMemoryTooSmall
	APIHTTPErrorNotAttached
	APIHTTPErrorTooLong
	APIHTTPErrorAlreadyExists
	APIHTTPErrorCannotBeUsed
	APIHTTPErrorAutoscaleInstance
	APIHTTPErrorAutoscaleConfigured
	APIHTTPErrorAutoscaleNotConfigured
	APIHTTPErrorAutoscaleDisavled
	APIHTTPErrorAutoscaleSizeOOR
	APIHTTPErrorCertCNMisMatch
)

type APIResponseCommon

type APIResponseCommon struct {
	Status  string        `json:"status"`
	Message string        `json:"message"`
	Error   *APIHTTPError `json:"error"`
}

APIResponseCommon contains attributes common to all API responses, namely the attributes which are returned either on error or partial success. https://docs.kraft.cloud/api/v1/#api-responses

func (APIResponseCommon) ErrorAttributes

func (c APIResponseCommon) ErrorAttributes() APIResponseCommon

ErrorAttributes implements APIResponseDataEntry.

type APIResponseDataEntry

type APIResponseDataEntry interface {
	ErrorAttributes() APIResponseCommon
}

APIResponseDataEntry provides access to data common to all data entries returned in API responses.

type ErrorResponse

type ErrorResponse struct {
	Status int `json:"status"`
}

ErrorResponse is the list of errors that have occurred during the invocation of the API call.

type ServiceClient

type ServiceClient[T any] interface {
	// WithMetro sets the just-in-time metro to use when connecting to the
	// KraftCloud API.
	WithMetro(string) T

	// WithTimeout sets the timeout when making the request.
	WithTimeout(time.Duration) T

	// WithHTTPClient overwrites the base HTTP client.
	WithHTTPClient(httpclient.HTTPClient) T
}

ServiceClient is an interface of mandatory methods that a service must implement. These methods are used to customize the request just-in-time, enabling deep customization of each request without having to re-instantiate the client.

type ServiceRequest

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

ServiceRequest is the utility structure for performing individual requests to a service location at KraftCloud.

func NewServiceRequestFromDefaultOptions

func NewServiceRequestFromDefaultOptions(opts *options.Options) *ServiceRequest

NewServiceRequestFromDefaultOptions is a constructor method which uses the prebuilt set of options as part of the request.

func (*ServiceRequest) DoRequest

func (r *ServiceRequest) DoRequest(ctx context.Context, method, url string, body io.Reader, target any) error

DoRequest performs the request and hydrates a target type with response body.

func (*ServiceRequest) DoWithAuth

func (r *ServiceRequest) DoWithAuth(req *http.Request) (*http.Response, error)

DoWithAuth performs a request with headers defining the content type. We also inject the authentication details.

func (*ServiceRequest) GetBearerToken

func (r *ServiceRequest) GetBearerToken() string

GetBearerToken uses the pre-defined token to construct the header used for authenticating requests.

func (*ServiceRequest) GetToken

func (r *ServiceRequest) GetToken() string

GetToken uses the pre-defined token to construct the Bearer token used for authenticating requests.

func (*ServiceRequest) Metro

func (r *ServiceRequest) Metro() string

Metro returns the metro that this request will perform against.

func (*ServiceRequest) Metrolink

func (r *ServiceRequest) Metrolink(path string) string

Metrolink returns the full URI representing the API endpoint of a KraftCloud metro.

func (*ServiceRequest) WithHTTPClient

func (r *ServiceRequest) WithHTTPClient(hc httpclient.HTTPClient) *ServiceRequest

WithHTTPClient returns a ServiceRequest which performs API requests using the given HTTPClient.

func (*ServiceRequest) WithMetro

func (r *ServiceRequest) WithMetro(m string) *ServiceRequest

WithMetro returns a ServiceRequest that uses the given metro in API requests.

func (*ServiceRequest) WithTimeout

func (r *ServiceRequest) WithTimeout(to time.Duration) *ServiceRequest

WithTimeout returns a ServiceRequest that uses the specified timeout duration in API requests.

type ServiceResponse

type ServiceResponse[T APIResponseDataEntry] struct {
	// Status contains the top-level information about a server response, and
	// returns either `success`, `partial_success` or `error`.
	Status string `json:"status,omitempty"`

	// Message contains the error message either on `partial_success` or `error`.
	Message string `json:"message,omitempty"`

	// Errors are the list of errors that have occurred.
	Errors []ErrorResponse `json:"errors,omitempty"`

	// On a successful response, the data element is returned with relevant
	// information.
	Data ServiceResponseData[T] `json:"data,omitempty"`
	// contains filtered or unexported fields
}

ServiceResponse embodies the the API response for an invocation to a service on KraftCloud. It uses standard HTTP response codes to indicate success or failure. In addition, the response body contains more details about the result of the operation in a JSON object. On success the data member contains an array of objects with one object per result. The array is named according to the type of object that the request is operating on. For example, when working with instances the response contains an instances array.

See: https://docs.kraft.cloud/api/v1/

func (*ServiceResponse[T]) AllOrErr

func (r *ServiceResponse[T]) AllOrErr() ([]T, error)

AllOrErr returns the all data entrypoints or an error if it is not available.

func (*ServiceResponse[T]) FirstOrErr

func (r *ServiceResponse[T]) FirstOrErr() (*T, error)

FirstOrErr returns the first data entrypoint or an error if it is not available.

func (*ServiceResponse[T]) RawBody

func (r *ServiceResponse[T]) RawBody() []byte

RawBody returns the raw API response body.

type ServiceResponseData

type ServiceResponseData[T APIResponseDataEntry] struct {
	Entries []T
}

ServiceResponseData is the embedded list of structures defined by T. The results are always available at the attribute `Entries` and uses a custom JSON unmarshaler to determine the JSON tag associated with these entries.

func (*ServiceResponseData[T]) UnmarshalJSON

func (d *ServiceResponseData[T]) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaler.