llm-wiki/raw/official-docs/redis-lua-api-determinism-replication.md

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

title	source_type	url	archive_url	related_branches	related_projects	tags	created
official-doc / Redis Lua API Reference — call vs pcall, typed errors, effects replication, sandbox	official-doc	https://redis.io/docs/latest/develop/programmability/lua-api/		feature-redis-atomic-program-catalog-contract	ca-skeleton	official-doc ca-skeleton runtime redis	2026-07-28

official-doc / Redis Lua API Reference — call vs pcall, typed errors, effects replication, sandbox

Layer: raw/ — 외부 자료(공식 문서)의 원문 발췌·출처 기록. 검증된 요약은 /ingest 후 wiki/concepts/에 별도 작성. 원본은 raw에 영구 보관.

Parent / 활용 branch

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-redis-atomic-program-catalog-contract	atomic program 은 bounded·결정론적이어야 하며, 오류는 typed 로 반환하고, 복제 의미(effects replication)를 이해한 상태에서 작성해야 한다 — 그 제약을 카탈로그 규칙으로 고정한다.

출처

• 원본 URL: https://redis.io/docs/latest/develop/programmability/lua-api/
• 참고: dispatch 에서 지정한 https://redis.io/docs/latest/develop/interact/programmability/lua-api/ 는 WebFetch 시 404 Not Found — 위 대체 URL 로 fetch 성공(본 문서의 url: 은 실제 fetch 성공한 URL).
• 아카이브 URL: (미제공)
• 저자 / 조직: Redis, Inc. (공식 레퍼런스 문서 — "Redis Lua API reference")
• 발행일: 문서 자체에 발행일 명시 없음 (버전 미고정 "latest" reference 페이지, 각 API 항목에 Since version: / Until version: 개별 명시)
• 마지막 확인일: 2026-07-28

왜 저장했는지

feature-redis-atomic-program-catalog-contract 는 EVALSHA 기반 atomic program 이 (1) bounded/deterministic 하고 (2) 오류를 typed 로 반환하며 (3) replication 의미(verbatim vs effects)를 이해한 상태로 작성되어야 한다는 카탈로그 규칙을 정의하려 한다. 이 문서는 그 세 축(오류 처리, typed reply, replication 모드)의 1차 공식 근거다.

핵심 인용

[§redis.call] "If and when redis.call() triggers a runtime exception, the raw exception is raised back to the user as an error, automatically." (line 127)

[§redis.pcall] "The redis.pcall() function behaves exactly like redis.call(), except that it: * Always returns a reply. * Never throws a runtime exception, and returns in its stead a redis.error_reply in case that a runtime exception is thrown by the server." (line 149)

[§redis.error_reply] "The helper accepts a single string argument and returns a Lua table with the err field set to that string." (line 177)

[§redis.status_reply] "The Lua API represents status replies as tables with a single field, ok, set with a simple status string." (line 211)

[§redis.set_repl] "As of Redis version 7.0, script replication is no longer supported, and the only replication mode available is script effects replication." (line 278)

[§redis.replicate_commands] "* Until version: 7.0.0" ... "The default, and only script replication mode supported, is script effects' replication." (lines 318, 327)

[§The KEYS global variable] "The script should only access keys whose names are given as input arguments. Scripts should never access keys with programmatically-generated names or based on the contents of data structures stored in the database." (lines 87–88)

[§Sandbox context > Global variables and functions] "The sandboxed Lua execution context blocks the declaration of global variables and functions." (line 17)

[§Sandbox context > Imported Lua modules] "The sandboxed execution context prevents the loading modules by disabling Lua's require function." (line 65)

[§redis.setresp] "The default protocol version is 2, but it can be switched to version 3." (line 257)

