hendridm/socketio-relay repository overview

⁠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
   

   Copy

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

   API_KEY=testkey DEBUG=1 npm start
   

   Copy

   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
   

   Copy

   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!" }'
   

   Copy

   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.