feature/README.md
This directory contains Tailscale's modular feature system. The Tailscale
client has grown large; not every user wants every feature (an IoT device on
a few-dollar chip does not need Taildrop, WebDAV, ACME, or SSH). The
feature/ tree is how we make individual features conditionally linkable so
that resource-constrained builds can omit them, and so that new code lives
in small self-contained packages instead of being dumped into
LocalBackend.
The preferred home for new functionality is a feature/<name> package.
If there is any plausible user who might not want your feature in their
build (which is almost always the case), it should be modular from the
start. A feature package should install itself into the rest of Tailscale
via hooks, extensions, and registrations from its own init (see
"Hooks and registration" below). It should not export API used by callers
elsewhere in the tree; callers reach the feature through the hook, not by
importing it.
Think your functionality is so core that it must always be linked in?
Imagine any plausible user who might not want it. If you cannot,
ask before dumping code into ipn/ipnlocal or
similar.
Much of the tree is in a half-migrated state. A given feature may:
ts_omit_<name> build tag declared in
featuretags/featuretags.go, andfeature/<name>/, butipn/ipnlocal, cmd/tailscaled,
or elsewhere, either:
.go file gated with
//go:build !ts_omit_<name>), orif buildfeatures.HasFoo { ... } block that
the compiler and linker dead-code-eliminate when the tag is set.When you touch one of these features, prefer to keep migrating code into
its feature/<name> package rather than adding more to the old location.
But do not feel obligated to finish the migration in one PR.
feature/featuretagsfeaturetags/featuretags.go is the single
source of truth. It declares the Features
map: for each feature tag (a
lowercase string like acme or taildrop), it records the exported symbol
name used by generated constants, a human-readable description, and any
other features it depends on (forming a DAG).
Adding a new feature starts with adding an entry there. See the top of the
file for the tag naming convention: feature foo corresponds to build tag
ts_omit_foo (opt-out). The one exception is cli, which is opt-in via
ts_include_cli; see FeatureTag.IsOmittable.
Features can be marked ImplementationDetail: true
when they are internal
plumbing (e.g. dbus, c2n) that users would not select directly; they
exist only so that user-visible features can depend on them.
feature/buildfeaturesAfter editing featuretags.go, run:
./tool/go generate ./feature/buildfeatures
(or the meta make generate). That regenerates two files per feature in
buildfeatures/: feature_<name>_enabled.go and
feature_<name>_disabled.go, gated with //go:build !ts_omit_<name> and
//go:build ts_omit_<name> respectively. Each pair exports a single
boolean constant, e.g. HasACME. Because these are Go constants, code of
the form:
if buildfeatures.HasACME {
// ...
}
is dead-code-eliminated by the compiler and linker when the feature is omitted. Constants can eliminate code but they cannot remove imports; for that you still need a build-tag-gated file.
Use constants when moving code to feature/<name> is impractical (e.g.
the code has to sit inside LocalBackend), or when a small conditional
inside otherwise-shared logic is clearer than splitting into two files.
Prefer separate packages when you can.
feature/condregister: opt-out registrationcondregister/ is the one central package that
tailscaled (and the macOS/iOS closed-source client) empty-imports so
that all "on by default" features get registered. Every feature that
should ship in tailscaled by default has a maybe_<name>.go file here
of the form:
//go:build !ts_omit_<name>
package condregister
import _ "tailscale.com/feature/<name>"
That is the whole file. The build tag is the only mechanism that decides
whether the feature is compiled in. Because tailscaled imports
condregister, all these maybe_* files pull in their respective
feature/<name> packages by default; adding ts_omit_<name> to the
build removes the file, and with it the import, and with it the
package's init and everything it transitively depends on.
Some maybe_* files carry additional build tags (e.g.
//go:build !ios && !ts_omit_capture) when a feature should be excluded
on specific platforms.
feature/<name> package should not carry ts_omit_* tagsThe ts_omit_<name> tag lives only on the condregister/maybe_<name>.go
(and analogous tsnet/maybe_<name>.go) import shim, not on the
feature/<name>/*.go files themselves. Keeping the feature package
free of its own omit tag lets any program directly opt in with a blank
import regardless of what ts_omit_* tags are set on the top-level
build:
import _ "tailscale.com/feature/foo"
That is how a tsnet-using application pulls a feature in on its own
terms without having to reason about which ts_omit_* tags are in
effect.
OS-specific build tags inside feature/<name>/ are fine, and often
desirable: if the feature only makes sense on some platforms, gating
its files with //go:build linux (or !ios, etc.) both keeps
go test ./... passing on every GOOS and prevents a tsnet user on an
unsupported platform from accidentally blank-importing a package that
would fail to compile or run there.
tsnet does NOT depend on condregistertsnet is a library, not a daemon, and it links in a different (and
generally smaller) default feature set than tailscaled. tsnet has its
own top-level maybe_*.go files that decide which features it opts in
to, and its own depaware.txt.
Consequence: you cannot assume buildfeatures.HasFoo == true means
feature foo was actually linked. In a tsnet build, ts_omit_foo may
not be set (so HasFoo is true), yet tsnet may have never imported
feature/foo, so its init never ran and no hooks were installed.
buildfeatures.HasFoo really means "not explicitly omitted by build
tag." Whether the feature is actually present is
feature.IsRegistered("foo").
The idiom is:
buildfeatures.HasFoo && feature.IsRegistered("foo")
HasFoo lets the compiler DCE the whole expression in ts_omit_foo
builds; IsRegistered guards against the tsnet case where the tag is
unset but the package was never imported.
feature APIPackage feature itself
exposes the small runtime API used by feature packages and their callers:
feature.Register(name):
a feature package calls this from its init to record that it was
linked in. Callers use
feature.IsRegistered(name)
to check.feature.Hook[Func]:
a single-writer, single-reader hook. The
extension point declares a var HookX feature.Hook[func(...)], the
feature package Sets it once from init, and callers use
GetOk/GetOrNil/IsSet to invoke it. Set panics if called twice.feature.Hooks[Func]:
a slice of hooks for extension points that may
legitimately have multiple registrants.hooks.go alongside their
small dispatcher functions like
feature.CanAutoUpdate()
and
feature.TPMAvailable().
Add hooks here only sparingly: every hook in this package is loaded
by every consumer of feature, so its function signature must not
reference types from "heavy" packages. By heavy we mean any package
whose presence in this signature would unnecessarily grow
cmd/tailscaled/depaware-min.txt:
packages with a large API/dependency footprint (e.g. net/http,
crypto/tls, golang.org/x/crypto/ssh, k8s.io/...), or packages
that trigger expensive runtime features like reflect-based
registration. The minimal build's depaware file is sacred and must
not grow without good reason. Prefer primitives, small types/...
packages, or interfaces. If your hook needs a wide type, keep the
hook (and its dispatcher) in the caller's package instead of
promoting it here.ipnext.RegisterExtension
(in ipn/ipnext) is the corresponding
mechanism for features that need to hook into LocalBackend; see the
next section.
ipn/ipnextFor features that need to attach state and behavior to LocalBackend,
the plain feature.Hook mechanism is not enough; you also need
per-LocalBackend state and a well-defined lifecycle. That is what
ipn/ipnext provides.
Per-LocalBackend state matters because a single process can have more
than one LocalBackend alive at once: a tsnet program can host many
tsnet.Server nodes concurrently, each with its own LocalBackend.
Package-global variables in a feature package would be shared across all
of them, which should be avoided unless it is otherwise infeasible. An
ipnext.Extension
is instantiated once per LocalBackend, so each node gets its own
copy of the extension's state.
(A related, not-yet-realized goal is letting different tsnet nodes in
the same process opt in to different sets of hooks. Today the hook
registration is still process-global (the init runs once and the hook
is on for every LocalBackend), but the extension design leaves room to
make this per-node in the future. Don't rely on the process-global
behavior; keep state on the extension instance, not in globals.)
An ipnext.Extension is created once per LocalBackend. From init, a
feature package registers a factory:
func init() {
feature.Register("taildrop")
ipnext.RegisterExtension("taildrop", newExtension)
}
When LocalBackend.Start runs, it instantiates each registered
extension and calls its
Init(host ipnext.Host) error
method. Init is where the extension wires up its per-backend hooks
against host.Hooks():
func (e *extension) Init(h ipnext.Host) error {
h.Hooks().ProfileStateChange.Add(e.onChangeProfile)
h.Hooks().OnSelfChange.Add(e.onSelfChange)
h.Hooks().MutateNotifyLocked.Add(e.setNotifyFilesWaiting)
h.Hooks().SetPeerStatus.Add(e.setPeerStatus)
h.Hooks().BackendStateChange.Add(e.onBackendStateChange)
return nil
}
ipnext.Hooks
is a struct of feature.Hook/feature.Hooks fields
covering LocalBackend's extension points: backend and profile state
changes, netmap toggles, self-node changes, notify mutation, peer
status, packet-filter hooks, audit logging, and more. Read the type in
ipn/ipnext/ipnext.go for the current list; new hooks are added there
as needed.
Extension hooks run synchronously with the triggering LocalBackend
operation and can influence its outcome. Because multiple extensions may
touch the same shared state (prefs, active profile, exit node, etc.),
new hooks should be designed with a clear conflict-resolution story
rather than assuming a single writer.
To get back to your extension from a LocalBackend inside a LocalAPI or
C2N handler, use
ipnlocal.GetExt[*yourExtType](b).
Canonical examples:
feature/taildrop/ext.go: full extension with
per-backend state.feature/acme/acme.go: extension that also Sets a
handful of ipnlocal.Hook* singletons.The ipnext mechanism is a work in progress and not every part of
LocalBackend has been converted to hooks yet. If you need a new
extension point, ask.
featuretags and depaware / depcheckerTests come in three flavors:
feature/featuretags self-tests (featuretags_test.go)
validate the registry itself: that every declared dependency exists,
that there are no cycles, that Requires/RequiredBy return the
expected sets, and that every ts_omit_* string that appears
anywhere in the tree (via git grep) is declared in the map.
depaware (github.com/tailscale/depaware)
snapshots the full set of Go packages linked into each binary into
a checked-in depaware.txt file. Its job is right there in the
name: to force us to be aware of our deps. Every change to the
dependency graph shows up as a diff to depaware.txt in the same
PR that introduced it, so reviewers can see, prominently, exactly
what got pulled in or dropped. We use this to have an auditable
history of the dependency footprint of key programs and libraries.
We track several flavors:
tailscaled on all GOOSestailscale CLI on all GOOSescmd/derpertailscaled+CLI (depaware-min.txt, depaware-minbox.txt)tsnet (has its own depaware.txt)k8s-operator, which uses tsnetWhen reviewing a PR, look at the depaware diff to see what got pulled in or dropped, and make sure the changes make sense.
deptest.DepChecker
lets you lock down omissions once you've
achieved them. Rather than hoping nobody accidentally adds a
taildrop import back into a ts_omit_taildrop build, you write:
func TestOmitACME(t *testing.T) {
deptest.DepChecker{
GOOS: "linux",
GOARCH: "amd64",
Tags: "ts_omit_acme,ts_include_cli",
OnDep: func(dep string) {
if strings.Contains(dep, "/acme") {
t.Errorf("unexpected dep with ts_omit_acme: %q", dep)
}
},
}.Check(t)
}
cmd/tailscaled/deps_test.go has many examples; add new ones there
or wherever they fit. tsnet has its own TestDeps in
tsnet_test.go with a BadDeps map
asserting that things like feature/remoteconfig,
feature/syspolicy, and x/crypto/ssh never sneak into tsnet.
cmd/featuretags constructs valid sets of Go omit build tags. Start
from a minimal build and add features with --min --add=..., or start
from a full build and remove with --remove=...; either way it
respects the declared dependency DAG.build_dist.sh uses cmd/featuretags under the hood, so you do not
need to hand-maintain its build-tag lists as new features are added.Features in feature/featuretags/featuretags.go,
including any Deps../tool/go generate ./feature/buildfeatures (or make generate).feature/<name>/ with the code, and register hooks and any
ipnext.Extension from its init. Call feature.Register("<name>")
from init too.tailscaled, add
feature/condregister/maybe_<name>.go with //go:build !ts_omit_<name>
and a blank import of tailscale.com/feature/<name>.tsnet should also link it, add an equivalent maybe_<name>.go
under tsnet/. Otherwise remember buildfeatures.HasFoo alone is not
enough; pair it with feature.IsRegistered("foo").deptest.DepChecker test to lock down what does not get
linked when the feature is omitted.If something in this document is unclear, if you are not sure whether your work should be modular, or if you need a new extension point:
#client Slack channel.