snowchecked: A checksummed variation on Twitter's Snowflake UID generation algorithm

[ apache, data, library ] [ Propose Tags ]

See the file ./README.md, which is included in the package and also on GitHub.


[Skip to Readme]
Versions [RSS] [faq] 0.0.0.1, 0.0.0.3, 0.0.1.0
Dependencies base (>=4.14.1.0 && <4.15), bytestring (>=0.10.12.0), data-default (>=0.7.1.1), deepseq (>=1.4.4.0), text (>=1.2.4.1), text-conversions (>=0.3.1), time (>=1.9.3), wide-word (>=0.1.1.2) [details]
License Apache-2.0
Copyright 2021 Robert Fischer
Author Robert Fischer
Maintainer smokejumperit@gmail.com
Category Data
Home page https://github.com/robertfischer/hs-snowflake-checked#readme
Bug tracker https://github.com/robertfischer/hs-snowflake-checked/issues
Source repo head: git clone https://github.com/robertfischer/hs-snowflake-checked
Uploaded by RobertFischer at 2021-08-17T14:05:47Z
Distributions NixOS:0.0.1.0
Downloads 142 total (7 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Hackage Matrix CI
Docs available [build log]
Last success reported on 2021-08-17 [all 1 reports]

Modules

[Index] [Quick Jump]

Downloads

Maintainer's Corner

For package maintainers and hackage trustees

Candidates


Readme for snowchecked-0.0.1.0

[back to package description]

SnowChecked

A Checksummed UID Generator based on Twitter's Snowflake

Unique ids are useful, but traditional GUID/UUID formats are lengthy, inefficient, and hard for humans to use. Twitter created a novel format for UIDs called "Snowflake" which addressed these issues, with the added benefit that the UIDs monotonically increase over time. This library extends the Snowflake format by adding checksum bits at the end. If you use this library with the number of checksum bits set to 0, then you have a Snowflake implementation.

This extension is valuable because the checksum detects error on input. If you're using ids in a human setting (eg: having users type them in or scan them from QR codes), then the checksum is valuable to catch typos, miscommunications, and other input issues.

Like Snowflake, this algorithm uses some bits from the timestamp, some bits from a counter, and some bits of the node id. This algorithm extends Snowflake by also using some bits to store the checksum, which derives from the sum of the other parts.

This implementation allows the number of bits in the id to range from 0 bits to 255^4 bits. The default configuration uses 64 bits, with 40 bits used for time, 10 bits used for the counter, 8 bits used for the node id, and 6 bits for the checksum. The odds of a false positive on the checksum is 1/(2^checkbits), so the odds of a false positive in the default configuration is ~1.5%. This configuration can generate 1024 UIDs per millisecond per node: the 1025th request in a given millisecond will cause a pause in the thread for one millisecond, and then the counter will reset to 0. (If you need more UID throughput than that, then create more generators with distinct node ids.)

Encoding

If you want to marshall a flake, then you can use the encodings in the Encoding sub-packages of this library. Implementations include a ByteString (strict or lazy), any Text-like value (using base 16), or any Integral value.

Credit

This project derives distantly from the snowfake package on Hackage.