webnet
/
tailscale
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

types/prefs: add a package containing generic preference types

Browse Source 
This adds a new package containing generic types to be used for defining preference hierarchies.
These include prefs.Item, prefs.List, prefs.StructList, and prefs.StructMap. Each of these types
represents a configurable preference, holding the preference's state, value, and metadata.
The metadata includes the default value (if it differs from the zero value of the Go type)
and flags indicating whether a preference is managed via syspolicy or is hidden/read-only for
another reason. This information can be marshaled and sent to the GUI, CLI and web clients
as a source of truth regarding preference configuration, management, and visibility/mutability states.

We plan to use these types to define device preferences, such as the updater preferences,
the permission mode to be used on Windows with #tailscale/corp#18342, and certain global options
that are currently exposed as tailscaled flags. We also aim to eventually use these types for
profile-local preferences in ipn.Prefs and and as a replacement for ipn.MaskedPrefs.

The generic preference types are compatible with the tailscale.com/cmd/viewer and
tailscale.com/cmd/cloner utilities.

Updates #12736

Signed-off-by: Nick Khyl <nickk@tailscale.com>
main
Nick Khyl 2 years ago committed by Nick Khyl
parent 151b77f9d6
commit af3d3c433b
14 changed files with 2877 additions and 0 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 178
      types/prefs/item.go
  2. 183
      types/prefs/list.go
  3. 159
      types/prefs/map.go
  4. 22
      types/prefs/options.go
  5. 179
      types/prefs/prefs.go
  6. 130
      types/prefs/prefs_clone_test.go
  7. 99
      types/prefs/prefs_example/prefs_example_clone.go
  8. 239
      types/prefs/prefs_example/prefs_example_view.go
  9. 140
      types/prefs/prefs_example/prefs_test.go
  10. 166
      types/prefs/prefs_example/prefs_types.go
  11. 670
      types/prefs/prefs_test.go
  12. 342
      types/prefs/prefs_view_test.go
  13. 195
      types/prefs/struct_list.go
  14. 175
      types/prefs/struct_map.go

178
types/prefs/item.go
Unescape View File

@ -0,0 +1,178 @@
// Copyright (c) Tailscale Inc & AUTHORS
// SPDX-License-Identifier: BSD-3-Clause
package prefs
import (
"fmt"
jsonv2 "github.com/go-json-experiment/json"
"github.com/go-json-experiment/json/jsontext"
"tailscale.com/types/opt"
"tailscale.com/types/ptr"
"tailscale.com/types/views"
"tailscale.com/util/must"
)
// Item is a single preference item that can be configured.
// T must either be an immutable type or implement the [views.ViewCloner] interface.
type Item[T any] struct {
preference[T]
}
// ItemOf returns an [Item] configured with the specified value and [Options].
func ItemOf[T any](v T, opts ...Options) Item[T] {
return Item[T]{preferenceOf(opt.ValueOf(must.Get(deepClone(v))), opts...)}
}
// ItemWithOpts returns an unconfigured [Item] with the specified [Options].
func ItemWithOpts[T any](opts ...Options) Item[T] {
return Item[T]{preferenceOf(opt.Value[T]{}, opts...)}
}
// SetValue configures the preference with the specified value.
// It fails and returns [ErrManaged] if p is a managed preference,
// and [ErrReadOnly] if p is a read-only preference.
func (i *Item[T]) SetValue(val T) error {
return i.preference.SetValue(must.Get(deepClone(val)))
}
// SetManagedValue configures the preference with the specified value
// and marks the preference as managed.
func (i *Item[T]) SetManagedValue(val T) {
i.preference.SetManagedValue(must.Get(deepClone(val)))
}
// Clone returns a copy of i that aliases no memory with i.
// It is a runtime error to call [Item.Clone] if T contains pointers
// but does not implement [views.Cloner].
func (i Item[T]) Clone() *Item[T] {
res := ptr.To(i)
if v, ok := i.ValueOk(); ok {
res.s.Value.Set(must.Get(deepClone(v)))
}
return res
}
// Equal reports whether i and i2 are equal.
// If the template type T implements an Equal(T) bool method, it will be used
// instead of the == operator for value comparison.
// If T is not comparable, it reports false.
func (i Item[T]) Equal(i2 Item[T]) bool {
if i.s.Metadata != i2.s.Metadata {
return false
}
return i.s.Value.Equal(i2.s.Value)
}
func deepClone[T any](v T) (T, error) {
if c, ok := any(v).(views.Cloner[T]); ok {
return c.Clone(), nil
}
if !views.ContainsPointers[T]() {
return v, nil
}
var zero T
return zero, fmt.Errorf("%T contains pointers, but does not implement Clone", v)
}
// ItemView is a read-only view of an [Item][T], where T is a mutable type
// implementing [views.ViewCloner].
type ItemView[T views.ViewCloner[T, V], V views.StructView[T]] struct {
// ж is the underlying mutable value, named with a hard-to-type
// character that looks pointy like a pointer.
// It is named distinctively to make you think of how dangerous it is to escape
// to callers. You must not let callers be able to mutate it.
ж *Item[T]
}
// ItemViewOf returns a read-only view of i.
// It is used by [tailscale.com/cmd/viewer].
func ItemViewOf[T views.ViewCloner[T, V], V views.StructView[T]](i *Item[T]) ItemView[T, V] {
return ItemView[T, V]{i}
}
// Valid reports whether the underlying [Item] is non-nil.
func (iv ItemView[T, V]) Valid() bool {
return iv.ж != nil
}
// AsStruct implements [views.StructView] by returning a clone of the preference
// which aliases no memory with the original.
func (iv ItemView[T, V]) AsStruct() *Item[T] {
if iv.ж == nil {
return nil
}
return iv.ж.Clone()
}
// IsSet reports whether the preference has a value set.
func (iv ItemView[T, V]) IsSet() bool {
return iv.ж.IsSet()
}
// Value returns a read-only view of the value if the preference has a value set.
// Otherwise, it returns a read-only view of its default value.
func (iv ItemView[T, V]) Value() V {
return iv.ж.Value().View()
}
// ValueOk returns a read-only view of the value and true if the preference has a value set.
// Otherwise, it returns an invalid view and false.
func (iv ItemView[T, V]) ValueOk() (val V, ok bool) {
if val, ok := iv.ж.ValueOk(); ok {
return val.View(), true
}
return val, false
}
// DefaultValue returns a read-only view of the default value of the preference.
func (iv ItemView[T, V]) DefaultValue() V {
return iv.ж.DefaultValue().View()
}
// IsManaged reports whether the preference is managed via MDM, Group Policy, or similar means.
func (iv ItemView[T, V]) IsManaged() bool {
return iv.ж.IsManaged()
}
// IsReadOnly reports whether the preference is read-only and cannot be changed by user.
func (iv ItemView[T, V]) IsReadOnly() bool {
return iv.ж.IsReadOnly()
}
// Equal reports whether iv and iv2 are equal.
func (iv ItemView[T, V]) Equal(iv2 ItemView[T, V]) bool {
if !iv.Valid() && !iv2.Valid() {
return true
}
if iv.Valid() != iv2.Valid() {
return false
}
return iv.ж.Equal(*iv2.ж)
}
// MarshalJSONV2 implements [jsonv2.MarshalerV2].
func (iv ItemView[T, V]) MarshalJSONV2(out *jsontext.Encoder, opts jsonv2.Options) error {
return iv.ж.MarshalJSONV2(out, opts)
}
// UnmarshalJSONV2 implements [jsonv2.UnmarshalerV2].
func (iv *ItemView[T, V]) UnmarshalJSONV2(in *jsontext.Decoder, opts jsonv2.Options) error {
var x Item[T]
if err := x.UnmarshalJSONV2(in, opts); err != nil {
return err
}
iv.ж = &x
return nil
}
// MarshalJSON implements [json.Marshaler].
func (iv ItemView[T, V]) MarshalJSON() ([]byte, error) {
return jsonv2.Marshal(iv) // uses MarshalJSONV2
}
// UnmarshalJSON implements [json.Unmarshaler].
func (iv *ItemView[T, V]) UnmarshalJSON(b []byte) error {
return jsonv2.Unmarshal(b, iv) // uses UnmarshalJSONV2
}

183
types/prefs/list.go
Unescape View File

@ -0,0 +1,183 @@
// Copyright (c) Tailscale Inc & AUTHORS
// SPDX-License-Identifier: BSD-3-Clause
package prefs
import (
"net/netip"
"slices"
"time"
jsonv2 "github.com/go-json-experiment/json"
"github.com/go-json-experiment/json/jsontext"
"golang.org/x/exp/constraints"
"tailscale.com/types/opt"
"tailscale.com/types/ptr"
"tailscale.com/types/views"
)
// BasicType is a constraint that allows types whose underlying type is a predeclared
// boolean, numeric, or string type.
type BasicType interface {
~bool | constraints.Integer | constraints.Float | constraints.Complex | ~string
}
// ImmutableType is a constraint that allows [BasicType]s and certain well-known immutable types.
type ImmutableType interface {
BasicType | time.Time | netip.Addr | netip.Prefix | netip.AddrPort
}
// List is a preference type that holds zero or more values of an [ImmutableType] T.
type List[T ImmutableType] struct {
preference[[]T]
}
// ListOf returns a [List] configured with the specified value and [Options].
func ListOf[T ImmutableType](v []T, opts ...Options) List[T] {
return List[T]{preferenceOf(opt.ValueOf(cloneSlice(v)), opts...)}
}
// ListWithOpts returns an unconfigured [List] with the specified [Options].
func ListWithOpts[T ImmutableType](opts ...Options) List[T] {
return List[T]{preferenceOf(opt.Value[[]T]{}, opts...)}
}
// SetValue configures the preference with the specified value.
// It fails and returns [ErrManaged] if p is a managed preference,
// and [ErrReadOnly] if p is a read-only preference.
func (l *List[T]) SetValue(val []T) error {
return l.preference.SetValue(cloneSlice(val))
}
// SetManagedValue configures the preference with the specified value
// and marks the preference as managed.
func (l *List[T]) SetManagedValue(val []T) {
l.preference.SetManagedValue(cloneSlice(val))
}
// View returns a read-only view of l.
func (l *List[T]) View() ListView[T] {
return ListView[T]{l}
}
// Clone returns a copy of l that aliases no memory with l.
func (l List[T]) Clone() *List[T] {
res := ptr.To(l)
if v, ok := l.s.Value.GetOk(); ok {
res.s.Value.Set(append(v[:0:0], v...))
}
return res
}
// Equal reports whether l and l2 are equal.
func (l List[T]) Equal(l2 List[T]) bool {
if l.s.Metadata != l2.s.Metadata {
return false
}
v1, ok1 := l.s.Value.GetOk()
v2, ok2 := l2.s.Value.GetOk()
if ok1 != ok2 {
return false
}
return !ok1 || slices.Equal(v1, v2)
}
func cloneSlice[T ImmutableType](s []T) []T {
c := make([]T, len(s))
copy(c, s)
return c
}
// ListView is a read-only view of a [List].
type ListView[T ImmutableType] struct {
// ж is the underlying mutable value, named with a hard-to-type
// character that looks pointy like a pointer.
// It is named distinctively to make you think of how dangerous it is to escape
// to callers. You must not let callers be able to mutate it.
ж *List[T]
}
// Valid reports whether the underlying [List] is non-nil.
func (lv ListView[T]) Valid() bool {
return lv.ж != nil
}
// AsStruct implements [views.StructView] by returning a clone of the [List]
// which aliases no memory with the original.
func (lv ListView[T]) AsStruct() *List[T] {
if lv.ж == nil {
return nil
}
return lv.ж.Clone()
}
// IsSet reports whether the preference has a value set.
func (lv ListView[T]) IsSet() bool {
return lv.ж.IsSet()
}
// Value returns a read-only view of the value if the preference has a value set.
// Otherwise, it returns a read-only view of its default value.
func (lv ListView[T]) Value() views.Slice[T] {
return views.SliceOf(lv.ж.Value())
}
// ValueOk returns a read-only view of the value and true if the preference has a value set.
// Otherwise, it returns an invalid view and false.
func (lv ListView[T]) ValueOk() (val views.Slice[T], ok bool) {
if v, ok := lv.ж.ValueOk(); ok {
return views.SliceOf(v), true
}
return views.Slice[T]{}, false
}
// DefaultValue returns a read-only view of the default value of the preference.
func (lv ListView[T]) DefaultValue() views.Slice[T] {
return views.SliceOf(lv.ж.DefaultValue())
}
// IsManaged reports whether the preference is managed via MDM, Group Policy, or similar means.
func (lv ListView[T]) IsManaged() bool {
return lv.ж.IsManaged()
}
// IsReadOnly reports whether the preference is read-only and cannot be changed by user.
func (lv ListView[T]) IsReadOnly() bool {
return lv.ж.IsReadOnly()
}
// Equal reports whether lv and lv2 are equal.
func (lv ListView[T]) Equal(lv2 ListView[T]) bool {
if !lv.Valid() && !lv2.Valid() {
return true
}
if lv.Valid() != lv2.Valid() {
return false
}
return lv.ж.Equal(*lv2.ж)
}
// MarshalJSONV2 implements [jsonv2.MarshalerV2].
func (lv ListView[T]) MarshalJSONV2(out *jsontext.Encoder, opts jsonv2.Options) error {
return lv.ж.MarshalJSONV2(out, opts)
}
// UnmarshalJSONV2 implements [jsonv2.UnmarshalerV2].
func (lv *ListView[T]) UnmarshalJSONV2(in *jsontext.Decoder, opts jsonv2.Options) error {
var x List[T]
if err := x.UnmarshalJSONV2(in, opts); err != nil {
return err
}
lv.ж = &x
return nil
}
// MarshalJSON implements [json.Marshaler].
func (lv ListView[T]) MarshalJSON() ([]byte, error) {
return jsonv2.Marshal(lv) // uses MarshalJSONV2
}
// UnmarshalJSON implements [json.Unmarshaler].
func (lv *ListView[T]) UnmarshalJSON(b []byte) error {
return jsonv2.Unmarshal(b, lv) // uses UnmarshalJSONV2
}

