Skip to main content

Testing with the WebSocket Echo Server

Eclypses provides a simple WebSocket echo server implemented in Go, used as the upstream test target when validating a SocketX deployment end to end. It demonstrates various WebSocket functionalities including different rooms, authorization mechanisms, message types (text and binary), rate limiting, and simulated error/disconnect scenarios.

Test Topology​

[SocketX client]  ── MTE-encoded WebSocket ──▶  [SocketX Server :8080]  ── plaintext ws:// ──▶  [ws-echo-server :9000]
  1. Start the echo server as the upstream service.
  2. Start SocketX Server with a DOMAIN_MAP pointing at the echo server.
  3. Connect a SocketX client through the proxy and verify that messages echo back decrypted.

Running the Echo Server​

From source​

go run .

The server starts on ws://localhost:8080. Configure a different port in config.go when running alongside SocketX Server on the same machine.

With Docker​

docker build -t ws-echo-server:local-build.1 .
docker run -p 9000:8080 ws-echo-server:local-build.1

The server is then accessible at ws://localhost:9000.

Pointing SocketX at the Echo Server​

DOMAIN_MAP='{"*":{"upstream":"ws://localhost:9000","allowedOrigins":["*"]}}' go run .

Or with Docker:

docker run --rm -it \
  -p 8080:8080 \
  -e DOMAIN_MAP='{"*":{"upstream":"ws://host.docker.internal:9000","allowedOrigins":["*"]}}' \
  socketx-server:<version>

Then connect a SocketX client to ws://localhost:8080/<room> — the pathname selects the echo room.

Available Rooms​

All connections are made to ws://localhost:8080/{room_name} (through SocketX, the room name is the pathname of your client URL).

RoomBehavior
/Basic echo. Messages are echoed back to the sender.
/dogs, /cats, /fishThemed echo rooms. Messages are echoed back prefixed with the room name, e.g. [dogs]: Your message.
/bytes-1, /bytes-2Binary message echo rooms. Expect and return binary messages.
/errorSimulates a protocol error. On the 3rd message, the server sends a CloseProtocolError (1002) frame and disconnects.
/disconnectSimulates a normal disconnection. On the 3rd message, the server sends a CloseNormalClosure (1000) frame with a custom message and disconnects.
/rate-limitAllows one message every 2 seconds. Faster messages are buffered until the next allowed interval.
/chatMulti-user chat room with real-time broadcasting. Requires a username query parameter (3-20 characters).
/private-room-query-paramRequires a token query parameter with the value dQw4w9WgXcQ.
/private-room-cookieRequires a cookie named authCookie with the value dQw4w9WgXcQ. Useful for verifying SocketX cookie forwarding.

Chat Room Details​

/chat?username=myuser provides:

  • Real-time broadcasting of messages to all users in the room.
  • User join and leave notifications.
  • JSON-based messaging for different event types (user_list, user_joined, user_left, chat_message).
  • Maximum message size of 512 bytes.
  • A central "Hub" that manages client connections and message distribution.

HTTP Echo Endpoint​

The echo server also exposes an HTTP endpoint that returns a JSON response with the current timestamp:

GET http://localhost:8080/echo
→ {"time": "2023-10-27T10:00:00Z", "message": "true"}

GET http://localhost:8080/echo?message=helloWorld
→ {"time": "2023-10-27T10:00:00Z", "message": "helloWorld"}

What to Verify​

  • Plain echo (/): text sent through a SocketX client arrives back decrypted and identical.
  • Binary rooms (/bytes-1): binary frame semantics are preserved through the SocketX protocol.
  • Error rooms (/error, /disconnect): close codes propagate through the proxy and your client's recovery handling behaves as expected.
  • Auth rooms (/private-room-query-param, /private-room-cookie): query parameters pass through in the pathname, and cookies are forwarded by SocketX to the upstream connection.
  • Rate limiting (/rate-limit): backpressure behavior through the proxy.