FEATURE: Add CompletableFuture Admin APIs

[f1v3-dev]

🔗 Related Issue

• https://github.com/jam2in/arcus-works/issues/832#event-23130177064

⌨️ What I did

• v2 API에 Admin API (flush, stats, version)를 지원합니다.
  • flush() / flush(int delay): flush_all
  • flush(String prefix) / flush(String prefix, int delay): flush_prefix
  • stats() / stats(String arg): 서버 통계 조회
  • versions(): 서버 버전 조회

[f1v3-dev]

flush(int delay) 의 delay 파라미터 처리 방식에 대해 논의가 필요합니다.

현재 -1을 "delay 파라미터를 생략한다"는 값으로 사용하고 있습니다.

• delay = -1 → flush_prefix <prefix>\r\n (delay 생략, 즉시 무효화)
• delay = 0 → flush_prefix <prefix> 0\r\n (동일하게 즉시 무효화)

서버는 음수를 받지 못하지만, "사용하지 않음"을 표현하기 위해 -1을 코드 내부 규약으로 허용하고 있습니다.

delay가 없는 경우(-1)와 delay = 0인 경우 모두 서버에서 즉시 flush로 동작이 일치하는데, 이를 어떻게 처리해야 할까요?

[f1v3-dev]

flush_prefix 에 대하여 아래와 같은 상황으로 논의가 필요합니다.

TO-BE는 제 생각을 기반으로 현재 구현한 방향입니다.

서버 동작

flush_prefix <prefix> 명령은 모든 캐시 노드에 브로드캐스트됩니다. 이 때, 각 노드는 독립적으로 응답하게 됩니다.

• 해당 prefix의 키가 있는 노드 → OK
• 해당 prefix의 키가 없는 노드 → NOT_FOUND

AS-IS (v1 문제)

NOT_FOUND를 실패로 처리하여 하나라도 NOT_FOUND가 오면 false를 반환합니다.

시나리오: 노드 A, B, C 중 A에만 prefixA:key 존재

노드	서버 응답	v1 처리
A	OK	-
B	NOT_FOUND	result = false 덮어쓰기
C	NOT_FOUND	result = false 덮어쓰기

• 실제 동작: A의 키는 flush됨
• 반환값: false → prefix가 없어서 아무것도 안 됐나? 라고 사용자가 해석할 수 있음

TO-BE (v2 변경)

NOT_FOUND를 "해당 노드에 prefix 없음"으로 처리하고, 하나라도 flush가 실제로 발생했는지를 기준으로 반환값을 결정합니다.

상황	v1	v2
일부 노드에 prefix 존재 (A=OK, B/C=NOT_FOUND)	false	true
모든 노드에 prefix 없음 (A/B/C=NOT_FOUND)	false	false