store

Documentation

Index

• Variables
• func DuplicateUsernameError(username string) error
• func KeyNotFoundError(key string) error
• func NotFoundError(id string, providerID ProviderIdentity, username string) error
• func Register(storageType string, f func(func(interface{}) error) (BackendFactory, error))
• type Backend
• type BackendFactory
• type Comparison
• type Config
  • func (c *Config) UnmarshalYAML(unmarshal func(interface{}) error) error
• type Field
• type Filter
• type Identity
• type Operation
• type ProviderDataStore
• type ProviderIdentity
  • func MakeProviderIdentity(provider, id string) ProviderIdentity
  • func (p ProviderIdentity) Provider() string
  • func (p *ProviderIdentity) Scan(src interface{}) error
  • func (p ProviderIdentity) Split() (provider, id string)
  • func (p ProviderIdentity) Value() (driver.Value, error)
• type Sort
• type Store
• type Update

Variables

var (
	// ErrNotFound is the error cause used when an identity cannot be
	// found in storage.
	ErrNotFound = errgo.New("not found")

	// ErrDuplicateUsername is the error cause used when an update
	// attempts to set a username that is already in use.
	ErrDuplicateUsername = errgo.New("duplicate username")
)

Functions

func DuplicateUsernameError

func DuplicateUsernameError(username string) error

DuplicateUsernameError creates a new error with a cause of ErrDuplicateUsername and an appropriate message.

func KeyNotFoundError

func KeyNotFoundError(key string) error

KeyNotFoundError creates a new error with a cause of ErrNotFound and an appropriate message.

func NotFoundError

func NotFoundError(id string, providerID ProviderIdentity, username string) error

NotFoundError creates a new error with a cause of ErrNotFound and an appropriate message.

func Register

func Register(storageType string, f func(func(interface{}) error) (BackendFactory, error))

Register is used by storage backends to register a function that can be used to unmarshal parameters for a storage backend. When a storage backend with the given type is used, f will be called to unmarshal its parameters from YAML. Its argument will be an unmarshalYAML function that can be used to unmarshal the configuration parameters into its argument according to the rules specified in gopkg.in/yaml.v2, and it should return a function that can be used to create a storage backend.

Types

type Backend

type Backend interface {
	// ProviderDataStore returns a new ProviderDataStore
	// implementation that uses the backend.
	ProviderDataStore() ProviderDataStore

	// BakeryRootKeyStore returns a new bakery.RootKeyStore
	// implementation that uses the backend.
	BakeryRootKeyStore() bakery.RootKeyStore

	// MeetingStore returns a new meeting.Store implementation
	// that uses the backend.
	MeetingStore() meeting.Store

	// DebugStatusCheckerFuncs returns a set of
	// debugstatus.CheckerFuncs that can be used to provide a status
	// of the backend in the /debug/status endpoint.
	DebugStatusCheckerFuncs() []debugstatus.CheckerFunc

	// Store returns a new store.Store instance that uses
	// the backend.
	Store() Store

	// ACLStore returns a new aclstore.Store that is used to provide
	// ACLs for system functions.
	ACLStore() aclstore.ACLStore

	// Close closes the Backend instance.
	Close()
}

Backend is the interface provided by a storage backend implementation. Backend instances should be closed after use.

type BackendFactory

type BackendFactory interface {
	NewBackend() (Backend, error)
}

BackendFactory represents a value that can create new storage backend instances.

type Comparison

type Comparison byte

A Comparison represents a type of comparison that can be used in a filter in a Store.FindIdentities call.

const (
	NoComparison Comparison = iota
	Equal
	NotEqual
	GreaterThan
	LessThan
	GreaterThanOrEqual
	LessThanOrEqual
)

type Config

type Config struct {
	BackendFactory
}

Config allows a storage instance to be unmarshaled from a YAML configuration file. The "type" field determines which registered backend is used for the unmarshaling.

func (*Config) UnmarshalYAML

func (c *Config) UnmarshalYAML(unmarshal func(interface{}) error) error

type Field

type Field int

Field represents a field in an identity record.

const (
	ProviderID Field = iota
	Username
	Name
	Email
	Groups
	PublicKeys
	LastLogin
	LastDischarge
	ProviderInfo
	ExtraInfo
	Owner
	NumFields
)

type Filter

type Filter [NumFields]Comparison

A Filter is used in a Store.FindEntities call to specify how the identities should be filtered.

type Identity

type Identity struct {
	// ID is the internal ID of the Identity, this is allocated by
	// the store when the identity is created.
	ID string

	// ProviderID contains the provider specific ID of the identity.
	ProviderID ProviderIdentity

	// Username contains the username of the identity.
	Username string

	// Name contains the display name of the identity.
	Name string

	// Email contains the email address of the identity.
	Email string

	// Groups contains the stored set of groups of which the identity
	// is a member. This should not be used by identity providers
	// to store group information acquired at login time (that's
	// what ProviderInfo is for).
	Groups []string

	// PublicKeys contains any public keys associated with the
	// identity.
	PublicKeys []bakery.PublicKey

	// LastLogin contains the time that the identity last logged in.
	LastLogin time.Time

	// LastDischarge contains the time that the identity last logged
	// in.
	LastDischarge time.Time

	// ProviderInfo contains provider specific information associated
	// with the identity. This field is reserved for the provider to
	// add any additional data the provider requires to manage the
	// identity.
	ProviderInfo map[string][]string

	// ExtraInfo contains extra information associated with the
	// identity. This field is used for any additional data that is
	// stored with the identity, but is not directly required by the
	// identity manager.
	ExtraInfo map[string][]string

	// Owner contains the ProviderIdentity of the identity that owns
	// this one.
	Owner ProviderIdentity
}

