oxidecomputer / oxidecomputer/newtype-uuid

Tagged UUID support (serialization format includes tag name)

Open
#8 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Rust
Stars
44
Forks
10
PR merge metrics
No merged PRs in 30d

Description

With something like a typed UUID format, there are several things to consider:

  1. The types within Rust code
  2. The serde serialization format used for our external APIs
  3. The Display and FromStr formats, which are implicitly used in a lot of places (I'd like to retain the property that they're reversible.)
  4. The database storage format.

TypedUuid only changes 1, leaving 2-4 untouched (4 isn't implemented in this crate -- but in omicron we define a DbTypedUuid type which follows the same property).

However, there are good reasons to change 2 and 3 as well, primarily around ensuring that when types are serialized we aren't mixing them up. One way is to define another type called a TaggedUuid. The definition is the same as that of a TypedUuid:

struct TaggedUuid<T: TypedUuidKind> {
    uuid: Uuid,
    marker: PhantomData<T>,
}

But the implementations for 2 and/or 3 above are different and also include T::tag(). For example, a TaggedUuid<SledKind> could be serialized as sled:50a03aaf-8b59-4f4b-a9dc-da6ff6c570be rather than just 50a03aaf-8b59-4f4b-a9dc-da6ff6c570be.

Then, we can allow bidirectional conversions between TypedUuid and TaggedUuid.

At that point, users of the crate can specify what kind of format they want by switching up the types, and make the conversion an explicit, gradual process.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the existing TypedUuid and TypedUuidKind definitions, then trace their serde, Display, and FromStr implementations. Define the scope for TaggedUuid serialization and parsing, preserve reversible formats, and verify bidirectional conversions with the crate's existing tests.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
api
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.