Failure Handling and Edge Case Design

이 문서는 개별 장애 목록만 나열하지 않고, Redis Stream Coordinator가 실패 상황을 어떤 원칙으로 처리해야 하는지 정의한다. 핵심 원칙은 모든 coordinator workflow가 Redis group metadata key와 client retry만으로 lease 범위 안에서 복구 가능해야 한다는 점이다.

Coordinator는 Redis Stream message processing을 소유하지 않는다. Coordinator가 소유하는 것은 group metadata, member epoch, target assignment, current assignment report, resharding metadata, producer routing metadata이다.

Design Goals

• 짧은 coordinator 장애가 healthy consumer/producer를 즉시 멈추면 안 된다.
• 긴 coordinator 장애는 split ownership이나 무기한 stale producer routing이 생기기 전에 fail closed해야 한다.
• 새 coordinator pod는 old pod의 memory가 아니라 Redis에 기록된 metadata에서 이어서 시작해야 한다.
• Heartbeat response는 잃어버리면 끝나는 일회성 command가 아니라 commit된 최신 assignment state의 반복 가능한 view여야 한다.
• Redis metadata는 최근 write loss가 가능하다. Consumer가 Redis 현재 version보다 높은 metadata version을 보고하면 coordinator는 현재 Redis version으로 metadata sync round를 시작해야 한다.
• 지원하지 않는 Redis command는 fail fast하거나 문서화된 fallback만 사용한다.

Core Model

Redis-Recorded State Machine

모든 coordinator workflow는 Redis-recorded state machine이다. Response는 현재 group metadata key에서만 파생한다.

request or tick
  -> acquire Redis mutex
  -> load group metadata hash
  -> validate input
  -> compute next state
  -> write metadata with storeRevision CAS
  -> return response derived from the written metadata

Coordinator는 client에게 행동을 요구하는 응답을 보내기 전에 해당 행동의 근거가 되는 next state를 먼저 Redis metadata에 기록해야 한다. 기록 전에 coordinator가 죽으면 client retry는 이전 state를 본다. 기록 후 response가 client에게 도달하기 전에 coordinator가 죽으면 Redis가 해당 version을 유지하는 동안 다음 heartbeat 또는 routing refresh가 같은 recorded decision을 다시 반환한다.

Metadata Version Correction

Client에게 반환된 metadata version은 이후 Redis에서 사라질 수 있다. 예를 들어 coordinator가 metadata version 10을 Redis에 쓰고 heartbeat response로 반환했는데, 직후 Redis failover 또는 restore로 version 9 상태로 돌아갈 수 있다. 이 경우 client는 Redis가 현재 저장한 값보다 더 최신 state를 이미 관측한 것이다.

Redis를 source of truth로 유지한다. 더 높은 client version은 Redis state를 복구할 권한이 아니라, client가 stale local view를 들고 있을 수 있다는 신호로 취급한다.

• Coordinator response는 현재 metadataVersion, assignmentEpoch, 관련 member epoch를 포함한다.
• Consumer와 producer는 현재 process lifetime 동안 관측한 최고 version을 기억한다. 더 강한 rollback detection이 필요한 deployment는 module SPI를 통해 작은 local 또는 external persistent version store를 제공해야 한다.
• 모든 heartbeat와 routing refresh는 client가 관측한 최고 version을 포함한다.
• Coordinator가 clientMaxObservedVersion > storedMetadataVersion을 보면 metadata regression으로 보고 metadata correction round를 시작한다. 단, coordinator가 metadata schema나 coordination version을 해석할 수 없으면 fail closed한다.
• Coordinator는 rollback된 Redis version을 단순히 증가시켜 문제를 "복구"하면 안 된다. 유실된 state transition의 내용이 무엇인지 알 수 없기 때문이다.
• request.metadataVersion > group.metadataVersion이면 coordinator는 metadata correction round를 시작하고 SYNC_METADATA를 반환한다.
• SYNC_METADATA는 현재 Redis metadataVersion, assignmentEpoch, 계속 유지 가능한 assigned shard, pending target shard를 포함한다.
• Consumer는 response를 현재 metadata truth로 적용하고, 이미 읽고 있던 shard 중 assignedShards에 남은 shard만 유지한다. 나머지는 신규 read를 중단하고 revoke/drain한다.
• Correction round가 활성화된 동안 coordinator는 현재 Redis metadata version과 다른 heartbeat를 보내는 모든 known consumer에게 SYNC_METADATA를 반환한다.
• Consumer가 현재 metadata version으로 heartbeat했지만 local revoke/drain 또는 다른 member의 revoke 때문에 target shard가 아직 막혀 있으면 coordinator는 REVOKE_PENDING을 반환한다.
• REVOKE_PENDING도 멱등적이다. Consumer는 drain을 계속하고, 나중에 OK를 받을 때까지 신규 shard read를 시작하지 않는다.
• 신규 shard read는 OK에서만 시작한다.
• Coordinator는 consumer report로 Redis metadata를 재구성하지 않고, client version에 맞추려고 Redis version만 증가시키지도 않는다.

