setting

package
v1.74.1 Latest Latest
Warning

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

 Go to latest Published: Sep 18, 2024 License: BSD-3-Clause Imports: 16 Imported by: 0

Documentation

Overview

Package setting contains types for defining and representing policy settings. It facilitates the registration of setting definitions using Register and RegisterDefinition, and the retrieval of registered setting definitions via Definitions and DefinitionOf. This package is intended for use primarily within the syspolicy package hierarchy.

Index

Constants

View Source 
const (
	// DeviceSetting indicates a policy setting that applies to a device, regardless of
	// which OS user or Tailscale profile is currently active, if any.
	// It can only be configured at a [DeviceScope].
	DeviceSetting Scope = iota
	// ProfileSetting indicates a policy setting that applies to a Tailscale profile.
	// It can only be configured for a specific profile or at a [DeviceScope],
	// in which case it applies to all profiles on the device.
	ProfileSetting
	// UserSetting indicates a policy setting that applies to users.
	// It can be configured for a user, profile, or the entire device.
	UserSetting

	// NumScopes is the number of possible [Scope] values.
	NumScopes int = iota // must be the last value in the const block.
)
View Source 
const KeyPathSeparator = "/"

KeyPathSeparator allows logical grouping of policy settings into categories.

Variables

View Source 
var (
	// ErrNotConfigured is returned when the requested policy setting is not configured.
	ErrNotConfigured = errors.New("not configured")
	// ErrTypeMismatch is returned when there's a type mismatch between the actual type
	// of the setting value and the expected type.
	ErrTypeMismatch = errors.New("type mismatch")
	// ErrNoSuchKey is returned by [DefinitionOf] when no policy setting
	// has been registered with the specified key.
	//
	// Until 2024-08-02, this error was also returned by a [Handler] when the specified
	// key did not have a value set. While the package maintains compatibility with this
	// usage of ErrNoSuchKey, it is recommended to return [ErrNotConfigured] from newer
	// [source.Store] implementations.
	ErrNoSuchKey = errors.New("no such key")
)
View Source 
var (

	// DeviceScope indicates a scope containing device-global policies.
	DeviceScope = PolicyScope{/* contains filtered or unexported fields */}
	// CurrentProfileScope indicates a scope containing policies that apply to the
	// currently active Tailscale profile.
	CurrentProfileScope = PolicyScope{/* contains filtered or unexported fields */}
	// CurrentUserScope indicates a scope containing policies that apply to the
	// current user, for whatever that means on the current platform and
	// in the current application context.
	CurrentUserScope = PolicyScope{/* contains filtered or unexported fields */}
)

Functions

func Register 

func Register(k Key, s Scope, t Type, platforms ...string)

Register registers a policy setting with the specified key, scope, value type, and an optional list of supported platforms. All policy settings must be registered before any of them can be used. Register panics if called after invoking any functions that use the registered policy definitions. This includes calling Definitions or DefinitionOf directly, or reading any policy settings via syspolicy.

func RegisterDefinition 

func RegisterDefinition(d *Definition)

RegisterDefinition is like Register, but accepts a Definition.

func SetDefaultScope 

func SetDefaultScope(scope PolicyScope) bool

SetDefaultScope attempts to set the specified scope as the default scope to be used by a program when querying policy settings. It fails and returns false if called more than once, or if the DefaultScope has already been used.

func SetDefinitionsForTest 

func SetDefinitionsForTest(tb lazy.TB, ds ...*Definition) error

SetDefinitionsForTest allows to register the specified setting definitions for the test duration. It is not concurrency-safe, but unlike Register, it does not panic and can be called anytime. It returns an error if ds contains two different settings with the same Key.

Types

type Definition 

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

Definition defines policy key, scope and value type.

func DefinitionOf 

func DefinitionOf(k Key) (*Definition, error)

DefinitionOf returns a setting definition by key, or ErrNoSuchKey if the specified key does not exist, or an error if there are conflicting policy definitions.

func Definitions 

func Definitions() ([]*Definition, error)

Definitions returns all registered setting definitions, or an error if different policies were registered under the same name.

func NewDefinition 

func NewDefinition(k Key, s Scope, t Type, platforms ...string) *Definition

