donghyeon.kang/llm-wiki

Fork 0

Files

T

DongHyeonka 58515ab0f3 feat: 공식 문서 근거자료, 브랜치 기능 문서 작성

2026-07-29 18:05:17 +09:00

11 KiB

Raw Permalink Blame History

title, source_type, url, archive_url, related_branches, related_projects, tags, created

title

source_type

url

archive_url

related_branches

related_projects

Lettuce ClientOptions — autoReconnect, disconnectedBehavior, requestQueueSize

Layer: raw/ — 외부 자료(공식 문서 / 대기업 기술 블로그)의 원문 발췌·출처 기록. 본 템플릿은 raw/official-docs/ 와 raw/company-tech-blogs/ 두 폴더가 공유. 검증된 요약은 /ingest 후 wiki/concepts/에 source-summary-template 형식으로 별도 작성. 원본은 raw에 영구 보관.

source_type 허용값

official-doc — 공식 레퍼런스 / 표준 / 사양 (Lettuce 프로젝트 공식 GitHub Pages 문서, redis/lettuce 리포의 공식 산출물)

활용 branch (필수, 최소 1개+)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-redis-runtime-role-isolation-contract	Redis 연결 런타임에서 `autoReconnect` / `disconnectedBehavior=REJECT_COMMANDS` / 유한한 `requestQueueSize` 를 명시 설정해 Redis 장애가 애플리케이션 heap 고갈로 번지지 않게 한다는 결정의 근거

출처

원본 URL: https://redis.github.io/lettuce/advanced-usage/client-options/ (요청받은 https://redis.github.io/lettuce/advanced-usage/ 는 404 — Lettuce 공식 사이트 내 Advanced Usage → Client Options 하위 페이지로 대체)
보조 URL (command replay / at-least-once 시맨틱): https://redis.github.io/lettuce/advanced-usage/command-execution-reliability/
아카이브 URL: (미수집 — 필요 시 사용자가 archive.org 스냅샷 지정)
저자 / 조직: Lettuce 프로젝트 (Redis 공식 Java 클라이언트, redis/lettuce GitHub org)
발행일: (페이지에 명시된 발행일 없음 — living reference doc)
마지막 확인일: 2026-07-28

왜 저장했는지

Redis 런타임 role-isolation 브랜치(feature-redis-runtime-role-isolation-contract)에서 "Redis 장애 시 애플리케이션 heap 이 커맨드 큐 적체로 고갈되지 않아야 한다"는 요구를 만족하려면 Lettuce ClientOptions 의 autoReconnect/disconnectedBehavior/requestQueueSize 기본값과 각 옵션의 의미를 정확히 알아야 한다. 이 문서는 그 결정(명시적 설정 필요성)의 1차 공식 근거다.

핵심 인용

[Client Options] "Controls auto-reconnect behavior on connections. As soon as a connection gets closed/reset without the intention to close it, the client will try to reconnect, activate the connection and re-issue any queued commands."

[Client Options — Disconnected Behavior] "DEFAULT: Accept commands when auto-reconnect is enabled, reject commands when auto-reconnect is disabled." / "ACCEPT_COMMANDS: Accept commands in disconnected state." / "REJECT_COMMANDS: Reject commands in disconnected state."

[Client Options — Request Queue Size] "Controls the per-connection request queue size. The command invocation will lead to a RedisException if the queue size is exceeded."

[Client Options — Cluster] "Clustered operations use multiple connections. The resulting overall-queue limit is requestQueueSize * ((number of cluster nodes * 2) + 1)."

[Command Execution Reliability] "commands may be duplicated but not lost" (at-least-once execution, via retry mechanisms during reconnection; commands are buffered in memory during failures)

Claims Extracted

이 자료가 직접 말하는 것만 claim 으로 분리한다. 내 프로젝트에 적용한 결론은 여기 쓰지 않는다.

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
LETTUCE-CO-C1	`autoReconnect` 기본값은 true 이며, 의도치 않게 연결이 끊기면 클라이언트가 재연결·활성화 후 큐에 쌓인 command 를 재발행(re-issue)한다	"Controls auto-reconnect behavior on connections. As soon as a connection gets closed/reset without the intention to close it, the client will try to reconnect, activate the connection and re-issue any queued commands."	official-vendor-doc	Lettuce 클라이언트 기본 동작 (버전 명시 없음, 현재 reference 문서 기준)	이 재발행이 모든 command 타입에 안전(idempotent)함을 증명하지 않음 — 중복 실행 가능성은 별도 검토 필요
LETTUCE-CO-C2	`disconnectedBehavior` 는 DEFAULT(autoReconnect 여부에 종속) / ACCEPT_COMMANDS(항상 버퍼링) / REJECT_COMMANDS(항상 즉시 거부) 3가지 값을 제공한다	"DEFAULT: Accept commands when auto-reconnect is enabled, reject commands when auto-reconnect is disabled." / "REJECT_COMMANDS: Reject commands in disconnected state."	official-vendor-doc	Lettuce `ClientOptions.disconnectedBehavior` 설정 전반	REJECT_COMMANDS 를 쓰는 것이 이 프로젝트에 "올바른 선택"이라고 증명하지 않음 — 이는 branch 의 trade-off 결정
LETTUCE-CO-C3	`requestQueueSize` 기본값은 `Integer.MAX_VALUE`(2147483647)이며, per-connection 단위이고 초과 시 `RedisException` 을 던진다	"Controls the per-connection request queue size. The command invocation will lead to a RedisException if the queue size is exceeded."	official-vendor-doc	Lettuce `ClientOptions.requestQueueSize` 기본값(사실상 무제한에 가까운 상한)	기본값이 실제로 OOM 을 유발한다는 실측치는 아님 — "사실상 무제한"이라는 설계상 위험만 보여줌, heap 고갈 실증은 이 문서 범위 밖
LETTUCE-CO-C4	Redis Cluster 모드에서는 여러 커넥션을 사용하므로 전체 큐 상한이 `requestQueueSize * ((number of cluster nodes * 2) + 1)` 공식으로 배수 증가한다	"Clustered operations use multiple connections. The resulting overall-queue limit is requestQueueSize * ((number of cluster nodes * 2) + 1)."	official-vendor-doc	Lettuce cluster client 의 큐 상한 계산	이 프로젝트가 실제 cluster 배포인지, 이 공식이 모든 Lettuce 버전에서 동일한지는 이 문서만으로 확정 불가
LETTUCE-CO-C5	auto-reconnect 활성 상태의 기본 동작(at-least-once)은 재연결 시 buffered command 를 재시도하므로 "손실은 없지만 중복될 수 있다"	"commands may be duplicated but not lost"	official-vendor-doc	auto-reconnect 활성 상태의 command 재전송(replay) 시맨틱	Lettuce 6.6+ 의 "replay filter" 기능 존재 여부·설정 방법은 fetch 결과에서 verbatim 인용으로 확인되지 않아 이 문서에서 claim 화하지 않음(§Usage Boundaries 참조)

