api

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Jan 23, 2023 License: BSD-3-Clause Imports: 16 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrInvalidCredentials   = errors.New("quarterdeck credentials are missing or invalid")
	ErrExpiredCredentials   = errors.New("quarterdeck credentials have expired")
	ErrMissingRegisterField = errors.New("name and email address are required")
	ErrPasswordMismatch     = errors.New("passwords do not match")
	ErrPasswordTooWeak      = errors.New("password is too weak: use a combination of upper and lower case letters, numbers, and special characters")
	ErrMissingField         = errors.New("missing required field")
	ErrInvalidField         = errors.New("invalid or unparsable field")
	ErrRestrictedField      = errors.New("field restricted for request")
	ErrModelIDMismatch      = errors.New("resource id does not match id of endpoint")
)

Functions

func ContextWithToken added in v0.2.0 

func ContextWithToken(parent context.Context, token string) context.Context

ContextWithToken returns a copy of the parent with the access token stored as a value on the new context. Passing in a context with an access token overrides the default credentials of the API to make per-request authenticated requests and is primarily used by clients that need to passthrough a user's credentials to each request so that the API call can be authenticated correctly.

func InvalidField added in v0.2.0 

func InvalidField(field string) error

func MissingField added in v0.2.0 

func MissingField(field string) error

func NotAllowed 

func NotAllowed(c *gin.Context)

NotAllowed returns a JSON 405 response for the API.

func NotFound 

func NotFound(c *gin.Context)

NotFound returns a JSON 404 response for the API. NOTE: we know it's weird to put server-side handlers like NotFound and NotAllowed here in the client/api side package but it unifies where we keep our error handling mechanisms.

func RestrictedField added in v0.2.0 

func RestrictedField(field string) error

Types

type APIAuthentication 

type APIAuthentication struct {
	ClientID     string `json:"client_id"`
	ClientSecret string `json:"client_secret"`
}

type APIKey 

type APIKey struct {
	ID           ulid.ULID `json:"id,omitempty"`            // not allowed on create
	ClientID     string    `json:"client_id"`               // not allowed on create, cannot be updated
	ClientSecret string    `json:"client_secret,omitempty"` // not allowed on created, cannot be updated
	Name         string    `json:"name"`                    // required on create, update
	OrgID        ulid.ULID `json:"org_id"`                  // required on create, cannot be updated
	ProjectID    ulid.ULID `json:"project_id"`              // required on create, cannot be updated
	CreatedBy    ulid.ULID `json:"created_by,omitempty"`    // required on create, cannot be updated
	Source       string    `json:"source,omitempty"`        // not required, but useful
	UserAgent    string    `json:"user_agent,omitempty"`    // not required, but useful
	LastUsed     time.Time `json:"last_used,omitempty"`     // cannot be edited
	Permissions  []string  `json:"permissions,omitempty"`   // required on create, cannot be updated
	Created      time.Time `json:"created,omitempty"`       // cannot be edited
	Modified     time.Time `json:"modified,omitempty"`      // cannot be edited
}

func (*APIKey) ValidateCreate added in v0.2.0 

func (k *APIKey) ValidateCreate() error

ValidateCreate ensures that the APIKey is valid when sent to the Create REST method. Validation ensures that the user does not supply data not allowed on create and that required fields are present.

func (*APIKey) ValidateUpdate added in v0.2.0 

func (k *APIKey) ValidateUpdate() error

ValidateUpdate ensures that the APIKey is valid when sent to the Update REST method. Validation ensures that the user does not supply data not allowed on updated and that any required fields are present to update the model.

type APIKeyList 

type APIKeyList struct {
	APIKeys       []*APIKey `json:"apikeys"`
	NextPageToken string    `json:"next_page_token,omitempty"`
}

type APIPageQuery added in v0.2.0 

type APIPageQuery struct {
	ProjectID     string `json:"project_id,omitempty" url:"project_id,omitempty" form:"project_id"`
	PageSize      int    `json:"page_size" url:"page_size,omitempty" form:"page_size"`
	NextPageToken string `json:"next_page_token" url:"next_page_token,omitempty" form:"next_page_token"`
}

