버튼 다섯 개를 눌렀는데 체크는 하나만 남았다

체크 항목이 여러 개 달린 메시지에서 버튼 5개를 연달아 눌렀다. 상태 파일을 열어 보니 체크가 1개만 남아 있었다. 먼저 누른 체크들이 사라졌다.

2026년 7월 말에 고친 문제다. 커뮤니티용 텔레그램 봇에 인라인 버튼으로 항목을 체크하는 메시지가 있고, 체크 상태는 JSON 파일 하나에 있다. 고친 뒤의 콜백부터 적는다.

_STATE_LOCK = asyncio.Lock()

async def on_toggle(update, context):
    query = update.callback_query
    async with _STATE_LOCK:
        state = _load_state()
        checks = state[token].setdefault("checks", {})
        if checks.get(item):
            checks.pop(item, None)
            answer = "체크를 해제했어요."
        else:
            checks[item] = who
            answer = "체크했어요."
        _save_state(state)
    await query.answer(answer)               # 락 밖에서 응답

asyncio.Lock 하나로 읽기부터 쓰기까지를 직렬화했고, 응답은 락 밖으로 뺐다.

고치기 전에는 읽기와 쓰기 사이에 await가 있었다

버튼 콜백은 파일을 읽고, 해당 항목을 고치고, 파일 전체를 다시 쓴다. 원래 흐름은 이랬다(식별자를 바꾸고 줄였다).

async def on_toggle(update, context):
    query = update.callback_query
    state = _load_state()                    # 1. 읽기
    checks = state[token].setdefault("checks", {})
    if checks.get(item):
        checks.pop(item, None)
        await query.answer("체크를 해제했어요.")   # 2. 네트워크 왕복
    else:
        checks[item] = who
        await query.answer("체크했어요.")
    _save_state(state)                       # 3. 쓰기

asyncio는 스레드 하나에서 도니까 경합이 없을 것 같지만, 있다. 코루틴이 await에서 결과를 기다리며 멈추면 제어가 이벤트 루프로 돌아가고, 루프는 그 사이에 다른 태스크를 실행한다. 이 봇은 update를 동시에 처리하도록 설정돼 있어서 앞 콜백이 끝나기 전에 다음 콜백이 시작될 수 있었다.

읽기와 쓰기 사이에 낀 await query.answer()는 텔레그램 서버까지 다녀오는 호출이다. 버튼 5개를 빠르게 누르면 이런 순서가 가능하다.

  1. 콜백 A가 파일을 읽는다. 체크 0개.
  2. A가 answer()에서 기다리는 동안 콜백 B, C, D, E가 차례로 파일을 읽는다. 전부 체크 0개인 같은 스냅샷이다.
  3. 각자 자기 항목 하나만 체크한 dict를 들고 파일 전체를 덮어쓴다.
  4. 마지막에 쓴 콜백의 내용만 남는다. 체크 1개.

전형적인 read-modify-write 경합이다. 스레드가 없어도 읽기와 쓰기 사이에 실제로 기다리는 await가 하나만 있으면 성립한다.

게시 코드는 미리 읽은 dict를 인자로 받고 있었다

콜백만의 문제도 아니었다. 정해진 시각에 이 메시지를 게시하는 코드도 같은 파일을 썼는데, 호출부가 미리 읽어 둔 상태 dict를 인자로 넘겨받아 메시지를 보낸 뒤 저장했다. 발송을 기다리는 사이에 누군가 버튼을 누르면 그 체크는 발송 코드가 들고 있던 옛 dict에 덮여 사라진다.

그래서 게시 쪽 함수도 상태 dict를 인자로 받지 않고, 락을 잡은 뒤 스스로 읽도록 시그니처를 바꿨다. 호출부가 넘기던 dict 인자를 없앤 것이 이 수정의 절반이다. 락을 추가해도 락 밖에서 읽은 스냅샷이 인자를 타고 들어오면 같은 문제가 남는다.

query.answer()를 락 밖으로 뺀 건 네트워크 호출이라서다. 락 안에 두면 그 시간만큼 다른 콜백이 기다린다. 응답에 쓸 문구만 락 안에서 정해 변수에 담고, 호출은 락을 푼 뒤에 한다.

