Skip to content

Shortlink Open Items

wcorn edited this page Aug 24, 2026 · 2 revisions

결정 기록: 단축 URL (링크)

확정 명세 · 아키텍처 · 데이터 모델 · API · 화면

결정한 것과 결정하면서 기각한 것을 남긴다. 기각 사유가 사라지면 같은 논의를 반년 뒤에 다시 한다.

D-1. 링크는 일상의 하위 메뉴가 아니라 세 번째 워크스페이스다

결정 (2026-08-23): /select 3카드 + 사이드바 3분할. 일상 사이드바에는 넣지 않는다.

디자인 핸드오프가 참조한 원래 결정(SL-020 — "일상 사이드바 「링크」")을 덮는다.

안 판단
일상 사이드바 하위 메뉴 기각. 링크는 일상 화면들과 데이터도 흐름도 공유하지 않는다. 발급까지 두 번 들어가야 하고, §5.4의 3초가 깨진다
독립 워크스페이스 채택. 진입 빈도는 높고 체류는 짧다(발급 3초) — 최상단 전환 한 번이면 닿는다
별도 앱/도메인 기각. 로그인·앱 셸·디자인 시스템을 통째로 다시 만들게 된다

대가: /select와 Sidebar는 여행·일상이 매일 지나가는 공용 화면이라 여기 손대는 것이 이 모듈에서 기존 기능에 가장 가까이 가는 변경이다(D-8).

D-2. 리다이렉트는 기존 BE가 서빙한다

결정 (2026-08-23, 개발자): s.orino.dev VirtualService → 기존 orino-app-api. 신규 배포 대상 없음.

안 판단
기존 BE + VirtualService 채택. 신규 이미지·CI·Helm 차트 0. *.orino.dev 와일드카드 인증서와 Gateway 호스트가 이미 있어 VirtualService 하나면 뜬다
같은 코드, 별도 Deployment 기각. 관리 API가 죽어도 리다이렉트가 사는 이점은 있으나, 2노드 홈랩에 파드·모니터링·배포 대상이 하나 더 늘어난다
완전 별도 경량 서비스 기각. 저장소 구조·CI·이미지·Trivy 스캔이 전부 따라붙는다

명세 §6.1의 "관리 화면과 독립"은 SPA로부터의 독립을 뜻한다. FE가 깨져도 리다이렉트는 산다. BE가 죽으면 둘 다 죽는데, 그건 이 홈랩에서 어차피 전면 장애다.

D-3. 공개 주소와 내부 경로를 분리한다 (/{slug} → /r/{slug})

결정: 게이트웨이에서 정규식 재작성.

BE 루트 catch-all을 만들면 스웨거·정적 리소스·오타 요청을 전부 삼키고, 인증 예외를 루트로 열게 된다. 재작성하면 공개 표면이 permitAll("/r/**") 한 줄로 보인다. 부수 효과로 슬러그 문자셋에 안 맞는 스캔 트래픽이 BE에 닿지 않는다.

D-4. 캐시를 두지 않는다

결정: 슬러그 → 목적지 조회에 Redis 캐시를 두지 않는다.

이 모듈의 핵심 기능이 목적지 즉시 교체(§5.1)다. 캐시는 그 즉시성을 정면으로 깎는다. 단일 사용자 트래픽에서 UNIQUE 인덱스 조회는 캐시가 필요한 종류의 부하가 아니다. 트래픽이 실제로 문제가 되면 그때 TTL과 무효화를 함께 설계한다.

D-5. 경로 키는 id가 아니라 slug

결정: FE 라우트 /links/{slug}, API /api/shortlinks/{slug}.

슬러그는 불변(§5.2)이고 사용자가 실제로 보고 부르는 식별자다. 핸드오프 본문은 /links/:id, 아트보드 캡션은 /links/9dwqr로 서로 달랐고 후자를 택했다.

