Skip to content

Shortlink Spec

wcorn edited this page Aug 30, 2026 · 4 revisions

확정 명세: 단축 URL (링크) v1

제품 결정 정본. 다른 문서와 어긋나면 이 문서가 이긴다. § 번호는 인용 대상이므로 재배치하지 않는다(내용이 폐기되면 취소선으로 남긴다).

PRD §14 · 유스케이스 · 아키텍처 · 데이터 모델 · API · 화면 · 결정 기록

0. 이 문서를 만든 경위 — 그리고 디자인 핸드오프의 § 번호에 대하여

이 모듈은 화면 설계가 먼저 왔다. 2026-08-23 디자인 핸드오프(design_handoff_shortlink)가 hifi 수준의 화면·인터랙션·토큰 대응표를 들고 도착했는데, 그 문서가 근거로 인용하는 PRD §12.2 · §12.7 · §12.8 · §12.11 · §12.12 · §12.16.4는 orino Wiki에 존재하지 않는다. 실제 PRD에서 §12는 모듈 8 일상기록이고 모듈 로드맵은 여행에서 끝나 있었다.

즉 화면은 문서화된 적 없는 제품 결정을 이미 전제하고 있었다. 이 명세는 그 전제를 역으로 세워 정본으로 만든 것이다. 핸드오프의 옛 번호는 아래로 대응한다.

핸드오프 인용 실제 위치
PRD §12.2 (서비스 정의) PRD §14.2
PRD §12.7 SL-020 (일상 사이드바 「링크」) 폐기. §9로 대체 — 독립 워크스페이스
PRD §12.8 (17자 고정) §3
PRD §12.11 (통계·프라이버시 D4) §8
PRD §12.12 (모바일 발급 · 리다이렉트 독립성) §5.4 · §6.1
PRD §12.16.4 (404 단일) §7

1. 한 문장

한 번 뿌린 주소를 죽지 않게 만든다 — 주소는 영구히 고정하고, 뒤의 목적지만 갈아끼운다.

2. 무엇이 아닌가

  • 마케팅 도구가 아니다. UTM·A/B·전환 추적은 범위 밖이다(PRD §14.6)
  • 공유 서비스가 아니다. 만드는 사람은 1인이고, 받는 사람에게 계정이 생기지 않는다
  • 통계 제품이 아니다. 통계는 "그 링크가 쓰였나"를 가늠하는 참고치이고, 정확도를 위해 프라이버시를 팔지 않는다(§8)

3. 주소 형식 — 17자 고정

s.orino.dev/ab3k9
└─────11────┘│└─5─┘   = 17자
             └ /
  • 경로 세그먼트를 추가하지 않는다. /s/, /l/, /go/ 전부 금지. 내부 라우팅에서 접두어가 필요하면 게이트웨이에서 재작성하고 공개 주소는 건드리지 않는다(§6.2)
  • 슬러그 길이 5 (자동 발급). 커스텀 슬러그는 최대 32자까지 허용하되 17자 고정은 자동 발급 기준값이다
  • 문자셋 32자: abcdefghijkmnpqrstuvwxyz23456789 — 영소문자 + 숫자에서 0 o 1 l을 뺀다(입으로 부르거나 손으로 옮겨 적을 때 갈리는 글자)
  • 대문자로 들어온 슬러그는 소문자로 정규화해 조회한다. 새로 발급할 때도 소문자로만 저장한다
  • 공간: 32⁵ ≈ 3,355만. 단일 사용자 규모에서 충돌은 재시도 몇 번으로 끝난다(§4.2)

3.1 슬러그는 영구 점유된다

삭제한 링크의 슬러그를 다시 쓰지 않는다. 소프트 삭제로 행을 남기고 UNIQUE(slug)가 재사용을 구조적으로 막는다.

이유가 편의가 아니라 안전이다. 예전에 s.orino.dev/k7m2p를 받은 사람의 카카오톡 대화창에는 그 주소가 영원히 남아 있다. 같은 주소가 다른 목적지를 가리키게 되는 순간, 그 사람은 자기가 뭘 여는지 모른 채 엉뚱한 곳으로 간다.

4. 발급

4.1 기본 경로는 「붙여넣고 Enter」다 (SL-002)

목록 맨 위에 입력창 하나가 상주한다. URL을 붙여넣고 Enter → 발급 → 클립보드 자동 복사 → 토스트. 모달을 여는 것은 옵션(메모·태그·만료·비밀번호를 함께 넣을 때)이지 기본이 아니다.

발급이 3초를 넘으면 사람은 이 기능을 안 쓴다. 옵션을 늘리는 모든 요구는 이 3초와 겨뤄야 한다.

4.2 자동 슬러그 생성

