v2: added UsersResource

Updates tailscale/corp#21629

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

Author: oxtoacart

v2/client.go

@@ -45,6 +45,7 @@ type (
 		keys          *KeysResource
 		logging       *LoggingResource
 		policyFile    *PolicyFileResource
+		users         *UsersResource
 		webhooks      *WebhooksResource
 	}
 
@@ -104,6 +105,7 @@ func (c *Client) init() {
 		c.keys = &KeysResource{c}
 		c.logging = &LoggingResource{c}
 		c.policyFile = &PolicyFileResource{c}
+		c.users = &UsersResource{c}
 		c.webhooks = &WebhooksResource{c}
 	})
 }
@@ -157,6 +159,11 @@ func (c *Client) PolicyFile() *PolicyFileResource {
 	return c.policyFile
 }
 
+func (c *Client) Users() *UsersResource {
+	c.init()
+	return c.users
+}
+
 func (c *Client) Webhooks() *WebhooksResource {
 	c.init()
 	return c.webhooks

v2/tailscale_test.go

@@ -21,6 +21,7 @@ type TestServer struct {
 
 	Method string
 	Path   string
+	Query  url.Values
 	Body   *bytes.Buffer
 	Header http.Header
 
@@ -69,6 +70,7 @@ func NewTestHarness(t *testing.T) (*tsclient.Client, *TestServer) {
 func (t *TestServer) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	t.Method = r.Method
 	t.Path = r.URL.Path
+	t.Query = r.URL.Query()
 	t.Header = r.Header
 
 	t.Body = bytes.NewBuffer([]byte{})

v2/users.go

@@ -0,0 +1,98 @@
+package tsclient
+
+import (
+	"context"
+	"net/http"
+	"time"
+)
+
+const (
+	UserTypeMember UserType = "member"
+	UserTypeShared UserType = "shared"
+)
+
+const (
+	UserRoleOwner        UserRole = "owner"
+	UserRoleMember       UserRole = "member"
+	UserRoleAdmin        UserRole = "admin"
+	UserRoleITAdmin      UserRole = "it-admin"
+	UserRoleNetworkAdmin UserRole = "network-admin"
+	UserRoleBillingAdmin UserRole = "billing-admin"
+	UserRoleAuditor      UserRole = "auditor"
+)
+
+const (
+	UserStatusActive           UserStatus = "active"
+	UserStatusIdle             UserStatus = "idle"
+	UserStatusSuspended        UserStatus = "suspended"
+	UserStatusNeedsApproval    UserStatus = "needs-approval"
+	UserStatusOverBillingLimit UserStatus = "over-billing-limit"
+)
+
+type (
+	// UserType is the type of relation this user has to the tailnet associated with the request.
+	UserType string
+
+	// UserRole is the role of the user.
+	UserRole string
+
+	// UserStatus is the status of the user.
+	UserStatus string
+
+	// User is a representation of a user within a tailnet.
+	User struct {
+		ID                 string     `json:"id"`
+		DisplayName        string     `json:"displayName"`
+		LoginName          string     `json:"loginName"`
+		ProfilePicURL      string     `json:"profilePicUrl"`
+		TailnetID          string     `json:"tailnetId"`
+		Created            time.Time  `json:"created"`
+		Type               UserType   `json:"type"`
+		Role               UserRole   `json:"role"`
+		Status             UserStatus `json:"status"`
+		DeviceCount        int        `json:"deviceCount"`
+		LastSeen           time.Time  `json:"lastSeen"`
+		CurrentlyConnected bool       `json:"currentlyConnected"`
+	}
+)
+
+type UsersResource struct {
+	*Client
+}
+
+// List lists all [User]s of a tailnet. If userType and/or role are provided,
+// the list of users will be filtered by those.
+func (ur *UsersResource) List(ctx context.Context, userType *UserType, role *UserRole) ([]User, error) {
+	u := ur.buildTailnetURL("users")
+	q := u.Query()
+	if userType != nil {
+		q.Add("type", string(*userType))
+	}
+	if role != nil {
+		q.Add("role", string(*role))
+	}
+	u.RawQuery = q.Encode()
+
+	req, err := ur.buildRequest(ctx, http.MethodGet, u)
+	if err != nil {
+		return nil, err
+	}
+
+	resp := make(map[string][]User)
+	if err = ur.do(req, &resp); err != nil {
+		return nil, err
+	}
+
+	return resp["users"], nil
+}
+
+// Get retrieves the [User] identified by the given id.
+func (ur *UsersResource) Get(ctx context.Context, id string) (*User, error) {
+	req, err := ur.buildRequest(ctx, http.MethodGet, ur.buildURL("users", id))
+	if err != nil {
+		return nil, err
+	}
+
+	var resp User
+	return &resp, ur.do(req, &resp)
+}

v2/users_test.go

@@ -0,0 +1,92 @@
+package tsclient_test
+
+import (
+	"context"
+	"net/http"
+	"net/url"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	tsclient "github.com/tailscale/tailscale-client-go/v2"
+)
+
+func TestClient_Users_List(t *testing.T) {
+	t.Parallel()
+
+	client, server := NewTestHarness(t)
+	server.ResponseCode = http.StatusOK
+
+	expectedUsers := map[string][]tsclient.User{
+		"users": {
+			{
+				ID:                 "12345",
+				DisplayName:        "Jane Doe",
+				LoginName:          "janedoe",
+				ProfilePicURL:      "http://example.com/users/janedoe",
+				TailnetID:          "1",
+				Created:            time.Date(2022, 2, 10, 11, 50, 23, 0, time.UTC),
+				Type:               tsclient.UserTypeMember,
+				Role:               tsclient.UserRoleOwner,
+				Status:             tsclient.UserStatusActive,
+				DeviceCount:        2,
+				LastSeen:           time.Date(2022, 2, 10, 12, 50, 23, 0, time.UTC),
+				CurrentlyConnected: true,
+			},
+			{
+				ID:                 "12346",
+				DisplayName:        "John Doe",
+				LoginName:          "johndoe",
+				ProfilePicURL:      "http://example.com/users/johndoe",
+				TailnetID:          "2",
+				Created:            time.Date(2022, 2, 10, 11, 50, 23, 12, time.UTC),
+				Type:               tsclient.UserTypeShared,
+				Role:               tsclient.UserRoleMember,
+				Status:             tsclient.UserStatusIdle,
+				DeviceCount:        2,
+				LastSeen:           time.Date(2022, 2, 10, 12, 50, 23, 12, time.UTC),
+				CurrentlyConnected: true,
+			},
+		},
+	}
+	server.ResponseBody = expectedUsers
+
+	actualUsers, err := client.Users().List(
+		context.Background(),
+		tsclient.PointerTo(tsclient.UserTypeMember),
+		tsclient.PointerTo(tsclient.UserRoleAdmin))
+	assert.NoError(t, err)
+	assert.Equal(t, http.MethodGet, server.Method)
+	assert.Equal(t, "/api/v2/tailnet/example.com/users", server.Path)
+	assert.Equal(t, url.Values{"type": []string{"member"}, "role": []string{"admin"}}, server.Query)
+	assert.Equal(t, expectedUsers["users"], actualUsers)
+}
+
+func TestClient_Users_Get(t *testing.T) {
+	t.Parallel()
+
+	client, server := NewTestHarness(t)
+	server.ResponseCode = http.StatusOK
+
+	expectedUser := &tsclient.User{
+		ID:                 "12345",
+		DisplayName:        "Jane Doe",
+		LoginName:          "janedoe",
+		ProfilePicURL:      "http://example.com/users/janedoe",
+		TailnetID:          "1",
+		Created:            time.Date(2022, 2, 10, 11, 50, 23, 0, time.UTC),
+		Type:               tsclient.UserTypeMember,
+		Role:               tsclient.UserRoleOwner,
+		Status:             tsclient.UserStatusActive,
+		DeviceCount:        2,
+		LastSeen:           time.Date(2022, 2, 10, 12, 50, 23, 0, time.UTC),
+		CurrentlyConnected: true,
+	}
+	server.ResponseBody = expectedUser
+
+	actualUser, err := client.Users().Get(context.Background(), "12345")
+	assert.NoError(t, err)
+	assert.Equal(t, http.MethodGet, server.Method)
+	assert.Equal(t, "/api/v2/users/12345", server.Path)
+	assert.Equal(t, expectedUser, actualUser)
+}