PgWebhookDedupeStoreOptions — @gj-kit/toss-payments-postgresql

@gj-kit/toss-payments-postgresql에서 공개하는 interface입니다. package version 0.5.1의 release declaration을 그대로 표시합니다.

검증된 import 예제

import { PgWebhookDedupeStoreOptions } from '@gj-kit/toss-payments-postgresql';

시그니처, 매개변수, 반환 타입

/**
 * WebhookDedupeStore PostgreSQL 구현 (설계 §3.5).
 *
 * 코어 계약의 핵심 불변식(verifier.ts TSDoc):
 * - **claim은 원자적이어야 한다** — 조회 후 생성하는 2단계 구현은 TOCTOU 레이스라
 *   금지. 그래서 INSERT ... ON CONFLICT DO UPDATE + CTE **단일 문**으로 전이한다.
 * - processing 레코드는 lease 만료 후 재점유 가능해야 한다(crash-recovery).
 * - completed에는 토스의 최장 재전송 기간보다 긴 TTL(권장 5일)을 적용한다 —
 *   TTL 삭제는 cleanup()(팩토리) 소관이며 이 스토어는 지우지 않는다.
 * - `complete`는 비즈니스 핸들러의 내구적 처리 완료 후에만, `release`는 처리 실패 시
 *   재전송 재점유를 위해 호출된다 — release는 completed 행을 절대 지우지 않는다.
 * - ⚠ 알려진 계약 한계: 코어 `release(dedupeKey)`에는 소유 토큰(fencing token)이
 *   없다 — lease 만료 후 다른 워커가 재점유한 뒤에 도착한 원래 워커의 늦은 release가
 *   새 claim의 processing 행을 지울 수 있는 창이 이론상 존재한다(이후 재전송이
 *   'claimed'를 받아 동시 처리 창이 열림). 스토어 구현만으로는 어느 워커의 release인지
 *   판별할 수 없어 이 계층에서 완전 차단이 불가능하다(코어 계약 보완 후보). 실전
 *   완화책은 `dedupe.leaseSeconds`(기본 60)를 핸들러 최대 처리 시간보다 길게 잡는 것.
 */
interface PgWebhookDedupeStoreOptions extends PgStoreOptions {
    /** processing 행의 crash-recovery lease(초). 기본 60. */
    readonly leaseSeconds?: number;
}

이 선언은 매개변수, optionality, 제네릭, 반환값, 공개 union/type 계약의 정본입니다. 호출 전 필요한 환경·권한·오류 경계는 패키지 Golden path와 이 subpath의 import 조건을 함께 확인하세요.

Release context

• 패키지: @gj-kit/toss-payments-postgresql
• 버전: 0.5.1
• 공개 entry: .
• 소스: GitHub

구현 주석

WebhookDedupeStore PostgreSQL 구현 (설계 §3.5).

코어 계약의 핵심 불변식(verifier.ts TSDoc):

• claim은 원자적이어야 한다 — 조회 후 생성하는 2단계 구현은 TOCTOU 레이스라 금지. 그래서 INSERT … ON CONFLICT DO UPDATE + CTE 단일 문으로 전이한다.
• processing 레코드는 lease 만료 후 재점유 가능해야 한다(crash-recovery).
• completed에는 토스의 최장 재전송 기간보다 긴 TTL(권장 5일)을 적용한다 — TTL 삭제는 cleanup()(팩토리) 소관이며 이 스토어는 지우지 않는다.
• complete는 비즈니스 핸들러의 내구적 처리 완료 후에만, release는 처리 실패 시 재전송 재점유를 위해 호출된다 — release는 completed 행을 절대 지우지 않는다.
• ⚠ 알려진 계약 한계: 코어 release(dedupeKey)에는 소유 토큰(fencing token)이 없다 — lease 만료 후 다른 워커가 재점유한 뒤에 도착한 원래 워커의 늦은 release가 새 claim의 processing 행을 지울 수 있는 창이 이론상 존재한다(이후 재전송이 ’claimed’를 받아 동시 처리 창이 열림). 스토어 구현만으로는 어느 워커의 release인지 판별할 수 없어 이 계층에서 완전 차단이 불가능하다(코어 계약 보완 후보). 실전 완화책은 dedupe.leaseSeconds(기본 60)를 핸들러 최대 처리 시간보다 길게 잡는 것.