e4caafda3070da4d55802fc6ca8fcccfd672dbe6
7
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
ece944d08b |
feat(bootstrap): 제품 세션 owner와 FE-REG-ENV 행을 제품 파일로 받는다 (1101/09-02)
문제
09-02(
|
||
|
|
da1e128999 |
feat(bootstrap): 제품 capability·자격증명·설정 키를 제품 소유 파일로 받는다 (1101/09-02)
문제
제품이 http·telemetry·indexedDb 밖의 capability, 세션 밖 자격증명(BFF
쿠키 XSRF, Studio CSRF), 제품 런타임 설정 키를 넣으려면
runtime-adapters.ts, feature-adapter-contribution.ts, rest-profiles.ts,
release-artifacts.ts, runtime-config-schema.ts를 직접 고쳐야 한다. 이
파일들은 템플릿이 보안·계약 수정을 자주 넣는 곳이라, 동기화 때마다
fail-closed 코드를 손으로 병합한다(memento +61줄, tech-log +118줄).
고른 방법 (리뷰 09 4.2의 (B))
- FeaturePlatformCapabilities를 interface로 바꾼다. 제품은 이 repo의
FeatureIndexedDbRepositories·ApplicationFeatureInputs와 같은
declaration merging으로 capability를 더한다.
- 제품 소유 파일 둘을 빈 구현으로 둔다.
- src/bootstrap/product-composition.ts: 추가 capability와 "인증 프로필
id → 자격증명 제공자" 표. 계약 타입은 템플릿 소유
product-composition-contract.ts에 둔다.
- src/contracts/product-contracts.ts: 제품 인증 프로필과 런타임 설정
zod 조각. 프로필 레지스트리와 strict 설정 스키마는 contracts 층에
있고 빌드 스크립트도 읽는다. contracts는 bootstrap을 import할 수
없어서 파일을 하나로 합치지 못했다.
- 판단 순서는 조립 루트가 쥔다: scope fence → ANONYMOUS 프로필 → 제품
제공자 → 세션 → 응답 뒤 fence 재확인. 제공자가 throw하면 executor가
CREDENTIAL_OWNER_FAILED로 닫는다. 나가는 헤더는 여전히 프로필 허용
목록이 정한다.
- 제공자 계약은 기존 attachCredentials 시그니처를 그대로 쓴다.
- 제품 composition은 http capability가 생긴 뒤에 부른다. tech-log가
두었던 전방 참조 stub이 필요 없다.
- 제품에 host 전체를 넘기지 않고 readCookie(name)만 넘긴다. host를 객체에
담으면 browser-data-boundary/no-capability-alias가 막는다.
- http·telemetry는 spread 뒤에 둬서 제품이 바꿀 수 없다(타입에서도 뺀다).
제품 프로필 id나 설정 키가 템플릿 이름과 겹치면 모듈 로드 때 throw한다.
버린 대안
- (A) 현 상태: 템플릿 비용은 0이지만 제품마다 동기화 비용이 반복된다.
- (C) 기능 계약 기여가 인증 프로필과 제공자를 함께 가져온다: 인증
정책이 기능마다 흩어져 보안 리뷰 범위가 넓어진다.
- 제공자에 응답 관찰 훅 추가: tech-log의 401/403 토큰 폐기는 제품
capability가 http를 감싸서 표현된다(픽스처). 제공자 계약을 작게 둔다.
위험·한계
- memento의 x-xsrf-token은 닫힌 자격증명 헤더 목록(VD-23,
CREDENTIAL_HEADER_NAMES)에 없다. 그 이름을 쓰려면 여전히
rest-profiles.ts를 고치거나 백엔드가 x-csrf-token을 받아야 한다.
픽스처는 x-csrf-token으로 표현했다.
- 제품 설정 키의 FE-REG-ENV 행(src/contracts/env.ts)은 이 변경 밖이다.
그 행을 요구하는 검사는 없다.
- tech-log가 부트 전에 BFF 세션 owner를 설치하는 코드
(create-runtime-composition.ts)는 이 확장 지점 밖이다.
- 제공자 응답 뒤 fence 재확인은 executor가 같은 fence로 먼저 전송을
끊어서 조립 루트 경유 테스트로는 따로 보이지 않는다. 세션 경로와 같은
이중 방어로 둔다.
- V1 설정 문서도 제품 키를 받는다(없으면 기본값). V1은 한 릴리스 동안만
쓰는 리더다.
- 초기 JS gzip 203,818 → 204,178 B(+360, 예산 204,800).
검증
- RED: tests/unit/runtime-adapters-credential-order.test.ts 7행 중 제품
제공자를 기대하는 4행 실패(세션이 먼저 답해 UNAUTHENTICATED, owner가
먼저 답해 SUCCESS). fence·ANONYMOUS·세션 3행은 통과.
- GREEN: 같은 파일 7/7. tests/unit/product-composition-fixture.test.ts
9/9(가짜 제품 파일 두 개로 offsetUpload, runtime, BFF 쿠키 XSRF 읽기·
쓰기, Studio CSRF 발급·403 폐기, 제품 설정 키, 이름 충돌 거절). 09-01
tests/unit/runtime-adapters-auth-profile.test.ts 12/12.
- 회귀: tests/unit·contract·runtime-schema 182 files 2590 tests 통과.
integration·component 47 files 386 tests 통과(pnpm을 띄우는
security-followup-archive 제외). tsc app·test·node·recipes·web-worker·
service-worker 통과. 바꾼 파일 eslint 통과. check:registries PASS
(compatibility=breaking은 기존 route·storage 행). verify:documentation
PASS_SCOPED. check:adapter-inventory PASS. check:architecture는 pnpm 대신
exec 전용 shim으로 그래프·fixture PASS. 템플릿 런타임 설정 JSON
schema는 baseline과 같다.
|
||
|
|
61baf96682 |
fix(docs): 입구 문서를 실제 src 폴더 9개와 규칙 이름에 맞추고 검사한다 (14-03)
문제: src/ 최상위 폴더는 adapters application apps bootstrap contexts
contracts features platform presentation 9개다. layers.md 표,
frontend-application-foundation.md 목록, overview.md 그림, README 구조
그림은 src/platform을 한 번도 적지 않았고 apps·contexts는 금지 간선
설명에만 나왔다. 대신 없는 최상위 domain을 계층으로 그렸다.
contract-ownership.md의 배치 규칙에는 src/platform 선택지가 없었다.
layers.md는 "표와 규칙이 어긋날 수 없다"고 적었지만
.dependency-cruiser.json 규칙 31개 중 25개의 이름이 없었다.
게이트는 금지 간선만 막으므로, 허용되지만 틀린 자리(최상위 domain 신설,
제품 중립 primitive를 contracts에 두기)를 문서로 막을 수 없었다.
고른 방법: 리뷰의 (B)안. 문서를 코드에 맞추고 verify:documentation에
대조 검사를 더한다.
- layers.md: 9개 폴더 표(폴더 | 소유)를 정본으로 두고, 금지 간선 글머리
목록을 규칙 31개 표(규칙 이름 | 적용 대상 | 금지)로 바꾼다. domain은
기능 안의 계층으로 옮기고 "최상위 domain 폴더는 지금 없고, 만들면
domain-is-framework-neutral이 이미 적용된다"고 적는다. 보증 문장은
실제로 검사하는 범위로 줄인다. kernel 절과 배럴 절은 그대로 둔다.
- README·overview·foundation: layers.md 표의 설명을 한 글자도 바꾸지
않고 "`src/<폴더>` — <설명>" 목록으로 싣는다. 그림은 실제 import
방향(presentation -> application -> contracts -> platform,
apps -> contexts -> features)으로 다시 그린다.
- contract-ownership.md: src/platform 선택지와 contracts와의 차이,
platform-kernel-is-product-neutral을 적는다.
- verify-documentation-readiness.ts: 폴더 목록은 src/를 읽고, 규칙 목록은
.dependency-cruiser.json을 읽는다. layers.md 표에 행이 없는 폴더,
나머지 세 문서에서 설명이 다른 폴더, 네 문서가 적은 없는 최상위
src 폴더, layers.md에 없는 규칙 이름이 있으면 실패한다. 결과는
documentation-review.json의 sourceStructure로 남긴다(스키마는 필드
하나를 더한다).
버린 대안: (A) 문서만 고치기 — 규칙이나 폴더가 늘면 다시 어긋난다.
(C) layers.md를 .dependency-cruiser.json에서 생성 — 사람이 읽는 설명을
넣기 어렵다. 네 문서 모두에 규칙 31개를 싣는 것 — 같은 목록이 네 벌이
되어 어긋날 곳만 늘어난다. 규칙 표는 layers.md 한 곳에 둔다.
위험·한계:
- 검사는 규칙 이름이 있는지만 본다. 행의 설명이 규칙과 맞는지는 보지
않는다(문서에도 그렇게 적었다).
- 없는 폴더 검사는 "src/<이름>" 꼴만 잡는다. "domain"처럼 src/ 없이
계층 이름만 쓰는 것은 잡지 못한다.
- README·overview·foundation에는 같은 9줄이 복사되어 있다. 설명을 바꾸면
네 곳을 함께 고쳐야 하고, 검사가 그것을 강제한다.
- .dependency-cruiser.json 주석의 "like src/domain"(feature-domain 규칙)은
코드 주석이라 이번 범위 밖이다.
- 문서 drift 전반(경로·줄 번호, 14-05)은 다루지 않는다.
검증:
- RED: 새 검사를 기준 커밋(
|
||
|
|
298201f3ee |
perf(features)!: 기능 실행부를 초기 청크에서 떼어 라우트 진입 때 적재한다 (15-01)
문제 초기 JS는 203,572 / 204,800 B(gzip)였다. 생성 인덱스가 각 기능의 feature-module.ts를 정적으로 import하고, 그 파일이 계약(zod 스키마·mapper 포함), HTTP 계약 contribution, application input 팩토리, route codec까지 모두 끌고 왔다. 참조 모양 기능 1개를 더하면 +3,922 B가 늘어 첫 기능에서 예산을 넘었다. 고른 방법 - 기능을 두 부분으로 나눈다. 선언(FeatureModule: route 표, route runtime 계약, invalidation, 문구, 부팅 때 release manifest와 맞춰 볼 contractPackages)은 초기 청크에 남는다. 실행부(FeatureRuntime: V2 API 계약, adapter contribution, contract contribution)는 feature-runtime.ts로 옮기고 loadRuntime이 동적 import한다. route codec은 context-routes.ts의 route handle에 실어 route와 함께 적재한다. - 적재 시점은 그 기능의 route에 들어갈 때다. ContextRouteGateway가 route 모듈과 함께 application.features.load(featureId)를 부르고, 끝난 뒤에 화면을 그린다(공개 포트에는 load만 추가). 들어온 URL의 기능은 route 모듈과 병렬로 적재해 왕복을 늘리지 않는다. 런타임 설정으로 꺼진 기능은 적재하지 않는다. - 조립부는 기능별 로더를 만든다(installed-feature-adapters.ts). contract registry는 기능이 적재될 때마다 전체를 다시 합쳐 검증한다 (installed-contract-contributions.ts). 선언하지 않은 contract package를 적재하면 거절한다. - 모든 실행부를 한꺼번에 읽는 registry(V2 API, contract contribution)는 installed-feature-runtime-registries.ts의 async 함수로, Node·테스트· registry 거버넌스용 상수는 top-level await 모듈 loaded-feature-runtimes.ts로 둔다. src에서 후자를 import하면 새 아키텍처 규칙 boot-does-not-load-every-feature-runtime이 막는다. 플랫폼 구성 화면은 route 로더에서 async 함수를 불러 결과를 prop으로 받는다. - vite.config.ts에 청크 그룹 2개를 둔다. rolldown은 부팅 그래프와 lazy 청크가 같이 쓰는 모듈을 importer 집합마다 따로 청크로 뗀다. 그대로 두면 기능마다 선언 청크가 하나씩 늘고(기능당 +1,471 B), 실행부와 공유하는 플랫폼 모듈(HTTP executor, contract runtime, zod)이 6개 청크로 쪼개져 템플릿 자체가 +438 B 커졌다. feature-declarations는 모든 기능의 선언을, feature-platform은 실행부가 같이 쓰는 부팅 모듈을 한 청크로 묶는다. render-boot-failure.tsx가 쓰는 모듈은 feature-platform에서 뺀다(09-03: 애플리케이션 그래프가 평가 중 던져도 실패 화면은 떠야 한다). 버린 대안 - 부팅 때 feature 청크를 미리 동적 import하고 기다린 뒤 렌더: 분류기는 lazy로 세지만 첫 렌더 경로의 바이트는 그대로다. 예산을 속이는 것이라 버렸다. - 실행부 일부만 지연(adapter와 contribution만): 모두 같은 zod 스키마를 공유해 줄지 않았다. 실측 +4,031 B로 오히려 늘었다. - 선언과 실행부를 같은 lazy 청크(context-routes)에 두기: 기능당 -60 B 수준이라 그룹 없이 목표에 못 미쳤다. - 페이지 문구까지 실행부로 옮기기: 기능당 약 300~450 B를 더 줄이지만 i18n catalog를 런타임 등록 구조로 바꿔야 해 이번 범위에서 뺐다. - boot.tsx를 별도 진입점으로 추가: 분류기가 boot의 동적 import를 모두 초기로 세어 218,303 B가 됐다. 위험·한계 - FeatureModule 모양이 바뀐다. 다운스트림 기능은 feature-runtime.ts로 실행부를 옮겨야 한다(BREAKING CHANGE). - 기능 계약 간 중복(operation, schema, contribution) 검사가 부팅이 아니라 그 기능의 적재 시점과 Node 검사(loaded-feature-runtimes를 읽는 스크립트· 테스트)로 옮겨 간다. - 기능 route에 처음 들어갈 때 실행부 청크(약 5 KB gzip)를 받는다. 플랫폼 구성 화면은 모든 기능의 실행부를 받은 뒤 그린다. lab 게이트(FE-GATE-026)가 재는 화면이라 LCP가 조금 늘 수 있다. 측정하지 않았다. - 청크 그룹은 rolldown 자동 분할을 일부 대신한다. feature-declarations가 비면 기능당 증가 상한 테스트가 실패한다. feature-platform이 비면 템플릿 총량(약 2 KB)만 늘고 번들 예산 검사가 잡는다. - config/contracts/registry-baseline.json의 FE-REG-API/SCHEMA source는 아직 installed-feature-contracts.ts다. 승인 digest가 걸려 있어 소유자 재승인 때 고친다. check-registries는 통과한다. - 예산 안에 들어가는 참조 모양 기능은 약 3개다. 플랫폼 자체가 예산의 98.8%다. 수치 (vite build, classifyViteJavascript + gzipSync 기본 수준) - 템플릿: 203,572 B(13파일) -> 202,361 B(16파일), -1,211 B - 참조 복사본 +1: 207,494 B(+3,922) -> 203,102 B(+741) - 참조 복사본 +2: 210,818 B(+3,324) -> 203,750 B(+648) - 참조 복사본 +5: 205,629 B - lazy JS: 23,516 B -> 28,204 B 검증 - RED: node scripts/run-vitest.ts run tests/unit/feature-shape-growth.test.ts "adds at most 1 KiB ... (15-01)" 실패: expected 3934 to be less than or equal to 1024 - GREEN: 같은 테스트 통과(+741 B) - node scripts/run-vitest.ts run tests/unit: 168파일 2,383 통과 - node scripts/run-vitest.ts run tests/component tests/features tests/integration tests/contract tests/runtime-schema tests/architecture tests/platform tests/recipes (security-followup-archive 제외, pnpm 호출): 109파일 787 통과 - npx tsc --noEmit: app, node, test, recipes, web-worker, service-worker 통과 - npx eslint 바뀐 파일 통과 - check-architecture.ts(pnpm exec 대신 eslint를 부르는 shim): PASS, 새 규칙이 boot.tsx의 import를 거절하는 것 확인 - check-adapter-inventory, check-registries, verify-documentation-readiness, check-ci-contract: PASS - e2e Chromium 전체(pnpm 없는 build-frontend + vite preview, 별도 포트): 55 통과 - storybook build 성공 - 미실행: Firefox·WebKit e2e, 시각 회귀, lab 성능(FE-GATE-026), pnpm 경로의 check:bundle, test:system BREAKING CHANGE: FeatureModule은 id, contracts(선언), routes, messages, loadRuntime만 가진다. adapters, contractContributions와 V2 API 계약 (apiOperations, schemas, runtimeSchemas, mappers)은 defineFeatureRuntime으로 만든 feature-runtime.ts로, route codec은 context-routes.ts의 route handle codecs로 옮긴다. contracts에는 contractPackages를 추가한다. Refs: docs/reviews/2026-11-01-maturity-review/15-performance.md 15-01, 16-structure-patterns.md 9절 |
||
|
|
bc7c46b2d5 |
fix(features): check declared needs and show the IndexedDB capability assembly (09-05)
A missing capability reached the feature factory as an anonymous TypeError. The composer now names the feature and the capability, and the IndexedDB provider example moves from a browser spec into an opt-in recipe with a test. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
ec7f20e2ee | refactor: 프론트엔드 리펙토링 | ||
|
|
5cc41467ae | refactor: 프론트 템플릿 리펙토링 |