source

package
v1.102.0 Latest Latest
Warning

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

 Go to latest Published: Jul 23, 2026 License: BSD-3-Clause Imports: 29 Imported by: 2

Documentation

Overview

Package source defines interfaces for policy stores, facilitates the creation of policy sources, and provides functionality for reading policy settings from these sources.

Index

Constants

This section is empty.

Variables

View Source 
var ErrStoreClosed = errors.New("the policy store has been closed")

ErrStoreClosed is an error returned when attempting to use a Store after it has been closed.

Functions

This section is empty.

Types

type Changeable 

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(), err error)
}

Changeable is an optional interface that Store implementations may support if the policy settings they contain can be externally changed after being initially read.

type EnvPolicyStore added in v1.78.0 

type EnvPolicyStore struct{}

EnvPolicyStore is a Store that reads policy settings from environment variables.

func (*EnvPolicyStore) ReadBoolean added in v1.78.0 

func (s *EnvPolicyStore) ReadBoolean(key pkey.Key) (bool, error)

ReadBoolean implements Store.

func (*EnvPolicyStore) ReadString added in v1.78.0 

func (s *EnvPolicyStore) ReadString(key pkey.Key) (string, error)

ReadString implements Store.

func (*EnvPolicyStore) ReadStringArray added in v1.78.0 

func (s *EnvPolicyStore) ReadStringArray(key pkey.Key) ([]string, error)

ReadStringArray implements Store.

func (*EnvPolicyStore) ReadUInt64 added in v1.78.0 

func (s *EnvPolicyStore) ReadUInt64(key pkey.Key) (uint64, error)

ReadUInt64 implements Store.

type Expirable 

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 that Store implementations may support if they can be externally closed or otherwise become invalid while in use.

type JSONPolicyStore added in v1.102.0 

type JSONPolicyStore struct {
	// contains filtered or unexported fields
}

JSONPolicyStore is a Store backed by a JSON object that maps policy setting keys to values. It is a read-only snapshot; the underlying map is captured at construction time and never re-read.

JSON values are mapped to policy setting types as follows:

func NewJSONPolicyStore added in v1.102.0 

func NewJSONPolicyStore(m map[string]any) *JSONPolicyStore

NewJSONPolicyStore returns a new JSONPolicyStore backed by the given map. A nil or empty map results in a store that reports every key as setting.ErrNotConfigured.

func NewJSONPolicyStoreFromBytes added in v1.102.0 

func NewJSONPolicyStoreFromBytes(data []byte) (*JSONPolicyStore, error)

NewJSONPolicyStoreFromBytes is like NewJSONPolicyStoreFromFile but reads from data instead of a file. When HuJSON support is linked into the build, data may be HuJSON (comments and trailing commas allowed); otherwise it must be pure standard JSON.

func NewJSONPolicyStoreFromFile added in v1.102.0 

func NewJSONPolicyStoreFromFile(path string) (*JSONPolicyStore, error)

NewJSONPolicyStoreFromFile reads the file at path and returns a new JSONPolicyStore backed by its contents. The file must contain a JSON object at its top level. JSON numbers are decoded as json.Number to preserve precision for setting.IntegerValue settings.

func (*JSONPolicyStore) ReadBoolean added in v1.102.0 

func (s *JSONPolicyStore) ReadBoolean(key pkey.Key) (bool, error)

ReadBoolean implements Store.

func (*JSONPolicyStore) ReadString added in v1.102.0 

func (s *JSONPolicyStore) ReadString(key pkey.Key) (string, error)

ReadString implements Store.

func (*JSONPolicyStore) ReadStringArray added in v1.102.0 

func (s *JSONPolicyStore) ReadStringArray(key pkey.Key) ([]string, error)

ReadStringArray implements Store.

func (*JSONPolicyStore) ReadUInt64 added in v1.102.0 

func (s *JSONPolicyStore) ReadUInt64(key pkey.Key) (uint64, error)

ReadUInt64 implements Store.

func (*JSONPolicyStore) Validate added in v1.102.0 

func (s *JSONPolicyStore) Validate() error

Validate checks that every key in the parsed JSON corresponds to a registered policy setting (per setting.Definitions) and that its value can be successfully decoded as the registered setting's type. It joins all problems into a single error so callers see every issue at once instead of one per startup-then-runtime cycle.

