package codersdk

import (

"context"

"fmt"

"net/http"

"strings"

"time"

"github.com/google/uuid"

"golang.org/x/xerrors"

)

// Template is the JSON representation of a Coder template. This type matches the

// database object for now, but is abstracted for ease of change later on.

type Template 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"`

OrganizationID uuid.UUID `json:"organization_id" format:"uuid"`

OrganizationName string `json:"organization_name" format:"url"`

OrganizationDisplayName string `json:"organization_display_name"`

OrganizationIcon string `json:"organization_icon"`

Name string `json:"name"`

DisplayName string `json:"display_name"`

Provisioner ProvisionerType `json:"provisioner" enums:"terraform"`

ActiveVersionID uuid.UUID `json:"active_version_id" format:"uuid"`

// ActiveUserCount is set to -1 when loading.

ActiveUserCount int `json:"active_user_count"`

BuildTimeStats TemplateBuildTimeStats `json:"build_time_stats"`

Description string `json:"description"`

Deprecated bool `json:"deprecated"`

DeprecationMessage string `json:"deprecation_message"`

Deleted bool `json:"deleted"`

Icon string `json:"icon"`

DefaultTTLMillis int64 `json:"default_ttl_ms"`

ActivityBumpMillis int64 `json:"activity_bump_ms"`

// TimeTilAutostopNotifyMillis is the duration before the workspace's

// autostop deadline at which a reminder notification is sent. 0 disables

// the notification.

TimeTilAutostopNotifyMillis int64 `json:"time_til_autostop_notify_ms"`

// AutostopRequirement and AutostartRequirement are enterprise features. Its

// value is only used if your license is entitled to use the advanced template

// scheduling feature.

AutostopRequirement TemplateAutostopRequirement `json:"autostop_requirement"`

AutostartRequirement TemplateAutostartRequirement `json:"autostart_requirement"`

CreatedByID uuid.UUID `json:"created_by_id" format:"uuid"`

CreatedByName string `json:"created_by_name"`

// AllowUserAutostart and AllowUserAutostop are enterprise-only. Their

// values are only used if your license is entitled to use the advanced

// template scheduling feature.

AllowUserAutostart bool `json:"allow_user_autostart"`

AllowUserAutostop bool `json:"allow_user_autostop"`

AllowUserCancelWorkspaceJobs bool `json:"allow_user_cancel_workspace_jobs"`

// FailureTTLMillis, TimeTilDormantMillis, and TimeTilDormantAutoDeleteMillis are enterprise-only. Their

// values are used if your license is entitled to use the advanced

// template scheduling feature.

FailureTTLMillis int64 `json:"failure_ttl_ms"`

TimeTilDormantMillis int64 `json:"time_til_dormant_ms"`

TimeTilDormantAutoDeleteMillis int64 `json:"time_til_dormant_autodelete_ms"`

// RequireActiveVersion mandates that workspaces are built with the active

// template version.

RequireActiveVersion bool `json:"require_active_version"`

MaxPortShareLevel WorkspaceAgentPortShareLevel `json:"max_port_share_level"`

CORSBehavior CORSBehavior `json:"cors_behavior"`

UseClassicParameterFlow bool `json:"use_classic_parameter_flow"`

AgentsAllowed bool `json:"agents_allowed"`

// DisableModuleCache disables the use of cached Terraform modules during

// provisioning for this template. It is read-only while

// ModuleCacheDisabledByDeployment is true.

DisableModuleCache bool `json:"disable_module_cache"`

// ModuleCacheDisabledByDeployment reports that the deployment disables the

// Terraform module cache for every template. Templates cannot opt back in,

// so the effective state is disabled regardless of DisableModuleCache.

ModuleCacheDisabledByDeployment bool `json:"module_cache_disabled_by_deployment"`

// AllowWorkspaceRenames permits users to rename workspaces built from this

// template. Renaming can be destructive for templates whose Terraform

// references the workspace name.

AllowWorkspaceRenames bool `json:"allow_workspace_renames"`

}

// WeekdaysToBitmap converts a list of weekdays to a bitmap in accordance with

// the schedule package's rules. The 0th bit is Monday, ..., the 6th bit is

