fix(web-push): 정상 알림 클릭이 router base path 아래 경로를 연다 (06-01)

문제: Web Push 정상 클릭은 registry path를 origin 기준으로 풀었다
(`new URL(path, origin)`). 거절된 클릭은 이미 앱 루트(=
registration.scope = router base path)를 쓴다(06-09). 그래서
VITE_ROUTER_BASE_PATH=/app/ 배포에서 열린 창이 없으면 정상 클릭이
https://host/inbox, 즉 앱 밖을 열었다. registry에 /app/inbox를 넣으면
openWindow는 맞지만 같은 값이 handoff path로 페이지에 가서 router
basename과 겹친다. 어떤 registry 값으로도 두 경로를 함께 맞출 수
없었다.

고른 방법: registry path를 "base path를 뺀 앱 기준 경로"로 정하고,
클릭 어댑터가 앱 루트의 pathname(끝 / 제외)을 앞에 붙여 openWindow
대상을 만든다. handoff path는 registry 값 그대로 둔다. same-origin·
userinfo·hash 검사(safeTarget)는 그대로 거친다. 규칙은
WebPushNotificationDefinition.path 주석, appRootUrl 주석, 설계 8.5절에
적었다. 앱 루트가 origin 루트(기본값)면 결과가 전과 같다.

버린 대안: 리뷰가 적은 `new URL(path.slice(1), appRootUrl)`. 앱 루트가
/로 끝나지 않으면(`https://host/app`) 마지막 segment가 사라지고,
`/a:b` 같은 경로는 `a:b`가 scheme으로 읽혀 거절된다. pathname을 앞에
붙이면 두 경우 모두 의도대로 된다.

위험·한계:
- realtime 레시피 번들(web-push 포함) 40,879 -> 40,897 / 40,900 gzip
  B(+18 B, 여유 3 B). 예산은 그대로다. 다음 realtime·web-push 변경은
  예산 인상과 함께 와야 한다.
- 페이지가 handoff path를 basename 기준으로 쓰는지는 제품 코드 몫이라
  확인하지 않았다(템플릿에는 handoff 소비자가 없다).
- 실제 브라우저·푸시 서비스에서는 실행하지 않았다.

검증:
- RED: 새 테스트 "opens an accepted click's route under the base
  path"가 수정 전 openWindow 인자 `https://app.example.test/inbox`
  (기대 `https://app.example.test/app/inbox`)로 실패(1 failed | 19
  passed).
- GREEN: 같은 테스트가 통과하고, 열린 창에는 handoff path `/inbox`가
  간다. `node scripts/run-vitest.ts run tests/unit/web-push
  tests/unit/sub-path-deployment.test.ts
  tests/unit/service-worker-web-push-remediation.test.ts` -> 8파일
  82건 통과(web-push-worker-runtime 20건 포함).
- `npx tsc` app·test·service-worker -> 오류 0.
- `npx eslint <바꾼 ts 3개> --max-warnings=0` -> 통과.
- `node scripts/check-realtime-boundaries.ts` -> PASS,
  `node scripts/check-optional-recipes.ts` -> PASS(realtime
  40897/40900), `node scripts/verify-documentation-readiness.ts` ->
  PASS_SCOPED.

