70 lines
1.8 KiB
Markdown
70 lines
1.8 KiB
Markdown
# 📖 Usage Guide
|
||
|
||
The **fx-test** stack exposes two primary interfaces:
|
||
|
||
1. **WebSocket** – Real‑time event channel.
|
||
2. **HTTP** – RESTful configuration and monitoring.
|
||
|
||
## 1️⃣ WebSocket API
|
||
|
||
The WebSocket endpoint is available on port `8080`. Common message types:
|
||
|
||
| Message Type | Description |
|
||
|--------------|-------------|
|
||
| `ping` | Health check; server replies with `pong`. |
|
||
| `subscribe` | Subscribe to a topic; server sends updates. |
|
||
| `publish` | Broadcast a message to all clients. |
|
||
|
||
Example using Node.js:
|
||
|
||
```js
|
||
const ws = require("ws");
|
||
const socket = new ws("ws://localhost:8080");
|
||
|
||
socket.on("open", () => socket.send(JSON.stringify({type:"ping"}));
|
||
|
||
socket.on("message", m => console.log("Received: ", m));
|
||
```
|
||
|
||
## 2️⃣ HTTP API
|
||
|
||
### Health
|
||
|
||
```bash
|
||
GET /health
|
||
```
|
||
|
||
Response:
|
||
```json
|
||
{"status":"ok","uptime":123456}
|
||
```
|
||
|
||
### Status
|
||
|
||
```bash
|
||
GET /status
|
||
```
|
||
|
||
Returns the current number of connected WebSocket clients and processing metrics.
|
||
|
||
## 3️⃣ Configuring via ENV
|
||
|
||
The stack reads the following environment variables:
|
||
|
||
| Variable | Default | Purpose |
|
||
|----------|---------|---------|
|
||
| **PORT** | `8080` | WebSocket port |
|
||
| **HTTP_PORT** | `8090` | HTTP listening port |
|
||
| **REGISTRY** | `docker.io` | Registry to fetch Docker images |
|
||
| **DEBUG** | `false` | Enable debug logging |
|
||
|
||
Set the environment variables in a `.env` file at the repo root or export them in your shell before running `run_dev.sh`.
|
||
|
||
---
|
||
|
||
## 4️⃣ Extending the Stack
|
||
|
||
1. **Add a new service** – Place a `Dockerfile` in `fluxer/` and reference it in the `docker-compose.yml`.
|
||
2. **Modify the relay** – Edit the Erlang source in `fluxer_relay/src/relay/`. After editing, recompile with `rebar3 do compile, release` and rebuild the Docker image.
|
||
3. **Update the CI** – Extend `ci/workflows/**.py` to run any new tests.
|