락은 하나로 충분하다고 봤다. 봇은 단일 프로세스로 돈다. 프로세스가 둘이었다면 asyncio.Lock으로는 막을 수 없고 파일 락 같은 것이 필요했을 것이다.

락 안에 네트워크 호출이 남은 자리도 있다. 메시지를 게시하는 함수는 보낸 메시지의 번호를 상태에 기록해야 해서 발송이 끝난 뒤에야 저장할 수 있다. 발송 호출이 락 구간 안에 들어 있고, 이 자리는 지금도 그대로다.

11월, 17초 간격으로 들어온 수정 요청 두 개

11월에는 다른 기능에서 같은 구조를 봤다. 대화방에 파일 묶음을 올리고 수정 요청을 글로 적으면 봇이 고친 묶음을 돌려주는 기능이다. 수정 요청을 연달아 보내면 뒤 요청은 앞 요청의 결과에 이어서 적용돼야 한다.

수정 요청 두 개가 17초 간격으로 들어왔다. 편집은 시간이 걸리는 작업이라, 앞 편집이 도는 동안 뒤 요청이 시작되면 뒤 요청은 “가장 최근 묶음”으로 아직 원본을 읽는다. 그러면 뒤 요청의 결과에는 앞 요청의 수정이 빠진다.

이날은 앞 결과가 간발의 차로 먼저 나가서 실제 피해는 없었다. 타이밍이 조금만 달랐으면 깨졌을 자리라 고쳤다.

수정 요청 두 개를 연달아 보낸 직후, 나온 결과가 둘 다 반영된 최종본이 맞는지 확인하다가 들여다보게 됐다. 거기서 고친 커밋까지 10분이 안 걸렸다.

여기서는 전역 락을 쓰지 않았다. 편집은 버튼 처리와 달리 오래 걸려서, 전역 락이면 한 대화의 편집이 다른 대화의 편집까지 막는다. 대화(채팅과 토픽의 쌍)별로 락을 따로 뒀다.

_edit_locks: dict[tuple[int, int], asyncio.Lock] = {}

async def handle_edit_request(message, route, context, text):
    lock = _edit_locks.setdefault(_key(route), asyncio.Lock())
    if lock.locked():
        await _send(context, route, QUEUED_NOTICE,
                    reply_to=message.message_id)
    async with lock:
        return await _handle_edit_text(message, route, context, text)

setdefault와 locked() 확인 사이에는 await가 없으므로 이 부분 자체는 경합하지 않는다. 안쪽 함수는 락을 잡은 뒤에 “가장 최근 묶음”을 읽는다. 기다리던 요청이 락을 얻었을 때는 앞 요청의 결과가 이미 최근 묶음으로 기록돼 있으므로 그 위에 이어서 고친다. 7월과 똑같이 읽기를 락 안에서 한다.

lock.locked()가 참이면 앞의 수정이 끝난 뒤 이어서 처리하겠다는 안내를 한 줄 보낸다. 직렬화하면 뒤 요청은 앞 작업이 끝날 때까지 아무 반응이 없게 되므로, 기다리는 중이라는 것을 알리는 안내를 같이 넣었다.

예전 코드에서 실패하는 테스트

두 번째 수정에는 경합을 재현하는 테스트를 붙였다. 편집 계획을 세우는 함수를 가짜로 바꿔, 첫 요청일 때는 이벤트를 세우고 0.3초를 잔다. 테스트는 첫 요청을 태스크로 띄우고, 그 이벤트가 세워질 때까지 기다린 다음 두 번째 요청을 보낸다. 이렇게 하면 “앞 편집이 도는 중에 뒤 요청이 들어온다”는 순서가 매번 같게 만들어진다.

확인하는 것은 세 가지다. 두 번째 요청이 원본 말고 첫 결과 파일을 읽었는지, 기다린다는 안내가 나갔는지, 최종 결과물에 두 수정이 모두 들어 있는지.

이 테스트는 락이 없던 예전 코드에서 실패한다. 경합 수정은 고친 뒤에도 “원래 안 깨지던 것 아닌가”를 가리기 어려워서, 예전 코드에서 실패하는 테스트가 있어야 고쳤다고 말할 수 있었다.

첫 번째 수정에는 이런 테스트가 없었다. 체크 5개 중 1개만 남은 상태 파일을 실물로 본 것이 근거의 전부였다.