APIs and Real-Time Communication

POST   /v1/photos                         create a photo record, get an upload URL
       body { caption, contentType }       → 201 { photoId, uploadUrl } + Location: /v1/photos/{photoId}
       header Idempotency-Key: <uuid>

GET    /v1/photos/{photoId}               → 200 { photoId, ownerId, caption, url, likeCount, createdAt }
                                           → 404 if missing or not visible to the caller

GET    /v1/feed?limit=20&cursor=<opaque>  → 200 { items: [photo…], nextCursor | null }

PUT    /v1/photos/{photoId}/likes/me      like (idempotent: liking twice is still one like) → 204
DELETE /v1/photos/{photoId}/likes/me      unlike → 204

All calls: Authorization: Bearer <token>  · errors: { type, title, detail }  · 429 + Retry-After when limited

// A feed of posts, newest first. Stable order: createdAt DESC, then id DESC as a tie-breaker.
const posts = Array.from({ length: 10 }, (_, i) => ({ id: i + 1, createdAt: 1000 + i * 10 }));
const newestFirst = (a, b) => b.createdAt - a.createdAt || b.id - a.id;
const sorted = () => [...posts].sort(newestFirst);

// Offset pagination: "skip N rows, take LIMIT".
const offsetPage = (offset, limit) => sorted().slice(offset, offset + limit);

// Cursor pagination: the cursor encodes the sort key of the last row the client saw.
const encode = (row) => Buffer.from(JSON.stringify([row.createdAt, row.id])).toString("base64url");
const decode = (cursor) => JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
function cursorPage(cursor, limit) {
  let rows = sorted();
  if (cursor) {
    const [c, id] = decode(cursor); // WHERE (created_at, id) < (c, id)
    rows = rows.filter((p) => p.createdAt < c || (p.createdAt === c && p.id < id));
  }
  const page = rows.slice(0, limit);
  return { page, next: page.length === limit ? encode(page.at(-1)) : null };
}

const ids = (rows) => rows.map((p) => p.id).join(", ");
const LIMIT = 4;

const o1 = offsetPage(0, LIMIT);
const c1 = cursorPage(null, LIMIT);
console.log("page 1   offset:", ids(o1), "  cursor:", ids(c1.page), " next =", c1.next, "→", decode(c1.next));

posts.push({ id: 11, createdAt: 1200 }); // someone posts while the reader is on page 1
console.log("-- post 11 inserted at the top --");

const o2 = offsetPage(LIMIT, LIMIT);
const c2 = cursorPage(c1.next, LIMIT);
console.log("page 2   offset:", ids(o2), "  cursor:", ids(c2.page));
const o3 = offsetPage(2 * LIMIT, LIMIT);
const c3 = cursorPage(c2.next, LIMIT);
console.log("page 3   offset:", ids(o3), "     cursor:", ids(c3.page), " next =", c3.next);

const seen = (pages) => pages.flat().map((p) => p.id);
const dupes = (list) => list.filter((id, i) => list.indexOf(id) !== i);
console.log("offset saw", seen([o1, o2, o3]).length, "rows, duplicates:", dupes(seen([o1, o2, o3])));
console.log("cursor saw", seen([c1.page, c2.page, c3.page]).length, "rows, duplicates:", dupes(seen([c1.page, c2.page, c3.page])));

page 1   offset: 10, 9, 8, 7   cursor: 10, 9, 8, 7  next = WzEwNjAsN10 → [ 1060, 7 ]
-- post 11 inserted at the top --
page 2   offset: 7, 6, 5, 4   cursor: 6, 5, 4, 3
page 3   offset: 3, 2, 1      cursor: 2, 1  next = null
offset saw 11 rows, duplicates: [ 7 ]
cursor saw 10 rows, duplicates: []

// One screen: "my last 5 orders", each showing the product name and the seller name.
const sellers = new Map([1, 2].map((id) => [id, { id, name: `Seller ${id}`, address: "x".repeat(300), rating: 4.8 }]));
const products = new Map([10, 11, 12, 13, 14].map((id, i) =>
  [id, { id, name: `Product ${id}`, sellerId: (i % 2) + 1, description: "x".repeat(600), price: 1999, images: ["a.jpg", "b.jpg"] }]));
const orders = [10, 11, 12, 13, 14].map((productId, i) => ({ id: 100 + i, productId, total: 1999 }));

let dbQueries = 0;
const db = {
  orders: async () => (dbQueries++, orders),
  products: async (ids) => (dbQueries++, ids.map((id) => products.get(id))),
  sellers: async (ids) => (dbQueries++, ids.map((id) => sellers.get(id))),
};
const bytes = (x) => Buffer.byteLength(JSON.stringify(x));

