Identity (TypeID)

Every entity in Ctrl Plane has a TypeID. TypeIDs are globally unique, sortable, URL-safe identifiers built on UUIDv7 with a human-readable prefix that tells you what kind of entity you're looking at.

A TypeID looks like this:

inst_01h455vb4pex5vsknk084sn02q

The inst prefix identifies this as an instance. The suffix is a base32-encoded UUIDv7 that encodes creation time, so IDs sort chronologically.

Why TypeID

Plain UUIDs are opaque. If you see 550e8400-e29b-41d4-a716-446655440000 in a log line, you have no idea what it refers to. With TypeIDs, inst_01h455vb... is immediately recognizable as an instance, dep_01h455vb... as a deployment, and ten_01h455vb... as a tenant.

TypeIDs also use UUIDv7 instead of UUIDv4, which means they encode creation time and sort chronologically. This gives better database index performance and eliminates the need for a separate created_at column in range queries.

The id package

The id package wraps the TypeID Go library with a thin API tailored for Ctrl Plane.

Creating IDs

Every call to id.New() requires a prefix:

import "github.com/xraph/ctrlplane/id"

instanceID := id.New(id.PrefixInstance)    // inst_01h455vb4pex5vsknk084sn02q
deployID   := id.New(id.PrefixDeployment)  // dep_01h455vb4pex5vsknk084sn02q
tenantID   := id.New(id.PrefixTenant)      // ten_01h455vb4pex5vsknk084sn02q

Parsing IDs

Parse any TypeID string:

parsed, err := id.Parse("inst_01h455vb4pex5vsknk084sn02q")

Parse with prefix validation (rejects IDs with the wrong prefix):

parsed, err := id.ParseWithPrefix("inst_01h455vb...", id.PrefixInstance)  // ok
parsed, err := id.ParseWithPrefix("dep_01h455vb...", id.PrefixInstance)   // error

Nil ID

The zero value of id.ID is the nil ID. Use it to represent "no value":

var empty id.ID
empty.IsNil()  // true
empty.String() // ""

id.Nil.IsNil() // true

Database storage

id.ID implements database/sql's Scanner and driver.Valuer interfaces. It stores as a string in the database and returns NULL for nil IDs:

// In a struct with db tags
type Instance struct {
    ID             id.ID  `db:"id"`
    CurrentRelease id.ID  `db:"current_release"` // nullable
}

JSON serialization

id.ID implements encoding.TextMarshaler and encoding.TextUnmarshaler. It serializes to the string form and deserializes back:

{
  "id": "inst_01h455vb4pex5vsknk084sn02q",
  "current_release": "rel_01h455vb4pex5vsknk084sn02q"
}

Nil IDs serialize as empty strings.

Prefix reference

Every entity type in Ctrl Plane has a dedicated prefix constant: