하트비트만 보내는 스트림은 영원히 생성되는 레이블이 아닌 첫 토큰 마감 시간이 필요하다

키보드 접근성 테스트를 거치고 나니 채팅 패널을 하나의 파일로 재구축하게 되었는데, 컴포지서가 비활성화되고 상태가 'Generating'에 멈춰 있는 문제가 있었습니다. 모의 추론 서버(mock inference server)가 이미 응답 헤더를 보냈기 때문에 네트워크 행은 정상적으로 보였고, 저는 거의 모델을 탓할 뻔했습니다. 스크린 리더는 예전의 공손한 상태 메시지를 한 번 반복하더니, 마치 어딘가에서 토큰이 계속 도착하는 것처럼 침묵했습니다. 혹시 상태 코드가 성공 범위(success range)를 전혀 벗어나지 않아서 스피너(spinner)를 영원히 돌려본 적이 있나요?

탭 순서 상의 실패 경험

저는 콘솔에서가 아니라 키보드에서부터 테스트를 시작했습니다. 왜냐하면 버그가 실제로 대기 중인 사용자에게 도달하는 방식이 그랬기 때문입니다. 포커스는 비활성화된 텍스트 영역(textarea)에 머물러 있었고, 'Stop' 제어 버튼은 사라졌으며, 화면의 유일한 변화는 깜빡이는 레이블뿐이었습니다. 라이브 리전(live region)은 요청이 시작될 때 'Generating'을 알렸지만, 그 순간 이후로는 더 이상 새로운 것을 말해주지 않았습니다. 만약 인터페이스가 구두로 실패를 알려주거나 접근 가능한 취소 동작을 제공하지 않는다면, 계속 기다리시겠어요?

시각적 스토리와 접근성 스토리가 분기된 것이었고, 이는 스트리밍 채팅 인터페이스에서 흔히 발생하는 함정입니다. 시각적인 디버깅은 스피너를 보고 지연 시간(latency)을 가정했지만, 보조 기술(assistive technology)은 복구 경로가 없는 정지 상태를 들었습니다. 파서(parser)를 만지기 전에 예상되는 상태들을 적어 놓았는데, 픽셀에서 추측하는 것은 이미 한 번의 시도를 낭비한 것이었기 때문입니다. 테이블은 추측보다 작성하기는 느리지만, 누락된 상태가 명확하게 나타날 수 있는 유일한 장소입니다.

또 다른 스피너 수정 전의 상태 테이블

⚠️ [IMG:N] 형식 토큰은 이미지 placeholder 입니다. 번역하지 말고 원래 위치에 그대로 유지하세요.

토큰이라고 생각했던 프레임들

저는 버그가 특정 공급업체 장애나 조용한 네트워크에 의존하지 않도록 로컬 목업으로 이 지연 현상을 재현했습니다. 서버는 성공 상태와 event-stream content type을 반환한 다음, 주석 하트비트를 작성하고 데이터 토큰은 전혀 보내지 않습니다. 브라우저 개발자 도구에서 원본 본문(raw body)을 숨기도록 허용하지 않는다면 Curl이 그 형태를 명확하게 보여줄 것입니다. 마지막 느린 토큰이 실제로 데이터 라인 없이 콜론 주석이었는지 확인해 보셨습니까?

원본 프레임들이 하는 일

curl -N --max-time 12 http://127.0.0.1:8787/mock-stream

// mock-server.mjs — 로컬 테스트용만, 공급업체 클라이언트 아님
import { createServer } from "node:http";

...

순진한 리더는 주석을 포함하여 모든 청크마다 수신 카운터를 증가시키므로 UI가 생성이 시작되었다고 믿게 됩니다. 저는 프레임을 하트비트와 토큰으로 분리했고, 비어있지 않은 텍스트 델타(text delta)가 나타날 때까지 보이는 상태를 변경하는 것을 거부했습니다. 아래 파서는 그 구분을 위한 테스트용 장치이며, 프로덕션 환경을 위한 완전한 Server-Sent Events 구현은 아닙니다. 공백 데이터 라인은 의도적으로 null로 유지되는데, 침묵이 리더가 신뢰할 수 있는 어시스턴트 텍스트로 승격되어서는 안 되기 때문입니다.

type Frame =
  | { kind: "heartbeat" }
  | { kind: "token"; text: string }
...

