{"id":19175768,"url":"https://github.com/handcraftedbits/flaky","last_synced_at":"2025-07-20T15:03:22.826Z","repository":{"id":57724806,"uuid":"118554652","full_name":"handcraftedbits/flaky","owner":"handcraftedbits","description":"A Java implementation of Twitter Snowflake","archived":false,"fork":false,"pushed_at":"2018-02-14T20:43:08.000Z","size":32,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"development","last_synced_at":"2025-07-11T13:43:59.054Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/handcraftedbits.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-01-23T03:50:47.000Z","updated_at":"2018-01-23T03:53:52.000Z","dependencies_parsed_at":"2022-09-11T20:10:47.848Z","dependency_job_id":null,"html_url":"https://github.com/handcraftedbits/flaky","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/handcraftedbits/flaky","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/handcraftedbits%2Fflaky","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/handcraftedbits%2Fflaky/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/handcraftedbits%2Fflaky/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/handcraftedbits%2Fflaky/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/handcraftedbits","download_url":"https://codeload.github.com/handcraftedbits/flaky/tar.gz/refs/heads/development","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/handcraftedbits%2Fflaky/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266143941,"owners_count":23883069,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-09T10:24:59.913Z","updated_at":"2025-07-20T15:03:22.808Z","avatar_url":"https://github.com/handcraftedbits.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Flaky [![Maven](https://img.shields.io/maven-metadata/v/http/central.maven.org/maven2/com/handcraftedbits/web/flaky/maven-metadata.xml.svg)](https://mvnrepository.com/artifact/com.handcraftedbits.web/flaky/1.0.2) [![Build Status](https://travis-ci.org/handcraftedbits/flaky.svg?branch=master)](https://travis-ci.org/handcraftedbits/flaky) [![Coverage Status](https://coveralls.io/repos/github/handcraftedbits/flaky/badge.svg)](https://coveralls.io/github/handcraftedbits/flaky) [![Javadocs](https://javadoc.io/badge/com.handcraftedbits.web/flaky.svg)](https://javadoc.io/doc/com.handcraftedbits.web/flaky)\n\nA Java implementation of [Twitter Snowflake](https://blog.twitter.com/engineering/en_us/a/2010/announcing-snowflake.html).\nThe implementation sticks closely to the specification with the exception that the node and sequence lengths can be\nadjusted instead of staying fixed at the default values of 10 and 12 bits, respectively.\n\nIn short: Flaky will generate unique, increasing 64-bit values, which are perfect for database entity IDs.  Furthermore,\nthese values will never collide, even in a distributed environment, as long as the machines generating the IDs maintain\ndifferent _node values_.\n\n# Concepts\n\n## Node Value\n\nAn integer used to identify a particular machine generating IDs using Flaky.  Can be between 0 (meaning there is\nonly a single machine generating IDs) and 16 (meaning there are up to 65535 machines generating IDs) bits in length.\n\n## Sequence Value\n\nAn increasing value that rolls over to 0 every millisecond.  Can be between 6 and 22 bits in length.\n\n## How an ID is Generated\n\nA Flaky ID is a 64-bit value that looks like this:\n\n```\n+---------------------+------------------------+----------------------------+\n| Timestamp (41 bits) | Node value (0-16 bits) | Sequence Value (6-22 bits) |\n+---------------------+------------------------+----------------------------+\n```\n\nThe **timestamp** is set to the number of milliseconds that have elapsed since the **epoch**, which is configurable and\ndefaults to `2016-11-28`.  Since this value is 41 bits in length, Flaky IDs will be valid for a little over 69 years\nafter the epoch.\n\nThe **node value** remains static and is dictated by a user-configurable value (with a default value of 0).  This value\nshould always remain the same when Flaky is invoked on the same machine.\n\nThe **sequence value** increments on every call and rolls over to 0 every millisecond.\n\nWith default settings, this means that each node can generate 4096 unique IDs per millisecond for nearly 70 years!  You\ncan generate more or fewer IDs per millisecond by tweaking the sequence length.\n\n# Requirements\n\nFlaky requires Java 8 or later.\n\n# Usage\n\nAdd the following dependency in your `pom.xml` file:\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003ecom.handcraftedbits.web\u003c/groupId\u003e\n  \u003cartifactId\u003eflaky\u003c/artifactId\u003e\n  \u003cversion\u003e1.0.1\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nThen, create a `FlakyId` instance:\n\n```java\n// Use defaults: 10-bit node length, 12 bit sequence length, node value = 0.\nFlakyId generator = new FlakyId.Builder().build();\n\n// Use defaults with a specific node value.\ngenerator = new FlakyId.Builder().withNode(1L).build();\n\n// Use a shorter node value length, which gives a much longer sequence length.\ngenerator = new FlakyId.Builder().withNodeLength(4L).build();\n\n// Use a custom epoch and longer sequence length.\ngenerator = new FlakyId.Builder().withEpoch(System.currentTimeMillis()).withSequenceLength(16L).build();\n```\n\nThen, generate away!\n\n```java\nlong timestamp = generator.generateIdSafe();\n// ...\n```\n\nNote that there is a very real possibility that the machine's system clock will drift backwards from time to time (such\nas when updated time is received from an NTP server), and in that case `generateIdSafe()` will wait as long as\nnecessary for the system clock to catch back up.  This is needed to ensure that IDs are unique and constantly\nincreasing.  Keep in mind that there is no upper limit on how long this will be, but unless something is very wrong\nwith the system clock this should be a fairly short amount of time.\n\nAlternatively, you can use `generateId()`, which will throw `SystemClockException` when the system clock drifts\nbackwards.  This gives you the opportunity to decide how you want to handle this situation (i.e., do nothing, wait if\nthe amount of time needed is short, fail, etc.):\n\n```java\ntry {\n     long timestamp = generator.generateId();\n     // ...\n}\n\ncatch (SystemClockException e) {\n     // Give up?  Or wait:\n\n     java.util.concurrent.locks.LockSupport.parkUntil(e.getNextTimestamp());\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhandcraftedbits%2Fflaky","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhandcraftedbits%2Fflaky","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhandcraftedbits%2Fflaky/lists"}