103 lines
11 KiB
Markdown
103 lines
11 KiB
Markdown
---
|
|
title: official-doc / Lettuce ClientOptions — autoReconnect, disconnectedBehavior, requestQueueSize
|
|
source_type: official-doc
|
|
url: https://redis.github.io/lettuce/advanced-usage/client-options/
|
|
archive_url:
|
|
related_branches: [feature-redis-runtime-role-isolation-contract]
|
|
related_projects: [ca-skeleton]
|
|
tags: [official-doc, ca-skeleton, redis, runtime, connection-pool]
|
|
created: 2026-07-28
|
|
---
|
|
|
|
# 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:` 에 반영).
|
|
|
|
## 관련
|
|
|
|
- 같은 주제 다른 official-doc: (아직 없음 — Redis Cluster topology refresh 전용 자료는 후속 수집 대상)
|
|
- 이 자료를 인용한 wiki 요약: `[[wiki/concepts/...]]` (생성 시)
|