Correction sequence:

higher-version heartbeat
  -> member가 Redis metadata version으로 heartbeat할 때까지 SYNC_METADATA 반복
  -> local revoke/drain 또는 다른 member revoke가 target shard를 막는 동안 REVOKE_PENDING
  -> 모든 live member가 동기화되고 충돌 이전 owner가 release, expire, fence된 뒤 OK

Client Lease

Consumer와 producer는 bounded local lease 안에서만 coordinator 없이 동작한다.

Consumer assignment lease는 coordinator의 member lease TTL보다 짧거나 같아야 한다. 그래야 coordinator가 member를 expired 처리하고 shard를 재할당한 뒤에도 기존 consumer가 계속 read하는 split ownership을 막을 수 있다.

Idempotent Retry

모든 coordinator interaction은 retry를 허용해야 한다.

• Heartbeat는 같은 memberId, memberEpoch, assignmentEpoch, owned shard, revoking shard에 대해 idempotent해야 한다.
• Revoke ack는 idempotent해야 한다. 이미 release된 shard에 대한 중복 REVOKED report는 무해하게 무시한다.
• Producer routing refresh는 metadataVersion 기준으로 idempotent해야 한다.
• Admin mutation은 store revision check를 사용하며, 더 최신 metadata를 조용히 덮어쓰면 안 된다.

Generic Failure Checkpoints

모든 workflow는 아래 checkpoint 기준으로 분석한다.

이 checkpoint model이 새로운 엣지케이스를 처리하는 기본 도구이다. 새 기능은 Redis-recorded handoff point, client retry behavior, lease expiry behavior, repair path를 정의해야 한다.

Before-write failure는 반드시 어떤 write boundary 전인지 명시해야 한다. "metadata write 전"은 하나의 상태가 아니다. 해당 workflow의 다음 state transition을 Redis에 기록하기 전에 실패했다는 뜻이다.

Rebalance Drain Failure Scenario

가장 중요한 rebalance flow는 다음이다.

member A owns shard S
member C joins or capacity changes
coordinator computes target owner B/C for shard S
coordinator asks member A to drain shard S through heartbeat response
member A stops new reads, drains in-flight work, then reports REVOKED
coordinator assigns shard S to the new target only after release is accepted

DRAIN instruction은 휘발성 message가 아니다. DRAIN은 Redis에 기록된 metadata에서 파생된 heartbeat response이다.

• target assignment는 shard S가 더 이상 member A 소유가 아니라고 말한다.
• current assignment는 member A를 current 또는 revoking owner로 기록한다.
• member B 또는 C는 release가 수락될 때까지 shard S를 pending으로만 받는다.
• assignment epoch가 이 판단을 식별한다.

Sequence

sequenceDiagram
    autonumber
    participant A as Consumer A
    participant C as Coordinator
    participant R as Redis Metadata
    participant B as Consumer B

    A->>C: heartbeat owned=[S]
    C->>R: write target owner B, A must revoke S
    C-->>A: heartbeat response assigned=[], pending=[], revoke/drain S
    A->>A: stop new reads for S, drain in-flight work
    B->>C: heartbeat
    C-->>B: pending=[S], do not read yet
    A->>C: heartbeat revoking=[S:REVOKED]
    C->>R: write S released from A
    C-->>B: next heartbeat assigned=[S]
    B->>B: start reads for S

