Progressive JSON

Progressive JSON 🎨

0. Overview ✍️

이미지를 위에서 아래로 순차적으로 로딩하는 것이 아니라, 처음에는 흐릿하게 보이다가 점점 선명해지는 방식으로 로딩하는 메커니즘을 점진적 JPEG라고 합니다. 이 아이디어를 JSON 전송 방식에 적용한 것이 Progressive JSON입니다.

const data = {
  header: 'Welcome to my blog',
  post: {
    content: 'This is my article',
    comments: [
      'First comment',
      'Second comment',
      // ...
    ]
  },
  footer: 'Hope you like it'
}

기존 JSON은 마지막 바이트까지 모두 로드되어야 유효한 객체 트리를 얻을 수 있습니다. 전체 데이터를 받아야만 JSON.parse를 호출할 수 있게 되는 것이죠. 만약 JSON의 일부 생성에 시간이 오래 걸린다면, 클라이언트는 서버가 모든 작업을 완료할 때까지 어떤 작업도 시작할 수 없습니다.

이는 마치 모든 내용을 완벽하게 이해해야만 다음 단원으로 넘어가는 학습 방식과 같습니다. 집합과 명제를 박사 수준으로 완벽하게 이해하지 못했다면 함수와 미적분 등 다음 단원으로 넘어가지 못하는 것처럼 말이죠. 이것은 좋은 학습 방식이라고 보기 어렵습니다.

1. Streaming JSON의 한계 ✍️

JSON 파서는 JSON 문자열을 프로그래밍 언어의 데이터 구조로 변환하는 역할을 합니다. 앞서 제시한 문제를 해결하기 위해 Streaming JSON Parser를 구현해볼 수 있습니다. 즉, 불완전한 입력으로부터 객체 트리를 생성하는 Parser입니다.

