llm-wiki/raw/company-tech-blogs/segment-ksuid.md

title, source_type, url, archive_url, related_branches, related_projects, tags, created

title	source_type	url	archive_url	related_branches	related_projects	tags	created
company-tech-blog / KSUID — K-Sortable Unique Identifier (Segment)	company-tech-blog	https://github.com/segmentio/ksuid		feature-resource-identifier-contract	ca-skeleton	company-tech-blog ca-skeleton api-design ksuid resource-identifier base62-encoding timestamp-leak	2026-05-31

KSUID — K-Sortable Unique Identifier (Segment)

Layer: raw/ — 외부 자료(대기업 기술 블로그 / 오픈소스 README)의 원문 발췌·출처 기록. Segment 가 설계·운영하는 KSUID(K-Sortable Unique IDentifier) Go 라이브러리의 공식 README. 검증된 요약은 /ingest 후 wiki/concepts/ 에 source-summary-template 형식으로 별도 작성. 원본은 raw 에 영구 보관.

Parent / 활용 branch

이 자료는 혼자 존재하지 않는다. feature-resource-identifier-contract branch 의 구현 결정 근거로서 보관됨.

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-resource-identifier-contract	D1 (resource ID default 형식) — KSUID 를 대안 후보로 평가하기 위한 설계 근거
raw/branch-notes/feature-resource-identifier-contract	D2 (charset/encoding) — base62 (대소문자 구분, case-sensitive) vs ULID base32 (case-insensitive) 트레이드오프
raw/branch-notes/feature-resource-identifier-contract	D7 (timestamp leak) — KSUID 의 32-bit 초 단위 timestamp 는 ULID/UUIDv7 의 밀리초 단위보다 정밀도가 낮아 시각 leak 위험이 상대적으로 낮음

출처 / Source

• 원본 URL: https://github.com/segmentio/ksuid
• 아카이브 URL: (미보관)
• 저자 / 조직: Segment (segmentio)
• 발행일: 미상 (레포 초기 커밋 기준 2017년경, 지속 관리 중)
• 마지막 확인일: 2026-05-31

왜 저장했는지 / Why archived

ca-skeleton 의 default resource ID 형식 결정(D1) 에서 KSUID 가 ULID / UUID v7 과 함께 주요 후보로 언급된다. KSUID 의 구조(20바이트, 32-bit 초 단위 timestamp + 128-bit 랜덤 payload, 27자 base62)는 D1/D2/D7 결정의 트레이드오프 분석에서 직접 인용할 근거가 된다. 특히 base62 (case-sensitive) vs base32 (case-insensitive) 의 charset 차이, 그리고 초 단위 timestamp 정밀도가 UUIDv7/ULID 의 밀리초 대비 timestamp leak 측면에서 어떤 의미를 갖는지 평가하기 위해 보관한다.

핵심 인용 / Key quotes (verbatim, 5문장)

[§What is a KSUID?] "KSUID is for K-Sortable Unique IDentifier. It is a kind of globally unique identifier similar to a RFC 4122 UUID, built from the ground-up to be "naturally" sorted by generation timestamp without any special type-aware logic."

[§How do KSUIDs work?] "Binary KSUIDs are 20-bytes: a 32-bit unsigned integer UTC timestamp and a 128-bit randomly generated payload. The timestamp uses big-endian encoding, to support lexicographic sorting. The timestamp epoch is adjusted to May 13th, 2014, providing over 100 years of life. The payload is generated by a cryptographically-strong pseudorandom number generator."

[§How do KSUIDs work?] "The text representation is always 27 characters, encoded in alphanumeric base62 that will lexicographically sort by timestamp."

[§3. Highly Portable Representations] "The text representation is an alphanumeric base62 encoding, so it "fits" anywhere alphanumeric strings are accepted. No delimiters are used, so stringified KSUIDs won't be inadvertently truncated or tokenized when interpreted by software that is designed for human-readable text, a common problem for the text representation of RFC 4122 UUIDs."

[§Battle Tested] "This code has been used in production at Segment for several years, across a diverse array of projects. Trillions upon trillions of KSUIDs have been generated in some of Segment's most performance-critical, large-scale distributed systems."

Claims Extracted / 추출된 주장