이 스니펫들은 본 가이드라인을 위해 구성된 로컬 더미 데이터이며, 실제 장애 기록이나 측정된 서비스 중단 시간의 트랜스크립트는 아닙니다. 저는 어떤 클라이언트에게 제가 통제하지 않는 호스트를 지목하기 전에, 이 실패가 지루하고 반복 가능하도록 만들고 싶습니다. 녹색 상태 코드와 움직이는 폭포수 애니메이션이 응답을 의미하는 것은 아니며, 이 더미 데이터는 그 유혹을 계속 보이게 하기 위해 존재합니다. 만약 여러분의 로그가 주석 프레임을 표시할 수 없다면, 스피너를 고치는 데만 몰두하다가 실제 장애 지점을 놓치게 될 것입니다.

근본 원인: connected가 generating으로 위장하고 있었다

근본 원인은 느린 페인트(slow paint)나 생성 중인 레이블의 애니메이션 누락이 아니라, 상태가 붕괴된 것이었습니다. Fetch가 해결되고, 리더 루프가 실행되었으며, 각 keepalive 청크는 제가 잘못 연결한 비활동 타이머를 지웠습니다. 상태 문자열이 절대 변경되지 않았기 때문에, 정중한 라이브 영역(live region)은 알릴 변동 사항(mutation)이 없었고, 이것이 바로 조용한 실패가 숨어드는 방식입니다. 우리가 감시하는 문자열을 변경하지 않고 포커스를 복구 제어 요소로 이동시키지 않았다면, 왜 라이브 영역이 말을 해야 할까요?

또한 저는 장애 지점 아래에 놓여 있던 포커스 버그도 발견했는데, 이것은 순전히 시각적인 시간 초과 조정으로는 살아남았을 것입니다. 제출(submit) 시 컴포저가 비활성화되었고, Stop 버튼은 스트리밍 상태에서만 렌더링되었기 때문에, awaiting-token 상태에서는 키보드 동작이 불가능했습니다. 콘솔에만 기록되는 마감 시간(deadline)은 제가 이미 이전 스트림 버그들로부터 알고 있던 실수를 반복했을 것입니다. 보이지 않는 복구는 복구가 아니며, Stop으로 탭할 수 없는 사용자는 장애가 감지된 후에도 여전히 갇혀 있습니다.

해결책은 토큰에 연결된 마감 시간이다

저는 시계를 awaiting-token 상태로 옮기고, 하트비트가 그 시계 자체를 건드리지 않고 디버그 라인을 업데이트하도록 했습니다. 8초는 이 목업(mock)의 데모 임계값일 뿐이며, 여러분이 출시하는 모든 모델이나 네트워크 경로에 대한 권장 사항은 아닙니다. 마감 시간이 작동하면, 저는 리더를 중단시키고 stalled 상태로 이동하며, 누락된 토큰을 명시하는 특정 실패를 알립니다. 일반적인 '무언가 잘못됨(something-went-wrong)' 문자열이 키보드 사용자에게 재시도할지, 기다릴지, 아니면 연결을 확인할지를 알려줄 수 있을까요?

상태 복사 및 포커스

상태 노드는 접근성 트리에서 같은 위치에 머무르기 때문에, 페이즈가 변경되어도 포커스를 훔치는 토스트 알림을 방지합니다. 저는 대기하는 사용자가 실제로 필요로 하는 중단(stall)과 취소(cancellation)에 대해서만 단 하나의 단정적(assertive) 발표를 사용합니다. 토큰 추가는 항상 공손하거나 시각적인 용도로만 유지되므로, 긴 답변이 나중에 오는 중단 메시지를 문자 폭우 속에 묻지 않게 합니다. '중지(Stop)' 버튼은 연결이 시작되는 순간부터 탭 순서상 실제 버튼으로 남아 있으며, 토큰이 도착하기 전에도 컨트롤러를 중단시킵니다.

<p id="stream-status" role="status">첫 번째 토큰을 기다리는 중</p>
<p id="stream-alert" aria-live="assertive" aria-atomic="true"></p>
<button type="button" id="stop-stream">생성 중지</button>

왜 aria-busy가 발표가 아닌가

