Container Image Reference

A library for using and handling Seaplane Object IDs.

• About
• The Pitch
• The Anti-Pitch
• Example
• License

About

An Object ID (OID) is a base32 (no padding) encoded UUID with a prefix separated by a -.

For example tst-agc6amh7z527vijkv2cutplwaa, by convention the prefix is three ASCII lowercase characters, however that is a hard constraint of OIDs in general. The current implementation limits prefixes to 3 characters, but prefix limit could be exposed as a tunable if that need arises.

The Pitch

OIDs allow a "human readable subject line" in the form of the prefix, where actual data is a UUID. This means while debugging or reviewing a system it's trivial to determine if an incorrect OID was passed in a particular location by looking at the prefix. This isn't easily achievable with bare UUIDs.

Base32 encoding the UUID also allows compressing the data into a smaller and more familiar format for humans, akin to a commit hash.

The Anti-Pitch

The downside to OIDs is a layer of indirection when handling IDs and values, it's not immediately obvious that the OIDs are a prefixed UUID. Additionally, the prefixes must be controlled in some manner including migrated on changes which adds a layer of complexity at the application layer.

There is also additional processing overhead compared to a bare UUID in order to encode/decode as well as handling the appending and removing the prefixes.

However, we believe the drawbacks to pale in comparison to the benefits derived from the format.

Example

use seaplane_oid::{error::*, Oid};

fn main() -> Result<()> {
    // OIDs can be created with a given prefix alone, which generates a new
    // UUID
    let oid = Oid::new("exm")?;
    println!("{oid}");

    // OIDs can be parsed from strings, however the "value" must be a valid
    // base32 encoded UUID
    let oid: Oid = "tst-agc6amh7z527vijkv2cutplwaa".parse()?;
    println!("{oid}");

    // OIDs can also be created from the raw parts
    let oid = Oid::with_uuid(
        "exm",
        "0185e030-ffcf-75fa-a12a-ae8549bd7600"
            .parse::<Uuid>()
            .unwrap(),
    )?;

    // One can retrieve the various parts of the OID if needed
    println!("Prefix: {}", oid.prefix());
    println!("Value: {}", oid.value());
    println!("UUID: {}", oid.uuid());

    Ok(())
}

License

Licensed under the Apache License, Version 2.0, LICENSE. Copyright 2023 Seaplane IO, Inc.