timeutil

Documentation

Overview

Package timeutil provides helpers for parsing timestamp strings used throughout the platform's data layer. All functions expect the ISO 8601 / RFC 3339 format YYYY-MM-DDTHH:MM:SSZ (UTC, no fractional seconds). This is the canonical format returned by MySQL's DATETIME columns when serialized to JSON or gRPC string fields.

Index

• Constants
• func BudgetedContext(ctx context.Context, reserve time.Duration) (context.Context, context.CancelFunc)
• func LookupZone(country, state string) (string, bool)
• func TimestampToTime(timestamp string) time.Time
• func TimestampToTimePtr(timestamp string) *time.Time
• func ZoneFor(stored *string, country, state, fallback string) *time.Location

Constants

const FanOutReserve = 1500 * time.Millisecond

FanOutReserve is the headroom BudgetedContext leaves between the end of a fan-out and the caller's own deadline: enough to assemble and serialize a response, and to survive the gap between when a goroutine observes cancellation and when the handler actually returns.

Functions

func BudgetedContext

func BudgetedContext(ctx context.Context, reserve time.Duration) (context.Context, context.CancelFunc)

BudgetedContext derives a context that expires far enough before ctx's own deadline for the caller to still return a response.

It exists for fan-outs over slow dependencies — a live carrier-rating round trip, a per-type search RPC — where an individual participant failing is already handled by dropping its contribution. Without a budget those fan-outs inherit the request deadline exactly, so one stalled participant spends the whole of it and the caller returns a 504 with nothing in it, discarding every result that did arrive. Cutting the fan-out short instead turns a total failure into a partial one.

reserve is the headroom to leave; pass FanOutReserve unless the assembly step after the fan-out is unusually expensive. When ctx carries no deadline, or when less than reserve remains (the request is already over budget and about to be abandoned), ctx is returned with a no-op cancel and the caller runs unbounded — a fan-out that cannot be shortened usefully should not be truncated to nothing.

func LookupZone

func LookupZone(country, state string) (string, bool)

LookupZone reports the zone a country and subdivision keep time in, and whether one is known.

The subdivision is consulted only for the countries that genuinely span zones. Everywhere else the country answer is exact, which is why most of the table is keyed on country alone.

func TimestampToTime

func TimestampToTime(timestamp string) time.Time

TimestampToTime parses a UTC timestamp string (YYYY-MM-DDTHH:MM:SSZ) into a time.Time value. Returns the zero time (time.Time{}) if the string does not match the expected format. Use TimestampToTimePtr when you need to distinguish between "missing" (nil) and "zero time".

func TimestampToTimePtr

func TimestampToTimePtr(timestamp string) *time.Time

TimestampToTimePtr parses a UTC timestamp string (YYYY-MM-DDTHH:MM:SSZ) into a *time.Time. Returns nil if the string does not match the expected format, making it safe to use directly in struct assignments where a nil pointer represents "not set" (e.g. optional processed_at or expires_at fields).

func ZoneFor

func ZoneFor(stored *string, country, state, fallback string) *time.Location

ZoneFor resolves the zone a place keeps time in, most trustworthy source first.

A stored zone wins outright. It is the only source a person can correct, and the derivation below is deliberately approximate — thirteen US states span two zones, and the majority answer is wrong for the minority of addresses in them. Persisting the derived value and letting it be edited is what makes those addresses fixable at all.

The fallback chain ends at the account's own zone rather than UTC, because an account's addresses cluster near it: a Denver plant shipping to an unrecognised state is far better served by Denver time than by UTC.