coder/codersdk/workspaces.go

package codersdk

import (
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"net/http"
	"net/http/cookiejar"
	"strings"
	"time"

	"github.com/google/uuid"
	"golang.org/x/xerrors"

	"cdr.dev/slog/v3"
	"github.com/coder/coder/v2/coderd/tracing"
	"github.com/coder/coder/v2/codersdk/wsjson"
	"github.com/coder/websocket"
)

type AutomaticUpdates string

const (
	AutomaticUpdatesAlways AutomaticUpdates = "always"
	AutomaticUpdatesNever  AutomaticUpdates = "never"
)

// Workspace is a deployment of a template. It references a specific
// version and can be updated.
type Workspace struct {
	ID        uuid.UUID `json:"id" format:"uuid"`
	CreatedAt time.Time `json:"created_at" format:"date-time"`
	UpdatedAt time.Time `json:"updated_at" format:"date-time"`
	OwnerID   uuid.UUID `json:"owner_id" format:"uuid"`
	// OwnerName is the username of the owner of the workspace.
	OwnerName                            string              `json:"owner_name"`
	OwnerAvatarURL                       string              `json:"owner_avatar_url"`
	OrganizationID                       uuid.UUID           `json:"organization_id" format:"uuid"`
	OrganizationName                     string              `json:"organization_name"`
	TemplateID                           uuid.UUID           `json:"template_id" format:"uuid"`
	TemplateName                         string              `json:"template_name"`
	TemplateDisplayName                  string              `json:"template_display_name"`
	TemplateIcon                         string              `json:"template_icon"`
	TemplateAllowUserCancelWorkspaceJobs bool                `json:"template_allow_user_cancel_workspace_jobs"`
	TemplateActiveVersionID              uuid.UUID           `json:"template_active_version_id" format:"uuid"`
	TemplateRequireActiveVersion         bool                `json:"template_require_active_version"`
	TemplateUseClassicParameterFlow      bool                `json:"template_use_classic_parameter_flow"`
	LatestBuild                          WorkspaceBuild      `json:"latest_build"`
	LatestAppStatus                      *WorkspaceAppStatus `json:"latest_app_status"`
	Outdated                             bool                `json:"outdated"`
	Name                                 string              `json:"name"`
	AutostartSchedule                    *string             `json:"autostart_schedule,omitempty"`
	TTLMillis                            *int64              `json:"ttl_ms,omitempty"`
	LastUsedAt                           time.Time           `json:"last_used_at" format:"date-time"`
	// DeletingAt indicates the time at which the workspace will be permanently deleted.
	// A workspace is eligible for deletion if it is dormant (a non-nil dormant_at value)
	// and a value has been specified for time_til_dormant_autodelete on its template.
	DeletingAt *time.Time `json:"deleting_at" format:"date-time"`
	// DormantAt being non-nil indicates a workspace that is dormant.
	// A dormant workspace is no longer accessible must be activated.
	// It is subject to deletion if it breaches
	// the duration of the time_til_ field on its template.
	DormantAt *time.Time `json:"dormant_at" format:"date-time"`
	// Health shows the health of the workspace and information about
	// what is causing an unhealthy status.
	Health           WorkspaceHealth  `json:"health"`
	AutomaticUpdates AutomaticUpdates `json:"automatic_updates" enums:"always,never"`
	AllowRenames     bool             `json:"allow_renames"`
	Favorite         bool             `json:"favorite"`
	NextStartAt      *time.Time       `json:"next_start_at" format:"date-time"`
	// IsPrebuild indicates whether the workspace is a prebuilt workspace.
	// Prebuilt workspaces are owned by the prebuilds system user and have specific behavior,
	// such as being managed differently from regular workspaces.
	// Once a prebuilt workspace is claimed by a user, it transitions to a regular workspace,
	// and IsPrebuild returns false.
	IsPrebuild bool `json:"is_prebuild"`
	// TaskID, if set, indicates that the workspace is relevant to the given codersdk.Task.
	TaskID     uuid.NullUUID          `json:"task_id,omitempty"`
	SharedWith []SharedWorkspaceActor `json:"shared_with,omitempty"`
}

func (w Workspace) FullName() string {
	return fmt.Sprintf("%s/%s", w.OwnerName, w.Name)
}

type WorkspaceHealth struct {
	Healthy       bool        `json:"healthy" example:"false"`      // Healthy is true if the workspace is healthy.
	FailingAgents []uuid.UUID `json:"failing_agents" format:"uuid"` // FailingAgents lists the IDs of the agents that are failing, if any.
}

