Documentation
¶
Overview ¶
Package time provides time-related helpers, aliases, and optional network time providers used by go-service.
This package serves two purposes:
Standard library compatibility via aliases. It re-exports a small subset of the Go standard library time API so code across go-service can consistently import go-service packages while still using the underlying time semantics.
Exported aliases include Time (time.Time), Duration (time.Duration), common duration constants (Second, Minute, Hour, etc.), and RFC3339.
Optional network time sourcing. In environments where local wall-clock time may drift or needs stronger guarantees, this package can construct a Network provider that fetches time from external services (for example NTP or NTS).
Standard library aliases ¶
The following identifiers are thin wrappers/aliases of the standard library and do not change semantics:
- Time and Duration alias time.Time and time.Duration.
- Now, Since, Sleep, and ParseDuration forward to time.Now, time.Since, time.Sleep, and time.ParseDuration respectively.
- Constants such as Second, Minute, Hour, and RFC3339 alias the standard library values.
Use these when you want to keep dependencies within the go-service module while remaining fully compatible with the standard library time types.
Strict helpers ¶
MustParseDuration parses a Go duration string (see time.ParseDuration) and panics if parsing fails (via runtime.Must).
This is intended for strict startup/configuration code paths where an invalid duration is a programmer/configuration error and should fail fast. If you need recoverable error handling, use ParseDuration directly.
Network time providers ¶
The Network interface provides a single method:
- Now() (Time, error): returns the current time as reported by the provider.
NewNetwork constructs a Network implementation based on *Config. Enablement is modeled by presence: a nil *Config is treated as disabled and NewNetwork returns (nil, nil).
Config.Kind selects the provider implementation. This package currently supports:
- "ntp": Network Time Protocol (NTP).
- "nts": Network Time Security (NTS), which provides authenticated time as defined by RFC 8915.
If Config.Kind is not recognized, NewNetwork returns ErrNotFound.
Provider implementations may wrap and prefix errors to provide clearer context (for example "ntp: ..." or "nts: ...").
Dependency injection (Fx) ¶
Module wires NewNetwork into Fx as a constructor so applications can optionally depend on a Network provider when configured.
Notes ¶
Network time providers require external connectivity and correct configuration (for example a valid server address). Services should treat network time as an optional dependency unless their operational requirements demand it.
Index ¶
Constants ¶
const Hour = time.Hour
Hour is a duration constant equal to 60 minutes.
It is an alias of time.Hour, provided so callers can depend on go-service packages while using standard library time values.
const Microsecond = time.Microsecond
Microsecond is a duration constant equal to 1e3 nanoseconds.
It is an alias of time.Microsecond.
const Millisecond = time.Millisecond
Millisecond is a duration constant equal to 1e6 nanoseconds.
It is an alias of time.Millisecond.
const Minute = time.Minute
Minute is a duration constant equal to 60 seconds.
It is an alias of time.Minute.
const Nanosecond = time.Nanosecond
Nanosecond is a duration constant equal to 1.
It is an alias of time.Nanosecond.
const RFC3339 = time.RFC3339
RFC3339 is the RFC3339 time format layout.
It is an alias of time.RFC3339.
const Second = time.Second
Second is a duration constant equal to 1e9 nanoseconds.
It is an alias of time.Second.
Variables ¶
var ErrNotFound = errors.New("time: network not found")
ErrNotFound is returned when Config.Kind does not match a supported network time provider.
This error is returned by NewNetwork when cfg is enabled (non-nil) but Kind is not recognized by this package.
var Module = di.Module( di.Constructor(NewNetwork), )
Module wires the network time provider constructor into Fx.
Including this module in an Fx application provides a constructor for Network via NewNetwork.
NewNetwork uses *Config to decide whether to enable network time and which provider to construct (for example "ntp" or "nts"). When network time is disabled (nil config), the constructor returns (nil, nil).
This module does not force the application to use network time; it only makes the provider available for optional injection.
Functions ¶
func After ¶ added in v2.326.1
After waits for the duration to elapse and then sends the current time on the returned channel.
This is a thin wrapper around time.After and does not change semantics.
func MustParseDuration ¶
MustParseDuration parses s as a duration string and panics if parsing fails.
This helper is intended for strict startup/configuration paths where an invalid duration is considered a fatal configuration/programming error. It panics by calling runtime.Must on the parse error.
If you need recoverable error handling, use ParseDuration instead.
Types ¶
type Config ¶
type Config struct {
// Kind selects the network time provider implementation (for example "ntp" or "nts").
//
// If Kind is unknown, NewNetwork returns ErrNotFound.
Kind string `yaml:"kind,omitempty" json:"kind,omitempty" toml:"kind,omitempty"`
// Address is the provider address passed to the selected implementation.
//
// The expected format is implementation-specific. For example, NTP may accept
// pool hostnames, and NTS may accept hostnames of NTS-enabled servers.
Address string `yaml:"address,omitempty" json:"address,omitempty" toml:"address,omitempty"`
}
Config configures a network time provider.
This configuration is consumed by NewNetwork, which selects a concrete Network implementation based on Kind and passes Address to that implementation.
Enablement ¶
Enablement is modeled by presence: a nil *Config indicates that network time is disabled. When disabled, NewNetwork returns (nil, nil).
Kind ¶
Kind selects the network time provider implementation. This package currently supports (via NewNetwork):
- "ntp": Network Time Protocol (NTP)
- "nts": Network Time Security (NTS)
If Kind is unrecognized, NewNetwork returns ErrNotFound.
Address ¶
Address is the provider/server address passed to the selected implementation. The expected format is implementation-specific (for example a hostname or pool name). If Address is empty or invalid, the provider will typically return an error when Now is called.
type Duration ¶
Duration is the go-service duration type used across the repository.
It is a type alias of time.Duration, meaning it has identical semantics and method set to the standard library type.
func ParseDuration ¶
ParseDuration parses a duration string.
This is a thin wrapper around time.ParseDuration. The input uses the standard Go duration format such as "250ms", "5s", or "1m".
type NTPNetwork ¶
type NTPNetwork struct {
// contains filtered or unexported fields
}
NTPNetwork implements Network by querying an NTP server for the current time.
This type is a small adapter around github.com/beevik/ntp. It prefixes returned errors with "ntp" to make failures easier to attribute when multiple time sources are possible.
func NewNTPNetwork ¶
func NewNTPNetwork(address string) *NTPNetwork
NewNTPNetwork constructs a Network implementation backed by NTP (Network Time Protocol).
NTP is a widely deployed protocol for synchronizing clocks over packet-switched networks. See: https://en.wikipedia.org/wiki/Network_Time_Protocol
The address argument is passed through to the upstream NTP client implementation and is typically a hostname (for example an NTP pool name) or host:port depending on the client library behavior. If address is empty or invalid, calls to Now will typically return an error.
func (*NTPNetwork) Now ¶
func (n *NTPNetwork) Now() (Time, error)
Now returns the current time as reported by the configured NTP server.
This method performs network I/O. Any error returned by the underlying NTP library is wrapped/prefixed with "ntp" for context.
type NTSNetwork ¶
type NTSNetwork struct {
// contains filtered or unexported fields
}
NTSNetwork implements Network by querying an NTS server and validating the response.
This type is a small adapter around github.com/beevik/nts. It prefixes returned errors with "nts" to make failures easier to attribute when multiple time sources are possible.
Note: NTS returns a clock offset relative to the local clock. This implementation returns Now().Add(offset), which means the returned value is derived from the local time adjusted by the authenticated offset.
func NewNTSNetwork ¶
func NewNTSNetwork(address string) *NTSNetwork
NewNTSNetwork constructs a Network implementation backed by NTS (Network Time Security).
NTS provides authenticated time over the network, improving on NTP by protecting against certain classes of on-path and server spoofing attacks. See: https://datatracker.ietf.org/doc/html/rfc8915
The address argument is passed through to the upstream NTS client implementation and is typically a hostname (and possibly port) of an NTS-enabled server. If address is empty or invalid, calls to Now will typically return an error.
func (*NTSNetwork) Now ¶
func (n *NTSNetwork) Now() (Time, error)
Now returns the current time as reported by the configured NTS server.
This method performs network I/O and validates the NTS response before returning.
The algorithm is:
- Establish a session (nts.NewSession).
- Query the server (session.Query).
- Validate the response (res.Validate).
- Apply the server-provided clock offset to the local time.
Any error returned by the underlying NTS library is wrapped/prefixed with "nts" for context.
type Network ¶
type Network interface {
// Now returns the current time from the provider.
//
// Implementations may perform network I/O and may return an error if the provider
// cannot be reached, the response is invalid, or the configured address is incorrect.
Now() (Time, error)
}
Network provides the current time from a network time provider (for example NTP or NTS).
Implementations should return the current time as reported by the configured provider. Errors returned by Now should include enough context for callers to diagnose the failure (for example connection failures, protocol errors, or validation failures).
func NewNetwork ¶
NewNetwork constructs a network time provider based on cfg.
Enablement is modeled by presence: if cfg is nil (disabled), NewNetwork returns (nil, nil).
Supported kinds:
- "ntp": constructs an NTP-backed provider (see NewNTPNetwork)
- "nts": constructs an NTS-backed provider (see NewNTSNetwork)
If cfg.Kind is not recognized, NewNetwork returns (nil, ErrNotFound).
Note: Address validation is provider-specific. NewNetwork does not validate cfg.Address; providers typically return an error from Network.Now when the address is empty or invalid.
type Ticker ¶ added in v2.326.1
Ticker is the go-service ticker type used across the repository.
It is a type alias of time.Ticker, meaning it has identical semantics and method set to the standard library type.
Source Files