123 lines
2.4 KiB
Markdown
123 lines
2.4 KiB
Markdown
# backend-signal
|
|
|
|
Beep backend handling WebRTC signaling.
|
|
|
|
**To run this service securely means to run it behind traefik forwarding auth to `backend-auth`**
|
|
|
|
## Quickstart
|
|
|
|
Docker:
|
|
|
|
```bash
|
|
export PORT=1837 # Or whatever port number you like
|
|
docker build -t backend-signal . && docker run -it backend-signal
|
|
```
|
|
|
|
Not hipster (requires node.js):
|
|
|
|
```bash
|
|
export PORT=1837 # Or whatever port number you like
|
|
npm install
|
|
node index.js
|
|
```
|
|
|
|
## API
|
|
|
|
Unless otherwise noted, bodies and responses are with ```Content-Type: application/json```.
|
|
|
|
| Contents |
|
|
| -------- |
|
|
| [Subscribe to SSE](#Subscribe-to-SSE) |
|
|
| [Get a user's devices](#Get-a-user's-devices) |
|
|
| [Post data to a user's device](#Post-data-to-a-user's-device) |
|
|
|
|
### Subscribe to SSE
|
|
|
|
```
|
|
GET /subscribe
|
|
```
|
|
|
|
Subscribe a user's device to the signaling service. Recommended usage:
|
|
|
|
```js
|
|
const es = new EventSource(`${host}/subscribe/${user}/device/${device}`);
|
|
es.onmessage = (e) => {
|
|
const data = e.data;
|
|
// Do whatever with data
|
|
};
|
|
```
|
|
|
|
#### Required headers
|
|
|
|
| Name | Description |
|
|
| ---- | ----------- |
|
|
| X-User-Claim | Stringified user claim, populated by `backend-auth` called by `traefik` |
|
|
|
|
#### Success Response (200 OK)
|
|
|
|
An [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) stream.
|
|
|
|
#### Errors
|
|
|
|
| Code | Description |
|
|
| ---- | ----------- |
|
|
| 401| Invalid user claims header. |
|
|
|
|
---
|
|
|
|
### Get a user's devices
|
|
|
|
```
|
|
GET /user/:user/devices
|
|
```
|
|
|
|
Get a list of device IDs associated with the specified user. One can then use the IDs to post data to individual devices.
|
|
|
|
#### URL Params
|
|
|
|
| Name | Type | Description | Required |
|
|
| ---- | ---- | ----------- | -------- |
|
|
| user | String | Target user's ID. | ✓ |
|
|
|
|
#### Success Response (200 OK)
|
|
|
|
List of device IDs. Can be an empty list.
|
|
|
|
```
|
|
[ <id>, <id2>, ... ]
|
|
```
|
|
|
|
---
|
|
|
|
### Post data to a user's device
|
|
|
|
```
|
|
POST /user/:user/device/:device
|
|
```
|
|
|
|
Post data to the specified device of the specified user.
|
|
|
|
#### URL Params
|
|
|
|
| Name | Type | Description | Required |
|
|
| ---- | ---- | ----------- | -------- |
|
|
| user | String | Target user's ID. | ✓ |
|
|
| device | String | Target device's ID. | ✓ |
|
|
|
|
#### Body
|
|
|
|
| Name | Type | Description | Required |
|
|
| ---- | ---- | ----------- | -------- |
|
|
| data | String | Data to be sent. | ✓ |
|
|
|
|
#### Success Response (200 OK)
|
|
|
|
Empty body.
|
|
|
|
#### Errors
|
|
|
|
| Code | Description |
|
|
| ---- | ----------- |
|
|
| 400 | No data to be sent was supplied. |
|
|
| 404 | The specified user/device's connection could not be found. |
|