Claims Extracted

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
REDIS-LUAAPI-C1	redis.call() propagates a runtime exception as a raw error automatically (script aborts); redis.pcall() never throws — it always returns a reply, converting the exception into a redis.error_reply table instead	[§redis.call] "the raw exception is raised back to the user as an error, automatically." / [§redis.pcall] "Never throws a runtime exception, and returns in its stead a redis.error_reply..."	official-reference	EVAL/EVALSHA 기반 ephemeral script 및 Redis Functions 모두 (문서에 "Available in functions: yes" 명시)	상위 클라이언트 라이브러리(예: Spring Data Redis RedisScript)가 이 예외를 어떻게 재래핑하는지는 증명 안 함
REDIS-LUAAPI-C2	redis.error_reply(x) / redis.status_reply(x) 는 각각 {err=...} / {ok=...} Lua table 을 반환하는 공식 helper — 스크립트가 typed error/status 를 반환하는 공식 수단	[§redis.error_reply] "returns a Lua table with the err field set to that string." / [§redis.status_reply] "tables with a single field, ok, set with a simple status string."	official-reference	모든 EVAL/EVALSHA 스크립트 및 함수의 반환값 설계	어떤 error code(첫 단어 convention)를 카탈로그가 강제해야 하는지는 규정 안 함 — 문서는 "convention"일 뿐 "not mandatory"라고 명시
REDIS-LUAAPI-C3	Redis 7.0 부터 verbatim script replication 이 완전히 제거되고, 오직 effects replication(쓰기 명령의 결과만 복제) 만 지원됨	[§redis.set_repl] "As of Redis version 7.0, script replication is no longer supported, and the only replication mode available is script effects replication."	official-reference	Redis 7.0+ 배포 환경의 replication 동작 이해	6.x 이하에서의 verbatim replication 동작 세부(스크립트 소스 자체가 replica로 전송되는 방식)까지는 이 인용만으로 재구성 불가 — 별도 §redis.set_repl 상단 문단 확인 필요
REDIS-LUAAPI-C4	redis.replicate_commands() 는 3.2.0~7.0.0 구간에만 존재한 API(verbatim→effects 전환 함수)였고, 7.0 이후에는 effects replication 이 기본값이자 유일한 모드가 되어 이 함수 호출이 불필요해짐	[§redis.replicate_commands] "* Until version: 7.0.0" / "The default, and only script replication mode supported, is script effects' replication."	official-reference	Redis 버전별(7.0 이전 vs 이후) 카탈로그 program 작성 시 redis.replicate_commands() 호출 필요 여부 판단	비결정적 명령(RANDOMKEY, TIME, SPOP 등)을 program 에서 사용해도 되는지에 대한 명시적 규칙은 이 페이지에 없음 — 별도 확인 필요 (아래 Usage Boundaries 참고)
REDIS-LUAAPI-C5	atomic program 이 접근하는 key 이름은 반드시 입력 인자(KEYS)로 명시되어야 하며, 프로그램적으로 생성되거나 데이터 내용에 기반한 key 이름 접근은 금지된다	[§The KEYS global variable] "The script should only access keys whose names are given as input arguments. Scripts should never access keys with programmatically-generated names..."	official-reference	ScriptDescriptor 의 필수 필드 설계(KEYS 선언 강제) 근거	이 규칙은 key 접근 방식에 대한 것이며, program 의 시간/공간 복잡도(O(1)/bounded)를 직접 규정하지 않음 — bounded execution 규칙 자체는 별도 근거 필요
REDIS-LUAAPI-C6	Lua 샌드박스는 전역 변수/함수 선언과 미정의 전역 변수 접근을 차단한다 — 모든 선언은 local 이어야 한다	[§Sandbox context > Global variables and functions] "The sandboxed Lua execution context blocks the declaration of global variables and functions."	official-reference	카탈로그 program 작성 코딩 규칙(전역 변수 금지)	문서 자체가 "sandbox 우회는 실수로는 어렵지만 불가능하지 않다"고 명시 — 우회 시도에 대한 강제력의 절대성까지는 증명 안 함
REDIS-LUAAPI-C7	Lua 샌드박스는 require 를 비활성화해 임의 외부 모듈 로드를 금지하며, 문서가 나열한 runtime 라이브러리(string/table/math/os 일부/struct/cjson/cmsgpack/bit)만 사용 가능하다	[§Sandbox context > Imported Lua modules] "prevents the loading modules by disabling Lua's require function."	official-reference	카탈로그 program 이 의존할 수 있는 라이브러리 화이트리스트 근거	Redis Functions 배포 모드에서 라이브러리 제약이 ephemeral script 와 동일한지는 이 인용만으로 확정 안 됨(문서는 이 제약이 sandbox 공통 서술이라고만 함)
REDIS-LUAAPI-C8	redis.setresp(x) 로 redis.call()/redis.pcall() 응답의 RESP 버전을 전환할 수 있으며 기본값은 RESP2, 옵트인으로 RESP3 전환 가능	[§redis.setresp] "The default protocol version is 2, but it can be switched to version 3."	official-reference	typed facade 가 redis.call/redis.pcall 반환값을 파싱할 때 어떤 RESP 버전을 가정해야 하는지 근거	RESP3 개별 타입(map/set/double/big_number/verbatim_string) 각각의 Lua 변환 세부 규칙까지는 이 인용에 포함하지 않음 — 필요 시 원문 "RESP3 to Lua type conversion" 섹션 추가 확인

