uuid

README

A Go package for generating and manipulating UUIDs

 

Generate, encode, and decode UUIDs v1, as defined in RFC 4122, in Go.

Project Status

v1.1.0 Stable: Guaranteed no breaking changes to the API in future v1.x releases. Probably safe to use in production, though provided on "AS IS" basis.

This package is being actively maintained. If you encounter any problems or have any suggestions for improvement, please open an issue. Pull requests are welcome.

Overview

Package uuid implements generation and manipulation of UUIDs (v1 defined in RFC 4122).

Version 1 UUIDs are time-based and include a node identifier that can be a MAC address or a random 48-bit value.

This package uses the random approach for the node identifier, setting both the 'multicast' and 'local' bits to make sure the value cannot be confused with a real IEEE 802 address (see section 4.5 of RFC 4122). The initial node identifier is a cryptographic-quality random 46-bit value. The first 30 bits can be set and retrieved with the SetNodeId and NodeId functions and method, so that they can be used as a hard-coded instance id. The remaining 16 bits are reserved for increasing the randomness of the UUIDs and to avoid collisions on clock sequence rollovers.

The basic generator New increments the clock sequence on every call and when the counter rolls over the last 16 bits of the node identifier are regenerated using a PRNG seeded at init()-time with the initial node identifier. This approach sacrifices cryptographic quality for speed and for avoiding depletion of the OS entropy pool (yes, it can and does happen).

The NewCrypto generator replaces the clock sequence and last 16 bits of the node identifier on each call with cryptographic-quality random values.

Installation

go get github.com/agext/uuid

License

Package uuid is released under the Apache 2.0 license. See the LICENSE file for details.

Documentation

Overview

Package uuid implements generation and manipulation of UUIDs (v1 defined in RFC 4122).

Version 1 UUIDs are time-based and include a node identifier that can be a MAC address or a random 48-bit value.

This package uses the random approach for the node identifier, setting both the 'multicast' and 'local' bits to make sure the value cannot be confused with a real IEEE 802 address (see section 4.5 of RFC 4122). The initial node identifier is a cryptographic-quality random 46-bit value. The first 30 bits can be set and retrieved with the `SetNodeId` and `NodeId` functions and method, so that they can be used as a hard-coded instance id. The remaining 16 bits are reserved for increasing the randomness of the UUIDs and to avoid collisions on clock sequence rollovers.

The basic generator `New` increments the clock sequence on every call and when the counter rolls over the last 16 bits of the node identifier are regenerated using a PRNG seeded at init()-time with the initial node identifier. This approach sacrifices cryptographic quality for speed and for avoiding depletion of the OS entropy pool (yes, it can and does happen).

The `NewCrypto` generator replaces the clock sequence and last 16 bits of the node identifier on each call with cryptographic-quality random values.

Index

• Variables
• func NodeId() uint32
• func SetNodeId(nodeId uint32) error
• type Base64Encoder
  • func (e Base64Encoder) Encode(src []byte) (out []byte)
  • func (e Base64Encoder) EncodeToString(src []byte) (out string)
• type Encoder
• type EncoderToString
• type UUID
  • func New() UUID
  • func NewCrypto() UUID
  • func NewFromBytes(b []byte) (UUID, error)
  • func NewFromString(s string) (UUID, error)
  • func (u UUID) Encode(e Encoder) []byte
  • func (u UUID) EncodeToString(e EncoderToString) string
  • func (u UUID) Hex() string
  • func (u UUID) MarshalJSON() ([]byte, error)
  • func (u UUID) NodeId() uint32
  • func (u UUID) String() string
  • func (u UUID) Time() time.Time
  • func (u *UUID) UnmarshalJSON(b []byte) error
  • func (u UUID) Variant() int
  • func (u UUID) Version() int

Variables

var (
	// Base64URLEncoder uses Base64 URL Encoding
	Base64URLEncoder = Base64Encoder{base64.RawURLEncoding}
	// Base64StdEncoder uses Base64 Std Encoding
	Base64StdEncoder = Base64Encoder{base64.RawStdEncoding}
)

Functions

func NodeId

func NodeId() uint32

NodeId returns the current node id used to generate UUIDs.

func SetNodeId

func SetNodeId(nodeId uint32) error

SetNodeId sets the bits corresponding to the node id. Any unsigned 32-bit integer is accepted and the operation is always successful, but only the least significant 30 bits are used. An error is returned if the discarded, most significant 2 bits are non-zero.

Types

type Base64Encoder

type Base64Encoder struct {
	Enc *base64.Encoding
}