// REST: one resource per call; the client stitches the screen together.
async function rest() {
  dbQueries = 0;
  const responses = [await db.orders()];
  for (const o of orders) {
    const [p] = await db.products([o.productId]);
    const [s] = await db.sellers([p.sellerId]);
    responses.push(p, s); // full resources, every field
  }
  return { roundTrips: responses.length, bytes: responses.reduce((n, r) => n + bytes(r), 0), dbQueries };
}

// GraphQL: one round trip; resolvers fetch each field. `batch` turns on a DataLoader-style batcher.
function loader(fetchMany) {
  let queue = null;
  return (id) => new Promise((resolve) => {
    if (!queue) {
      queue = [];
      queueMicrotask(async () => {
        const batch = queue; queue = null;
        const rows = await fetchMany(batch.map((q) => q.id));
        batch.forEach((q, i) => q.resolve(rows[i]));
      });
    }
    queue.push({ id, resolve });
  });
}
async function graphql(batch) {
  dbQueries = 0;
  const product = batch ? loader(db.products) : async (id) => (await db.products([id]))[0];
  const seller = batch ? loader(db.sellers) : async (id) => (await db.sellers([id]))[0];
  const data = await Promise.all((await db.orders()).map(async (o) => {
    const p = await product(o.productId);
    const s = await seller(p.sellerId);
    return { id: o.id, product: { name: p.name, seller: { name: s.name } } }; // only the fields asked for
  }));
  return { roundTrips: 1, bytes: bytes({ data }), dbQueries };
}

for (const [name, run] of [["REST, resource per call", rest], ["GraphQL, naive resolvers", () => graphql(false)], ["GraphQL + batching", () => graphql(true)]]) {
  const r = await run();
  console.log(`${name.padEnd(25)} round trips ${String(r.roundTrips).padStart(2)}   bytes ${String(r.bytes).padStart(5)}   DB queries ${r.dbQueries}`);
}

REST, resource per call   round trips 11   bytes  5451   DB queries 11
GraphQL, naive resolvers  round trips  1   bytes   370   DB queries 11
GraphQL + batching        round trips  1   bytes   370   DB queries 3

// Assumptions (state them out loud in the interview):
const clients = 1_000_000;      // concurrently open pages
const updateEvery = 60;         // seconds between updates for one client, on average (random arrivals)
const pollEvery = 5;            // short polling interval, seconds
const longPollTimeout = 30;     // the server answers "nothing new" after this long
const heartbeatEvery = 30;      // SSE comment (3 B) or WebSocket ping + pong (8 B) keeps proxies from closing idle connections
const httpOverhead = 700;       // bytes of request + response headers per HTTP exchange (rule of thumb; cookies make it far bigger)
const payload = 200;            // bytes of useful data per update
const sseFraming = 20;          // "id: …\ndata: …\n\n" around the payload
const wsFraming = 4;            // server-to-client frame header for a small message (2-10 bytes in RFC 6455)

const updatesPerSec = clients / updateEvery;
// Long polling: each held request ends at the next update or at the timeout, whichever is first.
// With random (exponential) update arrivals, the mean hold time is updateEvery × (1 − e^(−timeout/updateEvery)).
const meanHold = updateEvery * (1 - Math.exp(-longPollTimeout / updateEvery));

// [name, requests or heartbeats per second, bytes on the wire per second, connections held open, extra delay]
const rows = [
  ["short polling", clients / pollEvery, (clients / pollEvery) * httpOverhead + updatesPerSec * payload, 0, pollEvery / 2],
  ["long polling", clients / meanHold, (clients / meanHold) * httpOverhead + updatesPerSec * payload, clients, 0],
  ["SSE", clients / heartbeatEvery, updatesPerSec * (payload + sseFraming) + (clients / heartbeatEvery) * 3, clients, 0],
  ["WebSocket", clients / heartbeatEvery, updatesPerSec * (payload + wsFraming) + (clients / heartbeatEvery) * 8, clients, 0],
];