159
types/prefs/map.go
Unescape View File

@ -0,0 +1,159 @@
// Copyright (c) Tailscale Inc & AUTHORS
// SPDX-License-Identifier: BSD-3-Clause
package prefs
import (
"maps"
"net/netip"
jsonv2 "github.com/go-json-experiment/json"
"github.com/go-json-experiment/json/jsontext"
"golang.org/x/exp/constraints"
"tailscale.com/types/opt"
"tailscale.com/types/ptr"
"tailscale.com/types/views"
)
// MapKeyType is a constraint allowing types that can be used as [Map] and [StructMap] keys.
// To satisfy this requirement, a type must be comparable and must encode as a JSON string.
// See [jsonv2.Marshal] for more details.
type MapKeyType interface {
~string | constraints.Integer | netip.Addr | netip.Prefix | netip.AddrPort
}
// Map is a preference type that holds immutable key-value pairs.
type Map[K MapKeyType, V ImmutableType] struct {
preference[map[K]V]
}
// MapOf returns a map configured with the specified value and [Options].
func MapOf[K MapKeyType, V ImmutableType](v map[K]V, opts ...Options) Map[K, V] {
return Map[K, V]{preferenceOf(opt.ValueOf(v), opts...)}
}
// MapWithOpts returns an unconfigured [Map] with the specified [Options].
func MapWithOpts[K MapKeyType, V ImmutableType](opts ...Options) Map[K, V] {
return Map[K, V]{preferenceOf(opt.Value[map[K]V]{}, opts...)}
}
// View returns a read-only view of m.
func (m *Map[K, V]) View() MapView[K, V] {
return MapView[K, V]{m}
}
// Clone returns a copy of m that aliases no memory with m.
func (m Map[K, V]) Clone() *Map[K, V] {
res := ptr.To(m)
if v, ok := m.s.Value.GetOk(); ok {
res.s.Value.Set(maps.Clone(v))
}
return res
}
// Equal reports whether m and m2 are equal.
func (m Map[K, V]) Equal(m2 Map[K, V]) bool {
if m.s.Metadata != m2.s.Metadata {
return false
}
v1, ok1 := m.s.Value.GetOk()
v2, ok2 := m2.s.Value.GetOk()
if ok1 != ok2 {
return false
}
return !ok1 || maps.Equal(v1, v2)
}
// MapView is a read-only view of a [Map].
type MapView[K MapKeyType, V ImmutableType] struct {
// ж is the underlying mutable value, named with a hard-to-type
// character that looks pointy like a pointer.
// It is named distinctively to make you think of how dangerous it is to escape
// to callers. You must not let callers be able to mutate it.
ж *Map[K, V]
}
// Valid reports whether the underlying [Map] is non-nil.
func (mv MapView[K, V]) Valid() bool {
return mv.ж != nil
}
// AsStruct implements [views.StructView] by returning a clone of the [Map]
// which aliases no memory with the original.
func (mv MapView[K, V]) AsStruct() *Map[K, V] {
if mv.ж == nil {
return nil
}
return mv.ж.Clone()
}
// IsSet reports whether the preference has a value set.
func (mv MapView[K, V]) IsSet() bool {
return mv.ж.IsSet()
}
// Value returns a read-only view of the value if the preference has a value set.
// Otherwise, it returns a read-only view of its default value.
func (mv MapView[K, V]) Value() views.Map[K, V] {
return views.MapOf(mv.ж.Value())
}
// ValueOk returns a read-only view of the value and true if the preference has a value set.
// Otherwise, it returns an invalid view and false.
func (mv MapView[K, V]) ValueOk() (val views.Map[K, V], ok bool) {
if v, ok := mv.ж.ValueOk(); ok {
return views.MapOf(v), true
}
return views.Map[K, V]{}, false
}
// DefaultValue returns a read-only view of the default value of the preference.
func (mv MapView[K, V]) DefaultValue() views.Map[K, V] {
return views.MapOf(mv.ж.DefaultValue())
}
// Managed reports whether the preference is managed via MDM, Group Policy, or similar means.
func (mv MapView[K, V]) Managed() bool {
return mv.ж.IsManaged()
}
// ReadOnly reports whether the preference is read-only and cannot be changed by user.
func (mv MapView[K, V]) ReadOnly() bool {
return mv.ж.IsReadOnly()
}
// Equal reports whether mv and mv2 are equal.
func (mv MapView[K, V]) Equal(mv2 MapView[K, V]) bool {
if !mv.Valid() && !mv2.Valid() {
return true
}
if mv.Valid() != mv2.Valid() {
return false
}
return mv.ж.Equal(*mv2.ж)
}
// MarshalJSONV2 implements [jsonv2.MarshalerV2].
func (mv MapView[K, V]) MarshalJSONV2(out *jsontext.Encoder, opts jsonv2.Options) error {
return mv.ж.MarshalJSONV2(out, opts)
}
// UnmarshalJSONV2 implements [jsonv2.UnmarshalerV2].
func (mv *MapView[K, V]) UnmarshalJSONV2(in *jsontext.Decoder, opts jsonv2.Options) error {
var x Map[K, V]
if err := x.UnmarshalJSONV2(in, opts); err != nil {
return err
}
mv.ж = &x
return nil
}
// MarshalJSON implements [json.Marshaler].
func (mv MapView[K, V]) MarshalJSON() ([]byte, error) {
return jsonv2.Marshal(mv) // uses MarshalJSONV2
}
// UnmarshalJSON implements [json.Unmarshaler].
func (mv *MapView[K, V]) UnmarshalJSON(b []byte) error {
return jsonv2.Unmarshal(b, mv) // uses UnmarshalJSONV2
}

22
types/prefs/options.go
Unescape View File

@ -0,0 +1,22 @@
// Copyright (c) Tailscale Inc & AUTHORS
// SPDX-License-Identifier: BSD-3-Clause
package prefs
// Options are used to configure additional parameters of a preference.
type Options func(s *metadata)
var (
// ReadOnly is an option that marks preference as read-only.
ReadOnly Options = markReadOnly
// Managed is an option that marks preference as managed.
Managed Options = markManaged
)
func markReadOnly(s *metadata) {
s.ReadOnly = true
}
func markManaged(s *metadata) {
s.Managed = true
}

179
types/prefs/prefs.go
Unescape View File

@ -0,0 +1,179 @@
// Copyright (c) Tailscale Inc & AUTHORS
// SPDX-License-Identifier: BSD-3-Clause
// Package prefs contains types and functions to work with arbitrary
// preference hierarchies.
//
// Specifically, the package provides [Item], [List], [Map], [StructList] and [StructMap]
// types which represent individual preferences in a user-defined prefs struct.
// A valid prefs struct must contain one or more exported fields of the preference types,
// either directly or within nested structs, but not pointers to these types.
// Additionally to preferences, a prefs struct may contain any number of
// non-preference fields that will be marshalled and unmarshalled but are
// otherwise ignored by the prefs package.
//
// The preference types are compatible with the [tailscale.com/cmd/viewer] and
// [tailscale.com/cmd/cloner] utilities. It is recommended to generate a read-only view
// of the user-defined prefs structure and use it in place of prefs whenever the prefs
// should not be modified.
package prefs
import (
"errors"
jsonv2 "github.com/go-json-experiment/json"
"github.com/go-json-experiment/json/jsontext"
"tailscale.com/types/opt"
)
var (
// ErrManaged is the error returned when attempting to modify a managed preference.
ErrManaged = errors.New("cannot modify a managed preference")
// ErrReadOnly is the error returned when attempting to modify a readonly preference.
ErrReadOnly = errors.New("cannot modify a readonly preference")
)
// metadata holds type-agnostic preference metadata.
type metadata struct {
// Managed indicates whether the preference is managed via MDM, Group Policy, or other means.
Managed bool `json:",omitzero"`
// ReadOnly indicates whether the preference is read-only due to any other reasons,
// such as user's access rights.
ReadOnly bool `json:",omitzero"`
}
// serializable is a JSON-serializable preference data.
type serializable[T any] struct {
// Value is an optional preference value that is set when the preference is
// configured by the user or managed by an admin.
Value opt.Value[T] `json:",omitzero"`
// Default is the default preference value to be used
// when the preference has not been configured.
Default T `json:",omitzero"`
// Metadata is any additional type-agnostic preference metadata to be serialized.
Metadata metadata `json:",inline"`
}
// preference is an embeddable type that provides a common implementation for
// concrete preference types, such as [Item], [List], [Map], [StructList] and [StructMap].
type preference[T any] struct {
s serializable[T]
}
// preferenceOf returns a preference with the specified value and/or [Options].
func preferenceOf[T any](v opt.Value[T], opts ...Options) preference[T] {
var m metadata
for _, o := range opts {
o(&m)
}
return preference[T]{serializable[T]{Value: v, Metadata: m}}
}
// IsSet reports whether p has a value set.
func (p preference[T]) IsSet() bool {
return p.s.Value.IsSet()
}
// Value returns the value of p if the preference has a value set.
// Otherwise, it returns its default value.
func (p preference[T]) Value() T {
val, _ := p.ValueOk()
return val
}
// ValueOk returns the value of p and true if the preference has a value set.
// Otherwise, it returns its default value and false.
func (p preference[T]) ValueOk() (val T, ok bool) {
if val, ok = p.s.Value.GetOk(); ok {
return val, true
}
return p.DefaultValue(), false
}
// SetValue configures the preference with the specified value.
// It fails and returns [ErrManaged] if p is a managed preference,
// and [ErrReadOnly] if p is a read-only preference.
func (p *preference[T]) SetValue(val T) error {
switch {
case p.s.Metadata.Managed:
return ErrManaged
case p.s.Metadata.ReadOnly:
return ErrReadOnly
default:
p.s.Value.Set(val)
return nil
}
}
// ClearValue resets the preference to an unconfigured state.
// It fails and returns [ErrManaged] if p is a managed preference,
// and [ErrReadOnly] if p is a read-only preference.
func (p *preference[T]) ClearValue() error {
switch {
case p.s.Metadata.Managed:
return ErrManaged
case p.s.Metadata.ReadOnly:
return ErrReadOnly
default:
p.s.Value.Clear()
return nil
}
}
// DefaultValue returns the default value of p.
func (p preference[T]) DefaultValue() T {
return p.s.Default
}
// SetDefaultValue sets the default value of p.
func (p *preference[T]) SetDefaultValue(def T) {
p.s.Default = def
}
// IsManaged reports whether p is managed via MDM, Group Policy, or similar means.
func (p preference[T]) IsManaged() bool {
return p.s.Metadata.Managed
}
// SetManagedValue configures the preference with the specified value
// and marks the preference as managed.
func (p *preference[T]) SetManagedValue(val T) {
p.s.Value.Set(val)
p.s.Metadata.Managed = true
}
// ClearManaged clears the managed flag of the preference without altering its value.
func (p *preference[T]) ClearManaged() {
p.s.Metadata.Managed = false
}
// IsReadOnly reports whether p is read-only and cannot be changed by user.
func (p preference[T]) IsReadOnly() bool {
return p.s.Metadata.ReadOnly || p.s.Metadata.Managed
}
// SetReadOnly sets the read-only status of p, preventing changes by a user if set to true.
func (p *preference[T]) SetReadOnly(readonly bool) {
p.s.Metadata.ReadOnly = readonly
}
// MarshalJSONV2 implements [jsonv2.MarshalerV2].
func (p preference[T]) MarshalJSONV2(out *jsontext.Encoder, opts jsonv2.Options) error {
return jsonv2.MarshalEncode(out, &p.s, opts)
}
// UnmarshalJSONV2 implements [jsonv2.UnmarshalerV2].
func (p *preference[T]) UnmarshalJSONV2(in *jsontext.Decoder, opts jsonv2.Options) error {
return jsonv2.UnmarshalDecode(in, &p.s, opts)
}
// MarshalJSON implements [json.Marshaler].
func (p preference[T]) MarshalJSON() ([]byte, error) {
return jsonv2.Marshal(p) // uses MarshalJSONV2
}
// UnmarshalJSON implements [json.Unmarshaler].
func (p *preference[T]) UnmarshalJSON(b []byte) error {
return jsonv2.Unmarshal(b, p) // uses UnmarshalJSONV2
}

130
types/prefs/prefs_clone_test.go
Unescape View File

