Learning

4.2 Streams, queues, and the quota-aware sender

Why ReadableStream bodies always throw under keepalive, and the batching queue recipe that moves many events through one pool slot.

Levels: Intermediate ~15 min read

Intermediate

Two engineering problems grow out of the quota: a stream-shaped one (why the platform refuses the most natural body type) and a batching one (how to move many small events through one pool slot). This page takes them in order, then assembles the answer into the queue recipe that real telemetry SDKs are built around.

Why ReadableStream is refused

The IDL accepts a stream — BodyInit includes ReadableStream, so the call type-checks — but the extraction algorithm refuses it one step later: "If keepalive is true, then throw a TypeError" is the entire rule, and beacons always set it (part three triggered the throw live). The reason is structural: a keepalive request must be re-sendable after its origin page dies, and a stream can only be read once — so the platform refuses at the boundary instead of losing data later, with an honest, synchronous TypeError at call time.

The workaround is not a workaround at all — it is the intended shape: buffer the stream yourself, then send the bytes. await stream.text() or a reader loop materializes the content, and a string or Blob body is quota-countable, retryable, and legal. The service-worker page of this series meets the same rule from the other side, when forwarding intercepted requests whose bodies are streams.

Batching: one beacon, one pool slot

Events of a few hundred bytes are the normal case, and sending each as its own beacon wastes pool slots and OS sockets. The fix is to batch: accumulate stringified events, and flush them as a single JSON-array body — one request, one slot, one Content-Type. The design questions are when to flush (before the buffer would cross the budget), what to do when the pool says no (keep the batch, never retry inline), and how to measure (UTF-8 bytes via new Blob([s]).size, never string.length — a string of emoji measures 2 UTF-16 units but 4 UTF-8 bytes, and the quota counts bytes).

Interactive Runnable example

Edit

// BeaconQueue: the quota-aware batching queue.
//
// What it encodes, from the specs:
//   - One beacon request = one slot in the shared 64 KiB in-flight
//     pool, so small events are BATCHED into a single JSON-array
//     body instead of one beacon each.
//   - sendBeacon's false is the only synchronous saturation signal;
//     overflow batches are kept and drained later (never retried
//     inline — the pool refills only as requests complete).
//   - Payload sizes are measured in UTF-8 bytes with
//     new Blob([s]).size — the unit the quota actually counts.
//   - The send function is injectable: the default is the real
//     navigator.sendBeacon; tests pass a mock that enforces a quota.

const KIBIBYTE = 1024;
const QUOTA_BYTES = 64 * KIBIBYTE;
// Headroom because the pool is SHARED with every other in-flight
// keepalive request of this fetch group (fetch(keepalive) included),
// and the §4.6 sum includes them all — not because the spec counts
// headers or URLs (it counts body lengths only):
const BUDGET = QUOTA_BYTES - 2048;

class BeaconQueue {
  constructor(url, send) {
    this.url = url;
    this.send = send || ((u, d) => navigator.sendBeacon(u, d));
    this.buffer = [];
    this.bufferBytes = 0;
    this.overflow = [];
  }

add(event) {
    const chunk = JSON.stringify(event);
    const chunkBytes = new Blob([chunk]).size;
    // Pre-flush BEFORE adding: if this event would cross the
    // budget, ship what we have and start a fresh buffer:
    if (this.bufferBytes + chunkBytes > BUDGET) {
      if (!this.flush()) return false;
    }
    this.buffer.push(chunk);
    this.bufferBytes += chunkBytes;
    return true;
  }

flush() {
    if (this.buffer.length === 0) return true;
    const payload = '[' + this.buffer.join(',') + ']'; // one JSON array
    this.buffer = [];
    this.bufferBytes = 0;
    const queued = this.send(this.url, payload);
    if (!queued) {
      // false = the pool is full right now. Keep the batch for a
      // later drain; do NOT retry inline.
      this.overflow.push({ data: payload, bytes: new Blob([payload]).size });
    }
    return queued;
  }

drainOverflow() {
    let sent = 0;
    const remaining = [];
    for (const batch of this.overflow) {
      if (this.send(this.url, batch.data)) sent++;
      else remaining.push(batch);
    }
    this.overflow = remaining;
    return sent;
  }

get pendingCount() { return this.buffer.length; }
  get pendingBytes() { return this.bufferBytes; }
  get overflowCount() { return this.overflow.length; }
}

// -- Demonstrate with a mocked send that enforces the §4.6 rule: --
// (occupancy is explicit: settleAll() simulates requests completing
//  and releasing their pool slots — the real pool refills the same
//  way, on its own schedule)
let inflightBytes = 0;
const mockSend = (url, data) => {
  const bytes = new Blob([data]).size;
  if (bytes + inflightBytes > QUOTA_BYTES) return false; // pool full
  inflightBytes += bytes;
  return true;
};
const settleAll = () => { inflightBytes = 0; };

const q = new BeaconQueue('https://collect.example.com/ingest', mockSend);

// Phase A: a burst of small events (~300 bytes each). The queue
// pre-flushes a full batch mid-burst (one pool slot):
for (let i = 0; i < 400; i++) {
  q.add({ id: i, event: 'tick', pad: 'x'.repeat(260) });
}
console.log('after burst : pending events =', q.pendingCount,
  '| buffer bytes =', q.pendingBytes);

// The mid-burst batch completed (its slot is released):
settleAll();
console.log('flush #1    =>', q.flush(), '| overflow =', q.overflowCount);

// Phase B: heavy events (~2 KiB each) while flush #1's batch is
// still in flight — the mid-burst pre-flush is refused, and that
// batch survives in overflow instead of being lost:
for (let i = 0; i < 60; i++) {
  q.add({ heavy: i, pad: 'x'.repeat(1900) });
}
settleAll();                 // the earlier batches completed
const ok = q.flush();        // ships what it can
console.log('flush #2    =>', ok, '| overflow =', q.overflowCount);

// Phase C: the pool drains — overflow batches are recoverable:
settleAll();
console.log('drainOverflow() recovered', q.drainOverflow(),
  'batches | remaining =', q.overflowCount);

Ready to run.

Reading the output: the burst phase pre-flushes a full batch mid-stream (the pre-flush fires before adding the event that would overflow, so the buffer never splits an event); the settle phases simulate requests completing and releasing their slots; the refused flush lands in overflow instead of vanishing; and the drain recovers it once the pool refills. The injectable send function is what makes the whole recipe testable — the demo runs the real §4.6 arithmetic inside the mock, and the same class runs against navigator.sendBeacon in production without changing a line.

Quick check

Why does the queue measure sizes with new Blob([s]).size instead of s.length?

const chunk = JSON.stringify(event);
const size = ?; // must equal the wire bytes

Key takeaways

Streams type-check but always throw: extraction refuses ReadableStream when keepalive is true, because a one-shot stream cannot be re-sent after the page dies.
Buffer streams yourself — await stream.text() — then send the bytes as a string or Blob.
Batch small events into one JSON-array body: one beacon, one pool slot.
Pre-flush before the budget would be crossed; measure in UTF-8 bytes with Blob.size.
On false: keep the batch and drain later — the pool refills only as in-flight requests complete.

Was this page helpful?

Yes No

Mark this learning resource complete to track your learning progress.

Suggest an edit