Documentation
¶
Overview ¶
Package duration is the single parser for every duration Atmos reads from configuration, flags, and environment variables.
Accepted forms, in every place a duration is configured:
- Go durations: "500ms", "30s", "1h30m", "1.5s"
- Bare numbers are seconds: "10", 10, 1.5 (YAML integers and floats included)
- Days: "2d", "1d12h"
- Keywords: "minute", "hourly", "daily", "weekly", "monthly", "yearly"
- ISO-8601: "PT8H", "P1DT12H" (see iso8601.go)
The package depends only on the standard library and mapstructure so that pkg/schema and the errors package can import it without cycles. Callers add their own hints and context.
Index ¶
- Constants
- Variables
- func DecodeHook() mapstructure.DecodeHookFunc
- func FormatISO8601(d time.Duration) string
- func Is(err error) bool
- func IsExpired(updatedAt time.Time, ttl string) (bool, error)
- func IsZeroTTL(ttl string) bool
- func Parse(s string) (int64, error)
- func ParseAny(value any) (time.Duration, error)
- func ParseDuration(s string) (time.Duration, error)
- func ParseISO8601(s string) (time.Duration, error)
- func ParseNonNegative(s string) (time.Duration, error)
- func ParseString(s string) (time.Duration, error)
Constants ¶
const Hint = "Use a duration such as `30s`, `5m`, `1h30m`, or `2d`; a bare number means seconds."
Hint is the one-line format reminder callers attach to their errors.
Variables ¶
var ( // ErrInvalid is returned for a value that is not a duration in any accepted form. ErrInvalid = errors.New("invalid duration format") // ErrNotPositive is returned when a positive duration is required and the value is zero or negative. ErrNotPositive = errors.New("duration must be positive") // ErrNegative is returned when a non-negative duration is required and the value is negative. ErrNegative = errors.New("duration must not be negative") // ErrOverflow is returned when a value does not fit in time.Duration. ErrOverflow = errors.New("duration overflows time.Duration") )
Sentinel errors. The errors package re-exports ErrInvalid as ErrInvalidDuration so errors.Is works with either name.
var ( // ErrISO8601Empty is returned for an empty ISO-8601 duration. ErrISO8601Empty = fmt.Errorf("%w: empty ISO-8601 duration", ErrInvalid) // ErrISO8601Prefix is returned when the 'P' designator is missing. ErrISO8601Prefix = fmt.Errorf("%w: missing 'P' prefix", ErrInvalid) // ErrISO8601Designator is returned for a malformed or unknown designator. ErrISO8601Designator = fmt.Errorf("%w: invalid ISO-8601 designator", ErrInvalid) )
Sentinel errors for ISO-8601 duration parsing. Each wraps ErrInvalid so callers can match either the specific or the general error.
Functions ¶
func DecodeHook ¶
func DecodeHook() mapstructure.DecodeHookFunc
DecodeHook returns a mapstructure decode hook that converts configuration values into time.Duration using ParseAny: strings in any accepted form, and numbers as seconds.
It replaces mapstructure.StringToTimeDurationHookFunc, which only accepted Go duration strings and let a bare YAML integer decode as nanoseconds. Negative values are rejected; zero is accepted so callers can decide whether zero is meaningful.
func FormatISO8601 ¶
FormatISO8601 converts a Go time.Duration to the ISO-8601 form used by cloud APIs such as Azure PIM scheduleInfo.expiration (for example 8h -> "PT8H", 90m -> "PT1H30M"). Zero and negative durations format as "".
func IsExpired ¶ added in v1.221.0
IsExpired reports whether a cache entry last refreshed at updatedAt has exceeded ttl.
A zero TTL (see IsZeroTTL) is always expired. A non-zero TTL is parsed with ParseDuration; on a parse error the error is returned and callers should fail safe by treating the entry as expired to avoid serving stale data. This helper makes no decision for an empty ttl (""). The meaning of "no TTL configured" differs between subsystems (reuse-forever versus refresh-each-run), so callers handle "" explicitly.
func IsZeroTTL ¶ added in v1.221.0
IsZeroTTL reports whether the TTL string represents a zero duration.
Parse rejects zero (a zero duration is not a valid period for cleanup scheduling), but for cache TTLs a zero value is a legitimate, common case meaning "always expired / never reuse". Callers detect it with this helper before parsing.
func Parse ¶
Parse parses a duration and returns whole seconds. The value must be at least one second; this is the contract used for cache TTLs, cleanup periods, and the version-check frequency.
func ParseAny ¶
ParseAny parses a duration from a configuration value of any type. Strings go through ParseString; integers and floats are seconds; a time.Duration passes through. The result may be zero or negative; use ParseDuration or ParseNonNegative to enforce a sign.
func ParseDuration ¶
ParseDuration parses a duration that must be greater than zero.
func ParseISO8601 ¶
ParseISO8601 parses an ISO-8601 duration string into a time.Duration. It supports the date designators Y, M, W, D (365, 30, 7, and 1 days) and the time designators H, M, S, including decimal values such as "PT0.5H". Negative values are rejected.
func ParseNonNegative ¶
ParseNonNegative parses a duration that may be zero but not negative.
Types ¶
This section is empty.
Source Files