ALARA UUID

High-quality UUID generation for Erlang with distributed entropy powered by ALARA.

Hex.pmHex DocsLicense

Description

ALARA UUID is an RFC 9562 compliant UUID generator that leverages the ALARA distributed entropy network to produce cryptographically strong identifiers. It supports both UUID v7 (time-based with random components) for optimal database performance and UUID v5 (name-based SHA-1) for deterministic generation.

Unlike traditional UUID libraries, ALARA UUID uses a distributed entropy network instead of local randomness, providing superior entropy quality through network-wide consensus. This makes it ideal for distributed systems requiring high-quality randomness and chronologically sortable identifiers.

Features

Quick Start

UUID v7 - Time-based with ALARA Entropy

%% Generate a single UUID v7
UUID = alara_uuid:v7().
%% <<1,154,77,90,96,54,125,10,189,92,48,248,177,65,171,212>>

%% Generate multiple UUIDs
UUIDs = alara_uuid:v7(10).

%% Convert to string
Str = alara_uuid:to_string(UUID).
%% "019a4d5a-6036-7d0a-bd5c-30f8b141abd4"

%% Different formats
Hex = alara_uuid:to_string(UUID, "hex").
%% "019a4d5a60367d0abd5c30f8b141abd4"

URN = alara_uuid:to_string(UUID, "urn").
%% "urn:uuid:019a4d5a-6036-7d0a-bd5c-30f8b141abd4"

UUID v5 - Deterministic Name-based

%% Generate UUID v5 with predefined namespace
UUID1 = alara_uuid:v5(dns, "example.com").
UUID2 = alara_uuid:v5(dns, "example.com").
UUID1 =:= UUID2.  % true - always the same

%% Other predefined namespaces
URLBasedUUID = alara_uuid:v5(url, "https://example.com").
OIDBasedUUID = alara_uuid:v5(oid, "1.3.6.1.4.1").
X500BasedUUID = alara_uuid:v5(x500, "cn=John Doe").

%% Custom namespace
CustomNS = alara_uuid:ns_dns(),  % or any 16-byte binary
UUID = alara_uuid:v5(CustomNS, <<"my-custom-name">>).

API Reference

Generation Functions

v7() -> binary()

Generate a single UUID v7 with ALARA distributed entropy.

v7(N :: pos_integer()) -> [binary()]

Generate N UUID v7 identifiers.

v5(Namespace :: atom() | binary(), Name :: string() | binary()) -> binary()

Generate a deterministic UUID v5 from a namespace and name.

Predefined namespace atoms:

Namespace Accessors

ns_dns() -> binary()

Returns the RFC 9562 DNS namespace UUID.

ns_url() -> binary()

Returns the RFC 9562 URL namespace UUID.

ns_oid() -> binary()

Returns the RFC 9562 OID namespace UUID.

ns_x500() -> binary()

Returns the RFC 9562 X.500 namespace UUID.

Formatting Functions

to_string(UUID :: binary()) -> string()

Convert UUID to standard format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

to_string(UUID :: binary(), Format :: string() | atom()) -> string()

Convert UUID to specified format:

UUID v7 Structure

UUID v7 provides chronological sortability with high-quality randomness:

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                         unix_ts_ms (48)                       |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|ver|       rand_a (12)         |var|       rand_b (62)         |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Why UUID v7?

Database Performance

Distributed Systems

Better than UUID v4

Better than UUID v1

UUID v5 Structure

UUID v5 generates deterministic identifiers from namespace and name:

UUID = SHA1(namespace_uuid + name)[0:128]
Version = 5
Variant = RFC 4122

Use cases:

ALARA Integration

UUID v7 leverages ALARA's distributed entropy network for random bit generation. ALARA automatically starts when generating v7 UUIDs.

How ALARA Enhances UUID Generation

  1. Distributed Entropy: Random bits come from multiple network nodes
  2. Consensus-Based: Entropy is validated across the network
  3. High Quality: Statistical properties verified through distributed agreement
  4. Transparent: Automatic startup, no configuration needed

Manual ALARA Control

%% ALARA starts automatically, but you can control it:
{ok, Sup} = alara_node_sup:start_link(3).  % 3 nodes

%% Generate UUIDs (ALARA already running)
UUIDs = alara_uuid:v7(100).

%% Stop when done
alara_node_sup:stop().

Testing

Run the comprehensive test suite:

rebar3 eunit

Use Cases

Web Applications

%% Generate user IDs
UserID = alara_uuid:v7(),
User = #user{id = UserID, email = Email, created_at = erlang:system_time()}.

Distributed Databases

%% Primary keys that sort chronologically
lists:foreach(fun(Data) ->
    ID = alara_uuid:v7(),
    db:insert(#record{id = ID, data = Data})
end, Records).

%% Query by time range becomes efficient
RecentRecords = db:query("SELECT * FROM records WHERE id > ?", [SinceUUID]).

Content Addressable Storage

%% Deterministic IDs for content
ContentHash = crypto:hash(sha256, Content),
ContentID = alara_uuid:v5(ns_oid(), ContentHash),
store:put(ContentID, Content).

%% Same content always gets same ID
ContentID2 = alara_uuid:v5(ns_oid(), ContentHash),
ContentID =:= ContentID2.  % true

Distributed Tracing

%% Trace IDs with temporal ordering
TraceID = alara_uuid:v7(),
SpanID = alara_uuid:v7(),
trace:start_span(TraceID, SpanID, Operation).

RFC 9562 Compliance

ALARA UUID fully implements RFC 9562 (published May 2024), the latest UUID specification:

Contributing

Contributions are welcome. Please ensure:

  1. All tests pass: rebar3 eunit
  2. Code follows OTP design principles
  3. New features include tests
  4. Documentation is updated

License

Apache License 2.0

References