# sobani-tracker

## Introduction

Aim to set up a tracker server for sobani service and clients

## Setup

Clone to your instance

```
git clone https://github.com/BlueCocoa/sobani-tracker-rust.git
```

Compile

```
cd sobani-tracker-rust
cargo build --release
```

Start server

```
cargo run --release
```

## API Documentation

### Actions

#### announce

Announce action relates to the first connection from peer to server, within this action, a client send three parameters to tracker server in order to record and make the share action possible.

If sending is successful, an [announced](#announced) object will be returned.

| Field  | Type   | Required | Description             |
| ------ | ------ | -------- | ----------------------- |
| action | string | yes      | Fixed value, "announce" |

Expected response from server:

```json
{
  "action": "announced",
  "data": {
    "shareId": "1AbhoECj"
  }
}
```

#### alive

`alive` action meant to make maintaining the connection and the sharing session valid and possible by rapidly sending a packet to server to report the `Alive` state of the client. By doing this, server will store the session and shareId while the clients are alive, if a client stopped to send a packet, server will delete the related shareId and multiaddr it announced before. (**Default expiration time will be 5 minutes**)

#### push

Push action tells the server the unique shareId of the target client the peers shared. Tracker server respond with the `IP:Port` back to the requesting client, so on, the client can try to establish the connection between. 

If sending is successful, a [pushed](#pushed) message is returned.

| Field   | Type   | Required | Description          |
| ------- | ------ | -------- | -------------------- |
| action  | string | yes      | Fixed value, "push"  |
| data    | dict   | yes      | The requestee's info |

pushed data is demostrated below

| Field       | Type   | Required | Description |
| ----------- | ------ | -------- | ----------- |
| peeraddr    | string | yes      | `IP:Port`   |
| peerShareId | string | yes      | `ShareId`   |

Expected response from server:

```json
{
  "action": "pushed",
  "data": {
    "peeraddr": "1.2.3.4:23333",
    "peerShareId": "1AbhoECj"
  }
}
```

Also, the tracker will send an `income` message to the requestee

| Field   | Type   | Required | Description           |
| ------- | ------ | -------- | --------------------- |
| action  | string | yes      | Fixed value, "income" |
| data    | dict   | yes      | The requestor's info  |


income data is demostrated below

| Field       | Type   | Required | Description |
| ----------- | ------ | -------- | ----------- |
| peeraddr    | string | yes      | `IP:Port`   |
| peerShareId | string | yes      | `ShareId`   |

Expected income message from server:

```json
{
  "action": "income",
  "data": {
    "peeraddr": "1.2.3.4:23333",
    "peerShareId": "1AbhoECj"
  }
}
```

### Types

#### announced

| Field  | Type   | Required | Description              |
| ------ | ------ | -------- | ------------------------ |
| action | string | yes      | Fixed value, "announced" |
| data   | dict   | yes      |                          |

##### announced data

| Field   | Type   | Required | Description                      |
| ------- | ------ | -------- | -------------------------------- |
| shareId | string | yes      | shareId generated by server side |

#### pushed

| Field  | Type   | Required | Description           |
| ------ | ------ | -------- | --------------------- |
| action | string | yes      | Fixed value, "pushed" |
| data   | dict   | yes      |                       |

##### pushed data

| Field       | Type   | Required | Description |
| ----------- | ------ | -------- | ----------- |
| peeraddr    | string | yes      | `IP:Port`   |
| peerShareId | string | yes      | `ShareId`   |

#### income

| Field  | Type   | Required | Description           |
| ------ | ------ | -------- | --------------------- |
| action | string | yes      | Fixed value, "income" |
| data   | dict   | yes      |                       |

##### income data

| Field       | Type   | Required | Description |
| ----------- | ------ | -------- | ----------- |
| peeraddr    | string | yes      | `IP:Port`   |
| peerShareId | string | yes      | `ShareId`   |