Alix von Schirp @ BootMedia Media Production
070dae5aeb
+ Added Docker build file + added Readme.md + added LICENSE (GPLv3) * replaced dependency slf4j-api with logback + added dependency jetbrains-annotations + added dependency okhttp3 - removed build plugin central-publishing + added logback config files
128 lines
3.7 KiB
Markdown
128 lines
3.7 KiB
Markdown
|
|
# 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](https://blog.twitter.com/engineering/en_us/a/2010/announcing-snowflake)
|
|
- [Javalin](https://github.com/javalin/javalin)
|
|
- [QOS.CH's Logback](https://github.com/qos-ch/logback)
|
|
- [Square's OkHttp3](https://github.com/square/okhttp)
|
|
- [B00tLoad_'s ConfigurationUtilities](https://github.com/B00tLoad/Configurationutilities)
|
|
|
|
## Installation
|
|
|
|
### Docker (Recommended)
|
|
|
|
```bash
|
|
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
|
|
|
|
```http
|
|
GET /flake
|
|
```
|
|
|
|
Response example:
|
|
```json
|
|
{
|
|
"snowflake": ""
|
|
}
|
|
```
|
|
|
|
#### Register worker (internal)
|
|
|
|
```http request
|
|
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
|
|
```json
|
|
{
|
|
"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)
|
|
```http request
|
|
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_](https://www.github.com/B00tLoad)
|
|
|
|
|
|
## License
|
|
|
|
[GNU GPL v3](https://github.com/B00tLoad/SnowflakeService/blob/master/LICENSE)
|
|
|
|
|
|
## Support
|
|
|
|
For support, open a ticket or email me at alix (at) ja-lol-ey (dot) de.
|
|
|