이 자료가 직접 말하는 것만 claim 으로 분리한다. 내 프로젝트에 적용한 결론은 여기 쓰지 않는다. Claim ID prefix: KSUID-C

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
KSUID-C1	KSUID 의 binary 구조는 20바이트(4바이트 32-bit UTC timestamp + 16바이트 128-bit 랜덤 payload)이며, timestamp 는 custom epoch(2014-05-13)을 기준으로 big-endian 인코딩된다	[§How do KSUIDs work?] "Binary KSUIDs are 20-bytes: a 32-bit unsigned integer UTC timestamp and a 128-bit randomly generated payload. The timestamp uses big-endian encoding, to support lexicographic sorting. The timestamp epoch is adjusted to May 13th, 2014, providing over 100 years of life."	company-case-study	KSUID 형식을 채택한 모든 언어 구현	Unix epoch 와의 차이로 인해 타 시스템의 timestamp 와 직접 비교 불가 (ksuid.New().Time() 변환 필요); 초 단위 정밀도가 밀리초 단위 ULID/UUIDv7 보다 시각 추론 위험이 낮음을 공식적으로 언급하지 않음
KSUID-C2	KSUID 의 text 표현은 항상 27자이며, alphanumeric base62 인코딩을 사용하고 lexicographic 정렬 시 timestamp 순으로 정렬된다	[§How do KSUIDs work?] "The text representation is always 27 characters, encoded in alphanumeric base62 that will lexicographically sort by timestamp."	company-case-study	KSUID 를 문자열로 저장·정렬하는 모든 시스템	base62 는 대소문자 구분(case-sensitive)임을 README 가 명시하지 않음 — case-insensitive 비교 시스템과의 호환성은 별도 검토 필요; URL 대소문자 normalize 정책(RFC 3986)과의 정합성은 이 자료만으로 증명 불가
KSUID-C3	KSUID 의 text 표현은 alphanumeric base62 이므로 alphanumeric 문자열을 허용하는 모든 시스템에서 delimiters 없이 사용 가능하며, RFC 4122 UUID 의 dash-delimited 형식이 야기하는 tokenize/truncate 문제를 방지한다	[§3. Highly Portable Representations] "The text representation is an alphanumeric base62 encoding, so it "fits" anywhere alphanumeric strings are accepted. No delimiters are used, so stringified KSUIDs won't be inadvertently truncated or tokenized when interpreted by software that is designed for human-readable text, a common problem for the text representation of RFC 4122 UUIDs."	company-case-study	alphanumeric 문자열 허용 API, DB, log 시스템	base62 가 RFC 3986 unreserved charset 에 완전히 속하는지는 이 자료만으로 증명 불가 (RFC 3986 §2.3 별도 확인 필요); URL path 에서의 case-sensitivity normalize 정책은 이 자료 범위 밖
KSUID-C4	KSUID 는 RFC 4122 UUIDv4 의 122-bit entropy 대비 128-bit payload + timestamp "bonus entropy" 를 포함하여 충돌 확률이 실용적으로 불가능한 수준이며, Snowflake ID 처럼 coordination 없이 독립적으로 생성 가능하다	[§2. Collision-free, Coordination-free, Dependency-free] "A KSUID includes 128 bits of pseudorandom data ("entropy"). This number space is 64 times larger than the 122 bits used by the well-accepted RFC 4122 UUIDv4 standard."	company-case-study	분산 생성 환경에서의 충돌 방지 필요 시	collision 확률의 수학적 증명은 아님; FastRander 사용 시 보안 강도 저하 가능성을 README 자체가 NOTE 로 경고
KSUID-C5	KSUID 는 Segment 의 production 환경에서 수 년간 수조 개(trillions upon trillions)가 생성된 battle-tested 구현체이다	[§Battle Tested] "This code has been used in production at Segment for several years, across a diverse array of projects. Trillions upon trillions of KSUIDs have been generated in some of Segment's most performance-critical, large-scale distributed systems."	company-case-study	Segment 의 대규모 분산 시스템 사례	Segment 외 타사 production 사례를 증명하지 않음; 다른 언어 구현체(Java, Python 등)의 동일 안정성을 보장하지 않음

Usage Boundaries / 적용 경계

