lwtime

README

Lacework Time Library

A simple relative and natural time package.

Usage

Download the library into your $GOPATH:

$ go get github.com/lacework/go-sdk/lwtime

Import the library:

import "github.com/lacework/go-sdk/lwtime"

Relative Time Specifiers

Relative times allow you to represent time values dynamically, using specifiers that represent an offset from the current time. For instance, a relative time of -24h produces a date/time that is 24 hours less the current time. Relative times can also snap to a particular time. For instance, a relative time of @d would represent the start of the current day.

For example, to generate a time range (using a start and end time) that represents the previous day:

package main

import (
	"fmt"
    "os"

	"github.com/lacework/go-sdk/lwtime"
)

func main() {
    start, err := lwtime.ParseRelative("-1d@d")
    if err != nil {
		fmt.Println("Unable to parse start time range: %s", err)
        os.Exit(1)
    }
    end, err := lwtime.ParseRelative("@d")
    if err != nil {
		fmt.Println("Unable to parse end time range: %s", err)
        os.Exit(1)
    }
	// Output: The time range is 2023-07-11 07:00:00 +0000 UTC to 2023-07-12 07:00:00 +0000 UTC
    fmt.Printf("The time range is %s to %s\n", start.String(), end.String())
}

A relative time has three components:

• A signed (+/-) integer
• A relative time unit
• A relative time snap

Lacework supports the following relative time units:

• y - year
• mon - month
• w - week
• d - day
• h - hour
• m - minute
• s - second

Additional considerations include:

• To represent the current time, you can specify either now or +0s.
• When specifying an integer and relative time unit, snaps are optional.
• When specifying a snap, the integer and relative time unit are optional. For instance, @d is actually interpreted as +0s@d.

Natural Time Ranges

Natural time ranges allow you to represent time range values using natural language. For instance, a natural time range of yesterday represents a relative start time of -1d@d and a relative end time of @d.

For example, to generate a time range of this month:

package main

import (
	"fmt"
	"os"

	"github.com/lacework/go-sdk/lwtime"
)

func main() {
	start, end, err := lwtime.ParseNatural("this month")
	if err != nil {
		fmt.Println("Unable to parse natural time: %s", err)
		os.Exit(1)
	}
	// The time range is 2023-07-01 07:00:00 +0000 UTC to 2023-07-13 01:23:59.921851 +0000 UTC
	fmt.Printf("The time range is %s to %s\n", start.String(), end.String())
}

A natural time has three components:

• An adjective
• A positive number (only when using the last adjective)
• The full text representation of a relative time unit (i.e., year/years)

Lacework supports the following adjectives (disambiguating previous and last by design):

• this/current
• previous
• last

Additional considerations include:

• last implies "in the last". So last week reads as "in the last week" and represents a start time of -1w and an end time of now.
• previous always snaps. So "previous week" represents a start time of -1w@w and an end time of @w.
• yesterday is a valid natural time and is equivalent to previous day.
• today is a valid natural time and is equivalent to this day or current day.

Examples

Look at the _examples/ folder for more examples.

Documentation

Overview

A simple relative and natural time package.

Index

• Constants
• func ParseNatural(n string) (time.Time, time.Time, error)
• func ParseRelative(s string) (time.Time, error)
• type Epoch
  • func (epoch Epoch) Format(s string) string
  • func (epoch Epoch) MarshalJSON() ([]byte, error)
  • func (epoch *Epoch) String() string
  • func (epoch Epoch) ToTime() time.Time
  • func (epoch Epoch) UTC() time.Time
  • func (epoch *Epoch) UnmarshalJSON(b []byte) error
• type EpochString
  • func (epoch EpochString) Format(s string) string
  • func (epoch *EpochString) MarshalJSON() ([]byte, error)
  • func (epoch EpochString) ToTime() time.Time
  • func (epoch EpochString) UTC() time.Time
  • func (epoch *EpochString) UnmarshalJSON(b []byte) error
• type NanoTime
  • func (nano NanoTime) Format(s string) string
  • func (nano NanoTime) MarshalJSON() ([]byte, error)
  • func (nano NanoTime) ToTime() time.Time
  • func (nano NanoTime) UTC() time.Time
  • func (nano *NanoTime) UnmarshalJSON(b []byte) (err error)
