time: better handling of overflow in time.Time

[neild]

The time.Time type has a large, but finite range. The time package does not, so far as I can determine, document what this range is.

A Time can represent instants billions of years in the past or future. So far as I can tell, we've taken a general attitude that instants outside the probable lifespan of the human species are out of scope for the package and can be ignored.

For example, time.Unix converts a Unix timestamp (seconds & nanoseconds since the Unix epoch) to a Time. It documents the handling of out-of-range values only by saying:

Not all sec values have a corresponding time value. One such value is 1<<63-1 (the largest int64 value).

Functions such as time.AddDate do not document their behavior on overflow.

Most programs will never encounter out-of-range dates. (If Go proves to be unexpectedly durable on geologic time scales, we can leave the problem of increasing the size of the time.Time seconds counter to future generations.) However, a program handling adversarial inputs (such as a very large Unix timestamp) may be induced to overflow a time.Time, with surprising and undocumented results.

We could harden the time package a bit more against overflow. Some specific functions that we might harden:

• time.Unix could either saturate or return the zero time when provided with an out-of-range value.
• time.Add and time.AddDate could saturate rather than wrapping on overflow.
• time.Round could either truncate or saturate on overflow.

There might be others I'm missing.

Alternatively, we could leave the implementation alone and document what validation users should perform to adequately defend against adversarial inputs to time.Unix.

[gabyhelp]

Related Issues

• time: unchecked overflow in Add and AddDays #20678
• time: add microseconds-based APIs #16087 (closed)
• time: In time.Unix, an underflow occurs when you put a large negative value in the seconds area #64514
• time: Unix(sec, nanonsec) has bizarre undocumented behavior for large values of sec #10906 (closed)

Related Code Changes

• time: fix years overflow when using time.Date
• time: document that not all Unix time can be represented

Related Documentation

• Package time > type Time ¶ > func Unix ¶

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[seankhliao]

In #63844 it was noted that restricting to ±32767 years wasn't really acceptable

[neild]

If it isn't clear, this issue isn't about changing the range of supported instants. It's about what we do when some time package operation goes outside that range.

[seankhliao]

I think it does point to needing to support a range outside the probable lifespan of the human species...

there's #64514 for underflow, #56909 and #20678 for overflow, perhaps we should merge these?

[dsnet]

Personally, I would expect to overflow to use saturation arithmetic. It's what I've observed for time.Time.Sub and I guess I had mistakenly assumed was true for all other arithmetic methods. I've relied on the implicit saturation handling of Sub quite a bit.

Do you have any suggestions for time.Duration where you use the native Go + and - operation, which will overflow according to typical two's complement arithmentic? Should there be a Add method to add with saturation?

[neild]

time.Duration is an int64, and the fact that it's an int64 is user-visible, so the overflow behavior there is at least predictable. time.Time, in contrast, doesn't define what its valid range is and has no documented way to detect or handle overflow. (What happens if you call time.Unix with an out-of-range value? What values are out-of-range? We don't say. Maybe the answer is "don't create times more than a billion years away from the present", but if so, we should actually document that.)

Maybe there should be a saturating Duration.Add, but I think that's out of scope for this issue.