@ -0,0 +1,130 @@
// Copyright (c) Tailscale Inc & AUTHORS
// SPDX-License-Identifier: BSD-3-Clause
// Code generated by tailscale.com/cmd/cloner; DO NOT EDIT.
package prefs
import (
"net/netip"
"tailscale.com/types/ptr"
)
// Clone makes a deep copy of TestPrefs.
// The result aliases no memory with the original.
func (src *TestPrefs) Clone() *TestPrefs {
if src == nil {
return nil
}
dst := new(TestPrefs)
*dst = *src
dst.StringSlice = *src.StringSlice.Clone()
dst.IntSlice = *src.IntSlice.Clone()
dst.StringStringMap = *src.StringStringMap.Clone()
dst.IntStringMap = *src.IntStringMap.Clone()
dst.AddrIntMap = *src.AddrIntMap.Clone()
dst.Bundle1 = *src.Bundle1.Clone()
dst.Bundle2 = *src.Bundle2.Clone()
dst.Generic = *src.Generic.Clone()
dst.BundleList = *src.BundleList.Clone()
dst.StringBundleMap = *src.StringBundleMap.Clone()
dst.IntBundleMap = *src.IntBundleMap.Clone()
dst.AddrBundleMap = *src.AddrBundleMap.Clone()
return dst
}
// A compilation failure here means this code must be regenerated, with the command at the top of this file.
var _TestPrefsCloneNeedsRegeneration = TestPrefs(struct {
Int32Item Item[int32]
UInt64Item Item[uint64]
StringItem1 Item[string]
StringItem2 Item[string]
BoolItem1 Item[bool]
BoolItem2 Item[bool]
StringSlice List[string]
IntSlice List[int]
AddrItem Item[netip.Addr]
StringStringMap Map[string, string]
IntStringMap Map[int, string]
AddrIntMap Map[netip.Addr, int]
Bundle1 Item[*TestBundle]
Bundle2 Item[*TestBundle]
Generic Item[*TestGenericStruct[int]]
BundleList StructList[*TestBundle]
StringBundleMap StructMap[string, *TestBundle]
IntBundleMap StructMap[int, *TestBundle]
AddrBundleMap StructMap[netip.Addr, *TestBundle]
Group TestPrefsGroup
}{})
// Clone makes a deep copy of TestBundle.
// The result aliases no memory with the original.
func (src *TestBundle) Clone() *TestBundle {
if src == nil {
return nil
}
dst := new(TestBundle)
*dst = *src
if dst.Nested != nil {
dst.Nested = ptr.To(*src.Nested)
}
return dst
}
// A compilation failure here means this code must be regenerated, with the command at the top of this file.
var _TestBundleCloneNeedsRegeneration = TestBundle(struct {
Name string
Nested *TestValueStruct
}{})
// Clone makes a deep copy of TestValueStruct.
// The result aliases no memory with the original.
func (src *TestValueStruct) Clone() *TestValueStruct {
if src == nil {
return nil
}
dst := new(TestValueStruct)
*dst = *src
return dst
}
// A compilation failure here means this code must be regenerated, with the command at the top of this file.
var _TestValueStructCloneNeedsRegeneration = TestValueStruct(struct {
Value int
}{})
// Clone makes a deep copy of TestGenericStruct.
// The result aliases no memory with the original.
func (src *TestGenericStruct[T]) Clone() *TestGenericStruct[T] {
if src == nil {
return nil
}
dst := new(TestGenericStruct[T])
*dst = *src
return dst
}
// A compilation failure here means this code must be regenerated, with the command at the top of this file.
func _TestGenericStructCloneNeedsRegeneration[T ImmutableType](TestGenericStruct[T]) {
_TestGenericStructCloneNeedsRegeneration(struct {
Value T
}{})
}
// Clone makes a deep copy of TestPrefsGroup.
// The result aliases no memory with the original.
func (src *TestPrefsGroup) Clone() *TestPrefsGroup {
if src == nil {
return nil
}
dst := new(TestPrefsGroup)
*dst = *src
return dst
}
// A compilation failure here means this code must be regenerated, with the command at the top of this file.
var _TestPrefsGroupCloneNeedsRegeneration = TestPrefsGroup(struct {
FloatItem Item[float64]
TestStringItem Item[TestStringType]
}{})

99
types/prefs/prefs_example/prefs_example_clone.go
Unescape View File

@ -0,0 +1,99 @@
// Copyright (c) Tailscale Inc & AUTHORS
// SPDX-License-Identifier: BSD-3-Clause
// Code generated by tailscale.com/cmd/cloner; DO NOT EDIT.
package prefs_example
import (
"net/netip"
"tailscale.com/drive"
"tailscale.com/tailcfg"
"tailscale.com/types/opt"
"tailscale.com/types/persist"
"tailscale.com/types/prefs"
"tailscale.com/types/preftype"
)
// Clone makes a deep copy of Prefs.
// The result aliases no memory with the original.
func (src *Prefs) Clone() *Prefs {
if src == nil {
return nil
}
dst := new(Prefs)
*dst = *src
dst.AdvertiseTags = *src.AdvertiseTags.Clone()
dst.AdvertiseRoutes = *src.AdvertiseRoutes.Clone()
dst.DriveShares = *src.DriveShares.Clone()
dst.Persist = src.Persist.Clone()
return dst
}
// A compilation failure here means this code must be regenerated, with the command at the top of this file.
var _PrefsCloneNeedsRegeneration = Prefs(struct {
ControlURL prefs.Item[string]
RouteAll prefs.Item[bool]
ExitNodeID prefs.Item[tailcfg.StableNodeID]
ExitNodeIP prefs.Item[netip.Addr]
ExitNodePrior tailcfg.StableNodeID
ExitNodeAllowLANAccess prefs.Item[bool]
CorpDNS prefs.Item[bool]
RunSSH prefs.Item[bool]
RunWebClient prefs.Item[bool]
WantRunning prefs.Item[bool]
LoggedOut prefs.Item[bool]
ShieldsUp prefs.Item[bool]
AdvertiseTags prefs.List[string]
Hostname prefs.Item[string]
NotepadURLs prefs.Item[bool]
ForceDaemon prefs.Item[bool]
Egg prefs.Item[bool]
AdvertiseRoutes prefs.List[netip.Prefix]
NoSNAT prefs.Item[bool]
NoStatefulFiltering prefs.Item[opt.Bool]
NetfilterMode prefs.Item[preftype.NetfilterMode]
OperatorUser prefs.Item[string]
ProfileName prefs.Item[string]
AutoUpdate AutoUpdatePrefs
AppConnector AppConnectorPrefs
PostureChecking prefs.Item[bool]
NetfilterKind prefs.Item[string]
DriveShares prefs.StructList[*drive.Share]
AllowSingleHosts prefs.Item[marshalAsTrueInJSON]
Persist *persist.Persist
}{})
// Clone makes a deep copy of AutoUpdatePrefs.
// The result aliases no memory with the original.
func (src *AutoUpdatePrefs) Clone() *AutoUpdatePrefs {
if src == nil {
return nil
}
dst := new(AutoUpdatePrefs)
*dst = *src
return dst
}
// A compilation failure here means this code must be regenerated, with the command at the top of this file.
var _AutoUpdatePrefsCloneNeedsRegeneration = AutoUpdatePrefs(struct {
Check prefs.Item[bool]
Apply prefs.Item[opt.Bool]
}{})
// Clone makes a deep copy of AppConnectorPrefs.
// The result aliases no memory with the original.
func (src *AppConnectorPrefs) Clone() *AppConnectorPrefs {
if src == nil {
return nil
}
dst := new(AppConnectorPrefs)
*dst = *src
return dst
}
// A compilation failure here means this code must be regenerated, with the command at the top of this file.
var _AppConnectorPrefsCloneNeedsRegeneration = AppConnectorPrefs(struct {
Advertise prefs.Item[bool]
}{})

239
types/prefs/prefs_example/prefs_example_view.go
Unescape View File

@ -0,0 +1,239 @@
// Copyright (c) Tailscale Inc & AUTHORS
// SPDX-License-Identifier: BSD-3-Clause
// Code generated by tailscale/cmd/viewer; DO NOT EDIT.
package prefs_example
import (
"encoding/json"
"errors"
"net/netip"
"tailscale.com/drive"
"tailscale.com/tailcfg"
"tailscale.com/types/opt"
"tailscale.com/types/persist"
"tailscale.com/types/prefs"
"tailscale.com/types/preftype"
)
//go:generate go run tailscale.com/cmd/cloner -clonefunc=false -type=Prefs,AutoUpdatePrefs,AppConnectorPrefs
// View returns a readonly view of Prefs.
func (p *Prefs) View() PrefsView {
return PrefsView{ж: p}
}
// PrefsView provides a read-only view over Prefs.
//
// Its methods should only be called if `Valid()` returns true.
type PrefsView struct {
// ж is the underlying mutable value, named with a hard-to-type
// character that looks pointy like a pointer.
// It is named distinctively to make you think of how dangerous it is to escape
// to callers. You must not let callers be able to mutate it.
ж *Prefs
}
// Valid reports whether underlying value is non-nil.
func (v PrefsView) Valid() bool { return v.ж != nil }
// AsStruct returns a clone of the underlying value which aliases no memory with
// the original.
func (v PrefsView) AsStruct() *Prefs {
if v.ж == nil {
return nil
}
return v.ж.Clone()
}
func (v PrefsView) MarshalJSON() ([]byte, error) { return json.Marshal(v.ж) }
func (v *PrefsView) UnmarshalJSON(b []byte) error {
if v.ж != nil {
return errors.New("already initialized")
}
if len(b) == 0 {
return nil
}
var x Prefs
if err := json.Unmarshal(b, &x); err != nil {
return err
}
v.ж = &x
return nil
}
func (v PrefsView) ControlURL() prefs.Item[string] { return v.ж.ControlURL }
func (v PrefsView) RouteAll() prefs.Item[bool] { return v.ж.RouteAll }
func (v PrefsView) ExitNodeID() prefs.Item[tailcfg.StableNodeID] { return v.ж.ExitNodeID }
func (v PrefsView) ExitNodeIP() prefs.Item[netip.Addr] { return v.ж.ExitNodeIP }
func (v PrefsView) ExitNodePrior() tailcfg.StableNodeID { return v.ж.ExitNodePrior }
func (v PrefsView) ExitNodeAllowLANAccess() prefs.Item[bool] { return v.ж.ExitNodeAllowLANAccess }
func (v PrefsView) CorpDNS() prefs.Item[bool] { return v.ж.CorpDNS }
func (v PrefsView) RunSSH() prefs.Item[bool] { return v.ж.RunSSH }
func (v PrefsView) RunWebClient() prefs.Item[bool] { return v.ж.RunWebClient }
func (v PrefsView) WantRunning() prefs.Item[bool] { return v.ж.WantRunning }
func (v PrefsView) LoggedOut() prefs.Item[bool] { return v.ж.LoggedOut }
func (v PrefsView) ShieldsUp() prefs.Item[bool] { return v.ж.ShieldsUp }
func (v PrefsView) AdvertiseTags() prefs.ListView[string] { return v.ж.AdvertiseTags.View() }
func (v PrefsView) Hostname() prefs.Item[string] { return v.ж.Hostname }
func (v PrefsView) NotepadURLs() prefs.Item[bool] { return v.ж.NotepadURLs }
func (v PrefsView) ForceDaemon() prefs.Item[bool] { return v.ж.ForceDaemon }
func (v PrefsView) Egg() prefs.Item[bool] { return v.ж.Egg }
func (v PrefsView) AdvertiseRoutes() prefs.ListView[netip.Prefix] { return v.ж.AdvertiseRoutes.View() }
func (v PrefsView) NoSNAT() prefs.Item[bool] { return v.ж.NoSNAT }
func (v PrefsView) NoStatefulFiltering() prefs.Item[opt.Bool] { return v.ж.NoStatefulFiltering }
func (v PrefsView) NetfilterMode() prefs.Item[preftype.NetfilterMode] { return v.ж.NetfilterMode }
func (v PrefsView) OperatorUser() prefs.Item[string] { return v.ж.OperatorUser }
func (v PrefsView) ProfileName() prefs.Item[string] { return v.ж.ProfileName }
func (v PrefsView) AutoUpdate() AutoUpdatePrefs { return v.ж.AutoUpdate }
func (v PrefsView) AppConnector() AppConnectorPrefs { return v.ж.AppConnector }
func (v PrefsView) PostureChecking() prefs.Item[bool] { return v.ж.PostureChecking }
func (v PrefsView) NetfilterKind() prefs.Item[string] { return v.ж.NetfilterKind }
func (v PrefsView) DriveShares() prefs.StructListView[*drive.Share, drive.ShareView] {
return prefs.StructListViewOf(&v.ж.DriveShares)
}
func (v PrefsView) AllowSingleHosts() prefs.Item[marshalAsTrueInJSON] { return v.ж.AllowSingleHosts }
func (v PrefsView) Persist() persist.PersistView { return v.ж.Persist.View() }
// A compilation failure here means this code must be regenerated, with the command at the top of this file.
var _PrefsViewNeedsRegeneration = Prefs(struct {
ControlURL prefs.Item[string]
RouteAll prefs.Item[bool]
ExitNodeID prefs.Item[tailcfg.StableNodeID]
ExitNodeIP prefs.Item[netip.Addr]
ExitNodePrior tailcfg.StableNodeID
ExitNodeAllowLANAccess prefs.Item[bool]
CorpDNS prefs.Item[bool]
RunSSH prefs.Item[bool]
RunWebClient prefs.Item[bool]
WantRunning prefs.Item[bool]
LoggedOut prefs.Item[bool]
ShieldsUp prefs.Item[bool]
AdvertiseTags prefs.List[string]
Hostname prefs.Item[string]
NotepadURLs prefs.Item[bool]
ForceDaemon prefs.Item[bool]
Egg prefs.Item[bool]
AdvertiseRoutes prefs.List[netip.Prefix]
NoSNAT prefs.Item[bool]
NoStatefulFiltering prefs.Item[opt.Bool]
NetfilterMode prefs.Item[preftype.NetfilterMode]
OperatorUser prefs.Item[string]
ProfileName prefs.Item[string]
AutoUpdate AutoUpdatePrefs
AppConnector AppConnectorPrefs
PostureChecking prefs.Item[bool]
NetfilterKind prefs.Item[string]
DriveShares prefs.StructList[*drive.Share]
AllowSingleHosts prefs.Item[marshalAsTrueInJSON]
Persist *persist.Persist
}{})
// View returns a readonly view of AutoUpdatePrefs.
func (p *AutoUpdatePrefs) View() AutoUpdatePrefsView {
return AutoUpdatePrefsView{ж: p}
}
// AutoUpdatePrefsView provides a read-only view over AutoUpdatePrefs.
//
// Its methods should only be called if `Valid()` returns true.
type AutoUpdatePrefsView struct {
// ж is the underlying mutable value, named with a hard-to-type
// character that looks pointy like a pointer.
// It is named distinctively to make you think of how dangerous it is to escape
// to callers. You must not let callers be able to mutate it.
ж *AutoUpdatePrefs
}
// Valid reports whether underlying value is non-nil.
func (v AutoUpdatePrefsView) Valid() bool { return v.ж != nil }
// AsStruct returns a clone of the underlying value which aliases no memory with
// the original.
func (v AutoUpdatePrefsView) AsStruct() *AutoUpdatePrefs {
if v.ж == nil {
return nil
}
return v.ж.Clone()
}
func (v AutoUpdatePrefsView) MarshalJSON() ([]byte, error) { return json.Marshal(v.ж) }
func (v *AutoUpdatePrefsView) UnmarshalJSON(b []byte) error {
if v.ж != nil {
return errors.New("already initialized")
}
if len(b) == 0 {
return nil
}
var x AutoUpdatePrefs
if err := json.Unmarshal(b, &x); err != nil {
return err
}
v.ж = &x
return nil
}
func (v AutoUpdatePrefsView) Check() prefs.Item[bool] { return v.ж.Check }
func (v AutoUpdatePrefsView) Apply() prefs.Item[opt.Bool] { return v.ж.Apply }
// A compilation failure here means this code must be regenerated, with the command at the top of this file.
var _AutoUpdatePrefsViewNeedsRegeneration = AutoUpdatePrefs(struct {
Check prefs.Item[bool]
Apply prefs.Item[opt.Bool]
}{})
// View returns a readonly view of AppConnectorPrefs.
func (p *AppConnectorPrefs) View() AppConnectorPrefsView {
return AppConnectorPrefsView{ж: p}
}
// AppConnectorPrefsView provides a read-only view over AppConnectorPrefs.
//
// Its methods should only be called if `Valid()` returns true.
type AppConnectorPrefsView struct {
// ж is the underlying mutable value, named with a hard-to-type
// character that looks pointy like a pointer.
// It is named distinctively to make you think of how dangerous it is to escape
// to callers. You must not let callers be able to mutate it.
ж *AppConnectorPrefs
}
// Valid reports whether underlying value is non-nil.
func (v AppConnectorPrefsView) Valid() bool { return v.ж != nil }
// AsStruct returns a clone of the underlying value which aliases no memory with
// the original.
func (v AppConnectorPrefsView) AsStruct() *AppConnectorPrefs {
if v.ж == nil {
return nil
}
return v.ж.Clone()
}
func (v AppConnectorPrefsView) MarshalJSON() ([]byte, error) { return json.Marshal(v.ж) }
func (v *AppConnectorPrefsView) UnmarshalJSON(b []byte) error {
if v.ж != nil {
return errors.New("already initialized")
}
if len(b) == 0 {
return nil
}
var x AppConnectorPrefs
if err := json.Unmarshal(b, &x); err != nil {
return err
}
v.ж = &x
return nil
}
func (v AppConnectorPrefsView) Advertise() prefs.Item[bool] { return v.ж.Advertise }
// A compilation failure here means this code must be regenerated, with the command at the top of this file.
var _AppConnectorPrefsViewNeedsRegeneration = AppConnectorPrefs(struct {
Advertise prefs.Item[bool]
}{})

