ipnext

type AuditLogProvider func() ipnauth.AuditLogFunc

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

type Extension interface {
	// Name is a unique name of the extension.
	// It must be the same as the name used to register the extension.
	Name() string

	// Init is called to initialize the extension when LocalBackend's
	// Start method is called. Extensions are created but not initialized
	// unless LocalBackend is started.
	//
	// If the extension cannot be initialized, it must return an error,
	// and its Shutdown method will not be called on the host's shutdown.
	// Returned errors are not fatal; they are used for logging.
	// A [SkipExtension] error indicates an intentional decision rather than a failure.
	Init(Host) error

	// Shutdown is called when LocalBackend is shutting down,
	// provided the extension was initialized. For multiple extensions,
	// Shutdown is called in the reverse order of Init.
	// Returned errors are not fatal; they are used for logging.
	// After a call to Shutdown, the extension will not be called again.
	Shutdown() error
}

type ExtensionServices interface {
	// FindExtensionByName returns an active extension with the given name,
	// or nil if no such extension exists.
	FindExtensionByName(name string) any

	// FindMatchingExtension finds the first active extension that matches target,
	// and if one is found, sets target to that extension and returns true.
	// Otherwise, it returns false.
	//
	// It panics if target is not a non-nil pointer to either a type
	// that implements [ipnext.Extension], or to any interface type.
	FindMatchingExtension(target any) bool
}

type Hooks struct {
	// BackendStateChange is called when the backend state changes.
	BackendStateChange feature.Hooks[func(ipn.State)]

	// ProfileStateChange contains callbacks that are invoked when the current login profile
	// or its [ipn.Prefs] change, after those changes have been made. The current login profile
	// may be changed either because of a profile switch, or because the profile information
	// was updated by [LocalBackend.SetControlClientStatus], including when the profile
	// is first populated and persisted.
	ProfileStateChange feature.Hooks[ProfileStateChangeCallback]

	// BackgroundProfileResolvers are registered background profile resolvers.
	// They're used to determine the profile to use when no GUI/CLI client is connected.
	//
	// TODO(nickkhyl): allow specifying some kind of priority/altitude for the resolver.
	// TODO(nickkhyl): make it a "profile resolver" instead of a "background profile resolver".
	// The concepts of the "current user", "foreground profile" and "background profile"
	// only exist on Windows, and we're moving away from them anyway.
	BackgroundProfileResolvers feature.Hooks[ProfileResolver]

	// AuditLoggers are registered [AuditLogProvider]s.
	// Each provider is called to get an [ipnauth.AuditLogFunc] when an auditable action
	// is about to be performed. If an audit logger returns an error, the action is denied.
	AuditLoggers feature.Hooks[AuditLogProvider]

	// NewControlClient are the functions to be called when a new control client
	// is created. It is called with the LocalBackend locked.
	NewControlClient feature.Hooks[NewControlClientCallback]

	// OnSelfChange is called (with LocalBackend.mu held) when the self node
	// changes, including changing to nothing (an invalid view).
	OnSelfChange feature.Hooks[func(tailcfg.NodeView)]

	// MutateNotifyLocked is called to optionally mutate the provided Notify
	// before sending it to the IPN bus. It is called with LocalBackend.mu held.
	MutateNotifyLocked feature.Hooks[func(*ipn.Notify)]

	// SetPeerStatus is called to mutate PeerStatus.
	// Callers must only use NodeBackend to read data.
	SetPeerStatus feature.Hooks[func(*ipnstate.PeerStatus, tailcfg.NodeView, NodeBackend)]
}

type Host interface {
	// Extensions returns the host's [ExtensionServices].
	Extensions() ExtensionServices

	// Profiles returns the host's [ProfileServices].
	Profiles() ProfileServices

	// AuditLogger returns a function that calls all currently registered audit loggers.
	// The function fails if any logger returns an error, indicating that the action
	// cannot be logged and must not be performed.
	//
	// The returned function captures the current state (e.g., the current profile) at
	// the time of the call and must not be persisted.
	AuditLogger() ipnauth.AuditLogFunc

	// Hooks returns a non-nil pointer to a [Hooks] struct.
	// Hooks must not be modified concurrently or after Tailscale has started.
	Hooks() *Hooks

	// SendNotifyAsync sends a notification to the IPN bus,
	// typically to the GUI client.
	SendNotifyAsync(ipn.Notify)

	// NodeBackend returns the [NodeBackend] for the currently active node
	// (which is approximately the same as the current profile).
	NodeBackend() NodeBackend
}

