본문으로 건너뛰기

인터페이스: UpsertableStreamDurability<TOffset>

정의 위치: packages/ai/src/stream-durability.ts:83

StreamDurability의 이미 저장된 범위를 멱등적으로 다시 영속화할 수 있는 형태입니다.

충돌 후 재개하는 실행 드라이버는 소스 위치에서 동일한 오프셋을 다시 계산하므로, 겹치는 범위를 재생해도 중복이 생성되지 않고 아무 작업도 수행하지 않아야 합니다. 이 기능은 append의 선택적 매개변수가 아니라 의도적으로 별도의 선택적 메서드로 제공됩니다.

  • 실제로 해당 기능을 지원하는 어댑터만 이 타입을 반환하므로, 해당 능력을 요구하는 소비자가 UpsertableStreamDurability 를 요청하고 불일치가 발생하면 실행 로그에 묻혀 있는 런타임 오류가 아닌 컴파일 오류로 처리됩니다.
  • 각 청크와 오프셋을 구조적으로 짝지으면 길이 불일치와 짝이 없는 청크는 표현할 수 없게 됩니다. 희소한 공백은 여전히 표현 가능하므로 구현체는 명시적으로 이를 거부해야 합니다.

구현체는 저장된 상태를 변경하기 전에 전체 배치에 대해 유효성을 검사해야 합니다(거부된 호출이 부분적으로 적용되지 않도록), 자신이 발행하지 않은 오프셋을 거부해야 합니다(모든 수용된 오프셋은 정의에 따라 재개 가능), 한 배치 내에서 반복되는 오프셋을 거부해야 하며, 엔트리스 배열의 공백을 거부해야 합니다.

확장​

타입 매개변수​

TOffset​

TOffset extends string = string

속성​

append​

append: (chunks) => Promise<TOffset[]>;

정의 위치: packages/ai/src/stream-durability.ts:17

전달하기 전에 배치를 영속화하고, 각 청크에 대해 정확히 하나의 재개 가능한 오프셋을 같은 순서로 반환합니다.

매개변수​

chunks​

AGUIEvent[]

반환값​

Promise&lt;TOffset[]>

상속 원본​

StreamDurability.append

close​

close: () => Promise<void>;

정의 위치: packages/ai/src/stream-durability.ts:27

생산자 로그를 종료하고 실시간 리더의 차단을 해제합니다. 코어는 완료, 취소, 실패를 포함한 모든 생산자 종료에 대해 이를 기다립니다.

반환값​

Promise&lt;void>

상속 원본​

StreamDurability.close

read​

read: (offset, signal?) => AsyncIterable<{
  chunk: AGUIEvent;
  offset: TOffset;
}>;

정의 위치: packages/ai/src/stream-durability.ts:19

제공된 어댑터 소유 오프셋 이후의 청크를 엄격히 재생합니다.

매개변수​

offset​

TOffset

signal?​

AbortSignal

반환값​

AsyncIterable&lt;{ chunk: AGUIEvent; offset: TOffset; }>

상속 원본​

StreamDurability.read

resumeFrom​

resumeFrom: () => TOffset | null;

정의 위치: packages/ai/src/stream-durability.ts:12

요청에서 캡처한 어댑터 오프셋을 반환하거나, 생산자인 경우 null을 반환합니다.

반환값​

TOffset | null

상속 원본​

StreamDurability.resumeFrom

snapshot​

snapshot: () => Promise<object[]>;

정의 위치: packages/ai/src/stream-durability.ts:57

호출 시점에 이 실행에 저장된 모든 항목을 append 순서로 반환한 후 resolve합니다.

이는 StreamDurability.read의 제한된 대응 기능입니다. read는 로그가 종료되거나 호출자가 중단할 때까지 대기하므로 tail을 읽습니다. 따라서 처음부터 read를 조인하거나 close를 호출하지 않고 생산자가 종료된 로그를 검사하는 데 사용할 수 없습니다. 해당 로그는 영원히 열린 상태로 남고 for await도 끝나지 않습니다. 바로 이 경우를 위해 snapshot이 존재합니다. 실행을 재개하는 생산자는 이전 호스트가 저장한 접두부를 확인해 자신의 출력을 맞춰야 하며, 해당 읽기 작업이 반환되어야 합니다.

구현체는 다음을 반드시 수행해야 합니다:

  • 더 많은 항목을 기다리지 않고, 로그가 아직 열려 있고 계속 append되는 동안에도 저장된 내용을 resolve해야 합니다.
  • 저장된 것이 없는 실행에서는 예외를 던지지 않고 빈 배열로 resolve해야 합니다. read('-1')은 빈 로그에서 실패해도 되지만 snapshot()은 실패하면 안 됩니다. 네트워크 백엔드는 전송, 프로토콜 또는 권한 부여 실패 시 거부할 수 있으며, 이는 빈 실행이 아니라 실패한 호출입니다.
  • 호출자가 보관하거나 변경할 수 있도록 새로운 배열을 반환해야 합니다.

결과는 특정 시점의 뷰이며 잠금을 제공하지 않습니다. 동시 append가 snapshot 직후에 적용될 수 있으므로, 반환된 마지막 오프셋을 영구적인 tail로 간주해서는 안 됩니다.

반환값​

Promise&lt;object[]>

상속 원본​

StreamDurability.snapshot

upsert​

upsert: (entries) => Promise<TOffset[]>;

정의 위치: packages/ai/src/stream-durability.ts:90

호출자가 제공한 오프셋에 배치를 영속화하고, 같은 오프셋에 이미 저장된 항목이 있으면 교체합니다. 제공된 순서대로 오프셋을 반환합니다.

매개변수​

entries​

object[]

반환값​

Promise&lt;TOffset[]>