diff --git a/bake/hclparser/stdlib.go b/bake/hclparser/stdlib.go index 638f82f76653..fa2728d176c4 100644 --- a/bake/hclparser/stdlib.go +++ b/bake/hclparser/stdlib.go @@ -2,6 +2,7 @@ package hclparser import ( "errors" + "math/big" "os" "os/user" "path" @@ -63,7 +64,8 @@ var stdlibFunctions = []funcDef{ {name: "flatten", fn: stdlib.FlattenFunc}, {name: "floor", fn: stdlib.FloorFunc}, {name: "format", fn: stdlib.FormatFunc}, - {name: "formatdate", fn: stdlib.FormatDateFunc}, + {name: "formatdate", fn: stdlib.FormatDateFunc, descriptionAlt: `Deprecated: use formattimestamp instead. Formats a timestamp given in RFC 3339 syntax into another timestamp in some other machine-oriented time syntax, as described in the format string.`}, + {name: "formattimestamp", factory: formatTimestampFunc}, {name: "formatlist", fn: stdlib.FormatListFunc}, {name: "greaterthan", fn: stdlib.GreaterThanFunc}, {name: "greaterthanorequalto", fn: stdlib.GreaterThanOrEqualToFunc}, @@ -129,6 +131,7 @@ var stdlibFunctions = []funcDef{ {name: "trimspace", fn: stdlib.TrimSpaceFunc}, {name: "trimsuffix", fn: stdlib.TrimSuffixFunc}, {name: "try", fn: tryfunc.TryFunc, descriptionAlt: `Variadic function that tries to evaluate all of is arguments in sequence until one succeeds, in which case it returns that result, or returns an error if none of them succeed.`}, + {name: "unixtimestampparse", factory: unixtimestampParseFunc}, {name: "upper", fn: stdlib.UpperFunc}, {name: "urlencode", fn: encoding.URLEncodeFunc, descriptionAlt: `Applies URL encoding to a given string.`}, {name: "uuidv4", fn: uuid.V4Func, descriptionAlt: `Generates and returns a Type-4 UUID in the standard hexadecimal string format.`}, @@ -278,9 +281,43 @@ func semvercmpFunc() function.Function { }) } +// formatTimestampFunc constructs a function that formats either an RFC3339 +// timestamp string or a unix timestamp integer using the same format verbs as +// formatdate. +func formatTimestampFunc() function.Function { + return function.New(&function.Spec{ + Description: `Formats a timestamp string in RFC 3339 syntax or a unix timestamp integer into another timestamp in some other machine-oriented time syntax, as described in the format string.`, + Params: []function.Parameter{ + { + Name: "format", + Type: cty.String, + }, + { + Name: "time", + Type: cty.DynamicPseudoType, + }, + }, + Type: function.StaticReturnType(cty.String), + Impl: func(args []cty.Value, retType cty.Type) (cty.Value, error) { + switch args[1].Type() { + case cty.String: + return stdlib.FormatDateFunc.Call([]cty.Value{args[0], args[1]}) + case cty.Number: + t, err := unixTimestampValue(args[1]) + if err != nil { + return cty.DynamicVal, function.NewArgError(1, err) + } + return stdlib.FormatDateFunc.Call([]cty.Value{args[0], cty.StringVal(t.Format(time.RFC3339))}) + default: + return cty.DynamicVal, function.NewArgErrorf(1, "must be a string timestamp or a unix timestamp number") + } + }, + }) +} + // timestampFunc constructs a function that returns a string representation of the current date and time. // -// This function was imported from terraform's datetime utilities. +// This function was imported from Terraform's datetime utilities. func timestampFunc() function.Function { return function.New(&function.Spec{ Description: `Returns a string representation of the current date and time.`, @@ -313,6 +350,70 @@ func homedirFunc() function.Function { }) } +// unixtimestampParseFunc, given a unix timestamp integer, will parse and +// return an object representation of that date and time +// +// This function is similar to the `unix_timestamp_parse` function in Terraform: +// https://registry.terraform.io/providers/hashicorp/time/latest/docs/functions/unix_timestamp_parse +func unixtimestampParseFunc() function.Function { + return function.New(&function.Spec{ + Description: `Given a unix timestamp integer, will parse and return an object representation of that date and time. A unix timestamp is the number of seconds elapsed since January 1, 1970 UTC.`, + Params: []function.Parameter{ + { + Name: "unix_timestamp", + Description: "Unix Timestamp integer to parse", + Type: cty.Number, + }, + }, + Type: function.StaticReturnType(cty.Object(map[string]cty.Type{ + "year": cty.Number, + "year_day": cty.Number, + "day": cty.Number, + "month": cty.Number, + "month_name": cty.String, + "weekday": cty.Number, + "weekday_name": cty.String, + "hour": cty.Number, + "minute": cty.Number, + "second": cty.Number, + "rfc3339": cty.String, + "iso_year": cty.Number, + "iso_week": cty.Number, + })), + Impl: func(args []cty.Value, retType cty.Type) (cty.Value, error) { + unixTime, err := unixTimestampValue(args[0]) + if err != nil { + return cty.DynamicVal, function.NewArgError(0, err) + } + isoYear, isoWeek := unixTime.ISOWeek() + return cty.ObjectVal(map[string]cty.Value{ + "year": cty.NumberIntVal(int64(unixTime.Year())), + "year_day": cty.NumberIntVal(int64(unixTime.YearDay())), + "day": cty.NumberIntVal(int64(unixTime.Day())), + "month": cty.NumberIntVal(int64(unixTime.Month())), + "month_name": cty.StringVal(unixTime.Month().String()), + "weekday": cty.NumberIntVal(int64(unixTime.Weekday())), + "weekday_name": cty.StringVal(unixTime.Weekday().String()), + "hour": cty.NumberIntVal(int64(unixTime.Hour())), + "minute": cty.NumberIntVal(int64(unixTime.Minute())), + "second": cty.NumberIntVal(int64(unixTime.Second())), + "rfc3339": cty.StringVal(unixTime.Format(time.RFC3339)), + "iso_year": cty.NumberIntVal(int64(isoYear)), + "iso_week": cty.NumberIntVal(int64(isoWeek)), + }), nil + }, + }) +} + +func unixTimestampValue(v cty.Value) (time.Time, error) { + bf := v.AsBigFloat() + ts, acc := bf.Int64() + if acc != big.Exact { + return time.Time{}, errors.New("unix timestamp must be an integer") + } + return time.Unix(ts, 0).UTC(), nil +} + func Stdlib() map[string]function.Function { funcs := make(map[string]function.Function, len(stdlibFunctions)) for _, v := range stdlibFunctions { diff --git a/bake/hclparser/stdlib_test.go b/bake/hclparser/stdlib_test.go index 1f3038ca80c9..17427782bec4 100644 --- a/bake/hclparser/stdlib_test.go +++ b/bake/hclparser/stdlib_test.go @@ -258,3 +258,137 @@ func TestSemverCmp(t *testing.T) { }) } } + +func TestUnixTimestampParseFunc(t *testing.T) { + type testCase struct { + input cty.Value + want map[string]cty.Value + wantErr bool + } + tests := map[string]testCase{ + "positive timestamp": { + input: cty.NumberIntVal(1690328596), + want: map[string]cty.Value{ + "year": cty.NumberIntVal(2023), + "year_day": cty.NumberIntVal(206), + "day": cty.NumberIntVal(25), + "month": cty.NumberIntVal(7), + "month_name": cty.StringVal("July"), + "weekday": cty.NumberIntVal(2), + "weekday_name": cty.StringVal("Tuesday"), + "hour": cty.NumberIntVal(23), + "minute": cty.NumberIntVal(43), + "second": cty.NumberIntVal(16), + "rfc3339": cty.StringVal("2023-07-25T23:43:16Z"), + "iso_year": cty.NumberIntVal(2023), + "iso_week": cty.NumberIntVal(30), + }, + }, + "zero timestamp": { + input: cty.NumberIntVal(0), + want: map[string]cty.Value{ + "year": cty.NumberIntVal(1970), + "year_day": cty.NumberIntVal(1), + "day": cty.NumberIntVal(1), + "month": cty.NumberIntVal(1), + "month_name": cty.StringVal("January"), + "weekday": cty.NumberIntVal(4), + "weekday_name": cty.StringVal("Thursday"), + "hour": cty.NumberIntVal(0), + "minute": cty.NumberIntVal(0), + "second": cty.NumberIntVal(0), + "rfc3339": cty.StringVal("1970-01-01T00:00:00Z"), + "iso_year": cty.NumberIntVal(1970), + "iso_week": cty.NumberIntVal(1), + }, + }, + "negative timestamp": { + input: cty.NumberIntVal(-1), + want: map[string]cty.Value{ + "year": cty.NumberIntVal(1969), + "year_day": cty.NumberIntVal(365), + "day": cty.NumberIntVal(31), + "month": cty.NumberIntVal(12), + "month_name": cty.StringVal("December"), + "weekday": cty.NumberIntVal(3), + "weekday_name": cty.StringVal("Wednesday"), + "hour": cty.NumberIntVal(23), + "minute": cty.NumberIntVal(59), + "second": cty.NumberIntVal(59), + "rfc3339": cty.StringVal("1969-12-31T23:59:59Z"), + "iso_year": cty.NumberIntVal(1970), + "iso_week": cty.NumberIntVal(1), + }, + }, + "fractional timestamp": { + input: cty.NumberFloatVal(1.2), + wantErr: true, + }, + "string timestamp": { + input: cty.StringVal("0"), + wantErr: true, + }, + } + + for name, test := range tests { + t.Run(name, func(t *testing.T) { + got, err := unixtimestampParseFunc().Call([]cty.Value{test.input}) + if test.wantErr { + require.Error(t, err) + return + } + require.NoError(t, err) + for k, v := range test.want { + require.True(t, got.GetAttr(k).RawEquals(v), "field %s: got %v, want %v", k, got.GetAttr(k), v) + } + }) + } +} + +func TestFormatTimestampFunc(t *testing.T) { + type testCase struct { + format cty.Value + input cty.Value + want cty.Value + wantErr bool + } + tests := map[string]testCase{ + "rfc3339 string input": { + format: cty.StringVal("YYYY-MM-DD"), + input: cty.StringVal("2025-09-16T12:00:00Z"), + want: cty.StringVal("2025-09-16"), + }, + "unix timestamp input": { + format: cty.StringVal("YYYY-MM-DD'T'hh:mm:ssZ"), + input: cty.NumberIntVal(1690328596), + want: cty.StringVal("2023-07-25T23:43:16Z"), + }, + "negative unix timestamp input": { + format: cty.StringVal("YYYY-MM-DD'T'hh:mm:ssZ"), + input: cty.NumberIntVal(-1), + want: cty.StringVal("1969-12-31T23:59:59Z"), + }, + "fractional unix timestamp input": { + format: cty.StringVal("YYYY-MM-DD"), + input: cty.NumberFloatVal(1.2), + wantErr: true, + }, + "invalid string input": { + format: cty.StringVal("YYYY-MM-DD"), + input: cty.StringVal("0"), + wantErr: true, + }, + } + + for name, test := range tests { + t.Run(name, func(t *testing.T) { + got, err := formatTimestampFunc().Call([]cty.Value{test.format, test.input}) + if test.wantErr { + require.Error(t, err) + } else { + require.NoError(t, err) + require.Equal(t, test.want, got) + } + }) + } +} diff --git a/docs/bake-stdlib.md b/docs/bake-stdlib.md index a5503966e583..67f2cdb617db 100644 --- a/docs/bake-stdlib.md +++ b/docs/bake-stdlib.md @@ -38,8 +38,9 @@ title: Bake standard library functions | [`flatten`](#flatten) | Transforms a list, set, or tuple value into a tuple by replacing any given elements that are themselves sequences with a flattened tuple of all of the nested elements concatenated together. | | [`floor`](#floor) | Returns the greatest whole number that is less than or equal to the given value. | | [`format`](#format) | Constructs a string by applying formatting verbs to a series of arguments, using a similar syntax to the C function \"printf\". | -| [`formatdate`](#formatdate) | Formats a timestamp given in RFC 3339 syntax into another timestamp in some other machine-oriented time syntax, as described in the format string. | +| [`formatdate`](#formatdate) | Deprecated: use formattimestamp instead. Formats a timestamp given in RFC 3339 syntax into another timestamp in some other machine-oriented time syntax, as described in the format string. | | [`formatlist`](#formatlist) | Constructs a list of strings by applying formatting verbs to a series of arguments, using a similar syntax to the C function \"printf\". | +| [`formattimestamp`](#formattimestamp) | Formats a timestamp string in RFC 3339 syntax or a unix timestamp integer into another timestamp in some other machine-oriented time syntax, as described in the format string. | | [`greaterthan`](#greaterthan) | Returns true if and only if the second number is greater than the first. | | [`greaterthanorequalto`](#greaterthanorequalto) | Returns true if and only if the second number is greater than or equal to the first. | | [`hasindex`](#hasindex) | Returns true if if the given collection can be indexed with the given key without producing an error, or false otherwise. | @@ -104,6 +105,7 @@ title: Bake standard library functions | [`trimspace`](#trimspace) | Removes any consecutive space characters (as defined by Unicode) from the start and end of the given string. | | [`trimsuffix`](#trimsuffix) | Removes the given suffix from the start of the given string, if present. | | [`try`](#try) | Variadic function that tries to evaluate all of is arguments in sequence until one succeeds, in which case it returns that result, or returns an error if none of them succeed. | +| [`unixtimestampparse`](#unixtimestampparse) | Given a unix timestamp integer, will parse and return an object representation of that date and time. A unix timestamp is the number of seconds elapsed since January 1, 1970 UTC. | | [`upper`](#upper) | Returns the given string with all Unicode letters translated to their uppercase equivalents. | | [`urlencode`](#urlencode) | Applies URL encoding to a given string. | | [`uuidv4`](#uuidv4) | Generates and returns a Type-4 UUID in the standard hexadecimal string format. | @@ -532,6 +534,10 @@ target "webapp-dev" { ## `formatdate` +> [!WARNING] +> Deprecated: use `formattimestamp` instead. `formatdate` only accepts RFC3339 +> timestamp strings. + ```hcl # docker-bake.hcl target "webapp-dev" { @@ -543,6 +549,28 @@ target "webapp-dev" { } ``` +## `formattimestamp` + +Formats either an RFC3339 timestamp string or a unix timestamp integer. + +```hcl +# docker-bake.hcl +variable "SOURCE_DATE_EPOCH" { + type = number + default = 1690328596 +} + +target "default" { + dockerfile = "Dockerfile" + labels = { + "org.opencontainers.image.created" = formattimestamp("YYYY-MM-DD'T'hh:mm:ssZ", SOURCE_DATE_EPOCH) # => "2023-07-25T23:43:16Z" + } + args = { + build_date = formattimestamp("YYYY-MM-DD", "2025-09-16T12:00:00Z") # => "2025-09-16" + } +} +``` + ## `formatlist` ```hcl @@ -1409,6 +1437,40 @@ target "webapp-dev" { } ``` +## `unixtimestampparse` + +The returned object has the following attributes: +* `year` (Number) The year for the unix timestamp. +* `year_day` (Number) The day of the year for the unix timestamp, in the range 1-365 for non-leap years, and 1-366 in leap years. +* `day` (Number) The day of the month for the unix timestamp. +* `month` (Number) The month of the year for the unix timestamp. +* `month_name` (String) The name of the month for the unix timestamp (ex. "January"). +* `weekday` (Number) The day of the week for the unix timestamp. +* `weekday_name` (String) The name of the day for the unix timestamp (ex. "Sunday"). +* `hour` (Number) The hour within the day for the unix timestamp, in the range 0-23. +* `minute` (Number) The minute offset within the hour for the unix timestamp, in the range 0-59. +* `second` (Number) The second offset within the minute for the unix timestamp, in the range 0-59. +* `rfc3339` (String) The RFC3339 format string. +* `iso_year` (Number) The ISO 8601 year number. +* `iso_week` (Number) The ISO 8601 week number. + +```hcl +# docker-bake.hcl +variable "SOURCE_DATE_EPOCH" { + type = number + default = 1690328596 +} + +target "default" { + args = { + SOURCE_DATE_EPOCH = SOURCE_DATE_EPOCH + } + labels = { + "org.opencontainers.image.created" = unixtimestampparse(SOURCE_DATE_EPOCH).rfc3339 + } +} +``` + ## `upper` ```hcl