140
types/prefs/prefs_example/prefs_test.go
Unescape View File

@ -0,0 +1,140 @@
// Copyright (c) Tailscale Inc & AUTHORS
// SPDX-License-Identifier: BSD-3-Clause
package prefs_example
import (
"fmt"
"net/netip"
"tailscale.com/ipn"
"tailscale.com/types/prefs"
)
func ExamplePrefs_AdvertiseRoutes_setValue() {
p := &Prefs{}
// Initially, preferences are not configured.
fmt.Println("IsSet:", p.AdvertiseRoutes.IsSet()) // prints false
// And the Value method returns the default (or zero) value.
fmt.Println("Initial:", p.AdvertiseRoutes.Value()) // prints []
// Preferences can be configured with user-provided values using the
// SetValue method. It may fail if the preference is managed via syspolicy
// or is otherwise read-only.
routes := []netip.Prefix{netip.MustParsePrefix("192.168.1.1/24")}
if err := p.AdvertiseRoutes.SetValue(routes); err != nil {
// This block is never executed in the example because the
// AdvertiseRoutes preference is neither managed nor read-only.
fmt.Println("SetValue:", err)
}
fmt.Println("IsSet:", p.AdvertiseRoutes.IsSet()) // prints true
fmt.Println("Value:", p.AdvertiseRoutes.Value()) // prints 192.168.1.1/24
// Preference values are copied on use; you cannot not modify them after they are set.
routes[0] = netip.MustParsePrefix("10.10.10.0/24") // this has no effect
fmt.Println("Unchanged:", p.AdvertiseRoutes.Value()) // still prints 192.168.1.1/24
// If necessary, the value can be changed by calling the SetValue method again.
p.AdvertiseRoutes.SetValue(routes)
fmt.Println("Changed:", p.AdvertiseRoutes.Value()) // prints 10.10.10.0/24
// The following code is fine when defining default or baseline prefs, or
// in tests. However, assigning to a preference field directly overwrites
// syspolicy-managed values and metadata, so it should generally be avoided
// when working with the actual profile or device preferences.
// It is caller's responsibility to use the mutable Prefs struct correctly.
defaults := &Prefs{WantRunning: prefs.ItemOf(true)}
defaults.CorpDNS = prefs.Item[bool]{}
defaults.ExitNodeAllowLANAccess = prefs.ItemOf(true)
_, _, _ = defaults.WantRunning, defaults.CorpDNS, defaults.ExitNodeAllowLANAccess
// In most contexts, preferences should only be read and never mutated.
// To make it easier to enforce this guarantee, a view type generated with
// [tailscale.com/cmd/viewer] can be used instead of the mutable Prefs struct.
// Preferences accessed via a view have the same set of non-mutating
// methods as the underlying preferences but do not expose [prefs.Item.SetValue] or
// other methods that modify the preference's value or state.
v := p.View()
// Additionally, non-mutating methods like [prefs.ItemView.Value] and [prefs.ItemView.ValueOk]
// return read-only views of the underlying values instead of the actual potentially mutable values.
// For example, on the next line Value() returns a views.Slice[netip.Prefix], not a []netip.Prefix.
_ = v.AdvertiseRoutes().Value()
fmt.Println("Via View:", v.AdvertiseRoutes().Value().At(0)) // prints 10.10.10.0/24
fmt.Println("IsSet:", v.AdvertiseRoutes().IsSet()) // prints true
fmt.Println("IsManaged:", v.AdvertiseRoutes().IsManaged()) // prints false
fmt.Println("IsReadOnly:", v.AdvertiseRoutes().IsReadOnly()) // prints false
// Output:
// IsSet: false
// Initial: []
// IsSet: true
// Value: [192.168.1.1/24]
// Unchanged: [192.168.1.1/24]
// Changed: [10.10.10.0/24]
// Via View: 10.10.10.0/24
// IsSet: true
// IsManaged: false
// IsReadOnly: false
}
func ExamplePrefs_ControlURL_setDefaultValue() {
p := &Prefs{}
v := p.View()
// We can set default values for preferences when their default values
// should differ from the zero values of the corresponding Go types.
//
// Note that in this example, we configure preferences via a mutable
// [Prefs] struct but fetch values via a read-only [PrefsView].
// Typically, we set and get preference values in different parts
// of the codebase.
p.ControlURL.SetDefaultValue(ipn.DefaultControlURL)
// The default value is used if the preference is not configured...
fmt.Println("Default:", v.ControlURL().Value())
p.ControlURL.SetValue("https://control.example.com")
fmt.Println("User Set:", v.ControlURL().Value())
// ...including when it has been reset.
p.ControlURL.ClearValue()
fmt.Println("Reset to Default:", v.ControlURL().Value())
// Output:
// Default: https://controlplane.tailscale.com
// User Set: https://control.example.com
// Reset to Default: https://controlplane.tailscale.com
}
func ExamplePrefs_ExitNodeID_setManagedValue() {
p := &Prefs{}
v := p.View()
// We can mark preferences as being managed via syspolicy (e.g., via GP/MDM)
// by setting its managed value.
//
// Note that in this example, we enforce syspolicy-managed values
// via a mutable [Prefs] struct but fetch values via a read-only [PrefsView].
// This is typically spread throughout the codebase.
p.ExitNodeID.SetManagedValue("ManagedExitNode")
// Marking a preference as managed prevents it from being changed by the user.
if err := p.ExitNodeID.SetValue("CustomExitNode"); err != nil {
fmt.Println("SetValue:", err) // reports an error
}
fmt.Println("Exit Node:", v.ExitNodeID().Value()) // prints ManagedExitNode
// Clients can hide or disable preferences that are managed or read-only.
fmt.Println("IsManaged:", v.ExitNodeID().IsManaged()) // prints true
fmt.Println("IsReadOnly:", v.ExitNodeID().IsReadOnly()) // prints true; managed preferences are always read-only.
// ClearManaged is called when the preference is no longer managed,
// allowing the user to change it.
p.ExitNodeID.ClearManaged()
fmt.Println("IsManaged:", v.ExitNodeID().IsManaged()) // prints false
fmt.Println("IsReadOnly:", v.ExitNodeID().IsReadOnly()) // prints false
// Output:
// SetValue: cannot modify a managed preference
// Exit Node: ManagedExitNode
// IsManaged: true
// IsReadOnly: true
// IsManaged: false
// IsReadOnly: false
}

166
types/prefs/prefs_example/prefs_types.go
Unescape View File

@ -0,0 +1,166 @@
// Copyright (c) Tailscale Inc & AUTHORS
// SPDX-License-Identifier: BSD-3-Clause
// Package prefs_example contains a [Prefs] type, which is like [tailscale.com/ipn.Prefs],
// but uses the [prefs] package to enhance individual preferences with state and metadata.
//
// It also includes testable examples utilizing the [Prefs] type.
// We made it a separate package to avoid circular dependencies
// and due to limitations in [tailscale.com/cmd/viewer] when
// generating code for test packages.
package prefs_example
import (
"net/netip"
jsonv2 "github.com/go-json-experiment/json"
"github.com/go-json-experiment/json/jsontext"
"tailscale.com/drive"
"tailscale.com/tailcfg"
"tailscale.com/types/opt"
"tailscale.com/types/persist"
"tailscale.com/types/prefs"
"tailscale.com/types/preftype"
)
//go:generate go run tailscale.com/cmd/viewer --type=Prefs,AutoUpdatePrefs,AppConnectorPrefs
// Prefs is like [tailscale.com/ipn.Prefs], but with individual preferences wrapped in
// [prefs.Item], [prefs.List], and [prefs.StructList] to include preference
// state and metadata. Related preferences can be grouped together in a nested
// struct (e.g., [AutoUpdatePrefs] or [AppConnectorPrefs]), whereas each
// individual preference that can be configured by a user or managed via
// syspolicy is wrapped.
//
// Non-preference fields, such as ExitNodePrior and Persist, can be included as-is.
//
// Just like [tailscale.com/ipn.Prefs], [Prefs] is a mutable struct. It should
// only be used in well-defined contexts where mutability is expected and desired,
// such as when the LocalBackend receives a request from the GUI/CLI to change a
// preference, when a preference is managed via syspolicy and needs to be
// configured with an admin-provided value, or when the internal state (e.g.,
// [persist.Persist]) has changed and needs to be preserved.
// In other contexts, a [PrefsView] should be used to provide a read-only view
// of the preferences.
//
// It is recommended to use [jsonv2] for [Prefs] marshaling and unmarshalling to
// improve performance and enable the omission of unconfigured preferences with
// the `omitzero` JSON tag option. This option is not supported by the
// [encoding/json] package as of 2024-08-21; see golang/go#45669.
// It is recommended that a prefs type implements both
// [jsonv2.MarshalerV2]/[jsonv2.UnmarshalerV2] and [json.Marshaler]/[json.Unmarshaler]
// to ensure consistent and more performant marshaling, regardless of the JSON package
// used at the call sites; the standard marshalers can be implemented via [jsonv2].
// See [Prefs.MarshalJSONV2], [Prefs.UnmarshalJSONV2], [Prefs.MarshalJSON],
// and [Prefs.UnmarshalJSON] for an example implementation.
type Prefs struct {
ControlURL prefs.Item[string] `json:",omitzero"`
RouteAll prefs.Item[bool] `json:",omitzero"`
ExitNodeID prefs.Item[tailcfg.StableNodeID] `json:",omitzero"`
ExitNodeIP prefs.Item[netip.Addr] `json:",omitzero"`
// ExitNodePrior is an internal state rather than a preference.
// It can be kept in the Prefs structure but should not be wrapped
// and is ignored by the [prefs] package.
ExitNodePrior tailcfg.StableNodeID
ExitNodeAllowLANAccess prefs.Item[bool] `json:",omitzero"`
CorpDNS prefs.Item[bool] `json:",omitzero"`
RunSSH prefs.Item[bool] `json:",omitzero"`
RunWebClient prefs.Item[bool] `json:",omitzero"`
WantRunning prefs.Item[bool] `json:",omitzero"`
LoggedOut prefs.Item[bool] `json:",omitzero"`
ShieldsUp prefs.Item[bool] `json:",omitzero"`
// AdvertiseTags is a preference whose value is a slice of strings.
// The value is atomic, and individual items in the slice should
// not be modified after the preference is set.
// Since the item type (string) is immutable, we can use [prefs.List].
AdvertiseTags prefs.List[string] `json:",omitzero"`
Hostname prefs.Item[string] `json:",omitzero"`
NotepadURLs prefs.Item[bool] `json:",omitzero"`
ForceDaemon prefs.Item[bool] `json:",omitzero"`
Egg prefs.Item[bool] `json:",omitzero"`
// AdvertiseRoutes is a preference whose value is a slice of netip.Prefix.
// The value is atomic, and individual items in the slice should
// not be modified after the preference is set.
// Since the item type (netip.Prefix) is immutable, we can use [prefs.List].
AdvertiseRoutes prefs.List[netip.Prefix] `json:",omitzero"`
NoSNAT prefs.Item[bool] `json:",omitzero"`
NoStatefulFiltering prefs.Item[opt.Bool] `json:",omitzero"`
NetfilterMode prefs.Item[preftype.NetfilterMode] `json:",omitzero"`
OperatorUser prefs.Item[string] `json:",omitzero"`
ProfileName prefs.Item[string] `json:",omitzero"`
// AutoUpdate contains auto-update preferences.
// Each preference in the group can be configured and managed individually.
AutoUpdate AutoUpdatePrefs `json:",omitzero"`
// AppConnector contains app connector-related preferences.
// Each preference in the group can be configured and managed individually.
AppConnector AppConnectorPrefs `json:",omitzero"`
PostureChecking prefs.Item[bool] `json:",omitzero"`
NetfilterKind prefs.Item[string] `json:",omitzero"`
// DriveShares is a preference whose value is a slice of *[drive.Share].
// The value is atomic, and individual items in the slice should
// not be modified after the preference is set.
// Since the item type (*drive.Share) is mutable and implements [views.ViewCloner],
// we need to use [prefs.StructList] instead of [prefs.List].
DriveShares prefs.StructList[*drive.Share] `json:",omitzero"`
AllowSingleHosts prefs.Item[marshalAsTrueInJSON] `json:",omitzero"`
// Persist is an internal state rather than a preference.
// It can be kept in the Prefs structure but should not be wrapped
// and is ignored by the [prefs] package.
Persist *persist.Persist `json:"Config"`
}
// AutoUpdatePrefs is like [ipn.AutoUpdatePrefs], but it wraps individual preferences with [prefs.Item].
// It groups related preferences together while allowing each to be configured individually.
type AutoUpdatePrefs struct {
Check prefs.Item[bool] `json:",omitzero"`
Apply prefs.Item[opt.Bool] `json:",omitzero"`
}
// AppConnectorPrefs is like [ipn.AppConnectorPrefs], but it wraps individual preferences with [prefs.Item].
// It groups related preferences together while allowing each to be configured individually.
type AppConnectorPrefs struct {
Advertise prefs.Item[bool] `json:",omitzero"`
}
// MarshalJSONV2 implements [jsonv2.MarshalerV2].
// It is implemented as a performance improvement and to enable omission of
// unconfigured preferences from the JSON output. See the [Prefs] doc for details.
func (p Prefs) MarshalJSONV2(out *jsontext.Encoder, opts jsonv2.Options) error {
// The prefs type shadows the Prefs's method set,
// causing [jsonv2] to use the default marshaler and avoiding
// infinite recursion.
type prefs Prefs
return jsonv2.MarshalEncode(out, (*prefs)(&p), opts)
}
// UnmarshalJSONV2 implements [jsonv2.UnmarshalerV2].
func (p *Prefs) UnmarshalJSONV2(in *jsontext.Decoder, opts jsonv2.Options) error {
// The prefs type shadows the Prefs's method set,
// causing [jsonv2] to use the default unmarshaler and avoiding
// infinite recursion.
type prefs Prefs
return jsonv2.UnmarshalDecode(in, (*prefs)(p), opts)
}
// MarshalJSON implements [json.Marshaler].
func (p Prefs) MarshalJSON() ([]byte, error) {
return jsonv2.Marshal(p) // uses MarshalJSONV2
}
// UnmarshalJSON implements [json.Unmarshaler].
func (p *Prefs) UnmarshalJSON(b []byte) error {
return jsonv2.Unmarshal(b, p) // uses UnmarshalJSONV2
}
type marshalAsTrueInJSON struct{}
var trueJSON = []byte("true")
func (marshalAsTrueInJSON) MarshalJSON() ([]byte, error) { return trueJSON, nil }
func (*marshalAsTrueInJSON) UnmarshalJSON([]byte) error { return nil }

