OrderlyID

OrderlyID is a sophisticated identifier format designed for modern distributed systems, providing a typed, time-sortable globally unique identifier with optional checksum and fields for tenancy and sharding. It addresses the common pitfalls associated with existing solutions like UUIDv4 and INT IDs, enhancing both safety and developer ergonomics in public APIs, logs, and distributed environments.

Key Features

• Typed Identifiers: Each OrderlyID begins with a human-readable type prefix, such as order_... or user_..., improving context in logs and making it easier to identify the nature of each ID.
• K-sortable: OrderlyID maintains a lexicographic order that closely approximates creation time, making it easier to sort in databases and queries.
• Global Uniqueness: Each identifier is designed to be safely generated across various services and regions, eliminating the need for central sequencing.
• Developer Ergonomics: With its self-describing structure and supportive features, OrderlyID enhances the development experience.
• Optional Checksum: An additional checksum can be included to help catch errors from copy and paste mistakes.

Comparison with Existing ID Methods

Against AUTO_INCREMENT:

• Avoids reliance on database round-trips or central sequences, which can lead to performance bottlenecks and predictable patterns that compromise security.
• Enhances flexibility for sharding and offline generation.

Against UUIDv4:

• Provides a time-sortable format, reducing the necessity for additional timestamps or indexes.
• Incorporates type context, making logs and identification easier.

Practical Use Cases

• Improved Logging: Searching through logs is more efficient with identifiable prefixes (e.g., shipment_...) as opposed to random hex values.
• Cursor Pagination: Facilitates cursor-based pagination for smoother user experiences.
• Idempotency Keys: Ensures stable identifiers across HTTP requests, queues, and database actions.
• Cross-Service Coordination: Consistently utilize typed IDs across headers and metrics for better tracking.
• Offline ID Generation: Enables mobile and edge applications to generate IDs and synchronize later.

Format Specification

An OrderlyID adheres to the canonical format:

<prefix>_<payload>[-<checksum>]

Breakdown:

• Prefix: A lowercase string (e.g. order) representing the entity type, followed by a required underscore separator.
• Payload: A 32-character Base32 encoded string representing a unique 160-bit body.
• Checksum: An optional 4-character checksum for added safety.

Example:

order_00myngy59c0003000dfk59mg3e36j3rr-9xgg

The binary layout consists of time, flags, tenant, sequence, shard, and randomness, offering flexibility and robust data integrity.

Implementation

OrderlyID can be implemented using the provided reference Go library:

import "github.com/kpiljoong/orderlyid"

id := orderlyid.New("order",
  orderlyid.WithTenant(12),
  orderlyid.WithShardFromBytes([]byte("customer")),
  orderlyid.WithChecksum(true),
)
// => "order_00myngy59c0003000dfk59mg3e36j3rr-9xgg"

Roadmap

A reference implementation in Go is currently available and production-ready. Planned language bindings for Rust and Python are in the roadmap, along with enhancements and contributions from the community are welcome.

OrderlyID aims to provide a modern, ergonomic solution for identifiers, ensuring easier, safer, and more efficient identification in today's complex software systems.