fx-test/docs/usage.md

📖 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:

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

GET /health

Response:

{"status":"ok","uptime":123456}

Status

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.