// Sunday. The 7th bit is unused.

func WeekdaysToBitmap(days []string) (uint8, error) {

var bitmap uint8

for _, day := range days {

switch strings.ToLower(day) {

case "monday":

bitmap |= 1 << 0

case "tuesday":

bitmap |= 1 << 1

case "wednesday":

bitmap |= 1 << 2

case "thursday":

bitmap |= 1 << 3

case "friday":

bitmap |= 1 << 4

case "saturday":

bitmap |= 1 << 5

case "sunday":

bitmap |= 1 << 6

default:

return 0, xerrors.Errorf("invalid weekday %q", day)

}

}

return bitmap, nil

}

// BitmapToWeekdays converts a bitmap to a list of weekdays in accordance with

// the schedule package's rules (see above).

func BitmapToWeekdays(bitmap uint8) []string {

days := []string{}

for i := 0; i < 7; i++ {

if bitmap&(1<<i) != 0 {

switch i {

case 0:

days = append(days, "monday")

case 1:

days = append(days, "tuesday")

case 2:

days = append(days, "wednesday")

case 3:

days = append(days, "thursday")

case 4:

days = append(days, "friday")

case 5:

days = append(days, "saturday")

case 6:

days = append(days, "sunday")

}

}

}

return days

}

var AllDaysOfWeek = []string{"monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"}

type TemplateAutostartRequirement struct {

// DaysOfWeek is a list of days of the week in which autostart is allowed

// to happen. If no days are specified, autostart is not allowed.

DaysOfWeek []string `json:"days_of_week" enums:"monday,tuesday,wednesday,thursday,friday,saturday,sunday"`

}

type TemplateAutostopRequirement struct {

// DaysOfWeek is a list of days of the week on which restarts are required.

// Restarts happen within the user's quiet hours (in their configured

// timezone). If no days are specified, restarts are not required. Weekdays

// cannot be specified twice.

//

// Restarts will only happen on weekdays in this list on weeks which line up

// with Weeks.

DaysOfWeek []string `json:"days_of_week" enums:"monday,tuesday,wednesday,thursday,friday,saturday,sunday"`

// Weeks is the number of weeks between required restarts. Weeks are synced

// across all workspaces (and Coder deployments) using modulo math on a

// hardcoded epoch week of January 2nd, 2023 (the first Monday of 2023).

// Values of 0 or 1 indicate weekly restarts. Values of 2 indicate

// fortnightly restarts, etc.

Weeks int64 `json:"weeks"`

}

type TransitionStats struct {

P50 *int64 `example:"123"`

P95 *int64 `example:"146"`

}

type (

TemplateBuildTimeStats map[WorkspaceTransition]TransitionStats

UpdateActiveTemplateVersion struct {

ID uuid.UUID `json:"id" validate:"required" format:"uuid"`

}

)

type ArchiveTemplateVersionsRequest struct {

// By default, only failed versions are archived. Set this to true

// to archive all unused versions regardless of job status.

All bool `json:"all"`

}

type ArchiveTemplateVersionsResponse struct {

TemplateID uuid.UUID `json:"template_id" format:"uuid"`

ArchivedIDs []uuid.UUID `json:"archived_ids"`

}

// ModuleCacheDisabled reports whether cached Terraform modules must be withheld

// from provisioner jobs. The deployment-wide setting wins: a template cannot opt

// back into the cache once the deployment disables it.

func ModuleCacheDisabled(dv *DeploymentValues, templateDisableModuleCache bool) bool {

return templateDisableModuleCache || ModuleCacheDisabledByDeployment(dv)

}

// ModuleCacheDisabledByDeployment reports whether the deployment disables the

// Terraform module cache for every template.

func ModuleCacheDisabledByDeployment(dv *DeploymentValues) bool {

return dv != nil && dv.Provisioner.DisableModuleCache.Value()

}

type TemplateRole string

const (

TemplateRoleAdmin TemplateRole = "admin"

TemplateRoleUse TemplateRole = "use"

TemplateRoleDeleted TemplateRole = ""

)

