uuid.go

Documentation: github.com/google/uuid

     1  // Copyright 2018 Google Inc.  All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  package uuid
     6  
     7  import (
     8  	"bytes"
     9  	"crypto/rand"
    10  	"encoding/hex"
    11  	"errors"
    12  	"fmt"
    13  	"io"
    14  	"strings"
    15  	"sync"
    16  )
    17  
    18  // A UUID is a 128 bit (16 byte) Universal Unique IDentifier as defined in RFC
    19  // 4122.
    20  type UUID [16]byte
    21  
    22  // A Version represents a UUID's version.
    23  type Version byte
    24  
    25  // A Variant represents a UUID's variant.
    26  type Variant byte
    27  
    28  // Constants returned by Variant.
    29  const (
    30  	Invalid   = Variant(iota) // Invalid UUID
    31  	RFC4122                   // The variant specified in RFC4122
    32  	Reserved                  // Reserved, NCS backward compatibility.
    33  	Microsoft                 // Reserved, Microsoft Corporation backward compatibility.
    34  	Future                    // Reserved for future definition.
    35  )
    36  
    37  const randPoolSize = 16 * 16
    38  
    39  var (
    40  	rander      = rand.Reader // random function
    41  	poolEnabled = false
    42  	poolMu      sync.Mutex
    43  	poolPos     = randPoolSize     // protected with poolMu
    44  	pool        [randPoolSize]byte // protected with poolMu
    45  )
    46  
    47  type invalidLengthError struct{ len int }
    48  
    49  func (err invalidLengthError) Error() string {
    50  	return fmt.Sprintf("invalid UUID length: %d", err.len)
    51  }
    52  
    53  // IsInvalidLengthError is matcher function for custom error invalidLengthError
    54  func IsInvalidLengthError(err error) bool {
    55  	_, ok := err.(invalidLengthError)
    56  	return ok
    57  }
    58  
    59  // Parse decodes s into a UUID or returns an error if it cannot be parsed.  Both
    60  // the standard UUID forms defined in RFC 4122
    61  // (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx and
    62  // urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) are decoded.  In addition,
    63  // Parse accepts non-standard strings such as the raw hex encoding
    64  // xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx and 38 byte "Microsoft style" encodings,
    65  // e.g.  {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}.  Only the middle 36 bytes are
    66  // examined in the latter case.  Parse should not be used to validate strings as
    67  // it parses non-standard encodings as indicated above.
    68  func Parse(s string) (UUID, error) {
    69  	var uuid UUID
    70  	switch len(s) {
    71  	// xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
    72  	case 36:
    73  
    74  	// urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
    75  	case 36 + 9:
    76  		if !strings.EqualFold(s[:9], "urn:uuid:") {
    77  			return uuid, fmt.Errorf("invalid urn prefix: %q", s[:9])
    78  		}
    79  		s = s[9:]
    80  
    81  	// {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}
    82  	case 36 + 2:
    83  		s = s[1:]
    84  
    85  	// xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    86  	case 32:
    87  		var ok bool
    88  		for i := range uuid {
    89  			uuid[i], ok = xtob(s[i*2], s[i*2+1])
    90  			if !ok {
    91  				return uuid, errors.New("invalid UUID format")
    92  			}
    93  		}
    94  		return uuid, nil
    95  	default:
    96  		return uuid, invalidLengthError{len(s)}
    97  	}
    98  	// s is now at least 36 bytes long
    99  	// it must be of the form  xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   100  	if s[8] != '-' || s[13] != '-' || s[18] != '-' || s[23] != '-' {
   101  		return uuid, errors.New("invalid UUID format")
   102  	}
   103  	for i, x := range [16]int{
   104  		0, 2, 4, 6,
   105  		9, 11,
   106  		14, 16,
   107  		19, 21,
   108  		24, 26, 28, 30, 32, 34,
   109  	} {
   110  		v, ok := xtob(s[x], s[x+1])
   111  		if !ok {
   112  			return uuid, errors.New("invalid UUID format")
   113  		}
   114  		uuid[i] = v
   115  	}
   116  	return uuid, nil
   117  }
   118  
   119  // ParseBytes is like Parse, except it parses a byte slice instead of a string.
   120  func ParseBytes(b []byte) (UUID, error) {
   121  	var uuid UUID
   122  	switch len(b) {
   123  	case 36: // xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   124  	case 36 + 9: // urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   125  		if !bytes.EqualFold(b[:9], []byte("urn:uuid:")) {
   126  			return uuid, fmt.Errorf("invalid urn prefix: %q", b[:9])
   127  		}
   128  		b = b[9:]
   129  	case 36 + 2: // {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}
   130  		b = b[1:]
   131  	case 32: // xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   132  		var ok bool
   133  		for i := 0; i < 32; i += 2 {
   134  			uuid[i/2], ok = xtob(b[i], b[i+1])
   135  			if !ok {
   136  				return uuid, errors.New("invalid UUID format")
   137  			}
   138  		}
   139  		return uuid, nil
   140  	default:
   141  		return uuid, invalidLengthError{len(b)}
   142  	}
   143  	// s is now at least 36 bytes long
   144  	// it must be of the form  xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   145  	if b[8] != '-' || b[13] != '-' || b[18] != '-' || b[23] != '-' {
   146  		return uuid, errors.New("invalid UUID format")
   147  	}
   148  	for i, x := range [16]int{
   149  		0, 2, 4, 6,
   150  		9, 11,
   151  		14, 16,
   152  		19, 21,
   153  		24, 26, 28, 30, 32, 34,
   154  	} {
   155  		v, ok := xtob(b[x], b[x+1])
   156  		if !ok {
   157  			return uuid, errors.New("invalid UUID format")
   158  		}
   159  		uuid[i] = v
   160  	}
   161  	return uuid, nil
   162  }
   163  
   164  // MustParse is like Parse but panics if the string cannot be parsed.
   165  // It simplifies safe initialization of global variables holding compiled UUIDs.
   166  func MustParse(s string) UUID {
   167  	uuid, err := Parse(s)
   168  	if err != nil {
   169  		panic(`uuid: Parse(` + s + `): ` + err.Error())
   170  	}
   171  	return uuid
   172  }
   173  
   174  // FromBytes creates a new UUID from a byte slice. Returns an error if the slice
   175  // does not have a length of 16. The bytes are copied from the slice.
   176  func FromBytes(b []byte) (uuid UUID, err error) {
   177  	err = uuid.UnmarshalBinary(b)
   178  	return uuid, err
   179  }
   180  
   181  // Must returns uuid if err is nil and panics otherwise.
   182  func Must(uuid UUID, err error) UUID {
   183  	if err != nil {
   184  		panic(err)
   185  	}
   186  	return uuid
   187  }
   188  
   189  // Validate returns an error if s is not a properly formatted UUID in one of the following formats:
   190  //   xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   191  //   urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   192  //   xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   193  //   {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}
   194  // It returns an error if the format is invalid, otherwise nil.
   195  func Validate(s string) error {
   196  	switch len(s) {
   197  	// Standard UUID format
   198  	case 36:
   199  
   200  	// UUID with "urn:uuid:" prefix
   201  	case 36 + 9:
   202  		if !strings.EqualFold(s[:9], "urn:uuid:") {
   203  			return fmt.Errorf("invalid urn prefix: %q", s[:9])
   204  		}
   205  		s = s[9:]
   206  
   207  	// UUID enclosed in braces
   208  	case 36 + 2:
   209  		if s[0] != '{' || s[len(s)-1] != '}' {
   210  			return fmt.Errorf("invalid bracketed UUID format")
   211  		}
   212  		s = s[1 : len(s)-1]
   213  
   214  	// UUID without hyphens
   215  	case 32:
   216  		for i := 0; i < len(s); i += 2 {
   217  			_, ok := xtob(s[i], s[i+1])
   218  			if !ok {
   219  				return errors.New("invalid UUID format")
   220  			}
   221  		}
   222  
   223  	default:
   224  		return invalidLengthError{len(s)}
   225  	}
   226  
   227  	// Check for standard UUID format
   228  	if len(s) == 36 {
   229  		if s[8] != '-' || s[13] != '-' || s[18] != '-' || s[23] != '-' {
   230  			return errors.New("invalid UUID format")
   231  		}
   232  		for _, x := range []int{0, 2, 4, 6, 9, 11, 14, 16, 19, 21, 24, 26, 28, 30, 32, 34} {
   233  			if _, ok := xtob(s[x], s[x+1]); !ok {
   234  				return errors.New("invalid UUID format")
   235  			}
   236  		}
   237  	}
   238  
   239  	return nil
   240  }
   241  
   242  // String returns the string form of uuid, xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   243  // , or "" if uuid is invalid.
   244  func (uuid UUID) String() string {
   245  	var buf [36]byte
   246  	encodeHex(buf[:], uuid)
   247  	return string(buf[:])
   248  }
   249  
   250  // URN returns the RFC 2141 URN form of uuid,
   251  // urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx,  or "" if uuid is invalid.
   252  func (uuid UUID) URN() string {
   253  	var buf [36 + 9]byte
   254  	copy(buf[:], "urn:uuid:")
   255  	encodeHex(buf[9:], uuid)
   256  	return string(buf[:])
   257  }
   258  
   259  func encodeHex(dst []byte, uuid UUID) {
   260  	hex.Encode(dst, uuid[:4])
   261  	dst[8] = '-'
   262  	hex.Encode(dst[9:13], uuid[4:6])
   263  	dst[13] = '-'
   264  	hex.Encode(dst[14:18], uuid[6:8])
   265  	dst[18] = '-'
   266  	hex.Encode(dst[19:23], uuid[8:10])
   267  	dst[23] = '-'
   268  	hex.Encode(dst[24:], uuid[10:])
   269  }
   270  
   271  // Variant returns the variant encoded in uuid.
   272  func (uuid UUID) Variant() Variant {
   273  	switch {
   274  	case (uuid[8] & 0xc0) == 0x80:
   275  		return RFC4122
   276  	case (uuid[8] & 0xe0) == 0xc0:
   277  		return Microsoft
   278  	case (uuid[8] & 0xe0) == 0xe0:
   279  		return Future
   280  	default:
   281  		return Reserved
   282  	}
   283  }
   284  
   285  // Version returns the version of uuid.
   286  func (uuid UUID) Version() Version {
   287  	return Version(uuid[6] >> 4)
   288  }
   289  
   290  func (v Version) String() string {
   291  	if v > 15 {
   292  		return fmt.Sprintf("BAD_VERSION_%d", v)
   293  	}
   294  	return fmt.Sprintf("VERSION_%d", v)
   295  }
   296  
   297  func (v Variant) String() string {
   298  	switch v {
   299  	case RFC4122:
   300  		return "RFC4122"
   301  	case Reserved:
   302  		return "Reserved"
   303  	case Microsoft:
   304  		return "Microsoft"
   305  	case Future:
   306  		return "Future"
   307  	case Invalid:
   308  		return "Invalid"
   309  	}
   310  	return fmt.Sprintf("BadVariant%d", int(v))
   311  }
   312  
   313  // SetRand sets the random number generator to r, which implements io.Reader.
   314  // If r.Read returns an error when the package requests random data then
   315  // a panic will be issued.
   316  //
   317  // Calling SetRand with nil sets the random number generator to the default
   318  // generator.
   319  func SetRand(r io.Reader) {
   320  	if r == nil {
   321  		rander = rand.Reader
   322  		return
   323  	}
   324  	rander = r
   325  }
   326  
   327  // EnableRandPool enables internal randomness pool used for Random
   328  // (Version 4) UUID generation. The pool contains random bytes read from
   329  // the random number generator on demand in batches. Enabling the pool
   330  // may improve the UUID generation throughput significantly.
   331  //
   332  // Since the pool is stored on the Go heap, this feature may be a bad fit
   333  // for security sensitive applications.
   334  //
   335  // Both EnableRandPool and DisableRandPool are not thread-safe and should
   336  // only be called when there is no possibility that New or any other
   337  // UUID Version 4 generation function will be called concurrently.
   338  func EnableRandPool() {
   339  	poolEnabled = true
   340  }
   341  
   342  // DisableRandPool disables the randomness pool if it was previously
   343  // enabled with EnableRandPool.
   344  //
   345  // Both EnableRandPool and DisableRandPool are not thread-safe and should
   346  // only be called when there is no possibility that New or any other
   347  // UUID Version 4 generation function will be called concurrently.
   348  func DisableRandPool() {
   349  	poolEnabled = false
   350  	defer poolMu.Unlock()
   351  	poolMu.Lock()
   352  	poolPos = randPoolSize
   353  }
   354  
   355  // UUIDs is a slice of UUID types.
   356  type UUIDs []UUID
   357  
   358  // Strings returns a string slice containing the string form of each UUID in uuids.
   359  func (uuids UUIDs) Strings() []string {
   360  	var uuidStrs = make([]string, len(uuids))
   361  	for i, uuid := range uuids {
   362  		uuidStrs[i] = uuid.String()
   363  	}
   364  	return uuidStrs
   365  }
   366
View as plain text