Date & time manipulation

[divarvel]

Currently, datetime values only support comparison operations, which is useful for TTL checks.

Adding support for structured access to datetime components would be useful for other kinds of checks (eg. forbidding access during weekends and outside office hours).

In order to keep the API changes small, i think getting inspiration from postgres timestamp functions would be good, namely:
date_trunc for truncating a date based on a specified limit (eg days, months, seconds), extract for projecting a timestamp on specific fields (day in year, day in week, hours, minutes, …).

Going this way has the benefit of:

• not growing the API surface much (that would be adding two binary operations)
• not requiring to introduce new types (eg TimeOfDay)

Here's how it could look like:

check if time($time), [1,2,3,4,5].contains($time.extract("dow")),
                      $time.extract("hour") >= 9,
                      $time.extract("hour") <= 18;

Time zones and offsets

Currently, date time values are represented as an unsigned 64 bit timestamp. It doesn't carry any offset information. While the RFC339 input syntax allows specifying an offset (not a timezone), this information is not carried in the AST (and in the protobuf representation): the corresponding UTC timestamp is computed. As long as we're only comparing date time values, not caring about the offset is okay (comparing corresponding UTC timestamps yields the correct answers).

Extracting date fields, however, requires caring about offsets: the local year, month, day, hour and minute depends on the offset.

Timezones

Time zones depend on an external database and tz info is machine-dependent, so it would not be handled

Solutions

There are multiple solutions for that:

1. tracking the time offset in the token representation (and in the AST): that's the most expressive solution, but it raises not-trivial questions regarding interop with older tokens, especially wrt the behaviour of date literals containing non-zero offsets.
2. introducing an .at_time_offset() method that shifts the timestamp by the corresponding offset, so that subsequent calls to .date_extract() work as expected, without modifying the AST. This strikes me as dangerous, as it would mean that $date.at_time_offset("+02:00") == $date would be false, even though changing the offset should not affect the instant itself
3. Introduce a .at_time_offset() method that registers an offset, along the original timestamp, that can be used by a subsequent call to .date_extract(). This solves the problems of 2, at the cost of making the AST a bit more complex.
4. make .date_extract() take an extra parameter, allowing to specify the offset (default would be Z)
5. Do nothing. Local time can be provided through authorizer facts, allowing the authorizer to use time zone data.

Solutions 1 and 2 are not acceptable to me, since they create ambiguity (even though solution 1 would be best as a greenfield one). I favour solution 4 over 3, as it does not require changing the AST, keeps the "every timestamp is UTC" current behaviour, and keeps offsets contained in the scope of date_extract (both visually and in the AST). A method taking two arguments would require a Ternary operator and associated machinery, but that should not be too much work. Another solution would be to bundle both the date component and the offset in a single string, but that would be a dirty hack.
Solution 5 is also a strong contender, since dealing with offsets only and not actual timezones may make the whole feature set irrelevant.