링크 미리보기는 명세만 보면 세 줄짜리 기능이다. URL을 열고, HTML을 파싱하고, og: 태그를 꺼내면 된다. 그런데 그 세 줄이 프로덕션에서 무너지는 지점이 꽤 많고, 그중 상당수는 "에러율이 높다"는 하나의 숫자 뒤에 뭉쳐서 잘 보이지 않는다.
이 시리즈는 그 세 줄이 무너지는 자리를 순서대로 따라가는 설계 노트다. 1편은 실패를 원인별로 갈라놓고 런타임 선택이 실제로 갈리는 지점을 따진 뒤, User-Agent와 인코딩으로 커버리지를 올리고 캐시와 목표 수치를 세우는 데까지 간다. 2편은 사용자가 준 URL을 서버가 대신 여는 일의 위험을 다루는데, 막는 법보다 뚫리는 법을 먼저 보는 순서로 잡았다.
사용법보다 왜 그렇게 설계하게 되는지에 무게를 두었고, 등장하는 코드는 전부 Node.js v24.14.1에서 직접 돌려봤다. 그 과정에서 처음에 그럴듯하게 적어둔 것 중 넷이 틀렸다는 것을 알게 됐는데, 틀린 자리를 지우지 않고 그대로 남겨 두었다. 그 대비가 이 시리즈에서 가장 하고 싶은 이야기이기도 하다.