prefs_example

package
v1.78.2 Latest Latest
Warning

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

 Go to latest Published: Dec 11, 2024 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 readonly 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)

func (*AppConnectorPrefsView) UnmarshalJSON 

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

func (AppConnectorPrefsView) Valid 

func (v AppConnectorPrefsView) Valid() bool

Valid reports whether 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 readonly 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)

func (*AutoUpdatePrefsView) UnmarshalJSON 

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

func (AutoUpdatePrefsView) Valid 

func (v AutoUpdatePrefsView) Valid() bool

Valid reports whether 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.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.

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

func (p Prefs) MarshalJSONV2(out *jsontext.Encoder, opts jsonv2.Options) error

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 (*Prefs) UnmarshalJSON 

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

UnmarshalJSON implements json.Unmarshaler.

func (*Prefs) UnmarshalJSONV2 

func (p *Prefs) UnmarshalJSONV2(in *jsontext.Decoder, opts jsonv2.Options) error

UnmarshalJSONV2 implements jsonv2.UnmarshalerV2.

func (*Prefs) View 

func (p *Prefs) View() PrefsView

View returns a readonly 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]

func (PrefsView) AdvertiseTags 

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

func (PrefsView) AllowSingleHosts 

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

func (PrefsView) AppConnector 

func (v PrefsView) AppConnector() AppConnectorPrefs

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

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]

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

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)

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

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

func (PrefsView) Valid 

func (v PrefsView) Valid() bool

Valid reports whether 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.