Streaming¶

Contents | Previous: Authentication, TLS, and Proxy | Next: Client and Request Lifecycle

After reading this chapter

This chapter processes a response in chunks and sends a request body in parts. Its code comes from each language's HttpClient tutorial.

Streaming moves a large body through a caller callback or provider. Unlike a JSON body, it does not serialize or accumulate the whole body. Response Rules covers status and compression rules.

↗ 크게 보기

The provider and sink are each consumed once while the body moves. This is why the streaming path does not apply replay or transparent decompression.

1. Response Chunks Flow Through a Download Sink¶

A download sink is a callback invoked for each received body chunk. A raw response carries status, headers, and the body before JSON decoding. The final raw response from a download preserves status and headers; bodies from intermediate redirect responses do not reach the sink.

let downloadChunks = 0;
let downloadBytes = 0;
await client.get(`/rooms/${room}/export`).download((chunk) => {
  downloadChunks++;
  downloadBytes += chunk.byteLength;
});
console.log(`download stream: chunks ${downloadChunks} bytes ${downloadBytes}`);

The example counts each export-body chunk and accumulates the total number of chunks and bytes.

2. Request Chunks Come from a Body Stream Provider¶

A body stream provider returns the next chunk to send and signals completion with the language's empty value. Its configuration includes the content type.

const uploadChunks = [
  encoder.encode('{"playerId":"p2","text":"one"}\n'),
  encoder.encode('{"playerId":"p2","text":"two"}\n'),
  encoder.encode('{"playerId":"p2","text":"three"}\n')
];
let uploadIndex = 0;
const imported = await client
  .post(`/rooms/${room}/import`)
  .bodyStream(() => uploadChunks[uploadIndex++] ?? null, 'application/x-ndjson')
  .fetch<ImportedResult>();
console.log(`upload stream: imported ${imported.imported}`);

The example supplies three NDJSON lines in sequence and confirms that the server imported three items.

3. Retry and Decompression Are Excluded¶

A download sink and a body stream provider consume their body once and cannot recreate it. A streaming request is therefore excluded from retry and redirect replay. A download sink receives compressed response bytes unchanged; decompression is not applied.

4. Next Chapter¶

Client and Request Lifecycle covers client reuse, close timing, response completion, and timeout boundaries.