670
types/prefs/prefs_test.go
Unescape View File

@ -0,0 +1,670 @@
// Copyright (c) Tailscale Inc & AUTHORS
// SPDX-License-Identifier: BSD-3-Clause
package prefs
import (
"bytes"
"encoding/json"
"errors"
"net/netip"
"reflect"
"testing"
jsonv2 "github.com/go-json-experiment/json"
"github.com/go-json-experiment/json/jsontext"
"github.com/google/go-cmp/cmp"
"tailscale.com/types/views"
)
//go:generate go run tailscale.com/cmd/viewer --tags=test --type=TestPrefs,TestBundle,TestValueStruct,TestGenericStruct,TestPrefsGroup
type TestPrefs struct {
Int32Item Item[int32] `json:",omitzero"`
UInt64Item Item[uint64] `json:",omitzero"`
StringItem1 Item[string] `json:",omitzero"`
StringItem2 Item[string] `json:",omitzero"`
BoolItem1 Item[bool] `json:",omitzero"`
BoolItem2 Item[bool] `json:",omitzero"`
StringSlice List[string] `json:",omitzero"`
IntSlice List[int] `json:",omitzero"`
AddrItem Item[netip.Addr] `json:",omitzero"`
StringStringMap Map[string, string] `json:",omitzero"`
IntStringMap Map[int, string] `json:",omitzero"`
AddrIntMap Map[netip.Addr, int] `json:",omitzero"`
// Bundles are complex preferences that usually consist of
// multiple parameters that must be configured atomically.
Bundle1 Item[*TestBundle] `json:",omitzero"`
Bundle2 Item[*TestBundle] `json:",omitzero"`
Generic Item[*TestGenericStruct[int]] `json:",omitzero"`
BundleList StructList[*TestBundle] `json:",omitzero"`
StringBundleMap StructMap[string, *TestBundle] `json:",omitzero"`
IntBundleMap StructMap[int, *TestBundle] `json:",omitzero"`
AddrBundleMap StructMap[netip.Addr, *TestBundle] `json:",omitzero"`
// Group is a nested struct that contains one or more preferences.
// Each preference in a group can be configured individually.
// Preference groups should be included directly rather than by pointers.
Group TestPrefsGroup `json:",omitzero"`
}
// MarshalJSONV2 implements [jsonv2.MarshalerV2].
func (p TestPrefs) MarshalJSONV2(out *jsontext.Encoder, opts jsonv2.Options) error {
// The testPrefs type shadows the TestPrefs's method set,
// causing jsonv2 to use the default marshaler and avoiding
// infinite recursion.
type testPrefs TestPrefs
return jsonv2.MarshalEncode(out, (*testPrefs)(&p), opts)
}
// UnmarshalJSONV2 implements [jsonv2.UnmarshalerV2].
func (p *TestPrefs) UnmarshalJSONV2(in *jsontext.Decoder, opts jsonv2.Options) error {
// The testPrefs type shadows the TestPrefs's method set,
// causing jsonv2 to use the default unmarshaler and avoiding
// infinite recursion.
type testPrefs TestPrefs
return jsonv2.UnmarshalDecode(in, (*testPrefs)(p), opts)
}
// MarshalJSON implements [json.Marshaler].
func (p TestPrefs) MarshalJSON() ([]byte, error) {
return jsonv2.Marshal(p) // uses MarshalJSONV2
}
// UnmarshalJSON implements [json.Unmarshaler].
func (p *TestPrefs) UnmarshalJSON(b []byte) error {
return jsonv2.Unmarshal(b, p) // uses UnmarshalJSONV2
}
// TestBundle is an example structure type that,
// despite containing multiple values, represents
// a single configurable preference item.
type TestBundle struct {
Name string `json:",omitzero"`
Nested *TestValueStruct `json:",omitzero"`
}
func (b *TestBundle) Equal(b2 *TestBundle) bool {
if b == b2 {
return true
}
if b == nil || b2 == nil {
return false
}
return b.Name == b2.Name && b.Nested.Equal(b2.Nested)
}
// TestPrefsGroup contains logically grouped preference items.
// Each preference item in a group can be configured individually.
type TestPrefsGroup struct {
FloatItem Item[float64] `json:",omitzero"`
TestStringItem Item[TestStringType] `json:",omitzero"`
}
type TestValueStruct struct {
Value int
}
func (s *TestValueStruct) Equal(s2 *TestValueStruct) bool {
if s == s2 {
return true
}
if s == nil || s2 == nil {
return false
}
return *s == *s2
}
type TestGenericStruct[T ImmutableType] struct {
Value T
}
func (s *TestGenericStruct[T]) Equal(s2 *TestGenericStruct[T]) bool {
if s == s2 {
return true
}
if s == nil || s2 == nil {
return false
}
return *s == *s2
}
type TestStringType string
func TestMarshalUnmarshal(t *testing.T) {
tests := []struct {
name string
prefs *TestPrefs
indent bool
want string
}{
{
name: "string",
prefs: &TestPrefs{StringItem1: ItemOf("Value1")},
want: `{"StringItem1": {"Value": "Value1"}}`,
},
{
name: "empty-string",
prefs: &TestPrefs{StringItem1: ItemOf("")},
want: `{"StringItem1": {"Value": ""}}`,
},
{
name: "managed-string",
prefs: &TestPrefs{StringItem1: ItemOf("Value1", Managed)},
want: `{"StringItem1": {"Value": "Value1", "Managed": true}}`,
},
{
name: "readonly-item",
prefs: &TestPrefs{StringItem1: ItemWithOpts[string](ReadOnly)},
want: `{"StringItem1": {"ReadOnly": true}}`,
},
{
name: "readonly-item-with-value",
prefs: &TestPrefs{StringItem1: ItemOf("RO", ReadOnly)},
want: `{"StringItem1": {"Value": "RO", "ReadOnly": true}}`,
},
{
name: "int32",
prefs: &TestPrefs{Int32Item: ItemOf[int32](101)},
want: `{"Int32Item": {"Value": 101}}`,
},
{
name: "uint64",
prefs: &TestPrefs{UInt64Item: ItemOf[uint64](42)},
want: `{"UInt64Item": {"Value": 42}}`,
},
{
name: "bool-true",
prefs: &TestPrefs{BoolItem1: ItemOf(true)},
want: `{"BoolItem1": {"Value": true}}`,
},
{
name: "bool-false",
prefs: &TestPrefs{BoolItem1: ItemOf(false)},
want: `{"BoolItem1": {"Value": false}}`,
},
{
name: "empty-slice",
prefs: &TestPrefs{StringSlice: ListOf([]string{})},
want: `{"StringSlice": {"Value": []}}`,
},
{
name: "string-slice",
prefs: &TestPrefs{StringSlice: ListOf([]string{"1", "2", "3"})},
want: `{"StringSlice": {"Value": ["1", "2", "3"]}}`,
},
{
name: "int-slice",
prefs: &TestPrefs{IntSlice: ListOf([]int{4, 8, 15, 16, 23})},
want: `{"IntSlice": {"Value": [4, 8, 15, 16, 23]}}`,
},
{
name: "managed-int-slice",
prefs: &TestPrefs{IntSlice: ListOf([]int{4, 8, 15, 16, 23}, Managed)},
want: `{"IntSlice": {"Value": [4, 8, 15, 16, 23], "Managed": true}}`,
},
{
name: "netip-addr",
prefs: &TestPrefs{AddrItem: ItemOf(netip.MustParseAddr("127.0.0.1"))},
want: `{"AddrItem": {"Value": "127.0.0.1"}}`,
},
{
name: "string-string-map",
prefs: &TestPrefs{StringStringMap: MapOf(map[string]string{"K1": "V1"})},
want: `{"StringStringMap": {"Value": {"K1": "V1"}}}`,
},
{
name: "int-string-map",
prefs: &TestPrefs{IntStringMap: MapOf(map[int]string{42: "V1"})},
want: `{"IntStringMap": {"Value": {"42": "V1"}}}`,
},
{
name: "addr-int-map",
prefs: &TestPrefs{AddrIntMap: MapOf(map[netip.Addr]int{netip.MustParseAddr("127.0.0.1"): 42})},
want: `{"AddrIntMap": {"Value": {"127.0.0.1": 42}}}`,
},
{
name: "bundle-list",
prefs: &TestPrefs{BundleList: StructListOf([]*TestBundle{{Name: "Bundle1"}, {Name: "Bundle2"}})},
want: `{"BundleList": {"Value": [{"Name": "Bundle1"},{"Name": "Bundle2"}]}}`,
},
{
name: "string-bundle-map",
prefs: &TestPrefs{StringBundleMap: StructMapOf(map[string]*TestBundle{
"K1": {Name: "Bundle1"},
"K2": {Name: "Bundle2"},
})},
want: `{"StringBundleMap": {"Value": {"K1": {"Name": "Bundle1"}, "K2": {"Name": "Bundle2"}}}}`,
},
{
name: "int-bundle-map",
prefs: &TestPrefs{IntBundleMap: StructMapOf(map[int]*TestBundle{42: {Name: "Bundle1"}})},
want: `{"IntBundleMap": {"Value": {"42": {"Name": "Bundle1"}}}}`,
},
{
name: "addr-bundle-map",
prefs: &TestPrefs{AddrBundleMap: StructMapOf(map[netip.Addr]*TestBundle{netip.MustParseAddr("127.0.0.1"): {Name: "Bundle1"}})},
want: `{"AddrBundleMap": {"Value": {"127.0.0.1": {"Name": "Bundle1"}}}}`,
},
{
name: "bundle",
prefs: &TestPrefs{Bundle1: ItemOf(&TestBundle{Name: "Bundle1"})},
want: `{"Bundle1": {"Value": {"Name": "Bundle1"}}}`,
},
{
name: "managed-bundle",
prefs: &TestPrefs{Bundle2: ItemOf(&TestBundle{Name: "Bundle2", Nested: &TestValueStruct{Value: 17}}, Managed)},
want: `{"Bundle2": {"Value": {"Name": "Bundle2", "Nested": {"Value": 17}}, "Managed": true}}`,
},
{
name: "subgroup",
prefs: &TestPrefs{Group: TestPrefsGroup{FloatItem: ItemOf(1.618), TestStringItem: ItemOf(TestStringType("Value"))}},
want: `{"Group": {"FloatItem": {"Value": 1.618}, "TestStringItem": {"Value": "Value"}}}`,
},
{
name: "various",
prefs: &TestPrefs{
Int32Item: ItemOf[int32](101),
UInt64Item: ItemOf[uint64](42),
StringItem1: ItemOf("Value1"),
StringItem2: ItemWithOpts[string](ReadOnly),
BoolItem1: ItemOf(true),
BoolItem2: ItemOf(false, Managed),
StringSlice: ListOf([]string{"1", "2", "3"}),
IntSlice: ListOf([]int{4, 8, 15, 16, 23}, Managed),
AddrItem: ItemOf(netip.MustParseAddr("127.0.0.1")),
StringStringMap: MapOf(map[string]string{"K1": "V1"}),
IntStringMap: MapOf(map[int]string{42: "V1"}),
AddrIntMap: MapOf(map[netip.Addr]int{netip.MustParseAddr("127.0.0.1"): 42}),
BundleList: StructListOf([]*TestBundle{{Name: "Bundle1"}}),
StringBundleMap: StructMapOf(map[string]*TestBundle{"K1": {Name: "Bundle1"}}),
IntBundleMap: StructMapOf(map[int]*TestBundle{42: {Name: "Bundle1"}}),
AddrBundleMap: StructMapOf(map[netip.Addr]*TestBundle{netip.MustParseAddr("127.0.0.1"): {Name: "Bundle1"}}),
Bundle1: ItemOf(&TestBundle{Name: "Bundle1"}),
Bundle2: ItemOf(&TestBundle{Name: "Bundle2", Nested: &TestValueStruct{Value: 17}}, Managed),
Group: TestPrefsGroup{
FloatItem: ItemOf(1.618),
TestStringItem: ItemOf(TestStringType("Value")),
},
},
want: `{
"Int32Item": {"Value": 101},
"UInt64Item": {"Value": 42},
"StringItem1": {"Value": "Value1"},
"StringItem2": {"ReadOnly": true},
"BoolItem1": {"Value": true},
"BoolItem2": {"Value": false, "Managed": true},
"StringSlice": {"Value": ["1", "2", "3"]},
"IntSlice": {"Value": [4, 8, 15, 16, 23], "Managed": true},
"AddrItem": {"Value": "127.0.0.1"},
"StringStringMap": {"Value": {"K1": "V1"}},
"IntStringMap": {"Value": {"42": "V1"}},
"AddrIntMap": {"Value": {"127.0.0.1": 42}},
"BundleList": {"Value": [{"Name": "Bundle1"}]},
"StringBundleMap": {"Value": {"K1": {"Name": "Bundle1"}}},
"IntBundleMap": {"Value": {"42": {"Name": "Bundle1"}}},
"AddrBundleMap": {"Value": {"127.0.0.1": {"Name": "Bundle1"}}},
"Bundle1": {"Value": {"Name": "Bundle1"}},
"Bundle2": {"Value": {"Name": "Bundle2", "Nested": {"Value": 17}}, "Managed": true},
"Group": {
"FloatItem": {"Value": 1.618},
"TestStringItem": {"Value": "Value"}
}
}`,
},
}
arshalers := []struct {
name string
marshal func(in any) (out []byte, err error)
unmarshal func(in []byte, out any) (err error)
}{
{
name: "json",
marshal: json.Marshal,
unmarshal: json.Unmarshal,
},
{
name: "jsonv2",
marshal: func(in any) (out []byte, err error) { return jsonv2.Marshal(in) },
unmarshal: func(in []byte, out any) (err error) { return jsonv2.Unmarshal(in, out) },
},
}
for _, a := range arshalers {
t.Run(a.name, func(t *testing.T) {
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
t.Run("marshal-directly", func(t *testing.T) {
gotJSON, err := a.marshal(tt.prefs)
if err != nil {
t.Fatalf("marshalling failed: %v", err)
}
checkJSON(t, gotJSON, jsontext.Value(tt.want))
var gotPrefs TestPrefs
if err = a.unmarshal(gotJSON, &gotPrefs); err != nil {
t.Fatalf("unmarshalling failed: %v", err)
}
if diff := cmp.Diff(tt.prefs, &gotPrefs); diff != "" {
t.Errorf("mismatch (-want +got):\n%s", diff)
}
})
t.Run("marshal-via-view", func(t *testing.T) {
gotJSON, err := a.marshal(tt.prefs.View())
if err != nil {
t.Fatalf("marshalling failed: %v", err)
}
checkJSON(t, gotJSON, jsontext.Value(tt.want))
var gotPrefs TestPrefsView
if err = a.unmarshal(gotJSON, &gotPrefs); err != nil {
t.Fatalf("unmarshalling failed: %v", err)
}
if diff := cmp.Diff(tt.prefs, gotPrefs.AsStruct()); diff != "" {
t.Errorf("mismatch (-want +got):\n%s", diff)
}
})
})
}
})
}
}
func TestPreferenceStates(t *testing.T) {
const (
zeroValue = 0
defValue = 5
userValue = 42
mdmValue = 1001
)
i := ItemWithOpts[int]()
checkIsSet(t, &i, false)
checkIsManaged(t, &i, false)
checkIsReadOnly(t, &i, false)
checkValueOk(t, &i, zeroValue, false)
i.SetDefaultValue(defValue)
checkValue(t, &i, defValue)
checkValueOk(t, &i, defValue, false)
checkSetValue(t, &i, userValue)
checkValue(t, &i, userValue)
checkValueOk(t, &i, userValue, true)
i2 := ItemOf(userValue)
checkIsSet(t, &i2, true)
checkValue(t, &i2, userValue)
checkValueOk(t, &i2, userValue, true)
checkEqual(t, i2, i, true)
i2.SetManagedValue(mdmValue)
// Setting a managed value should set the value, mark the preference
// as managed and read-only, and prevent it from being modified with SetValue.
checkIsSet(t, &i2, true)
checkIsManaged(t, &i2, true)
checkIsReadOnly(t, &i2, true)
checkValue(t, &i2, mdmValue)
checkValueOk(t, &i2, mdmValue, true)
checkCanNotSetValue(t, &i2, userValue, ErrManaged)
checkValue(t, &i2, mdmValue) // the value must not be changed
checkCanNotClearValue(t, &i2, ErrManaged)
i2.ClearManaged()
// Clearing the managed flag should change the IsManaged and IsReadOnly flags...
checkIsManaged(t, &i2, false)
checkIsReadOnly(t, &i2, false)
// ...but not the value.
checkValue(t, &i2, mdmValue)
// We should be able to change the value after clearing the managed flag.
checkSetValue(t, &i2, userValue)
checkIsSet(t, &i2, true)
checkValue(t, &i2, userValue)
checkValueOk(t, &i2, userValue, true)
checkEqual(t, i2, i, true)
i2.SetReadOnly(true)
checkIsReadOnly(t, &i2, true)
checkIsManaged(t, &i2, false)
checkCanNotSetValue(t, &i2, userValue, ErrReadOnly)
checkCanNotClearValue(t, &i2, ErrReadOnly)
i2.SetReadOnly(false)
i2.SetDefaultValue(defValue)
checkClearValue(t, &i2)
checkIsSet(t, &i2, false)
checkValue(t, &i2, defValue)
checkValueOk(t, &i2, defValue, false)
}
func TestItemView(t *testing.T) {
i := ItemOf(&TestBundle{Name: "B1"})
iv := ItemViewOf(&i)
checkIsSet(t, iv, true)
checkIsManaged(t, iv, false)
checkIsReadOnly(t, iv, false)
checkValue(t, iv, TestBundleView{i.Value()})
checkValueOk(t, iv, TestBundleView{i.Value()}, true)
i2 := *iv.AsStruct()
checkEqual(t, i, i2, true)
i2.SetValue(&TestBundle{Name: "B2"})
iv2 := ItemViewOf(&i2)
checkEqual(t, iv, iv2, false)
}
func TestListView(t *testing.T) {
l := ListOf([]int{4, 8, 15, 16, 23, 42}, ReadOnly)
lv := l.View()
checkIsSet(t, lv, true)
checkIsManaged(t, lv, false)
checkIsReadOnly(t, lv, true)
checkValue(t, lv, views.SliceOf(l.Value()))
checkValueOk(t, lv, views.SliceOf(l.Value()), true)
l2 := *lv.AsStruct()
checkEqual(t, l, l2, true)
}
func TestStructListView(t *testing.T) {
l := StructListOf([]*TestBundle{{Name: "E1"}, {Name: "E2"}}, ReadOnly)
lv := StructListViewOf(&l)
checkIsSet(t, lv, true)
checkIsManaged(t, lv, false)
checkIsReadOnly(t, lv, true)
checkValue(t, lv, views.SliceOfViews(l.Value()))
checkValueOk(t, lv, views.SliceOfViews(l.Value()), true)
l2 := *lv.AsStruct()
checkEqual(t, l, l2, true)
}
func TestStructMapView(t *testing.T) {
m := StructMapOf(map[string]*TestBundle{
"K1": {Name: "E1"},
"K2": {Name: "E2"},
}, ReadOnly)
mv := StructMapViewOf(&m)
checkIsSet(t, mv, true)
checkIsManaged(t, mv, false)
checkIsReadOnly(t, mv, true)
checkValue(t, *mv.AsStruct(), m.Value())
checkValueOk(t, *mv.AsStruct(), m.Value(), true)
m2 := *mv.AsStruct()
checkEqual(t, m, m2, true)
}
// check that the preference types implement the test [pref] interface.
var (
_ pref[int] = (*Item[int])(nil)
_ pref[*TestBundle] = (*Item[*TestBundle])(nil)
_ pref[[]int] = (*List[int])(nil)
_ pref[[]*TestBundle] = (*StructList[*TestBundle])(nil)
_ pref[map[string]*TestBundle] = (*StructMap[string, *TestBundle])(nil)
)
// pref is an interface used by [checkSetValue], [checkClearValue], and similar test
// functions that mutate preferences. It is implemented by all preference types, such
// as [Item], [List], [StructList], and [StructMap], and provides both read and write
// access to the preference's value and state.
type pref[T any] interface {
prefView[T]
SetValue(v T) error
ClearValue() error
SetDefaultValue(v T)
SetManagedValue(v T)
ClearManaged()
SetReadOnly(readonly bool)
}
// check that the preference view types implement the test [prefView] interface.
var (
_ prefView[int] = (*Item[int])(nil)
_ prefView[TestBundleView] = (*ItemView[*TestBundle, TestBundleView])(nil)
_ prefView[views.Slice[int]] = (*ListView[int])(nil)
_ prefView[views.SliceView[*TestBundle, TestBundleView]] = (*StructListView[*TestBundle, TestBundleView])(nil)
_ prefView[views.MapFn[string, *TestBundle, TestBundleView]] = (*StructMapView[string, *TestBundle, TestBundleView])(nil)
)
// prefView is an interface used by [checkIsSet], [checkIsManaged], and similar non-mutating
// test functions. It is implemented by all preference types, such as [Item], [List], [StructList],
// and [StructMap], as well as their corresponding views, such as [ItemView], [ListView], [StructListView],
// and [StructMapView], and provides read-only access to the preference's value and state.
type prefView[T any] interface {
IsSet() bool
Value() T
ValueOk() (T, bool)
DefaultValue() T
IsManaged() bool
IsReadOnly() bool
}
func checkIsSet[T any](tb testing.TB, p prefView[T], wantSet bool) {
tb.Helper()
if gotSet := p.IsSet(); gotSet != wantSet {
tb.Errorf("IsSet: got %v; want %v", gotSet, wantSet)
}
}
func checkIsManaged[T any](tb testing.TB, p prefView[T], wantManaged bool) {
tb.Helper()
if gotManaged := p.IsManaged(); gotManaged != wantManaged {
tb.Errorf("IsManaged: got %v; want %v", gotManaged, wantManaged)
}
}
func checkIsReadOnly[T any](tb testing.TB, p prefView[T], wantReadOnly bool) {
tb.Helper()
if gotReadOnly := p.IsReadOnly(); gotReadOnly != wantReadOnly {
tb.Errorf("IsReadOnly: got %v; want %v", gotReadOnly, wantReadOnly)
}
}
func checkValue[T any](tb testing.TB, p prefView[T], wantValue T) {
tb.Helper()
if gotValue := p.Value(); !testComparerFor[T]()(gotValue, wantValue) {
tb.Errorf("Value: got %v; want %v", gotValue, wantValue)
}
}
func checkValueOk[T any](tb testing.TB, p prefView[T], wantValue T, wantOk bool) {
tb.Helper()
gotValue, gotOk := p.ValueOk()
if gotOk != wantOk || !testComparerFor[T]()(gotValue, wantValue) {
tb.Errorf("ValueOk: got (%v, %v); want (%v, %v)", gotValue, gotOk, wantValue, wantOk)
}
}
func checkEqual[T equatable[T]](tb testing.TB, a, b T, wantEqual bool) {
tb.Helper()
if gotEqual := a.Equal(b); gotEqual != wantEqual {
tb.Errorf("Equal: got %v; want %v", gotEqual, wantEqual)
}
}
func checkSetValue[T any](tb testing.TB, p pref[T], v T) {
tb.Helper()
if err := p.SetValue(v); err != nil {
tb.Fatalf("SetValue: gotErr %v, wantErr: nil", err)
}
}
func checkCanNotSetValue[T any](tb testing.TB, p pref[T], v T, wantErr error) {
tb.Helper()
if err := p.SetValue(v); err == nil || !errors.Is(err, wantErr) {
tb.Fatalf("SetValue: gotErr %v, wantErr: %v", err, wantErr)
}
}
func checkClearValue[T any](tb testing.TB, p pref[T]) {
tb.Helper()
if err := p.ClearValue(); err != nil {
tb.Fatalf("ClearValue: gotErr %v, wantErr: nil", err)
}
}
func checkCanNotClearValue[T any](tb testing.TB, p pref[T], wantErr error) {
tb.Helper()
err := p.ClearValue()
if err == nil || !errors.Is(err, wantErr) {
tb.Fatalf("ClearValue: gotErr %v, wantErr: %v", err, wantErr)
}
}
// testComparerFor is like [comparerFor], but uses [reflect.DeepEqual]
// unless T is [equatable].
func testComparerFor[T any]() func(a, b T) bool {
return func(a, b T) bool {
switch a := any(a).(type) {
case equatable[T]:
return a.Equal(b)
default:
return reflect.DeepEqual(a, b)
}
}
}
func checkJSON(tb testing.TB, got, want jsontext.Value) {
tb.Helper()
got = got.Clone()
want = want.Clone()
// Compare canonical forms.
if err := got.Canonicalize(); err != nil {
tb.Error(err)
}
if err := want.Canonicalize(); err != nil {
tb.Error(err)
}
if bytes.Equal(got, want) {
return
}
gotMap := make(map[string]any)
if err := jsonv2.Unmarshal(got, &gotMap); err != nil {
tb.Fatal(err)
}
wantMap := make(map[string]any)
if err := jsonv2.Unmarshal(want, &wantMap); err != nil {
tb.Fatal(err)
}
tb.Errorf("mismatch (-want +got):\n%s", cmp.Diff(wantMap, gotMap))
}

