lockbox

Documentation

Index

• Variables
• type Account
• type AccountsService
  • func (a AccountsService) Create(ctx context.Context, account Account) (Account, error)
  • func (a AccountsService) Delete(ctx context.Context, id string) error
  • func (a AccountsService) Get(ctx context.Context, id string) (Account, error)
  • func (a AccountsService) ListByProfileID(ctx context.Context, profileID string) ([]Account, error)
• type AuthMethod
• type AuthTokens
  • func (a AuthTokens) Apply(c *Client)
• type Client
  • func NewClient(ctx context.Context, baseURL string, auth ...AuthMethod) (*Client, error)
  • func (c *Client) AddTokenCredentials(r *http.Request) error
  • func (c *Client) AppendToUserAgent(s string)
  • func (c *Client) Do(req *http.Request) (*http.Response, error)
  • func (c *Client) EnableLogs()
  • func (c *Client) GetTokens() (access, refresh string)
  • func (c *Client) NewRequest(ctx context.Context, method, path string, body io.Reader) (*http.Request, error)
  • func (c *Client) PrependToUserAgent(s string)
  • func (c *Client) RefreshTokens(_ context.Context) error
• type RequestError
  • func (e RequestError) Equal(other RequestError) bool
• type RequestErrors
  • func (e RequestErrors) Contains(err RequestError) bool
  • func (e RequestErrors) FieldMatches(slug string, reg *regexp.Regexp) [][]string
• type Response

Variables

var (
	// ErrAccountRequestMissingID is returned when a request requires an
	// ID, but none was set.
	ErrAccountRequestMissingID = errors.New("request must have the ID set")

	// ErrAccountRequestMissingProfileID is returned when a request
	// requires a profile ID, but none was set.
	ErrAccountRequestMissingProfileID = errors.New("request must have the ProfileID set")

	// ErrAccountAlreadyRegistered is returned when the account that is
	// being registered has already been registered.
	ErrAccountAlreadyRegistered = errors.New("that account has already been registered")

	// ErrAccountNotFound is returned when the requested account can't be
	// found.
	ErrAccountNotFound = errors.New("account not found")

	// ErrAccountAccessDenied is returned when the authenticating
	// credentials don't have access to the requested account.
	ErrAccountAccessDenied = errors.New("account access denied")

	// ErrProfileAccessDenied is returned when the authenticating
	// credentials don't have access to the requested profile.
	ErrProfileAccessDenied = errors.New("profile access denied")
)

var (
	// ErrNoAccessTokenSet is returned when the Client tries to use an
	// access token but is not configured with one
	ErrNoAccessTokenSet = errors.New("no access token set")

	// ErrNoRefreshTokenSet is returned when the Client tries to use a
	// refresh token but is not configured with one
	ErrNoRefreshTokenSet = errors.New("no refresh token set")
)

var (
	// ErrServerError is returned when a server error is encountered while
	// making a request. Users typically can't do anything about these, and
	// they should be reported as bugs.
	ErrServerError = errors.New("server error")

	// ErrInvalidFormatError is returned when the server couldn't parse
	// the request as made. Users typically can't do anything about these,
	// and they should be reported as bugs against go-lockbox.
	ErrInvalidFormatError = errors.New("invalid request")

	// ErrInvalidRequestError is returned when the server rejected the
	// request, without giving more information as to why.
	ErrInvalidRequestError = errors.New("invalid request")

	// ErrUnauthorized is returned when a request is made that the Client
	// is not authorized to make. Check the credentials and try again.
	ErrUnauthorized = errors.New("unauthorized request")

	// ErrUnexpectedError is returned when a RequestError is returned in a
	// Response that the cliente doesn't know how to handle. This is
	// usually indicative of a bug in go-lockbox and an issue whould be
	// filed about it. The logs can provide more information on what the
	// error is.
	ErrUnexpectedError = errors.New("unexpected error in response")

	// ErrUnexpectedResponse is returned when a Response is returned that
	// doesn't make sense or that go-lockbox wasn't expecting. It's often
	// used in situations where ignoring it would cause a panic. This is
	// usually indicative of a bug in go-lockbox or the server, and an
	// issue should be filed about it. There's not much a caller can do
	// about these errors.
	ErrUnexpectedResponse = errors.New("unexpected response")
)

Types

type Account

type Account struct {
	ID             string    `json:"id,omitempty"`
	ProfileID      string    `json:"profileID,omitempty"`
	IsRegistration bool      `json:"isRegistration"`
	CreatedAt      time.Time `json:"createdAt"`
	LastSeenAt     time.Time `json:"lastSeenAt"`
	LastUsedAt     time.Time `json:"lastUsedAt"`
}

Account is an Account from the accounts service. It represents a login method available to a user.

type AccountsService

type AccountsService struct {
	BasePath string
	// contains filtered or unexported fields
}

AccountsService is the accounts service. Set the BasePath to modify where requests will be sent relative to the Client's base URL. AccountsService should only be instantiated by calling NewClient.

