Snowspeck

A lightweight, thread-safe, extensible, and decodable Snowflake ID generator for .NET.

---

Features

• 64-bit unique, time-ordered ID generation
• Fully thread-safe
• Decodable (timestamp, datacenter ID, worker ID, sequence)
• Minimal dependencies (Microsoft.Extensions.Options)
• Great for distributed systems and high-throughput workloads

---

What is a Snowflake ID?

A Snowflake ID is a 64-bit integer originally developed by Twitter to generate unique, time-ordered identifiers in distributed systems.

It typically encodes:

• A timestamp (usually in milliseconds)
• A machine or worker ID (identifying the node that generated the ID)
• A sequence number (to prevent collisions when generating multiple IDs in the same millisecond)

This structure ensures:

• Globally unique identifiers without coordination between nodes
• IDs that increase over time (sortable)
• High-performance generation, suitable for distributed environments

Disclaimer

Snowflake IDs are intentionally decodable and expose metadata like generation time and worker identity.
They are not cryptographically secure and should not be used to encode sensitive or private information.

Use them only for unique, ordered identifiers, not for hiding or securing data.

---

Installation

Using the CLI:

dotnet add package Snowspeck

Or via the NuGet Package Manager:

Install-Package Snowspeck

---

Implementations

Snowspeck offers two implementations of the generator, depending on whether you prefer signed or unsigned IDs:

Class	Return Type	ID Range	Notes
SignedSnowflakeService	long	-2⁶³ to 2⁶³−1	Default in DI setup, fits in signed columns
UnsignedSnowflakeService	ulong	0 to 2⁶⁴−1	Full 64-bit range, use when unsigned is OK

Both use the same structure:

• 41 bits for timestamp
• 5 bits for datacenter ID
• 5 bits for worker ID
• 12 bits for sequence number

Choose the implementation that best fits your database, serialization, or sorting needs.

---

Quick Start

Manual Instantiation

using Snowspeck;
using Snowspeck.Interfaces;
using Snowspeck.Services;

var options = new SnowflakeOptions
{
    WorkerId = 1,
    Epoch = 1735689600000L // (optional) Default is 1735689600000L -> Jan 1, 2025
};

ISnowflakeGenerator generator = new SignedSnowflakeService(options);
long id = generator.NextId();

---

Dependency Injection (ASP.NET Core)

builder.Services.AddSnowspeck(options =>
{
    options.WorkerId = 1;
    options.Epoch = 1735689600000L; // (optional) Default is 1735689600000L -> Jan 1, 2025
});

builder.Services.AddSnowspeckUnsigned(options =>
{
    options.WorkerId = 1;
    options.Epoch = 1735689600000L; // (optional) Default is 1735689600000L -> Jan 1, 2025
});

Once registered, resolve ISnowflakeGenerator via constructor injection:

public class MyService
{
    private readonly ISnowflakeGenerator _generator;

    public MyService(ISnowflakeGenerator generator)
    {
        _generator = generator;
    }

    public void DoSomething()
    {
        long id = _generator.NextId();
    }
}

---

Decoding Snowflake Metadata

The generator supports decoding a Snowflake ID back into:

• Timestamp (UTC time the ID was generated)
• DatacenterId
• WorkerId
• Sequence

long id = generator.NextId();
var metadata = generator.Decode(id);

Console.WriteLine($"Timestamp: {metadata.Timestamp}");
Console.WriteLine($"DatacenterId: {metadata.DatacenterId}");
Console.WriteLine($"WorkerId: {metadata.WorkerId}");
Console.WriteLine($"Sequence: {metadata.Sequence}");

---

Planned Features

• Future extensions via subclassing (override clock skew handling, timestamp source, etc.)

Have an idea or feature request? Feel free to open an issue.

---

License

Licensed under the MIT License.
© 2025 Tiago Ferreira Alves