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
+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