DRAIN Response 이후 Coordinator Down

Member A가 DRAIN instruction을 받은 뒤 coordinator가 down되면 다음 정책을 따른다.

세부 failure point:

Write boundary별 Redis-recorded state:

Consumer rule: shard가 local revoking state에 들어가면 heartbeat가 일시적으로 실패한다는 이유만으로 read를 재개하면 안 된다. 이후 coordinator가 다시 assigned로 내려줄 때만 read 가능하다.

Coordinator rule: 새 owner에게 pending shard를 assigned로 바꾸려면 아래 중 하나가 먼저 성립해야 한다.

• previous owner가 in-flight work 없이 REVOKED를 보고했다.
• previous owner가 member lease TTL로 expired 처리됐다.
• previous owner가 rebalance timeout을 초과해 fenced 처리됐다.

Coordinator Rolling Update와 일시적 Coordinator 손실

이 섹션은 replicas=1에서 rolling update 중 순간적으로 다음 형태가 되는 상황을 다룬다.

1 coordinator -> 2 coordinators -> 1 coordinator

또한 일시적 coordinator 손실도 다룬다.

1 coordinator -> 0 reachable coordinators -> 1 coordinator

Coordinator는 Kubernetes readiness, service endpoint propagation, external load balancer를 직접 제어하지 않는다. Coordinator가 소유하는 것은 process-local terminating state와 Redis critical section이다.

구현 guardrail:

• CoordinatorShutdownGate는 Spring context shutdown 시 terminating mode로 진입한다.
• @CriticalSection service method는 local monitor를 잡은 뒤 shutdown gate를 통과하고, 이후 Redis mutex를 획득한다.
• terminating mode 이후 들어오는 heartbeat/admin mutation은 503 COORDINATOR_TERMINATING을 반환하고 다른 coordinator instance로 retry되도록 한다.
• 이미 진입한 짧은 critical section은 Redis write와 mutex release를 완료할 수 있도록 끝까지 실행한다.
• Event-loop tick은 terminating mode 이후 state transition scheduling을 중단한다.

새 coordinator는 old stack frame을 이어받지 않는다. Redis-recorded metadata에서 이어받는다.

Consumer Join, Rejoin, Leave, Expiration

Producer Routing During Failures

Producer는 heartbeat를 보내지 않는다. Producer는 routing metadata refresh만 수행한다.

Producer에는 heartbeat channel이 없기 때문에 shard count 변경은 routing metadata refresh로만 전파된다. 따라서 producer 모듈은 publish가 정상적으로 성공하고 있더라도 routing metadata를 주기적으로 refresh해야 한다. Refresh interval과 routing cache TTL은 coordinator가 shard를 추가한 뒤 producer가 old shard count를 계속 사용할 수 있는 최대 시간을 결정한다.

Refresh 규칙:

• Local routing cache가 만료되기 전에 주기적으로 refresh한다.
• Publish path에서 stale routing 또는 metadata-version mismatch를 감지하면 즉시 refresh한다.
• Refresh된 metadataVersion이 더 최신일 때만 cache를 교체한다.
• Refresh가 실패했지만 cache lease가 아직 유효하면 기존 cache를 유지한다.
• Cache lease가 만료된 뒤 refresh가 실패하면 publish를 실패시킨다.

Redis Metadata Volatility and Corruption

Coordinator metadata는 group별 단일 Redis hash key에 저장한다.

redis-stream:coord:{streamPrefix:consumerGroup}:metadata

권장 hash field:

aggregate      -> GroupMetadata JSON
revision       -> storeRevision
schemaVersion  -> metadata JSON schema version
layoutVersion  -> Redis metadata layout version
updatedAt      -> last successful metadata write time

Redis는 휘발 가능하다고 취급한다. Key는 operator error, eviction policy, failover data loss, restore 실패, 잘못된 logical database, 잘못된 key prefix, accidental delete로 사라질 수 있다. 또한 Redis는 write를 성공으로 응답한 뒤에도 failover, restore, persistence lag로 최근 몇 초의 metadata 변경을 잃을 수 있다.

Index는 rebuild 가능한 보조 데이터일 뿐이다.

