# 📖 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.