SnowflakeService

A tool/microservice to centrally generate snowflake IDs. Can be run distributed.

Acknowledgements

This utility uses:

• The format and name of Twitter's Snowflake IDs
• Javalin
• QOS.CH's Logback
• Square's OkHttp3
• B00tLoad_'s ConfigurationUtilities

Installation

Docker (Recommended)

  docker pull bootmediaalix/snowflake-service
  docker run bootmediaalix/snowflake-service -e %{set required .env, see below} -p 95674:95674 -v /data/b00tload-services/snowflake:%desired path on host%

Containerless

A containerless installation is possible, although not supported. For development convenience the application base directory is located in ~/.b00tload-services/snowflake instead of /data/b00tload-services/snowflake. If you want to work containerless you are on your own.

Environment Variables

To run this project, you will need to add the following environment variables to your .env file

EPOCH - the starting time of the snowflake

MACHINE_ID_BITS - the amount of bits used for the machine ID

SEQUENCE_BITS - the amount of bits used for the sequence counter

MACHINE_ID - the ID of the generator

or

ORCHESTRATOR_IP - an IP where a snowflake orchestrator is available to fetch all above values

or

EPOCH - the starting time of the snowflake

MACHINE_ID_BITS - the amount of bits used for the machine ID

SEQUENCE_BITS - the amount of bits used for the sequence counter

with neither MACHINE_ID nor ORCHESTRATOR_IP set, the Service will start as an orchestrator itself with MACHINE_ID = 0.

API Reference

Get an ID

  GET /flake

Response example:

{
    "snowflake": ""
}

Register worker (internal)

POST /orchestra/register

Header	Description
name	Required. A name to recognize the worker by (e.g. hostname+pid+random number)

Response example: Http Status: 200

{
  "machineBits": "",
  "workerid": "",
  "sequenceBits": "",
  "epoch": ""
}

Response on error:

Value name	Value description
Http Status	426 - Upgrade required
Upgrade Header content	required software version

Worker heartbeat (internal)

GET /orchestra/heartbeat

Parameter	Description
name	the ID used in registration
workerID	the workerID assigned by the orchestrator

HTTP status code responses:

Status	Description
200	Ok
409	Conflict, please reregister

Maintainer

• @B00tLoad_

License

GNU GPL v3

Support

For support, open a ticket or email me at alix (at) ja-lol-ey (dot) de.