342
types/prefs/prefs_view_test.go
Unescape View File

@ -0,0 +1,342 @@
// Copyright (c) Tailscale Inc & AUTHORS
// SPDX-License-Identifier: BSD-3-Clause
// Code generated by tailscale/cmd/viewer; DO NOT EDIT.
package prefs
import (
"encoding/json"
"errors"
"net/netip"
)
//go:generate go run tailscale.com/cmd/cloner -clonefunc=false -type=TestPrefs,TestBundle,TestValueStruct,TestGenericStruct,TestPrefsGroup -tags=test
// View returns a readonly view of TestPrefs.
func (p *TestPrefs) View() TestPrefsView {
return TestPrefsView{ж: p}
}
// TestPrefsView provides a read-only view over TestPrefs.
//
// Its methods should only be called if `Valid()` returns true.
type TestPrefsView struct {
// ж is the underlying mutable value, named with a hard-to-type
// character that looks pointy like a pointer.
// It is named distinctively to make you think of how dangerous it is to escape
// to callers. You must not let callers be able to mutate it.
ж *TestPrefs
}
// Valid reports whether underlying value is non-nil.
func (v TestPrefsView) Valid() bool { return v.ж != nil }
// AsStruct returns a clone of the underlying value which aliases no memory with
// the original.
func (v TestPrefsView) AsStruct() *TestPrefs {
if v.ж == nil {
return nil
}
return v.ж.Clone()
}
func (v TestPrefsView) MarshalJSON() ([]byte, error) { return json.Marshal(v.ж) }
func (v *TestPrefsView) UnmarshalJSON(b []byte) error {
if v.ж != nil {
return errors.New("already initialized")
}
if len(b) == 0 {
return nil
}
var x TestPrefs
if err := json.Unmarshal(b, &x); err != nil {
return err
}
v.ж = &x
return nil
}
func (v TestPrefsView) Int32Item() Item[int32] { return v.ж.Int32Item }
func (v TestPrefsView) UInt64Item() Item[uint64] { return v.ж.UInt64Item }
func (v TestPrefsView) StringItem1() Item[string] { return v.ж.StringItem1 }
func (v TestPrefsView) StringItem2() Item[string] { return v.ж.StringItem2 }
func (v TestPrefsView) BoolItem1() Item[bool] { return v.ж.BoolItem1 }
func (v TestPrefsView) BoolItem2() Item[bool] { return v.ж.BoolItem2 }
func (v TestPrefsView) StringSlice() ListView[string] { return v.ж.StringSlice.View() }
func (v TestPrefsView) IntSlice() ListView[int] { return v.ж.IntSlice.View() }
func (v TestPrefsView) AddrItem() Item[netip.Addr] { return v.ж.AddrItem }
func (v TestPrefsView) StringStringMap() MapView[string, string] { return v.ж.StringStringMap.View() }
func (v TestPrefsView) IntStringMap() MapView[int, string] { return v.ж.IntStringMap.View() }
func (v TestPrefsView) AddrIntMap() MapView[netip.Addr, int] { return v.ж.AddrIntMap.View() }
func (v TestPrefsView) Bundle1() ItemView[*TestBundle, TestBundleView] {
return ItemViewOf(&v.ж.Bundle1)
}
func (v TestPrefsView) Bundle2() ItemView[*TestBundle, TestBundleView] {
return ItemViewOf(&v.ж.Bundle2)
}
func (v TestPrefsView) Generic() ItemView[*TestGenericStruct[int], TestGenericStructView[int]] {
return ItemViewOf(&v.ж.Generic)
}
func (v TestPrefsView) BundleList() StructListView[*TestBundle, TestBundleView] {
return StructListViewOf(&v.ж.BundleList)
}
func (v TestPrefsView) StringBundleMap() StructMapView[string, *TestBundle, TestBundleView] {
return StructMapViewOf(&v.ж.StringBundleMap)
}
func (v TestPrefsView) IntBundleMap() StructMapView[int, *TestBundle, TestBundleView] {
return StructMapViewOf(&v.ж.IntBundleMap)
}
func (v TestPrefsView) AddrBundleMap() StructMapView[netip.Addr, *TestBundle, TestBundleView] {
return StructMapViewOf(&v.ж.AddrBundleMap)
}
func (v TestPrefsView) Group() TestPrefsGroup { return v.ж.Group }
// A compilation failure here means this code must be regenerated, with the command at the top of this file.
var _TestPrefsViewNeedsRegeneration = TestPrefs(struct {
Int32Item Item[int32]
UInt64Item Item[uint64]
StringItem1 Item[string]
StringItem2 Item[string]
BoolItem1 Item[bool]
BoolItem2 Item[bool]
StringSlice List[string]
IntSlice List[int]
AddrItem Item[netip.Addr]
StringStringMap Map[string, string]
IntStringMap Map[int, string]
AddrIntMap Map[netip.Addr, int]
Bundle1 Item[*TestBundle]
Bundle2 Item[*TestBundle]
Generic Item[*TestGenericStruct[int]]
BundleList StructList[*TestBundle]
StringBundleMap StructMap[string, *TestBundle]
IntBundleMap StructMap[int, *TestBundle]
AddrBundleMap StructMap[netip.Addr, *TestBundle]
Group TestPrefsGroup
}{})
// View returns a readonly view of TestBundle.
func (p *TestBundle) View() TestBundleView {
return TestBundleView{ж: p}
}
// TestBundleView provides a read-only view over TestBundle.
//
// Its methods should only be called if `Valid()` returns true.
type TestBundleView struct {
// ж is the underlying mutable value, named with a hard-to-type
// character that looks pointy like a pointer.
// It is named distinctively to make you think of how dangerous it is to escape
// to callers. You must not let callers be able to mutate it.
ж *TestBundle
}
// Valid reports whether underlying value is non-nil.
func (v TestBundleView) Valid() bool { return v.ж != nil }
// AsStruct returns a clone of the underlying value which aliases no memory with
// the original.
func (v TestBundleView) AsStruct() *TestBundle {
if v.ж == nil {
return nil
}
return v.ж.Clone()
}
func (v TestBundleView) MarshalJSON() ([]byte, error) { return json.Marshal(v.ж) }
func (v *TestBundleView) UnmarshalJSON(b []byte) error {
if v.ж != nil {
return errors.New("already initialized")
}
if len(b) == 0 {
return nil
}
var x TestBundle
if err := json.Unmarshal(b, &x); err != nil {
return err
}
v.ж = &x
return nil
}
func (v TestBundleView) Name() string { return v.ж.Name }
func (v TestBundleView) Nested() *TestValueStruct {
if v.ж.Nested == nil {
return nil
}
x := *v.ж.Nested
return &x
}
func (v TestBundleView) Equal(v2 TestBundleView) bool { return v.ж.Equal(v2.ж) }
// A compilation failure here means this code must be regenerated, with the command at the top of this file.
var _TestBundleViewNeedsRegeneration = TestBundle(struct {
Name string
Nested *TestValueStruct
}{})
// View returns a readonly view of TestValueStruct.
func (p *TestValueStruct) View() TestValueStructView {
return TestValueStructView{ж: p}
}
// TestValueStructView provides a read-only view over TestValueStruct.
//
// Its methods should only be called if `Valid()` returns true.
type TestValueStructView struct {
// ж is the underlying mutable value, named with a hard-to-type
// character that looks pointy like a pointer.
// It is named distinctively to make you think of how dangerous it is to escape
// to callers. You must not let callers be able to mutate it.
ж *TestValueStruct
}
// Valid reports whether underlying value is non-nil.
func (v TestValueStructView) Valid() bool { return v.ж != nil }
// AsStruct returns a clone of the underlying value which aliases no memory with
// the original.
func (v TestValueStructView) AsStruct() *TestValueStruct {
if v.ж == nil {
return nil
}
return v.ж.Clone()
}
func (v TestValueStructView) MarshalJSON() ([]byte, error) { return json.Marshal(v.ж) }
func (v *TestValueStructView) UnmarshalJSON(b []byte) error {
if v.ж != nil {
return errors.New("already initialized")
}
if len(b) == 0 {
return nil
}
var x TestValueStruct
if err := json.Unmarshal(b, &x); err != nil {
return err
}
v.ж = &x
return nil
}
func (v TestValueStructView) Value() int { return v.ж.Value }
func (v TestValueStructView) Equal(v2 TestValueStructView) bool { return v.ж.Equal(v2.ж) }
// A compilation failure here means this code must be regenerated, with the command at the top of this file.
var _TestValueStructViewNeedsRegeneration = TestValueStruct(struct {
Value int
}{})
// View returns a readonly view of TestGenericStruct.
func (p *TestGenericStruct[T]) View() TestGenericStructView[T] {
return TestGenericStructView[T]{ж: p}
}
// TestGenericStructView[T] provides a read-only view over TestGenericStruct[T].
//
// Its methods should only be called if `Valid()` returns true.
type TestGenericStructView[T ImmutableType] struct {
// ж is the underlying mutable value, named with a hard-to-type
// character that looks pointy like a pointer.
// It is named distinctively to make you think of how dangerous it is to escape
// to callers. You must not let callers be able to mutate it.
ж *TestGenericStruct[T]
}
// Valid reports whether underlying value is non-nil.
func (v TestGenericStructView[T]) Valid() bool { return v.ж != nil }
// AsStruct returns a clone of the underlying value which aliases no memory with
// the original.
func (v TestGenericStructView[T]) AsStruct() *TestGenericStruct[T] {
if v.ж == nil {
return nil
}
return v.ж.Clone()
}
func (v TestGenericStructView[T]) MarshalJSON() ([]byte, error) { return json.Marshal(v.ж) }
func (v *TestGenericStructView[T]) UnmarshalJSON(b []byte) error {
if v.ж != nil {
return errors.New("already initialized")
}
if len(b) == 0 {
return nil
}
var x TestGenericStruct[T]
if err := json.Unmarshal(b, &x); err != nil {
return err
}
v.ж = &x
return nil
}
func (v TestGenericStructView[T]) Value() T { return v.ж.Value }
func (v TestGenericStructView[T]) Equal(v2 TestGenericStructView[T]) bool { return v.ж.Equal(v2.ж) }
// A compilation failure here means this code must be regenerated, with the command at the top of this file.
func _TestGenericStructViewNeedsRegeneration[T ImmutableType](TestGenericStruct[T]) {
_TestGenericStructViewNeedsRegeneration(struct {
Value T
}{})
}
// View returns a readonly view of TestPrefsGroup.
func (p *TestPrefsGroup) View() TestPrefsGroupView {
return TestPrefsGroupView{ж: p}
}
// TestPrefsGroupView provides a read-only view over TestPrefsGroup.
//
// Its methods should only be called if `Valid()` returns true.
type TestPrefsGroupView struct {
// ж is the underlying mutable value, named with a hard-to-type
// character that looks pointy like a pointer.
// It is named distinctively to make you think of how dangerous it is to escape
// to callers. You must not let callers be able to mutate it.
ж *TestPrefsGroup
}
// Valid reports whether underlying value is non-nil.
func (v TestPrefsGroupView) Valid() bool { return v.ж != nil }
// AsStruct returns a clone of the underlying value which aliases no memory with
// the original.
func (v TestPrefsGroupView) AsStruct() *TestPrefsGroup {
if v.ж == nil {
return nil
}
return v.ж.Clone()
}
func (v TestPrefsGroupView) MarshalJSON() ([]byte, error) { return json.Marshal(v.ж) }
func (v *TestPrefsGroupView) UnmarshalJSON(b []byte) error {
if v.ж != nil {
return errors.New("already initialized")
}
if len(b) == 0 {
return nil
}
var x TestPrefsGroup
if err := json.Unmarshal(b, &x); err != nil {
return err
}
v.ж = &x
return nil
}
func (v TestPrefsGroupView) FloatItem() Item[float64] { return v.ж.FloatItem }
func (v TestPrefsGroupView) TestStringItem() Item[TestStringType] { return v.ж.TestStringItem }
// A compilation failure here means this code must be regenerated, with the command at the top of this file.
var _TestPrefsGroupViewNeedsRegeneration = TestPrefsGroup(struct {
FloatItem Item[float64]
TestStringItem Item[TestStringType]
}{})

