2023-08-09 13:00:25 +02:00
package cli
import (
2026-02-26 14:34:30 +01:00
"encoding/json"
2023-08-09 13:00:25 +02:00
"fmt"
2023-11-06 13:44:39 +00:00
"strings"
2023-08-09 13:00:25 +02:00
"golang.org/x/xerrors"
2023-08-18 13:55:43 -05:00
"github.com/coder/coder/v2/cli/cliui"
2023-11-06 13:44:39 +00:00
"github.com/coder/coder/v2/cli/cliutil/levenshtein"
2023-08-18 13:55:43 -05:00
"github.com/coder/coder/v2/codersdk"
2023-11-06 13:44:39 +00:00
"github.com/coder/pretty"
2024-03-15 11:24:38 -05:00
"github.com/coder/serpent"
2023-08-09 13:00:25 +02:00
)
type WorkspaceCLIAction int
const (
WorkspaceCreate WorkspaceCLIAction = iota
WorkspaceStart
WorkspaceUpdate
WorkspaceRestart
)
type ParameterResolver struct {
2023-11-09 19:22:47 +01:00
lastBuildParameters [] codersdk . WorkspaceBuildParameter
sourceWorkspaceParameters [] codersdk . WorkspaceBuildParameter
2023-08-09 13:00:25 +02:00
2025-07-28 14:46:04 +01:00
presetParameters [] codersdk . WorkspaceBuildParameter
2024-04-29 11:23:54 -07:00
richParameters [] codersdk . WorkspaceBuildParameter
richParametersDefaults map [ string ] string
richParametersFile map [ string ] string
2024-10-16 23:54:12 +02:00
ephemeralParameters [] codersdk . WorkspaceBuildParameter
2023-08-09 13:00:25 +02:00
2024-10-16 23:54:12 +02:00
promptRichParameters bool
promptEphemeralParameters bool
2026-01-16 18:04:57 -08:00
useParameterDefaults bool
2023-08-09 13:00:25 +02:00
}
func ( pr * ParameterResolver ) WithLastBuildParameters ( params [] codersdk . WorkspaceBuildParameter ) * ParameterResolver {
pr . lastBuildParameters = params
return pr
}
2023-11-09 19:22:47 +01:00
func ( pr * ParameterResolver ) WithSourceWorkspaceParameters ( params [] codersdk . WorkspaceBuildParameter ) * ParameterResolver {
pr . sourceWorkspaceParameters = params
return pr
}
2025-07-28 14:46:04 +01:00
func ( pr * ParameterResolver ) WithPresetParameters ( params [] codersdk . WorkspaceBuildParameter ) * ParameterResolver {
pr . presetParameters = params
return pr
}
2023-08-09 13:00:25 +02:00
func ( pr * ParameterResolver ) WithRichParameters ( params [] codersdk . WorkspaceBuildParameter ) * ParameterResolver {
pr . richParameters = params
return pr
}
2024-10-16 23:54:12 +02:00
func ( pr * ParameterResolver ) WithEphemeralParameters ( params [] codersdk . WorkspaceBuildParameter ) * ParameterResolver {
pr . ephemeralParameters = params
2023-08-09 13:00:25 +02:00
return pr
}
func ( pr * ParameterResolver ) WithRichParametersFile ( fileMap map [ string ] string ) * ParameterResolver {
pr . richParametersFile = fileMap
return pr
}
2024-04-29 11:23:54 -07:00
func ( pr * ParameterResolver ) WithRichParametersDefaults ( params [] codersdk . WorkspaceBuildParameter ) * ParameterResolver {
if pr . richParametersDefaults == nil {
pr . richParametersDefaults = make ( map [ string ] string )
}
for _ , p := range params {
pr . richParametersDefaults [ p . Name ] = p . Value
}
return pr
}
2023-08-09 13:00:25 +02:00
func ( pr * ParameterResolver ) WithPromptRichParameters ( promptRichParameters bool ) * ParameterResolver {
pr . promptRichParameters = promptRichParameters
return pr
}
2024-10-16 23:54:12 +02:00
func ( pr * ParameterResolver ) WithPromptEphemeralParameters ( promptEphemeralParameters bool ) * ParameterResolver {
pr . promptEphemeralParameters = promptEphemeralParameters
2023-08-09 13:00:25 +02:00
return pr
}
2026-01-16 18:04:57 -08:00
func ( pr * ParameterResolver ) WithUseParameterDefaults ( useParameterDefaults bool ) * ParameterResolver {
pr . useParameterDefaults = useParameterDefaults
return pr
}
// Resolve gathers workspace build parameters in a layered fashion, applying
// values from various sources in order of precedence:
// 1. template defaults (if auto-accepting defaults)
// 2. cli parameter defaults (if auto-accepting defaults)
// 3. parameter file
// 4. CLI/ENV
// 5. source build
// 6. last build
// 7. preset
// 8. user input (unless auto-accepting defaults)
2024-03-15 11:24:38 -05:00
func ( pr * ParameterResolver ) Resolve ( inv * serpent . Invocation , action WorkspaceCLIAction , templateVersionParameters [] codersdk . TemplateVersionParameter ) ([] codersdk . WorkspaceBuildParameter , error ) {
2023-08-09 13:00:25 +02:00
var staged [] codersdk . WorkspaceBuildParameter
var err error
staged = pr . resolveWithParametersMapFile ( staged )
staged = pr . resolveWithCommandLineOrEnv ( staged )
2026-02-03 14:10:49 -06:00
staged = pr . resolveWithSourceBuildParametersInParameters ( staged , templateVersionParameters )
staged = pr . resolveWithLastBuildParametersInParameters ( staged , templateVersionParameters )
2025-07-28 14:46:04 +01:00
staged = pr . resolveWithPreset ( staged ) // Preset parameters take precedence from all other parameters
2023-08-09 13:00:25 +02:00
if err = pr . verifyConstraints ( staged , action , templateVersionParameters ); err != nil {
return nil , err
}
if staged , err = pr . resolveWithInput ( staged , inv , action , templateVersionParameters ); err != nil {
return nil , err
}
return staged , nil
}
2026-02-03 14:10:49 -06:00
func ( pr * ParameterResolver ) InitialValues () [] codersdk . WorkspaceBuildParameter {
var staged [] codersdk . WorkspaceBuildParameter
staged = pr . resolveWithParametersMapFile ( staged )
staged = pr . resolveWithCommandLineOrEnv ( staged )
staged = pr . resolveWithSourceBuildParameters ( staged )
staged = pr . resolveWithLastBuildParameters ( staged )
staged = pr . resolveWithPreset ( staged ) // Preset parameters take precedence from all other parameters
return staged
}
2025-07-28 14:46:04 +01:00
func ( pr * ParameterResolver ) resolveWithPreset ( resolved [] codersdk . WorkspaceBuildParameter ) [] codersdk . WorkspaceBuildParameter {
next :
for _ , presetParameter := range pr . presetParameters {
for i , r := range resolved {
if r . Name == presetParameter . Name {
resolved [ i ]. Value = presetParameter . Value
continue next
}
}
resolved = append ( resolved , presetParameter )
}
return resolved
}
2023-08-09 13:00:25 +02:00
func ( pr * ParameterResolver ) resolveWithParametersMapFile ( resolved [] codersdk . WorkspaceBuildParameter ) [] codersdk . WorkspaceBuildParameter {
2023-08-10 12:08:00 +02:00
next :
2023-08-09 13:00:25 +02:00
for name , value := range pr . richParametersFile {
for i , r := range resolved {
if r . Name == name {
resolved [ i ]. Value = value
2023-08-10 12:08:00 +02:00
continue next
2023-08-09 13:00:25 +02:00
}
}
resolved = append ( resolved , codersdk . WorkspaceBuildParameter {
Name : name ,
Value : value ,
})
}
return resolved
}
func ( pr * ParameterResolver ) resolveWithCommandLineOrEnv ( resolved [] codersdk . WorkspaceBuildParameter ) [] codersdk . WorkspaceBuildParameter {
2023-08-10 12:08:00 +02:00
nextRichParameter :
2023-08-09 13:00:25 +02:00
for _ , richParameter := range pr . richParameters {
for i , r := range resolved {
if r . Name == richParameter . Name {
resolved [ i ]. Value = richParameter . Value
2023-08-10 12:08:00 +02:00
continue nextRichParameter
2023-08-09 13:00:25 +02:00
}
}
resolved = append ( resolved , richParameter )
}
2024-10-16 23:54:12 +02:00
nextEphemeralParameter :
for _ , ephemeralParameter := range pr . ephemeralParameters {
2023-08-09 13:00:25 +02:00
for i , r := range resolved {
2024-10-16 23:54:12 +02:00
if r . Name == ephemeralParameter . Name {
resolved [ i ]. Value = ephemeralParameter . Value
continue nextEphemeralParameter
2023-08-09 13:00:25 +02:00
}
}
2024-10-16 23:54:12 +02:00
resolved = append ( resolved , ephemeralParameter )
2023-08-09 13:00:25 +02:00
}
return resolved
}
2026-02-03 14:10:49 -06:00
func ( pr * ParameterResolver ) resolveWithLastBuildParameters ( resolved [] codersdk . WorkspaceBuildParameter ) [] codersdk . WorkspaceBuildParameter {
if pr . promptRichParameters {
return resolved // don't pull parameters from last build
}
next :
for _ , buildParameter := range pr . lastBuildParameters {
for i , r := range resolved {
if r . Name == buildParameter . Name {
resolved [ i ]. Value = buildParameter . Value
continue next
}
}
resolved = append ( resolved , buildParameter )
}
return resolved
}
func ( pr * ParameterResolver ) resolveWithLastBuildParametersInParameters ( resolved [] codersdk . WorkspaceBuildParameter , templateVersionParameters [] codersdk . TemplateVersionParameter ) [] codersdk . WorkspaceBuildParameter {
2023-08-09 13:00:25 +02:00
if pr . promptRichParameters {
return resolved // don't pull parameters from last build
}
2023-08-10 12:08:00 +02:00
next :
2023-08-09 13:00:25 +02:00
for _ , buildParameter := range pr . lastBuildParameters {
tvp := findTemplateVersionParameter ( buildParameter , templateVersionParameters )
if tvp == nil {
continue // it looks like this parameter is not present anymore
}
if tvp . Ephemeral {
continue // ephemeral parameters should not be passed to consecutive builds
}
if ! tvp . Mutable {
continue // immutables should not be passed to consecutive builds
}
2026-02-26 14:34:30 +01:00
if len ( tvp . Options ) > 0 && ! isValidTemplateParameterOption ( buildParameter , * tvp ) {
2023-08-23 18:18:38 +02:00
continue // do not propagate invalid options
}
2023-08-09 13:00:25 +02:00
for i , r := range resolved {
if r . Name == buildParameter . Name {
resolved [ i ]. Value = buildParameter . Value
2023-08-10 12:08:00 +02:00
continue next
2023-08-09 13:00:25 +02:00
}
}
resolved = append ( resolved , buildParameter )
}
return resolved
}
2026-02-03 14:10:49 -06:00
func ( pr * ParameterResolver ) resolveWithSourceBuildParameters ( resolved [] codersdk . WorkspaceBuildParameter ) [] codersdk . WorkspaceBuildParameter {
next :
for _ , buildParameter := range pr . sourceWorkspaceParameters {
for i , r := range resolved {
if r . Name == buildParameter . Name {
resolved [ i ]. Value = buildParameter . Value
continue next
}
}
resolved = append ( resolved , buildParameter )
}
return resolved
}
func ( pr * ParameterResolver ) resolveWithSourceBuildParametersInParameters ( resolved [] codersdk . WorkspaceBuildParameter , templateVersionParameters [] codersdk . TemplateVersionParameter ) [] codersdk . WorkspaceBuildParameter {
2023-11-09 19:22:47 +01:00
next :
for _ , buildParameter := range pr . sourceWorkspaceParameters {
tvp := findTemplateVersionParameter ( buildParameter , templateVersionParameters )
if tvp == nil {
continue // it looks like this parameter is not present anymore
}
if tvp . Ephemeral {
continue // ephemeral parameters should not be passed to consecutive builds
}
for i , r := range resolved {
if r . Name == buildParameter . Name {
resolved [ i ]. Value = buildParameter . Value
continue next
}
}
resolved = append ( resolved , buildParameter )
}
return resolved
}
2023-08-09 13:00:25 +02:00
func ( pr * ParameterResolver ) verifyConstraints ( resolved [] codersdk . WorkspaceBuildParameter , action WorkspaceCLIAction , templateVersionParameters [] codersdk . TemplateVersionParameter ) error {
for _ , r := range resolved {
tvp := findTemplateVersionParameter ( r , templateVersionParameters )
if tvp == nil {
2023-11-06 13:44:39 +00:00
return templateVersionParametersNotFound ( r . Name , templateVersionParameters )
2023-08-09 13:00:25 +02:00
}
2024-10-16 23:54:12 +02:00
if tvp . Ephemeral && ! pr . promptEphemeralParameters && findWorkspaceBuildParameter ( tvp . Name , pr . ephemeralParameters ) == nil {
return xerrors . Errorf ( "ephemeral parameter %q can be used only with --prompt-ephemeral-parameters or --ephemeral-parameter flag" , r . Name )
2023-08-09 13:00:25 +02:00
}
2026-02-24 09:15:02 +01:00
if ! tvp . Mutable && action != WorkspaceCreate && ! pr . isFirstTimeUse ( r . Name ) {
2023-08-09 13:00:25 +02:00
return xerrors . Errorf ( "parameter %q is immutable and cannot be updated" , r . Name )
}
}
return nil
}
2024-03-15 11:24:38 -05:00
func ( pr * ParameterResolver ) resolveWithInput ( resolved [] codersdk . WorkspaceBuildParameter , inv * serpent . Invocation , action WorkspaceCLIAction , templateVersionParameters [] codersdk . TemplateVersionParameter ) ([] codersdk . WorkspaceBuildParameter , error ) {
2023-08-09 13:00:25 +02:00
for _ , tvp := range templateVersionParameters {
2023-08-10 12:08:00 +02:00
p := findWorkspaceBuildParameter ( tvp . Name , resolved )
2023-08-09 13:00:25 +02:00
if p != nil {
continue
}
2025-05-20 10:45:12 -05:00
// PreviewParameter has not been resolved yet, so CLI needs to determine if user should input it.
2023-08-09 13:00:25 +02:00
2023-08-10 12:08:00 +02:00
firstTimeUse := pr . isFirstTimeUse ( tvp . Name )
2023-08-23 18:18:38 +02:00
promptParameterOption := pr . isLastBuildParameterInvalidOption ( tvp )
2023-08-09 13:00:25 +02:00
2024-10-16 23:54:12 +02:00
if ( tvp . Ephemeral && pr . promptEphemeralParameters ) ||
2023-08-18 14:06:46 +02:00
( action == WorkspaceCreate && tvp . Required ) ||
( action == WorkspaceCreate && ! tvp . Ephemeral ) ||
2023-08-23 18:18:38 +02:00
( action == WorkspaceUpdate && promptParameterOption ) ||
2023-08-23 12:46:52 +02:00
( action == WorkspaceUpdate && tvp . Mutable && tvp . Required ) ||
2023-08-09 13:00:25 +02:00
( action == WorkspaceUpdate && ! tvp . Mutable && firstTimeUse ) ||
2023-11-02 14:41:34 -05:00
( tvp . Mutable && ! tvp . Ephemeral && pr . promptRichParameters ) {
2026-01-16 18:04:57 -08:00
name := tvp . Name
if tvp . DisplayName != "" {
name = tvp . DisplayName
}
parameterValue := tvp . DefaultValue
if v , ok := pr . richParametersDefaults [ tvp . Name ]; ok {
parameterValue = v
}
// Auto-accept the default if there is one.
if pr . useParameterDefaults && parameterValue != "" {
_ , _ = fmt . Fprintf ( inv . Stdout , "Using default value for %s: '%s'\n" , name , parameterValue )
} else {
var err error
parameterValue , err = cliui . RichParameter ( inv , tvp , name , parameterValue )
if err != nil {
return nil , err
}
2023-08-09 13:00:25 +02:00
}
resolved = append ( resolved , codersdk . WorkspaceBuildParameter {
Name : tvp . Name ,
Value : parameterValue ,
})
} else if action == WorkspaceUpdate && ! tvp . Mutable && ! firstTimeUse {
2023-09-07 17:28:22 -04:00
_ , _ = fmt . Fprintln ( inv . Stdout , pretty . Sprint ( cliui . DefaultStyles . Warn , fmt . Sprintf ( "Parameter %q is not mutable, and cannot be customized after workspace creation." , tvp . Name )))
2023-08-09 13:00:25 +02:00
}
}
return resolved , nil
}
2023-08-10 12:08:00 +02:00
func ( pr * ParameterResolver ) isFirstTimeUse ( parameterName string ) bool {
return findWorkspaceBuildParameter ( parameterName , pr . lastBuildParameters ) == nil
2023-08-09 13:00:25 +02:00
}
2023-08-23 18:18:38 +02:00
func ( pr * ParameterResolver ) isLastBuildParameterInvalidOption ( templateVersionParameter codersdk . TemplateVersionParameter ) bool {
if len ( templateVersionParameter . Options ) == 0 {
return false
}
for _ , buildParameter := range pr . lastBuildParameters {
if buildParameter . Name == templateVersionParameter . Name {
2026-02-26 14:34:30 +01:00
return ! isValidTemplateParameterOption ( buildParameter , templateVersionParameter )
2023-08-23 18:18:38 +02:00
}
}
return false
}
2023-08-09 13:00:25 +02:00
func findTemplateVersionParameter ( workspaceBuildParameter codersdk . WorkspaceBuildParameter , templateVersionParameters [] codersdk . TemplateVersionParameter ) * codersdk . TemplateVersionParameter {
for _ , tvp := range templateVersionParameters {
if tvp . Name == workspaceBuildParameter . Name {
return & tvp
}
}
return nil
}
2023-08-10 12:08:00 +02:00
func findWorkspaceBuildParameter ( parameterName string , params [] codersdk . WorkspaceBuildParameter ) * codersdk . WorkspaceBuildParameter {
2023-08-09 13:00:25 +02:00
for _ , p := range params {
2023-08-10 12:08:00 +02:00
if p . Name == parameterName {
2023-08-09 13:00:25 +02:00
return & p
}
}
return nil
}
2023-08-23 18:18:38 +02:00
2026-02-26 14:34:30 +01:00
func isValidTemplateParameterOption ( buildParameter codersdk . WorkspaceBuildParameter , templateVersionParameter codersdk . TemplateVersionParameter ) bool {
// Multi-select parameters store values as a JSON array (e.g.
// '["vim","emacs"]'), so we need to parse the array and validate
// each element individually against the allowed options.
if templateVersionParameter . Type == "list(string)" {
var values [] string
if err := json . Unmarshal ([] byte ( buildParameter . Value ), & values ); err != nil {
return false
}
for _ , v := range values {
found := false
for _ , opt := range templateVersionParameter . Options {
if opt . Value == v {
found = true
break
}
}
if ! found {
return false
}
}
return true
}
for _ , opt := range templateVersionParameter . Options {
2023-08-23 18:18:38 +02:00
if opt . Value == buildParameter . Value {
return true
}
}
return false
}
2023-11-06 13:44:39 +00:00
func templateVersionParametersNotFound ( unknown string , params [] codersdk . TemplateVersionParameter ) error {
var sb strings . Builder
_ , _ = sb . WriteString ( fmt . Sprintf ( "parameter %q is not present in the template." , unknown ))
// Going with a fairly generous edit distance
maxDist := len ( unknown ) / 2
var paramNames [] string
for _ , p := range params {
paramNames = append ( paramNames , p . Name )
}
matches := levenshtein . Matches ( unknown , maxDist , paramNames ... )
if len ( matches ) > 0 {
_ , _ = sb . WriteString ( fmt . Sprintf ( "\nDid you mean: %s" , strings . Join ( matches , ", " )))
}
return xerrors . Errorf ( sb . String ())
}