const fmt = (n) => Math.round(n).toLocaleString("en-US");
console.log(`updates to deliver: ${fmt(updatesPerSec)}/s; long-poll mean hold ${meanHold.toFixed(1)} s`);
console.log("approach        requests/s (or pings/s)       MB/s  held open   average delay");
for (const [name, perSec, bytesPerSec, open, delay] of rows) {
  const useful = name.includes("polling") ? ` (${((updatesPerSec / perSec) * 100).toFixed(0)}% carry news)` : " (heartbeats)";
  console.log(`${name.padEnd(15)} ${fmt(perSec).padStart(7)}${useful.padEnd(18)} ${(bytesPerSec / 1e6).toFixed(1).padStart(7)}  ${fmt(open).padStart(9)}   ${delay ? `+${delay} s` : "network only"}`);
}

updates to deliver: 16,667/s; long-poll mean hold 23.6 s
approach        requests/s (or pings/s)       MB/s  held open   average delay
short polling   200,000 (8% carry news)     143.3          0   +2.5 s
long polling     42,358 (39% carry news)     33.0  1,000,000   network only
SSE              33,333 (heartbeats)          3.8  1,000,000   network only
WebSocket        33,333 (heartbeats)          3.7  1,000,000   network only

// 1,000 users connected to 10 WebSocket servers; 200 group chats of 5 members. Seeded, so it is repeatable.
function mulberry32(seed) {
  return () => {
    seed = (seed + 0x6d2b79f5) | 0;
    let t = Math.imul(seed ^ (seed >>> 15), 1 | seed);
    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
  };
}
const rand = mulberry32(7);
const pick = (n) => Math.floor(rand() * n);

const SERVERS = 10, USERS = 1000, ROOMS = 200;
const serverOf = Array.from({ length: USERS }, () => pick(SERVERS)); // the load balancer's choice
const members = Array.from({ length: ROOMS }, () => new Set(Array.from({ length: 5 }, () => pick(USERS))));

// The backplane (think Redis pub/sub): channel -> set of subscribed servers.
class Backplane {
  subs = new Map();
  deliveries = 0;
  subscribe(channel, server) {
    if (!this.subs.has(channel)) this.subs.set(channel, new Set());
    this.subs.get(channel).add(server);
  }
  publish(channel, msg, onDeliver) {
    for (const server of this.subs.get(channel) ?? []) { this.deliveries++; onDeliver(server, msg); }
  }
}

function run(mode) {
  const bp = new Backplane();
  for (let s = 0; s < SERVERS; s++) {
    if (mode === "every server gets everything") bp.subscribe("all", s);
    else members.forEach((m, room) => { if ([...m].some((u) => serverOf[u] === s)) bp.subscribe(`room:${room}`, s); });
  }
  let pushes = 0, wasted = 0;
  const r = mulberry32(42);
  for (let i = 0; i < 1000; i++) {
    const room = Math.floor(r() * ROOMS);
    bp.publish(mode === "every server gets everything" ? "all" : `room:${room}`, { room }, (server, msg) => {
      const local = [...members[msg.room]].filter((u) => serverOf[u] === server); // sockets on this server
      pushes += local.length;
      if (local.length === 0) wasted++;
    });
  }
  console.log(`${mode.padEnd(30)} backplane deliveries ${String(bp.deliveries).padStart(6)}  wasted ${String(wasted).padStart(5)}  socket pushes ${pushes}`);
}

const room7 = [...members[7]].map((u) => `u${u}@S${serverOf[u]}`).join(" ");
console.log("room 7 members:", room7);
run("every server gets everything");
run("servers subscribe per room");

room 7 members: u619@S7 u57@S6 u945@S6 u400@S6 u200@S3
every server gets everything   backplane deliveries  10000  wasted  5999  socket pushes 4996
servers subscribe per room     backplane deliveries   4001  wasted     0  socket pushes 4996

import { createHmac, timingSafeEqual } from "node:crypto";

const SECRET = "whsec_demo_only"; // shared once, out of band, per receiving endpoint
const TOLERANCE_SEC = 300;        // 5 minutes, the default in Stripe's libraries

// Sender: sign "timestamp.rawBody" and send both in one header.
function sign(rawBody, timestamp, secret = SECRET) {
  const mac = createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  return `t=${timestamp},v1=${mac}`;
}

// Receiver: recompute over the exact bytes received, compare in constant time, then check freshness.
function verify(rawBody, header, nowSec) {
  const parts = Object.fromEntries(header.split(",").map((kv) => kv.split("=")));
  const expected = Buffer.from(createHmac("sha256", SECRET).update(`${parts.t}.${rawBody}`).digest("hex"));
  const given = Buffer.from(parts.v1 ?? "");
  if (given.length !== expected.length || !timingSafeEqual(given, expected)) return "reject: bad signature";
  const age = nowSec - Number(parts.t);
  if (Math.abs(age) > TOLERANCE_SEC) return `reject: too old (${age} s)`;
  return "accept";
}

