api

package
v0.5.1 Latest Latest
Warning

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

 Go to latest Published: Mar 22, 2023 License: BSD-3-Clause Imports: 18 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")
	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")
	ErrUserExists         = errors.New("user or organization already exists")
	ErrInvalidUserClaims  = errors.New("user claims invalid or unavailable")
	ErrUnparsable         = errors.New("could not parse request")
)

Functions

func ContextWithRequestID added in v0.5.0 

func ContextWithRequestID(parent context.Context, requestID string) context.Context

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 ErrorStatus added in v0.3.0 

func ErrorStatus(err error) int

ErrorStatus returns the HTTP status code from an error or 500 if the error is not a StatusError.

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 RequestIDFromContext added in v0.5.0 

func RequestIDFromContext(ctx context.Context) (string, bool)

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       []*APIKeyPreview `json:"apikeys"`
	NextPageToken string           `json:"next_page_token,omitempty"`
}

type APIKeyPreview added in v0.5.0 

type APIKeyPreview struct {
	ID        ulid.ULID `json:"id"`
	ClientID  string    `json:"client_id"`
	Name      string    `json:"name,omitempty"`
	ProjectID ulid.ULID `json:"project_id"`
	Partial   bool      `json:"partial"`
	Status    string    `json:"status"`
	LastUsed  time.Time `json:"last_used,omitempty"`
	Created   time.Time `json:"created"`
	Modified  time.Time `json:"modified"`
}

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) APIKeyPermissions added in v0.5.0 

func (s *APIv1) APIKeyPermissions(ctx context.Context) (out []string, err error)

func (*APIv1) APIKeyUpdate 

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

func (*APIv1) AccountUpdate added in v0.5.0 

func (s *APIv1) AccountUpdate(ctx context.Context, in *User) (out *User, 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) OrganizationDetail added in v0.4.0 

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

func (*APIv1) ProjectAccess added in v0.5.0 

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

func (*APIv1) ProjectCreate added in v0.3.0 

func (s *APIv1) ProjectCreate(ctx context.Context, in *Project) (out *Project, err error)

func (*APIv1) Refresh 

func (s *APIv1) Refresh(ctx context.Context, in *RefreshRequest) (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)

func (*APIv1) UserDelete added in v0.4.0 

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

func (*APIv1) UserDetail added in v0.4.0 

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

func (*APIv1) UserList added in v0.4.0 

func (s *APIv1) UserList(ctx context.Context, in *UserPageQuery) (out *UserList, err error)

func (*APIv1) UserUpdate added in v0.3.0 

func (s *APIv1) UserUpdate(ctx context.Context, in *User) (out *User, err error)

func (*APIv1) VerifyEmail added in v0.5.0 

func (s *APIv1) VerifyEmail(ctx context.Context, in *VerifyRequest) (err error)

func (*APIv1) WaitForReady added in v0.4.0 

func (s *APIv1) WaitForReady(ctx context.Context) (err error)

Wait for ready polls the Quarterdeck status endpoint until it responds with an 200 response, retrying with exponential backoff or until the context deadline is expired. If the user does not supply a context with a deadline, then a default deadline of 5 minutes is used so that this method does not block indefinitely. If the Quarterdeck service is ready (e.g. responds to a status request) then no error is returned, otherwise an error is returned if Quarterdeck never responds.

NOTE: if Quarterdeck returns a 503 Service Unavailable because it is in maintenance mode, this method will continue to wait until the deadline for Quarterdeck to exit from maintenance mode and be ready again.

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,omitempty"`
	LastLogin    string `json:"last_login,omitempty"`
}

type LoginRequest 

type LoginRequest struct {
	Email    string    `json:"email"`
	Password string    `json:"password"`
	OrgID    ulid.ULID `json:"org_id"`
}

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 Organization added in v0.4.0 

type Organization struct {
	ID       ulid.ULID `json:"id"`
	Name     string    `json:"name"`
	Domain   string    `json:"domain"`
	Projects int       `json:"projects"`
	Created  time.Time `json:"created,omitempty"`
	Modified time.Time `json:"modified,omitempty"`
}

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 Project added in v0.3.0 

type Project struct {
	OrgID     ulid.ULID `json:"org_id,omitempty"`   // not allowed on create
	ProjectID ulid.ULID `json:"project_id"`         // required on create and access
	Created   time.Time `json:"created,omitempty"`  // cannot be edited
	Modified  time.Time `json:"modified,omitempty"` // cannot be edited
}

func (*Project) Validate added in v0.3.0 

func (p *Project) Validate() error

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)
	Refresh(context.Context, *RefreshRequest) (*LoginReply, error)
	VerifyEmail(context.Context, *VerifyRequest) error

	// Organizations Resource
	OrganizationDetail(context.Context, string) (*Organization, 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
	APIKeyPermissions(context.Context) ([]string, error)

	// Project Resource
	ProjectCreate(context.Context, *Project) (*Project, error)
	ProjectAccess(context.Context, *Project) (*LoginReply, error)

	// Users Resource
	UserUpdate(context.Context, *User) (*User, error)
	UserList(context.Context, *UserPageQuery) (*UserList, error)
	UserDetail(context.Context, string) (*User, error)
	UserDelete(context.Context, string) error

	// Accounts Resource
	AccountUpdate(context.Context, *User) (*User, error)

	// Client Utility Functions
	WaitForReady(context.Context) 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 RefreshRequest added in v0.3.0 

type RefreshRequest struct {
	RefreshToken string `json:"refresh_token"`
}

type RegisterReply 

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

type RegisterRequest 

type RegisterRequest struct {
	ProjectID    string `json:"project_id"`
	Name         string `json:"name"`
	Email        string `json:"email"`
	Password     string `json:"password"`
	PwCheck      string `json:"pwcheck"`
	Organization string `json:"organization"`
	Domain       string `json:"domain"`
	AgreeToS     bool   `json:"terms_agreement"`
	AgreePrivacy bool   `json:"privacy_agreement"`
}

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.

type User added in v0.3.0 

type User struct {
	UserID      ulid.ULID            `json:"user_id"`
	Name        string               `json:"name"`
	Email       string               `json:"email"`
	LastLogin   string               `json:"last_login"`
	OrgID       ulid.ULID            `json:"org_id"`
	OrgRoles    map[ulid.ULID]string `json:"org_roles"`
	Permissions []string             `json:"permissions"`
}

func (*User) ValidateUpdate added in v0.3.0 

func (u *User) ValidateUpdate() error

TODO: validate Email

type UserList added in v0.4.0 

type UserList struct {
	Users         []*User `json:"users"`
	NextPageToken string  `json:"next_page_token,omitempty"`
}

type UserPageQuery added in v0.4.0 

type UserPageQuery 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"`
}

type VerifyRequest added in v0.5.0 

type VerifyRequest struct {
	Token string `json:"token"`
}

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.