redis-stream:coord:groups

목표 동작:

운영 제어:

• Metadata key에는 TTL을 설정하지 않는다.
• Redis snapshot/AOF 또는 managed backup을 활성화한다. 이 설정은 recovery loss를 줄일 뿐, 최근 write loss 가능성을 제거하지 않는다.
• Production Redis는 metadata에 대해 noeviction 같은 memory policy를 사용한다.
• Coordinator ACL user에는 FLUSHDB, FLUSHALL, broad key deletion 권한을 주지 않는다.
• Client가 관측한 metadata version이 coordinator에 저장된 version보다 높으면 반드시 alert해야 한다.

미지원 Redis Version 또는 Command Set

New Edge Case Design Checklist

새 coordinator 기능은 구현 전에 아래 질문에 답해야 한다.

1. Redis-recorded state machine state는 무엇인가?
2. Response 전에 어떤 metadata field를 Redis에 기록하는가?
3. Response가 손실되어도 반복 가능한가?
4. Coordinator unavailable 동안 client는 무엇을 하는가?
5. 어떤 local lease/cache가 client 동작을 제한하는가?
6. Lease 만료 후 어떤 동작을 하는가?
7. 어떤 epoch, revision, version이 stale report를 거절하는가?
8. 새 coordinator가 Redis metadata와 client retry만으로 state를 재구성할 수 있는가?
9. Metadata key가 사라지면 어떻게 하는가?
10. Consumer가 Redis 현재 값보다 높은 metadataVersion을 보고하면 어떻게 하는가?
11. 어떤 client request가 client가 관측한 최고 version을 전달하는가?
12. 어떤 metric과 runbook이 이 실패를 드러내는가?

Test Matrix

구현은 세 수준의 시나리오 테스트를 가져야 한다.

우선순위 테스트:

• DRAIN response state가 Redis에 기록됐고 response가 손실되면 다음 heartbeat가 같은 DRAIN을 반환한다.
• DRAIN 전달 후 coordinator unavailable이면 consumer가 shard를 revoking 상태로 유지하고 read를 재개하지 않는다.
• REVOKED ack가 Redis에 기록됐지만 response가 손실되면 다음 heartbeat에서 새 owner가 assignment를 받는다.
• Previous owner가 draining 중 expire되면 expiration 이후 새 owner가 assignment를 받는다.
• Metadata key가 삭제되면 coordinator는 fail closed하고 heartbeat로 재구성하지 않는다.
• Client가 metadata version N을 받은 뒤 Redis가 N-1로 되돌아가면 다음 heartbeat가 SYNC_METADATA를 받는다.
• SYNC_METADATA response가 유실되면 다음 high-version heartbeat가 같은 SYNC_METADATA를 다시 받는다.
• Consumer가 SYNC_METADATA를 받고 제거된 shard를 drain하기 시작하면, REVOKED 보고와 다른 owner blocking 해소 전까지 REVOKE_PENDING을 받는다.
• Metadata correction round 중 여러 consumer가 stale revoke를 동시에 보고해도 coordinator는 현재 Redis target/current ownership과 일치하는 revoke만 반영한다.
• Coordinator outage 중 producer cache가 만료되면 publish fail closed한다.
• Old coordinator crash 후 new coordinator가 Redis-recorded metadata에서 rebalance를 이어간다.

Monitoring과 Runbook 요구사항

필요 signal:

• coordinator terminating state
• Redis mutex latency와 revision conflict count
• heartbeat success/failure by status
• member heartbeat age
• metadata version regression count
• client가 보고한 max metadata version이 coordinator에 저장된 version보다 높은 횟수
• consumer assignment lease remaining time
• member revoking shard count
• producer routing cache age와 refresh failure
• metadata revision conflict count
• metadata schema/layout error count
• Redis command compatibility failure count

Runbook은 다음 상황을 다뤄야 한다.

• DRAIN은 발급됐지만 revoke ack가 진행되지 않음
• heartbeat 중 coordinator unreachable
• rolling update handoff stall
• member lease expiration과 rejoin
• Redis metadata key loss 또는 corruption
• unsupported Redis command configuration
• coordinator outage 중 producer routing cache expiry