# Nchan-base messenger for QFQ

| Directory | Documentation                | Intention                                           |
|-----------|------------------------------|-----------------------------------------------------|
|`js`       |[doc/JS.md](doc/JS.md)        | JavaScript SDK for listeners and publishers         |
|`php`      |[doc/PHP.md](doc/PHP.md)      | PHP SDK for publishing messages and creating tokens |
|`nginx`    |[nchan.io](https://nchan.io/) | A flexible nchan configuration                      |
|`example`  | (see below)                  | A comprehensive example                             |

## Installation

### Web server

```bash
# Copy necessary files to the server as the www-user user
rsync -a --chown=www-data:www-data example hooks php js index.php \
      root@webserver:/var/www/html/messenger

# Copy nginx configuration
rsync nginx/messenger-{local,global}.conf root@webserver:/etc/nginx/snippets/
rsync nginx/messenger-vars.conf root@webserver:/etc/nginx/conf.d/

# Include snippets to site configurations (see files in nginx/sites/):
# - localhost (127.0.0.1:8080):
#
#     include snippets/messenger-local.conf;
#
# - a site with messenger:
#
#     include snippets/messenger-global.conf;
```

Test pages:

* `https://your.domain.com/messenger/` - a general test for websockets
* `https://your.domain.com/messenger/rest/rest/` - checks the REST service


#### Proxy configuration

If the messenger is accessed via a proxy, then a special care must be taken for websocket connections on the proxy server. In case of Nginx reverse proxy, the following snippet is enough:

```nginx
# --- /etc/nginx/conf.d/messenger ----

# Required for websocket connections: the Connection header is not passed
# by the proxy and we have to make sure it exists.
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}


# --- /etc/nginx/sites-available/proxy-with-messenger

location ^~ /messenger/ {
  proxy_pass https://messenger-backend/messenger/;

  # Standard proxy settings; replace $target_host with the domain
  # expected by the messenger-backend
  proxy_set_header Host $target_host;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Forwarded-Proto $scheme;
  proxy_ssl_server_name on;
  proxy_ssl_name $target_host;

  # Websocket specific settings
  proxy_http_version 1.1;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection $connection_upgrade;
}
```

#### Alternate version for testing

Run the following commands on the web server to get a version with extensive logging:

```bash
# Go to the root folder
cd /var/www/html/messenger

# Make a backup of original files
mkdir -p example/orig/hooks
cp -pr hooks/*.php example/orig/hooks/
cp -pr example/*.php example/orig/

# Copy alternate files
cp -pr example/alt/* ./
```


### Development

Install dependencies

```bash
npm install
composer install
```

Run tests with

```bash
npm test
phpunit --bootstrap vendor/autoload.php
```
