timestamp

Documentation

Overview

Package timestamp provides a type-safe timestamp implementation for evidence packs.

The Timestamp type enforces the exact format "YYYY-MM-DDTHH:MM:SSZ" (RFC 3339 strict) required by the evidence pack spec. This format is critical for JCS canonicalization - different timestamp representations (fractional seconds, timezone offsets) would produce different manifest digests.

Format Requirements

• Exactly 20 characters
• UTC timezone (trailing "Z")
• No fractional seconds
• No timezone offsets

Usage

ts := timestamp.Now()
ts, err := timestamp.Parse("2024-01-15T10:30:00Z")
ts := timestamp.FromTime(time.Now())

Security Properties

• Format validation at parse time
• Immutable after construction
• JSON marshaling preserves exact format

Index

• Constants
• func Validate(s string) error
• type Timestamp
  • func FromTime(t time.Time) Timestamp
  • func MustParse(s string) Timestamp
  • func Now() Timestamp
  • func Parse(s string) (Timestamp, error)
  • func (ts Timestamp) After(other Timestamp) bool
  • func (ts Timestamp) Before(other Timestamp) bool
  • func (ts Timestamp) Equal(other Timestamp) bool
  • func (ts Timestamp) IsZero() bool
  • func (ts Timestamp) MarshalJSON() ([]byte, error)
  • func (ts Timestamp) String() string
  • func (ts Timestamp) Sub(other Timestamp) time.Duration
  • func (ts Timestamp) Time() time.Time
  • func (ts *Timestamp) UnmarshalJSON(data []byte) error

Constants

const Format = "2006-01-02T15:04:05Z"

Format is the exact timestamp format required by the evidence pack spec. This is a strict subset of RFC 3339: no fractional seconds, no timezone offsets.

Functions

func Validate

func Validate(s string) error

Validate checks if a string is a valid timestamp format without allocating a Timestamp. This is useful for validation-only scenarios.

Types

type Timestamp

type Timestamp struct {
	// contains filtered or unexported fields
}

Timestamp represents a timestamp in the canonical evidence pack format. The zero value is invalid; use Now, Parse, or FromTime to create.

func FromTime

func FromTime(t time.Time) Timestamp

FromTime converts a time.Time to a Timestamp. The time is converted to UTC and truncated to second precision.

func MustParse

func MustParse(s string) Timestamp

MustParse parses a timestamp string, panicking if invalid. Use only for compile-time constants and tests.

func Now

func Now() Timestamp

Now returns the current time as a Timestamp.

func Parse

func Parse(s string) (Timestamp, error)

Parse parses a timestamp string in the canonical format. Returns an error if the format is invalid.

func (Timestamp) After

func (ts Timestamp) After(other Timestamp) bool

After reports whether ts is after other. Returns false if either timestamp is zero.

func (Timestamp) Before

func (ts Timestamp) Before(other Timestamp) bool

Before reports whether ts is before other. Returns false if either timestamp is zero.

func (Timestamp) Equal

func (ts Timestamp) Equal(other Timestamp) bool

Equal reports whether ts and other represent the same timestamp.

func (Timestamp) IsZero

func (ts Timestamp) IsZero() bool

IsZero reports whether ts is the zero value (invalid/unset).

func (Timestamp) MarshalJSON

func (ts Timestamp) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (Timestamp) String

func (ts Timestamp) String() string

String returns the canonical string representation. Returns empty string for zero-value Timestamp.

func (Timestamp) Sub

func (ts Timestamp) Sub(other Timestamp) time.Duration

Sub returns the duration ts - other. Returns 0 if either timestamp is zero.

func (Timestamp) Time

func (ts Timestamp) Time() time.Time

Time returns the underlying time.Time value. Returns zero time for zero-value Timestamp.

func (*Timestamp) UnmarshalJSON

func (ts *Timestamp) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler. Validates the timestamp format during unmarshaling.