[EXT-034][실무] 바이트 흐름을 글자 흐름으로 바꾸기 > IT 기술 공유

• 목록

[이번 수업]

큰 파일이나 네트워크 응답을 메모리에 한꺼번에 올리지 않고 조각씩 읽는 방식을 스트리밍이라고 합니다. 이번에는 TextDecoderStream을 연결해 UTF-8 바이트 흐름을 문자열 흐름으로 바꿉니다. 문자 중간에서 바이트가 갈려도 변환기가 경계를 이어 줍니다.

[선수지식]

EXT-033의 청크, TextDecoder의 stream 옵션과 UTF-8 문자 경계를 이해해야 합니다. JavaScript 객체와 비동기 반복문 for await...of를 읽고 Node.js 파일을 실행할 수 있으면 됩니다.

[학습목표]

1. ReadableStream과 변환 스트림의 역할을 구분한다.
2. pipeThrough()로 TextDecoderStream을 연결한다.
3. 역압과 오류 전파가 스트림 처리에 필요한 이유를 설명한다.

[핵심개념]

ReadableStream은 읽을 데이터가 차례로 나오는 통로입니다. TransformStream은 입력 청크를 다른 형태로 바꾸는 통로이며 쓰기 쪽과 읽기 쪽을 함께 가집니다. TextDecoderStream은 바이트를 받아 디코딩한 문자열 청크를 내보내는 표준 변환 스트림입니다. 기본 인코딩은 UTF-8이고 { fatal: true }를 지정하면 잘못된 바이트에서 TypeError로 실패합니다.

pipeThrough()는 앞의 ReadableStream을 변환기의 쓰기 쪽에 연결하고 읽기 쪽을 돌려줍니다. 연결된 파이프 체인은 오류를 전달하고 역압(backpressure)을 존중합니다. 역압은 소비자가 느릴 때 생산자에게 속도를 줄이라는 신호입니다. 다만 사용자 정의 원본도 pull 요청과 desiredSize를 따르는 등 신호를 지켜야 실제 메모리 증가를 막을 수 있습니다.

[따라하기]

아래 내용을 decoder-stream.mjs로 저장합니다. ‘한’의 첫 바이트 뒤에서 청크를 나눠 문자 경계를 일부러 깨뜨립니다.

```js
const bytes = new TextEncoder().encode('A한B');

const source = new ReadableStream({
  start(controller) {
    controller.enqueue(bytes.slice(0, 2));
    controller.enqueue(bytes.slice(2));
    controller.close();
  },
});

const decoded = source.pipeThrough(
  new TextDecoderStream('utf-8', { fatal: true }),
);

let result = '';
for await (const chunk of decoded) {
  console.log(`chunk=${JSON.stringify(chunk)}`);
  result += chunk;
}
console.log(`result=${result}`);
```

터미널에서 실행합니다.

```text
node decoder-stream.mjs
```

예상 결과는 다음과 같습니다.

```text
chunk="A"
chunk="한B"
result=A한B
```

변환기가 첫 청크 끝의 미완성 바이트를 보관했다가 다음 청크와 합쳤습니다. Node.js 18 이상에서는 예제의 Web Streams 클래스가 전역으로 제공됩니다. Windows PowerShell, macOS 터미널, Linux 셸의 실행 명령은 같고 `node --version`으로 버전을 확인합니다.

[흔한 실수]

원본에는 Uint8Array 같은 바이트 청크를 넣어야 합니다. 이미 문자열인 값을 다시 디코딩하지 마세요. pipeThrough()의 반환값 대신 원래 source를 반복하면 변환 결과를 읽지 못합니다. 스트림이 한 소비자에게 잠긴 뒤 다른 reader를 얻어도 오류가 납니다. start()에서 큰 데이터를 모두 enqueue하면 역압의 이점을 잃으므로 실제 원본은 필요한 만큼만 생산합니다.

[보안 주의]

스트림도 청크 크기, 누적 바이트 수, 처리 시간에 제한을 두고 초과하면 취소해야 합니다. 외부 입력에는 { fatal: true }와 내용 형식 검증을 적용해 손상된 바이트를 정상 데이터로 오해하지 않게 하세요. 오류나 청크 로그에 비밀번호·토큰·개인정보를 넣지 않습니다. 중단 시 파일 핸들이나 네트워크 연결도 정리해야 합니다. 실습은 본인 소유의 로컬 데이터로만 진행합니다.

[직접 해볼 과제]

문자열을 ‘시작