Dependency update, Docker buildfile, Readme, LICENSE

+ 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
2024-05-09 19:50:24 +02:00
parent efa92243f1
commit 070dae5aeb
6 changed files with 907 additions and 14 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,127 @@
+
+# SnowflakeService
+
+A tool/microservice to centrally generate snowflake IDs. Can be run distributed.
+
+![GitHub License](https://img.shields.io/github/license/B00tLoad/SnowflakeService)
+![GitHub Issues or Pull Requests](https://img.shields.io/github/issues/B00tLoad/SnowflakeService)
+![GitHub repo size](https://img.shields.io/github/repo-size/B00tLoad/SnowflakeService)
+![GitHub Release](https://img.shields.io/github/v/release/B00tLoad/SnowflakeService)
+## 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.
+