type NewControlClientCallback func(controlclient.Client, ipn.LoginProfileView) (cleanup func())

type NewExtensionFn func(logger.Logf, SafeBackend) (Extension, error)

type NodeBackend interface {
	// AppendMatchingPeers appends all peers that match the predicate
	// to the base slice and returns it.
	AppendMatchingPeers(base []tailcfg.NodeView, pred func(tailcfg.NodeView) bool) []tailcfg.NodeView

	// PeerCaps returns the capabilities that src has to this node.
	PeerCaps(src netip.Addr) tailcfg.PeerCapMap

	// PeerHasCap reports whether the peer has the specified peer capability.
	PeerHasCap(peer tailcfg.NodeView, cap tailcfg.PeerCapability) bool

	// PeerAPIBase returns the "http://ip:port" URL base to reach peer's
	// PeerAPI, or the empty string if the peer is invalid or doesn't support
	// PeerAPI.
	PeerAPIBase(tailcfg.NodeView) string

	// PeerHasPeerAPI whether the provided peer supports PeerAPI.
	//
	// It effectively just reports whether PeerAPIBase(node) is non-empty, but
	// potentially more efficiently.
	PeerHasPeerAPI(tailcfg.NodeView) bool
}

type ProfileResolver func(ProfileStore) ipn.LoginProfileView

type ProfileServices interface {
	// CurrentProfileState returns read-only views of the current profile
	// and its preferences. The returned views are always valid,
	// but the profile's [ipn.LoginProfileView.ID] returns ""
	// if the profile is new and has not been persisted yet.
	//
	// The returned views are immutable snapshots of the current profile
	// and prefs at the time of the call. The actual state is only guaranteed
	// to remain unchanged and match these views for the duration
	// of a callback invoked by the host, if used within that callback.
	//
	// Extensions that need the current profile or prefs at other times
	// should typically subscribe to [ProfileStateChangeCallback]
	// to be notified if the profile or prefs change after retrieval.
	// CurrentProfileState returns both the profile and prefs
	// to guarantee that they are consistent with each other.
	CurrentProfileState() (ipn.LoginProfileView, ipn.PrefsView)

	// CurrentPrefs is like [CurrentProfileState] but only returns prefs.
	CurrentPrefs() ipn.PrefsView

	// SwitchToBestProfileAsync asynchronously selects the best profile to use
	// and switches to it, unless it is already the current profile.
	//
	// If an extension needs to know when a profile switch occurs,
	// it must use [ProfileServices.RegisterProfileStateChangeCallback]
	// to register a [ProfileStateChangeCallback].
	//
	// The reason indicates why the profile is being switched, such as due
	// to a client connecting or disconnecting or a change in the desktop
	// session state. It is used for logging.
	SwitchToBestProfileAsync(reason string)
}

type ProfileStateChangeCallback func(_ ipn.LoginProfileView, _ ipn.PrefsView, sameNode bool)

type ProfileStore interface {
	// CurrentUserID returns the current user ID. It is only non-empty on
	// Windows where we have a multi-user system.
	//
	// Deprecated: this method exists for compatibility with the current (as of 2024-08-27)
	// permission model and will be removed as we progress on tailscale/corp#18342.
	CurrentUserID() ipn.WindowsUserID

	// CurrentProfile returns a read-only [ipn.LoginProfileView] of the current profile.
	// The returned view is always valid, but the profile's [ipn.LoginProfileView.ID]
	// returns "" if the profile is new and has not been persisted yet.
	CurrentProfile() ipn.LoginProfileView

	// CurrentPrefs returns a read-only view of the current prefs.
	// The returned view is always valid.
	CurrentPrefs() ipn.PrefsView

	// DefaultUserProfile returns a read-only view of the default (last used) profile for the specified user.
	// It returns a read-only view of a new, non-persisted profile if the specified user does not have a default profile.
	DefaultUserProfile(uid ipn.WindowsUserID) ipn.LoginProfileView
}

type SafeBackend interface {
	Sys() *tsd.System
	Clock() tstime.Clock
	TailscaleVarRoot() string
}