Crate seaplane_oid

source ·
Expand description

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};
use uuid::Uuid;

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, Copyright 2023 Seaplane IO, Inc.

Modules

Defines the convenience Result type and Error type

Structs

An Object ID
An OID Prefix designed to be similar to a human readable “subject line” for the ID
A Typed Object ID where the Prefix is part of the type

Traits