1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
|
// 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 read-only preference.
ErrReadOnly = errors.New("cannot modify a read-only 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
}
var (
_ jsonv2.MarshalerTo = (*preference[struct{}])(nil)
_ jsonv2.UnmarshalerFrom = (*preference[struct{}])(nil)
)
// MarshalJSONTo implements [jsonv2.MarshalerTo].
func (p preference[T]) MarshalJSONTo(out *jsontext.Encoder) error {
return jsonv2.MarshalEncode(out, &p.s)
}
// UnmarshalJSONFrom implements [jsonv2.UnmarshalerFrom].
func (p *preference[T]) UnmarshalJSONFrom(in *jsontext.Decoder) error {
return jsonv2.UnmarshalDecode(in, &p.s)
}
// MarshalJSON implements [json.Marshaler].
func (p preference[T]) MarshalJSON() ([]byte, error) {
return jsonv2.Marshal(p) // uses MarshalJSONTo
}
// UnmarshalJSON implements [json.Unmarshaler].
func (p *preference[T]) UnmarshalJSON(b []byte) error {
return jsonv2.Unmarshal(b, p) // uses UnmarshalJSONFrom
}
|