{
  header: 'Welcome to my blog',
  post: {
    content: 'This is my article',
    comments: [
      'First comment',
      'Second comment'
      // 여기서 스트림이 끊어진 상태

이 시점에서 결과를 요청하면, Streaming Parser는 다음과 같은 객체를 반환할 것입니다:

{
  header: 'Welcome to my blog',
  post: {
    content: 'This is my article',
    comments: [
      'First comment',
      'Second comment'
      // (나머지 댓글들이 누락됨)
    ]
  }
  // (footer 속성이 누락됨)
}

Streaming Parser의 문제점:

• 객체들이 불완전하다는 치명적인 단점
• 최상위 객체는 header / post / footer 세 개의 속성을 가져야 하지만 footer가 누락
• post는 더 많은 comments를 가질 수 있지만 현재 상태로는 확실하지 않음

이는 여전히 하향식(top-down) 로딩 메커니즘을 따릅니다. 이미지의 상단 10%는 선명하지만 전체 그림을 이해하기 어려운 것처럼, top-down 방식의 불완전한 객체는 그 자체로 불안정성을 내포하고 있습니다.

2. Progressive JSON의 핵심 아이디어 ✍️

지금까지 설명한 방식은 깊이 우선(depth-first) 방식의 데이터 전송입니다. 최상위 객체의 속성부터 시작하여 post, comments 순으로 들어가는 방식이죠.

Progressive JSON은 너비 우선(breadth-first) 방식으로 데이터를 전송합니다:

{
  header: "$1",
  post: "$2", 
  footer: "$3"
}

$ 표시는 아직 전송되지 않은 정보를 나타내는 placeholder입니다. 이후 스트림에서 점진적으로 채워질 것입니다:

{
  header: "$1",
  post: "$2",
  footer: "$3"
}
/*$1*/
"Welcome to my blog"
/*$3*/
"Hope you like it"

$1과 $3은 먼저 보냈지만 $2는 아직 대기 중인 상황입니다. 클라이언트가 트리를 재구성하면:

{
  header: "Welcome to my blog",
  post: new Promise(/* ... 아직 이행되지 않음 ... */),
  footer: "Hope you like it"
}

아직 로드되지 않은 부분들은 Promise로 표현됩니다. 서버가 계속 스트리밍하면:

{
  header: "$1",
  post: "$2",
  footer: "$3"
}
/*$1*/
"Welcome to my blog"
/*$3*/
"Hope you like it"
/*$2*/
{
  content: "$4",
  comments: "$5"
}
/*$4*/
"This is my article"
/*$5*/
["$6", "$7", "$8"]
/*$6*/
"This is the first comment"
/*$7*/
"This is the second comment"
/*$8*/
"This is the third comment"

최종적으로 클라이언트에서는 완전한 트리가 조립됩니다:

{
  header: "Welcome to my blog",
  post: {
    content: "This is my article",
    comments: [
      "This is the first comment",
      "This is the second comment", 
      "This is the third comment"
    ]
  },
  footer: "Hope you like it"
}

데이터를 너비 우선 방식으로 청크 단위로 전송함으로써, 클라이언트에서는 이를 점진적으로 처리할 수 있게 되었습니다.

3. Inlining: 선택적 지연 전송 ✍️

인라이닝은 느리게 생성되는 데이터만 지연 로딩하고 나머지는 즉시 포함시켜 전송하는 선택적 지연 전송 기법입니다.

앞선 예제에서는 스트리밍을 과도하게 사용했습니다. 일부 콘텐츠 생성이 실제로 느리지 않다면, 각기 다른 행으로 나눠 보내는 것에는 이점이 없습니다.

post 본문과 댓글을 불러오는 작업만 특히 느린 상황이라고 가정해봅시다:

1단계: 가장 바깥 요소를 먼저 전송

{
  header: "Welcome to my blog",
  post: "$1",
  footer: "Hope you like it"
}

클라이언트 해석:

{
  header: "Welcome to my blog",
  post: new Promise(/* ... 아직 이행되지 않음 ... */),
  footer: "Hope you like it"
}

2단계: comments를 제외한 post 데이터 전송

{
  header: "Welcome to my blog",
  post: "$1",
  footer: "Hope you like it"
}
/*$1*/
{
  content: "This is my article",
  comments: "$2"
}

클라이언트 해석:

{
  header: "Welcome to my blog",
  post: {
    content: "This is my article",
    comments: new Promise(/* ... 아직 이행되지 않음 ... */),
  },
  footer: "Hope you like it"
}

3단계: 댓글을 한 번에 묶어서 전송

/*$2*/
[
  "This is the first comment",
  "This is the second comment", 
  "This is the third comment"
]

인라이닝의 핵심은 속도와 필요에 따른 균형 있는 데이터 분해입니다. 느린 부분만 별도로 지연시키고, 빠르게 준비되는 부분은 즉시 포함시켜 전송함으로써 전체 사용자 경험을 매끄럽게 만드는 전략입니다.

4. Outlining: 중복 제거와 순환 참조 지원 ✍️

아웃라이닝은 중복되거나 참조 가능한 모든 데이터를 토큰으로 대체한 후, 각 데이터를 별도의 스트림으로 분리하여 순차적으로 전송함으로써 중복 제거와 순환 참조 지원을 가능하게 하는 '전면' 지연 전송 기법입니다.

다음과 같은 객체 트리가 있다고 가정해봅시다:

const userInfo = { name: 'Dan' };

[
  { type: 'header', user: userInfo },
  { type: 'sidebar', user: userInfo },
  { type: 'footer', user: userInfo }
]

일반 JSON으로 직렬화하면 { name: 'Dan' }이 반복됩니다:

[
  { type: 'header', user: { name: 'Dan' } },
  { type: 'sidebar', user: { name: 'Dan' } },
  { type: 'footer', user: { name: 'Dan' } }
]

Progressive JSON에서는 아웃라인으로 분리할 수 있습니다:

[
  { type: 'header', user: "$1" },
  { type: 'sidebar', user: "$1" },
  { type: 'footer', user: "$1" }
]
/* $1 */
{ name: "Dan" }

아웃라이닝의 장점:

• 중복 제거: 같은 데이터를 여러 번 전송하지 않음
• 순환 참조 지원: 일반 JSON과 달리 순환 객체도 직렬화 가능
• 메모리 효율성: 동일한 객체를 여러 곳에서 참조할 때 메모리 절약

인라이닝과 아웃라이닝을 혼합하여 더 균형 잡힌 전략을 취할 수도 있습니다. 기본적으로 객체를 인라인으로 직렬화하되, 같은 객체가 두 번 이상 등장하면 별도로 분리해서 중복을 제거하는 방식입니다.

5. Streaming Data vs Streaming UI ✍️

지금까지의 설명은 사실 리액트 서버 컴포넌트(React Server Components)가 동작하는 방식과 동일합니다.

리액트 서버 컴포넌트로 다음과 같은 페이지를 만든다고 해봅시다:

function Page() {
  return (
    <html>
      <body>
        <header>Welcome to my blog</header>
        <Post />
        <footer>Hope you like it</footer>
      </body>
    </html>
  );
}

async function Post() {
  const post = await loadPost();
  return (
    <article>
      <p>{post.text}</p>
      <Comments />
    </article>
  );
}

async function Comments() {
  const comments = await loadComments();
  return <ul>{comments.map(c => <li key={c.id}>{c.text}</li>)}</ul>;
}

리액트는 Page의 결과를 Progressive JSON 스트림으로 클라이언트에 제공합니다. 클라이언트에서는 해당 스트림이 점진적으로 리액트 트리로 복원됩니다.

로딩 단계별 UI 상태:

1단계: 초기 상태

<html>
  <body>
    <header>Welcome to my blog</header>
    {new Promise(/* ... 아직 이행되지 않음 */)}
    <footer>Hope you like it</footer>
  </body>
</html>

2단계: loadPost() 완료 후

<html>
  <body>
    <header>Welcome to my blog</header>
    <article>
      <p>This is my post</p>
      {new Promise(/* ... 아직 이행되지 않음 */)}
    </article>
    <footer>Hope you like it</footer>
  </body>
</html>

3단계: loadComments() 완료 후

<html>
  <body>
    <header>Welcome to my blog</header>
    <article>
      <p>This is my post</p>
      <ul>
        <li key="1">This is the first comment</li>
        <li key="2">This is the second comment</li>
        <li key="3">This is the third comment</li>
      </ul>
    </article>
    <footer>Hope you like it</footer>
  </body>
</html>

Suspense를 통한 UI 제어

데이터가 점진적으로 들어오더라도, 페이지가 임의로 점프하듯 렌더링되길 원하지는 않을 것입니다. 포스트 본문 없이 헤더와 푸터만 먼저 보이는 것은 좋지 않겠죠.

리액트는 <Suspense>를 통해 이 문제를 해결합니다:

import { Suspense } from 'react';

function Page() {
  return (
    <html>
      <body>
        <header>Welcome to my blog</header>
        <Post />
        <footer>Hope you like it</footer>
      </body>
    </html>
  );
}

async function Post() {
  const post = await loadPost();
  return (
    <article>
      <p>{post.text}</p>
      <Suspense fallback={<CommentsGlimmer />}>
        <Comments />
      </Suspense>
    </article>
  );
}

async function Comments() {
  const comments = await loadComments();
  return <ul>{comments.map(c => <li key={c.id}>{c.text}</li>)}</ul>;
}

사용자는 이제 두 단계에 걸친 로딩 시퀀스를 경험하게 됩니다:

1. 1단계: 포스트 본문 / 헤더 / 푸터 / 댓글의 placeholder가 함께 나타남
2. 2단계: 댓글이 자연스럽게 들어옴

리액트 트리 안의 Promise가 throw라면, Suspense는 catch와 같은 역할을 합니다. 데이터는 서버가 준비되는 대로 가능한 한 빨리 도착하지만, 리액트는 이러한 상황을 우아하게 보여주는 흐름을 관리해주고, 개발자가 시각적인 공개를 제어할 수 있도록 합니다.

6. Conclusion ✍️

Progressive JSON은 단순히 기술적 최적화를 넘어서, 사용자가 기다리는 시간을 의미 있게 만드는 철학을 담고 있습니다. 모든 데이터를 기다리는 대신, 준비된 것부터 차근차근 보여주며 전체적인 경험을 개선하는 것이 바로 Progressive JSON의 핵심 가치입니다.

reference
: https://overreacted.io/progressive-json/#streaming-data-vs-streaming-ui
: https://hanameee.github.io/posts/progressive_json?utm_source=substack&utm_medium=email
: https://www.liquidweb.com/blog/what-is-a-progressive-jpeg/