스냅샷과 델타

스냅샷과 델타 (1.0) (Snapshots and Deltas)

진화하는 값이 어떻게 이동하는지 다루는 페이지예요. 통째로 교체하는 스냅샷과 JSON Patch로 수정하는 델타. 에이전트의 상태, activity의 콘텐츠, 대화 자체 같은 값들이 어떻게 전달되는지 설명합니다.

출처: 문서

본문

생산자가 보고하는 것 중 일부는 텍스트 스트림이 아니라 진화하는 값입니다. 에이전트의 상태, activity의 콘텐츠, 대화 자체가 그렇죠. 이들은 스냅샷(snapshots) — 교체하는 — 과 델타(deltas) — 수정하는 — 으로 이동합니다.

이 패턴을 쓰는 패밀리는 세 가지입니다: 상태(STATE_SNAPSHOT, STATE_DELTA, 그리고 대화용 MESSAGES_SNAPSHOT)와 activity(ACTIVITY_SNAPSHOT, ACTIVITY_DELTA). 이 페이지는 그것들이 공유하는 것을 서술하고, 패밀리 페이지는 각각이 무엇을 교체·수정하는지 서술합니다.

스냅샷 (Snapshots)

스냅샷은 전체 값을 운반합니다. 소비자는 자기 사본을 스냅샷의 내용으로 교체해야 합니다(MUST) — 스냅샷은 병합이 아니에요 — 스냅샷 자신이 자기 패밀리가 정의하는 필드로 거부하지 않는 한 말입니다(activity의 replace: false가 그 유일한 경우예요). 그 앞에 온 델타는 전부 소진됩니다. 스냅샷은 적용되든 거부되든 새 기준선 순간입니다.

생산자는 언제든 스냅샷을 보낼 수 있고(MAY), 소비자의 기준선이 자기와 일치함을 보장할 수 없을 때마다 보내야 합니다(SHOULD) — 오류 후, 델타로 표현할 수 없는 콘텐츠 후, 또는 오래된 스레드를 이어가는 실행의 시작에 말이죠.

델타 (Deltas)

델타는 현재 값을 RFC 6902 JSON Patch로 표현해 수정합니다. 순서대로 원자적으로 적용되는 연산 배열입니다 — 어떤 연산이 실패해도 문서는 원래대로 남습니다.

  • 델타는 소비자의 현재 값에 적용됩니다: 마지막 스냅샷에 그 이후의 모든 델타가 더해진 값이죠. 상태의 경우, 실행이 시작하는 값은 입력의 state이며, 입력이 아무것도 담지 않았다면 빈 객체입니다.
  • 생산자는 소비자에게 기준선을 주지 않은 값에 대해 델타를 보내면 안 됩니다(MUST NOT). 기준선으로 치는 것은 패밀리의 몫이에요 — 상태는 입력에서 하나를 갖고, activity는 첫 스냅샷 후에야 갖습니다.
  • Patch 연산은 의도적으로 열린 객체입니다. 스키마가 그렇게 표시하며, RFC 6902가 정의하지 않는 멤버는 처리 모델이 떼어내면 안 되는 프로토콜 법적 자료입니다.

patch가 적용되지 않을 때 (When a patch does not apply)

구조적 유효성은 patch가 적용된다는 뜻이 아닙니다. 잘 만들어진 연산이 존재하지 않는 경로를 가리킬 수 있고, RFC 6902는 그것을 적용자에게 맡깁니다. 잘못된 연산 — 배열이 아닌 patch, 필수 멤버가 없거나 잘못된 타입의 멤버를 가진 연산 — 은 잘못된 알려진 값이라 여느 것처럼 치명적입니다. op가 RFC 6902가 정의하지 않는 것을 지칭하는 연산은 잘못된 것이 아니라 인식되지 않는 것 — 이 소비자가 출시된 후 판별된 합집합(discriminated union)에 추가된 멤버 — 이며, 처리 모델의 목록 규칙이 적용됩니다. 그 요소는 경고와 함께 patch에서 버려지고 실행은 살아남습니다. 적용에 실패하는 잘 만들어진 patch는 또 다릅니다:

  • 소비자는 부분 적용된 결과를 유지하면 안 됩니다(MUST NOT) — RFC 6902 적용은 원자적입니다.
  • 소비자는 실패를 표면화해야 합니다(MUST) — 무엇이 왜 실패했는지 진단할 수 있을 만큼 식별하는 경고 — 그리고 실행을 실패시키기보다 이전 값을 계속 가질 수 있습니다(MAY).
  • 실패하는 test 연산도 같은 경우입니다. patch가 적용되지 않고, 소비자는 이전 값을 유지합니다.

그 시점부터 소비자의 값은 생산자의 것과 갈라졌을 수 있습니다. 그것을 알게 되거나, 배제할 수 없는 생산자는 스냅샷으로 재동기화해야 하며(SHOULD), 소비자는 그 앞에 무엇을 건너뛰었든 다음 스냅샷을 채택해야 합니다(MUST) — 그것이 회복을 가능하게 하는 것입니다.

메시지 흐름 (Message Flow)

sequenceDiagram
    participant Producer
    participant Consumer

    Producer->>Consumer: STATE_SNAPSHOT {"items": []}
    Producer->>Consumer: STATE_DELTA add /items/0
    Producer->>Consumer: STATE_DELTA replace /items/0/status
    Note over Consumer: a delta fails to apply → warn, keep prior value
    Producer->>Consumer: STATE_SNAPSHOT (resynchronises)

데이터 타입 (Data Types)

patch 형태 — JsonPatch, 그 연산들, JsonPointer — 는 RFC 6902를 참조하여 스키마 레퍼런스로 정의됩니다.

더 알아보기 (Learn more)