암호학적 난수로 5자를 뽑아 INSERT를 시도하고, UNIQUE 위반이면 최대 5회 재시도한다. 순차 채번이나 카운터 인코딩을 쓰지 않는다 — 다음 슬러그를 추측할 수 있게 되면 §7의 전제가 무너진다.

4.3 목적지 검증 (SL-004)

  • 허용 스킴: http · https · mailto · tel. 그 외(javascript:, data:, file: 등)는 거부
  • 목적지 호스트가 s.orino.dev면 거부한다 — 자기 자신을 가리키는 링크는 루프다
  • 길이 상한 2048자
  • 도달 가능성은 검사하지 않는다. 지금 죽어 있는 URL도 발급된다(나중에 갈아끼우면 되니까)

4.4 OG 프리뷰는 발급을 막지 않는다 (SL-005)

프리뷰는 비동기로 뒤따라 채운다. 느리거나 실패해도 만들기는 항상 눌린다. 화면에도 그렇게 적는다 — 프리뷰는 확인용이에요. 못 읽어도 발급은 막지 않습니다.

프리뷰 fetch의 SSRF 방어는 아키텍처 §5에서 다룬다. 방어 없이 이 기능을 켜지 않는다.

5. 관리

5.1 목적지 교체 (SL-008) — 이 모듈의 핵심

주소를 고정한 채 목적지만 바꾼다. 교체할 때마다 이력 한 줄(목적지 URL · 시각 · 사유)을 남기고, 상세 화면에서 시간 역순으로 보여준다. 최초 발급도 이력의 첫 줄이다.

화면에 이유를 적어 둔다 — 주소는 그대로 두고 목적지만 갈아끼웁니다. 이미 뿌린 링크가 전부 살아납니다.

5.2 슬러그는 바꿀 수 없다

편집으로 메모·태그·만료·비밀번호·목적지는 바꾸지만 슬러그는 못 바꾼다. 바꿀 수 있으면 §3.1의 영구 점유가 무의미해지고(옛 슬러그가 비므로), 이미 뿌린 주소가 죽는다. 다른 주소를 원하면 새로 발급한다.

그래서 슬러그는 불변 키다. 관리 화면 라우트와 API 경로 키를 id가 아니라 slug로 쓴다(결정 기록 D-5).

5.3 비활성 · 만료 · 삭제

상태 방문 결과 관리 화면 되돌릴 수 있나
활성 302 정상 —
비활성(꺼짐) §7 실패 흐리게 + 꺼짐 배지 예
만료 §7 실패 흐리게 + 만료 배지 만료일을 미루면 예
삭제 §7 실패 목록에서 사라짐 아니오(슬러그는 영구 점유)

방문자 입장에서는 넷이 전부 똑같이 보인다. 구분은 관리 화면에만 있다.

5.4 모바일 발급이 이 모듈의 성패다

링크를 만드는 순간은 대개 폰에서 뭔가를 보내려던 순간이다. 데스크탑 화면을 먼저 만들고 모바일을 축약하는 방식으로 접근하지 않는다 — 빠른 발급 바는 모바일에서도 제목 바로 아래 상주한다(화면 §6).

6. 리다이렉트

6.1 관리 화면과 독립이다

s.orino.dev/{slug}는 SPA를 거치지 않는다. 서버가 직접 302를 낸다. /links가 깨져도, FE 배포가 실패해도, 이미 뿌린 링크는 살아 있어야 한다.

6.2 공개 주소와 내부 경로를 분리한다