NewDefinition returns a new Definition with the specified key, scope, type and supported platforms (see PlatformList).

func (*Definition) Equal 

func (d *Definition) Equal(d2 *Definition) bool

Equal reports whether d and d2 have the same key, type and scope. It does not check whether both s and s2 are supported on the same platforms.

func (*Definition) IsSupported 

func (d *Definition) IsSupported() bool

IsSupported reports whether the policy setting is supported on the current OS.

func (*Definition) Key 

func (d *Definition) Key() Key

Key returns a policy setting's identifier.

func (*Definition) Scope 

func (d *Definition) Scope() Scope

Scope reports the broadest Scope the policy setting may apply to.

func (*Definition) String 

func (d *Definition) String() string

String implements fmt.Stringer.

func (*Definition) SupportedPlatforms 

func (d *Definition) SupportedPlatforms() PlatformList

SupportedPlatforms reports platforms on which the policy setting is supported. An empty PlatformList indicates that s is available on all platforms.

func (*Definition) Type 

func (d *Definition) Type() Type

Type reports the underlying value type of the policy setting.

type DefinitionMap 

type DefinitionMap map[Key]*Definition

DefinitionMap is a map of setting Definition by Key.

func DefinitionMapOf 

func DefinitionMapOf(settings []*Definition) (DefinitionMap, error)

DefinitionMapOf returns a DefinitionMap with the specified settings, or an error if any settings have the same key but different type or scope.

type ErrorText 

type ErrorText string

ErrorText represents an error that occurs when reading or parsing a policy setting. This includes errors due to permissions issues, value type and format mismatches, and other platform- or source-specific errors. It does not include ErrNotConfigured and ErrNoSuchKey, as those correspond to unconfigured policy settings rather than settings that cannot be read or parsed due to an error.

ErrorText is used to marshal errors when a policy setting is sent over the wire, allowing the error to be logged or displayed. It does not preserve the type information of the underlying error.

func MaybeErrorText added in v1.74.0 

func MaybeErrorText(err error) *ErrorText

MaybeErrorText returns an ErrorText with the text of the specified error, or nil if err is nil, ErrNotConfigured, or ErrNoSuchKey.

func NewErrorText 

func NewErrorText(text string) *ErrorText

NewErrorText returns a ErrorText with the specified error message.

func (ErrorText) Error 

func (e ErrorText) Error() string

Error implements error.

func (ErrorText) MarshalText 

func (e ErrorText) MarshalText() (text []byte, err error)

MarshalText implements encoding.TextMarshaler.

func (*ErrorText) UnmarshalText 

func (e *ErrorText) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

type Key 

type Key string

Key is a string that uniquely identifies a policy and must remain unchanged once established and documented for a given policy setting. It may contain alphanumeric characters and zero or more [KeyPathSeparator]s to group individual policy settings into categories.

type Origin 

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

Origin describes where a policy or a policy setting is configured.

func NewNamedOrigin 

func NewNamedOrigin(name string, scope PolicyScope) *Origin

NewNamedOrigin returns a new Origin with the specified scope and name.

func NewOrigin 

func NewOrigin(scope PolicyScope) *Origin

NewOrigin returns a new Origin with the specified scope.

func (Origin) MarshalJSON 

func (s Origin) MarshalJSON() ([]byte, error)

MarshalJSON implements [json.Marshaler].

func (Origin) MarshalJSONV2 

func (s Origin) MarshalJSONV2(out *jsontext.Encoder, opts jsonv2.Options) error

MarshalJSONV2 implements jsonv2.MarshalerV2.

func (Origin) Name 

func (s Origin) Name() string

Name returns the name of the policy source where the setting is configured, or "" if not available.

func (Origin) Scope 

func (s Origin) Scope() PolicyScope

Scope reports the policy PolicyScope where the setting is configured.

func (Origin) String 

func (s Origin) String() string

String implements fmt.Stringer.

func (*Origin) UnmarshalJSON 

func (s *Origin) UnmarshalJSON(b []byte) error

UnmarshalJSON implements [json.Unmarshaler].

func (*Origin) UnmarshalJSONV2 

