crystal-scatter/README.md

# crystal-scatter

Release candidate for v1.0 "David Robert Jones"

## Installation

Add this to your application's `shard.yml`:

```yaml
dependencies:
  crystal-scatter:
    git: https://git.nekoit.xyz/Archivist/crystal-scatter
    version: ~> 1.0.0-rc1
```

## Usage

```crystal
require "crystal-scatter"
```

Create a MetaRing and add services to it, using the weights as a mark of the load the service can handle (example: number of threads each CPU of the servers can handle).

```crystal
client_ip = "185.124.235.1"

ring = Crystal::Scatter::MetaRing.new(3)

ring.add [
    Crystal::Scatter::Daemon (8 , uuid01,   [0,0,0,0,0,0], "https://api01.myservice.com"),
    Crystal::Scatter::Daemon (16, uuid02,   [0,0,0,0,1,0], "https://api02.myservice.com"),
    Crystal::Scatter::Daemon (12, uuid03,   [1,0,0,0,0,0], "https://api03.myservice.com"),
    Crystal::Scatter::Daemon (12, uuid04,   [1,0,0,0,1,0], "https://api04.myservice.com"),
    Crystal::Scatter::Daemon (12, uuid05,   [2,0,0,0,0,0], "https://api05.myservice.com")
]

ring.get_slices_for(client_ip) 
# => [
#       "https://api01.myservice.com",
#       "https://api03.myservice.com",
#       "https://api05.myservice.com"
#    ]
```

The output will provide you information to contact the service in a balanced way.

### In details

```crystal
Crystal::Scatter::Daemon (12, uuid,   [2,0,0,0,0], "https://api05.myservice.com")
                          ^    ^       ^ ^ ^ ^ ^ ^   ^
                          |    |       | | | | | |   |
                          |    |       | | | | | |   L Real target
                          |    |       | | | | | L Serving daemon
                          |    |       | | | | L Serving server
                          |    |       | | | L Serving PSU
                          |    |       | | L Serving rack
                          |    |       | L Serving room
                          |    |       L Serving datacenter
                          |    L UUID provided by the HARP wrapper
                          L Weight
```

Such information is to be supplied to `Crystal::Scatter`.

## Contributing

1. [Fork it](https://git.nekoit.xyz/repo/fork/18)
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create a new Pull Request

## Contributors

- Ludovic 'Archivist' Lagouardette - creator, maintainer
    - [Gitea](https://git.nekoit.xyz/Archivist) 
    - [Github](https://www.github.com/Zenohate)