Strength 허용값

official-standard — RFC, 표준 사양, 언어/프로토콜 표준
official-vendor-doc — Spring, Keycloak, AWS, Google 등 공식 벤더 문서
official-reference — 공식 reference/API 문서
company-case-study — 대기업/실무 기술 블로그의 특정 사례
engineering-blog — 개인/팀 블로그의 엔지니어링 해설
tutorial — 튜토리얼/가이드. 일반화 금지
needs-confirmation — 원문만으로는 적용 판단 불가

Usage Boundaries

이 자료가 직접 증명하는 것:
- LETTUCE-CO-C1: autoReconnect 기본값(true)과 재연결 시 큐에 쌓인 command 재발행 동작
- LETTUCE-CO-C2: disconnectedBehavior 3개 값의 정의 (DEFAULT/ACCEPT_COMMANDS/REJECT_COMMANDS)
- LETTUCE-CO-C3: requestQueueSize 기본값이 Integer.MAX_VALUE 이고 per-connection 단위이며 초과 시 예외를 던진다는 사실
- LETTUCE-CO-C4: cluster 모드에서 전체 큐 상한이 노드 수에 비례해 배수 증가한다는 공식
- LETTUCE-CO-C5: auto-reconnect 활성 상태에서 command 가 손실 없이(다만 중복 가능하게) 재시도된다는 at-least-once 시맨틱
이 자료가 증명하지 않는 것:
- requestQueueSize 기본값(사실상 무제한)이 실제로 이 프로젝트에서 heap 고갈을 일으킨다는 실측 근거 — 이 문서는 설계상 위험(상한이 매우 큼)만 보여줄 뿐, 이 프로젝트의 부하·메모리 프로파일에서의 결과는 별도 검증 필요
- disconnectedBehavior=REJECT_COMMANDS 선택이 이 프로젝트에 "공식 best practice"라는 것 — 공식 문서는 옵션과 기본값만 설명하며 어떤 값을 골라야 하는지 권고하지 않음. 선택 자체는 branch 의 trade-off 결정
- Lettuce 6.6+ "command replay filter" 기능의 존재·설정 방법 — WebFetch 결과에서 이 부분은 verbatim 인용으로 확인되지 않아 claim 화하지 않았음 (fabrication 방지, §메모 참조)
- Cluster topology refresh (periodic/adaptive) 설정 — 요청받은 항목이었으나 advanced-usage/client-options/ 와 advanced-usage/command-execution-reliability/ 두 페이지 어디에도 verbatim 으로 존재하지 않아 이 문서에 포함하지 않음. 필요 시 별도 raw-source 조사 대상 (아래 §메모 참조)
내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- ca-skeleton 의 실제 LettuceClientConfiguration/ClientOptions 빌더 설정에서 autoReconnect(true) + disconnectedBehavior(REJECT_COMMANDS) + 명시적 requestQueueSize 상한이 role(cache/coordination/session) 별로 실제 반영되는지 코드/테스트 검증

메모

나중에 wiki로 옮길 때 참고할 짧은 메모. 검증되지 않은 내 추론은 여기에 두지 말 것.

WebFetch 처리 특성상 결과가 "요약 + 원문 발췌(따옴표)" 혼합 형태로 반환됨. 이 문서의 ## 핵심 인용/## Claims Extracted 표에는 따옴표로 감싸져 있고 self-grep 으로 확인된 문장만 채택했다. "Lettuce 6.6+ replay filter" 서술은 fetch 결과에서 따옴표 없이(모델의 재서술로) 나타나 verbatim 확인 대상에서 제외 — claim 화하지 않음.
Cluster topology refresh (periodic/adaptive refresh) 설정은 별도 페이지(추정: High-Availability and Sharding 섹션 하위)에 있을 가능성이 높음. 이 branch 에서 topology refresh 근거가 필요하면 별도 dispatch(URL: 해당 페이지 확정 후) 필요.
요청받은 원 URL https://redis.github.io/lettuce/advanced-usage/ 는 404. 실제 유효 페이지는 https://redis.github.io/lettuce/advanced-usage/client-options/ (frontmatter url: 에 반영).

11 KiB Raw Permalink Blame History