summaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
Diffstat
-rw-r--r--.github/workflows/test.yml8
-rw-r--r--misc/genreadme/genreadme.go96
-rw-r--r--tempfork/pkgdoc/pkgdoc.go46
-rw-r--r--tsnet/README.md100
-rw-r--r--tsnet/example/tshello/README.md5
-rw-r--r--tsnet/example/tsnet-funnel/README.md9
-rw-r--r--tsnet/example/tsnet-http-client/README.md5
-rw-r--r--tsnet/example/tsnet-services/README.md32
-rw-r--r--tsnet/example/tsnet-services/tsnet-services.go7
-rw-r--r--tsnet/example/web-client/README.md5
-rw-r--r--tsnet/tsnet.go122
11 files changed, 399 insertions, 36 deletions
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 1a7690022..ded7873aa 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -787,6 +787,14 @@ jobs:
echo
echo
git diff --name-only --exit-code || (echo "The files above need updating. Please run 'go generate'."; exit 1)
+ - name: check that 'genreadme' is clean
+ working-directory: src
+ run: |
+ ./tool/go run ./misc/genreadme
+ git add -N . # ensure untracked files are noticed
+ echo
+ echo
+ git diff --name-only --exit-code || (echo "The files above need updating. Please run './tool/go run ./misc/genreadme'."; exit 1)
make_tidy:
runs-on: ubuntu-24.04
diff --git a/misc/genreadme/genreadme.go b/misc/genreadme/genreadme.go
index 779f4c8c4..97a8d9e16 100644
--- a/misc/genreadme/genreadme.go
+++ b/misc/genreadme/genreadme.go
@@ -20,6 +20,7 @@ import (
"io/fs"
"log"
"os"
+ "path"
"path/filepath"
"runtime"
"strings"
@@ -28,6 +29,9 @@ import (
"tailscale.com/tempfork/pkgdoc"
)
+// modulePath is the current module's import path, read from go.mod at startup.
+var modulePath string
+
var skip = map[string]bool{
"out": true,
}
@@ -36,15 +40,25 @@ var skip = map[string]bool{
// Buildkite because a deploy workflow is not set up for them.
var bkSkip = map[string]bool{}
+// defaultRoots are the directory trees walked when genreadme is run with
+// no arguments. Add a directory here to opt its package (and any
+// sub-packages) into README.md generation from godoc.
+var defaultRoots = []string{
+ "tsnet",
+}
+
func main() {
flag.Parse()
- root := "."
+ modulePath = readModulePath("go.mod")
+ var roots []string
switch flag.NArg() {
case 0:
+ roots = defaultRoots
case 1:
- root = flag.Arg(0)
+ root := flag.Arg(0)
root = strings.TrimPrefix(root, "./")
root = strings.TrimSuffix(root, "/")
+ roots = []string{root}
default:
log.Fatalf("Usage: genreadme [dir]")
}
@@ -54,27 +68,29 @@ func main() {
updateErrs = append(updateErrs, err)
}).Limit(runtime.NumCPU() * 2) // usually I/O bound
- g.Go(func() error {
- return fs.WalkDir(os.DirFS("."), root, func(path string, d fs.DirEntry, err error) error {
- if err != nil {
- return err
- }
- if !d.IsDir() {
+ for _, root := range roots {
+ g.Go(func() error {
+ return fs.WalkDir(os.DirFS("."), root, func(path string, d fs.DirEntry, err error) error {
+ if err != nil {
+ return err
+ }
+ if !d.IsDir() {
+ return nil
+ }
+ if skip[path] {
+ return fs.SkipDir
+ }
+ base := filepath.Base(path)
+ if base == "testdata" || (path != "." && base[0] == '.') {
+ return fs.SkipDir
+ }
+ run(func() error {
+ return update(path)
+ })
return nil
- }
- if skip[path] {
- return fs.SkipDir
- }
- base := filepath.Base(path)
- if base == "testdata" || (path != "." && base[0] == '.') {
- return fs.SkipDir
- }
- run(func() error {
- return update(path)
})
- return nil
})
- })
+ }
g.Wait()
if err := errors.Join(updateErrs...); err != nil {
log.Fatal(err)
@@ -126,7 +142,7 @@ func getNewContent(dir string) (newContent []byte, err error) {
quickTest func(dir string, dents []fs.DirEntry) bool
generate func(dir string) ([]byte, error)
}{
- {"go", hasPkgMainGoFiles, genGoDoc},
+ {"go", hasGoFiles, genGoDoc},
}
for _, gen := range generators {
if !gen.quickTest(dir, dents) {
@@ -147,7 +163,11 @@ func genGoDoc(dir string) ([]byte, error) {
if err != nil {
return nil, fmt.Errorf("failed to get absolute path for %q: %w", dir, err)
}
- godoc, err := pkgdoc.PackageDoc(abs)
+ var importPath string
+ if modulePath != "" {
+ importPath = path.Join(modulePath, filepath.ToSlash(dir))
+ }
+ godoc, err := pkgdoc.PackageDoc(abs, importPath)
if err != nil {
return nil, fmt.Errorf("failed to get package doc for %q: %w", dir, err)
}
@@ -155,13 +175,22 @@ func genGoDoc(dir string) ([]byte, error) {
// No godoc; skipping.
return nil, nil
}
- if bytes.HasPrefix(godoc, []byte("package ")) {
- // Not a package main; skipping.
+ isLibrary := bytes.HasPrefix(godoc, []byte("package "))
+ if isLibrary {
+ // Strip the "package X // import Y\n\n" clause emitted for library packages.
+ if i := bytes.Index(godoc, []byte("\n\n")); i != -1 {
+ godoc = godoc[i+2:]
+ }
+ }
+ if len(bytes.TrimSpace(godoc)) == 0 {
return nil, nil
}
var buf bytes.Buffer
io.WriteString(&buf, genHeader)
fmt.Fprintf(&buf, "\n# %s\n\n", filepath.Base(dir))
+ if isLibrary && importPath != "" {
+ fmt.Fprintf(&buf, "[![Go Reference](https://pkg.go.dev/badge/%s.svg)](https://pkg.go.dev/%s)\n\n", importPath, importPath)
+ }
buf.Write(godoc)
if !bytes.Contains(godoc, []byte("## Deploying")) {
@@ -184,6 +213,21 @@ const genHeader = "<!-- README.md auto-generated by misc/genreadme; DO NOT EDIT.
func isGenerated(b []byte) bool { return bytes.HasPrefix(b, []byte(genHeader)) }
+// readModulePath returns the module path declared in the given go.mod file,
+// or "" if it can't be read or parsed.
+func readModulePath(file string) string {
+ b, err := os.ReadFile(file)
+ if err != nil {
+ return ""
+ }
+ for line := range strings.Lines(string(b)) {
+ if rest, ok := strings.CutPrefix(strings.TrimSpace(line), "module "); ok {
+ return strings.Trim(strings.TrimSpace(rest), `"`)
+ }
+ }
+ return ""
+}
+
func hasBuildkite(dir string) bool {
if bkSkip[dir] {
return false
@@ -192,7 +236,7 @@ func hasBuildkite(dir string) bool {
return flyErr != nil
}
-func hasPkgMainGoFiles(dir string, dents []fs.DirEntry) bool {
+func hasGoFiles(dir string, dents []fs.DirEntry) bool {
var fset *token.FileSet
for _, de := range dents {
@@ -217,7 +261,7 @@ func hasPkgMainGoFiles(dir string, dents []fs.DirEntry) bool {
continue
}
- return pkgFile.Name.Name == "main"
+ return pkgFile.Name.Name != ""
}
return false
}
diff --git a/tempfork/pkgdoc/pkgdoc.go b/tempfork/pkgdoc/pkgdoc.go
index 1868b028e..cab38dd48 100644
--- a/tempfork/pkgdoc/pkgdoc.go
+++ b/tempfork/pkgdoc/pkgdoc.go
@@ -13,6 +13,7 @@ import (
"go/ast"
"go/build"
"go/doc"
+ "go/doc/comment"
"go/parser"
"go/token"
"io"
@@ -46,6 +47,31 @@ func (pkg *Package) ToText(w io.Writer, text, prefix, codePrefix string) {
w.Write(pr.Text(d))
}
+// ToMarkdown parses the godoc comment text and writes a Markdown rendering to w
+// suitable for a repository README.md: top-level sections become ## headings
+// without per-heading anchor IDs, and [Symbol] doc links resolve to pkg.go.dev,
+// including for symbols in the current package (which the default printer would
+// otherwise emit as bare #Name fragments with no backing anchor).
+func (pkg *Package) ToMarkdown(w io.Writer, text string) {
+ d := pkg.doc.Parser().Parse(text)
+ pr := pkg.doc.Printer()
+ pr.HeadingLevel = 2
+ pr.HeadingID = func(*comment.Heading) string { return "" }
+ pr.DocLinkBaseURL = "https://pkg.go.dev"
+ pr.DocLinkURL = func(link *comment.DocLink) string {
+ importPath := link.ImportPath
+ if importPath == "" {
+ importPath = pkg.doc.ImportPath
+ }
+ name := link.Name
+ if link.Recv != "" {
+ name = link.Recv + "." + name
+ }
+ return "https://pkg.go.dev/" + importPath + "#" + name
+ }
+ w.Write(pr.Markdown(d))
+}
+
// pkgBuffer is a wrapper for bytes.Buffer that prints a package clause the
// first time Write is called.
type pkgBuffer struct {
@@ -85,7 +111,10 @@ func parsePackage(writer io.Writer, pkg *build.Package, userPath string) *Packag
return slices.Contains(pkg.GoFiles, info.Name()) || slices.Contains(pkg.CgoFiles, info.Name())
}
fset := token.NewFileSet()
- pkgs, err := parser.ParseDir(fset, pkg.Dir, include, parser.ParseComments|parser.ImportsOnly)
+ // Parse declarations (not just imports) so that doc.Package knows the
+ // package's symbols; the Markdown printer needs this to resolve
+ // [Symbol] doc links in package comments.
+ pkgs, err := parser.ParseDir(fset, pkg.Dir, include, parser.ParseComments)
if err != nil {
log.Fatal(err)
}
@@ -144,10 +173,10 @@ func (pkg *Package) newlines(n int) {
}
}
-// packageDoc prints the docs for the package.
+// packageDoc prints the docs for the package as Markdown.
func (pkg *Package) packageDoc() {
pkg.Printf("") // Trigger the package clause; we know the package exists.
- pkg.ToText(&pkg.buf, pkg.doc.Doc, "", indent)
+ pkg.ToMarkdown(&pkg.buf, pkg.doc.Doc)
pkg.newlines(1)
pkg.bugs()
@@ -175,8 +204,12 @@ func (pkg *Package) bugs() {
}
}
-// PackageDoc generates documentation for a package in the given directory.
-func PackageDoc(dir string) ([]byte, error) {
+// PackageDoc generates Markdown documentation for the package in the given
+// directory. importPath is the full Go import path of that package (e.g.
+// "tailscale.com/tsnet"); it's used to render [Symbol] doc links to the
+// right pkg.go.dev URL. If importPath is empty, build.ImportDir's guess
+// is used (typically "." for module-based repos).
+func PackageDoc(dir, importPath string) ([]byte, error) {
var buf bytes.Buffer
var writer io.Writer = &buf
@@ -188,6 +221,9 @@ func PackageDoc(dir string) ([]byte, error) {
}
return nil, err
}
+ if importPath != "" {
+ buildPackage.ImportPath = importPath
+ }
userPath := dir
pkg := parsePackage(writer, buildPackage, userPath)
diff --git a/tsnet/README.md b/tsnet/README.md
new file mode 100644
index 000000000..432e71957
--- /dev/null
+++ b/tsnet/README.md
@@ -0,0 +1,100 @@
+<!-- README.md auto-generated by misc/genreadme; DO NOT EDIT. (or remove this line) -->
+
+# tsnet
+
+[![Go Reference](https://pkg.go.dev/badge/tailscale.com/tsnet.svg)](https://pkg.go.dev/tailscale.com/tsnet)
+
+Package tsnet embeds a Tailscale node directly into a Go program, allowing it to join a tailnet and accept or dial connections without running a separate tailscaled daemon or requiring any system-level configuration.
+
+## Overview
+
+Normally, Tailscale runs as a background system service (tailscaled) that manages a virtual network interface for the whole machine. tsnet takes a different approach: it runs a fully self-contained Tailscale node inside your process using a userspace TCP/IP stack (gVisor). This means:
+
+ - No root privileges required.
+ - No system daemons to install or manage.
+ - Multiple independent Tailscale nodes can run within a single binary.
+ - The node's [Tailscale identity](https://tailscale.com/docs/concepts/tailscale-identity) and state are stored in a directory you control.
+
+The core type is [Server](https://pkg.go.dev/tailscale.com/tsnet#Server), which represents one embedded Tailscale node. Calling [Server.Listen](https://pkg.go.dev/tailscale.com/tsnet#Server.Listen) or [Server.Dial](https://pkg.go.dev/tailscale.com/tsnet#Server.Dial) routes traffic exclusively over the tailnet. The standard library's [net.Listener](https://pkg.go.dev/net#Listener) and [net.Conn](https://pkg.go.dev/net#Conn) interfaces are returned, so any existing Go HTTP server, gRPC server, or other net-based code works without modification.
+
+## Usage
+
+ import "tailscale.com/tsnet"
+
+ s := &tsnet.Server{
+ Hostname: "my-service",
+ AuthKey: os.Getenv("TS_AUTHKEY"),
+ }
+ defer s.Close()
+
+ ln, err := s.Listen("tcp", ":80")
+ if err != nil {
+ log.Fatal(err)
+ }
+ log.Fatal(http.Serve(ln, myHandler))
+
+On first run, if no [Server.AuthKey](https://pkg.go.dev/tailscale.com/tsnet#Server.AuthKey) is provided and the node is not already enrolled, the server logs an authentication URL. Open it in a browser to add the node to your tailnet.
+
+## Authentication
+
+A [Server](https://pkg.go.dev/tailscale.com/tsnet#Server) authenticates using, in order of precedence:
+
+ 1. [Server.AuthKey](https://pkg.go.dev/tailscale.com/tsnet#Server.AuthKey).
+ 2. The TS\_AUTHKEY environment variable.
+ 3. The TS\_AUTH\_KEY environment variable.
+ 4. An OAuth client secret ([Server.ClientSecret](https://pkg.go.dev/tailscale.com/tsnet#Server.ClientSecret) or TS\_CLIENT\_SECRET), used to mint an auth key.
+ 5. Workload identity federation ([Server.ClientID](https://pkg.go.dev/tailscale.com/tsnet#Server.ClientID) plus [Server.IDToken](https://pkg.go.dev/tailscale.com/tsnet#Server.IDToken) or [Server.Audience](https://pkg.go.dev/tailscale.com/tsnet#Server.Audience)).
+ 6. An interactive login URL printed to [Server.UserLogf](https://pkg.go.dev/tailscale.com/tsnet#Server.UserLogf).
+
+If the node is already enrolled (state found in [Server.Store](https://pkg.go.dev/tailscale.com/tsnet#Server.Store)), the auth key is ignored unless TSNET\_FORCE\_LOGIN=1 is set.
+
+## Identifying callers
+
+Use the WhoIs method on the client returned by [Server.LocalClient](https://pkg.go.dev/tailscale.com/tsnet#Server.LocalClient) to identify who is making a request:
+
+ lc, _ := srv.LocalClient()
+ http.Serve(ln, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ who, err := lc.WhoIs(r.Context(), r.RemoteAddr)
+ if err != nil {
+ http.Error(w, err.Error(), 500)
+ return
+ }
+ fmt.Fprintf(w, "Hello, %s!", who.UserProfile.LoginName)
+ }))
+
+## Tailscale Funnel
+
+[Server.ListenFunnel](https://pkg.go.dev/tailscale.com/tsnet#Server.ListenFunnel) exposes your service on the public internet. [Tailscale Funnel](https://tailscale.com/docs/features/tailscale-funnel) currently supports TCP on ports 443, 8443, and 10000. HTTPS must be enabled in the Tailscale admin console.
+
+ ln, err := srv.ListenFunnel("tcp", ":443")
+ // ln is a TLS listener; connections can come from anywhere on the
+ // internet as well as from your tailnet.
+
+ // To restrict to public traffic only:
+ ln, err = srv.ListenFunnel("tcp", ":443", tsnet.FunnelOnly())
+
+## Tailscale Services
+
+[Server.ListenService](https://pkg.go.dev/tailscale.com/tsnet#Server.ListenService) advertises the node as a host for a named [Tailscale Service](https://tailscale.com/docs/features/tailscale-services). The node must use a tag-based identity. To advertise multiple ports, call ListenService once per port.
+
+ srv.AdvertiseTags = []string{"tag:myservice"}
+
+ ln, err := srv.ListenService("svc:my-service", tsnet.ServiceModeHTTP{
+ HTTPS: true,
+ Port: 443,
+ })
+ log.Printf("Listening on https://%s", ln.FQDN)
+
+## Running multiple nodes in one process
+
+Each [Server](https://pkg.go.dev/tailscale.com/tsnet#Server) instance is an independent node. Give each a unique [Server.Dir](https://pkg.go.dev/tailscale.com/tsnet#Server.Dir) and [Server.Hostname](https://pkg.go.dev/tailscale.com/tsnet#Server.Hostname):
+
+ for _, name := range []string{"frontend", "backend"} {
+ srv := &tsnet.Server{
+ Hostname: name,
+ Dir: filepath.Join(baseDir, name),
+ AuthKey: os.Getenv("TS_AUTHKEY"),
+ Ephemeral: true,
+ }
+ srv.Start()
+ }
diff --git a/tsnet/example/tshello/README.md b/tsnet/example/tshello/README.md
new file mode 100644
index 000000000..5d9d81829
--- /dev/null
+++ b/tsnet/example/tshello/README.md
@@ -0,0 +1,5 @@
+<!-- README.md auto-generated by misc/genreadme; DO NOT EDIT. (or remove this line) -->
+
+# tshello
+
+The tshello server demonstrates how to use Tailscale as a library.
diff --git a/tsnet/example/tsnet-funnel/README.md b/tsnet/example/tsnet-funnel/README.md
new file mode 100644
index 000000000..2b3031bed
--- /dev/null
+++ b/tsnet/example/tsnet-funnel/README.md
@@ -0,0 +1,9 @@
+<!-- README.md auto-generated by misc/genreadme; DO NOT EDIT. (or remove this line) -->
+
+# tsnet-funnel
+
+The tsnet-funnel server demonstrates how to use tsnet with Funnel.
+
+To use it, generate an auth key from the Tailscale admin panel and run the demo with the key:
+
+ TS_AUTHKEY=<yourkey> go run tsnet-funnel.go
diff --git a/tsnet/example/tsnet-http-client/README.md b/tsnet/example/tsnet-http-client/README.md
new file mode 100644
index 000000000..24aba97c8
--- /dev/null
+++ b/tsnet/example/tsnet-http-client/README.md
@@ -0,0 +1,5 @@
+<!-- README.md auto-generated by misc/genreadme; DO NOT EDIT. (or remove this line) -->
+
+# tsnet-http-client
+
+The tshello server demonstrates how to use Tailscale as a library.
diff --git a/tsnet/example/tsnet-services/README.md b/tsnet/example/tsnet-services/README.md
new file mode 100644
index 000000000..18bc072d7
--- /dev/null
+++ b/tsnet/example/tsnet-services/README.md
@@ -0,0 +1,32 @@
+<!-- README.md auto-generated by misc/genreadme; DO NOT EDIT. (or remove this line) -->
+
+# tsnet-services
+
+The tsnet-services example demonstrates how to use tsnet with Services.
+
+To run this example yourself:
+
+ 1. Add access controls which (i) define a new ACL tag, (ii) allow the demo node to host the Service, and (iii) allow peers on the tailnet to reach the Service. A sample ACL policy is provided below.
+ 2. [Generate an auth key](https://tailscale.com/kb/1085/auth-keys#generate-an-auth-key) using the Tailscale admin panel. When doing so, add your new tag to your key (Service hosts must be tagged nodes).
+ 3. [Define a Service](https://tailscale.com/kb/1552/tailscale-services#step-1-define-a-tailscale-service). For the purposes of this demo, it must be defined to listen on TCP port 443. Note that you only need to follow Step 1 in the linked document.
+ 4. Run the demo on the command line (step 4 command shown below).
+
+Command for step 4:
+
+ TS_AUTHKEY=<yourkey> go run tsnet-services.go -service <service-name>
+
+The following is a sample ACL policy for step 1:
+
+ "tagOwners": {
+ "tag:tsnet-demo-host": ["autogroup:member"],
+ },
+ "autoApprovers": {
+ "services": {
+ "svc:tsnet-demo": ["tag:tsnet-demo-host"],
+ },
+ },
+ "grants": [
+ "src": ["*"],
+ "dst": ["svc:tsnet-demo"],
+ "ip": ["*"],
+ ],
diff --git a/tsnet/example/tsnet-services/tsnet-services.go b/tsnet/example/tsnet-services/tsnet-services.go
index d72fd68fd..4604e8d3f 100644
--- a/tsnet/example/tsnet-services/tsnet-services.go
+++ b/tsnet/example/tsnet-services/tsnet-services.go
@@ -8,17 +8,16 @@
// 1. Add access controls which (i) define a new ACL tag, (ii) allow the demo
// node to host the Service, and (iii) allow peers on the tailnet to reach
// the Service. A sample ACL policy is provided below.
-//
// 2. [Generate an auth key] using the Tailscale admin panel. When doing so, add
// your new tag to your key (Service hosts must be tagged nodes).
-//
// 3. [Define a Service]. For the purposes of this demo, it must be defined to
// listen on TCP port 443. Note that you only need to follow Step 1 in the
// linked document.
+// 4. Run the demo on the command line (step 4 command shown below).
//
-// 4. Run the demo on the command line:
+// Command for step 4:
//
-// TS_AUTHKEY=<yourkey> go run tsnet-services.go -service <service-name>
+// TS_AUTHKEY=<yourkey> go run tsnet-services.go -service <service-name>
//
// The following is a sample ACL policy for step 1:
//
diff --git a/tsnet/example/web-client/README.md b/tsnet/example/web-client/README.md
new file mode 100644
index 000000000..6b4c42235
--- /dev/null
+++ b/tsnet/example/web-client/README.md
@@ -0,0 +1,5 @@
+<!-- README.md auto-generated by misc/genreadme; DO NOT EDIT. (or remove this line) -->
+
+# web-client
+
+The web-client command demonstrates serving the Tailscale web client over tsnet.
diff --git a/tsnet/tsnet.go b/tsnet/tsnet.go
index f28179773..cc03cdbb6 100644
--- a/tsnet/tsnet.go
+++ b/tsnet/tsnet.go
@@ -1,7 +1,127 @@
// Copyright (c) Tailscale Inc & contributors
// SPDX-License-Identifier: BSD-3-Clause
-// Package tsnet provides Tailscale as a library.
+// Package tsnet embeds a Tailscale node directly into a Go program,
+// allowing it to join a tailnet and accept or dial connections without
+// running a separate tailscaled daemon or requiring any system-level
+// configuration.
+//
+// # Overview
+//
+// Normally, Tailscale runs as a background system service (tailscaled)
+// that manages a virtual network interface for the whole machine. tsnet
+// takes a different approach: it runs a fully self-contained Tailscale
+// node inside your process using a userspace TCP/IP stack (gVisor).
+// This means:
+//
+// - No root privileges required.
+// - No system daemons to install or manage.
+// - Multiple independent Tailscale nodes can run within a single binary.
+// - The node's [Tailscale identity] and state are stored in a directory you control.
+//
+// The core type is [Server], which represents one embedded Tailscale
+// node. Calling [Server.Listen] or [Server.Dial] routes traffic
+// exclusively over the tailnet. The standard library's [net.Listener]
+// and [net.Conn] interfaces are returned, so any existing Go HTTP
+// server, gRPC server, or other net-based code works without
+// modification.
+//
+// # Usage
+//
+// import "tailscale.com/tsnet"
+//
+// s := &tsnet.Server{
+// Hostname: "my-service",
+// AuthKey: os.Getenv("TS_AUTHKEY"),
+// }
+// defer s.Close()
+//
+// ln, err := s.Listen("tcp", ":80")
+// if err != nil {
+// log.Fatal(err)
+// }
+// log.Fatal(http.Serve(ln, myHandler))
+//
+// On first run, if no [Server.AuthKey] is provided and the node is not
+// already enrolled, the server logs an authentication URL. Open it in a
+// browser to add the node to your tailnet.
+//
+// # Authentication
+//
+// A [Server] authenticates using, in order of precedence:
+//
+// 1. [Server.AuthKey].
+// 2. The TS_AUTHKEY environment variable.
+// 3. The TS_AUTH_KEY environment variable.
+// 4. An OAuth client secret ([Server.ClientSecret] or TS_CLIENT_SECRET),
+// used to mint an auth key.
+// 5. Workload identity federation ([Server.ClientID] plus
+// [Server.IDToken] or [Server.Audience]).
+// 6. An interactive login URL printed to [Server.UserLogf].
+//
+// If the node is already enrolled (state found in [Server.Store]), the
+// auth key is ignored unless TSNET_FORCE_LOGIN=1 is set.
+//
+// # Identifying callers
+//
+// Use the WhoIs method on the client returned by [Server.LocalClient]
+// to identify who is making a request:
+//
+// lc, _ := srv.LocalClient()
+// http.Serve(ln, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+// who, err := lc.WhoIs(r.Context(), r.RemoteAddr)
+// if err != nil {
+// http.Error(w, err.Error(), 500)
+// return
+// }
+// fmt.Fprintf(w, "Hello, %s!", who.UserProfile.LoginName)
+// }))
+//
+// # Tailscale Funnel
+//
+// [Server.ListenFunnel] exposes your service on the public internet.
+// [Tailscale Funnel] currently supports TCP on ports 443, 8443, and
+// 10000. HTTPS must be enabled in the Tailscale admin console.
+//
+// ln, err := srv.ListenFunnel("tcp", ":443")
+// // ln is a TLS listener; connections can come from anywhere on the
+// // internet as well as from your tailnet.
+//
+// // To restrict to public traffic only:
+// ln, err = srv.ListenFunnel("tcp", ":443", tsnet.FunnelOnly())
+//
+// # Tailscale Services
+//
+// [Server.ListenService] advertises the node as a host for a named
+// [Tailscale Service]. The node must use a tag-based identity. To
+// advertise multiple ports, call ListenService once per port.
+//
+// srv.AdvertiseTags = []string{"tag:myservice"}
+//
+// ln, err := srv.ListenService("svc:my-service", tsnet.ServiceModeHTTP{
+// HTTPS: true,
+// Port: 443,
+// })
+// log.Printf("Listening on https://%s", ln.FQDN)
+//
+// # Running multiple nodes in one process
+//
+// Each [Server] instance is an independent node. Give each a unique
+// [Server.Dir] and [Server.Hostname]:
+//
+// for _, name := range []string{"frontend", "backend"} {
+// srv := &tsnet.Server{
+// Hostname: name,
+// Dir: filepath.Join(baseDir, name),
+// AuthKey: os.Getenv("TS_AUTHKEY"),
+// Ephemeral: true,
+// }
+// srv.Start()
+// }
+//
+// [Tailscale identity]: https://tailscale.com/docs/concepts/tailscale-identity
+// [Tailscale Funnel]: https://tailscale.com/docs/features/tailscale-funnel
+// [Tailscale Service]: https://tailscale.com/docs/features/tailscale-services
package tsnet
import (
Copyright © 2025 - 2026 Wayne Cole. WTFPL. Attribution appreciated. No warranty. Not liable for bodily damages.