prefs_example

package
v1.88.1 Latest Latest
Warning

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

 Go to latest Published: Sep 11, 2025 License: BSD-3-Clause Imports: 11 Imported by: 0

Documentation

Overview

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.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AppConnectorPrefs 

type AppConnectorPrefs struct {
	Advertise prefs.Item[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.

func (*AppConnectorPrefs) Clone 

func (src *AppConnectorPrefs) Clone() *AppConnectorPrefs

Clone makes a deep copy of AppConnectorPrefs. The result aliases no memory with the original.

func (*AppConnectorPrefs) View 

func (p *AppConnectorPrefs) View() AppConnectorPrefsView

View returns a read-only view of AppConnectorPrefs.

type AppConnectorPrefsView 

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

AppConnectorPrefsView provides a read-only view over AppConnectorPrefs.

Its methods should only be called if `Valid()` returns true.

func (AppConnectorPrefsView) Advertise 

func (v AppConnectorPrefsView) Advertise() prefs.Item[bool]

func (AppConnectorPrefsView) AsStruct 

func (v AppConnectorPrefsView) AsStruct() *AppConnectorPrefs

AsStruct returns a clone of the underlying value which aliases no memory with the original.

func (AppConnectorPrefsView) MarshalJSON 

func (v AppConnectorPrefsView) MarshalJSON() ([]byte, error)

MarshalJSON implements jsonv1.Marshaler.

func (AppConnectorPrefsView) MarshalJSONTo added in v1.88.0 

func (v AppConnectorPrefsView) MarshalJSONTo(enc *jsontext.Encoder) error

MarshalJSONTo implements jsonv2.MarshalerTo.

func (*AppConnectorPrefsView) UnmarshalJSON 

func (v *AppConnectorPrefsView) UnmarshalJSON(b []byte) error

UnmarshalJSON implements jsonv1.Unmarshaler.

func (*AppConnectorPrefsView) UnmarshalJSONFrom added in v1.88.0 

func (v *AppConnectorPrefsView) UnmarshalJSONFrom(dec *jsontext.Decoder) error

UnmarshalJSONFrom implements jsonv2.UnmarshalerFrom.

func (AppConnectorPrefsView) Valid 

func (v AppConnectorPrefsView) Valid() bool

Valid reports whether v's underlying value is non-nil.

type AutoUpdatePrefs 

type AutoUpdatePrefs struct {
	Check prefs.Item[bool]     `json:",omitzero"`
	Apply prefs.Item[opt.Bool] `json:",omitzero"`
}

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.

func (*AutoUpdatePrefs) Clone 

func (src *AutoUpdatePrefs) Clone() *AutoUpdatePrefs

Clone makes a deep copy of AutoUpdatePrefs. The result aliases no memory with the original.

func (*AutoUpdatePrefs) View 

func (p *AutoUpdatePrefs) View() AutoUpdatePrefsView

View returns a read-only view of AutoUpdatePrefs.

type AutoUpdatePrefsView 

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

AutoUpdatePrefsView provides a read-only view over AutoUpdatePrefs.

Its methods should only be called if `Valid()` returns true.

func (AutoUpdatePrefsView) Apply 

func (v AutoUpdatePrefsView) Apply() prefs.Item[opt.Bool]

func (AutoUpdatePrefsView) AsStruct 

func (v AutoUpdatePrefsView) AsStruct() *AutoUpdatePrefs

AsStruct returns a clone of the underlying value which aliases no memory with the original.

func (AutoUpdatePrefsView) Check 

func (v AutoUpdatePrefsView) Check() prefs.Item[bool]

func (AutoUpdatePrefsView) MarshalJSON 

func (v AutoUpdatePrefsView) MarshalJSON() ([]byte, error)

MarshalJSON implements jsonv1.Marshaler.

func (AutoUpdatePrefsView) MarshalJSONTo added in v1.88.0 

func (v AutoUpdatePrefsView) MarshalJSONTo(enc *jsontext.Encoder) error

MarshalJSONTo implements jsonv2.MarshalerTo.

func (*AutoUpdatePrefsView) UnmarshalJSON 

func (v *AutoUpdatePrefsView) UnmarshalJSON(b []byte) error

UnmarshalJSON implements jsonv1.Unmarshaler.

func (*AutoUpdatePrefsView) UnmarshalJSONFrom added in v1.88.0 

func (v *AutoUpdatePrefsView) UnmarshalJSONFrom(dec *jsontext.Decoder) error

UnmarshalJSONFrom implements jsonv2.UnmarshalerFrom.

func (AutoUpdatePrefsView) Valid 

func (v AutoUpdatePrefsView) Valid() bool

Valid reports whether v's underlying value is non-nil.

type Prefs 

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"`
}

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.MarshalerTo/jsonv2.UnmarshalerFrom 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.MarshalJSONTo, Prefs.UnmarshalJSONFrom, Prefs.MarshalJSON, and Prefs.UnmarshalJSON for an example implementation.

func (*Prefs) Clone 

func (src *Prefs) Clone() *Prefs

Clone makes a deep copy of Prefs. The result aliases no memory with the original.

func (Prefs) MarshalJSON 

func (p Prefs) MarshalJSON() ([]byte, error)

MarshalJSON implements [json.Marshaler].

func (Prefs) MarshalJSONTo added in v1.82.0 

func (p Prefs) MarshalJSONTo(out *jsontext.Encoder) error

MarshalJSONTo implements jsonv2.MarshalerTo. 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 (*Prefs) UnmarshalJSON 

func (p *Prefs) UnmarshalJSON(b []byte) error

UnmarshalJSON implements [json.Unmarshaler].

func (*Prefs) UnmarshalJSONFrom added in v1.82.0 

func (p *Prefs) UnmarshalJSONFrom(in *jsontext.Decoder) error

UnmarshalJSONFrom implements jsonv2.UnmarshalerFrom.

func (*Prefs) View 

func (p *Prefs) View() PrefsView

View returns a read-only view of Prefs.

type PrefsView 

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

PrefsView provides a read-only view over Prefs.

Its methods should only be called if `Valid()` returns true.

func (PrefsView) AdvertiseRoutes 

func (v PrefsView) AdvertiseRoutes() prefs.ListView[netip.Prefix]

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.

func (PrefsView) AdvertiseTags 

func (v PrefsView) AdvertiseTags() prefs.ListView[string]

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.

func (PrefsView) AllowSingleHosts 

func (v PrefsView) AllowSingleHosts() prefs.Item[marshalAsTrueInJSON]

func (PrefsView) AppConnector 

func (v PrefsView) AppConnector() AppConnectorPrefs

AppConnector contains app connector-related preferences. Each preference in the group can be configured and managed individually.

func (PrefsView) AsStruct 

func (v PrefsView) AsStruct() *Prefs

AsStruct returns a clone of the underlying value which aliases no memory with the original.

func (PrefsView) AutoUpdate 

func (v PrefsView) AutoUpdate() AutoUpdatePrefs

AutoUpdate contains auto-update preferences. Each preference in the group can be configured and managed individually.

func (PrefsView) ControlURL 

func (v PrefsView) ControlURL() prefs.Item[string]

func (PrefsView) CorpDNS 

func (v PrefsView) CorpDNS() prefs.Item[bool]

func (PrefsView) DriveShares 

func (v PrefsView) DriveShares() prefs.StructListView[*drive.Share, drive.ShareView]

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.

func (PrefsView) Egg 

func (v PrefsView) Egg() prefs.Item[bool]

func (PrefsView) ExitNodeAllowLANAccess 

func (v PrefsView) ExitNodeAllowLANAccess() prefs.Item[bool]

func (PrefsView) ExitNodeID 

func (v PrefsView) ExitNodeID() prefs.Item[tailcfg.StableNodeID]

func (PrefsView) ExitNodeIP 

func (v PrefsView) ExitNodeIP() prefs.Item[netip.Addr]

func (PrefsView) ExitNodePrior 

func (v PrefsView) ExitNodePrior() tailcfg.StableNodeID

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.

func (PrefsView) ForceDaemon 

func (v PrefsView) ForceDaemon() prefs.Item[bool]

func (PrefsView) Hostname 

func (v PrefsView) Hostname() prefs.Item[string]

func (PrefsView) LoggedOut 

func (v PrefsView) LoggedOut() prefs.Item[bool]

func (PrefsView) MarshalJSON 

func (v PrefsView) MarshalJSON() ([]byte, error)

MarshalJSON implements jsonv1.Marshaler.

func (PrefsView) MarshalJSONTo added in v1.88.0 

func (v PrefsView) MarshalJSONTo(enc *jsontext.Encoder) error

MarshalJSONTo implements jsonv2.MarshalerTo.

func (PrefsView) NetfilterKind 

func (v PrefsView) NetfilterKind() prefs.Item[string]

func (PrefsView) NetfilterMode 

func (v PrefsView) NetfilterMode() prefs.Item[preftype.NetfilterMode]

func (PrefsView) NoSNAT 

func (v PrefsView) NoSNAT() prefs.Item[bool]

func (PrefsView) NoStatefulFiltering 

func (v PrefsView) NoStatefulFiltering() prefs.Item[opt.Bool]

func (PrefsView) NotepadURLs 

func (v PrefsView) NotepadURLs() prefs.Item[bool]

func (PrefsView) OperatorUser 

func (v PrefsView) OperatorUser() prefs.Item[string]

func (PrefsView) Persist 

func (v PrefsView) Persist() persist.PersistView

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.

func (PrefsView) PostureChecking 

func (v PrefsView) PostureChecking() prefs.Item[bool]

func (PrefsView) ProfileName 

func (v PrefsView) ProfileName() prefs.Item[string]

func (PrefsView) RouteAll 

func (v PrefsView) RouteAll() prefs.Item[bool]

func (PrefsView) RunSSH 

func (v PrefsView) RunSSH() prefs.Item[bool]

func (PrefsView) RunWebClient 

func (v PrefsView) RunWebClient() prefs.Item[bool]

func (PrefsView) ShieldsUp 

func (v PrefsView) ShieldsUp() prefs.Item[bool]

func (*PrefsView) UnmarshalJSON 

func (v *PrefsView) UnmarshalJSON(b []byte) error

UnmarshalJSON implements jsonv1.Unmarshaler.

func (*PrefsView) UnmarshalJSONFrom added in v1.88.0 

func (v *PrefsView) UnmarshalJSONFrom(dec *jsontext.Decoder) error

UnmarshalJSONFrom implements jsonv2.UnmarshalerFrom.

func (PrefsView) Valid 

func (v PrefsView) Valid() bool

Valid reports whether v's underlying value is non-nil.

func (PrefsView) WantRunning 

func (v PrefsView) WantRunning() prefs.Item[bool]

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.