로그에 aria-busy를 설정하는 것은 스크린 리더에게 토큰이 도착하지 않았다고 알려주지 않으며, 포커스를 '중지(Stop)'로 이동시키지도 않습니다. Busy는 영역에 대한 힌트일 뿐 회복 계획은 아니며, 어떤 사용자들은 그것을 명확한 실패로 전혀 듣지 못합니다. 저는 여전히 연결 중일 때 aria-busy를 설정하지만, 중단된 전환이 이를 지우고 상태 옆에 단정적인 텍스트를 작성합니다. 만약 busy만 토글한다면, 속성을 변경했을 뿐 사용자의 말하는 상태는 'Generating'에 고착됩니다.

재시도(Retry)는 새로운 요청 ID와 새로운 발표를 생성하며, 이전의 빈 시도를 가짜 어시스턴트 산문으로 다시 작성하지 않습니다. 빈 시도는 토큰이 도착하지 않았기 때문에 진단(diagnostics) 라인에 남아 있으며, 따라서 나중에 성공한 내용이 중단된 턴과 혼동되지 않습니다. 저는 각 전환에서 페이즈, 프레임 종류, 경과 밀리초를 기록합니다. 왜냐하면 이 한 줄이 심장 박동 오류(heartbeat mistake)를 부인할 수 없게 만들었기 때문입니다. 만약 당신의 로그가 주석을 토큰과 구분하지 못한다면, 당신은 여전히 스트림 자체가 아니라 스피너 자체를 디버깅하고 있는 것입니다.

재사용 가능한 디버깅 루프

1. 원격 모델이나 서버, 또는 불안정한 사무실 네트워크를 탓하기 전에 로컬 목(mock) 환경에서 재현해 보세요.
2. curl과 -N 플래그를 사용하여 원시 프레임을 캡처하고, 주석, 데이터 라인, 터미널 이벤트를 개별적으로 표시하세요.
3. 응답 헤더와 첫 사용자에게 보이는 텍스트 토큰 사이의 대기 간격을 포함하여 상태 테이블을 작성하세요.
4. 스크린 리더가 감지할 것으로 예상하는 모든 전환에서 라이브 영역 문자열이 실제로 변경되는지 확인하세요.
5. 아무 토큰도 생성되기 전에 Stop 버튼을 누르는 경우를 포함하여, 스크린 리더를 실행한 상태에서 복구 경로를 탭 해보세요.
6. 오직 그 후에야 동일한 클라이언트를 원격 엔드포인트에 연결하고, 느리게 느껴지는 감각보다는 프레임 종류를 비교하세요.

이러한 단계들은 지연이 프록시, 절전 모드의 노트북, 또는 소켓을 열어두는 패딩에서 발생하는 경우에도 여전히 유용합니다. 이 기법은 클라이언트 측에서 전송 활성도(transport liveness)와 답변 진행 상황(answer progress)을 분리하는 아티팩트가 제가 유지하고 싶은 것입니다. 공지 및 포커스는 그 구분에 묶여야 하며, 그렇지 않으면 인터페이스는 시작조차 하지 않은 생성을 계속해서 이야기할 것입니다. 원격 엔드포인트는 나중에 비교할 대상일 뿐이며, 조용히 생성되는 레이블을 이해하려는 첫 번째 장소는 아닙니다.

다음 버그를 살아남는 작은 로그 형태

저는 시간, 종류, 바이트 단위로 마지막 20개 프레임을 담은 링 버퍼(ring buffer)를 유지하고, 마감 시간이 발생할 때 이를 출력합니다. 이 버퍼는 스피너 스크린샷이 아니라 버그 리포트에 포함되어야 합니다. 왜냐하면 스크린샷으로는 누락된 데이터 라인을 보여줄 수 없기 때문입니다. 바이트 단위가 여기서 중요합니다. 주석 하트비트(comment heartbeat)가 작더라도 네트워크 폭포수(network waterfall)에서 실제 트래픽처럼 보일 수 있기 때문입니다. 만약 버퍼에 하트비트 종류만 표시된다면, 저는 렌더링 프로파일링을 중단하고 CSS를 건드리기 전에 파서로 돌아갑니다.

무료 서버에 동일한 탐침(probe) 시도하기

공개 고지: 이 문서는 MonkeyCode의 제품 홍보의 일환으로 작성되었습니다. 제가 여기서 프로젝트를 언급하는 이유는, 모의(mock)가 성공적으로 작동한 후 이 프로브를 다시 실행하기 위한 실용적인 장소가 무료 서버이기 때문입니다. 공급업체 이름이 무음 라이브 영역을 고치지는 못하며, 저는 이 섹션이 로딩 상태의 기적처럼 들리게 하고 싶지 않습니다. 이 초안에 대한 홍보 메모에는 무료 모델 액세스, 무료 서버 옵션, 그리고 1천만 토큰이라는 명시된 허용량이 설명되어 있습니다.