type WorkspacesRequest struct {
	SearchQuery string `json:"q,omitempty"`
	Pagination
}

type WorkspacesResponse struct {
	Workspaces []Workspace `json:"workspaces"`
	Count      int         `json:"count"`
}

type ProvisionerLogLevel string

const (
	ProvisionerLogLevelDebug ProvisionerLogLevel = "debug"
)

type CreateWorkspaceBuildReason string

const (
	CreateWorkspaceBuildReasonDashboard           CreateWorkspaceBuildReason = "dashboard"
	CreateWorkspaceBuildReasonCLI                 CreateWorkspaceBuildReason = "cli"
	CreateWorkspaceBuildReasonSSHConnection       CreateWorkspaceBuildReason = "ssh_connection"
	CreateWorkspaceBuildReasonVSCodeConnection    CreateWorkspaceBuildReason = "vscode_connection"
	CreateWorkspaceBuildReasonJetbrainsConnection CreateWorkspaceBuildReason = "jetbrains_connection"
	CreateWorkspaceBuildReasonTaskManualPause     CreateWorkspaceBuildReason = "task_manual_pause"
	CreateWorkspaceBuildReasonTaskResume          CreateWorkspaceBuildReason = "task_resume"
)

// CreateWorkspaceBuildRequest provides options to update the latest workspace build.
type CreateWorkspaceBuildRequest struct {
	TemplateVersionID uuid.UUID           `json:"template_version_id,omitempty" format:"uuid"`
	Transition        WorkspaceTransition `json:"transition" validate:"oneof=start stop delete,required"`
	DryRun            bool                `json:"dry_run,omitempty"`
	ProvisionerState  []byte              `json:"state,omitempty"`
	// Orphan may be set for the Destroy transition.
	Orphan bool `json:"orphan,omitempty"`
	// ParameterValues are optional. It will write params to the 'workspace' scope.
	// This will overwrite any existing parameters with the same name.
	// This will not delete old params not included in this list.
	RichParameterValues []WorkspaceBuildParameter `json:"rich_parameter_values,omitempty"`

	// Log level changes the default logging verbosity of a provider ("info" if empty).
	LogLevel ProvisionerLogLevel `json:"log_level,omitempty" validate:"omitempty,oneof=debug"`
	// TemplateVersionPresetID is the ID of the template version preset to use for the build.
	TemplateVersionPresetID uuid.UUID `json:"template_version_preset_id,omitempty" format:"uuid"`
	// Reason sets the reason for the workspace build.
	Reason CreateWorkspaceBuildReason `json:"reason,omitempty" validate:"omitempty,oneof=dashboard cli ssh_connection vscode_connection jetbrains_connection task_manual_pause"`
}

type WorkspaceOptions struct {
	IncludeDeleted bool `json:"include_deleted,omitempty"`
}

// asRequestOption returns a function that can be used in (*Client).Request.
// It modifies the request query parameters.
func (o WorkspaceOptions) asRequestOption() RequestOption {
	return func(r *http.Request) {
		q := r.URL.Query()
		if o.IncludeDeleted {
			q.Set("include_deleted", "true")
		}
		r.URL.RawQuery = q.Encode()
	}
}

// Workspace returns a single workspace.
func (c *Client) Workspace(ctx context.Context, id uuid.UUID) (Workspace, error) {
	return c.getWorkspace(ctx, id)
}

// DeletedWorkspace returns a single workspace that was deleted.
func (c *Client) DeletedWorkspace(ctx context.Context, id uuid.UUID) (Workspace, error) {
	o := WorkspaceOptions{
		IncludeDeleted: true,
	}
	return c.getWorkspace(ctx, id, o.asRequestOption())
}

func (c *Client) getWorkspace(ctx context.Context, id uuid.UUID, opts ...RequestOption) (Workspace, error) {
	res, err := c.Request(ctx, http.MethodGet, fmt.Sprintf("/api/v2/workspaces/%s", id), nil, opts...)
	if err != nil {
		return Workspace{}, err
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		return Workspace{}, ReadBodyAsError(res)
	}
	var workspace Workspace
	return workspace, json.NewDecoder(res.Body).Decode(&workspace)
}

type WorkspaceBuildsRequest struct {
	WorkspaceID uuid.UUID `json:"workspace_id" format:"uuid" typescript:"-"`
	Pagination
	Since time.Time `json:"since,omitempty" format:"date-time"`
}