195
types/prefs/struct_list.go
Unescape View File

@ -0,0 +1,195 @@
// Copyright (c) Tailscale Inc & AUTHORS
// SPDX-License-Identifier: BSD-3-Clause
package prefs
import (
"fmt"
"reflect"
"slices"
jsonv2 "github.com/go-json-experiment/json"
"github.com/go-json-experiment/json/jsontext"
"tailscale.com/types/opt"
"tailscale.com/types/ptr"
"tailscale.com/types/views"
)
// StructList is a preference type that holds zero or more potentially mutable struct values.
type StructList[T views.Cloner[T]] struct {
preference[[]T]
}
// StructListOf returns a [StructList] configured with the specified value and [Options].
func StructListOf[T views.Cloner[T]](v []T, opts ...Options) StructList[T] {
return StructList[T]{preferenceOf(opt.ValueOf(deepCloneSlice(v)), opts...)}
}
// StructListWithOpts returns an unconfigured [StructList] with the specified [Options].
func StructListWithOpts[T views.Cloner[T]](opts ...Options) StructList[T] {
return StructList[T]{preferenceOf(opt.Value[[]T]{}, opts...)}
}
// SetValue configures the preference with the specified value.
// It fails and returns [ErrManaged] if p is a managed preference,
// and [ErrReadOnly] if p is a read-only preference.
func (l *StructList[T]) SetValue(val []T) error {
return l.preference.SetValue(deepCloneSlice(val))
}
// SetManagedValue configures the preference with the specified value
// and marks the preference as managed.
func (l *StructList[T]) SetManagedValue(val []T) {
l.preference.SetManagedValue(deepCloneSlice(val))
}
// Clone returns a copy of l that aliases no memory with l.
func (l StructList[T]) Clone() *StructList[T] {
res := ptr.To(l)
if v, ok := l.s.Value.GetOk(); ok {
res.s.Value.Set(deepCloneSlice(v))
}
return res
}
// Equal reports whether l and l2 are equal.
// If the template type T implements an Equal(T) bool method, it will be used
// instead of the == operator for value comparison.
// It panics if T is not comparable.
func (l StructList[T]) Equal(l2 StructList[T]) bool {
if l.s.Metadata != l2.s.Metadata {
return false
}
v1, ok1 := l.s.Value.GetOk()
v2, ok2 := l2.s.Value.GetOk()
if ok1 != ok2 {
return false
}
if ok1 != ok2 {
return false
}
return !ok1 || slices.EqualFunc(v1, v2, comparerFor[T]())
}
func deepCloneSlice[T views.Cloner[T]](s []T) []T {
c := make([]T, len(s))
for i := range s {
c[i] = s[i].Clone()
}
return c
}
type equatable[T any] interface {
Equal(other T) bool
}
func comparerFor[T any]() func(a, b T) bool {
switch t := reflect.TypeFor[T](); {
case t.Implements(reflect.TypeFor[equatable[T]]()):
return func(a, b T) bool { return any(a).(equatable[T]).Equal(b) }
case t.Comparable():
return func(a, b T) bool { return any(a) == any(b) }
default:
panic(fmt.Errorf("%v is not comparable", t))
}
}
// StructListView is a read-only view of a [StructList].
type StructListView[T views.ViewCloner[T, V], V views.StructView[T]] struct {
// ж is the underlying mutable value, named with a hard-to-type
// character that looks pointy like a pointer.
// It is named distinctively to make you think of how dangerous it is to escape
// to callers. You must not let callers be able to mutate it.
ж *StructList[T]
}
// StructListViewOf returns a read-only view of l.
// It is used by [tailscale.com/cmd/viewer].
func StructListViewOf[T views.ViewCloner[T, V], V views.StructView[T]](l *StructList[T]) StructListView[T, V] {
return StructListView[T, V]{l}
}
// Valid reports whether the underlying [StructList] is non-nil.
func (lv StructListView[T, V]) Valid() bool {
return lv.ж != nil
}
// AsStruct implements [views.StructView] by returning a clone of the preference
// which aliases no memory with the original.
func (lv StructListView[T, V]) AsStruct() *StructList[T] {
if lv.ж == nil {
return nil
}
return lv.ж.Clone()
}
// IsSet reports whether the preference has a value set.
func (lv StructListView[T, V]) IsSet() bool {
return lv.ж.IsSet()
}
// Value returns a read-only view of the value if the preference has a value set.
// Otherwise, it returns a read-only view of its default value.
func (lv StructListView[T, V]) Value() views.SliceView[T, V] {
return views.SliceOfViews(lv.ж.Value())
}
// ValueOk returns a read-only view of the value and true if the preference has a value set.
// Otherwise, it returns an invalid view and false.
func (lv StructListView[T, V]) ValueOk() (val views.SliceView[T, V], ok bool) {
if v, ok := lv.ж.ValueOk(); ok {
return views.SliceOfViews(v), true
}
return views.SliceView[T, V]{}, false
}
// DefaultValue returns a read-only view of the default value of the preference.
func (lv StructListView[T, V]) DefaultValue() views.SliceView[T, V] {
return views.SliceOfViews(lv.ж.DefaultValue())
}
// IsManaged reports whether the preference is managed via MDM, Group Policy, or similar means.
func (lv StructListView[T, V]) IsManaged() bool {
return lv.ж.IsManaged()
}
// IsReadOnly reports whether the preference is read-only and cannot be changed by user.
func (lv StructListView[T, V]) IsReadOnly() bool {
return lv.ж.IsReadOnly()
}
// Equal reports whether iv and iv2 are equal.
func (lv StructListView[T, V]) Equal(lv2 StructListView[T, V]) bool {
if !lv.Valid() && !lv2.Valid() {
return true
}
if lv.Valid() != lv2.Valid() {
return false
}
return lv.ж.Equal(*lv2.ж)
}
// MarshalJSONV2 implements [jsonv2.MarshalerV2].
func (lv StructListView[T, V]) MarshalJSONV2(out *jsontext.Encoder, opts jsonv2.Options) error {
return lv.ж.MarshalJSONV2(out, opts)
}
// UnmarshalJSONV2 implements [jsonv2.UnmarshalerV2].
func (lv *StructListView[T, V]) UnmarshalJSONV2(in *jsontext.Decoder, opts jsonv2.Options) error {
var x StructList[T]
if err := x.UnmarshalJSONV2(in, opts); err != nil {
return err
}
lv.ж = &x
return nil
}
// MarshalJSON implements [json.Marshaler].
func (lv StructListView[T, V]) MarshalJSON() ([]byte, error) {
return jsonv2.Marshal(lv) // uses MarshalJSONV2
}
// UnmarshalJSON implements [json.Unmarshaler].
func (lv *StructListView[T, V]) UnmarshalJSON(b []byte) error {
return jsonv2.Unmarshal(b, lv) // uses UnmarshalJSONV2
}

