Puid

Simple, fast, flexible and efficient generation of probably unique identifiers (puid, aka random strings) of intuitively specified entropy using predefined or custom characters.

import Puid

let alphaId = try Puid(total: 1e5, risk: 1e12, chars: .alpha)
try alphaId.generate()
// => "uTJtdTPQFk"

Overview

Puid provides full, explicit control over all important facets of random ID generation: entropy source, characters, and desired randomness. A general overview details information relevant to all PUID implementations.

TOC

Usage

Creating a random ID generator using Puid is a simple as:

import Puid

let sessionId = try Puid()
try sessionId.generate()
// => "1Uyt1bj-cAgsHRpWjyPya6"

Options allow easy and complete control over random ID generation. The above example uses the default for each of:

entropy source: Cryptographically strong random bytes
characters: File system & URL safe characters
randomness: 128 bits of entropy

These defaults are suitable for web session IDs.

TOC

Entropy Source

Puid provides a CSPRNG entropy source (Puid.Entropy.System.csprng, using SecCopyRandomBytes) and a PRNG entropy source (Puid.Entropy.System.prng, using UInt64.random) via the entropy option:

let prngId = try Puid(entropy: .prng)
try prngId.generate()
// => "WONlvSz5wRzw6GUz1LqDTK"

The entropy option can also designate any implementation of the PuidEntropySource protocol for using a custom entropy source:

let fixedBytes = Puid.Entropy.Fixed(hex: "d0 52 91 fd 13 62 16 fc bc 52 57 d1 a9 17 42 bf bf")
let fixedId = try Puid(entropy: fixedBytes)
try fixedId.generate()
// => "0FKR_RNiFvy8UlfRqRdCv7"

Note: The Puid.Entropy.Fixed source is convenient for deterministic testing but not suitable for general use.

A convenience class, Puid.Entropy.Source, provides a means of using any RandomNumberGenerator implementation as a PuidEntropySource. If, for example, you had a favorite PRNG, say FavePrng, that generates a repeatable sequence of random UInt64 numbers via an initialization seed, you could use that PRNG as an entropy source:

let favePrng = Puid.Entropy.Source(using: FavePrng(seed: 42))
let prngId = try Puid(entropy: favePrng)
try prngId.generate()
// => A puid generated using bytes from the custom FavePrng entropy source

TOC

Characters

The characters used in ID generation are designated using the chars option. Puid provides 17 predefined characters sets, as well as an option to specify any set of unique characters:

let alphaNumId = try Puid(chars: .alphaNum)
try alphaNumId.generate()
// => "cjm7wFkJQW5igrWUdjFnaA"

let customId = try Puid(chars: .custom("customID_CHARS"))
try customId.generate()
// => "oRmcAACtHsuAIuDSsooItACHIICo_S_IHo"

Note: Puid validates that the custom chars are unique to maximizes the entropy captured during ID generation.

TOC

Randomness

A critical aspect of random ID generation is, of course, the randomness of the IDs generated. Puid provides direct specification of ID randomness via the bits option for situations like session IDs (which are recommended to be 128-bit) or for 256-bit security tokens. But a more general, intuitive declaration of randomness is to explicitly specify the total number of IDs actually needed and assign an acceptable risk of repeat:

let randId = try Puid(total: 1e5, risk: 1e12, chars: .safe32)
try randId.generate()
// => "dqHqFD79QGd2TNP"

In the above example, a total of 100,000 IDs can be generated with a 1 in a trillion risk of repeat. Remember, all random ID generation has an inherent risk of repeat. There is simply no such thing as a univerally unique ID, regardless of the UUID moniker. Rather than blindly use one-size-fits-all (which, for UUID, may be better described as an inefficient, one-size-fits-none solution), Puid allows full control so that risk can be explicitly declared as appropriate for specific application need.

For those instances where bits of entropy is explicitly known:

let token = try Puid(bits: 256, chars: .hexUpper)
try token.generate()
// => "3AE2F836FB09E4D32850ABBA3A20A510B8F47D5CB8EA7CF6BFF10DE58F8FA7BD"

TOC

Predefined Characters

The Puid.Chars enum includes 17 predefined character sets:

Name	Characters
.alpha	ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz
.alphaLower	abcdefghijklmnopqrstuvwxyz
.alphaUpper	ABCDEFGHIJKLMNOPQRSTUVWXYZ
.alphaNum	ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789
.alphaNumLower	abcdefghijklmnopqrstuvwxyz0123456789
.alphaNumUpper	ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789
.base32	ABCDEFGHIJKLMNOPQRSTUVWXYZ234567
.base32Hex	0123456789abcdefghijklmnopqrstuv
.base32HexUpper	0123456789ABCDEFGHIJKLMNOPQRSTUV
.crockford32	0123456789ABCDEFGHJKMNPQRSTVWXYZ
.decimal	0123456789
.hex	0123456789abcdef
.hexUpper	0123456789ABCDEF
.safeSscii	!#$%&()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[]^_abcdefghijklmnopqrstuvwxyz{\|}~
.safe32	2346789bdfghjmnpqrtBDFGHJLMNPQRT
.safe64	ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_
.symbol	!#$%&()*+,-./:;<=>?@[]^_{\|}~

Puid.Chars.custom(String) provides a mechanism to use any String of up to 256 unique characters for ID generation.

TOC

Installation

Swift Package Manager URL: https://github.com/puid/Swift-puid

TOC

License

MIT license. See LICENSE.