type APIv1 

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

APIv1 implements the QuarterdeckClient interface

func (*APIv1) APIKeyCreate 

func (s *APIv1) APIKeyCreate(ctx context.Context, in *APIKey) (out *APIKey, err error)

func (*APIv1) APIKeyDelete 

func (s *APIv1) APIKeyDelete(ctx context.Context, id string) (err error)

func (*APIv1) APIKeyDetail 

func (s *APIv1) APIKeyDetail(ctx context.Context, id string) (out *APIKey, err error)

func (*APIv1) APIKeyList 

func (s *APIv1) APIKeyList(ctx context.Context, in *APIPageQuery) (out *APIKeyList, err error)

func (*APIv1) APIKeyUpdate 

func (s *APIv1) APIKeyUpdate(ctx context.Context, in *APIKey) (out *APIKey, err error)

func (*APIv1) Authenticate 

func (s *APIv1) Authenticate(ctx context.Context, in *APIAuthentication) (out *LoginReply, err error)

func (*APIv1) Do 

func (s *APIv1) Do(req *http.Request, data interface{}, checkStatus bool) (rep *http.Response, err error)

Do executes an http request against the server, performs error checking, and deserializes the response data into the specified struct.

func (*APIv1) Login 

func (s *APIv1) Login(ctx context.Context, in *LoginRequest) (out *LoginReply, err error)

func (*APIv1) NewRequest 

func (s *APIv1) NewRequest(ctx context.Context, method, path string, data interface{}, params *url.Values) (req *http.Request, err error)

func (*APIv1) Refresh 

func (s *APIv1) Refresh(ctx context.Context) (out *LoginReply, err error)

func (*APIv1) Register 

func (s *APIv1) Register(ctx context.Context, in *RegisterRequest) (out *RegisterReply, err error)

func (*APIv1) Status 

func (s *APIv1) Status(ctx context.Context) (out *StatusReply, err error)

type ClientOption 

type ClientOption func(c *APIv1) error

ClientOption allows us to configure the APIv1 client when it is created.

func WithClient 

func WithClient(client *http.Client) ClientOption

func WithCredentials added in v0.2.0 

func WithCredentials(creds Credentials) ClientOption

type Credentials added in v0.2.0 

type Credentials interface {
	AccessToken() (string, error)
}

Credentials provides a basic interface for loading an access token from Quarterdeck into the Quarterdeck API client. Credentials can be loaded from disk, generated, or feched from a passthrough request.

func CredsFromContext added in v0.2.0 

func CredsFromContext(ctx context.Context) (Credentials, bool)

CredsFromContext returns the Credentials from the provided context along with a boolean describing if credentials were available on the specified context.

type FieldError added in v0.2.0 

type FieldError struct {
	Field string `json:"field"`
	Err   error  `json:"error"`
}

FieldError provides a general mechanism for specifying errors with specific API object fields such as missing required field or invalid field and giving some feedback about which fields are the problem. TODO: allow multiple field errors to be specified in one response.

func (*FieldError) Error added in v0.2.0 

func (e *FieldError) Error() string

func (*FieldError) Is added in v0.2.0 

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

func (*FieldError) Unwrap added in v0.2.0 

func (e *FieldError) Unwrap() error

type LoginReply 

type LoginReply struct {
	AccessToken  string `json:"access_token"`
	RefreshToken string `json:"refresh_token"`
}

type LoginRequest 

type LoginRequest struct {
	Email    string `json:"email"`
	Password string `json:"password"`
}

type OpenIDConfiguration added in v0.1.1 