175
types/prefs/struct_map.go
Unescape View File

@ -0,0 +1,175 @@
// Copyright (c) Tailscale Inc & AUTHORS
// SPDX-License-Identifier: BSD-3-Clause
package prefs
import (
"maps"
jsonv2 "github.com/go-json-experiment/json"
"github.com/go-json-experiment/json/jsontext"
"tailscale.com/types/opt"
"tailscale.com/types/ptr"
"tailscale.com/types/views"
)
// StructMap is a preference type that holds potentially mutable key-value pairs.
type StructMap[K MapKeyType, V views.Cloner[V]] struct {
preference[map[K]V]
}
// StructMapOf returns a [StructMap] configured with the specified value and [Options].
func StructMapOf[K MapKeyType, V views.Cloner[V]](v map[K]V, opts ...Options) StructMap[K, V] {
return StructMap[K, V]{preferenceOf(opt.ValueOf(deepCloneMap(v)), opts...)}
}
// StructMapWithOpts returns an unconfigured [StructMap] with the specified [Options].
func StructMapWithOpts[K MapKeyType, V views.Cloner[V]](opts ...Options) StructMap[K, V] {
return StructMap[K, V]{preferenceOf(opt.Value[map[K]V]{}, opts...)}
}
// SetValue configures the preference with the specified value.
// It fails and returns [ErrManaged] if p is a managed preference,
// and [ErrReadOnly] if p is a read-only preference.
func (l *StructMap[K, V]) SetValue(val map[K]V) error {
return l.preference.SetValue(deepCloneMap(val))
}
// SetManagedValue configures the preference with the specified value
// and marks the preference as managed.
func (l *StructMap[K, V]) SetManagedValue(val map[K]V) {
l.preference.SetManagedValue(deepCloneMap(val))
}
// Clone returns a copy of m that aliases no memory with m.
func (m StructMap[K, V]) Clone() *StructMap[K, V] {
res := ptr.To(m)
if v, ok := m.s.Value.GetOk(); ok {
res.s.Value.Set(deepCloneMap(v))
}
return res
}
// Equal reports whether m and m2 are equal.
// If the template type V implements an Equal(V) bool method, it will be used
// instead of the == operator for value comparison.
// It panics if T is not comparable.
func (m StructMap[K, V]) Equal(m2 StructMap[K, V]) bool {
if m.s.Metadata != m2.s.Metadata {
return false
}
v1, ok1 := m.s.Value.GetOk()
v2, ok2 := m2.s.Value.GetOk()
if ok1 != ok2 {
return false
}
return !ok1 || maps.EqualFunc(v1, v2, comparerFor[V]())
}
func deepCloneMap[K comparable, V views.Cloner[V]](m map[K]V) map[K]V {
c := make(map[K]V, len(m))
for i := range m {
c[i] = m[i].Clone()
}
return c
}
// StructMapView is a read-only view of a [StructMap].
type StructMapView[K MapKeyType, T views.ViewCloner[T, V], V views.StructView[T]] struct {
// ж is the underlying mutable value, named with a hard-to-type
// character that looks pointy like a pointer.
// It is named distinctively to make you think of how dangerous it is to escape
// to callers. You must not let callers be able to mutate it.
ж *StructMap[K, T]
}
// StructMapViewOf returns a readonly view of m.
// It is used by [tailscale.com/cmd/viewer].
func StructMapViewOf[K MapKeyType, T views.ViewCloner[T, V], V views.StructView[T]](m *StructMap[K, T]) StructMapView[K, T, V] {
return StructMapView[K, T, V]{m}
}
// Valid reports whether the underlying [StructMap] is non-nil.
func (mv StructMapView[K, T, V]) Valid() bool {
return mv.ж != nil
}
// AsStruct implements [views.StructView] by returning a clone of the preference
// which aliases no memory with the original.
func (mv StructMapView[K, T, V]) AsStruct() *StructMap[K, T] {
if mv.ж == nil {
return nil
}
return mv.ж.Clone()
}
// IsSet reports whether the preference has a value set.
func (mv StructMapView[K, T, V]) IsSet() bool {
return mv.ж.IsSet()
}
// Value returns a read-only view of the value if the preference has a value set.
// Otherwise, it returns a read-only view of its default value.
func (mv StructMapView[K, T, V]) Value() views.MapFn[K, T, V] {
return views.MapFnOf(mv.ж.Value(), func(t T) V { return t.View() })
}
// ValueOk returns a read-only view of the value and true if the preference has a value set.
// Otherwise, it returns an invalid view and false.
func (mv StructMapView[K, T, V]) ValueOk() (val views.MapFn[K, T, V], ok bool) {
if v, ok := mv.ж.ValueOk(); ok {
return views.MapFnOf(v, func(t T) V { return t.View() }), true
}
return views.MapFn[K, T, V]{}, false
}
// DefaultValue returns a read-only view of the default value of the preference.
func (mv StructMapView[K, T, V]) DefaultValue() views.MapFn[K, T, V] {
return views.MapFnOf(mv.ж.DefaultValue(), func(t T) V { return t.View() })
}
// Managed reports whether the preference is managed via MDM, Group Policy, or similar means.
func (mv StructMapView[K, T, V]) IsManaged() bool {
return mv.ж.IsManaged()
}
// ReadOnly reports whether the preference is read-only and cannot be changed by user.
func (mv StructMapView[K, T, V]) IsReadOnly() bool {
return mv.ж.IsReadOnly()
}
// Equal reports whether mv and mv2 are equal.
func (mv StructMapView[K, T, V]) Equal(mv2 StructMapView[K, T, V]) bool {
if !mv.Valid() && !mv2.Valid() {
return true
}
if mv.Valid() != mv2.Valid() {
return false
}
return mv.ж.Equal(*mv2.ж)
}
// MarshalJSONV2 implements [jsonv2.MarshalerV2].
func (mv StructMapView[K, T, V]) MarshalJSONV2(out *jsontext.Encoder, opts jsonv2.Options) error {
return mv.ж.MarshalJSONV2(out, opts)
}
// UnmarshalJSONV2 implements [jsonv2.UnmarshalerV2].
func (mv *StructMapView[K, T, V]) UnmarshalJSONV2(in *jsontext.Decoder, opts jsonv2.Options) error {
var x StructMap[K, T]
if err := x.UnmarshalJSONV2(in, opts); err != nil {
return err
}
mv.ж = &x
return nil
}
// MarshalJSON implements [json.Marshaler].
func (mv StructMapView[K, T, V]) MarshalJSON() ([]byte, error) {
return jsonv2.Marshal(mv) // uses MarshalJSONV2
}
// UnmarshalJSON implements [json.Unmarshaler].
func (mv *StructMapView[K, T, V]) UnmarshalJSON(b []byte) error {
return jsonv2.Unmarshal(b, mv) // uses UnmarshalJSONV2
}
Write Preview
Loading…
Cancel
Save