ADR-0043: 공유 링크는 문서 전체를 압축해 URL의 fragment에 담는다

이후 변경

  • 2026-11-21: 공유 링크(와 그 안의 봉투 {"name", "model"}, 모델 JSON)를 붙여넣어서도 연다(R-WEB-11). 붙여넣은 링크는 주소 https://ariadnensd.com/#ns1.(또는 지금 페이지의 주소)로 알아보고, 열기는 이 ADR의 검증(길이 · 크기 한도, parseModel)을 그대로 거친다. 다만 보기 모드가 아니라 편집할 수 있는 새 문서로 연다 → 3.2 붙여넣은 문서, JP1

배경

공유 URL(R-WEB-05)은 다이어그램 전체를 URL에 담아 링크만으로 열게 한다. 웹은 서버가 없는 정적 사이트다(R-WEB-01). 그래서 링크가 문서 그 자체여야 하고, 그 형식은 한번 퍼지면 오래 남는다: 남이 받은 링크는 몇 해 뒤의 버전에서도 열려야 한다. 링크는 누구나 만들 수 있으므로 믿을 수 없는 입력이다. 메인테이너는 2026-11-03에 “나의 선택이 필요한 부분은 일단 달님의 추천안을 수용하겠습니다”라고 했고, 이 ADR은 Claude의 추천안이고, 메인테이너가 꾸림 u를 더한 뒤 2026-11-10에 승인했다.

결정 기준

  • 서버 없이 연다. 링크의 내용이 서버 로그나 리퍼러로 새지 않는다.
  • 짧다. 채팅 · 메일 · 이슈에 붙여 넣어 잘리지 않는 길이에 보통 문서가 들어간다.
  • 번들이 커지지 않는다(QA-09의 첫 방문 크기 한도).
  • 뒤의 버전이 앞의 링크를 연다. 형식이 바뀌어도 링크가 스스로 무엇인지 밝힌다.
  • 파일과 같은 검증을 거친다. 깨진 링크, 아주 큰 링크, 작은 링크가 크게 풀리는 것(zip bomb)에 버틴다.

검토한 대안

대안 A: query(?doc=…)

  • 장점: 서버가 읽을 수 있어 나중에 미리보기 카드(Open Graph)를 만들 수 있다.
  • 단점: 문서가 GitHub Pages의 접근 로그와 다른 사이트로 가는 리퍼러에 실린다. 정적 사이트는 그것을 쓰지 않으니 얻는 것 없이 새기만 한다.

