devices: support querying all device fields

Add 'AdvertisedRoutes', 'EnabledRoutes' and 'ClientConnectivity' to the 'Device' type
and add the method 'ListWithAllFields' to obtain Devices with those fields populated.

Updates tailscale/corp#22748

Signed-off-by: Percy Wegmann <[email protected]>

Author: oxtoacart

devices.go

@@ -44,6 +44,29 @@ func (t *Time) UnmarshalJSON(data []byte) error {
 	return nil
 }
 
+type DERPRegion struct {
+	Preferred           bool    `json:"preferred,omitempty"`
+	LatencyMilliseconds float64 `json:"latencyMs"`
+}
+
+type ClientSupports struct {
+	HairPinning bool `json:"hairPinning"`
+	IPV6        bool `json:"ipv6"`
+	PCP         bool `json:"pcp"`
+	PMP         bool `json:"pmp"`
+	UDP         bool `json:"udp"`
+	UPNP        bool `json:"upnp"`
+}
+
+type ClientConnectivity struct {
+	Endpoints             []string `json:"endpoints"`
+	DERP                  string   `json:"derp"`
+	MappingVariesByDestIP bool     `json:"mappingVariesByDestIP"`
+	// DERPLatency is mapped by region name (e.g. "New York City", "Seattle").
+	DERPLatency    map[string]DERPRegion `json:"latency"`
+	ClientSupports ClientSupports        `json:"clientSupports"`
+}
+
 type Device struct {
 	Addresses                 []string `json:"addresses"`
 	Name                      string   `json:"name"`
@@ -66,6 +89,11 @@ type Device struct {
 	TailnetLockError          string   `json:"tailnetLockError"`
 	TailnetLockKey            string   `json:"tailnetLockKey"`
 	UpdateAvailable           bool     `json:"updateAvailable"`
+
+	// The below are only included in listings when querying `all` fields.
+	AdvertisedRoutes   []string            `json:"AdvertisedRoutes"`
+	EnabledRoutes      []string            `json:"enabledRoutes"`
+	ClientConnectivity *ClientConnectivity `json:"clientConnectivity"`
 }
 
 type DevicePostureAttributes struct {
@@ -115,13 +143,31 @@ func (dr *DevicesResource) SetPostureAttribute(ctx context.Context, deviceID, at
 	return dr.do(req, nil)
 }
 
-// List lists every [Device] in the tailnet.
+// ListWithAllFields lists every [Device] in the tailnet. Each [Device] in
+// the response will have all fields populated.
+func (dr *DevicesResource) ListWithAllFields(ctx context.Context) ([]Device, error) {
+	return dr.list(ctx, true)
+}
+
+// List lists every [Device] in the tailnet. The fields `EnabledRoutes`,
+// `AdvertisedRoutes` and `ClientConnectivity` will be omitted from the resulting
+// [Devices]. To get these fields, use `ListWithAllFields`.
 func (dr *DevicesResource) List(ctx context.Context) ([]Device, error) {
+	return dr.list(ctx, false)
+}
+
+func (dr *DevicesResource) list(ctx context.Context, all bool) ([]Device, error) {
 	req, err := dr.buildRequest(ctx, http.MethodGet, dr.buildTailnetURL("devices"))
 	if err != nil {
 		return nil, err
 	}
 
+	if all {
+		q := req.URL.Query()
+		q.Set("fields", "all")
+		req.URL.RawQuery = q.Encode()
+	}
+
 	m := make(map[string][]Device)
 	err = dr.do(req, &m)
 	if err != nil {

devices_test.go

@@ -64,6 +64,30 @@ func TestClient_Devices_Get(t *testing.T) {
 		TailnetLockError:          "test error",
 		TailnetLockKey:            "tlpub:test",
 		UpdateAvailable:           true,
+		AdvertisedRoutes:          []string{"127.0.0.1", "127.0.0.2"},
+		EnabledRoutes:             []string{"127.0.0.1"},
+		ClientConnectivity: &ClientConnectivity{
+			Endpoints: []string{"199.9.14.201:59128", "192.68.0.21:59128"},
+			DERP:      "New York City",
+			DERPLatency: map[string]DERPRegion{
+				"Dallas": {
+					LatencyMilliseconds: 60.463043,
+				},
+				"New York City": {
+					Preferred:           true,
+					LatencyMilliseconds: 31.323811,
+				},
+			},
+			MappingVariesByDestIP: true,
+			ClientSupports: ClientSupports{
+				HairPinning: false,
+				IPV6:        false,
+				PCP:         false,
+				PMP:         false,
+				UDP:         false,
+				UPNP:        false,
+			},
+		},
 	}
 
 	client, server := NewTestHarness(t)
@@ -142,6 +166,30 @@ func TestClient_Devices_List(t *testing.T) {
 				NodeKey:                   "nodekey:test",
 				OS:                        "windows",
 				UpdateAvailable:           true,
+				AdvertisedRoutes:          []string{"127.0.0.1", "127.0.0.2"},
+				EnabledRoutes:             []string{"127.0.0.1"},
+				ClientConnectivity: &ClientConnectivity{
+					Endpoints: []string{"199.9.14.201:59128", "192.68.0.21:59128"},
+					DERP:      "New York City",
+					DERPLatency: map[string]DERPRegion{
+						"Dallas": {
+							LatencyMilliseconds: 60.463043,
+						},
+						"New York City": {
+							Preferred:           true,
+							LatencyMilliseconds: 31.323811,
+						},
+					},
+					MappingVariesByDestIP: true,
+					ClientSupports: ClientSupports{
+						HairPinning: false,
+						IPV6:        false,
+						PCP:         false,
+						PMP:         false,
+						UDP:         false,
+						UPNP:        false,
+					},
+				},
 			},
 		},
 	}
@@ -150,10 +198,11 @@ func TestClient_Devices_List(t *testing.T) {
 	server.ResponseCode = http.StatusOK
 	server.ResponseBody = expectedDevices
 
-	actualDevices, err := client.Devices().List(context.Background())
+	actualDevices, err := client.Devices().ListWithAllFields(context.Background())
 	assert.NoError(t, err)
 	assert.Equal(t, http.MethodGet, server.Method)
 	assert.Equal(t, "/api/v2/tailnet/example.com/devices", server.Path)
+	assert.Equal(t, "all", server.Query.Get("fields"))
 	assert.EqualValues(t, expectedDevices["devices"], actualDevices)
 }