func (s *Origin) UnmarshalJSONV2(in *jsontext.Decoder, opts jsonv2.Options) error

UnmarshalJSONV2 implements jsonv2.UnmarshalerV2.

type PlatformList 

type PlatformList []string

PlatformList is a list of OSes. An empty list indicates that all possible platforms are supported.

func (PlatformList) Has 

func (l PlatformList) Has(target string) bool

Has reports whether l contains the target platform.

func (PlatformList) HasCurrent 

func (l PlatformList) HasCurrent() bool

HasCurrent is like Has, but for the current platform.

type PolicyScope 

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

PolicyScope is a management scope.

func DefaultScope 

func DefaultScope() PolicyScope

DefaultScope returns the default PolicyScope to be used by a program when querying policy settings. It returns DeviceScope, unless explicitly changed with SetDefaultScope.

func UserScopeOf 

func UserScopeOf(uid string) PolicyScope

UserScopeOf returns a policy PolicyScope of the user with the specified id.

func (PolicyScope) Contains 

func (s PolicyScope) Contains(s2 PolicyScope) bool

Contains reports whether policy settings that apply to s also apply to s2. For example, policy settings that apply to the DeviceScope also apply to the CurrentUserScope.

func (PolicyScope) IsApplicableSetting 

func (s PolicyScope) IsApplicableSetting(setting *Definition) bool

IsApplicableSetting reports whether the specified setting applies to and can be retrieved for this scope. Policy settings are applicable to their own scopes as well as more specific scopes. For example, device settings are applicable to device, profile and user scopes, but user settings are only applicable to user scopes. For instance, a menu visibility setting is inherently a user setting and only makes sense in the context of a specific user.

func (PolicyScope) IsConfigurableSetting 

func (s PolicyScope) IsConfigurableSetting(setting *Definition) bool

IsConfigurableSetting reports whether the specified setting can be configured by a policy at this scope. Policy settings are configurable at their own scopes as well as broader scopes. For example, [UserSetting]s are configurable in user, profile, and device scopes, but [DeviceSetting]s are only configurable in the DeviceScope. For instance, the InstallUpdates policy setting can only be configured in the device scope, as it controls whether updates will be installed automatically on the device, rather than for specific users.

func (PolicyScope) Kind 

func (s PolicyScope) Kind() Scope

Kind reports the scope kind of s.

func (PolicyScope) MarshalText 

func (s PolicyScope) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (PolicyScope) StrictlyContains 

func (s PolicyScope) StrictlyContains(s2 PolicyScope) bool

StrictlyContains is like PolicyScope.Contains, but returns false when s and s2 is the same scope.

func (PolicyScope) String 

func (s PolicyScope) String() string

String implements fmt.Stringer.

func (*PolicyScope) UnmarshalText 

func (s *PolicyScope) UnmarshalText(b []byte) error

MarshalText implements encoding.TextUnmarshaler.

type PreferenceOption 

type PreferenceOption byte

PreferenceOption is a policy that governs whether a boolean variable is forcibly assigned an administrator-defined value, or allowed to receive a user-defined value. 

const (
	ShowChoiceByPolicy PreferenceOption = iota
	NeverByPolicy
	AlwaysByPolicy
)

func (PreferenceOption) IsAlways 

func (p PreferenceOption) IsAlways() bool

IsAlways reports whether the preference should always be enabled.

func (PreferenceOption) IsNever 

func (p PreferenceOption) IsNever() bool

IsNever reports whether the preference should always be disabled.

func (*PreferenceOption) MarshalText 

func (p *PreferenceOption) MarshalText() (text []byte, err error)

MarshalText implements encoding.TextMarshaler.

func (PreferenceOption) ShouldEnable 

func (p PreferenceOption) ShouldEnable(userChoice bool) bool

ShouldEnable checks if the choice administered by this policy should be enabled. If the administrator has chosen a setting, the administrator's setting is returned, otherwise userChoice is returned.

func (PreferenceOption) Show 

func (p PreferenceOption) Show() bool

Show returns if the UI option that controls the choice administered by this policy should be shown. Currently this is true if and only if the policy is ShowChoiceByPolicy.

func (PreferenceOption) String 

func (p PreferenceOption) String() string

