uuid

Documentation

Overview

Package uuid provides a wrapper for handling UUID codes.

Index

• Variables
• func NodeID() string
• func Normalize(u *UUID)
• func SetRandomNodeID()
• func Within(ttl time.Duration) validation.Rule
• type Identify
  • func IdentifyParse(s string) Identify
  • func IdentifyV1() Identify
  • func IdentifyV3(ns UUID, data []byte) Identify
  • func IdentifyV4() Identify
  • func IdentifyV5(ns UUID, data []byte) Identify
  • func IdentifyV6() Identify
  • func IdentifyV7() Identify
  • func (d *Identify) GetUUID() UUID
  • func (d *Identify) SetUUID(id UUID)
• type UUID
  • func MakeV1() UUID
  • func MakeV3(space UUID, data []byte) UUID
  • func MakeV4() UUID
  • func MakeV5(space UUID, data []byte) UUID
  • func MustParse(s string) UUID
  • func NewV1() *UUID
  • func NewV3(space UUID, data []byte) *UUID
  • func NewV4() *UUID
  • func NewV5(space UUID, data []byte) *UUID
  • func Parse(s string) (UUID, error)
  • func ParseBase64(s string) (UUID, error)
  • func ShouldParse(s string) UUID
  • func V1() UUID
  • func V3(space UUID, data []byte) UUID
  • func V4() UUID
  • func V5(space UUID, data []byte) UUID
  • func V6() UUID
  • func V7() UUID
  • func (u UUID) Base64() string
  • func (u *UUID) IsZero() bool
  • func (UUID) JSONSchemaExtend(s *jsonschema.Schema)
  • func (u UUID) String() string
  • func (u UUID) Timestamp() time.Time
  • func (u *UUID) UnmarshalText(txt []byte) error
  • func (u UUID) Validate() error
  • func (u UUID) Version() Version
• type Version

Variables

var (
	// Valid confirms the UUID is valid
	Valid = versionRule{}
	// IsV1 confirms the UUID is version 1
	IsV1 = versionRule{/* contains filtered or unexported fields */}
	// IsV3 confirms the UUID is version 3
	IsV3 = versionRule{/* contains filtered or unexported fields */}
	// IsV4 confirms the UUID is version 4
	IsV4 = versionRule{/* contains filtered or unexported fields */}
	// IsV5 confirms the UUID is version 5
	IsV5 = versionRule{/* contains filtered or unexported fields */}
	// IsV6 confirms the UUID is version 6
	IsV6 = versionRule{/* contains filtered or unexported fields */}
	// IsV7 confirms the UUID is version 7
	IsV7 = versionRule{/* contains filtered or unexported fields */}
	// HasTimestamp confirms the UUID is based on a timestamp version
	HasTimestamp = versionRule{/* contains filtered or unexported fields */}
	// Timeless confirms the UUID is not based on a timestamp version
	Timeless = versionRule{/* contains filtered or unexported fields */}
	// IsNotZero confirms the UUID is not zero
	IsNotZero = versionRule{/* contains filtered or unexported fields */}
)

Functions

func NodeID

func NodeID() string

NodeID returns the hex representation of the current host bytes

func Normalize

func Normalize(u *UUID)

Normalize will ensure that zero value UUIDs will be empty strings instead of zeros.

func SetRandomNodeID

func SetRandomNodeID()

SetRandomNodeID is used to generate a random host ID to be used in V1 UUIDs instead of the MAC address. This is stored in the uuid library as a global constant, so should be called just once when starting the application if you're intending to generate V1 UUIDs to get a node ID that won't change.

func Within

func Within(ttl time.Duration) validation.Rule

Within is a validation method that can be used to determine if the UUID is version 1, 6, or 7 and contains a timestamp that is greater than the current time minus the ttl. A tolerance is allowed for future timestamps.

Types

type Identify

type Identify struct {
	UUID UUID `json:"uuid,omitempty" jsonschema:"title=UUID,description=Universally Unique Identifier."`
}

Identify defines a struct that can be used to identify a document by a UUID.

func IdentifyParse

func IdentifyParse(s string) Identify

IdentifyParse will parse the provided string as a UUID in the UUID field, or panic. This is mainly meant to be used in tests.

func IdentifyV1

func IdentifyV1() Identify

IdentifyV1 is a helper method to generate a version 1 uuid ready to embed.

func IdentifyV3

func IdentifyV3(ns UUID, data []byte) Identify

IdentifyV3 is a helper method to generate a version 3 uuid ready to embed.

func IdentifyV4

func IdentifyV4() Identify

IdentifyV4 is a helper method to generate a version 4 uuid ready to embed.

func IdentifyV5

func IdentifyV5(ns UUID, data []byte) Identify

IdentifyV5 is a helper method to generate a version 5 uuid ready to embed.

func IdentifyV6

func IdentifyV6() Identify

IdentifyV6 is a helper method to generate a version 6 uuid ready to embed.

func IdentifyV7

func IdentifyV7() Identify

IdentifyV7 is a helper method to generate a version 7 uuid ready to embed.

func (*Identify) GetUUID

func (d *Identify) GetUUID() UUID

GetUUID returns the UUID of the document.

func (*Identify) SetUUID

func (d *Identify) SetUUID(id UUID)

SetUUID sets the UUID of the document.

type UUID

type UUID string

UUID defines a string wrapper for dealing with UUIDs using the google uuid package for parsing and specific method support. This implementation has been optimized for convenience and JSON conversion as opposed to performance.