type TemplateACL struct {

Users []TemplateUser `json:"users"`

Groups []TemplateGroup `json:"group"`

}

type TemplateGroup struct {

Group

Role TemplateRole `json:"role" enums:"admin,use"`

}

type TemplateUser struct {

User

Role TemplateRole `json:"role" enums:"admin,use"`

}

type UpdateTemplateACL struct {

// UserPerms is a mapping from valid user UUIDs to the template role they

// should be granted. To remove a user from the template, use "" as the role

// (available as a constant named codersdk.TemplateRoleDeleted)

UserPerms map[string]TemplateRole `json:"user_perms,omitempty" example:"<user_id>:admin,4df59e74-c027-470b-ab4d-cbba8963a5e9:use"`

// GroupPerms is a mapping from valid group UUIDs to the template role they

// should be granted. To remove a group from the template, use "" as the role

// (available as a constant named codersdk.TemplateRoleDeleted)

GroupPerms map[string]TemplateRole `json:"group_perms,omitempty" example:"<group_id>:admin,8bd26b20-f3e8-48be-a903-46bb920cf671:use"`

}

// ACLAvailable is a list of users and groups that can be added to a resource

// ACL.

type ACLAvailable struct {

Users []ReducedUser `json:"users"`

Groups []Group `json:"groups"`

}

// UpdateTemplateMeta is the request body for the PATCH /templates/{template}

// endpoint. All fields are optional. Fields that are nil are not modified.

type UpdateTemplateMeta struct {

Name *string `json:"name,omitempty" validate:"omitempty,template_name"`

DisplayName *string `json:"display_name,omitempty" validate:"omitempty,template_display_name"`

Description *string `json:"description,omitempty"`

Icon *string `json:"icon,omitempty"`

DefaultTTLMillis *int64 `json:"default_ttl_ms,omitempty"`

// ActivityBumpMillis allows optionally specifying the activity bump

// duration for all workspaces created from this template. Defaults to 1h

// but can be set to 0 to disable activity bumping.

ActivityBumpMillis *int64 `json:"activity_bump_ms,omitempty"`

// TimeTilAutostopNotifyMillis allows optionally specifying the duration

// before the autostop deadline at which a reminder notification is sent for

// workspaces created from this template. Defaults to 0 (disabled). Omitting

// the field keeps the existing value.

TimeTilAutostopNotifyMillis *int64 `json:"time_til_autostop_notify_ms,omitempty"`

// AutostopRequirement and AutostartRequirement can only be set if your license

// includes the advanced template scheduling feature. If you attempt to set this

// value while unlicensed, it will be ignored.

AutostopRequirement *TemplateAutostopRequirement `json:"autostop_requirement,omitempty"`

AutostartRequirement *TemplateAutostartRequirement `json:"autostart_requirement,omitempty"`

AllowUserAutostart *bool `json:"allow_user_autostart,omitempty"`

AllowUserAutostop *bool `json:"allow_user_autostop,omitempty"`

AllowUserCancelWorkspaceJobs *bool `json:"allow_user_cancel_workspace_jobs,omitempty"`

FailureTTLMillis *int64 `json:"failure_ttl_ms,omitempty"`

TimeTilDormantMillis *int64 `json:"time_til_dormant_ms,omitempty"`

TimeTilDormantAutoDeleteMillis *int64 `json:"time_til_dormant_autodelete_ms,omitempty"`

// UpdateWorkspaceLastUsedAt updates the last_used_at field of workspaces

// spawned from the template. This is useful for preventing workspaces being

// immediately locked when updating the inactivity_ttl field to a new, shorter

// value.

UpdateWorkspaceLastUsedAt *bool `json:"update_workspace_last_used_at,omitempty"`

// UpdateWorkspaceDormantAt updates the dormant_at field of workspaces spawned

// from the template. This is useful for preventing dormant workspaces being

// immediately deleted when updating the dormant_ttl field to a new, shorter

// value.

UpdateWorkspaceDormantAt *bool `json:"update_workspace_dormant_at,omitempty"`

// RequireActiveVersion mandates workspaces built using this template

// use the active version of the template. This option has no

// effect on template admins.

RequireActiveVersion *bool `json:"require_active_version,omitempty"`

// DeprecationMessage if set, will mark the template as deprecated and block

// any new workspaces from using this template.

// If passed an empty string, will remove the deprecated message, making

// the template usable for new workspaces again.

DeprecationMessage *string `json:"deprecation_message,omitempty"`

// DisableEveryoneGroupAccess allows optionally disabling the default

// behavior of granting the 'everyone' group access to use the template.

// If this is set to true, the template will not be available to all users,

// and must be explicitly granted to users or groups in the permissions settings

// of the template.

DisableEveryoneGroupAccess *bool `json:"disable_everyone_group_access,omitempty"`

MaxPortShareLevel *WorkspaceAgentPortShareLevel `json:"max_port_share_level,omitempty"`

CORSBehavior *CORSBehavior `json:"cors_behavior,omitempty"`

// UseClassicParameterFlow is a flag that switches the default behavior to use the classic

// parameter flow when creating a workspace. This only affects deployments with the experiment

// "dynamic-parameters" enabled. This setting will live for a period after the experiment is

// made the default.

// An "opt-out" is present in case the new feature breaks some existing templates.

UseClassicParameterFlow *bool `json:"use_classic_parameter_flow,omitempty"`

// DisableModuleCache disables the using of cached Terraform modules during

// provisioning. It is ignored while the deployment disables the module

// cache for all templates. It is recommended not to disable this.

DisableModuleCache *bool `json:"disable_module_cache,omitempty"`

// AgentsAllowed controls whether Coder Agents can create workspaces using

// this template. If omitted, the current value is preserved.

AgentsAllowed *bool `json:"agents_allowed,omitempty"`

// AllowWorkspaceRenames permits users to rename workspaces built from this

// template. Renaming can be destructive for templates whose Terraform

// references the workspace name.

AllowWorkspaceRenames *bool `json:"allow_workspace_renames,omitempty"`

}