const body = '{"id":"evt_1","type":"payment.succeeded","amount":5000}';
const sentAt = 1_790_000_000; // a fixed clock, in seconds
const header = sign(body, sentAt);
console.log("header:", header.slice(0, 32) + "…");

const cases = [
  ["genuine, 2 s later", body, header, sentAt + 2],
  ["amount changed in transit", body.replace("5000", "500000"), header, sentAt + 2],
  ["body re-serialised by a JSON parser", JSON.stringify(JSON.parse(body), null, 1), header, sentAt + 2],
  ["captured and replayed 1 hour later", body, header, sentAt + 3600],
  ["replayed with a fresh t= but the old v1", body, header.replace(`t=${sentAt}`, `t=${sentAt + 3600}`), sentAt + 3600],
  ["signed with someone else's secret", body, sign(body, sentAt, "whsec_attacker"), sentAt + 2],
];
for (const [label, raw, h, now] of cases) console.log(`${label.padEnd(40)} → ${verify(raw, h, now)}`);

header: t=1790000000,v1=682b97a5f32fb39f…
genuine, 2 s later                       → accept
amount changed in transit                → reject: bad signature
body re-serialised by a JSON parser      → reject: bad signature
captured and replayed 1 hour later       → reject: too old (3600 s)
replayed with a fresh t= but the old v1  → reject: bad signature
signed with someone else's secret        → reject: bad signature

// Policy: "10 requests per 10 seconds" (a sustained rate of 1/s). One client, one seeded trace.
const LIMIT = 10, WINDOW = 10_000;
function mulberry32(seed) {
  return () => {
    seed = (seed + 0x6d2b79f5) | 0;
    let t = Math.imul(seed ^ (seed >>> 15), 1 | seed);
    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
  };
}
const rand = mulberry32(2026);
const trace = [];
for (let t = 0; t < 30_000; t += 250) if (rand() < 0.12) trace.push(t);       // background, about 0.5/s
for (let i = 0; i < 10; i++) trace.push(9_500 + i * 50, 10_000 + i * 50);      // a burst either side of t = 10 s
trace.sort((a, b) => a - b);

const limiters = {
  "fixed window": () => { const n = new Map(); return (t) => { const w = Math.floor(t / WINDOW); const c = (n.get(w) ?? 0) + 1; n.set(w, c); return c <= LIMIT; }; },
  "sliding log": () => { const log = []; return (t) => { while (log.length && log[0] <= t - WINDOW) log.shift(); if (log.length >= LIMIT) return false; log.push(t); return true; }; },
  "sliding counter": () => {
    const n = new Map();
    return (t) => {
      const w = Math.floor(t / WINDOW);
      const est = (n.get(w - 1) ?? 0) * (1 - (t % WINDOW) / WINDOW) + (n.get(w) ?? 0);
      if (est >= LIMIT) return false;
      n.set(w, (n.get(w) ?? 0) + 1);
      return true;
    };
  },
  "token bucket": () => {
    let credit = LIMIT * 1000, last = 0; // capacity 10 tokens, refill 1 per second; counted in ms so it stays exact
    return (t) => { credit = Math.min(LIMIT * 1000, credit + (t - last)); last = t; if (credit < 1000) return false; credit -= 1000; return true; };
  },
};

// The number that matters to the backend: the most requests it ever saw in any 10-second span.
const worstSpan = (ts) => Math.max(...ts.map((s) => ts.filter((t) => t >= s && t < s + WINDOW).length));
const inBurst = (ts) => ts.filter((t) => t >= 9_500 && t < 10_500).length;

console.log(`trace: ${trace.length} requests in 30 s, 20 of them between 9.5 s and 10.5 s`);
console.log("algorithm         accepted  rejected  burst accepted  worst 10 s span");
for (const [name, make] of Object.entries(limiters)) {
  const allow = make();
  const ok = trace.filter((t) => allow(t));
  console.log(`${name.padEnd(17)} ${String(ok.length).padStart(8)}  ${String(trace.length - ok.length).padStart(8)}  ${String(inBurst(ok)).padStart(14)}  ${String(worstSpan(ok)).padStart(15)}`);
}

trace: 35 requests in 30 s, 20 of them between 9.5 s and 10.5 s
algorithm         accepted  rejected  burst accepted  worst 10 s span
fixed window            25        10              14               20
sliding log             18        17               4               10
sliding counter         19        16               5               11
token bucket            24        11               9               16

import { createHash } from "node:crypto";