Note that this package is not registered inside its own schema. We instead rely on the `"format"` parameter already included in JSON Schema.

const (
	Empty UUID = ""
	Zero  UUID = "00000000-0000-0000-0000-000000000000"
)

Constants for empty and zero states.

func MakeV1

func MakeV1() UUID

MakeV1 generates a version 1 UUID.

Deprecated: use V1() instead.

func MakeV3

func MakeV3(space UUID, data []byte) UUID

MakeV3 generates a new UUIDv3 using the provided namespace and data. The behavior is deterministic, that is, the same inputs will always generate the same UUID. This is handy to transform any other types of IDs into UUIDs, among other uses.

In UUIDv3, the data is hashed using MD5 which is a performant algorithm, but is subject to collision attacks and other vulnerabilities. If security is a concern, use UUIDv5 instead.

Deprecated: use V3() instead.

func MakeV4

func MakeV4() UUID

MakeV4 generates a new completely random UUIDv4.

Deprecated: use V4() instead.

func MakeV5

func MakeV5(space UUID, data []byte) UUID

MakeV5 generates a new UUIDv5 using the provided namespace and data. The behavior is deterministic, that is, the same inputs will always generate the same UUID. This is handy to transform any other types of IDs into UUIDs, among other uses.

In UUIDv5, the data is hashed using SHA1, a secure algorithm but slower than MD5. If you don't need the security of SHA1 and performance is a concern, use UUIDv3 instead.

Deprecated: use V5() instead.

func MustParse

func MustParse(s string) UUID

MustParse will panic if the UUID does not look good.

func NewV1

func NewV1() *UUID

NewV1 generates a version 1 UUID.

Deprecated: Use V1() instead.

func NewV3

func NewV3(space UUID, data []byte) *UUID

NewV3 creates a new MD5 UUID using the provided namespace and data. See MakeV3 for more details.

Deprecated: Use V3() instead.

func NewV4

func NewV4() *UUID

NewV4 creates a pointer a new completely random UUIDv4.

Deprecated: Use V4() instead.

func NewV5

func NewV5(space UUID, data []byte) *UUID

NewV5 creates a new SHA1 UUID using the provided namespace and data. See MakeV5 for more details.

Deprecated: Use V5() instead

func Parse

func Parse(s string) (UUID, error)

Parse decodes s into a UUID or provides an error.

func ParseBase64

func ParseBase64(s string) (UUID, error)

ParseBase64 will attempt to decode a Base64 string into a UUID. If the string is already a regular UUID, it will be parsed and returned using the regular Parse method.

func ShouldParse

func ShouldParse(s string) UUID

ShouldParse will return a UUID if the string is valid, otherwise it will provide a zero UUID.

func V1

func V1() UUID

V1 generates a version 1 UUID. We strongly recommend using V7 now as an alternative as it provides the same functionality with a more secure random node ID.

func V3

func V3(space UUID, data []byte) UUID

V3 generates a new UUIDv3 using the provided namespace and data. The behavior is deterministic, that is, the same inputs will always generate the same UUID. This is handy to transform any other types of IDs into UUIDs, among other uses.

In UUIDv3, the data is hashed using MD5 which is a performant algorithm, but is subject to collision attacks and other vulnerabilities. If security is a concern, use UUIDv5 instead.

func V4

func V4() UUID

V4 generates a new completely random UUIDv4.

func V5

func V5(space UUID, data []byte) UUID

V5 generates a new UUIDv5 using the provided namespace and data. The behavior is deterministic, that is, the same inputs will always generate the same UUID. This is handy to transform any other types of IDs into UUIDs, among other uses.

In UUIDv5, the data is hashed using SHA1, a secure algorithm but slower than MD5. If you don't need the security of SHA1 and performance is a concern, use UUIDv3 instead.

func V6

func V6() UUID

V6 generates a version 6 UUID, a drop-in replaced for V1 UUIDs that uses random data instead of node. It maintains a similar structure to V1 UUIDs with the timestamp, so no ordering is maintained.

func V7

func V7() UUID

V7 generates a new UUIDv7, a replacement for V1 or V6 UUIDs which combines the Unix timestamp with millisecond precision and random data. An important difference with other versions is that order is maintained, making this a great option for primary keys in databases.

func (UUID) Base64

func (u UUID) Base64() string

Base64 returns a compact URL-safe Base64 string of the UUID as opposed to the regular hex representation. This can be used for prettier and shorter URLs and is completely reversible.

func (*UUID) IsZero

func (u *UUID) IsZero() bool

IsZero returns true if the UUID is all zeros or empty.

func (UUID) JSONSchemaExtend

func (UUID) JSONSchemaExtend(s *jsonschema.Schema)

JSONSchemaExtend ensures the schema contains the additional UUID format wherever it is used.

func (UUID) String

func (u UUID) String() string

String provides the string representation of the UUID.

func (UUID) Timestamp

func (u UUID) Timestamp() time.Time

Timestamp extracts the time. Anything other than a version 1, 6, or 7 UUID will provide zero time without an error, so ensure your error checks are performed previously.

func (*UUID) UnmarshalText

func (u *UUID) UnmarshalText(txt []byte) error

UnmarshalText will ensure the UUID is always a valid UUID when unmarshalling and just return an empty value if incorrect. TODO: Remove this and instead depend on validation to provide more readable errors.

func (UUID) Validate

func (u UUID) Validate() error

Validate checks to ensure the value is a UUID

func (UUID) Version

func (u UUID) Version() Version

Version returns the version number of the UUID.

type Version

type Version byte

Version represents the version number of the UUID