type TemplateExample struct {

ID string `json:"id" format:"uuid"`

URL string `json:"url"`

Name string `json:"name"`

Description string `json:"description"`

Icon string `json:"icon"`

Tags []string `json:"tags"`

Markdown string `json:"markdown"`

}

// Template returns a single template.

func (c *Client) Template(ctx context.Context, template uuid.UUID) (Template, error) {

res, err := c.Request(ctx, http.MethodGet, fmt.Sprintf("/api/v2/templates/%s", template), nil)

if err != nil {

return Template{}, xerrors.Errorf("do request: %w", err)

}

defer res.Body.Close()

if res.StatusCode != http.StatusOK {

return Template{}, ReadBodyAsError(res)

}

var resp Template

return resp, ReadBodyAsJSON(res, &resp)

}

func (c *Client) ArchiveTemplateVersions(ctx context.Context, template uuid.UUID, all bool) (ArchiveTemplateVersionsResponse, error) {

res, err := c.Request(ctx, http.MethodPost,

fmt.Sprintf("/api/v2/templates/%s/versions/archive", template),

ArchiveTemplateVersionsRequest{

All: all,

},

)

if err != nil {

return ArchiveTemplateVersionsResponse{}, err

}

defer res.Body.Close()

if res.StatusCode != http.StatusOK {

return ArchiveTemplateVersionsResponse{}, ReadBodyAsError(res)

}

var resp ArchiveTemplateVersionsResponse

return resp, ReadBodyAsJSON(res, &resp)

}

//nolint:revive

func (c *Client) SetArchiveTemplateVersion(ctx context.Context, templateVersion uuid.UUID, archive bool) error {

u := fmt.Sprintf("/api/v2/templateversions/%s", templateVersion.String())

if archive {

u += "/archive"

} else {

u += "/unarchive"

}

res, err := c.Request(ctx, http.MethodPost, u, nil)

if err != nil {

return err

}

defer res.Body.Close()

if res.StatusCode != http.StatusOK {

return ReadBodyAsError(res)

}

return nil

}

func (c *Client) DeleteTemplate(ctx context.Context, template uuid.UUID) error {

res, err := c.Request(ctx, http.MethodDelete, fmt.Sprintf("/api/v2/templates/%s", template), nil)

if err != nil {

return err

}

defer res.Body.Close()

if res.StatusCode != http.StatusOK {

return ReadBodyAsError(res)

}

return nil

}

