slugid

Documentation

Overview

A go (golang) module for generating v4 UUIDs and encoding them into 22 character URL-safe base64 slug representation (see [RFC 4648 sec. 5](http://tools.ietf.org/html/rfc4648#section-5)).

Slugs are url-safe base64 encoded v4 uuids, stripped of base64 `=` padding.

There are two methods for generating slugs - `slugid.V4()` and `slugid.Nice()`.

V4 Slugs

The `slugid.V4()` method returns a slug from a randomly generated v4 uuid.

Nice slugs

The `slugid.Nice()` method returns a v4 slug which conforms to a set of "nice" properties. At the moment the only "nice" property is that the slug starts with `[A-Za-f]`, which in turn implies that the first (most significant) bit of its associated uuid is set to 0.

The purpose of the `slugid.Nice()` method is to support having slugids which can be used in more contexts safely. Regular slugids can safely be used in urls, and for example in AMQP routing keys. However, slugs beginning with `-` may cause problems when used as command line parameters.

In contrast, slugids generated by the `slugid.Nice()` method can safely be used as command line parameters. This comes at a cost to entropy (121 bits vs 122 bits for regular v4 slugs).

Choosing which slug generation method to use

Slug consumers should consider carefully which of these two slug generation methods to call. Is it more important to have maximum entropy, or to have slugids that do not need special treatment when used as command line parameters? This is especially important if you are providing a service which supplies slugs to unexpecting tool developers downstream, who may not realise the risks of using your regular v4 slugs as command line parameters, especially since this would arise only as an intermittent issue (one time in 64).

Generated slugs take the form `[A-Za-z0-9_-]{22}`, or more precisely:

`slugid.V4()` slugs conform to `[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]`

`slugid.Nice()` slugs conform to `[A-Za-f][A-Za-z0-9_-]{7}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]`

RFC 4122 defines the setting of 6 bits of the v4 UUID which implies v4 slugs provide 128 - 6 = 122 bits entropy. Due to the (un)setting of the first bit of "nice" slugs, nice slugs provide therefore 121 bits entropy.

Index

• func Decode(slug string) uuid.UUID
• func Encode(uuid_ uuid.UUID) string
• func Nice() string
• func V4() string

Examples

• Decode
• Encode
• Nice
• V4

Functions

func Decode

func Decode(slug string) uuid.UUID

Returns the uuid.UUID object represented by the given v4 or "nice" slug, or nil if it cannot be decoded

Example

package main

import (
	"fmt"

	"github.com/taskcluster/slugid-go/slugid"
)

func main() {
	fmt.Printf("%s\n", slugid.Decode("eWIgwMgxSfeXQ36iPbOxiQ"))
}

Output:

796220c0-c831-49f7-9743-7ea23db3b189

func Encode

func Encode(uuid_ uuid.UUID) string

Returns the given uuid.UUID object as a 22 character slug. This can be a regular v4 slug or a "nice" slug.

Example

package main

import (
	"fmt"

	"github.com/pborman/uuid"
	"github.com/taskcluster/slugid-go/slugid"
)

func main() {
	fmt.Println(slugid.Encode(uuid.Parse("796220c0-c831-49f7-9743-7ea23db3b189")))
}

Output:

eWIgwMgxSfeXQ36iPbOxiQ

func Nice

func Nice() string

Returns a randomly generated uuid v4 compliant slug which conforms to a set of "nice" properties, at the cost of some entropy. Currently this means one extra fixed bit (the first bit of the uuid is set to 0) which guarantees the slug will begin with [A-Za-f]. For example such slugs don't require special handling when used as command line parameters (whereas non-nice slugs may start with `-` which can confuse command line tools).

Potentially other "nice" properties may be added in future to further restrict the range of potential uuids that may be generated.

Example

package main

import (
	"github.com/taskcluster/slugid-go/slugid"
)

func main() {
	slugid.Nice() // e.g. "eWIgwMgxSfeXQ36iPbOxiQ"
}

func V4

func V4() string

Returns a randomly generated uuid v4 compliant slug

Example

package main

import (
	"github.com/taskcluster/slugid-go/slugid"
)

func main() {
	slugid.Nice() // e.g. "-9OpXaCORAaFh4sJRk7PUA"
}