Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

### Fixed

- **features** — a feature option declared as a string (or untyped) that
is given a non-string value is converted the way the reference CLI
converts it, instead of failing with `option "packages" expects
string, got []interface {}`. Arrays join with `,` (`["jq","tree"]` →
`jq,tree`), numbers, booleans and `null` take their JavaScript string
form, and a `config.WarnFeatureOptionCoerced` warning is reported.
Objects are still rejected. A boolean option given the string
`"true"` or `"false"` takes that boolean (the reference CLI writes
both forms identically) with the same warning; any other non-boolean
still errors. Non-string defaults and undeclared options are
converted too, so `feature.env` never carries Go formatting such as
`[jq tree]`.
- **engine** — `Up` and `Build` called without `ConfigPath` now use the
discovered `devcontainer.json`'s directory for local features and the
compose working directory. Previously they always assumed
Expand Down
1 change: 1 addition & 0 deletions config/resolved.go
Original file line number Diff line number Diff line change
Expand Up @@ -414,6 +414,7 @@ const (
WarnUnknownVariable WarningCode = "unknown_variable"
WarnDeepFeatureChain WarningCode = "deep_feature_chain"
WarnUnknownFeatureOption WarningCode = "unknown_feature_option"
WarnFeatureOptionCoerced WarningCode = "feature_option_coerced"
WarnComposePortsIgnored WarningCode = "compose_ports_ignored"
WarnUIDReconcileSkipped WarningCode = "uid_reconcile_skipped"
)
Expand Down
163 changes: 146 additions & 17 deletions feature/options.go
Original file line number Diff line number Diff line change
@@ -1,9 +1,12 @@
package feature