Base64Encoder is a wrapper around any encoding/base64.Encoding to satisfy Encoder and EncoderToString.

func (Base64Encoder) Encode

func (e Base64Encoder) Encode(src []byte) (out []byte)

Encode encodes the source to a byte slice using the encoding/base64.Encoding set on the receiver.

func (Base64Encoder) EncodeToString

func (e Base64Encoder) EncodeToString(src []byte) (out string)

EncodeToString encodes the source to a string using the encoding/base64.Encoding set on the receiver.

type Encoder

type Encoder interface {
	Encode([]byte) []byte
}

Encoder implementations provide a method of encoding a UUID into a byte slice.

type EncoderToString

type EncoderToString interface {
	EncodeToString([]byte) string
}

EncoderToString implementations provide a method of encoding a UUID into a string.

type UUID

type UUID []byte

UUID is a byte-encoded sequence in the following form:

0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                          time_low                             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|       time_mid                |         time_hi_and_version   |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|clk_seq_hi_res |  clk_seq_low  |         node (0-1)            |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                         node (2-5)                            |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Field                  Data Type     Octet  Note
                                     #

time_low               unsigned 32   0-3    The low field of the
                       bit integer          timestamp

time_mid               unsigned 16   4-5    The middle field of the
                       bit integer          timestamp

time_hi_and_version    unsigned 16   6-7    The high field of the
                       bit integer          timestamp multiplexed
                                            with the version number

clock_seq_hi_res       unsigned 8    8      The high field of the
                       bit integer          clock sequence
                                            multiplexed with the
                                            variant

clock_seq_low          unsigned 8    9      The low field of the
                       bit integer          clock sequence

node                   unsigned 48   10-15  The spatially unique
                       bit integer          node identifier

see http://www.ietf.org/rfc/rfc4122.txt section 4.1.2

func New

func New() UUID

New creates a new UUID v1 from the current time, clock sequence and node identifier.

func NewCrypto

func NewCrypto() UUID

NewCrypto creates a new UUID v1 from the current time, with cryptographic-quality random clock sequence and last 16 bits of the node identifier.

func NewFromBytes

func NewFromBytes(b []byte) (UUID, error)

NewFromBytes creates a UUID from a slice of byte; mostly useful for copying UUIDs.

func NewFromString

func NewFromString(s string) (UUID, error)

NewFromString creates a UUID from a dash-separated hex string

func (UUID) Encode

func (u UUID) Encode(e Encoder) []byte

Encode formats the receiver UUID using the provided Encoder.

func (UUID) EncodeToString

func (u UUID) EncodeToString(e EncoderToString) string

EncodeToString formats the receiver UUID using the provided EncodeToString.

func (UUID) Hex

func (u UUID) Hex() string

Hex formats the receiver UUID as a hex string.

func (UUID) MarshalJSON

func (u UUID) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

func (UUID) NodeId

func (u UUID) NodeId() uint32

NodeId extracts the node id from the receiver UUID.

func (UUID) String

func (u UUID) String() string

String formats the receiver UUID as a dash-separated hex string.

func (UUID) Time

func (u UUID) Time() time.Time

Time extracts the time from the receiver UUID as time.Time.

func (*UUID) UnmarshalJSON

func (u *UUID) UnmarshalJSON(b []byte) error

UnmarshalJSON implements the json.Unmarshaler interface.

func (UUID) Variant

func (u UUID) Variant() int

Variant extracts the variant of the receiver UUID.

The following table lists the contents of the variant field, where the letter "x" indicates a "don't-care" value.

Msb0  Msb1  Msb2  Description

 0     x     x    Reserved, NCS backward compatibility.

 1     0     x    The variant specified in this document.

 1     1     0    Reserved, Microsoft Corporation backward
                  compatibility

 1     1     1    Reserved for future definition.

see http://www.ietf.org/rfc/rfc4122.txt section 4.1.1

func (UUID) Version

func (u UUID) Version() int

Version extracts the version of the receiver UUID.

The following table lists the currently-defined versions for this UUID variant.

Msb0  Msb1  Msb2  Msb3   Version  Description

 0     0     0     1        1     The time-based version
                                  specified in this document.

 0     0     1     0        2     DCE Security version, with
                                  embedded POSIX UIDs.

 0     0     1     1        3     The name-based version
                                  specified in this document
                                  that uses MD5 hashing.

 0     1     0     0        4     The randomly or pseudo-
                                  randomly generated version
                                  specified in this document.

 0     1     0     1        5     The name-based version
                                  specified in this document
                                  that uses SHA-1 hashing.

see http://www.ietf.org/rfc/rfc4122.txt section 4.1.3