Folly Code Review · 73/89

folly::Uri — URL 파서

2026년 6월 8일 · Hawk · 4분 읽기

한 줄 요약: folly::Uri는 RFC 3986 기반 URL 파서다. C++ 표준에는 URL 파서가 없어 fbcode·외부 모두 같은 빈자리를 채우는 도구가 필요했다.

#동기

C++ 표준 라이브러리에는 URL 파서가 없다. WHATWG URL Spec 구현은 옵션이지만 모든 라이브러리가 fbcode 패턴(scheme://user:pass@host:port/path?query#fragment)을 정확히 다뤄야 한다.

매번 strtok나 regex로 짜는 건 위험하다. percent-encoding, IPv6 bracket, IDN, default port 같은 함정이 많다. Boost.URL도 비교적 최근(2022). Folly는 일찍 자체 파서를 만들어 fbcode 내부 RPC client·log 전체가 사용한다.

1
folly::Uri u("https://user:pw@api.example.com:8080/v1/items?id=42#section");
2

3
u.scheme();    // "https"
4
u.username();  // "user"
5
u.password();  // "pw"
6
u.host();      // "api.example.com"
7
u.port();      // 8080
8
u.path();      // "/v1/items"
9
u.query();     // "id=42"
10
u.fragment();  // "section"

#API

1
#include <folly/Uri.h>
2

3
folly::Uri u("https://example.com/path?a=1&b=2");
4

5
u.scheme();              // "https"
6
u.host();                // "example.com"
7
u.path();                // "/path"
8
u.query();               // "a=1&b=2"
9

10
// query parameter 분해
11
auto params = u.getQueryParams();
12
// std::vector<std::pair<std::string, std::string>>
13
//   { {"a", "1"}, {"b", "2"} }
14

15
// authority 재조립
16
u.authority();           // "example.com"
17

18
// 전체 재조립
19
u.toString();            // "https://example.com/path?a=1&b=2"

URI parsing은 생성자에서 일어난다. 잘못된 URI면 std::invalid_argument throw.

1
try {
2
  folly::Uri u("not a valid url");
3
} catch (const std::invalid_argument& e) {
4
  LOG(ERROR) << e.what();
5
}

#Query string 처리

1
folly::Uri u("https://api/search?q=hello+world&limit=10&page=1");
2

3
auto params = u.getQueryParams();
4
for (const auto& [k, v] : params) {
5
  std::cout << k << " = " << v << "\n";
6
}
7
// q = hello world      ← + 가 space로 변환됨
8
// limit = 10
9
// page = 1

+/%20 → space, %XX percent-encoding 처리가 표준대로. 잘못된 encoding은 ignore 또는 verbatim 보존 (구현 정책).

#직접 query 조작

1
folly::Uri u("https://api/search");
2
u.setQuery("q=foo&limit=20");
3
auto s = u.toString();   // "https://api/search?q=foo&limit=20"

setter도 있다. 단 setter 호출 후 내부 파싱이 다시 일어나야 일관성이 유지된다.

#내부 구현 — 정규식

1
// folly/Uri.cpp 약식
2
const boost::regex uriRegex(
3
  "([a-zA-Z][a-zA-Z0-9+.-]*):"          // scheme
4
  "(?://"                                // ://
5
    "(?:([^@/?#]*)@)?"                   // userinfo
6
    "([^:/?#]+)"                         // host
7
    "(?::(\\d+))?"                       // port
8
  ")?"
9
  "([^?#]*)"                              // path
10
  "(?:\\?([^#]*))?"                       // query
11
  "(?:#(.*))?"                            // fragment
12
);
13

14
Uri::Uri(folly::StringPiece s) {
15
  boost::cmatch m;
16
  if (!boost::regex_match(s.begin(), s.end(), m, uriRegex)) {
17
    throw std::invalid_argument("invalid URI");
18
  }
19
  scheme_   = m[1];
20
  username_ = ...;   // userinfo split
21
  host_     = m[3];
22
  port_     = m[4].matched ? std::stoi(m[4]) : 0;
23
  path_     = m[5];
24
  query_    = m[6];
25
  fragment_ = m[7];
26
}

내부적으로 boost::regex(또는 std::regex)로 한 번에 파싱. RFC 3986의 grammar가 거의 그대로 regex가 된다. percent-decode는 별도 단계.

성능이 critical하면 hand-rolled parser가 낫지만 fbcode use case는 RPC URL 한 번 파싱이라 regex로 충분.

#RFC 3986과의 충실도

1
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
2
hier-part = "//" authority path-abempty
3
          / path-absolute
4
          / path-rootless
5
          / path-empty
6
authority = [ userinfo "@" ] host [ ":" port ]

folly는 위 grammar 대부분을 다룬다. 단 다음은 완벽하진 않다.

IPv6 host with bracket — [::1]:8080 형태 — 지원하나 일부 corner case가 다를 수 있음.
IDN (international domain) — punycode 변환은 안 함. raw 문자열로 보관.
Percent-decoding — query에서는 한다. path는 raw 보관(decode는 호출자 책임).
Relative URI 해석 — base URI에 대한 resolution은 별도 API 필요.

WHATWG URL Spec(브라우저용)과는 다른 RFC 3986 grammar 기반. 브라우저용 URL을 완벽히 처리해야 한다면 별도 라이브러리(Boost.URL, ada-url 등).

#std와의 비교

항목	표준	folly::Uri	Boost.URL	ada-url
C++ 표준	없음	folly 내부	Boost 1.81+	외부
RFC 3986	N/A	거의 충실	충실	충실
WHATWG URL	N/A	부분	부분	완전
IDN punycode	N/A	안 함	안 함	함
성능	N/A	regex 기반 (보통)	hand-rolled (빠름)	SIMD (가장 빠름)
의존성	N/A	folly	boost	없음

fbcode 내부 RPC는 percent-encoded ASCII 위주라 folly::Uri로 충분. 브라우저 fidelity가 필요하면 ada-url.

#코드 리뷰 포인트

입력 URL의 신뢰성 — 사용자 입력이면 catch std::invalid_argument 필수.
port()가 0을 반환하면 URI에 port가 없다는 뜻 (default port resolution은 호출자).
query parameter가 순서를 유지해야 하면 getQueryParams()(vector<pair>) 사용. unordered map 변환은 정보 손실.
path가 percent-encoded인 채로 반환됨 — 사용 전 decode 필요할 수 있다.
HTTPS/HTTP 같은 scheme 비교는 case-insensitive (RFC). 직접 == 비교 전 lower-case 정규화.

#자주 보는 안티패턴

1
// 1. regex로 직접 URL 파싱
2
std::regex r(R"(^(https?)://([^/]+))");
3
// → 표준 도구로 percent-encoding/IPv6 처리 누락 가능
4

5
// 2. port 비교 없이 host만 비교
6
if (u.host() == "api.example.com") { ... }
7
// → 같은 host의 다른 port가 다른 서비스일 수 있음
8

9
// 3. percent-encoded path 직접 file system에 사용
10
auto path = u.path();
11
std::ifstream f(path);   // %20 같은 인코딩이 그대로 들어감
12

13
// 4. setter 후 내부 일관성 무시
14
folly::Uri u("https://a/p");
15
u.setHost("[::1");   // 잘못된 IPv6 — setter가 throw하지 않을 수 있음

#실전 예 — RPC client URL 처리

1
folly::Uri ParseEndpoint(const std::string& raw) {
2
  folly::Uri u(raw);   // throw if invalid
3

4
  if (u.scheme() != "http" && u.scheme() != "https") {
5
    throw std::invalid_argument("unsupported scheme: " + u.scheme().str());
6
  }
7

8
  if (u.host().empty()) {
9
    throw std::invalid_argument("missing host");
10
  }
11

12
  // default port
13
  if (u.port() == 0) {
14
    u_port = (u.scheme() == "https") ? 443 : 80;
15
  }
16

17
  return u;
18
}