import (
"encoding/json"
"fmt"
"math"
"regexp"
"sort"
"strconv"
"strings"

"github.com/crunchloop/devcontainer/config"
Expand All @@ -14,65 +17,191 @@ import (
//
// Order of precedence (later wins): defaults → user. Keys not declared
// in the feature's options are kept (some features accept arbitrary
// extras) but emit WarnUnknownFeatureOption. Enum-typed options are
// extras), converted to strings when they can be, and emit
// WarnUnknownFeatureOption. Enum-typed options are
// hard-validated; values outside the enum produce an error. Proposals
// (soft constraints) do not validate.
//
// A string-typed (or untyped) option given a non-string value is
// converted the way the reference CLI converts it (see
// coerceOptionString) and emits WarnFeatureOptionCoerced; only an
// object is rejected. A boolean-typed option accepts the strings
// "true" and "false" as the booleans (also with
// WarnFeatureOptionCoerced) and rejects any other non-boolean.
//
// Returns the merged map and any non-fatal warnings. Errors are
// validation failures (enum mismatch, type mismatch on declared options).
func MergeOptions(meta config.FeatureMetadata, user map[string]any) (map[string]any, []config.Warning, error) {
out := make(map[string]any, len(meta.Options)+len(user))
var warnings []config.Warning

// Start with defaults from the feature's declared options.
// Start with defaults from the feature's declared options. A
// non-string default of a string option is converted too, so the
// env file never carries Go's formatting of it.
for name, opt := range meta.Options {
if opt.Default != nil {
out[name] = opt.Default
if opt.Default == nil {
continue
}
out[name] = opt.Default
if isStringOption(opt) {
if s, ok := coerceOptionString(opt.Default); ok {
out[name] = s
}
}
}

// Overlay user values, validating against declarations.
for name, val := range user {
decl, declared := meta.Options[name]
if !declared {
// The reference CLI writes undeclared options to the env
// file too; convert them the same way when it can.
out[name] = val
if s, ok := coerceOptionString(val); ok {
out[name] = s
}
warnings = append(warnings, config.Warning{
Code: config.WarnUnknownFeatureOption,
Message: fmt.Sprintf("feature %q: option %q is not declared in devcontainer-feature.json", meta.ID, name),
})
continue
}
if err := validateOptionValue(name, decl, val); err != nil {
v, converted, err := validateOptionValue(name, decl, val)
if err != nil {
return nil, warnings, fmt.Errorf("feature %q: %w", meta.ID, err)
}
out[name] = val
if converted {
want := decl.Type
if want == "" {
want = "string"
}
warnings = append(warnings, config.Warning{
Code: config.WarnFeatureOptionCoerced,
Message: fmt.Sprintf("feature %q: option %q expects a %s; %T value converted to %#v", meta.ID, name, want, val, v),
})
}
out[name] = v
}

return out, warnings, nil
}

func validateOptionValue(name string, opt config.FeatureOption, val any) error {
func isStringOption(opt config.FeatureOption) bool {
return opt.Type == "string" || opt.Type == ""
}

// validateOptionValue checks val against opt and returns the value to
// install with: val itself, or for a string option its string form,
// or for a boolean option given the string "true" or "false" that
// boolean. converted reports whether the returned value differs in
// type from val.
func validateOptionValue(name string, opt config.FeatureOption, val any) (v any, converted bool, err error) {
switch {
case isStringOption(opt):
s, ok := coerceOptionString(val)
if !ok {
return nil, false, fmt.Errorf("option %q expects string, got %T", name, val)
}
_, wasString := val.(string)
val, converted = s, !wasString
case opt.Type == "boolean":
// The reference CLI writes "true" and true identically
// (TRUE="true"), so the strings "true" and "false" mean the
// boolean. Any other string stays an error.
if s, ok := val.(string); ok && (s == "true" || s == "false") {
val, converted = s == "true", true
}
}
if len(opt.Enum) > 0 {
for _, allowed := range opt.Enum {
if anyEqual(allowed, val) {
return nil
return val, converted, nil
}
}
return fmt.Errorf("option %q value %v is not in enum %v", name, val, opt.Enum)
return nil, false, fmt.Errorf("option %q value %v is not in enum %v", name, val, opt.Enum)
}
switch opt.Type {
case "boolean":
if opt.Type == "boolean" {
if _, ok := val.(bool); !ok {
return fmt.Errorf("option %q expects boolean, got %T", name, val)
return nil, false, fmt.Errorf("option %q expects boolean, got %T", name, val)
}
}
// Any other type: accept and let install.sh deal with it.
return val, converted, nil
}

// coerceOptionString converts a JSON option value to a string the way
// the reference CLI (@devcontainers/cli) does: it writes each value
// into devcontainer-features.env through a JavaScript template
// literal, i.e. JavaScript's String(). An array joins its elements
// with "," (null → "", nested arrays flatten), null is "null", and
// numbers use JavaScript's number formatting. An object (which
// JavaScript would write as "[object Object]") is not converted: it
// reports false so the option is rejected.
func coerceOptionString(v any) (string, bool) {
switch x := v.(type) {
case nil:
return "null", true
case string:
return x, true
case bool:
return strconv.FormatBool(x), true
case float64:
return jsNumberString(x), true
case float32:
return jsNumberString(float64(x)), true
case json.Number:
// JavaScript parses every JSON number as a double, so
// "1e6" is 1000000 and a 19-digit integer loses precision.
if f, err := x.Float64(); err == nil {
return jsNumberString(f), true
}
case "string", "":
if _, ok := val.(string); !ok {
return fmt.Errorf("option %q expects string, got %T", name, val)
return x.String(), true
case int:
return strconv.Itoa(x), true
case int64:
return strconv.FormatInt(x, 10), true
case int32:
return strconv.FormatInt(int64(x), 10), true
case uint:
return strconv.FormatUint(uint64(x), 10), true
case uint64:
return strconv.FormatUint(x, 10), true
case uint32:
return strconv.FormatUint(uint64(x), 10), true
case []any:
parts := make([]string, len(x))
for i, e := range x {
if e == nil {
continue // Array.prototype.join writes null as "".
}
s, ok := coerceOptionString(e)
if !ok {
return "", false
}
parts[i] = s
}
return strings.Join(parts, ","), true
default:
// Unknown type — accept and let install.sh deal with it.
return "", false
}
}

// jsNumberString formats f as JavaScript's Number.prototype.toString
// does: shortest round-trip digits, positional notation for
// 1e-6 <= |f| < 1e21, and otherwise exponent form with no exponent
// padding ("1e+21", "1.5e-7").
func jsNumberString(f float64) string {
if f == 0 {
return "0" // also -0
}
if a := math.Abs(f); a >= 1e21 || a < 1e-6 {
s := strconv.FormatFloat(f, 'e', -1, 64)
mant, exp, _ := strings.Cut(s, "e")
sign := exp[:1]
exp = strings.TrimLeft(exp[1:], "0")
return mant + "e" + sign + exp
}
return nil
return strconv.FormatFloat(f, 'f', -1, 64)
}

func anyEqual(a, b any) bool {
Expand Down
Loading
Loading