README
¶
Duration
A JSON-friendly duration type that stores values as whole seconds (int64). Serializes as a plain integer, matching the OAuth/OIDC expires_in convention.
Overview
duration.Seconds wraps an int64 representing seconds. Because the underlying type is int64, the standard encoding/json codec handles marshal/unmarshal without a custom marshaler — config files contain readable integers like 900 instead of Go-style strings like "15m0s".
Quick Start
import "github.com/oddbit-project/blueprint/types/duration"
type Config struct {
AccessTokenTTL duration.Seconds `json:"accessTokenTtl"`
RefreshTokenTTL duration.Seconds `json:"refreshTokenTtl"`
}
cfg := Config{
AccessTokenTTL: duration.Minutes(15), // JSON: 900
RefreshTokenTTL: duration.Days(7), // JSON: 604800
}
Constructors
| Function | Description | Example |
|---|---|---|
Minutes(n) |
Duration of n minutes | Minutes(15) → 900 |
Hours(n) |
Duration of n hours | Hours(2) → 7200 |
Days(n) |
Duration of n days (24h, no DST) | Days(7) → 604800 |
FromStd(d) |
Convert time.Duration, truncating sub-seconds |
FromStd(time.Hour) → 3600 |
Methods
| Method | Description |
|---|---|
Std() |
Returns time.Duration for standard library interop |
IsPositive() |
Reports whether the duration is strictly greater than zero |
String() |
Formats using time.Duration.String() (e.g. "15m0s") |
Standard Library Interop
// Convert to time.Duration for timers, deadlines, etc.
timer := time.NewTimer(cfg.AccessTokenTTL.Std())
deadline := time.Now().Add(cfg.AccessTokenTTL.Std())
// Convert from time.Duration (sub-second precision is lost)
d := duration.FromStd(1500 * time.Millisecond) // 1s, not 1.5s
JSON Encoding
Duration values serialize as plain integers (seconds):
{
"accessTokenTtl": 900,
"refreshTokenTtl": 604800
}
No custom marshaler is needed — the defined int64 type handles this natively.
Documentation
¶
Overview ¶
Package duration provides a JSON-friendly duration type for goauth configuration. Values are stored as whole seconds (int64) so they serialize as a plain integer, matching the OAuth/OIDC `expires_in` convention and giving operators a config file they can read at a glance.
The canonical type is duration.Seconds (Go-idiomatic stutter, like time.Time or url.URL). Construct values with the named helpers, which all return Seconds:
cfg.AccessTokenTTL = duration.Minutes(15) cfg.RefreshTokenTTL = duration.Days(7) cfg.OIDCStateTTL = duration.Seconds(600) cfg.JWKSCacheTTL = duration.FromStd(time.Hour)
Interop with the standard library goes through Std(), which hands back a time.Duration:
timer := time.NewTimer(cfg.AccessTokenTTL.Std()) deadline := time.Now().Add(cfg.AccessTokenTTL.Std())
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Seconds ¶
type Seconds int64
Seconds is a duration measured in whole seconds. The default encoding/json codec serializes it as a plain integer (e.g. 900 for fifteen minutes) — no custom marshaler is required because Seconds is a defined int64 type.
int64 (not uint64) is the underlying type so subtraction and time.Duration interop stay arithmetic-friendly. Validation that a TTL must be positive is a separate concern, expressed as `d > 0` at the callsite or via the IsPositive method.
func Days ¶
Days returns the duration equal to n days (24 hours each — no DST, no leap seconds; that is a calendar concept, not a duration one).
func FromStd ¶
FromStd converts a time.Duration to Seconds, truncating toward zero. Sub-second precision is lost — that is by design: the public surface should not promise precision the JSON form cannot carry.
func (Seconds) IsPositive ¶
IsPositive reports whether the duration is strictly greater than zero. Useful in Validate() methods that reject non-positive TTLs.
Source Files