func (c *Client) UpdateTemplateMeta(ctx context.Context, templateID uuid.UUID, req UpdateTemplateMeta) (Template, error) {

res, err := c.Request(ctx, http.MethodPatch, fmt.Sprintf("/api/v2/templates/%s", templateID), req)

if err != nil {

return Template{}, err

}

defer res.Body.Close()

if res.StatusCode != http.StatusOK {

return Template{}, ReadBodyAsError(res)

}

var updated Template

return updated, ReadBodyAsJSON(res, &updated)

}

func (c *Client) UpdateTemplateACL(ctx context.Context, templateID uuid.UUID, req UpdateTemplateACL) error {

res, err := c.Request(ctx, http.MethodPatch, fmt.Sprintf("/api/v2/templates/%s/acl", templateID), req)

if err != nil {

return err

}

defer res.Body.Close()

if res.StatusCode != http.StatusOK {

return ReadBodyAsError(res)

}

return nil

}

// TemplateACLAvailable returns available users + groups that can be assigned

// template perms. The optional req controls the q/limit/offset query

// parameters applied server-side; pass codersdk.UsersRequest{} when no

// filtering is desired.

func (c *Client) TemplateACLAvailable(ctx context.Context, templateID uuid.UUID, req UsersRequest) (ACLAvailable, error) {

res, err := c.Request(

ctx,

http.MethodGet,

fmt.Sprintf("/api/v2/templates/%s/acl/available", templateID),

nil,

req.Pagination.asRequestOption(),

req.asRequestOption(),

)

if err != nil {

return ACLAvailable{}, err

}

defer res.Body.Close()

if res.StatusCode != http.StatusOK {

return ACLAvailable{}, ReadBodyAsError(res)

}

var acl ACLAvailable

return acl, ReadBodyAsJSON(res, &acl)

}

func (c *Client) TemplateACL(ctx context.Context, templateID uuid.UUID) (TemplateACL, error) {

res, err := c.Request(ctx, http.MethodGet, fmt.Sprintf("/api/v2/templates/%s/acl", templateID), nil)

if err != nil {

return TemplateACL{}, err

}

defer res.Body.Close()

if res.StatusCode != http.StatusOK {

return TemplateACL{}, ReadBodyAsError(res)

}

var acl TemplateACL

return acl, ReadBodyAsJSON(res, &acl)

}

// UpdateActiveTemplateVersion updates the active template version to the ID provided.

// The template version must be attached to the template.

func (c *Client) UpdateActiveTemplateVersion(ctx context.Context, template uuid.UUID, req UpdateActiveTemplateVersion) error {

res, err := c.Request(ctx, http.MethodPatch, fmt.Sprintf("/api/v2/templates/%s/versions", template), req)

if err != nil {

return nil

}

defer res.Body.Close()

if res.StatusCode != http.StatusOK {

return ReadBodyAsError(res)

}

return nil

}

// TemplateVersionsByTemplateRequest defines the request parameters for

// TemplateVersionsByTemplate.

type TemplateVersionsByTemplateRequest struct {

TemplateID uuid.UUID `json:"template_id" validate:"required" format:"uuid"`

IncludeArchived bool `json:"include_archived"`

Pagination

}

// TemplateVersionsByTemplate lists versions associated with a template.

func (c *Client) TemplateVersionsByTemplate(ctx context.Context, req TemplateVersionsByTemplateRequest) ([]TemplateVersion, error) {

u := fmt.Sprintf("/api/v2/templates/%s/versions", req.TemplateID)

if req.IncludeArchived {

u += "?include_archived=true"

}

res, err := c.Request(ctx, http.MethodGet, u, nil, req.asRequestOption())

if err != nil {

return nil, err

}

defer res.Body.Close()

if res.StatusCode != http.StatusOK {

return nil, ReadBodyAsError(res)

}

var templateVersion []TemplateVersion

return templateVersion, ReadBodyAsJSON(res, &templateVersion)

}