Validate triggers registration of any deferred setting definitions, so it should only be called after all init-time registrations have run.

type Lockable 

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 that Store implementations may support. Locking a Store is not mandatory as Store must be concurrency-safe, but is recommended to avoid issues where consecutive read calls for related policies might return inconsistent results if a policy change occurs between the calls. Implementations may use locking to pre-read policies or for similar performance optimizations.

type ReadableSource 

type ReadableSource struct {
	*Source
	*ReadingSession
}

ReadableSource is a Source open for reading.

func (ReadableSource) Close 

func (s ReadableSource) Close()

Close closes the underlying ReadingSession.

type ReadableSources 

type ReadableSources []ReadableSource

ReadableSources is a slice of ReadableSource.

func (*ReadableSources) Close 

func (s *ReadableSources) Close()

Close closes and deletes all sources in s.

func (ReadableSources) Contains 

func (s ReadableSources) Contains(source *Source) bool

Contains reports whether s contains the specified source.

func (*ReadableSources) DeleteAt 

func (s *ReadableSources) DeleteAt(i int)

DeleteAt closes and deletes the i-th source from s.

func (ReadableSources) IndexOf 

func (s ReadableSources) IndexOf(source *Source) int

IndexOf returns position of the specified source in s, or -1 if the source does not exist.

func (ReadableSources) InsertionIndexOf 

func (s ReadableSources) InsertionIndexOf(source *Source) int

InsertionIndexOf returns the position at which source can be inserted to 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 sorts ReadableSource in s by precedence, so that policy settings from sources with higher precedence (e.g., [DeviceScope]) will be read and merged last, overriding any policy settings with the same keys configured in sources with lower precedence (e.g., [CurrentUserScope]).

type Reader 

type Reader struct {
	// contains filtered or unexported fields
}

Reader reads all configured policy settings from a given Store. It registers a change callback with the Store and maintains the current version of the setting.Snapshot by lazily re-reading policy settings from the Store whenever a new settings snapshot is requested with Reader.GetSettings. It is safe for concurrent use.

func (*Reader) Close 

func (r *Reader) Close() error

Close closes the store reader and the underlying store.

func (*Reader) Done 

func (r *Reader) Done() <-chan struct{}

Done returns a channel that is closed when the reader is closed.

func (*Reader) GetSettings 

func (r *Reader) GetSettings() *setting.Snapshot

GetSettings returns the current *setting.Snapshot, re-reading it from the underlying Store only if the policy has changed since it was read last. It never fails and returns the 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 caller to get notified whenever a policy change is reported by the source.Store, or an ErrStoreClosed if the reader has already been closed.

func (*Reader) ReadSettings 

func (r *Reader) ReadSettings() (*setting.Snapshot, error)

ReadSettings reads policy settings from the underlying Store even if no changes were detected. It returns the new *setting.Snapshot,nil on success or an undefined snapshot (possibly `nil`) along with a non-`nil` error in case of failure.

type ReadingSession 

type ReadingSession struct {
	// contains filtered or unexported fields
}

ReadingSession is like Reader, but with a channel that's written to 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 the Reader.

func (*ReadingSession) GetSettings 

func (s *ReadingSession) GetSettings() *setting.Snapshot

GetSettings is like Reader.GetSettings.

func (*ReadingSession) PolicyChanged 

func (s *ReadingSession) PolicyChanged() <-chan struct{}

PolicyChanged returns a channel that's written to when there's a policy change, closed when the session is terminated.

func (*ReadingSession) ReadSettings 

func (s *ReadingSession) ReadSettings() (*setting.Snapshot, error)

ReadSettings is like Reader.ReadSettings.

type Source 

type Source struct {
	// contains filtered or unexported fields
}

Source represents a named source of policy settings for a given setting.PolicyScope.

func NewSource 

func NewSource(name string, scope setting.PolicyScope, store Store) *Source

NewSource returns a new Source with the specified name, scope, and store.

func (*Source) Close 

func (s *Source) Close() error

Close closes the Source and the underlying Store.

func (*Source) Compare 

func (s *Source) Compare(s2 *Source) int

Compare returns an integer comparing s and s2 by 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 

func (s *Source) Description() string

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) Name 

func (s *Source) Name() string

Name reports the name of the policy source.

func (*Source) Reader 

func (s *Source) Reader() (*Reader, error)

Reader returns a Reader that reads from this source's Store.

