source
package
This package is not in the latest version of its module.
Details
Validgo.mod file
The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
- Redistributable license
Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
- Tagged version
Modules with tagged versions give importers more predictable builds.
- Stable version
When a project reaches major version v1 it is considered stable.
- Learn more about best practices
Repository
Links
Open Source Insights
Documentation¶
Overview¶
Package source defines interfaces for policy stores,facilitates the creation of policy sources, and providesfunctionality for reading policy settings from these sources.
Index¶
- Variables
- type Changeable
- type EnvPolicyStore
- type Expirable
- type Lockable
- type ReadableSource
- type ReadableSources
- type Reader
- type ReadingSession
- type Source
- type Store
- type TestExpectedReads
- type TestSetting
- type TestStore
- func (s *TestStore) Clear()
- func (s *TestStore) Close()
- func (s *TestStore) Delete(keys ...pkey.Key)
- func (s *TestStore) Done() <-chan struct{}
- func (s *TestStore) IsEmpty() bool
- func (s *TestStore) Lock() error
- func (s *TestStore) NotifyPolicyChanged()
- func (s *TestStore) ReadBoolean(key pkey.Key) (bool, error)
- func (s *TestStore) ReadString(key pkey.Key) (string, error)
- func (s *TestStore) ReadStringArray(key pkey.Key) ([]string, error)
- func (s *TestStore) ReadUInt64(key pkey.Key) (uint64, error)
- func (s *TestStore) ReadsMustContain(reads ...TestExpectedReads)
- func (s *TestStore) ReadsMustEqual(reads ...TestExpectedReads)
- func (s *TestStore) RegisterChangeCallback(callback func()) (unregister func(), err error)
- func (s *TestStore) ResetCounters()
- func (s *TestStore) Resume()
- func (s *TestStore) SetBooleans(settings ...TestSetting[bool])
- func (s *TestStore) SetStringLists(settings ...TestSetting[[]string])
- func (s *TestStore) SetStrings(settings ...TestSetting[string])
- func (s *TestStore) SetUInt64s(settings ...TestSetting[uint64])
- func (s *TestStore) Suspend()
- func (s *TestStore) Unlock()
- type TestValueType
Constants¶
This section is empty.
Variables¶
var ErrStoreClosed =errors.New("the policy store has been closed")ErrStoreClosed is an error returned when attempting to use aStore after ithas been closed.
Functions¶
This section is empty.
Types¶
typeChangeable¶
type Changeable interface {// RegisterChangeCallback adds a function that will be called// whenever there's a policy change in the [Store].// The returned function can be used to unregister the callback.RegisterChangeCallback(callback func()) (unregister func(), errerror)}Changeable is an optional interface thatStore implementations may supportif the policy settings they contain can be externally changed after being initially read.
typeEnvPolicyStore¶added inv1.78.0
type EnvPolicyStore struct{}EnvPolicyStore is aStore that reads policy settings from environment variables.
func (*EnvPolicyStore)ReadBoolean¶added inv1.78.0
func (s *EnvPolicyStore) ReadBoolean(keypkey.Key) (bool,error)
ReadBoolean implementsStore.
func (*EnvPolicyStore)ReadString¶added inv1.78.0
func (s *EnvPolicyStore) ReadString(keypkey.Key) (string,error)
ReadString implementsStore.
func (*EnvPolicyStore)ReadStringArray¶added inv1.78.0
func (s *EnvPolicyStore) ReadStringArray(keypkey.Key) ([]string,error)
ReadStringArray implementsStore.
func (*EnvPolicyStore)ReadUInt64¶added inv1.78.0
func (s *EnvPolicyStore) ReadUInt64(keypkey.Key) (uint64,error)
ReadUInt64 implementsStore.
typeExpirable¶
type Expirable interface {// Done returns a channel that is closed when the policy [Store] should no longer be used.// It should return nil if the store never expires.Done() <-chan struct{}}Expirable is an optional interface thatStore implementations may supportif they can be externally closed or otherwise become invalid while in use.
typeLockable¶
type Lockable interface {// Lock acquires a read lock on the policy store,// ensuring the store's state remains unchanged while locked.// Multiple readers can hold the lock simultaneously.// It returns an error if the store cannot be locked.Lock()error// Unlock unlocks the policy store.// It is a run-time error if the store is not locked on entry to Unlock.Unlock()}Lockable is an optional interface thatStore implementations may support.Locking aStore is not mandatory asStore must be concurrency-safe,but is recommended to avoid issues where consecutive read calls for relatedpolicies might return inconsistent results if a policy change occurs betweenthe calls. Implementations may use locking to pre-read policies or forsimilar performance optimizations.
typeReadableSource¶
type ReadableSource struct {*Source*ReadingSession}ReadableSource is aSource open for reading.
typeReadableSources¶
type ReadableSources []ReadableSource
ReadableSources is a slice ofReadableSource.
func (*ReadableSources)Close¶
func (s *ReadableSources) Close()
Close closes and deletes all sources in s.
func (ReadableSources)Contains¶
func (sReadableSources) Contains(source *Source)bool
Contains reports whether s contains the specified source.
func (*ReadableSources)DeleteAt¶
func (s *ReadableSources) DeleteAt(iint)
DeleteAt closes and deletes the i-th source from s.
func (ReadableSources)IndexOf¶
func (sReadableSources) IndexOf(source *Source)int
IndexOf returns position of the specified source in s, or -1if the source does not exist.
func (ReadableSources)InsertionIndexOf¶
func (sReadableSources) InsertionIndexOf(source *Source)int
InsertionIndexOf returns the position at which source can be insertedto maintain the sorted order of the readableSources.The return value is unspecified if s is not sorted on entry to InsertionIndexOf.
func (*ReadableSources)StableSort¶
func (s *ReadableSources) StableSort()
StableSort sortsReadableSource in s by precedence, so that policysettings from sources with higher precedence (e.g., [DeviceScope])will be read and merged last, overriding any policy settings withthe same keys configured in sources with lower precedence(e.g., [CurrentUserScope]).
typeReader¶
type Reader struct {// contains filtered or unexported fields}Reader reads all configured policy settings from a givenStore.It registers a change callback with theStore and maintains the current versionof thesetting.Snapshot by lazily re-reading policy settings from theStorewhenever a new settings snapshot is requested withReader.GetSettings.It is safe for concurrent use.
func (*Reader)Done¶
func (r *Reader) Done() <-chan struct{}
Done returns a channel that is closed when the reader is closed.
func (*Reader)GetSettings¶
GetSettings returns the current*setting.Snapshot,re-reading it from from the underlyingStore only if the policyhas changed since it was read last. It never fails and returnsthe previous version of the policy settings if a read attempt fails.
func (*Reader)OpenSession¶
func (r *Reader) OpenSession() (*ReadingSession,error)
OpenSession opens and returns a new session to r, allowing the callerto get notified whenever a policy change is reported by thesource.Store,or anErrStoreClosed if the reader has already been closed.
func (*Reader)ReadSettings¶
ReadSettings reads policy settings from the underlyingStore even if nochanges were detected. It returns the new*setting.Snapshot,nil onsuccess or an undefined snapshot (possibly `nil`) along with a non-`nil`error in case of failure.
typeReadingSession¶
type ReadingSession struct {// contains filtered or unexported fields}ReadingSession is likeReader, but with a channel that's writtento when there's a policy change, and closed when the session is terminated.
func (*ReadingSession)Close¶
func (s *ReadingSession) Close()
Close unregisters this session with theReader.
func (*ReadingSession)GetSettings¶
func (s *ReadingSession) GetSettings() *setting.Snapshot
GetSettings is likeReader.GetSettings.
func (*ReadingSession)PolicyChanged¶
func (s *ReadingSession) PolicyChanged() <-chan struct{}
PolicyChanged returns a channel that's written to whenthere's a policy change, closed when the session is terminated.
func (*ReadingSession)ReadSettings¶
func (s *ReadingSession) ReadSettings() (*setting.Snapshot,error)
ReadSettings is likeReader.ReadSettings.
typeSource¶
type Source struct {// contains filtered or unexported fields}Source represents a named source of policy settings for a givensetting.PolicyScope.
funcNewSource¶
func NewSource(namestring, scopesetting.PolicyScope, storeStore) *Source
NewSource returns a newSource with the specified name, scope, and store.
func (*Source)Compare¶
Compare returns an integer comparing s and s2by their precedence, following the "last-wins" model.The result will be:
-1 if policy settings from s should be processed before policy settings from s2;+1 if policy settings from s should be processed after policy settings from s2, overriding s2;0 if the relative processing order of policy settings in s and s2 is unspecified.
func (*Source)Description¶
Description returns a formatted string with the scope and name of this policy source.It can be used for logging or display purposes.
func (*Source)Scope¶
func (s *Source) Scope()setting.PolicyScope
Scope reports the management scope of the policy source.
typeStore¶
type Store interface {// ReadString returns the value of a [setting.StringValue] with the specified key,// an [setting.ErrNotConfigured] if the policy setting is not configured, or// an error on failure.ReadString(keypkey.Key) (string,error)// ReadUInt64 returns the value of a [setting.IntegerValue] with the specified key,// an [setting.ErrNotConfigured] if the policy setting is not configured, or// an error on failure.ReadUInt64(keypkey.Key) (uint64,error)// ReadBoolean returns the value of a [setting.BooleanValue] with the specified key,// an [setting.ErrNotConfigured] if the policy setting is not configured, or// an error on failure.ReadBoolean(keypkey.Key) (bool,error)// ReadStringArray returns the value of a [setting.StringListValue] with the specified key,// an [setting.ErrNotConfigured] if the policy setting is not configured, or// an error on failure.ReadStringArray(keypkey.Key) ([]string,error)}Store provides methods to read system policy settings from OS-specific storage.Implementations must be concurrency-safe, and may also implementLockable,Changeable,Expirable andio.Closer.
If aStore implementation also implementsio.Closer,it will be called by the package to release the resourceswhen the store is no longer needed.
typeTestExpectedReads¶
type TestExpectedReads struct {// Key is the setting's unique identifier.Keypkey.Key// Type is a value type of a read operation.// [setting.BooleanValue], [setting.IntegerValue], [setting.StringValue] or [setting.StringListValue]Typesetting.Type// NumTimes is how many times a setting with the specified key and type should have been read.NumTimesint}TestExpectedReads is the number of read operations with the specified details.
typeTestSetting¶
type TestSetting[TTestValueType] struct {// Key is the setting's unique identifier.Keypkey.Key// Error is the error to be returned by the [TestStore] when reading// a policy setting with the specified key.Errorerror// Value is the value to be returned by the [TestStore] when reading// a policy setting with the specified key.// It is only used if the Error is nil.Value T}
TestSetting is a policy setting in aTestStore.
funcTestSettingOf¶
func TestSettingOf[TTestValueType](keypkey.Key, value T)TestSetting[T]
TestSettingOf returns aTestSetting representing a policy settingconfigured with the specified key and value.
funcTestSettingWithError¶
func TestSettingWithError[TTestValueType](keypkey.Key, errerror)TestSetting[T]
TestSettingWithError returns aTestSetting representing a policy settingwith the specified key and error.
typeTestStore¶
type TestStore struct {// contains filtered or unexported fields}TestStore is aStore that can be used in tests.
funcNewTestStore¶
NewTestStore returns a newTestStore.The tb will be used to report coding errors detected by theTestStore.
funcNewTestStoreOf¶
func NewTestStoreOf[TTestValueType](tbtestenv.TB, settings ...TestSetting[T]) *TestStore
NewTestStoreOf is a shorthand forNewTestStore followed byTestStore.SetBooleans,TestStore.SetUInt64s,TestStore.SetStrings orTestStore.SetStringLists.
func (*TestStore)Close¶
func (s *TestStore) Close()
Close closes s, notifying its users that it has expired.
func (*TestStore)IsEmpty¶added inv1.86.0
IsEmpty reports whether the store does not contain any settings.
func (*TestStore)NotifyPolicyChanged¶added inv1.78.0
func (s *TestStore) NotifyPolicyChanged()
func (*TestStore)ReadBoolean¶
ReadBoolean implementsStore.
func (*TestStore)ReadString¶
ReadString implementsStore.
func (*TestStore)ReadStringArray¶
ReadStringArray implementsStore.
func (*TestStore)ReadUInt64¶
ReadUInt64 implementsStore.
func (*TestStore)ReadsMustContain¶
func (s *TestStore) ReadsMustContain(reads ...TestExpectedReads)
ReadsMustContain fails the test if the specified reads have not been made,or have been made a different number of times. It permits other values to beread in addition to the ones being tested.
func (*TestStore)ReadsMustEqual¶
func (s *TestStore) ReadsMustEqual(reads ...TestExpectedReads)
ReadsMustEqual fails the test if the actual reads differs from the specified reads.
func (*TestStore)RegisterChangeCallback¶
RegisterChangeCallback implementsChangeable.
func (*TestStore)ResetCounters¶
func (s *TestStore) ResetCounters()
func (*TestStore)Resume¶
func (s *TestStore) Resume()
Resume resumes the store, applying the changes and invokingthe change callbacks.
func (*TestStore)SetBooleans¶
func (s *TestStore) SetBooleans(settings ...TestSetting[bool])
SetBooleans sets the specified boolean settings in s.
func (*TestStore)SetStringLists¶
func (s *TestStore) SetStringLists(settings ...TestSetting[[]string])
SetStrings sets the specified string list settings in s.
func (*TestStore)SetStrings¶
func (s *TestStore) SetStrings(settings ...TestSetting[string])
SetStrings sets the specified string settings in s.
func (*TestStore)SetUInt64s¶
func (s *TestStore) SetUInt64s(settings ...TestSetting[uint64])
SetUInt64s sets the specified integer settings in s.
func (*TestStore)Suspend¶
func (s *TestStore) Suspend()
Suspend suspends the store, batching changes and notificationsuntilTestStore.Resume is called the same number of times as Suspend.
Source Files