let now = 0;                                  // fake clock, in hours
const TTL_HOURS = 24;
const keys = new Map();                       // key -> { state, fingerprint, response, expiresAt }
const charges = [];                           // what actually hit the card network
const fingerprint = (body) => createHash("sha256").update(JSON.stringify(body)).digest("hex").slice(0, 12);

// POST /payments. `gate` lets the demo pause the charge to create a concurrent duplicate.
async function createPayment(key, body, gate = Promise.resolve()) {
  const fp = fingerprint(body);
  const row = keys.get(key);
  if (row && row.expiresAt <= now) keys.delete(key);  // expired: forget it
  const existing = keys.get(key);
  if (existing) {
    if (existing.fingerprint !== fp) return [422, "key reused with a different body"];
    if (existing.state === "in_progress") return [409, "original request still running, retry later"];
    return [...existing.response, "(replayed)"];
  }
  // Claim the key atomically before doing anything (in a database: INSERT ... unique key; in Redis: SET NX).
  keys.set(key, { state: "in_progress", fingerprint: fp, expiresAt: now + TTL_HOURS });
  await gate;
  const id = `pay_${charges.push({ key, ...body })}`;
  const response = [201, id];
  Object.assign(keys.get(key), { state: "done", response });
  return response;
}

const log = (label, r) => console.log(label.padEnd(44), r.join(" "));

log("1. first attempt (reply lost on the way back)", await createPayment("k-7f3a", { amount: 5000 }));
log("2. client retries with the same key", await createPayment("k-7f3a", { amount: 5000 }));
log("3. same key, amount changed by a bug", await createPayment("k-7f3a", { amount: 9000 }));

let release;
const slow = createPayment("k-91bc", { amount: 1200 }, new Promise((r) => (release = r)));
log("4. double-click while the first is running", await createPayment("k-91bc", { amount: 1200 }));
release();
log("   ...the first one finishes", await slow);

now = 25;
log("5. same key again 25 hours later", await createPayment("k-7f3a", { amount: 5000 }));
console.log("charges made:", charges.map((c) => `${c.key}:${c.amount}`).join(", "));

1. first attempt (reply lost on the way back) 201 pay_1
2. client retries with the same key          201 pay_1 (replayed)
3. same key, amount changed by a bug         422 key reused with a different body
4. double-click while the first is running   409 original request still running, retry later
   ...the first one finishes                 201 pay_2
5. same key again 25 hours later             201 pay_3
charges made: k-7f3a:5000, k-91bc:1200, k-7f3a:5000

// Compare two versions of an API contract and classify each difference the way a reviewer would.
// A field is { type, required } (requests) or { type } (responses); enums list their values.
const v1 = {
  request: { sku: { type: "string", required: true }, qty: { type: "integer", required: true } },
  response: { id: { type: "string" }, status: { type: "enum", values: ["paid", "refunded"] }, total: { type: "integer" }, note: { type: "string" } },
};
const v2 = {
  request: { sku: { type: "string", required: true }, qty: { type: "integer", required: true }, giftWrap: { type: "boolean", required: false }, region: { type: "string", required: true } },
  response: { id: { type: "string" }, status: { type: "enum", values: ["paid", "refunded", "disputed"] }, total: { type: "string" }, eta: { type: "string" } },
};

function diff(oldC, newC) {
  const out = [];
  for (const [name, f] of Object.entries(newC.request)) {
    const was = oldC.request[name];
    if (!was) out.push([f.required ? "BREAKING" : "safe", `request field "${name}" added (${f.required ? "required: old clients don't send it" : "optional"})`]);
    else if (f.required && !was.required) out.push(["BREAKING", `request field "${name}" became required`]);
  }
  for (const [name, f] of Object.entries(oldC.response)) {
    const now = newC.response[name];
    if (!now) out.push(["BREAKING", `response field "${name}" removed (clients may read it)`]);
    else if (now.type !== f.type) out.push(["BREAKING", `response field "${name}" changed ${f.type} → ${now.type}`]);
    else if (f.type === "enum") {
      const added = now.values.filter((v) => !f.values.includes(v));
      if (added.length) out.push(["RISKY", `response enum "${name}" gained ${added.join(", ")} (strict switch statements break)`]);
    }
  }
  for (const name of Object.keys(newC.response)) {
    if (!oldC.response[name]) out.push(["safe", `response field "${name}" added (tolerant readers ignore it)`]);
  }
  return out;
}

for (const [kind, text] of diff(v1, v2)) console.log(kind.padEnd(9), text);