/callback/callbacks.md

Callbacks
=========
Silver features a clan-based callback system, in which clients have the ability to monitor specified clans, provided they are a member. This functionality can be useful if you wish to establish realtime monitoring for certain clan information, when building a clan or network website, for example.


# Callback Events
There are four callback events provided by Silver at the moment. All callback events are named according to the [command](../command/commands.md) which should be called in order to retrieve the updated state. When the responder is called, it will be called with the exact parameters which should be used as well.

| **Name**                                 | **Parameters** | **Notes**                                                                                                                                |
|------------------------------------------|----------------|------------------------------------------------------------------------------------------------------------------------------------------|
| [`warInfo`](../command/warInfo.md)       | `clanId`       | Sent when a war starts, ends, changes from prep-day to battle-day, and when an attack is made.                                           |
| [`warStars`](../command/warStars.md)     | `clanId`       | Sent whenever a clan member's war-star count changes.                                                                                    |
| [`warHistory`](../command/warHistory.md) | `clanId`       | Sent whenever a war attack is made.                                                                                                      |
| [`clanInfo`](../command/clanInfo.md)     | `id`           | Sent whenever a clan member joins, leaves, or is promoted. Also sent when clan settings are changed and when the current war-ID changes. |

Certain commands may require a callback established to work. In cases where you want to use the command, but don't need live notifications, one can empty their `url` config-option and maintain the callback, while avoiding any warnings due to failing to reach a responder.


# Setup
The general layout of the callback configuration is detailed on the [Configuration](../config/config.md#callbacks-list) page, though is reproduced below with some added explanation to the options.
```json
"callbacks": [
  {
    "url": "http://127.0.0.1:8080/csCallbackNotify.php",
    "subscriptions": "warInfo warStars warHistory clanInfo",
    "clanId": 0
  }
]
```
| **Option**      | **Purpose**                                                                                                                                                                                     |
|-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `url`           | The address of a responder script responsible for handling any notifications generated by this callback. A warning will be logged if this URL cannot be reached, unless it is completely empty. |
| `subscriptions` | A space-separated list of the callback-events which the responder should be notified of.                                                                                                        |
| `clanId`        | The ID representing the clan which should be monitored. Any client that belongs to this clan can monitor it.                                                                                    |


# Working Mechanism
Upon startup, all callbacks with a valid clan-ID are loaded from `config.json` and registered into the callback system. This system is then checked whenever a client is logged in, to determine whether the client belongs to a clan which requires monitoring. If any client's clan is found to require monitoring, the client will:

 - Begin handling live clan events, if the clan is not being monitored by another client.
 - OR disconnect, if the clan is already being monitored. This is to ensure there will be extras available to monitor if the previous monitoring client enters personal break.

Upon any change to clan or war information, monitored clans will perform an HTTP GET request on the specified `url` in their configuration entry, provided they are subscribed to notifications for the change that's occurring. The HTTP request will include parameters describing the event which occurred, in the following ([query-string](https://en.wikipedia.org/wiki/Query_string)) format:

`url` + `?cmd=` + `COMMAND_NAME` + `...PARAMS...`

 

As an example using the default configuration, let's pretend that someone's finished an attack in the active clan-war. Silver will perform a GET request on the following URLs:
```
http://127.0.0.1:8080/csCallbackNotify.php?cmd=warStars&clanId=%CLAN_ID_HERE%
http://127.0.0.1:8080/csCallbackNotify.php?cmd=warHistory&clanId=%CLAN_ID_HERE%
http://127.0.0.1:8080/csCallbackNotify.php?cmd=warInfo&clanId=%CLAN_ID_HERE%
```
The requests are made since the attacker hypothetically gained some stars, and did change the attack history, so we need to notify our responder script (the `url`) to call `warStars`, `warHistory`, and `warInfo` in order to update its state.

 

Responder scripts should ideally output (`echo`) `OK` in response to the request, in order to inform Silver that it has delivered the notification successfully and does not need to try again. Below is a sample responder script, which outputs any events to a `silverCallbacks.log` file.

```php
<?php
set_time_limit(0);

ini_set('log_errors', TRUE);
ini_set('error_log', "silverCallbacks.log");

$cmd = $_GET['cmd'];

switch ($cmd) {
  case 'warInfo':
   $clanId = $_GET['clanId']; 
   error_log($cmd . ', clanId = ' . $clanId . "\r\n");
   break;
  
  case 'warStars':
   $clanId = $_GET['clanId'];
   error_log($cmd . ', clanId = ' . $clanId . "\r\n");
   break;
  
  case 'warHistory':
   $clanId = $_GET['clanId'];
   error_log($cmd . ', clanId = ' . $clanId . "\r\n");
   break;
  
  case 'clanInfo':
   $clanId = $_GET['id']; // PLEASE mind this difference
   error_log($cmd . ', id = ' . $clanId . "\r\n");
   break;
  
  default:
   error_log("unknown {http://$_SERVER[HTTP_HOST]$_SERVER[REQUEST_URI]}\r\n");
   break;
  
}

echo "OK";
?>
```


Please note that Silver clients will also send notifications for every subscribed callback-event upon login, simply to ensure that the server has received data without requiring any changes to occur. When using the above sample responder, the following is output after a client has logged-in:
```
[28-Jul-2016 16:46:53 America/New_York] warInfo, clanId = 103080058097
[28-Jul-2016 16:46:53 America/New_York] warStars, clanId = 103080058097
[28-Jul-2016 16:46:53 America/New_York] warHistory, clanId = 103080058097
[28-Jul-2016 16:46:53 America/New_York] clanInfo, id = 103080058097
```


# Best Practices
 - Callback notifications are sent with the intention that the responder will perform the request indicated, then store the updated information in a database. This database information should then be referred to in order to access up-to-date information without needing to call Silver again.
    - Essentially, your responder is the only thing that calls the callback-event commands, and tosses them into a DB, which everything else fetches from. It's a hassle-free and the fastest way to maintain updated data for a certain clan.
 - If you are intent on calling the callback-event commands outside of your responder, multiple times, without events occurring between, then there's no point in using a responder, so please disable it. Although slightly easier to setup only, this is not recommended, as it completely neglects performance. Please use a responder.

# Notes
 - Silver will only send out one notification at a time. After a connection has been established, it will wait to be either disconnected or receive at least some response before continuing onto the next. The current notification can be dropped if the responder takes too long, however.
 - Responders have three minutes to make any needed updates before Silver will disconnect and request once again. If a request has failed three times, Silver will drop it from the queue.
    - If a responder must take longer than three minutes you're doing something wrong.
    - One could technically `echo 'OK'` then `flush()` at the start of your responder in order to force Silver onto the next notification, while still allowing the current responder script to execute, past the three minute limit without warning.
 - Because Silver automatically handles deduplication of clients listening for callback events, it's best to set `connection.limit` to the count of `users[]` or something unreachable, so it can be certain that there's always a player monitoring. This is contrary to the normal advice of having a limit somewhat less than the size of `users[]`.