func (c *Client) WorkspaceBuilds(ctx context.Context, req WorkspaceBuildsRequest) ([]WorkspaceBuild, error) {
	res, err := c.Request(
		ctx, http.MethodGet,
		fmt.Sprintf("/api/v2/workspaces/%s/builds", req.WorkspaceID),
		nil, req.Pagination.asRequestOption(), WithQueryParam("since", req.Since.Format(time.RFC3339)),
	)
	if err != nil {
		return nil, err
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		return nil, ReadBodyAsError(res)
	}
	var workspaceBuild []WorkspaceBuild
	return workspaceBuild, json.NewDecoder(res.Body).Decode(&workspaceBuild)
}

// CreateWorkspaceBuild queues a new build to occur for a workspace.
func (c *Client) CreateWorkspaceBuild(ctx context.Context, workspace uuid.UUID, request CreateWorkspaceBuildRequest) (WorkspaceBuild, error) {
	res, err := c.Request(ctx, http.MethodPost, fmt.Sprintf("/api/v2/workspaces/%s/builds", workspace), request)
	if err != nil {
		return WorkspaceBuild{}, err
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusCreated {
		return WorkspaceBuild{}, ReadBodyAsError(res)
	}
	var workspaceBuild WorkspaceBuild
	return workspaceBuild, json.NewDecoder(res.Body).Decode(&workspaceBuild)
}

func (c *Client) WatchWorkspace(ctx context.Context, id uuid.UUID) (<-chan Workspace, error) {
	ctx, span := tracing.StartSpan(ctx)
	defer span.End()
	//nolint:bodyclose
	res, err := c.Request(ctx, http.MethodGet, fmt.Sprintf("/api/v2/workspaces/%s/watch", id), nil)
	if err != nil {
		return nil, err
	}
	if res.StatusCode != http.StatusOK {
		return nil, ReadBodyAsError(res)
	}
	nextEvent := ServerSentEventReader(ctx, res.Body)

	wc := make(chan Workspace, 256)
	go func() {
		defer close(wc)
		defer res.Body.Close()

		for {
			select {
			case <-ctx.Done():
				return
			default:
				sse, err := nextEvent()
				if err != nil {
					return
				}
				if sse.Type != ServerSentEventTypeData {
					continue
				}
				var ws Workspace
				b, ok := sse.Data.([]byte)
				if !ok {
					return
				}
				err = json.Unmarshal(b, &ws)
				if err != nil {
					return
				}
				select {
				case <-ctx.Done():
					return
				case wc <- ws:
				}
			}
		}
	}()

	return wc, nil
}

type UpdateWorkspaceRequest struct {
	Name string `json:"name,omitempty" validate:"username"`
}

func (c *Client) UpdateWorkspace(ctx context.Context, id uuid.UUID, req UpdateWorkspaceRequest) error {
	path := fmt.Sprintf("/api/v2/workspaces/%s", id.String())
	res, err := c.Request(ctx, http.MethodPatch, path, req)
	if err != nil {
		return xerrors.Errorf("update workspace: %w", err)
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusNoContent {
		return ReadBodyAsError(res)
	}
	return nil
}

// UpdateWorkspaceAutostartRequest is a request to update a workspace's autostart schedule.
type UpdateWorkspaceAutostartRequest struct {
	// Schedule is expected to be of the form `CRON_TZ=<IANA Timezone> <min> <hour> * * <dow>`
	// Example: `CRON_TZ=US/Central 30 9 * * 1-5` represents 0930 in the timezone US/Central
	// on weekdays (Mon-Fri). `CRON_TZ` defaults to UTC if not present.
	Schedule *string `json:"schedule,omitempty"`
}

// UpdateWorkspaceAutostart sets the autostart schedule for workspace by id.
// If the provided schedule is empty, autostart is disabled for the workspace.
func (c *Client) UpdateWorkspaceAutostart(ctx context.Context, id uuid.UUID, req UpdateWorkspaceAutostartRequest) error {
	path := fmt.Sprintf("/api/v2/workspaces/%s/autostart", id.String())
	res, err := c.Request(ctx, http.MethodPut, path, req)
	if err != nil {
		return xerrors.Errorf("update workspace autostart: %w", err)
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusNoContent {
		return ReadBodyAsError(res)
	}
	return nil
}

// UpdateWorkspaceTTLRequest is a request to update a workspace's TTL.
type UpdateWorkspaceTTLRequest struct {
	TTLMillis *int64 `json:"ttl_ms"`
}

// UpdateWorkspaceTTL sets the ttl for workspace by id.
// If the provided duration is nil, autostop is disabled for the workspace.
func (c *Client) UpdateWorkspaceTTL(ctx context.Context, id uuid.UUID, req UpdateWorkspaceTTLRequest) error {
	path := fmt.Sprintf("/api/v2/workspaces/%s/ttl", id.String())
	res, err := c.Request(ctx, http.MethodPut, path, req)
	if err != nil {
		return xerrors.Errorf("update workspace time until shutdown: %w", err)
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusNoContent {
		return ReadBodyAsError(res)
	}
	return nil
}

// PutExtendWorkspaceRequest is a request to extend the deadline of
// the active workspace build.
type PutExtendWorkspaceRequest struct {
	Deadline time.Time `json:"deadline" validate:"required" format:"date-time"`
}

// PutExtendWorkspace updates the deadline for resources of the latest workspace build.
func (c *Client) PutExtendWorkspace(ctx context.Context, id uuid.UUID, req PutExtendWorkspaceRequest) error {
	path := fmt.Sprintf("/api/v2/workspaces/%s/extend", id.String())
	res, err := c.Request(ctx, http.MethodPut, path, req)
	if err != nil {
		return xerrors.Errorf("extend workspace time until shutdown: %w", err)
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK && res.StatusCode != http.StatusNotModified {
		return ReadBodyAsError(res)
	}
	return nil
}

type PostWorkspaceUsageRequest struct {
	AgentID uuid.UUID    `json:"agent_id" format:"uuid"`
	AppName UsageAppName `json:"app_name"`
}

type UsageAppName string

const (
	UsageAppNameVscode          UsageAppName = "vscode"
	UsageAppNameJetbrains       UsageAppName = "jetbrains"
	UsageAppNameReconnectingPty UsageAppName = "reconnecting-pty"
	UsageAppNameSSH             UsageAppName = "ssh"
)

var AllowedAppNames = []UsageAppName{
	UsageAppNameVscode,
	UsageAppNameJetbrains,
	UsageAppNameReconnectingPty,
	UsageAppNameSSH,
}

// PostWorkspaceUsage marks the workspace as having been used recently and records an app stat.
func (c *Client) PostWorkspaceUsageWithBody(ctx context.Context, id uuid.UUID, req PostWorkspaceUsageRequest) error {
	path := fmt.Sprintf("/api/v2/workspaces/%s/usage", id.String())
	res, err := c.Request(ctx, http.MethodPost, path, req)
	if err != nil {
		return xerrors.Errorf("post workspace usage: %w", err)
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusNoContent {
		return ReadBodyAsError(res)
	}
	return nil
}

// PostWorkspaceUsage marks the workspace as having been used recently.
// Deprecated: use PostWorkspaceUsageWithBody instead
func (c *Client) PostWorkspaceUsage(ctx context.Context, id uuid.UUID) error {
	path := fmt.Sprintf("/api/v2/workspaces/%s/usage", id.String())
	res, err := c.Request(ctx, http.MethodPost, path, nil)
	if err != nil {
		return xerrors.Errorf("post workspace usage: %w", err)
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusNoContent {
		return ReadBodyAsError(res)
	}
	return nil
}

// UpdateWorkspaceUsageWithBodyContext periodically posts workspace usage for the workspace
// with the given id and app name in the background.
// The caller is responsible for calling the returned function to stop the background
// process.
func (c *Client) UpdateWorkspaceUsageWithBodyContext(ctx context.Context, workspaceID uuid.UUID, req PostWorkspaceUsageRequest) func() {
	hbCtx, hbCancel := context.WithCancel(ctx)
	// Perform one initial update
	err := c.PostWorkspaceUsageWithBody(hbCtx, workspaceID, req)
	if err != nil {
		c.logger.Warn(ctx, "failed to post workspace usage", slog.Error(err))
	}
	ticker := time.NewTicker(time.Minute)
	doneCh := make(chan struct{})
	go func() {
		defer func() {
			ticker.Stop()
			close(doneCh)
		}()
		for {
			select {
			case <-ticker.C:
				err := c.PostWorkspaceUsageWithBody(hbCtx, workspaceID, req)
				if err != nil {
					c.logger.Warn(ctx, "failed to post workspace usage in background", slog.Error(err))
				}
			case <-hbCtx.Done():
				return
			}
		}
	}()
	return func() {
		hbCancel()
		<-doneCh
	}
}

// UpdateWorkspaceUsageContext periodically posts workspace usage for the workspace
// with the given id in the background.
// The caller is responsible for calling the returned function to stop the background
// process.
// Deprecated: use UpdateWorkspaceUsageContextWithBody instead
func (c *Client) UpdateWorkspaceUsageContext(ctx context.Context, workspaceID uuid.UUID) func() {
	hbCtx, hbCancel := context.WithCancel(ctx)
	// Perform one initial update
	err := c.PostWorkspaceUsage(hbCtx, workspaceID)
	if err != nil {
		c.logger.Warn(ctx, "failed to post workspace usage", slog.Error(err))
	}
	ticker := time.NewTicker(time.Minute)
	doneCh := make(chan struct{})
	go func() {
		defer func() {
			ticker.Stop()
			close(doneCh)
		}()
		for {
			select {
			case <-ticker.C:
				err := c.PostWorkspaceUsage(hbCtx, workspaceID)
				if err != nil {
					c.logger.Warn(ctx, "failed to post workspace usage in background", slog.Error(err))
				}
			case <-hbCtx.Done():
				return
			}
		}
	}()
	return func() {
		hbCancel()
		<-doneCh
	}
}

// UpdateWorkspaceDormancy is a request to activate or make a workspace dormant.
// A value of false will activate a dormant workspace.
type UpdateWorkspaceDormancy struct {
	Dormant bool `json:"dormant"`
}

// UpdateWorkspaceDormancy sets a workspace as dormant if dormant=true and activates a dormant workspace
// if dormant=false.
func (c *Client) UpdateWorkspaceDormancy(ctx context.Context, id uuid.UUID, req UpdateWorkspaceDormancy) error {
	path := fmt.Sprintf("/api/v2/workspaces/%s/dormant", id.String())
	res, err := c.Request(ctx, http.MethodPut, path, req)
	if err != nil {
		return xerrors.Errorf("update workspace lock: %w", err)
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK && res.StatusCode != http.StatusNotModified {
		return ReadBodyAsError(res)
	}
	return nil
}

// UpdateWorkspaceAutomaticUpdatesRequest is a request to updates a workspace's automatic updates setting.
type UpdateWorkspaceAutomaticUpdatesRequest struct {
	AutomaticUpdates AutomaticUpdates `json:"automatic_updates"`
}

// UpdateWorkspaceAutomaticUpdates sets the automatic updates setting for workspace by id.
func (c *Client) UpdateWorkspaceAutomaticUpdates(ctx context.Context, id uuid.UUID, req UpdateWorkspaceAutomaticUpdatesRequest) error {
	path := fmt.Sprintf("/api/v2/workspaces/%s/autoupdates", id.String())
	res, err := c.Request(ctx, http.MethodPut, path, req)
	if err != nil {
		return xerrors.Errorf("update workspace automatic updates: %w", err)
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusNoContent {
		return ReadBodyAsError(res)
	}
	return nil
}

type WorkspaceFilter struct {
	// Owner can be "me" or a username
	Owner string `json:"owner,omitempty" typescript:"-"`
	// Template is a template name
	Template string `json:"template,omitempty" typescript:"-"`
	// Name will return partial matches
	Name string `json:"name,omitempty" typescript:"-"`
	// Status is a workspace status, which is really the status of the latest build
	Status string `json:"status,omitempty" typescript:"-"`
	// Offset is the number of workspaces to skip before returning results.
	Offset int `json:"offset,omitempty" typescript:"-"`
	// Limit is a limit on the number of workspaces returned.
	Limit int `json:"limit,omitempty" typescript:"-"`
	// Shared is a whether the workspace is shared with any users or groups
	Shared *bool `json:"shared,omitempty" typescript:"-"`
	// SharedWithUser is the username or ID of the user that the workspace is shared with
	SharedWithUser string `json:"shared_with_user,omitempty" typescript:"-"`
	// SharedWithGroup is the group name, group ID, or <org name>/<group name> of the group that the workspace is shared with
	SharedWithGroup string `json:"shared_with_group,omitempty" typescript:"-"`
	// FilterQuery supports a raw filter query string
	FilterQuery string `json:"q,omitempty"`
}

// asRequestOption returns a function that can be used in (*Client).Request.
// It modifies the request query parameters.
func (f WorkspaceFilter) asRequestOption() RequestOption {
	return func(r *http.Request) {
		var params []string
		// Make sure all user input is quoted to ensure it's parsed as a single
		// string.
		if f.Owner != "" {
			params = append(params, fmt.Sprintf("owner:%q", f.Owner))
		}
		if f.Name != "" {
			params = append(params, fmt.Sprintf("name:%q", f.Name))
		}
		if f.Template != "" {
			params = append(params, fmt.Sprintf("template:%q", f.Template))
		}
		if f.Status != "" {
			params = append(params, fmt.Sprintf("status:%q", f.Status))
		}
		if f.Shared != nil {
			params = append(params, fmt.Sprintf("shared:%v", *f.Shared))
		}
		if f.SharedWithUser != "" {
			params = append(params, fmt.Sprintf("shared_with_user:%q", f.SharedWithUser))
		}
		if f.SharedWithGroup != "" {
			params = append(params, fmt.Sprintf("shared_with_group:%q", f.SharedWithGroup))
		}
		if f.FilterQuery != "" {
			// If custom stuff is added, just add it on here.
			params = append(params, f.FilterQuery)
		}

		q := r.URL.Query()
		q.Set("q", strings.Join(params, " "))
		r.URL.RawQuery = q.Encode()
	}
}

// Workspaces returns all workspaces the authenticated user has access to.
func (c *Client) Workspaces(ctx context.Context, filter WorkspaceFilter) (WorkspacesResponse, error) {
	page := Pagination{
		Offset: filter.Offset,
		Limit:  filter.Limit,
	}
	res, err := c.Request(ctx, http.MethodGet, "/api/v2/workspaces", nil, filter.asRequestOption(), page.asRequestOption())
	if err != nil {
		return WorkspacesResponse{}, err
	}
	defer res.Body.Close()

	if res.StatusCode != http.StatusOK {
		return WorkspacesResponse{}, ReadBodyAsError(res)
	}

	var wres WorkspacesResponse
	return wres, json.NewDecoder(res.Body).Decode(&wres)
}

// WorkspaceByOwnerAndName returns a workspace by the owner's UUID and the workspace's name.
func (c *Client) WorkspaceByOwnerAndName(ctx context.Context, owner string, name string, params WorkspaceOptions) (Workspace, error) {
	res, err := c.Request(ctx, http.MethodGet, fmt.Sprintf("/api/v2/users/%s/workspace/%s", owner, name), nil, func(r *http.Request) {
		q := r.URL.Query()
		q.Set("include_deleted", fmt.Sprintf("%t", params.IncludeDeleted))
		r.URL.RawQuery = q.Encode()
	})
	if err != nil {
		return Workspace{}, err
	}
	defer res.Body.Close()

	if res.StatusCode != http.StatusOK {
		return Workspace{}, ReadBodyAsError(res)
	}

	var workspace Workspace
	return workspace, json.NewDecoder(res.Body).Decode(&workspace)
}

// SplitWorkspaceIdentifier splits an identifier into owner and
// workspace name. A bare name defaults the owner to Me ("me"). An
// "owner/name" pair is accepted, and identifiers with more than one
// "/" are rejected.
func SplitWorkspaceIdentifier(identifier string) (owner, name string, err error) {
	owner, name, ok := strings.Cut(identifier, "/")
	if !ok {
		return Me, identifier, nil
	}
	if strings.Contains(name, "/") {
		return "", "", xerrors.Errorf("invalid workspace identifier: %q", identifier)
	}
	return owner, name, nil
}

// ResolveWorkspace fetches a workspace by identifier, which may be a
// UUID, a bare name (owned by the current user), or an "owner/name"
// pair. When the identifier parses as a valid UUID but no workspace
// exists with that ID, the function falls back to a name-based
// lookup because workspace names can be valid UUID strings.
func (c *Client) ResolveWorkspace(ctx context.Context, identifier string) (Workspace, error) {
	if uid, err := uuid.Parse(identifier); err == nil {
		ws, err := c.Workspace(ctx, uid)
		if err == nil {
			return ws, nil
		}
		// A workspace name might be a valid UUID string. If the
		// ID-based lookup returned 404, fall through to name-based
		// lookup below.
		var sdkErr *Error
		if !errors.As(err, &sdkErr) || sdkErr.StatusCode() != http.StatusNotFound {
			return Workspace{}, err
		}
		// A standard dashed UUID (36 chars) cannot be a valid
		// workspace name (max 32 chars). Skip the wasted
		// name-based round-trip.
		if err := NameValid(identifier); err != nil {
			return Workspace{}, sdkErr
		}
	}
	owner, name, err := SplitWorkspaceIdentifier(identifier)
	if err != nil {
		return Workspace{}, err
	}
	return c.WorkspaceByOwnerAndName(ctx, owner, name, WorkspaceOptions{})
}

type WorkspaceQuota struct {
	CreditsConsumed int `json:"credits_consumed"`
	Budget          int `json:"budget"`
}

func (c *Client) WorkspaceQuota(ctx context.Context, organizationID string, userID string) (WorkspaceQuota, error) {
	res, err := c.Request(ctx, http.MethodGet, fmt.Sprintf("/api/v2/organizations/%s/members/%s/workspace-quota", organizationID, userID), nil)
	if err != nil {
		return WorkspaceQuota{}, err
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		return WorkspaceQuota{}, ReadBodyAsError(res)
	}
	var quota WorkspaceQuota
	return quota, json.NewDecoder(res.Body).Decode(&quota)
}

type ResolveAutostartResponse struct {
	ParameterMismatch bool `json:"parameter_mismatch"`
}

func (c *Client) ResolveAutostart(ctx context.Context, workspaceID string) (ResolveAutostartResponse, error) {
	res, err := c.Request(ctx, http.MethodGet, fmt.Sprintf("/api/v2/workspaces/%s/resolve-autostart", workspaceID), nil)
	if err != nil {
		return ResolveAutostartResponse{}, err
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		return ResolveAutostartResponse{}, ReadBodyAsError(res)
	}
	var response ResolveAutostartResponse
	return response, json.NewDecoder(res.Body).Decode(&response)
}

func (c *Client) FavoriteWorkspace(ctx context.Context, workspaceID uuid.UUID) error {
	res, err := c.Request(ctx, http.MethodPut, fmt.Sprintf("/api/v2/workspaces/%s/favorite", workspaceID), nil)
	if err != nil {
		return err
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusNoContent {
		return ReadBodyAsError(res)
	}
	return nil
}

func (c *Client) UnfavoriteWorkspace(ctx context.Context, workspaceID uuid.UUID) error {
	res, err := c.Request(ctx, http.MethodDelete, fmt.Sprintf("/api/v2/workspaces/%s/favorite", workspaceID), nil)
	if err != nil {
		return err
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusNoContent {
		return ReadBodyAsError(res)
	}
	return nil
}

func (c *Client) WorkspaceTimings(ctx context.Context, id uuid.UUID) (WorkspaceBuildTimings, error) {
	path := fmt.Sprintf("/api/v2/workspaces/%s/timings", id.String())
	res, err := c.Request(ctx, http.MethodGet, path, nil)
	if err != nil {
		return WorkspaceBuildTimings{}, err
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		return WorkspaceBuildTimings{}, ReadBodyAsError(res)
	}
	var timings WorkspaceBuildTimings
	return timings, json.NewDecoder(res.Body).Decode(&timings)
}

type WorkspaceACL struct {
	Users  []WorkspaceUser  `json:"users"`
	Groups []WorkspaceGroup `json:"group"`
}

type WorkspaceGroup struct {
	Group
	Role WorkspaceRole `json:"role" enums:"admin,use"`
}

type WorkspaceUser struct {
	MinimalUser
	Role WorkspaceRole `json:"role" enums:"admin,use"`
}

type SharedWorkspaceActor struct {
	ID        uuid.UUID                `json:"id" format:"uuid"`
	ActorType SharedWorkspaceActorType `json:"actor_type" enums:"group,user"`
	Name      string                   `json:"name"`
	AvatarURL string                   `json:"avatar_url,omitempty" format:"uri"`
	Roles     []WorkspaceRole          `json:"roles"`
}

type WorkspaceRole string

const (
	WorkspaceRoleAdmin   WorkspaceRole = "admin"
	WorkspaceRoleUse     WorkspaceRole = "use"
	WorkspaceRoleDeleted WorkspaceRole = ""
)

type SharedWorkspaceActorType string

const (
	SharedWorkspaceActorTypeGroup SharedWorkspaceActorType = "group"
	SharedWorkspaceActorTypeUser  SharedWorkspaceActorType = "user"
)

func (c *Client) WorkspaceACL(ctx context.Context, workspaceID uuid.UUID) (WorkspaceACL, error) {
	res, err := c.Request(ctx, http.MethodGet, fmt.Sprintf("/api/v2/workspaces/%s/acl", workspaceID), nil)
	if err != nil {
		return WorkspaceACL{}, err
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		return WorkspaceACL{}, ReadBodyAsError(res)
	}
	var acl WorkspaceACL
	return acl, json.NewDecoder(res.Body).Decode(&acl)
}

type UpdateWorkspaceACL struct {
	// UserRoles is a mapping from valid user UUIDs to the workspace role they
	// should be granted. To remove a user from the workspace, use "" as the role
	// (available as a constant named codersdk.WorkspaceRoleDeleted)
	UserRoles map[string]WorkspaceRole `json:"user_roles,omitempty"`
	// GroupRoles is a mapping from valid group UUIDs to the workspace role they
	// should be granted. To remove a group from the workspace, use "" as the role
	// (available as a constant named codersdk.WorkspaceRoleDeleted)
	GroupRoles map[string]WorkspaceRole `json:"group_roles,omitempty"`
}

func (c *Client) UpdateWorkspaceACL(ctx context.Context, workspaceID uuid.UUID, req UpdateWorkspaceACL) error {
	res, err := c.Request(ctx, http.MethodPatch, fmt.Sprintf("/api/v2/workspaces/%s/acl", workspaceID), req)
	if err != nil {
		return err
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusNoContent {
		return ReadBodyAsError(res)
	}
	return nil
}

func (c *Client) DeleteWorkspaceACL(ctx context.Context, workspaceID uuid.UUID) error {
	res, err := c.Request(ctx, http.MethodDelete, fmt.Sprintf("/api/v2/workspaces/%s/acl", workspaceID), nil)
	if err != nil {
		return err
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusNoContent {
		return ReadBodyAsError(res)
	}
	return nil
}

// ExternalAgentCredentials contains the credentials needed for an external agent to connect to Coder.
type ExternalAgentCredentials struct {
	Command    string `json:"command"`
	AgentToken string `json:"agent_token"`
}

func (c *Client) WorkspaceExternalAgentCredentials(ctx context.Context, workspaceID uuid.UUID, agentName string) (ExternalAgentCredentials, error) {
	path := fmt.Sprintf("/api/v2/workspaces/%s/external-agent/%s/credentials", workspaceID.String(), agentName)
	res, err := c.Request(ctx, http.MethodGet, path, nil)
	if err != nil {
		return ExternalAgentCredentials{}, err
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		return ExternalAgentCredentials{}, ReadBodyAsError(res)
	}
	var credentials ExternalAgentCredentials
	return credentials, json.NewDecoder(res.Body).Decode(&credentials)
}

// WorkspaceBuildUpdate contains information about a workspace build state change.
// This is published via the /watch-all-workspacebuilds SSE endpoint when the
// workspace-build-updates experiment is enabled.
type WorkspaceBuildUpdate struct {
	WorkspaceID   uuid.UUID `json:"workspace_id" format:"uuid"`
	WorkspaceName string    `json:"workspace_name"`
	BuildID       uuid.UUID `json:"build_id" format:"uuid"`
	// Transition is the workspace transition type: "start", "stop", or "delete".
	Transition string `json:"transition"`
	// JobStatus is the provisioner job status: "pending", "running",
	// "succeeded", "canceling", "canceled", or "failed".
	JobStatus   string `json:"job_status"`
	BuildNumber int32  `json:"build_number"`
}

// WatchAllWorkspaceBuilds watches for workspace build updates across all workspaces.
// This requires the workspace-build-updates experiment to be enabled.
// The returned decoder should be closed by calling Close() when done to properly
// clean up the WebSocket connection.
func (c *Client) WatchAllWorkspaceBuilds(ctx context.Context) (*wsjson.Decoder[WorkspaceBuildUpdate], error) {
	ctx, span := tracing.StartSpan(ctx)
	defer span.End()

	serverURL, err := c.URL.Parse("/api/experimental/watch-all-workspacebuilds")
	if err != nil {
		return nil, xerrors.Errorf("parse url: %w", err)
	}

	jar, err := cookiejar.New(nil)
	if err != nil {
		return nil, xerrors.Errorf("create cookie jar: %w", err)
	}
	jar.SetCookies(serverURL, []*http.Cookie{{
		Name:  SessionTokenCookie,
		Value: c.SessionToken(),
	}})
	httpClient := &http.Client{
		Jar:       jar,
		Transport: c.HTTPClient.Transport,
	}

	conn, res, err := websocket.Dial(ctx, serverURL.String(), &websocket.DialOptions{
		HTTPClient:      httpClient,
		CompressionMode: websocket.CompressionDisabled,
	})
	if err != nil {
		if res == nil {
			return nil, err
		}
		return nil, ReadBodyAsError(res)
	}

	d := wsjson.NewDecoder[WorkspaceBuildUpdate](conn, websocket.MessageText, c.logger)
	return d, nil
}

// WorkspaceAvailableUsers returns users available for workspace creation.
// This is used to populate the owner dropdown when creating workspaces for
// other users.
func (c *Client) WorkspaceAvailableUsers(ctx context.Context, organizationID uuid.UUID, userID string) ([]MinimalUser, error) {
	res, err := c.Request(ctx, http.MethodGet, fmt.Sprintf("/api/v2/organizations/%s/members/%s/workspaces/available-users", organizationID, userID), nil)
	if err != nil {
		return nil, err
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		return nil, ReadBodyAsError(res)
	}
	var users []MinimalUser
	return users, json.NewDecoder(res.Body).Decode(&users)
}