func (*Source) Scope 

func (s *Source) Scope() setting.PolicyScope

Scope reports the management scope of the policy source.

type Store 

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(key pkey.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(key pkey.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(key pkey.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(key pkey.Key) ([]string, error)
}

Store provides methods to read system policy settings from OS-specific storage. Implementations must be concurrency-safe, and may also implement Lockable, Changeable, Expirable and io.Closer.

If a Store implementation also implements io.Closer, it will be called by the package to release the resources when the store is no longer needed.

type TestExpectedReads 

type TestExpectedReads struct {
	// Key is the setting's unique identifier.
	Key pkey.Key
	// Type is a value type of a read operation.
	// [setting.BooleanValue], [setting.IntegerValue], [setting.StringValue] or [setting.StringListValue]
	Type setting.Type
	// NumTimes is how many times a setting with the specified key and type should have been read.
	NumTimes int
}

TestExpectedReads is the number of read operations with the specified details.

type TestSetting 

type TestSetting[T TestValueType] struct {
	// Key is the setting's unique identifier.
	Key pkey.Key
	// Error is the error to be returned by the [TestStore] when reading
	// a policy setting with the specified key.
	Error error
	// 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 a TestStore.

func TestSettingOf 

func TestSettingOf[T TestValueType](key pkey.Key, value T) TestSetting[T]

TestSettingOf returns a TestSetting representing a policy setting configured with the specified key and value.

func TestSettingWithError 

func TestSettingWithError[T TestValueType](key pkey.Key, err error) TestSetting[T]

TestSettingWithError returns a TestSetting representing a policy setting with the specified key and error.

type TestStore 

type TestStore struct {
	// contains filtered or unexported fields
}

TestStore is a Store that can be used in tests.

func NewTestStore 

func NewTestStore(tb testenv.TB) *TestStore

NewTestStore returns a new TestStore. The tb will be used to report coding errors detected by the TestStore.

func NewTestStoreOf 

func NewTestStoreOf[T TestValueType](tb testenv.TB, settings ...TestSetting[T]) *TestStore

NewTestStoreOf is a shorthand for NewTestStore followed by TestStore.SetBooleans, TestStore.SetUInt64s, TestStore.SetStrings or TestStore.SetStringLists.

func (*TestStore) Clear 

func (s *TestStore) Clear()

Clear deletes all settings from s.

func (*TestStore) Close 

func (s *TestStore) Close()

Close closes s, notifying its users that it has expired.

func (*TestStore) Delete 

func (s *TestStore) Delete(keys ...pkey.Key)

Delete deletes the specified settings from s.

func (*TestStore) Done 

func (s *TestStore) Done() <-chan struct{}

Done implements Expirable.

func (*TestStore) IsEmpty added in v1.86.0 

func (s *TestStore) IsEmpty() bool

IsEmpty reports whether the store does not contain any settings.

func (*TestStore) Lock 

func (s *TestStore) Lock() error

Lock implements Lockable.

func (*TestStore) NotifyPolicyChanged added in v1.78.0 

func (s *TestStore) NotifyPolicyChanged()

func (*TestStore) ReadBoolean 

func (s *TestStore) ReadBoolean(key pkey.Key) (bool, error)

ReadBoolean implements Store.

func (*TestStore) ReadString 

func (s *TestStore) ReadString(key pkey.Key) (string, error)

ReadString implements Store.

func (*TestStore) ReadStringArray 

func (s *TestStore) ReadStringArray(key pkey.Key) ([]string, error)

ReadStringArray implements Store.

func (*TestStore) ReadUInt64 

func (s *TestStore) ReadUInt64(key pkey.Key) (uint64, error)

ReadUInt64 implements Store.

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 be read 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 

func (s *TestStore) RegisterChangeCallback(callback func()) (unregister func(), err error)

RegisterChangeCallback implements Changeable.

func (*TestStore) ResetCounters 

func (s *TestStore) ResetCounters()

func (*TestStore) Resume 

func (s *TestStore) Resume()

Resume resumes the store, applying the changes and invoking the 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 notifications until TestStore.Resume is called the same number of times as Suspend.

func (*TestStore) Unlock 

func (s *TestStore) Unlock()

Unlock implements Lockable.

type TestValueType 

type TestValueType interface {
	bool | uint64 | string | []string
}

TestValueType is a constraint that allows types supported by TestStore.

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.