Choosing how clients and services communicate

HOW IT FITS TOGETHER

KEY TERMS

Sync, streaming and async

Sync request/response couples the caller's latency and availability to yours, which is why it suits reads and user-facing commands. Streaming keeps one connection and costs a held socket per client. Async messaging separates the producer from the consumer in time. The producer only learns that a message was accepted, so outcomes come back through another channel: a status resource, an event or a webhook.

Direction and initiator

A browser can only open connections. For the server to speak first, the client must already hold a connection (SSE, WebSocket, long poll), or a third party must deliver for you (APNs, FCM and Web Push services, or a partner's webhook endpoint). This one fact rules out half the options for any server-initiated feature.

Freshness budget

Put a number on it. Polling every 30 s is fine for an order that ships in days. Seconds-level freshness for a few thousand users is a single SSE endpoint. Sub-second interaction at large scale means a dedicated realtime tier with pub/sub fan-out. Each step up adds connection state you must route, drain and observe.

Consumer type sets the floor

Partners need stable REST and signed webhooks, because they won't regenerate your stubs or run your SDK. Browsers rule out native gRPC (use gRPC-Web or Connect) and custom headers on EventSource and WebSocket. Mobile clients rule out relying on a socket while the app is backgrounded. Internal services can afford strict schemas and generated clients.

Contract and coupling

Coupling is a dial. tRPC shares types and needs both sides deployed together. gRPC and GraphQL share a schema and allow additive change. REST with OpenAPI tolerates the widest range of consumers and the slowest upgrades. Queues and webhooks also decouple time, but their payload schema becomes a public contract that consumers read long after it was written.

Delivery guarantees live in storage

No transport gives exactly-once. Queues and webhook senders give at-least-once with redelivery. WebSocket and SSE give at-most-once unless you add sequence numbers and a replayable log. Write the event to an outbox in the same transaction as the state change, deliver at least once, and dedupe at the consumer by event id.

Long-running jobs

Return 202 Accepted with a Location to a status resource. RFC 9110 says the 202 body ought to describe the current status and point to a status monitor. Clients poll it with backoff or ETag. Partners can register a callback webhook, and internal consumers subscribe to a job.completed event. Require an idempotency key on the creating POST so a retried submit doesn't start a second job.

IN YOUR STACK

// Server: the ETag comes from the order's version, so an unchanged poll costs one indexed read
app.get("/orders/:id/status", async (req, res) => {
  const order = await db.orders.findForUser(req.params.id, req.user.id); // ownership check
  if (!order) return res.sendStatus(404);
  const etag = `"o${order.id}-v${order.version}"`;
  res.set({ ETag: etag, "Cache-Control": "private, no-cache" });
  if (req.get("If-None-Match") === etag) return res.status(304).end();
  res.json({ status: order.status, updatedAt: order.updatedAt });
});

// Client: conditional GET, jittered interval, paused while the tab is hidden
let etag: string | null = null, timer: ReturnType<typeof setTimeout> | undefined;
async function poll(id: string) {
  try {
    const res = await fetch(`/orders/${id}/status`, { headers: etag ? { "If-None-Match": etag } : {} });
    if (res.status === 200) {
      etag = res.headers.get("ETag");
      render(await res.json());
    } // 304: nothing changed, no body transferred
  } catch { /* offline: try again next tick */ }
  clearTimeout(timer); // keep a single loop, however often visibilitychange fires
  if (document.visibilityState === "visible") timer = setTimeout(() => poll(id), 10_000 + Math.random() * 3_000);
}
document.addEventListener("visibilitychange", () => { if (document.visibilityState === "visible") poll(orderId); });

app.get("/orders/:id/events", async (req, res) => {
  if (!(await canSee(req.user, req.params.id))) return res.sendStatus(404);
  res.set({ "Content-Type": "text/event-stream", "Cache-Control": "no-cache", "X-Accel-Buffering": "no" });
  res.flushHeaders();
  const send = (e: OrderEvent) => res.write(`id: ${e.seq}\nevent: status\ndata: ${JSON.stringify(e)}\n\n`);

  let last = Number(req.get("Last-Event-ID") ?? 0);
  const live: OrderEvent[] = [];
  let replaying = true;
  const off = bus.subscribe(`order:${req.params.id}`, (e) => (replaying ? live.push(e) : send(e)));
  for (const e of await events.since(req.params.id, last)) { send(e); last = e.seq; } // fill the gap
  live.filter((e) => e.seq > last).forEach(send); // events published during the replay
  replaying = false;

  const ping = setInterval(() => res.write(": ping\n\n"), 15_000); // beats proxy idle timeouts
  req.on("close", () => { clearInterval(ping); off(); });
});

// Browser: reconnects by itself and sends Last-Event-ID; no custom headers, so use cookies
const es = new EventSource(`/orders/${orderId}/events`, { withCredentials: true });
es.addEventListener("status", (e) => render(JSON.parse(e.data)));

import { WebSocketServer } from "ws";
const wss = new WebSocketServer({ noServer: true, maxPayload: 64 * 1024 });

server.on("upgrade", async (req, socket, head) => {
  const user = await authenticate(req).catch(() => null); // cookie + Origin allowlist, or a one-time ticket
  if (!user) return socket.destroy();
  wss.handleUpgrade(req, socket, head, (ws) => {
    const subs = new Map<string, () => void>();
    const push = (e: OrderEvent) => {
      if (ws.bufferedAmount > 1 << 20) return ws.terminate(); // slow consumer: drop it; it will resync
      ws.send(JSON.stringify(e));
    };
    ws.on("message", async (raw) => {
      let msg: { type: string; orderId: string; afterSeq?: number };
      try { msg = JSON.parse(raw.toString()); } catch { return ws.close(1003, "bad json"); }
      if (msg.type !== "watch" || subs.has(msg.orderId) || !(await canSee(user, msg.orderId))) return;
      subs.set(msg.orderId, bus.subscribe(`order:${msg.orderId}`, push)); // then replay; client dedupes by seq
      for (const e of await events.since(msg.orderId, msg.afterSeq ?? 0)) push(e);
    });
    ws.on("close", () => subs.forEach((off) => off()));
  });
});

import { createHmac } from "node:crypto";

// Runs inside a durable job (one job per delivery), not a request handler
export async function deliver(endpoint: { url: string; secret: string }, event: OrderEvent, attempt: number) {
  const id = event.eventId; // stable across retries so the partner can dedupe
  const body = JSON.stringify({ type: "order.status_changed", timestamp: event.at, data: event });
  const ts = Math.floor(Date.now() / 1000).toString();
  const key = Buffer.from(endpoint.secret.replace(/^whsec_/, ""), "base64");
  const signature = createHmac("sha256", key).update(`${id}.${ts}.${body}`).digest("base64");

  const res = await fetch(endpoint.url, {
    method: "POST",
    body,
    redirect: "manual", // never follow redirects to internal addresses
    signal: AbortSignal.timeout(10_000),
    headers: { "content-type": "application/json", "webhook-id": id, "webhook-timestamp": ts, "webhook-signature": `v1,${signature}` },
  }).catch(() => null);

  if (res?.ok) return { done: true };
  if (attempt >= 12) return { done: true, deadLetter: true }; // show in the partner's dashboard, allow replay
  return { done: false, retryInSeconds: Math.min(2 ** attempt * 30, 6 * 3600) }; // exponential, capped
}

import { SQSClient, ReceiveMessageCommand, DeleteMessageCommand } from "@aws-sdk/client-sqs";
const sqs = new SQSClient({});
const QueueUrl = process.env.ORDER_EVENTS_QUEUE_URL!;

while (running) {
  const { Messages = [] } = await sqs.send(new ReceiveMessageCommand({
    QueueUrl, MaxNumberOfMessages: 10, WaitTimeSeconds: 20, VisibilityTimeout: 60, // long poll
  }));
  for (const m of Messages) {
    try {
      const event = JSON.parse(m.Body!) as OrderEvent;
      // At-least-once and (standard queues) unordered: dedupe by id, apply only newer seq
      await db.transaction(async (tx) => {
        if (!(await tx.processedEvents.insertIfAbsent(event.eventId))) return;
        await tx.orderViews.upsertIfNewer(event.orderId, { status: event.status, seq: event.seq });
      });
      await sqs.send(new DeleteMessageCommand({ QueueUrl, ReceiptHandle: m.ReceiptHandle! }));
    } catch (err) {
      // Not deleted: it reappears after the visibility timeout; the redrive policy moves it to a DLQ
      log.error({ err, messageId: m.MessageId }, "order event failed");
    }
  }
}

WHEN TO REACH FOR WHAT

WHERE IT BITES

• Choosing by fashion instead of by the questions: a WebSocket tier for updates that change once an hour, or GraphQL for one fixed screen. Each adds infrastructure you must run for years.
• Using a push channel as the source of truth. Sockets drop, push is throttled and SSE ids reset if they aren't durable. Every client needs a way to fetch the current state over HTTP after a reconnect.
• Chaining synchronous calls across services for work that could be async. Availability multiplies (99.9% to the power of 5 is about 99.5%), and one slow dependency ties up every caller's threads.
• Assuming exactly-once anywhere. Queues redeliver, webhook senders retry and clients double-submit. Use idempotency keys on commands and dedupe consumers by event id.
• Ignoring the consumer's lifecycle. Mobile apps run old versions for months and lose sockets in the background, and partners upgrade yearly. Contracts must evolve additively, and freshness must not depend on a live connection.
• Long-running work inside a request. Proxies and load balancers cut connections at 30 to 100 s, users retry, and the job runs twice. Use 202 plus a job id, with an idempotency key on the create call.

WHEN IT BREAKS IN PRODUCTION

• WebSockets disconnect, duplicate, or lose events
• Webhooks arrive twice, late, or out of order
• One request waits on a chain of services and times out
• A brief blip turns into a long outage
• One bad message blocks or floods the queue
• A background job runs on every replica
• A retry creates two payments
• The database and the queue disagree after a failure
• A backend deploy breaks old app versions
• The frontend breaks when the API response changes
• The UI shows old data after a save
• Search results show an older query's results
• Memory balloons when producers outpace consumers
• Large uploads crash the server or time out
• Push notifications never arrive for some users
• A third-party API starts returning 429
• One big account posts and everyone's feed lags
• Our microservices can only be released together
• Offline edits conflict or vanish on reconnect
• A "fetch this URL" feature reaches internal services

SOURCES

• RFC 9110: HTTP Semantics (202 Accepted, conditional requests) (opens in new tab)Checked 2026-11-06
• MDN: If-None-Match (opens in new tab)Checked 2026-11-06
• MDN: EventSource (opens in new tab)Checked 2026-11-06
• Standard Webhooks specification (opens in new tab)Checked 2026-11-06
• Amazon SQS: Short and long polling (opens in new tab)Checked 2026-11-06