전제: 슬러그 변경 기능을 만들지 않는다. 만드는 순간 이 결정이 무너지고 §3.1 영구 점유도 함께 무너진다.

D-6. 삭제는 소프트, 슬러그는 영구 점유

결정: UNIQUE(slug)를 삭제 여부와 무관하게 유지한다. "삭제된 것 제외 부분 UNIQUE"를 쓰지 않는다.

기각한 반론 — "지운 링크의 예쁜 슬러그를 재활용하고 싶다": 예전에 그 주소를 받은 사람의 대화창에 주소가 영원히 남아 있다. 재활용은 그 사람을 예고 없이 다른 곳으로 보낸다.

D-7. 게이트웨이 404와 BE 404는 같은 화면이어야 한다

결정: 문자셋 밖 요청은 Envoy directResponse가 처리하되, BE의 실패 화면과 같은 HTML을 심는다.

같은 문자열이 두 곳에 생기는 중복을 감수한다. 대안(모든 요청을 BE로 넘겨 화면을 한 곳에 두기)은 스캐너 트래픽을 애플리케이션까지 들이는 대가가 있다. 화면이 갈리면 그 차이 자체가 정보이므로(§7), 두 HTML이 어긋나지 않는지 테스트로 고정한다.

D-8. 진입 동선 변경을 여행 리허설 전에 끝낸다