type OpenIDConfiguration struct {
	Issuer                        string   `json:"issuer"`
	AuthorizationEP               string   `json:"authorization_endpoint"`
	TokenEP                       string   `json:"token_endpoint"`
	DeviceAuthorizationEP         string   `json:"device_authorization_endpoint"`
	UserInfoEP                    string   `json:"userinfo_endpoint"`
	MFAChallengeEP                string   `json:"mfa_challenge_endpoint"`
	JWKSURI                       string   `json:"jwks_uri"`
	RegistrationEP                string   `json:"registration_endpoint"`
	RevocationEP                  string   `json:"revocation_endpoint"`
	ScopesSupported               []string `json:"scopes_supported"`
	ResponseTypesSupported        []string `json:"response_types_supported"`
	CodeChallengeMethodsSupported []string `json:"code_challenge_methods_supported"`
	ResponseModesSupported        []string `json:"response_modes_supported"`
	SubjectTypesSupported         []string `json:"subject_types_supported"`
	IDTokenSigningAlgValues       []string `json:"id_token_signing_alg_values_supported"`
	TokenEndpointAuthMethods      []string `json:"token_endpoint_auth_methods_supported"`
	ClaimsSupported               []string `json:"claims_supported"`
	RequestURIParameterSupported  bool     `json:"request_uri_parameter_supported"`
}

type PageQuery 

type PageQuery struct {
	PageSize      int    `json:"page_size" url:"page_size,omitempty" form:"page_size"`
	NextPageToken string `json:"next_page_token" url:"next_page_token,omitempty" form:"next_page_token"`
}

PageQuery manages paginated list requests.

type QuarterdeckClient 

type QuarterdeckClient interface {
	// Unauthenticated endpoints
	Status(context.Context) (*StatusReply, error)
	Register(context.Context, *RegisterRequest) (*RegisterReply, error)
	Login(context.Context, *LoginRequest) (*LoginReply, error)
	Authenticate(context.Context, *APIAuthentication) (*LoginReply, error)

	// Authenticated endpoints
	Refresh(context.Context) (*LoginReply, error)

	// API Keys Resource
	APIKeyList(context.Context, *APIPageQuery) (*APIKeyList, error)
	APIKeyCreate(context.Context, *APIKey) (*APIKey, error)
	APIKeyDetail(context.Context, string) (*APIKey, error)
	APIKeyUpdate(context.Context, *APIKey) (*APIKey, error)
	APIKeyDelete(context.Context, string) error
}

func New 

func New(endpoint string, opts ...ClientOption) (_ QuarterdeckClient, err error)

New creates a new API v1 client that implements the Quarterdeck Client interface.

type RegisterReply 

type RegisterReply struct {
	ID      string `json:"user_id"`
	Email   string `json:"email"`
	Message string `json:"message"`
	Role    string `json:"role"`
	Created string `json:"created"`
}

type RegisterRequest 

type RegisterRequest struct {
	Name     string `json:"name"`
	Email    string `json:"email"`
	Password string `json:"password"`
	PwCheck  string `json:"pwcheck"`
}

func (*RegisterRequest) Validate added in v0.2.0 

func (r *RegisterRequest) Validate() error

Validate the register request ensuring that the required fields are available and that the password is valid - an error is returned if the request is not correct. This method also performs some basic data cleanup, trimming whitespace.

type Reply 

type Reply struct {
	Success bool   `json:"success"`
	Error   string `json:"error,omitempty"`
}

Reply contains standard fields that are used for generic API responses and errors.

func ErrorResponse 

func ErrorResponse(err interface{}) Reply

Construct a new response for an error or simply return unsuccessful.

type StatusError added in v0.2.0 

type StatusError struct {
	StatusCode int
	Reply      Reply
}

StatusError decodes an error response from Quarterdeck.

func (*StatusError) Error added in v0.2.0 

func (e *StatusError) Error() string

type StatusReply 

type StatusReply struct {
	Status  string `json:"status"`
	Uptime  string `json:"uptime,omitempty"`
	Version string `json:"version,omitempty"`
}

Returned on status requests.

type Token added in v0.2.0 

type Token string

A Token is just the JWT base64 encoded token string that is obtained from Quarterdeck either using the authtest server or from a login with the client.

func (Token) AccessToken added in v0.2.0 

func (t Token) AccessToken() (string, error)

Token implements the credentials interface and performs limited validation.

Source Files

View all Source files

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.