fix(hono): 경로 정규화 미동작으로 동적 경로가 메트릭 라벨에 누적되던 문제 수정

[2-one-week]

문제

Hono 메트릭 미들웨어에서 경로 정규화(normalizePath)가 동작하지 않아, 동적 경로(예: /pfms/api/statements/prepaid-9900916908805/memo)의 ID가 정규화되지 않고 메트릭 path 라벨에 그대로 누적되었습니다. 그 결과 라벨 카디널리티가 무한 증가하여 prom-client 메모리/CPU가 우상향했습니다.

스크린샷의 /http://host/... 형태 라벨이 단서였습니다 — url.pathname이 아니라 url.href(scheme/host 포함)가 정규화에 들어가고 있었습니다.

원인

1. url.href 전달: Next.js 라우트 그룹핑에 전체 URL(url.href)을 넘겨 /http://host/... 형태의 비정규화 라벨 생성.
2. normalizePath 무시: next || normalizePath || default 의 || 체이닝에서 Next.js 그룹핑이 미매칭 시에도 비어있지 않은 값을 반환 → 사용자 normalizePath가 영원히 실행되지 않음.
3. prefix 이중부착: createNormalizedHonoRouterPath가 getHonoRouterPaths(app, prefix)로 prefix를 붙인 뒤 createPathTesters(paths, prefix)가 한 번 더 붙여(/prefix/prefix/...) 정규식 매칭이 깨짐.

변경

• metrics: Next.js 그룹핑에 url.href → url.pathname 전달.
• metrics: 사용자 normalizePath 우선 적용 + undefined 반환 시 Next.js 그룹핑 → 기본 정규화로 fall-through. (하이브리드 앱에서 "API 경로만 직접 정규화, 나머지는 Next.js에 위임" 가능)
• types: normalizePath 반환 타입을 string | undefined로 확장.
• router/utils: createNormalizedHonoRouterPath의 prefix 이중부착 버그 수정.

nextjs 기본값(true)은 유지했습니다 — Next.js 우선 사용처의 페이지 라우트 그룹핑 회귀를 막기 위함이며, fall-through 설계로 동일 문제를 해결합니다.

참고 (rollout)

이 변경은 minor 릴리스이며, 소비처(예: pfms-web)는 새 버전 반영 후 normalizePath/prefix 사용 패턴을 적용해야 정규화가 정상 동작합니다.

🤖 Generated with Claude Code

[npayfebot]

✅ Changeset detected

Latest commit: 4961157

@naverpay/prometheus-hono package have detected changes.

If no version change is needed, please add skip-detect-change to the label.

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@naverpay/prometheus-hono	✨ Minor

_{powered by: naverpay changeset detect-add actions}