tailscale

Documentation

Overview

Package tailscale wraps the Tailscale REST API for testfleet.

We talk to api.tailscale.com directly rather than depending on the giant tailscale.com Go module. The OAuth client_credentials grant mints a short lived bearer; the bearer then lists devices for a tailnet. Mockable via BaseURL for tests using httptest.Server.

Index

• Constants
• Variables
• func ErrorCode(err error) output.ErrorCode
• func ToMachines(devs []Device, tag string, nowFn func() time.Time) []machines.Machine
• func ToMachinesWithInventory(devs []Device, tag string, nowFn func() time.Time, inv machines.Inventory) []machines.Machine
• type Client
  • func New(cfg Config) *Client
  • func (c *Client) ListDevices(ctx context.Context) ([]Device, error)
• type Config
• type Device

Constants

const DefaultBaseURL = "https://api.tailscale.com"

DefaultBaseURL is the production Tailscale API root.

const IdleThreshold = 5 * time.Minute

IdleThreshold is the lastSeen recency cutoff. A device seen within this window is reported as idle; older is offline. Inclusive at the boundary.

Variables

var ErrAuthFailed = errors.New("tailscale: authentication failed")

ErrAuthFailed is the sentinel returned when the OAuth token mint or any subsequent API call rejects our credentials. CLI commands branch on this via errors.Is and emit output.ErrTailscaleAuthFailed.

Functions

func ErrorCode

func ErrorCode(err error) output.ErrorCode

ErrorCode maps a client error to the public output.ErrorCode used in --json envelopes. Returns empty string for unclassified errors so callers can fall back to a generic message.

func ToMachines

func ToMachines(devs []Device, tag string, nowFn func() time.Time) []machines.Machine

ToMachines is the no-override convenience for ToMachinesWithInventory. nowFn lets tests inject a deterministic clock.

func ToMachinesWithInventory

func ToMachinesWithInventory(devs []Device, tag string, nowFn func() time.Time, inv machines.Inventory) []machines.Machine

ToMachinesWithInventory projects Tailscale devices to the testfleet Machine model: filters by tag, derives Status from lastSeen, applies per-host inventory overrides on top of defaults.

SnapshotCaps defaults to "none" (AC1: field always present) and may be overridden via inventory. RemotePrefix has no Tailscale-derived value and is supplied entirely by inventory.

Types

type Client

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

Client is a Tailscale API client. Safe for concurrent use; the cached token is guarded by a mutex.

func New

func New(cfg Config) *Client

New constructs a Client. It does not perform I/O.

func (*Client) ListDevices

func (c *Client) ListDevices(ctx context.Context) ([]Device, error)

ListDevices fetches all devices in the configured tailnet.

type Config

type Config struct {
	ClientID     string
	ClientSecret string
	APIToken     string // optional; when set, skips OAuth and uses this token as Bearer
	Tailnet      string
	BaseURL      string
	HTTPClient   *http.Client
}

Config configures a Client. The minimal required set is ClientID, ClientSecret, Tailnet. BaseURL defaults to DefaultBaseURL; HTTPClient defaults to http.DefaultClient.

type Device

type Device struct {
	Name      string   `json:"name"`     // FQDN, e.g. "host.tailnet.ts.net"
	Hostname  string   `json:"hostname"` // short hostname
	OS        string   `json:"os"`       // "windows", "linux", "macOS", ...
	Tags      []string `json:"tags"`
	Addresses []string `json:"addresses"` // Tailscale IPs (first entry is the IPv4 100.x.y.z)
	LastSeen  string   `json:"lastSeen"`  // RFC3339; empty string if never seen
}

Device mirrors the fields of the /devices response that we care about. Tailscale returns more fields; we ignore the rest to stay forward-compatible.