• 이 자료가 직접 증명하는 것:

  • KSUID-C1: KSUID 의 물리적 구조 — 20바이트(4B timestamp + 16B payload), 32-bit 초 단위 정밀도, custom epoch(2014-05-13), big-endian
  • KSUID-C2: text 표현 27자, base62, lexicographic 정렬 보장
  • KSUID-C3: delimiter 없음, alphanumeric 문자열 수용 시스템과 호환, RFC 4122 UUID 의 tokenize 문제 없음
  • KSUID-C4: 128-bit payload, UUID v4 대비 64배 entropy, coordination-free 생성
  • KSUID-C5: Segment production 환경에서 수조 개 생성 이력

• 이 자료가 증명하지 않는 것:

  • KSUID 가 ULID / UUID v7 / NanoID / CUID2 보다 우월하다 — Segment 의 선택이 다른 프로젝트의 best practice 임을 의미하지 않음
  • base62 가 RFC 3986 unreserved charset(ALPHA / DIGIT / "-" / "." / "_" / "~")에 완전히 속하는지 — 대소문자 모두 포함하므로 URL path case-sensitivity 정책과의 정합성은 별도 확인 필요
  • 초 단위 timestamp 정밀도가 밀리초 단위 ULID/UUIDv7 대비 timestamp leak 위험을 공식적으로 감소시킨다는 주장 — 이는 branch 의 분석이며, 이 자료가 직접 말하지 않음
  • Java / Spring Boot 에서 KSUID 를 사용할 때의 라이브러리 호환성 (Go 레퍼런스 구현만 다룸)
  • GDPR / PII 관점에서 초 단위 timestamp 의 법적 안전성

• 내 프로젝트(ca-skeleton)에 적용하려면 추가 확인이 필요한 것:

  • Java 생태계의 KSUID 라이브러리 성숙도 — Go 가 reference implementation 이며 Java 구현은 서드파티 (github.com/ksuid/ksuid, ksuid-creator)
  • base62 대소문자와 Spring MVC path variable 의 case-sensitive matching 정합성
  • 27자 base62 의 PostgreSQL / MySQL 컬럼 타입 결정 (varchar(27)) 및 index 성능 (ULID 26자 대비 1자 더 길고 case-sensitive)
  • KSUID custom epoch(2014-05-13)와 timestamp 해석 시 Unix epoch 변환 필요 여부

메모 / Notes

• KSUID 의 timestamp 정밀도는 초(second) 단위 — ULID/UUIDv7 의 밀리초(millisecond) 대비 시각 추론의 정밀도가 낮다. 이는 D7(timestamp leak) 관점에서 유리하지만, 동일 초 내 단조 증가(monotonicity) 보장이 없다는 트레이드오프도 있다.
• Custom epoch(2014-05-13)은 Unix epoch(1970-01-01)이 아니므로, KSUID timestamp 를 직접 Unix time 으로 해석하면 오류. 라이브러리 API 를 통해서만 time 변환해야 함.
• base62 는 대소문자를 모두 사용 ([0-9A-Za-z] 62가지) — case-insensitive 데이터베이스 collation 이나 HTTP 헤더에서 expect-lowercase normalize 를 수행하는 환경에서는 소문자로 fold 될 위험 있음.
• ULID 는 oklog/ulid 의 OrNil 사례를 명시적으로 언급 ((panic) 주석) — KSUID 설계자가 ULID 를 인지하고 있음을 시사하나, ULID 와의 공식 비교표는 README 에 없음.
• Go 외 언어 구현체 다수 존재 (Python, Ruby, Java, Rust, .NET, Erlang, Zig) 하나 reference implementation 은 Go.

Related / 관련

• 같은 주제 다른 raw 자료 (예정):
  • raw/official-docs/ulid-spec.md — ULID 공식 spec (26자 base32, 밀리초 timestamp, case-insensitive)
  • raw/official-docs/rfc9562-uuid.md — UUID v4/v7 RFC (밀리초 timestamp, RFC 표준)
  • raw/official-docs/cuid2-spec.md — CUID2 (timestamp leak 없음, fingerprint 기반)
  • raw/official-docs/rfc3986-uri-generic-syntax.md — URL charset / case sensitivity 근거
• 이 자료를 인용한 wiki 요약: wiki/concepts/resource-identifier-format (생성 시)