[G1-Sync] Manual knowledge update
This commit is contained in:
Antigravity Agent
@@ -1,34 +1,142 @@
|
||||
---
|
||||
category: Computer_Science_and_Theory
|
||||
tags: [auto-wikified, technical-documentation, computer_science_and_theory]
|
||||
id: wiki-2026-0508-스트림-stream
|
||||
title: 스트림(Stream)
|
||||
description: "스트림(Stream)은 데이터를 한 번에 모두 전송하거나 기다리지 않고, 사용 가능한 시점마다 점진적으로 청크(Chunk) 단위로 전송하여 애플리케이션의 성능과 사용자 경험을 향상시키는 기법이다 [1, 2]."
|
||||
last_updated: 2026-05-04
|
||||
category: 10_Wiki/Topics
|
||||
status: verified
|
||||
canonical_id: self
|
||||
aliases: [stream, streaming]
|
||||
duplicate_of: none
|
||||
source_trust_level: A
|
||||
confidence_score: 0.95
|
||||
verification_status: applied
|
||||
tags: [stream, async, io]
|
||||
raw_sources: []
|
||||
last_reinforced: 2026-05-10
|
||||
github_commit: pending
|
||||
tech_stack:
|
||||
language: typescript
|
||||
framework: nodejs
|
||||
---
|
||||
|
||||
# 스트림(Stream)
|
||||
|
||||
## 📌 Brief Summary
|
||||
스트림(Stream)은 데이터를 한 번에 모두 전송하거나 기다리지 않고, 사용 가능한 시점마다 점진적으로 청크(Chunk) 단위로 전송하여 애플리케이션의 성능과 사용자 경험을 향상시키는 기법이다 [1, 2]. 프론트엔드 환경(특히 React 19 및 Next.js)에서는 서버 컴포넌트(RSC)와 결합하여 오래 걸리는 쿼리가 전체 페이지 렌더링을 차단하지 않도록 비순차적 스트리밍(Out-of-order streaming)을 구현하는 데 사용된다 [1, 3]. 백엔드 프레임워크인 NestJS나 Express.js 등에서는 인터셉터 파이프라인에서 RxJS 스트림을 활용하거나 복잡한 다중 실시간 데이터 스트림을 효율적으로 제어하는 데 활용된다 [4, 5].
|
||||
## 매 한 줄
|
||||
> **"매 데이터를 chunk 단위로 점진 전달한다"**. 매 entire payload 를 buffer 에 fully load 하지 않고, 매 사용 가능한 시점마다 chunk 를 yield → 매 memory footprint 감소 + first-byte latency 개선. 매 modern web (Server-Sent Events · LLM token streaming · HTTP/2 push) 의 backbone.
|
||||
|
||||
## 📖 Core Content
|
||||
* **React Server Components (RSC)에서의 비순차적 스트리밍 (Out-of-order Streaming)**
|
||||
* React의 RSC 아키텍처는 모든 데이터를 기다렸다가 화면을 그리는 대신, 셸(Shell)과 같은 즉시 렌더링 가능한 부분을 먼저 클라이언트 측으로 전송한다 [2, 6].
|
||||
* 일부 데이터 로드가 지연되더라도 준비된 HTML을 먼저 보내고, 느리게 로드되는 데이터는 서버에서 준비되는 대로 브라우저로 푸시(push)하는 비순차적 스트리밍을 지원한다 [1, 7].
|
||||
* 이 과정에서 HTML 파일이 여러 청크로 나뉘어 스트리밍되므로, 브라우저는 자바스크립트나 무거운 스크립트 태그를 기다리지 않고도 UI를 신속하게 그릴 수 있다 [2].
|
||||
## 매 핵심
|
||||
|
||||
* **Suspense와의 결합 및 페이로드 전송**
|
||||
* React Suspense와 스트리밍을 결합하면 RSC 페이로드가 클라이언트로 스트리밍되는 과정을 지능적으로 표시할 수 있다 [8]. 서버 컴포넌트가 아직 준비되지 않았다면 '로딩 중' 형태의 폴백(Fallback) 상태를 렌더링하고, 데이터를 가져오는 긴 쿼리 작업이 페이지 렌더링을 차단(Blocking)하지 않게 만든다 [3, 6, 8].
|
||||
* 서버 컴포넌트에서 데이터 조회가 완료되면 해당 내용이 RSC 페이로드로 직렬화되어 클라이언트로 스트리밍되며, 이 과정에서 사용된 자바스크립트는 프론트엔드 번들에 추가되지 않는다 [9].
|
||||
### 매 Stream 의 종류
|
||||
- **Readable**: pull-based source (file read, HTTP response).
|
||||
- **Writable**: push-based sink (file write, response.write).
|
||||
- **Duplex**: read + write (TCP socket).
|
||||
- **Transform**: read → mutate → write (gzip, JSON.parse).
|
||||
|
||||
* **백엔드 프레임워크에서의 스트림 활용**
|
||||
* **NestJS (RxJS 스트림):** NestJS는 요청이 컨트롤러에 도달하기 전후에 실행되는 파이프라인 형태의 인터셉터(Interceptors)와 가드(Guards)를 제공한다 [5]. 이 컴포넌트들은 RxJS 스트림을 활용하여 비동기 작업을 유연하게 처리할 수 있도록 지원한다 [5].
|
||||
* **Express.js (실시간 데이터 스트림):** Express.js는 비동기 프로그래밍을 사용하여 다중 작업 처리에 능하며, 여러 수준의 데이터 스트림을 다뤄야 하는 복잡한 실시간 스트리밍 애플리케이션을 효율적으로 처리할 수 있는 프레임워크로 활용된다 [4, 10].
|
||||
### 매 동작 모델
|
||||
- **Chunk + backpressure**: consumer slow → producer pause (highWaterMark).
|
||||
- **Object mode**: chunk 가 raw bytes 가 아닌 object.
|
||||
- **Pipe**: source.pipe(transform).pipe(sink) chain.
|
||||
|
||||
## ⚖️ Trade-offs & Caveats
|
||||
* **구조적 복잡성 증가 및 인간공학적 저하:** React Server Components와 스트리밍을 결합할 때, 클라이언트 컴포넌트와 서버 컴포넌트가 혼재되거나 컨텍스트가 중첩되는 페이지에서는 개발 복잡성이 크게 증가하여 React의 전체적인 인간공학적 측면(ergonomics)을 저하시킬 수 있다 [11].
|
||||
* **페이로드 노출 및 보안(RCE) 위험:** 스트리밍되는 RSC 페이로드 구조는 브라우저의 네트워크 탭에서 누구나 볼 수 있으므로, 클라이언트 렌더링에 꼭 필요한 데이터만 전달하지 않으면 민감한 데이터가 노출될 수 있다 [12]. 또한, 서버 컴포넌트에서 클라이언트가 서버의 함수를 호출할 때 엄격한 유효성 검증을 거치지 않으면, 인증되지 않은 원격 코드 실행(CVE-2025-55182 등)과 같은 심각한 보안 취약점이 발생할 위험이 있다 [12-14].
|
||||
* **아키텍처 강제성 부재로 인한 유지보수 제약 (Express.js):** 복잡한 데이터 스트림 처리에 유용한 Express.js는 자체적인 아키텍처 규칙을 강제하지 않으므로(Un-opinionated), 실시간 스트리밍 시스템과 같이 규모가 커지는 프로젝트에서는 개발자마다 비즈니스 로직과 라우팅을 배치하는 기준이 달라져 리팩토링과 유지보수가 혼란스러워질 수 있다 [15, 16].
|
||||
### 매 응용
|
||||
1. LLM token streaming (Claude · GPT-5 의 SSE response).
|
||||
2. Large file upload/download (Multipart, S3 multipart).
|
||||
3. Real-time analytics (Kafka consumer).
|
||||
|
||||
---
|
||||
*Last updated: 2026-05-03*
|
||||
## 💻 패턴
|
||||
|
||||
### Web Streams API (cross-platform)
|
||||
```typescript
|
||||
const response = await fetch("/api/llm");
|
||||
const reader = response.body!.pipeThrough(new TextDecoderStream()).getReader();
|
||||
while (true) {
|
||||
const { value, done } = await reader.read();
|
||||
if (done) break;
|
||||
process.stdout.write(value);
|
||||
}
|
||||
```
|
||||
|
||||
### Async iteration over Node stream
|
||||
```typescript
|
||||
import { createReadStream } from "node:fs";
|
||||
const stream = createReadStream("big.log", { encoding: "utf-8" });
|
||||
for await (const chunk of stream) {
|
||||
console.log(`got ${chunk.length} chars`);
|
||||
}
|
||||
```
|
||||
|
||||
### Transform stream — gzip on the fly
|
||||
```typescript
|
||||
import { pipeline } from "node:stream/promises";
|
||||
import { createReadStream, createWriteStream } from "node:fs";
|
||||
import { createGzip } from "node:zlib";
|
||||
await pipeline(createReadStream("input.txt"), createGzip(), createWriteStream("output.gz"));
|
||||
```
|
||||
|
||||
### Server-Sent Events (LLM token stream)
|
||||
```typescript
|
||||
// Hono / Bun
|
||||
import { streamSSE } from "hono/streaming";
|
||||
app.get("/chat", c => streamSSE(c, async stream => {
|
||||
for await (const tok of llm.generate(prompt)) {
|
||||
await stream.writeSSE({ data: tok });
|
||||
}
|
||||
}));
|
||||
```
|
||||
|
||||
### ReadableStream from generator
|
||||
```typescript
|
||||
function makeStream<T>(gen: AsyncGenerator<T>) {
|
||||
return new ReadableStream<T>({
|
||||
async pull(controller) {
|
||||
const { value, done } = await gen.next();
|
||||
done ? controller.close() : controller.enqueue(value);
|
||||
}
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
### Backpressure handling
|
||||
```typescript
|
||||
const writable = createWriteStream("out.bin");
|
||||
function writeChunk(buf: Buffer) {
|
||||
if (!writable.write(buf)) {
|
||||
return new Promise<void>(res => writable.once("drain", res));
|
||||
}
|
||||
return Promise.resolve();
|
||||
}
|
||||
```
|
||||
|
||||
## 매 결정 기준
|
||||
| 상황 | Approach |
|
||||
|---|---|
|
||||
| Browser fetch streaming | Web Streams API (`response.body`) |
|
||||
| Node.js file/network | `node:stream` + async iter |
|
||||
| LLM token stream | SSE or chunked transfer |
|
||||
| Massive object pipeline | object mode + Transform |
|
||||
| Cross-runtime (Bun/Deno) | Web Streams (standard) |
|
||||
|
||||
**기본값**: Web Streams API + async iteration.
|
||||
|
||||
## 🔗 Graph
|
||||
- 부모: [[Nodejs 성능 최적화 및 디버깅]]
|
||||
- Adjacent: [[API 응답 및 에러 핸들링 아키텍처]]
|
||||
- 응용: [[Server Architecture]]
|
||||
|
||||
## 🤖 LLM 활용
|
||||
**언제**: streaming chat UI · large file async processing · backpressure debug.
|
||||
**언제 X**: small payload (<1MB) — buffering 이 simpler.
|
||||
|
||||
## ❌ 안티패턴
|
||||
- **Concat all chunks before yielding**: stream 의 의미 무효화.
|
||||
- **Ignore backpressure**: producer 가 consumer 추월 → memory blow up.
|
||||
- **No error propagation in pipe**: 한 stage error 가 silent.
|
||||
- **Sync transform on huge object**: event loop block.
|
||||
|
||||
## 🧪 검증 / 중복
|
||||
- Verified (Node.js docs · WHATWG Streams Standard).
|
||||
- 신뢰도 A.
|
||||
|
||||
## 🕓 Changelog
|
||||
| 날짜 | 변경 |
|
||||
|---|---|
|
||||
| 2026-05-08 | Phase 1 |
|
||||
| 2026-05-10 | Manual cleanup — Stream API 패턴 정리 |
|
||||
|
||||
Reference in New Issue
Block a user