Refs: docs/reviews/2026-11-01-maturity-review/06-adapters-service-worker-push.md 06-01
This commit is contained in:
DongHyeonka
2026-11-01 22:49:38 +09:00
parent 5b3f5b0eb3
commit c67edd2557
4 changed files with 66 additions and 4 deletions
@@ -1547,6 +1547,11 @@ NotificationClickDataV1
-> authoritative notification/resource fetch
```
registry `path`는 router base path를 뺀 앱 기준 경로다. 정상 click은 그 경로를
같은 앱 루트 아래에서 연다(`/app/` + `/inbox` → `/app/inbox`). 열린 창에 보내는
handoff `path`는 registry 값 그대로(`/inbox`)라서 router basename과 겹치지
않는다(06-01).
route intent가 stale/unknown이면 안전한 notification inbox/home으로 이동한다.
notification action 자체에서 destructive 업무 mutation을 실행하려면 별도의
confirmed UI 또는 idempotent authorized server command 설계가 필요하다.
@@ -85,8 +85,9 @@ export function createNotificationClickAdapter(dependencies: Readonly<{
clients: WorkerClientsFacade;
origin: string;
/**
* 06-09. Where a refused click opens: the registration scope, which is the
* router base path. Defaults to the origin root; must be same-origin.
* The registration scope, which is the router base path. A refused click
* opens it (06-09) and an accepted click opens its registry path under it
* (06-01). Defaults to the origin root; must be same-origin.
*/
appRootUrl?: string;
now?: () => number;
@@ -114,6 +115,7 @@ export function createNotificationClickAdapter(dependencies: Readonly<{
throw new TypeError("Web Push click adapter configuration is invalid.");
}
const appRootUrl: string = parsedAppRootUrl;
const appBasePath = new URL(appRootUrl).pathname.replace(/\/$/u, "");
return Object.freeze({
handle(event) {
@@ -187,7 +189,8 @@ export function createNotificationClickAdapter(dependencies: Readonly<{
if (!path) {
return webPushFailure("CONTRACT_REJECTED", "NOTIFICATION_CLICK");
}
const target = safeTarget(origin, path);
// 06-01. The registry path is an app path; the handoff keeps it as is.
const target = safeTarget(origin, `${appBasePath}${path}`);
if (!target) {
return webPushFailure("CONTRACT_REJECTED", "NOTIFICATION_CLICK");
}
@@ -19,6 +19,7 @@ export type WebPushNotificationDefinition = Readonly<{
routeIntent: NotificationRouteIntentId;
title: string;
body: string;
/** App path, without the router base path (`/inbox`, not `/app/inbox`). */
path: string;
}>;
+54 -1
View File
@@ -7,7 +7,10 @@ import {
import { createPushAssociationFenceStore } from "../../src/adapters/web-push/push-association-fence-store.ts";
import { createWebPushNotificationRegistry } from "../../src/adapters/web-push/notification-registry.ts";
import { createPushEventAdapter } from "../../src/adapters/web-push/inbound/push-event-adapter.ts";
import { createNotificationClickAdapter } from "../../src/adapters/web-push/inbound/notification-click-adapter.ts";
import {
createNotificationClickAdapter,
type WindowClientFacade,
} from "../../src/adapters/web-push/inbound/notification-click-adapter.ts";
import { createWebPushServiceWorkerRuntime } from "../../src/adapters/web-push/service-worker-runtime.ts";
import type { TimeoutScheduler } from "../../src/adapters/web-push/runtime-support.ts";
import {
@@ -365,6 +368,56 @@ describe("Web Push worker runtime", () => {
expect(focus).not.toHaveBeenCalled();
});
// 06-01. A registry path is an app path: an accepted click opens it
// under the base path, and the handoff keeps the app path for the router.
it("opens an accepted click's route under the base path", async () => {
const store = await activeFence();
const messages: unknown[] = [];
const openWindow = vi.fn(
async (url: string): Promise<WindowClientFacade> => ({
url,
focus: async () => {},
postMessage() {},
}),
);
let windows: readonly WindowClientFacade[] = [];
const adapter = createNotificationClickAdapter({
fenceStore: store,
registry,
origin: "https://app.example.test",
appRootUrl: "https://app.example.test/app/",
now: () => now,
clients: {
matchControlledWindowClients: async () => windows,
openWindow,
},
});
const click = () =>
adapter.handle({
notification: { data: clickData(), close() {} },
waitUntil() {},
});
await expect(click()).resolves.toEqual({ ok: true, value: undefined });
expect(openWindow.mock.calls).toEqual([
["https://app.example.test/app/inbox"],
]);
windows = [
{
url: "https://app.example.test/app/current",
focus: async () => {},
postMessage(message) {
messages.push(message);
},
},
];
await expect(click()).resolves.toEqual({ ok: true, value: undefined });
expect(messages).toEqual([
expect.objectContaining({ path: "/inbox" }),
]);
});
describe("a rejected click opens the app root (Q-6.6-11, D-14)", () => {
async function rejectedClick(
options: Readonly<{ at?: number; data?: unknown }>,