Skip to content

bake: add unixtimestampparse and formattimestamp functions #3286

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
crazy-max wants to merge 2 commits into
base: master
Choose a base branch
from
+300 −3
Open

bake: add unixtimestampparse and formattimestamp functions #3286

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2303b5d
bake: add unixtimestampparse function
crazy-max Nov 6, 2025
a079c15
bake: add formattimestamp and tighten unix timestamp parsing
crazy-max Mar 11, 2026
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
105 changes: 103 additions & 2 deletions bake/hclparser/stdlib.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ package hclparser

import (
"errors"
"math/big"
"os"
"os/user"
"path"
Expand Down Expand Up @@ -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},
Expand Down Expand Up @@ -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.`},
Expand Down Expand Up @@ -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.`,
Expand Down Expand Up @@ -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 {
Expand Down
134 changes: 134 additions & 0 deletions bake/hclparser/stdlib_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
}
})
}
}
64 changes: 63 additions & 1 deletion docs/bake-stdlib.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
Expand Down Expand Up @@ -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. |
Expand Down Expand Up @@ -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" {
Expand All @@ -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
Expand Down Expand Up @@ -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
Copy link
Member

@tonistiigi tonistiigi Jul 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

how about

variable "SOURCE_DATE_EPOCH" {
  type    = number
  default = formattimestamp("X", "2015-10-21T00:00:00Z")
}

target "default" {
  args = {
    SOURCE_DATE_EPOCH = SOURCE_DATE_EPOCH
    BUILD_TIME = formattimestamp("YYYY-MM-DD'T'00:00:00Z", SOURCE_DATE_EPOCH)
  }
}

I'm also ok for special formatting for rfc3399 for less verbosity.

Copy link
Member Author

@crazy-max crazy-max Jul 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I looked at forking FormatDateFunc func as they are not willing to accept timestamp format: zclconf/go-cty#130 (comment) but there's quite a lot to fork and it might be better to be aligned so users are not confused. So that's why I opted for the terraform unix_timestamp_parse function func instead.

Copy link
Member Author

@crazy-max crazy-max Mar 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated with new formattimestamp func

# 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
Expand Down
Loading