Identity represents an identity in the store.

type Operation

type Operation byte

An Operation represents a type of update that can be applied to an identity record in a Store.UpdateIdentity call.

const (
	// NoUpdate makes no changes to the field.
	NoUpdate Operation = iota

	// Set overrides the value of the field with the specified value.
	//
	// For the ProviderInfo and ExtraInfo fields the values are
	// replaced on each specified key individually.
	Set

	// Clear removes the field from the document.
	//
	// For the ProviderInfo and ExtraInfo fields the values are
	// cleared on each specified key individually.
	Clear

	// Push ensures that all the values in the field are added to any
	// that are already present.
	//
	// For the ProviderInfo and ExtraInfo fields the new values are
	// added to each specified key individually.
	Push

	// Pull ensures that all the values in the field are removed from
	// those present. It is legal to remove values that aren't
	// already stored.
	//
	// For the ProviderInfo and ExtraInfo fields the values are
	// removed from each specified key individually.
	Pull
)

type ProviderDataStore

type ProviderDataStore interface {
	// KeyValueStore gets a key-value store for use by the given
	// identity provider.
	KeyValueStore(ctx context.Context, idp string) (simplekv.Store, error)
}

An ProviderDataStore is a data store that supports identity provider specific KeyValueStores. These stores can be used by identity providers to store data that is not directly related to an identity.

type ProviderIdentity

type ProviderIdentity string

A ProviderIdentity is a provider-specific unique identity.

func MakeProviderIdentity

func MakeProviderIdentity(provider, id string) ProviderIdentity

MakeProviderIdentity creates a ProviderIdentitiy from the given provider name and provider-specific identity.

func (ProviderIdentity) Provider

func (p ProviderIdentity) Provider() string

Provider returns the provider part of the identity.

func (*ProviderIdentity) Scan

func (p *ProviderIdentity) Scan(src interface{}) error

Scan implements sql.Scanner by converting a string value into a ProviderIdentity.

func (ProviderIdentity) Split

func (p ProviderIdentity) Split() (provider, id string)

Split splits a ProviderIdentity into provider and id parts.

func (ProviderIdentity) Value

func (p ProviderIdentity) Value() (driver.Value, error)

Value implements driver.Valuer.

type Sort

type Sort struct {
	Field      Field
	Descending bool
}

A Sort specifies the sort order of returned identities in a call to Store.FindIdenties.

type Store

type Store interface {
	// Context returns a context that is suitable for passing to the
	// other store methods. Store methods called with such a context
	// will be sequentially consistent; for example, a value that is
	// set in UpdateIdentity will immediately be available from
	// Identity.
	//
	// The returned close function must be called when the returned
	// context will no longer be used, to allow for any required
	// cleanup.
	Context(ctx context.Context) (_ context.Context, close func())

	// Identity reads the given identity from persistant storage and
	// completes all the fields. The given identity will be matched
	// using the first non-zero value of ID, ProviderID or Username.
	// If no match can found for the given identity then an error
	// with the cause ErrNotFound will be returned.
	Identity(ctx context.Context, identity *Identity) error

	// FindIdentities searches for all identities that match the
	// given ref when the given filter has been applied. The results
	// will be sorted in the order specified by sort. If limit is
	// greater than 0 then the results will contain at most that many
	// identities. If skip is greater than 0 then that many results
	// will be skipped before those that are returned.
	FindIdentities(ctx context.Context, ref *Identity, filter Filter, sort []Sort, skip, limit int) ([]Identity, error)

	// UpdateIdentity stores the data from the given identity in
	// persistant storage. The identity that is updated will be the
	// one matching the first non-zero value of ID, ProviderID or
	// Username. If the ID or username does not find a match then an
	// error with a cause of ErrNotFound will be returned. If there
	// is no match for an identity specified by ProviderID and the
	// update specifies setting the username then a new record will
	// be created for the identity, in this case the assigned ID will
	// be written back into the given identity.
	//
	// The fields that are written to the database are dictated by
	// the given UpdateOperations parameter. For each updatable field
	// this parameter will be consulted for the type of update to
	// perform. If the update would result in a duplicate username
	// being used then an error with the cause ErrDuplicateUsername
	// will be returned.
	UpdateIdentity(ctx context.Context, identity *Identity, update Update) error

	// IdentityCounts returns the number of identities stored in the
	// store split by provider ID.
	IdentityCounts(ctx context.Context) (map[string]int, error)
}

Store is the interface that represents the data storage mechanism for the identity manager.

type Update

type Update [NumFields]Operation

An Update is used in a Store.UpdateIdentity to specify how the identity record fields should be changed.