대안 B: fragment(#…)

  • 장점: 브라우저가 서버에 보내지 않는다. 페이지를 다시 받지 않고 바꿀 수 있다(같은 탭에 붙여 넣으면 hashchange).
  • 단점: 서버 쪽 미리보기는 만들 수 없다.

압축: deflate-raw(브라우저 내장) / LZ-string / fflate / 압축 없음

  • 브라우저의 CompressionStream('deflate-raw')는 Chrome 103 · Firefox 113 · Safari 16.4부터 있고 번들에 아무것도 더하지 않는다. 모델 JSON(들여쓰기를 뺀 것)은 대개 1/5 ~ 1/8로 준다.
  • LZ-string은 URL용 글자로 바로 내지만 deflate보다 덜 줄고 라이브러리가 하나 는다. fflate는 이미 fonts에 있으나(서브셋 글꼴의 WOFF) 웹의 첫 다운로드에 수 KB가 더해진다.
  • 압축 없음은 링크가 몇 배 길어진다.

글자: base64url / 더 촘촘한 글자 집합

  • base64url(RFC 4648 5절, 패딩 없음)은 URL에서 이스케이프되지 않는 글자만 쓰고 어디서나 읽힌다. 더 많은 글자를 쓰는 인코딩은 몇 % 짧지만 앱마다 링크를 자르는 글자가 달라 위험하다.

결정

링크는 https://ariadnensd.com/#ns1.d.<내용>이다.

  • 자리: URL의 fragment. 페이지 주소(origin + pathname, query는 뺌) 뒤에 #과 함께 붙는다.
  • 머리: ns1.은 공유 링크 형식의 이름과 버전이다. 형식을 바꾸면 ns2.로 올리고, 이 버전은 ns + 숫자로 시작하지만 모르는 버전을 “더 새 버전이 만든 링크”로 알린다. ns로 시작하지 않는 fragment는 공유 링크가 아니다(페이지가 평소처럼 연다).
  • 꾸림 한 글자: d는 deflate-raw, j는 압축 없음(CompressionStream이 없는 브라우저가 만든 링크), u는 봉투 JSON을 encodeURIComponent로 퍼센트 인코딩한 것(다른 AI가 손으로 쓰는 링크, 2026-11-10 → 아래). 읽는 쪽은 셋 다 연다. 앱이 만드는 것은 d(또는 j)뿐이다. d를 풀 수 없는 브라우저는 그렇다고 알린다.
  • 내용: UTF-8 JSON {"name": "…", "model": {…}}을 꾸린 바이트의 base64url(u는 그 JSON의 퍼센트 인코딩). model은 파일의 모델 JSON(01-file-format) 그대로이며 뷰 상태(접힘 등)도 들어 있다. 모델의 버전 규칙(옮기기, 더 새 버전 거절)은 파일과 같다. 그림(SVG)과 글꼴은 넣지 않는다. 받는 쪽이 같은 렌더러로 다시 그린다. 이름은 문서의 파일 이름(정렬.ns.svg)이다.
  • 검증: 링크의 길이가 1 MB(1,048,576자)를 넘으면 풀지 않는다. u는 풀린 글이 링크보다 길 수 없어 이 한도가 크기 한도다. 풀 때는 스트림으로 읽어 16 MB를 넘는 순간 멈춘다. JSON 봉투는 name(문자열)과 model 두 키만 받는다. model은 파일을 열 때와 같은 검증 파서(parseModel)를 거친다. 이름은 파일 이름 규칙(documentFileName)으로 다듬는다.
  • 만드는 쪽의 한도: 1 MB를 넘는 링크는 만들지 않고, 8 KB를 넘으면 경고와 함께 복사한다(조작과 문구 → SH2).

2026-11-10: 손으로 쓰는 꾸림 u

다른 AI(채팅 LLM)가 사용자에게 공유 링크를 만들어 주게 하려면(R-WEB-10), 코드 없이도 만들 수 있는 꾸림이 필요하다. d는 deflate가 있어야 하고, j(base64)는 손으로 하면 한 글자만 틀려도 뒤가 모두 깨진다. 시안 M56의 실험에서 haiku · sonnet · opus는 안내서만 보고 u 링크를 만들었고 그 대부분(20번 가운데 18번)이 열렸다. 그래서 u를 읽기만 더한다. 압축이 없어 zip bomb의 걱정이 없고, 길이 한도 · parseModel의 검증은 다른 꾸림과 같다. 공유 링크 복사는 여전히 d를 만든다. u는 2 ~ 3배 길어 사람끼리의 공유에는 맞지 않기 때문이다. 견준 것(파일만, 짧은 글 DSL, 공유 링크 복사가 u를 만듦)과 실험 → LG2, LG5, 안내서 → 3.1 LLM · 에이전트를 위한 안내서

결과

  • 좋아지는 점: 서버도 라이브러리도 없이 공유한다(번들 크기 그대로, 첫 다운로드 +1 KB 남짓은 셸의 코드). 링크의 내용이 서버로 가지 않는다. 링크가 자기 형식의 버전을 밝혀, 뒤의 버전이 앞의 링크를 읽거나 왜 못 읽는지 말할 수 있다. 파일과 같은 파서를 거쳐 깨진 링크가 편집기를 넘어뜨리지 않는다.
  • 감수하는 점: 링크는 문서보다 오래 남는다. ns1과 모델 JSON의 버전 1을 읽는 코드를 계속 두어야 한다. 링크를 가진 사람은 누구나 내용을 본다(비밀은 링크로 보내지 않는다는 것을 사용법에 적는다). 큰 다이어그램은 링크가 길어져 파일로 나눠야 한다. 서버 쪽 미리보기 카드는 없다.
  • u를 더하며(2026-11-10): 링크 형식의 버전(ns1)은 그대로다. 꾸림 한 글자를 더하는 것은 앞의 링크를 바꾸지 않기 때문이다. 다만 u를 읽기 전의 판은 u 링크를 “손상”으로 알린다.
  • 후속 작업: 링크 형식을 바꿀 때 앞 버전을 읽는 테스트를 남긴다(src/apps/web/src/files/share-link.test.ts). Claude skill(R-SKILL-01)이 공유 URL을 내놓을 때 이 형식을 쓴다.