WebSockets & Realtime Systems Programming · Lesson

Request-Response over WebSockets

Learn techniques to simulate traditional request-response semantics using WebSocket message IDs and acknowledgments.

Request-Response over WebSockets is a free WebSockets & Realtime Systems Programming lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the WebSockets & Realtime Systems Programming learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Beyond Fire-and-Forget

WebSockets are fantastic for real-time, continuous streams of data. Think chat messages, live updates, or game states!

But what if you need to perform a traditional request-response interaction, like fetching specific data from a server and expecting a single, matching reply?

The Asynchronous Nature

Unlike HTTP, where each request gets an immediate, direct response, WebSockets operate on an asynchronous, message-based model.

When you send a message over a WebSocket, you don't automatically know which incoming message is its specific reply. It's like sending a letter and waiting for a specific reply letter in a pile of mail!

Unique Request Identifiers

To solve this, we introduce a crucial concept: Message IDs. Every time a client sends a request, it attaches a unique identifier.

The server then processes the request and includes that same identifier in its response. This allows the client to match the response to its original request.

Client-Side Request Tracking

On the client, we need a way to track which requests are pending and what to do when their responses arrive. A common pattern is to use a Map or object to store a Promise for each pending request.

Try running this basic setup in your browser's console:

const ws = new WebSocket("ws://localhost:8080");
const pendingRequests = new Map();

ws.onopen = () => console.log("WebSocket Connected!");
ws.onclose = () => console.log("WebSocket Disconnected.");
ws.onerror = (error) => console.error("WebSocket Error:", error);

// This will be updated later to handle responses

Server Responds with ID

The server's role is simple: when it receives a message with an id, it should process it and send back a response that includes the same id.

Here's a simplified Node.js server snippet:

const WebSocket = require('ws');
const wss = new WebSocket.Server({ port: 8080 });

wss.on('connection', ws => {
  ws.on('message', message => {
    const request = JSON.parse(message);
    console.log('Received:', request);

    // Assume processing takes time...
    setTimeout(() => {
      const response = {
        id: request.id, // Echo the original ID!
        type: 'response',
        payload: `Hello from server, for request ${request.id}`
      };
      ws.send(JSON.stringify(response));
    }, 1000);
  });
});
console.log('Server started on ws://localhost:8080');

The Full Cycle in Action

Let's trace a request-response cycle:

Client generates unique id (e.g., 1).
Client stores a Promise for id: 1 in pendingRequests.
Client sends {id: 1, type: 'fetchUser', userId: 123}.
Server receives, processes, and prepares response.
Server sends {id: 1, type: 'userFetched', data: {...}}.
Client receives message, looks up id: 1 in pendingRequests, and resolves its Promise.

A `sendRequest` Function

To make sending requests easier, we can wrap the logic in a helper function. This function will generate an ID, store a promise, send the message, and return the promise.

Add this to your client-side code:

let nextRequestId = 0;

function sendRequest(type, payload) {
  const requestId = nextRequestId++;
  const message = { id: requestId, type, payload };

  return new Promise((resolve, reject) => {
    pendingRequests.set(requestId, { resolve, reject, timeoutId: null });
    ws.send(JSON.stringify(message));
    console.log("Sent request:", message);

    // We'll add timeout logic soon!
  });
}

// Example usage (after ws is open):
// sendRequest('getUser', { id: 1 }).then(data => console.log(data));

Processing Server Responses

Now, let's update our client's ws.onmessage handler to correctly process incoming server responses and resolve (or reject) the associated promises.

This is where the pendingRequests map truly shines!

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  console.log("Received:", message);

  const { id, error, payload } = message;
  if (pendingRequests.has(id)) {
    const { resolve, reject, timeoutId } = pendingRequests.get(id);
    clearTimeout(timeoutId); // Important: clear the timeout!
    pendingRequests.delete(id); // Remove from tracking

    if (error) {
      reject(new Error(error));
    } else {
      resolve(payload); // Resolve with the response payload
    }
  } else {
    console.warn("Unmatched message ID or broadcast received:", message);
    // Handle messages that are not direct responses to a request (e.g., broadcasts)
  }
};

Timeouts and Error Handling

What if the server never responds? Or the connection drops?

It's crucial to implement timeouts for pending requests. If a response isn't received within a set duration, the client should automatically reject the promise with a timeout error.

This prevents requests from hanging indefinitely and consuming memory.

Check Your Understanding

Which of the following are essential components for implementing a robust request-response pattern over WebSockets?

Recap: Request-Response

You've learned how to simulate a traditional request-response model using WebSockets!

Unique Message IDs: Attach an ID to each request.
Client-Side Tracking: Use a Map to store Promises for pending requests.
Server Echo: Server includes the request ID in its response.
Timeouts: Implement timeouts to handle unreceived responses gracefully.

This pattern makes WebSockets incredibly versatile for both streaming and discrete data exchanges!

Frequently asked questions

Is the “Request-Response over WebSockets” lesson free?

Yes — the full text of “Request-Response over WebSockets” is free to read here on the web, and the WebSockets & Realtime Systems Programming course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the WebSockets & Realtime Systems Programming course, upgrade to CoddyKit PRO.

What will I learn in “Request-Response over WebSockets”?

Learn techniques to simulate traditional request-response semantics using WebSocket message IDs and acknowledgments. You practise WebSockets & Realtime Systems Programming with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start WebSockets & Realtime Systems Programming?

No prior experience is required. WebSockets & Realtime Systems Programming on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Request-Response over WebSockets” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this WebSockets & Realtime Systems Programming lesson?

Yes. Every WebSockets & Realtime Systems Programming lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

Implementing Publish/Subscribe Messaging
Request-Response over WebSockets
Bidirectional Streaming and Flow Control
Backpressure and Message Batching

← Back to WebSockets & Realtime Systems Programming