This code provides a utility package for generating, managing, and...

September 2, 2025 at 01:09 AM

package utils

import (
	"crypto/rand"
	"encoding/binary"
	"unsafe"
)

// Size is the length in bytes of the ID
const Size = 16

// StringLen is the length of the string representation of ID
const StringLen = 22

// ID is our 128-bit random value
type ID [2]uint64

func (id ID) Bytes() [Size]byte {
	var out [Size]byte

	out[0] = byte(id[0])
	out[1] = byte(id[0] >> 8)
	out[2] = byte(id[0] >> 16)
	out[3] = byte(id[0] >> 24)
	out[4] = byte(id[0] >> 32)
	out[5] = byte(id[0] >> 40)
	out[6] = byte(id[0] >> 48)
	out[7] = byte(id[0] >> 56)

	out[8] = byte(id[1])
	out[9] = byte(id[1] >> 8)
	out[10] = byte(id[1] >> 16)
	out[11] = byte(id[1] >> 24)
	out[12] = byte(id[1] >> 32)
	out[13] = byte(id[1] >> 40)
	out[14] = byte(id[1] >> 48)
	out[15] = byte(id[1] >> 56)

	return out
}

// String returns base64 encoding of our ID
func (id ID) String() string {
	var buf [StringLen]byte
	encodeUnrolled(&buf, id)
	// Directly convert the array to a string without an
	// intermediary slice
	return unsafe.String((*byte)(unsafe.Pointer(&buf)), StringLen)
}

// New generates a new random ID
func New() (ID, error) {
	var id ID
	var bytes [Size]byte
	if _, err := rand.Read(bytes[:]); err != nil {
		return id, err
	}
	id[0] = binary.LittleEndian.Uint64(bytes[0:8])
	id[1] = binary.LittleEndian.Uint64(bytes[8:16])
	return id, nil
}

// vendoring in a bit simpler variant of base64 url encoding
// that removes some extra branches and removes the concept of padding
// We're working with a fixed size and fixed character set.
var encodeMap = [64]byte{
	'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N', 'O', 'P',
	'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z', 'a', 'b', 'c', 'd', 'e', 'f',
	'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v',
	'w', 'x', 'y', 'z', '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', '-', '_',
}

func encodeUnrolled(dst *[StringLen]byte, src ID) {
	// XXX: this is manually unrolled and performance is
	// a few percentage faster, likely the only optimization
	// that can be accomplished here is through ASM and utilizing
	// vectors and probably encode this entire thing in one
	// vector CPU instruction.
	var val uint32

	// Convert 3x 8bit source bytes into 4 bytes
	val = (uint32(byte(src[(0+0)/8]>>((0+0)%8*8)))<<16 |
		uint32(byte(src[(0+1)/8]>>((0+1)%8*8)))<<8 |
		uint32(byte(src[(0+2)/8]>>((0+2)%8*8)))<<0)

	dst[0+0] = encodeMap[val>>18&0x3F]
	dst[0+1] = encodeMap[val>>12&0x3F]
	dst[0+2] = encodeMap[val>>6&0x3F]
	dst[0+3] = encodeMap[val&0x3F]

	// Convert 3x 8bit source bytes into 4 bytes
	val = (uint32(byte(src[(3+0)/8]>>((3+0)%8*8)))<<16 |
		uint32(byte(src[(3+1)/8]>>((3+1)%8*8)))<<8 |
		uint32(byte(src[(3+2)/8]>>((3+2)%8*8)))<<0)

	dst[4+0] = encodeMap[val>>18&0x3F]
	dst[4+1] = encodeMap[val>>12&0x3F]
	dst[4+2] = encodeMap[val>>6&0x3F]
	dst[4+3] = encodeMap[val&0x3F]

	// Convert 3x 8bit source bytes into 4 bytes
	val = (uint32(byte(src[(6+0)/8]>>((6+0)%8*8)))<<16 |
		uint32(byte(src[(6+1)/8]>>((6+1)%8*8)))<<8 |
		uint32(byte(src[(6+2)/8]>>((6+2)%8*8)))<<0)

	dst[8+0] = encodeMap[val>>18&0x3F]
	dst[8+1] = encodeMap[val>>12&0x3F]
	dst[8+2] = encodeMap[val>>6&0x3F]
	dst[8+3] = encodeMap[val&0x3F]

	// Convert 3x 8bit source bytes into 4 bytes
	val = (uint32(byte(src[(9+0)/8]>>((9+0)%8*8)))<<16 |
		uint32(byte(src[(9+1)/8]>>((9+1)%8*8)))<<8 |
		uint32(byte(src[(9+2)/8]>>((9+2)%8*8)))<<0)

	dst[12+0] = encodeMap[val>>18&0x3F]
	dst[12+1] = encodeMap[val>>12&0x3F]
	dst[12+2] = encodeMap[val>>6&0x3F]
	dst[12+3] = encodeMap[val&0x3F]

	// Convert 3x 8bit source bytes into 4 bytes
	val = (uint32(byte(src[(12+0)/8]>>((12+0)%8*8)))<<16 |
		uint32(byte(src[(12+1)/8]>>((12+1)%8*8)))<<8 |
		uint32(byte(src[(12+2)/8]>>((12+2)%8*8)))<<0)

	dst[16+0] = encodeMap[val>>18&0x3F]
	dst[16+1] = encodeMap[val>>12&0x3F]
	dst[16+2] = encodeMap[val>>6&0x3F]
	dst[16+3] = encodeMap[val&0x3F]

	// last byte
	val = uint32(src[1]>>56) << 16
	dst[20+0] = encodeMap[val>>18&0x3F]
	dst[20+1] = encodeMap[val>>12&0x3F]
}

