TL;DR

  • macOS 14.6 이상에 포함된 libcurl 8.7.1의 HTTP/2 오류로 덤(dumb) 프로토콜을 사용하는 Git 저장소 복제가 실패하거나 멈추며, 최신 macOS 27에도 문제가 남아 있음.
  • 원인은 FAILONERROR 옵션이 설정된 요청에서 발생하는 libcurl 오류이며, 같은 HTTP/2 연결의 다른 요청까지 실패하거나 멈추게 함.
  • objects/info/alternates와 objects/info/http-alternates가 없는 경우 반환되는 404 오류가 문제를 촉발하며, go get의 직접 프록시 사용이나 GOPRIVATE 모듈도 영향을 받음.
  • 클라이언트에서는 Git의 HTTP 버전을 1.1로 강제하거나 MacPorts로 Git을 설치할 수 있고, 서버에서는 두 대체 위치 파일을 빈 파일로 만들 수 있음.
  • 스마트(smart) 프로토콜은 이 오류의 영향을 받지 않지만 서버 측 계산 부담이 크며, 덤 프로토콜은 정적 파일만으로 제공할 수 있어 웹 스크래핑 부하에 더 잘 대응함.

문제와 영향 범위

  • macOS 14.6 이상에 포함된 libcurl 8.7.1로 다음 저장소를 복제하면 실패하거나 멈춤: git clone https://software.sslmate.com/src/macosgitbug.git
  • HTTP/2를 끄면 복제가 정상 작동함: git clone -c http.version=HTTP/1.1 https://software.sslmate.com/src/macosgitbug.git
  • 문제는 libcurl 8.7.1의 FAILONERROR 옵션 처리 오류임. 이 옵션은 404 같은 실패한 HTTP 상태 코드를 요청 실패로 처리함.
  • HTTP/2를 사용할 때 이 오류로 같은 연결에서 진행 중인 다른 요청도 실패하거나 멈출 수 있음.
  • 이 문제는 2년여 전 curl 8.8.0에서 수정됐지만, Apple은 지난주 출시된 macOS 27에도 문제가 있는 버전을 계속 포함함.

덤 프로토콜에서 발생하는 이유

  • Git은 덤 전송 프로토콜로 저장소를 가져올 때 objects/info/alternates와 objects/info/http-alternates 등에 FAILONERROR 옵션이 설정된 HTTP 요청을 보냄.
  • 두 파일은 저장소 콘텐츠를 찾을 수 있는 대체 위치를 나열함. 대부분의 저장소에는 대체 위치가 없어 파일이 존재하지 않으며, 해당 URL은 404를 반환함.
  • 문제가 있는 libcurl 버전에서는 이 404 응답이 Git의 다른 HTTP 요청도 실패하게 만들어 저장소 복제를 막음.
  • 영향은 Git을 직접 실행하는 경우에 국한되지 않으며, 내부에서 Git을 호출하는 GOPROXY=direct 방식의 go get과 GOPRIVATE에 등록된 모듈도 해당함.

우회 방법

  • 클라이언트에서는 Git이 HTTP/1.1을 사용하도록 전역 설정하면 됨: git config --global http.version HTTP/1.1
  • MacPorts를 통해 Git을 설치하는 방법도 있음. 반면 Homebrew는 시스템 libcurl을 사용하므로 이 문제의 해결책이 되지 않음.
  • 클라이언트 사용자가 우회 방법을 모를 수 있으므로, 덤 프로토콜로 Git 저장소를 호스팅하는 서버는 macOS 사용자의 복제를 고려할 필요가 있음.
  • 서버 측에서는 다음 두 파일을 빈 파일로 만들면 404 응답이 발생하지 않아 오류가 촉발되지 않음: objects/info/alternates, objects/info/http-alternates.
  • Git은 빈 파일을 404 응답과 동일하게 처리함: touch /path/to/repo.git/objects/info/alternates /path/to/repo.git/objects/info/http-alternates

스마트 프로토콜과 덤 프로토콜

  • 저장소가 스마트 프로토콜을 지원하면 오류가 발생하지 않음. 따라서 GitHub 등 인기 호스팅 서비스의 저장소는 HTTP/2를 사용해도 macOS에서 복제 가능함.
  • 스마트 프로토콜은 여러 장점이 있지만 서버 측 계산량이 많으며, 적당한 수준의 부하만으로도 서버가 중단될 수 있음.
  • 덤 프로토콜은 정적 파일만으로 제공할 수 있어 현재 웹을 괴롭히는 AI 스크래퍼의 대규모 부하를 견디는 데 큰 차이를 만듦.
  • 정적 파일로 계속 제공하면서 스마트 프로토콜의 장점을 일부 제공하는 덤 프로토콜의 개선이 기대됨.

오류 원인 파악

  • Traefik 프로젝트의 Romain이 SSLMate 저장소를 macOS에서 복제할 수 없다는 점을 발견함.
  • Sebastiaan van Stijn은 Traefik의 go.mod 파일에서 조용히 우회하는 대신 이 문제를 상위 프로젝트에 보고하자고 요청함.
  • Kangmin Kim이 근본 원인으로 libcurl 오류를 지목했으며, Claude Code가 빈 파일 우회 방법을 제안함.
  • macOS에 2년 된 치명적 libcurl 오류를 포함한 Apple에 대한 불만이 제기됨.