String returns a string representation of p.

func (*PreferenceOption) UnmarshalText 

func (p *PreferenceOption) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler. It never fails and sets p to ShowChoiceByPolicy if the specified text does not represent a valid PreferenceOption.

func (PreferenceOption) WillOverride 

func (p PreferenceOption) WillOverride(userChoice bool) bool

WillOverride checks if the choice administered by the policy is different from the user's choice.

type RawItem 

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

RawItem contains a raw policy setting value as read from a policy store, or an error if the requested setting could not be read from the store. As a special case, it may also hold a value of the Visibility, PreferenceOption, or time.Duration types. While the policy store interface does not support these types natively, and the values of these types have to be unmarshalled or converted from strings, these setting types predate the typed policy hierarchies, and must be supported at this layer.

func RawItemOf 

func RawItemOf(value any) RawItem

RawItemOf returns a RawItem with the specified value.

func RawItemWith 

func RawItemWith(value any, err *ErrorText, origin *Origin) RawItem

RawItemWith returns a RawItem with the specified value, error and origin.

func (RawItem) Error 

func (i RawItem) Error() error

Error returns the error that occurred when reading the policy setting, or nil if no error occurred.

func (RawItem) Origin 

func (i RawItem) Origin() *Origin

Origin returns an optional Origin indicating where the policy setting is configured.

func (RawItem) String 

func (i RawItem) String() string

String implements fmt.Stringer.

func (RawItem) Value 

func (i RawItem) Value() any

Value returns the value of the policy setting, or nil if the policy setting is not configured, or an error occurred while reading it.

type Scope 

type Scope int8

Scope indicates the broadest scope at which a policy setting may apply, and the narrowest scope at which it may be configured.

func (Scope) MarshalText 

func (s Scope) MarshalText() (text []byte, err error)

MarshalText implements encoding.TextMarshaler.

func (Scope) String 

func (s Scope) String() string

String implements fmt.Stringer.

func (*Scope) UnmarshalText 

func (s *Scope) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

type Snapshot 

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

Snapshot is an immutable collection of (Key, RawItem) pairs, representing a set of policy settings applied at a specific moment in time. A nil pointer to Snapshot is valid.

func MergeSnapshots 

func MergeSnapshots(snapshot1, snapshot2 *Snapshot) *Snapshot

MergeSnapshots returns a Snapshot that contains all [RawItem]s from snapshot1 and snapshot2 and the Summary with the narrower PolicyScope. If there's a conflict between policy settings in the two snapshots, the policy settings from the snapshot with the broader scope take precedence. In other words, policy settings configured for the DeviceScope win over policy settings configured for a user scope.

func NewSnapshot 

func NewSnapshot(items map[Key]RawItem, opts ...SummaryOption) *Snapshot

NewSnapshot returns a new Snapshot with the specified items and options.

func (*Snapshot) All 

func (s *Snapshot) All() map[Key]RawItem

All returns a map of all policy settings in s. The returned map must not be modified.

func (*Snapshot) Equal 

func (s *Snapshot) Equal(s2 *Snapshot) bool

Equal reports whether s and s2 are equal.

func (*Snapshot) EqualItems 

func (s *Snapshot) EqualItems(s2 *Snapshot) bool

EqualItems reports whether items in s and s2 are equal.

func (*Snapshot) Get 

func (s *Snapshot) Get(k Key) any

Get returns the value of the policy setting with the specified key or nil if it is not configured or has an error.

func (*Snapshot) GetErr 

func (s *Snapshot) GetErr(k Key) (any, error)

GetErr returns the value of the policy setting with the specified key, ErrNotConfigured if it is not configured, or an error returned by the policy Store if the policy setting could not be read.

func (*Snapshot) GetSetting 

func (s *Snapshot) GetSetting(k Key) (setting RawItem, ok bool)

GetSetting returns the untyped policy setting with the specified key and true if a policy setting with such key has been configured; otherwise, it returns zero, false.

func (*Snapshot) Keys 

func (s *Snapshot) Keys() []Key

Keys return an iterator over keys in s. The iteration order is not specified and is not guaranteed to be the same from one call to the next.

func (*Snapshot) Len 