상황: /select·Sidebar는 여행 워크스페이스도 지나간다. 여행 실사용 리허설(#1176)이 10/6–10/19, 기능 동결이 10/13이다.

검토한 안: (a) 링크 전체를 여행 이후로, (b) 기능은 지금 만들되 3분할 동선만 여행 후, (c) 전부 지금.

결정 (2026-08-23, 개발자): (c) 전부 지금. 대신 동선 변경(SL-020)은 리허설 시작(10/6) 전에 머지를 끝낸다는 조건을 붙인다. 리허설이 여행 변경과 링크 변경을 동시에 검증하는 상태로 들어가지 않게 한다.

리스크는 남아 있다 — 리허설 중 /select·사이드바에서 이상이 나오면 원인이 두 갈래가 된다. 그래서 이 두 화면의 변경은 한 PR에 묶어 되돌리기 쉽게 둔다.

D-9. 국가 판정은 MaxMind GeoLite2를 이미지에 내장한다 → 뒤집혔다: 국가를 판정하지 않는다

2026-08-24 정정(개발자 판단). GeoLite2를 들이지 않는다. MaxMind 계정도 라이선스 키도 만들지 않는다. #1241은 착수하지 않고 닫았다.

명세 §11의 「잘라낼 순서」 1번이 그대로 실행된 것이다 — 기기·국가(SL-019)가 가장 먼저 잘리는 항목이었다. 기기 판정은 User-Agent로 되므로 남았고, 잘린 것은 국가뿐이다.

지금 상태: shortlink_visit.country 컬럼과 집계 쿼리는 서 있고 값이 채워지지 않는다. GET /api/shortlinks/{slug}/stats의 countries는 항상 빈 배열이고, 상세 화면은 그 줄을 그리지 않는다. 나중에 국가가 정말 필요해지면 아래 원안이 그대로 출발점이 된다 — 그래서 지우지 않고 남긴다.

원안 (채택했다가 뒤집힌 기록)

상황: Cloudflare 제거(#456)로 CF-IPCountry를 잃었고, 현재 인프라에 국가를 아는 수단이 하나도 없다. SL-019는 수단을 새로 들여야 성립한다.

결정: com.maxmind.geoip2 + GeoLite2-Country DB(~9MB)를 이미지 빌드 시 다운로드해 COPY. 라이선스 키는 GitHub Actions 시크릿에만 두고 클러스터에 넣지 않는다. 갱신은 이미지 재빌드에 딸려 간다(별도 루프 없음).

기각: Envoy geoip 필터(같은 DB에 게이트웨이 복잡도만 추가) · 외부 GeoIP API(방문마다 유료 외부 호출 — ELOG-023에 정면으로 반한다) · 국가 포기(2026-08-23 전체 범위 채택으로 기각).

받아들인 비용: 운영 부담이 하나 는다 — MaxMind 계정과 라이선스 키가 CI 시크릿으로 존재하고, 만료되면 이미지 빌드가 깨진다. 빌드 단계에서 다운로드 실패 시 명확히 실패하게 만든다(조용히 DB 없이 빌드되면 국가가 전부 NULL이 되고 아무도 모른다).

이 비용이 뒤집기의 이유가 됐다. 참고치 하나를 위해 외부 계정·키·빌드 의존을 늘리는 것이 단일 사용자 규모에서 남는 장사가 아니었다.

D-10. 비밀번호 보호는 404 단일 원칙의 명시적 예외다

상황: 확인 화면이 뜨는 순간 "이 슬러그는 존재한다"가 드러나 §7이 부분적으로 깨진다.

결정 (2026-08-23, 개발자): 1차 범위에 포함한다. 조건:

  • 기본 꺼짐. 사용자가 켠 소수 링크에서만 성질이 달라진다
  • 슬러그당 분당 10회 시도 제한
  • 실패 사유를 나누지 않는다
  • 세션·쿠키를 만들지 않는다 — 통과해도 다음 방문에 다시 입력. 인증 표면을 늘리지 않기 위해 불편을 택한다
  • 이 예외를 명세 §10에 못박아 둔다. 나중에 "왜 여기만 다르지"가 나오면 이 항목이 답이다

D-11. OG 프리뷰는 방어가 전제 조건이다

결정: SSRF 방어(아키텍처 §5) 없이는 켜지 않는다. 방어를 같은 PR에 넣는다 — "일단 붙이고 방어는 다음에"가 되면 그 사이에 내부망 스캐너가 열려 있다.

핵심은 DNS 해석 결과로 판정하고, 해석한 IP로 직접 연결하는 것이다. 호스트명 문자열 검사만으로는 DNS 재바인딩을 막지 못한다.

받아들인 비용: 이 방어 때문에 정상 URL 일부가 프리뷰에 실패할 수 있다. 명세 §4.4대로 실패가 발급을 막지 않으므로 사용자에게는 프리뷰가 안 뜨는 정도로 보인다.

D-12. 원시와 집계를 방문 시점에 함께 쓴다

결정: shortlink_visit INSERT + shortlink_visit_daily UPSERT를 한 번에. 야간 집계 배치를 만들지 않는다.

이득: 주기 작업이 하나 준다(90일 정리만 남는다). 원시가 사라져도 일별 그래프가 영구히 남는다. 대가: 방문 경로에서 쓰기가 둘이 된다. 어차피 비동기이고 302를 막지 않으므로 감수한다(§6.5).

D-13. 서명된 목적지에는 방문 쿼리를 전달하지 않는다

결정: 목적지에 X-Amz-Signature 등 서명 파라미터가 있으면 방문 쿼리를 버린다.

가장 자주 단축할 대상이 MinIO presigned URL인데, 파라미터가 하나만 더 붙어도 SignatureDoesNotMatch가 난다. 가장 중요한 유스케이스가 조용히 깨지는 것보다, 드문 쿼리 전달을 포기하는 편이 낫다.

열린 항목

# 항목 언제 정하나
O-1 QR 라이브러리 선정(번들 크기 · PNG 품질 · 라이선스) FE 발급 화면 착수 시
O-2 봇 UA 목록의 유지 주체 — 새 메신저가 나오면 누가 추가하나 실사용에서 오탐이 보일 때
O-3 링크가 수천 건이 되면 목록 LIKE %…% 검색을 바꿀지 실제로 느려지면
O-4 s.orino.dev 외 커스텀 도메인 범위 밖(PRD §14.6). 필요가 확인되면
O-5 통계 CSV 내보내기 〃

Clone this wiki locally