misc/genreadme,tempfork/pkgdoc,tsnet: generate README.md files from godoc
Adds a CI check to keep opted-in directories' README.md files in sync
with their package godoc. For now tsnet (and its sub-packages under
tsnet/example) is the only opted-in tree. The list of directories
lives in misc/genreadme/genreadme.go as defaultRoots, so CI and humans
both just run `./tool/go run ./misc/genreadme` with no arguments.
The check piggybacks on the existing go_generate job in test.yml and
fails if any README.md is out of date, pointing the user at the same
command.
Along the way:
- tempfork/pkgdoc now emits Markdown instead of plain text: headings
become level-2 with no {#hdr-...} anchors, and [Symbol] doc links
resolve to pkg.go.dev URLs, including for symbols in the current
package (which the default Printer would otherwise emit as bare
#Name fragments with no backing anchor in a README). Parsing no
longer uses parser.ImportsOnly, so doc.Package knows the package's
symbols and can resolve [Symbol] links at all.
- genreadme also emits a pkg.go.dev Go Reference badge at the top of
a library package's README; suppressed for package main.
- tsnet/tsnet.go's package godoc is expanded in idiomatic godoc
syntax — [Type], [Type.Method], reference-style [link]: URL
definitions — rather than Markdown-flavored [text](url) or
backtick-quoted identifiers, so that both pkg.go.dev and the
generated README.md render cleanly from a single source.
Fixes #19431
Fixes #19483
Fixes #19470
Change-Id: I8ca37e9e7b3bd446b8bfa7a91ac548f142688cb1
Co-authored-by: Brad Fitzpatrick <bradfitz@tailscale.com>
Signed-off-by: Walter Poupore <walterp@tailscale.com>
Signed-off-by: Brad Fitzpatrick <bradfitz@tailscale.com>
This commit is contained in:
Brad Fitzpatrick
committed by
Brad Fitzpatrick
Brad Fitzpatrick
parent
311dd3839d
commit
a7d8aeb8ae
+100
@@ -0,0 +1,100 @@
|
||||
<!-- README.md auto-generated by misc/genreadme; DO NOT EDIT. (or remove this line) -->
|
||||
|
||||
# tsnet
|
||||
|
||||
[](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()
|
||||
}
|
||||
@@ -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.
|
||||
@@ -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
|
||||
@@ -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.
|
||||
@@ -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": ["*"],
|
||||
],
|
||||
@@ -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:
|
||||
//
|
||||
|
||||
@@ -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.
|
||||
+121
-1
@@ -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 (
|
||||
|
||||
Reference in New Issue
Block a user