func (AccountsService) Create

func (a AccountsService) Create(ctx context.Context, account Account) (Account, error)

Create registers a new Account in the accounts service. If ProfileID is empty, IsRegistration must be true. If IsRegistration is false, ProfileID must be set. ProfileID cannot be set while IsRegistration is true. If ProfileID is set, the request will be authenticated with the token credentials configured on the Client.

func (AccountsService) Delete

func (a AccountsService) Delete(ctx context.Context, id string) error

Delete removes an Account from the accounts service. The request will be authenticated with the token credentials configured on the Client.

func (AccountsService) Get

func (a AccountsService) Get(ctx context.Context, id string) (Account, error)

Get retrieves the Account specified by `id` from the accounts service. The request will be authenticated with the token credentials configured on the Client.

func (AccountsService) ListByProfileID

func (a AccountsService) ListByProfileID(ctx context.Context, profileID string) ([]Account, error)

ListByProfileID returns a list of Accounts associated with profileID. The request will be authenticated with the token credentials configured on the Client.

type AuthMethod

type AuthMethod interface {
	Apply(c *Client)
}

AuthMethod is a way of authenticating the Client. When constructing a Client, passed AuthMethods will configure the Client to authenticate with various services.

type AuthTokens

type AuthTokens struct {
	Access  string
	Refresh string
}

AuthTokens configures the client with credentials necessary to authenticate against services that use token authentication, like services utilising Lockbox as an authentication service.

func (AuthTokens) Apply

func (a AuthTokens) Apply(c *Client)

Apply configures the Client `c` with the access and refresh tokens in `a`.

type Client

type Client struct {
	Accounts *AccountsService
	// contains filtered or unexported fields
}

Client is an HTTP client that can make requests against Lockbox's various services and the services that use Lockbox for authentication.

func NewClient

func NewClient(ctx context.Context, baseURL string, auth ...AuthMethod) (*Client, error)

NewClient returns a new client capable of interacting with Lockbox services. The baseURL specified should point to the URL that lockbox-apid is serving at. Any number of AuthMethods can be passed to configure the client, including none.

func (*Client) AddTokenCredentials

func (c *Client) AddTokenCredentials(r *http.Request) error

AddTokenCredentials adds the configured tokens to `r` as credentials, authenticating the request.

func (*Client) AppendToUserAgent

func (c *Client) AppendToUserAgent(s string)

AppendToUserAgent adds the string to the end of the User-Agent header that will be sent with requests from this client.

func (*Client) Do

func (c *Client) Do(req *http.Request) (*http.Response, error)

Do executes an *http.Request using the *http.Client associated with `c`.

func (*Client) EnableLogs

func (c *Client) EnableLogs()

EnableLogs turns on request and response logging for the client, for debugging purposes. This should probably not be called in production, as sensitive values will be logged.

func (*Client) GetTokens

func (c *Client) GetTokens() (access, refresh string)

GetTokens retrieves the currently set access and refresh tokens for the Client. It is meant to be used to persist the tokens to avoid authenticating on every Client instantiation; there should be no other reason to interact with the tokens this way.

func (*Client) NewRequest

func (c *Client) NewRequest(ctx context.Context, method, path string, body io.Reader) (*http.Request, error)

NewRequest builds a new *http.Request against the specified `path`, using the configured base URL of the client.

func (*Client) PrependToUserAgent

func (c *Client) PrependToUserAgent(s string)

PrependToUserAgent adds the string to the beginning of the User-Agent header that will be sent with requests from this client.

func (*Client) RefreshTokens

func (c *Client) RefreshTokens(_ context.Context) error

RefreshTokens exchanges the token credentials configured on `c` for new token credentials, and configures `c` with the new token credentials.

type RequestError

type RequestError struct {
	Slug   string `json:"error,omitempty"`
	Field  string `json:"field,omitempty"`
	Param  string `json:"param,omitempty"`
	Header string `json:"header,omitempty"`
}

RequestError describes an error that an HTTP request encountered, hopefully with enough information to point to a single root cause.

func (RequestError) Equal

func (e RequestError) Equal(other RequestError) bool

Equal returns true if two RequestErrors should be considered equivalent.

type RequestErrors

type RequestErrors []RequestError

RequestErrors is a collection of RequestErrors, describing all known errors with a request. It has its own type to facilitate helper methods.

func (RequestErrors) Contains

func (e RequestErrors) Contains(err RequestError) bool

Contains returns true if the RequestError can be found in the RequestErrors.

func (RequestErrors) FieldMatches

func (e RequestErrors) FieldMatches(slug string, reg *regexp.Regexp) [][]string

FieldMatches checks if any RequestError in e has the specified slug and a field that matches the passed regular expression.

type Response

type Response struct {
	Accounts []Account     `json:"accounts,omitempty"`
	Errors   RequestErrors `json:"errors,omitempty"`
}

Response is the standard response format we get back from every service, except the oauth2 service, which follows the standard.