저는 그 허용량을 측정하지 않았고, 모델 이름이나 하드웨어를 나열하지 않았으며, 이 제안을 영구적인 것으로 취급하지 않습니다. 의존하기 전에 현재 프로젝트 약관을 읽어보십시오. 왜냐하면 홍보 수치는 이 기사가 변경되지 않아도 바뀔 수 있기 때문입니다. 원격 대상이 필요하다면, 무료 서버 옵션은 모의가 고의로 실패한 후 다음 적절한 소켓(socket)입니다. 로컬호스트를 떠나 그 서버로 이동할 때는 첫 토큰 마감 시간, 원본 프레임 로그, 그리고 키보드 중지 경로를 기억하십시오.

무료 엔드포인트도 여전히 하트비트를 보내거나, 멈추거나(stall), 토큰이 아닌 본문을 반환할 수 있으므로 동일한 버그는 여러분이 고칠 책임으로 남아 있습니다. 오픈 소스 가용성이 이러한 확인 절차를 제거하지 않으며, 큰 토큰 허용량이 스크린 리더에게 알리는 것도 아닙니다. 만약 이 프로브가 이미 가지고 있는 버그와 일치한다면, 현재 MonkeyCode 무료 서버를 사용하기 전에 라이브 약관을 직접 확인해 보시기 바랍니다. 호스팅된 소켓을 인터페이스 상태가 완료되었다는 증거로 여기기보다는, 먼저 로컬에서 멈춤 현상을 재현하는 것이 더 좋습니다.

이 마감 시간을 그대로 사용해서는 안 되는 사람

• 프로토콜이 이미 유형화된 오류(typed error)나 신뢰할 수 있는 첫 토큰 이벤트(trusted first-token event)를 방출하는 경우, 이 클라이언트 타이머는 건너뛰십시오.
• 8초 데모 상수를 용량 계획, 할당량 모니터 또는 호스팅되는 모델의 어떤 벤치마크로도 사용하지 마십시오.
• 리더(reader)를 중단하는 것을 보안 경계로 취급하지 마십시오. 왜냐하면 이것은 단지 인터페이스 제어권을 사용자에게 반환할 뿐이기 때문입니다.
• 제품이 재연결 시 부분 토큰을 보존해야 하는 경우 이 패턴을 피하십시오. 왜냐하면 이 데모는 빈 시도(empty attempt)를 폐기하기 때문입니다.
• 스크린 리더가 작동하지 않는 팀은 본 기사의 상태 복사본을 다른 검토 없이 배포해서는 안 됩니다.

재현의 한계점 (Limits of the reproduction)

이 목업(mock)은 실제 모델 델타를 전송하지 않으므로, 특정 무료 모델이 텍스트를 청크로 분할하거나 주석을 방출하는 방식에 대해 알려줄 수 없습니다. 8초 상수는 긴 콜드 스타트(cold starts)에는 부정확하므로, 자체 지연 시간 기록에서 이를 대체해야 합니다. 나중에 단계 변경만 알리는 것이 아니라 모든 토큰을 발표한다면 단 하나의 정중한 영역(polite region)도 여전히 너무 말이 많을 수 있습니다. 저는 공식적인 적합성 감사(formal conformance audit)를 수행하지 않았으며, 이 마크업은 WCAG 적합성에 대한 주장이라기보다는 회귀 수정 사항(regression fixture)입니다.

브라우저, 운영 체제 및 보조 기술 버전은 알림 타이밍을 변경할 것이므로, 이 매트릭스는 수정 사항의 일부입니다. 이것을 다시 실행하려면 브라우저, 운영 체제, 보조 기술 버전 및 실패한 정확한 전환(transition)을 보내주십시오. 제가 가장 중요하게 생각하는 것은 헤더 수신에서 정지 상태로 점프하는 부분인데, 그 부분이 제 첫 번째 스피너가 완전히 숨겼던 전환이기 때문입니다. 절대 변하지 않는 생성 레이블은 로딩 전략이 아니며, 첫 토큰 시계(first-token clock)가 그 누락된 상태를 눈에 보이게 만들었습니다.