func (s *Snapshot) Len() int

Len reports the number of [RawItem]s in s.

func (*Snapshot) String 

func (s *Snapshot) String() string

String implements fmt.Stringer

func (*Snapshot) Summary 

func (s *Snapshot) Summary() Summary

Summary returns information about s as a whole rather than about specific [RawItem]s in it.

type Summary 

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

Summary is an immutable PolicyScope and Origin.

func SummaryWith 

func SummaryWith(opts ...SummaryOption) Summary

SummaryWith returns a Summary with the specified options.

func (Summary) IsEmpty 

func (s Summary) IsEmpty() bool

IsEmpty reports whether s is empty.

func (Summary) MarshalJSON 

func (s Summary) MarshalJSON() ([]byte, error)

MarshalJSON implements [json.Marshaler].

func (Summary) MarshalJSONV2 

func (s Summary) MarshalJSONV2(out *jsontext.Encoder, opts jsonv2.Options) error

MarshalJSONV2 implements jsonv2.MarshalerV2.

func (Summary) Origin 

func (s Summary) Origin() opt.Value[Origin]

Origin reports the Origin in s.

func (Summary) Scope 

func (s Summary) Scope() opt.Value[PolicyScope]

Scope reports the PolicyScope in s.

func (Summary) String 

func (s Summary) String() string

String implements fmt.Stringer.

func (*Summary) UnmarshalJSON 

func (s *Summary) UnmarshalJSON(b []byte) error

UnmarshalJSON implements [json.Unmarshaler].

func (*Summary) UnmarshalJSONV2 

func (s *Summary) UnmarshalJSONV2(in *jsontext.Decoder, opts jsonv2.Options) error

UnmarshalJSONV2 implements jsonv2.UnmarshalerV2.

type SummaryOption 

type SummaryOption interface {
	// contains filtered or unexported methods
}

SummaryOption is an option that configures Summary The following are allowed options:

type Type 

type Type int

Type is a policy setting value type. Except for InvalidValue, which represents an invalid policy setting type, and PreferenceOptionValue, VisibilityValue, and DurationValue, which have special handling due to their legacy status in the package, SettingTypes represent the raw value types readable from policy stores. 

const (
	// InvalidValue indicates an invalid policy setting value type.
	InvalidValue Type = iota
	// BooleanValue indicates a policy setting whose underlying type is a bool.
	BooleanValue
	// IntegerValue indicates a policy setting whose underlying type is a uint64.
	IntegerValue
	// StringValue indicates a policy setting whose underlying type is a string.
	StringValue
	// StringListValue indicates a policy setting whose underlying type is a []string.
	StringListValue
	// PreferenceOptionValue indicates a three-state policy setting whose
	// underlying type is a string, but the actual value is a [PreferenceOption].
	PreferenceOptionValue
	// VisibilityValue indicates a two-state boolean-like policy setting whose
	// underlying type is a string, but the actual value is a [Visibility].
	VisibilityValue
	// DurationValue indicates an interval/period/duration policy setting whose
	// underlying type is a string, but the actual value is a [time.Duration].
	DurationValue
)

func (Type) String 

func (t Type) String() string

String returns a string representation of t.

type ValueType 

type ValueType interface {
	bool | uint64 | string | []string | Visibility | PreferenceOption | time.Duration
}

ValueType is a constraint that allows Go types corresponding to Type.

type Visibility 

type Visibility byte

Visibility is a policy that controls whether or not a particular component of a user interface is to be shown. 

const (
	VisibleByPolicy Visibility = 'v'
	HiddenByPolicy  Visibility = 'h'
)

func (Visibility) MarshalText 

func (v Visibility) MarshalText() (text []byte, err error)

MarshalText implements encoding.TextMarshaler.

func (Visibility) Show 

func (v Visibility) Show() bool

Show reports whether the UI option administered by this policy should be shown. Currently this is true if the policy is not [hiddenByPolicy].

func (Visibility) String 

func (v Visibility) String() string

String returns a string representation of v.

func (*Visibility) UnmarshalText 

func (v *Visibility) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler. It never fails and sets v to VisibleByPolicy if the specified text does not represent a valid Visibility.

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.