• type RFC1123Z
  • func (rfc RFC1123Z) Format(s string) string
  • func (rfc *RFC1123Z) MarshalJSON() ([]byte, error)
  • func (rfc RFC1123Z) ToTime() time.Time
  • func (rfc RFC1123Z) UTC() time.Time
  • func (rfc *RFC1123Z) UnmarshalJSON(b []byte) (err error)

Constants

const (
	Today     naturalAdjective = "today"
	Yesterday naturalAdjective = "yesterday"
	This      naturalAdjective = "this"
	Current   naturalAdjective = "current"
	Previous  naturalAdjective = "previous"
	Last      naturalAdjective = "last"
)

const (
	Year        relativeUnit = "y"
	Month       relativeUnit = "mon"
	Week        relativeUnit = "w"
	Day         relativeUnit = "d"
	Hour        relativeUnit = "h"
	Minute      relativeUnit = "m"
	Second      relativeUnit = "s"
	HoursInADay              = 24
)

const (
	RFC3339Milli = "2006-01-02T15:04:05.000Z"
)

Functions

func ParseNatural

func ParseNatural(n string) (time.Time, time.Time, error)

ParseNatural parses the string representation of a Lacework natural time Start and End time objects are returned in UTC

start, end, err := lwtime.ParseNatural("this year")
if err != nil {
	...
}

func ParseRelative

func ParseRelative(s string) (time.Time, error)

ParseRelative parses the string representation of a Lacework relative time. Time object is returned in UTC.

t, err := lwtime.ParseRelative("-1y@y")
if err != nil {
	...
}

Types

type Epoch

type Epoch time.Time

Epoch time type to parse the returned 13 digit time in milliseconds

func (Epoch) Format

func (epoch Epoch) Format(s string) string

func (Epoch) MarshalJSON

func (epoch Epoch) MarshalJSON() ([]byte, error)

func (*Epoch) String

func (epoch *Epoch) String() string

func (Epoch) ToTime

func (epoch Epoch) ToTime() time.Time

func (Epoch) UTC

func (epoch Epoch) UTC() time.Time

func (*Epoch) UnmarshalJSON

func (epoch *Epoch) UnmarshalJSON(b []byte) error

type EpochString

type EpochString time.Time

EpochString time type to parse the returned 13 digit time in milliseconds. Used instead of Epoch type when unmarshalling a json response where epoch time is a string.

func (EpochString) Format

func (epoch EpochString) Format(s string) string

func (*EpochString) MarshalJSON

func (epoch *EpochString) MarshalJSON() ([]byte, error)

func (EpochString) ToTime

func (epoch EpochString) ToTime() time.Time

func (EpochString) UTC

func (epoch EpochString) UTC() time.Time

func (*EpochString) UnmarshalJSON

func (epoch *EpochString) UnmarshalJSON(b []byte) error

type NanoTime

type NanoTime time.Time

NanoTime time type to parse the returned time with nano format

Example: "2020-08-20T01:00:00+0000"

func (NanoTime) Format

func (nano NanoTime) Format(s string) string

func (NanoTime) MarshalJSON

func (nano NanoTime) MarshalJSON() ([]byte, error)

func (NanoTime) ToTime

func (nano NanoTime) ToTime() time.Time

func (NanoTime) UTC

func (nano NanoTime) UTC() time.Time

func (*NanoTime) UnmarshalJSON

func (nano *NanoTime) UnmarshalJSON(b []byte) (err error)

type RFC1123Z

type RFC1123Z time.Time

func (RFC1123Z) Format

func (rfc RFC1123Z) Format(s string) string

func (*RFC1123Z) MarshalJSON

func (rfc *RFC1123Z) MarshalJSON() ([]byte, error)

func (RFC1123Z) ToTime

func (rfc RFC1123Z) ToTime() time.Time

func (RFC1123Z) UTC

func (rfc RFC1123Z) UTC() time.Time

func (*RFC1123Z) UnmarshalJSON

func (rfc *RFC1123Z) UnmarshalJSON(b []byte) (err error)