// TemplateVersionByName returns a template version by it's friendly name.

// This is used for path-based routing. Like: /templates/example/versions/helloworld

func (c *Client) TemplateVersionByName(ctx context.Context, template uuid.UUID, name string) (TemplateVersion, error) {

res, err := c.Request(ctx, http.MethodGet, fmt.Sprintf("/api/v2/templates/%s/versions/%s", template, name), nil)

if err != nil {

return TemplateVersion{}, err

}

defer res.Body.Close()

if res.StatusCode != http.StatusOK {

return TemplateVersion{}, ReadBodyAsError(res)

}

var templateVersion TemplateVersion

return templateVersion, ReadBodyAsJSON(res, &templateVersion)

}

func (c *Client) TemplateDAUsLocalTZ(ctx context.Context, templateID uuid.UUID) (*DAUsResponse, error) {

return c.TemplateDAUs(ctx, templateID, TimezoneOffsetHour(time.Local))

}

// TemplateDAUs requires a tzOffset in hours. Use 0 for UTC, and TimezoneOffsetHour(time.Local) for the

// local timezone.

func (c *Client) TemplateDAUs(ctx context.Context, templateID uuid.UUID, tzOffset int) (*DAUsResponse, error) {

res, err := c.Request(ctx, http.MethodGet, fmt.Sprintf("/api/v2/templates/%s/daus", templateID), nil, DAURequest{

TZHourOffset: tzOffset,

}.asRequestOption())

if err != nil {

return nil, xerrors.Errorf("execute request: %w", err)

}

defer res.Body.Close()

if res.StatusCode != http.StatusOK {

return nil, ReadBodyAsError(res)

}

var resp DAUsResponse

return &resp, ReadBodyAsJSON(res, &resp)

}

// AgentStatsReportRequest is a WebSocket request by coderd

// to the agent for stats.

// @typescript-ignore AgentStatsReportRequest

type AgentStatsReportRequest struct{}

// AgentStatsReportResponse is returned for each report

// request by the agent.

type AgentStatsReportResponse struct {

NumConns int64 `json:"num_comms"`

// RxBytes is the number of received bytes.

RxBytes int64 `json:"rx_bytes"`

// TxBytes is the number of transmitted bytes.

TxBytes int64 `json:"tx_bytes"`

}

// TemplateExamples lists example templates available in Coder.

//

// Deprecated: Use StarterTemplates instead.

func (c *Client) TemplateExamples(ctx context.Context, _ uuid.UUID) ([]TemplateExample, error) {

return c.StarterTemplates(ctx)

}

// StarterTemplates lists example templates available in Coder.

func (c *Client) StarterTemplates(ctx context.Context) ([]TemplateExample, error) {

res, err := c.Request(ctx, http.MethodGet, "/api/v2/templates/examples", nil)

if err != nil {

return nil, err

}

defer res.Body.Close()

if res.StatusCode != http.StatusOK {

return nil, ReadBodyAsError(res)

}

var templateExamples []TemplateExample

return templateExamples, ReadBodyAsJSON(res, &templateExamples)

}

type InvalidatePresetsResponse struct {

Invalidated []InvalidatedPreset `json:"invalidated"`

}

type InvalidatedPreset struct {

TemplateName string `json:"template_name"`

TemplateVersionName string `json:"template_version_name"`

PresetName string `json:"preset_name"`

}

// InvalidateTemplatePresets invalidates all presets for the

// template's active version by setting last_invalidated_at timestamp.

// The reconciler will then mark these prebuilds as expired and create new ones.

func (c *Client) InvalidateTemplatePresets(ctx context.Context, template uuid.UUID) (InvalidatePresetsResponse, error) {

res, err := c.Request(ctx, http.MethodPost,

fmt.Sprintf("/api/v2/templates/%s/prebuilds/invalidate", template),

nil,

)

if err != nil {

return InvalidatePresetsResponse{}, err

}

defer res.Body.Close()

if res.StatusCode != http.StatusOK {

return InvalidatePresetsResponse{}, ReadBodyAsError(res)

}

var response InvalidatePresetsResponse

return response, ReadBodyAsJSON(res, &response)

}