promptfoo--promptfoo/examples/config-websockets/streaming/server/README.md

config-websockets/streaming/server (OpenAI WebSocket Server)

Simple Node.js server using Express and native WebSockets that exposes two real-time endpoints to interact with the OpenAI Responses API.

Requirements

• Node.js >= 18.17
• An OpenAI API key

Setup

1. Install dependencies:

npm install

2. Configure environment:

• set OPENAI_API_KEY in your environment or use .env file

cp env.example .env
# edit .env and set OPENAI_API_KEY

3. Start the server (defaults to port 3300):

npm start

You can also run in dev mode with automatic restarts:

npm run dev

HTTP

• Health check: GET /health → { "status": "ok" }

Real-time (WebSocket)

Two WebSocket upgrade paths are provided:

• /ws — non-streaming. Emits a single response when the OpenAI request completes.
• /ws-stream — streaming. Emits incremental delta and message events, then done.

Both endpoints accept the same request payload (model is configured via env):

{ "input": "Hello there!" }

Model is read from CHATBOT_MODEL env var and defaults to gpt-4.1-mini.

Client examples

Non-streaming (/ws):

const ws = new WebSocket('ws://localhost:3300/ws');

ws.onopen = () => {
  ws.send(JSON.stringify({ input: 'Hello there!' }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  // msg.type: 'ready' | 'response' | 'done' | 'error'
  console.log(msg);
};

ws.onerror = (err) => console.error('ws error', err);

Streaming (/ws-stream):

const ws = new WebSocket('ws://localhost:3300/ws-stream');

ws.onopen = () => {
  ws.send(JSON.stringify({ input: 'Stream this please' }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  // msg.type: 'ready' | 'delta' | 'message' | 'done' | 'error'
  if (msg.type === 'delta') process.stdout.write(msg.message || '');
  else console.log(msg);
};

ws.onerror = (err) => console.error('ws error', err);

Notes

• Configure port via PORT in .env.
• Configure model via CHATBOT_MODEL in .env (default: gpt-4.1-mini).
• Health route is GET /health. WebSocket upgrade paths are /ws and /ws-stream.