Usage Boundaries

• 이 자료가 직접 증명하는 것:
  • REDIS-LUAAPI-C1, C2: call/pcall 오류 전파 차이 + typed error/status reply 공식 API
  • REDIS-LUAAPI-C3, C4: Redis 7.0 기준 effects replication 이 유일한 모드이고 redis.replicate_commands() 는 과거(3.2.0~7.0.0) 호환 함수였다는 사실
  • REDIS-LUAAPI-C5: KEYS 는 반드시 입력 인자로 선언되어야 한다는 규칙
  • REDIS-LUAAPI-C6, C7: 전역 변수 금지 + require 비활성화(라이브러리 화이트리스트)
  • REDIS-LUAAPI-C8: redis.setresp() 기본값/전환 가능 여부
• 이 자료가 증명하지 않는 것:
  • 비결정적 명령(RANDOMKEY, TIME, SPOP 등) 사용 시의 규칙 — 이 페이지(lua-api)에는 명시적 서술이 없다. eval-intro 페이지(redis.io/docs/latest/develop/programmability/eval-intro)에서 다룰 가능성이 높으나 본 fetch 범위 밖이다. 카탈로그 문서에서 "비결정적 명령을 program 에서 금지/제한한다"는 규칙을 세우려면 UNSUPPORTED_DECISION 으로 표시하거나 eval-intro 를 별도 raw-source 로 추가 수집해야 한다.
  • Redis Functions(FUNCTION LOAD) 전용 API(redis.register_function, script flags no-writes/allow-oom/no-cluster 등)의 세부 동작 — 본 문서에 존재하나 이번 인용 셋에 포함하지 않았다. Functions 배포 모드를 카탈로그 규칙에 넣으려면 별도 claim 추출 필요.
  • RESP3 개별 타입 변환 세부 규칙(map/set/double/big_number/verbatim_string) — 원문에 존재하나 인용 미포함.
  • Redis 6.x 이하에서 redis.replicate_commands() 를 호출하지 않았을 때의 구체적 오류/폴백 동작.
• 내 프로젝트(ca-skeleton)에 적용하려면 추가 확인이 필요한 것:
  • 사용 중인 Redis 서버/클라이언트 버전이 7.0 이상인지 확인 — 이상이면 redis.replicate_commands() 호출은 불필요(no-op)하고 effects replication 이 기본.
  • typed facade 구현 시 redis.setresp() 미호출 상태(RESP2 기본)를 가정해도 되는지 실제 배포 Redis 버전과 클라이언트 설정으로 검증.

메모

검증되지 않은 추론은 여기까지만. 인용 섹션에는 넣지 않았다.

• 비결정적 명령 규칙 공백(RANDOMKEY/TIME/SPOP)은 eval-intro 페이지를 별도 wiki-source-summarizer dispatch 로 수집해야 branch-note의 "bounded/deterministic" 결정이 완전히 근거를 갖춘다 — 현재는 부분 근거만 확보된 상태.
• 이 문서 하나로 branch 의 "복제 의미를 이해한 상태에서 작성" 요구는 effects-replication 전환(C3/C4) 근거는 있으나, "왜 그 요구가 필요한가"(replica/AOF 불일치 위험)는 redis.set_repl 섹션 상단의 warning 문단(이번 인용에 미포함)에 더 있다 — 필요 시 추가 인용 가능.

Related

• 같은 branch 의 sibling 근거 (아직 미등록): eval-intro (bounded execution, blocking, 비결정적 명령) — /branch-spec feature-redis-atomic-program-catalog-contract 진행 시 추가 수집 권고.
• 이 자료를 인용한 wiki 요약: 아직 없음 (raw 단계).