이벤트 루프와 보안을 깨뜨리지 않고 Rust 리버스 프록시를 고치세요

## 프록시 라이브러리의 계층과 의존 방향을 지키세요 저장소를 의존성 방향이 명확한 계층형 시스템으로 취급한다. - 제어 영역 라이브러리는 구성 파싱, 명령 스키마, 공유 상태, 로깅 도우미, 프로세스 간 채널을 담당한다. - 프로토콜/런타임 라이브러리는 단일 스레드 이벤트 루프, 라우팅, 소켓, 버퍼, 메트릭, TLS, HTTP, 프록시 프로토콜 처리를 담당한다. - 바이너리 크레이트는 감독자, 워커, CLI, 구성 로딩, 무중단 재구성, 업그레이드, 명령 서버를 담당한다. - 통합 테스트 및 결정론적 시뮬레이션 크레이트는 런타임 라이브러리에 의존하지만 비동기 또는 테스트 전용 의존성을 프로덕션 코드로 유출해서는 안 된다. - 퍼징 대상은 도구 체인 요구사항이 다르면 주 워크스페이스 밖에 둘 수 있다. 런타임에서 제어 영역 코드로 향하는 의존성 방향을 유지한다. 각 워커를 단일 스레드로 유지하고 이벤트 루프에서 공유 뮤텍스를 피하며, 아키텍처를 의도적으로 재설계하지 않는 한 프로덕션 라이브러리에 비동기 런타임을 넣지 않는다. ## 고정된 툴체인으로 빌드하고 기능 조합을 테스트하세요 코드 변경 전에 고정된 Rust 도구 체인과 필수 코드 생성기를 확인한다. 스키마 생성이 엄격한 전제 조건이라면 컴파일 실패를 해석하기 전에 생성기를 설치하거나 검증한다. 일반 빌드와 테스트에는 잠긴 의존성을 사용한다. 저장소 구성에서 요구하는 도구 체인으로 포매터를 실행하고, 경고를 거부하도록 린트를 실행하며, 출시 작업 전에 전체 워크스페이스를 테스트한다. 반복 작업 중에는 집중 테스트를 사용한 뒤 영향을 받는 워크스페이스 수준 게이트로 돌아간다. 기능 플래그를 명시적인 호환성 셀로 취급한다. - 기본 할당자와 암호화 선택을 문서화한다. - 규정 준수 지향 모드를 포함해 지원되는 각 암호화 공급자를 개별 테스트한다. - 프로덕션 빌드에서 테스트 주입 훅을 절대 활성화하지 않는다. - 디버그/추적 로깅, 파서 허용 범위, SIMD, 무복사 I/O, 원격 측정 기능이 동작·크기·관찰 가능성을 바꾼다면 명시적으로 선택해야만 켜지게 한다. 기본 빌드 하나가 통과했다는 이유로 변경이 깨끗하다고 주장하지 않는다. 변경이 직접 영향을 주는 기능 조합을 확인한다. ## panic 없이 오류와 로그를 다루고 생성 코드는 손으로 고치지 마세요 구조화된 라이브러리 오류를 사용하고 넓은 맥락은 실행 파일 경계에서만 추가한다. 네트워크가 제어하는 입력은 프로토콜 오류, 연결 조치, 메트릭, 맥락 로그가 되어야 하며 출시 경로에서 `unwrap`, `expect`, `panic` 또는 도달 불가능 분기를 절대 유발해서는 안 된다. 주변 코드의 소유권 관례를 따른다. 빌린 문자열이나 바이트를 소유 값으로 바꿀 때는 의도가 드러나는 변환을 선호하고, 이미 소유되고 복제 가능한 값이면 일반 복제를 사용한다. 프로토콜 모듈은 기존 맥락 로깅 매크로와 안정적인 검색 태그를 사용해야 한다. 운영자가 실패를 연계할 수 있도록 표준 세션/요청/백엔드 컨텍스트를 유지한다. 예상된 유휴 종료와 잡음이 많은 상태에는 디버그나 추적을 사용하고, 경고와 오류 수준은 실제 프로토콜 결함이나 불변 조건 위반에만 사용한다. 공개 메트릭은 중앙 메트릭 계층에 두고, 추가하거나 이름을 바꿀 때 사용자용 구성 참조를 갱신한다. 게이지 언더플로를 정확성 버그로 취급한다. 생성된 프로토콜 바인딩을 절대 직접 편집하지 않는다. 원본 스키마를 편집하고 빌드로 다시 생성한다. 핵심 경로의 새 비안전 코드는 가까운 곳에 불변 조건 설명과 집중 테스트가 필요하다. ## 소켓 쓰기와 버퍼 때문에 이벤트 루프가 멈추지 않게 하세요 에지 트리거 I/O에서는 읽기 경로에서 바이트를 대기열에 넣는 것만으로 부족하다. 쓰기 준비가 대기 중임을 명시적으로 알린다. 이 신호가 없으면 특정 프레임이나 버퍼 경계에서만 세션이 멈춘다. 스칼라 및 벡터 소켓 쓰기 구현은 재시도와 부분 쓰기 동작까지 구조적으로 대칭을 유지한다. 암호화된 프런트엔드에서는 재설정을 내보내 이미 대기 중인 바이트를 잘라낼 수 있는 완전한 양방향 종료를 피한다. 쓰기 측을 닫고 상대의 종료는 정상 읽기 경로를 따르게 한다. 최대 프로토콜 프레임과 헤더를 담을 만큼 큰 버퍼를 유지한다. 작은 버퍼가 프레이밍 코드를 교착시키게 두지 말고 시작 시 구성을 검증한다. 회선 수준 연결 상태와 버퍼를 소유하는 스트림 상태를 분리하고, 검증된 수명 주기 규칙을 갖춘 안정적 식별자로 상호 참조한다. 프런트엔드 프로토콜 협상과 백엔드 기능 힌트는 다른 개념이므로 하나를 다른 하나의 우발적 게이트로 사용하지 않는다. 플러드 제어는 재설정 폭주, 연속 프레임 체인, 반복 제어 프레임, 우선순위 남용을 다뤄야 한다. 다중 프로세스 무중단 재구성은 단일 스레드 워커에 명령을 배포하기 전에 감독자에서 검증해야 한다. ## 퍼징과 재현 가능한 시뮬레이션으로 계층별로 테스트하세요 모듈 옆 단위 테스트, 프로세스 수준 통합 테스트, 퍼징 대상, I/O 없는 상태 머신의 결정론적 시뮬레이션, 로그 배치 같은 구조 계약의 회귀 방지라는 다섯 가지 보완적 테스트 계층을 사용한다. 파서와 복잡한 상태 머신 함수에서는 디버그 빌드에 사전 조건, 사후 조건, 긍정·부정 단언을 넣는다. 공개 상태 머신 진입점은 불변 조건 전체 검사로 끝나야 한다. 단언은 내부적으로 불가능한 상태를 설명하며, 적대적 네트워크 입력도 안전한 프로토콜 결과를 반환해야 한다. 시드가 있는 난수원, 가상 시간, 적대적 부하, 장애 주입으로 결정론적 시뮬레이션을 구동한다. 모든 실패를 재현할 수 있도록 시드를 기록한다. 시뮬레이션 전용 런타임 플래그와 의존성은 시뮬레이션 크레이트로 제한한다. 통합 테스트는 포트를 동적으로 할당하고 TCP 응답을 한 세그먼트가 아니라 끝까지 읽으며, 임의 대기 대신 명시적 기한이나 조건 충족까지의 재시도를 사용해야 한다. 무시된 테스트에는 구체적인 환경 의존성이나 추적되는 이유가 필요하며, 회귀를 숨기려고 무시해서는 절대 안 된다. 업그레이드, 파서, 압축, 프레이밍 변경에는 일반 테스트와 함께 전용 통합 테스트 모음과 일치하는 퍼징 대상을 실행한다. ## TLS, 파서, 프레이밍은 회귀 테스트와 함께 신중히 바꾸세요 TLS 설정, 프로토콜 협상, 이름 바인딩, 인증서 로딩, 파서와 헤더 정규화, 흐름 제어, 명령 프레이밍, 디스크립터 전달, 메트릭, 로그는 보수적으로 테스트에 근거해 변경한다. 실제 적용된 프레이밍과 다른 표현을 전달하지 말고 모호한 메시지 프레이밍을 거부한다. 의사 헤더 순서, 콘텐츠 길이 조정, 요청 밀수 방어, 올바른 재설정 또는 정상 종료 의미 체계를 유지한다. 명령 채널에서는 길이 접두사, 부분 메시지, 파일 디스크립터 전송, 상태 재생, 버퍼 경계를 검증한다. 프록시 프로토콜 처리에서는 부분 및 과대 헤더와 상태 확인 트래픽을 다룬다. 로그나 메트릭으로 비밀 또는 민감한 값을 노출하지 않는다. 모든 오류 및 종료 경로에서 카운터와 게이지를 정확히 유지한다. 이벤트 루프나 보안 코드를 변경할 때 정확한 불변 조건에 대한 집중 회귀 범위를 추가한 뒤 인접 프로토콜 테스트를 실행한다. 관련 없는 리팩터링을 같은 변경에 섞지 않는다. ## 풀 리퀘스트에 프로토콜과 보안 영향을 적으세요 복잡한 프로토콜 하위 시스템을 변경하기 전에 표준 수명 주기 또는 아키텍처 문서를 읽는다. 오래된 문서는 참고로만 취급하고 파일 참조를 현재 코드와 대조한다. 범위가 제한된 브랜치와 영향받는 하위 시스템을 밝히는 규약식 커밋 메시지를 사용한다. 저장소의 서명 및 승인 정책을 따른다. 작업이 게시를 허가하면 커밋된 브랜치를 푸시하고 결과 CI 실행을 보고하며, 그렇지 않으면 로컬에서 허가된 경계에서 멈춘다. 활성 통합 브랜치가 명시되지 않았다면 현재 기본 브랜치를 기준으로 변경한다. 풀 리퀘스트에는 프로토콜 또는 보안 영향, 실행한 명령, 추가한 테스트, 문서 변경을 설명해야 한다. 소유권과 기여자 라이선스 게이트를 준수한다. 구성 키, 메트릭, 명령줄 플래그, 업그레이드 요구사항 등 사용자나 운영자에게 보이는 동작이 바뀌면 변경 로그와 구성 참조를 갱신한다. 인계 전에 생성 파일, 우발적 기능 유출, 누락된 테스트, 오래된 참조, 관련 없는 편집이 있는지 diff를 검토한다. ## 승인을 받은 뒤에만 출시하고 핫 업그레이드를 먼저 테스트하세요 배포를 별도로 허가되는 단계로 취급한다. 먼저 잠기거나 동결된 의존성으로 출시 산출물을 빌드한 뒤, 구성 검증과 영향을 받는 준비 게이트를 스테이징과 동등한 환경에서 실행한다. 컨테이너와 운영체제 패키지는 스키마 생성기와 플랫폼 라이브러리를 포함해 로컬에서 사용한 것과 같은 빌드 전제 조건을 설치해야 한다. 도구 체인을 고정하고 테스트 전용 의존성을 프로덕션 산출물에서 제외한다. 이벤트 루프나 워커 수명 주기 회귀는 워커 하나, 자동 재시작 비활성화, 백트레이스 활성화 상태로 재현한다. 그러면 감독자 복구가 첫 실패를 숨기지 못해 첫 실패가 보인다. 무중단 업그레이드는 리스너와 세션 인계 불변 조건을 유지해야 한다. 출시 전에 업그레이드 경로를 명시적으로 테스트한다. 일반 재시작 성공을 디스크립터 전송이나 재생이 작동한다는 증거로 취급하지 않는다. 명시적 허가와 롤백 경로 없이는 프로덕션에 배포하거나 자격 증명을 변경하거나 파괴적 복구를 수행하지 않는다. 빌드한 것, 통과한 게이트, 미검증 사항, 작업을 멈춘 정확한 경계를 보고한다.