key

type Cache interface {
	Resolver

	// UpdateKeys updates all keys known to this cache.  This method makes
	// a best-effort to avoid blocking other goroutines which use ResolveKey,
	// which may mean copy-on-write semantics.
	//
	// The first return value is the count of keys for which attempts were
	// made to update.
	//
	// UpdateKeys may run multiple I/O operations.  The second return value is a slice of
	// errors that occurred while it attempted to update each key.  Exactly one (1)
	// attempt will be made to update each key present in the cache, regardless
	// of any update errors for each individual key.  This slice may be nil if no
	// errors occurred.
	UpdateKeys(ctx context.Context) (int, []error)
}

type MockCache struct {
	mock.Mock
}

type MockPair struct {
	mock.Mock
}

type MockParser struct {
	mock.Mock
}

type MockResolver struct {
	mock.Mock
}

type Pair interface {
	// Purpose returns the configured intended usage of this key pair
	Purpose() Purpose

	// Public returns the public key associated with this pair.  It will never be nil
	Public() interface{}

	// HasPrivate tests whether this key Pair has a private key
	HasPrivate() bool

	// Private returns the optional private key associated with this Pair.  If there
	// is no private key, this method returns nil.
	Private() interface{}
}

type Parser interface {
	// Parse examines data to produce a Pair.  If the returned error is not nil,
	// the Pair will always be nil.  This method is responsible for dealing with
	// any required decoding, such as PEM or DER.
	ParseKey(context.Context, Purpose, []byte) (Pair, error)
}

type Purpose int

type Resolver interface {
	// ResolveKey returns a key Pair associated with the given identifier.  The exact mechanics of resolving
	// a keyId into a Pair are implementation-specific.  Implementations are free
	// to ignore the keyId parameter altogether.
	ResolveKey(ctx context.Context, keyId string) (Pair, error)
}

type ResolverFactory struct {
	resource.Factory

	// All keys resolved by this factory will have this purpose, which affects
	// how keys are parsed.
	Purpose Purpose `json:"purpose"`

	// UpdateInterval specifies how often keys should be refreshed.
	// If negative or zero, keys are never refreshed and are cached forever.
	UpdateInterval time.Duration `json:"updateInterval"`

	// Parser is a custom key parser.  If omitted, DefaultParser is used.
	Parser Parser `json:"-"`
}

type ResolverFactoryIn struct {
	fx.In
	R *ResolverFactory `name:"key_resolver_factory"`
}

type UpdateOptions struct {
	// Ctx is the required context.  If the caller doesn't have a context, she should
	// use context.Background() here explicitly.  Not permitting nil here is a common pattern,
	// and makes client code self-documenting.
	Ctx context.Context

	// Resolver is the required key resolver that optionally implements Cache.  If this member
	// does not implement cache, no updating is done.
	Resolver Resolver

	// OpTimeout is the amount of time to wait before timing out an UpdateKeys() operation.  If
	// this is 0, then there is no timeout.
	OpTimeout time.Duration

	// Interval is the options time interval for updating.  If unset, no update should occur.
	// This allows client code to turn off updates via configuration without having to do a lot
	// of branching.
	Interval time.Duration

	// NewTicker is the factory function for a ticker.  If nil, the default is used.
	// Injecting a closure here makes testing easier, as unit tests can simply supply
	// their own factory function.
	NewTicker func(time.Duration) (<-chan time.Time, func())
}