This code provides a utility package for generating, managing, and encoding a unique identifier (ID) using a custom format. Here's a summary of what each component does:

Components Breakdown:

ID Type:
- The ID type is a custom representation of a 128-bit identifier, implemented as an array of two uint64 values ([2]uint64).
- This makes it capable of holding 128 bits of information (64 bits in each array element).
Constants:
- Size: Represents the size (in bytes, 16) of the ID when serialized to raw bytes.
- StringLen: Represents the length (22) of the ID when converted to its custom base64-like string format.
Bytes Method:
- Converts the ID into a byte array of length 16.
- It does so by splitting the two uint64 values into their constituent bytes and placing them in order in a byte array (little-endian format).
String Method:
- Converts the ID into a string representation using a custom base64-like encoding scheme.
- Uses the encodeUnrolled function to perform efficient base64 encoding of the ID into a 22-character string.
- Avoids slice and memory allocations by using direct unsafe casting to a string.
New Function:
- Generates a new random ID.
- It fills a 16-byte array with cryptographically secure random bytes (using the crypto/rand package) and then converts those bytes into the two uint64 values that make up the ID.
encodeUnrolled Function:
- Efficiently performs custom base64 encoding for the ID using a fixed character set (encodeMap).
- Encodes blocks of three bytes from the ID into four encoded characters using the base64-like scheme.
- Avoids padding and ensures computations are optimized (e.g., unrolled loops for performance).
- Produces a total of 22 encoded characters — enough to represent the 128-bit identifier without padding.
Custom Base64 Encoding with encodeMap:
- Defines a custom base64 encoding character set (encodeMap) that replaces padding (=) with a fixed-length encoding.
- The output is URL-safe due to the use of - and _ rather than the + and / characters used in traditional base64.

Overall Purpose:

The code generates a 128-bit random identifier (ID) and provides methods for:

Serializing the identifier into raw bytes (Bytes()).
Converting the identifier into a URL-safe base64-like string with fixed length (String()).

This system is optimized for performance (e.g., by avoiding padding, using unrolled loops for encoding, and minimizing allocations) and can be used in applications requiring compact, unique, and URL-safe identifiers (e.g., tracking IDs, keys for distributed systems, etc.).

Generate your own explanations

Download our vscode extension

Read other generated explanations

Built by @thebuilderjr