공개 주소는 s.orino.dev/{slug}(§3)이지만 백엔드 내부 경로는 /r/{slug}다. 게이트웨이에서 재작성한다.

  • BE 루트에 catch-all(/{slug})을 만들지 않는다 — 스웨거·정적 리소스·액추에이터와 충돌한다
  • 인증 예외 경로가 /r/** 하나로 좁혀진다. 공개 표면의 크기가 설정 한 줄로 보인다
  • 슬러그 문자셋에 안 맞는 요청은 BE에 닿기 전에 게이트웨이에서 걸러진다

6.3 응답 계약

항목 값 이유
상태 302 Found 301이면 브라우저가 캐시해 §5.1 목적지 교체가 먹지 않는다
Cache-Control no-store 같은 이유. 중간 캐시도 들고 있으면 안 된다
Referrer-Policy no-referrer 목적지 사이트가 유효한 슬러그를 알게 될 이유가 없다
인증 없음 —
본문 없음 —

6.4 쿼리스트링 전달

  1. 방문 요청에 쿼리가 없으면 목적지를 그대로 쓴다. ?를 새로 붙이지 않는다
  2. 방문 요청에 쿼리가 있으면 목적지 쿼리 뒤에 이어붙인다(? 또는 & 판단)
  3. 예외 — 목적지가 서명된 URL이면 방문 쿼리를 버린다. X-Amz-Signature·X-Goog-Signature·Signature 파라미터가 목적지에 있으면 무엇을 덧붙여도 서명 검증이 깨진다

이 규칙이 필요한 이유가 이 모듈의 출발점과 같다. 가장 자주 단축할 대상이 MinIO presigned URL이고, 거기에 파라미터 하나만 더 붙어도 목적지가 SignatureDoesNotMatch를 뱉는다.

프래그먼트(#...)는 서버에 오지 않는다. 브라우저가 알아서 목적지에 이어 붙인다.

6.5 통계 기록은 리다이렉트를 막지 않는다

방문 기록은 비동기다. DB가 느리거나 죽어도 302는 정상적으로 나간다. 통계를 잃는 것과 링크가 죽는 것은 비교 대상이 아니다.

7. 실패 — 404 하나

이 화면이 orino의 유일한 공개 표면이다. 기준은 「정보를 주지 않는 것」이다.

  • 없음 · 꺼짐 · 만료 · 삭제를 구분하지 않는다
  • 문구 하나: 이 링크는 사용할 수 없습니다
  • HTTP 상태도 404 하나. 410(Gone)을 쓰지 않는다 — 410은 "예전엔 있었다"를 알려준다
  • 목적지·메모·생성 시각·계정 정보 노출 금지
  • 로그인 유도 금지, 재시도·검색 UI 금지
  • 브랜드 마크 + 한 줄 외에 아무것도 두지 않는다

이 화면도 §6.1대로 리다이렉트 쪽에서 서버 렌더한다. 다크/라이트는 prefers-color-scheme으로만 대응한다(FE 번들·테마 컨텍스트에 의존하지 않는다).

7.1 열거에 대하여

슬러그 공간은 33,554,432다(32⁵ — 알파벳 32자 × AUTO_LENGTH 5). 게이트웨이 rate limit이 걸린다(아키텍처 §6).

2026-08-31 정정. 이 항목은 「전수 탐색은 현실적이지 않다」고 적고 있었다. 나눗셈이 틀렸다.

33,554,432 ÷ 300/분 = 111,848분 ≈ 78일

게다가 rate limit 버킷은 route마다 따로이고(applyTo: HTTP_ROUTE) 게이트웨이 파드도 2개라, 열거에 쓰이는 GET route는 실제로 분당 600을 쓸 수 있다 — 약 39일이다. 200년이 아니다(#1299 · ELOG-014).

2026-08-31 갱신 — IP별 버킷이 되었다(#1301).

remote_address descriptor로 IP마다 버킷이 생긴다. 한 IP가 쓸 수 있는 것은 분당 300이므로,

33,554,432 ÷ 300/분 = 111,848분 ≈ 78일   (IP 하나로 계속 붙어 있을 때)

분산시키면 여전히 빨라지지만 IP 수만큼 비용이 든다. 목표는 「막는다」가 아니라 **「한 대가 전체를 먹지 못하게 한다」**이고, 그건 달성됐다.

그래도 rate limit을 열거 방어의 본체로 세지 않는다. IP를 돌리면 뚫리고, 그때는 이 방식으로 막을 수 없다.

방어의 본체는 응답이 아무것도 알려주지 않는다는 것이다(§7). rate limit은 「한 대가 독점하지 못하게」 하는 보조다.

공개 단축링크는 원래 URL을 아는 사람이면 누구나 연다. 열거로 드러나는 것은 「알리지 않은 링크의 존재」이고, 링크 뒤의 내용을 지키는 것은 비밀번호 보호(§10)다.

8. 통계 — 참고치이고, 프라이버시를 팔지 않는다

8.1 무엇을 남기나

남긴다 남기지 않는다
방문 시각 IP 주소 — 컬럼 자체를 두지 않는다
리퍼러 도메인까지만 (kakaotalk / mail.google.com) 전체 리퍼러 URL(경로·쿼리)
기기 구분(모바일/데스크탑/태블릿) User-Agent 원문
국가 코드 2자 — 판정하지 않는다(2026-08-24, D-9). 컬럼은 있고 값은 비어 있다 도시·좌표
봇 여부 방문자 식별자·쿠키

리퍼러는 저장하는 시점에 도메인으로 잘라서 넣는다. 원시 테이블에도 전체 URL이 들어가지 않는다 — "나중에 필요할지 모르니 일단 저장"이 프라이버시 원칙이 무너지는 전형적인 경로다.

국가는 IP로 판정하되 판정 직후 IP를 버린다. 판정 수단은 아키텍처 §4.

2026-08-24 정정: 국가를 판정하지 않는다(D-9). 판정 수단(GeoLite2)을 들이지 않기로 했고, 그 결과 IP를 읽는 코드 자체가 없다. §8.1의 "IP를 저장하지 않는다"는 더 강해졌다 — 저장하지 않는 것이 아니라 읽지 않는다.

8.2 봇·프리뷰는 따로 센다 (SL-017)

카카오톡·슬랙·디스코드에 링크를 붙이면 사람이 누르기 전에 프리뷰 봇이 먼저 연다. 이걸 같이 세면 방문 수가 실제의 몇 배가 된다.

  • 봇 판정은 User-Agent 기반이고 완벽하지 않다
  • 그래서 화면에 그대로 적는다 — 봇·프리뷰 18건은 따로 셉니다 — 통계는 참고치
  • 봇에게도 리다이렉트는 정상으로 내준다. 프리뷰 카드가 떠야 하니까

8.3 보존 (SL-022)

  • 원시 방문 90일. 이후 삭제
  • 일별 집계는 영구. 방문 시점에 원시 INSERT와 함께 일별 카운터를 갱신하므로, 원시를 지워도 일별 막대 그래프는 남는다
  • 90일이 지나면 유입 경로·기기·국가는 사라지고 총 방문·일별 추이만 남는다. 화면 기본 범위가 30일이라 실사용에서 이 경계는 잘 보이지 않는다

9. 진입 — 세 번째 워크스페이스 (SL-020)

로그인 → /select가 여행 · 일상 · 링크 3카드가 된다. 사이드바 최상단 전환도 3분할.

  • 링크는 일상의 하위 메뉴가 아니다. "일상 사이드바에 「링크」 항목을 넣는다" 는 폐기한다
  • 일상 사이드바는 손대지 않는다 — 원래 링크 항목이 없었으므로 뺄 것도 없다
  • 여행 워크스페이스의 범위는 변경 없다

근거: 링크는 일상 화면들과 데이터도 흐름도 공유하지 않고, 진입 빈도는 높지만 체류가 짧다(발급 3초). 하위 메뉴로 넣으면 두 번 들어가야 한다. 결정 기록 D-1.

10. 비밀번호 보호 (SL-014) — §7의 예외

이 기능은 §7 「구분하지 않는다」 원칙을 부분적으로 깬다. 알고 켠다.

비밀번호 링크를 열면 확인 화면이 뜨고, 그 순간 "이 슬러그는 존재한다"가 드러난다. 없는 슬러그는 여전히 404이므로, 방문자는 둘을 구분할 수 있게 된다.

이 예외를 감수하는 이유와 조건:

  • 비밀번호는 기본 꺼짐이고, 켠 링크에만 적용된다. 전체 표면이 아니라 사용자가 명시적으로 만든 소수의 링크에서만 성질이 달라진다
  • 그 대가로 얻는 것은 잘못 퍼진 링크를 사후에 막는 수단이다. 비활성으로 끄면 아는 사람도 못 들어가지만, 비밀번호는 아는 사람만 통과시킨다
  • 완화: 슬러그당 분당 10회 시도 제한. 틀렸을 때 이유를 나누지 않는다(없는 비밀번호·틀린 비밀번호 구분 없음)
  • 세션·쿠키를 두지 않는다. 통과해도 다음 방문에 다시 입력한다. 인증 표면을 만들지 않기 위해 불편을 택한다

확인 화면도 §7과 같이 서버 렌더다.

11. 잘라낼 순서 (일정이 밀릴 경우 위에서부터)

기기·국가(SL-019) → 유입 경로(SL-016) → OG 프리뷰(SL-005) → 비밀번호(SL-014) → 즐겨찾기(SL-011) → 만료(SL-007)

실제로 잘린 것은 「국가」 하나다(2026-08-24). 기기 판정은 User-Agent로 되므로 남았고, 그 뒤 항목(유입 경로 · OG 프리뷰 · 비밀번호)은 전부 구현했다.

절대 빼지 않는 것: 발급·리다이렉트(302 계약) · 목적지 교체와 이력 · 404 단일 실패 · 슬러그 영구 점유 · 세 번째 워크스페이스 진입

12. 완료 판정

  1. 폰에서 URL을 붙여넣고 Enter 한 번으로 짧은 주소가 클립보드에 들어왔다
  2. 그 주소를 남에게 보냈고, 다른 사람 기기에서 열렸다
  3. 목적지를 갈아끼운 뒤에도 같은 주소가 열렸다 — 이미 보낸 메시지를 고치지 않고
  4. 꺼진 링크·없는 링크·만료된 링크가 똑같은 화면, 똑같은 404로 끝났다
  5. 상세 화면의 방문 수가 봇을 뺀 값으로 보였고, 실제로 누른 횟수와 크게 어긋나지 않았다

Clone this wiki locally