Simple Message Relay Server

A simple Node.js message relay for Docker for transmitting to Socket.IO clients.

1. Run the Docker service.
2. Create a listener on the client, such as a web page.
3. Send messages using cURL or your favorite REST client.

For more information, see my nodejs-simple-message-relay example and screenshot.

Deployment

Issue the following command to run in Docker:

docker run -p 3000:3000 --name socketio-relay -e API_KEY=MY_SECRET_API_KEY hendridm/socketio-relay

See demo.html or Client Side Example Code for examples of using the Socket.IO browser client to receive messages.

Environmental Variables

• API_KEY - The API key required to send messages to clients.
• DEBUG - Set DEBUG=1 (or -e DEBUG=1 in Docker) to display incoming messages to the console.
• PORT - The port the server listens on. Defaults to 3000.

Local Development

Requires Node.js 24 or later.

1. Install dependencies:

   npm install

2. Start the server, setting an API key (and optionally enabling debug output):

   API_KEY=testkey DEBUG=1 npm start

   For auto-reload during development, use npm run dev (via nodemon) instead.

3. Open a client to listen for messages. You can open demo.html directly from the filesystem (file://) — it works because the server reflects and allows any origin by default, including the null origin that file:// pages send. Serving it over HTTP is still recommended, since it more closely mirrors a real deployment (and keeps working if you later restrict the server to specific origins):

   npx serve . -l 8080
   # then open http://localhost:8080/demo.html

   Either way, you should see the status indicator turn green ("Connected").

4. Send a test message:

   curl -X POST 'http://localhost:3000/socket/my-socket-name?api_key=testkey' \
       --header 'Content-Type: application/json' \
       --data-raw '{ "message": "Hello World!" }'

   The message should appear in the browser demo. The server responds with 401 Unauthorized if the api_key query parameter is missing or does not match.

Usage

Once you have to service running and one or more clients connected, you can send messages to them using your favorite REST client. You can send any data you like as long as it's in JSON. For example, to send a message to the included demo.html, you could issue the following command:

curl --location --request POST 'http://localhost:3000/socket/my-socket-name?api_key=MY_SECRET_API_KEY' \
    --header 'Content-Type: application/json' \
    --data-raw '{ "message": "Hello World!" }'

Note that "my-socket-name" in the endpoint above must match the name of the socket that you are listening to in the client (see demo.html). In this way, you can set different listeners and send different messages to different sockets.