diff --git a/.dependency-cruiser.json b/.dependency-cruiser.json index 7621ddf7..60714add 100644 --- a/.dependency-cruiser.json +++ b/.dependency-cruiser.json @@ -300,7 +300,7 @@ }, { "name": "feature-and-app-roots-do-not-reach-adapters", - "comment": "12-03. The graph checks one edge at a time, so a module that presentation may import must not re-export a concrete adapter: presentation would then reach it with every direct rule passing. That covers every file under src/features outside a feature's adapters/ folder (the root files, and any folder that is not a layer, such as support/: 0929/12-03), src/contexts and src/apps. Inside a feature, only its adapters/ folder reaches src/adapters; the product composes adapters in bootstrap. Exception: src/features/feature-adapter-contribution.ts imports the InstalledHttpOperationExecutor type that bootstrap hands to feature adapters (type only). Owner: frontend-platform. Revisit when that type moves to an application port.", + "comment": "12-03. The graph checks one edge at a time, so a module that presentation may import must not re-export a concrete adapter: presentation would then reach it with every direct rule passing. That covers every file under src/features outside a feature's adapters/ folder (the root files, and any folder that is not a layer, such as support/: 0929/12-03), src/contexts and src/apps. Inside a feature, only its adapters/ folder reaches src/adapters; the product composes adapters in bootstrap. Exception: src/features/feature-adapter-contribution.ts imports the adapter types of the capabilities it declares, InstalledHttpOperationExecutor and the opt-in FileserverUploadClientDependencies (type only, 1112/09-01). Owner: frontend-platform. Revisit when that type moves to an application port.", "severity": "error", "from": { "path": "^src/(features/|contexts/|apps/)", diff --git a/config/contracts/backend-contract-pin.json b/config/contracts/backend-contract-pin.json index 42776de9..cb7ff36e 100644 --- a/config/contracts/backend-contract-pin.json +++ b/config/contracts/backend-contract-pin.json @@ -2,7 +2,7 @@ "schemaVersion": 1, "backend": { "repository": "clean-architecture-backend-template", - "commit": "45d2a478b800586f1d84151723629a560265d58e", + "commit": "d32b4b53de734aca7d76dc08acf6e97bea899672", "document": "docs/web/http-contract.md", "sectionsCompared": ["1", "2", "4"], "scaffoldSources": [ @@ -12,12 +12,12 @@ "copiedTo": { "file": "scripts/create-feature.ts", "symbol": "backendPathSegment" } }, { - "path": "scripts/feature-scaffold/templates/src/domain-core/src/main/java/dev/caskeleton/domain/__feature__/__Feature__.java.tmpl", + "path": "scripts/feature-scaffold/templates/src/domain/core/src/main/java/dev/caskeleton/domain/__feature__/__Feature__.java.tmpl", "fact": "NAME_MAX_LENGTH 100", "copiedTo": { "file": "scripts/create-feature-write-slice.ts", "symbol": "BACKEND_NAME_MAX_LENGTH" } }, { - "path": "scripts/feature-scaffold/templates/src/application-core/src/main/java/dev/caskeleton/application/__feature__/__Feature__ErrorCode.java.tmpl", + "path": "scripts/feature-scaffold/templates/src/application/core/src/main/java/dev/caskeleton/application/__feature__/__Feature__ErrorCode.java.tmpl", "fact": "오류 코드 _INVALID와 _NOT_FOUND", "copiedTo": { "file": "scripts/create-feature-write-slice.ts", "symbol": "invalidCode" } }, @@ -32,22 +32,51 @@ "copiedTo": { "file": "scripts/create-feature-write-slice.ts", "symbol": "renderWriteDescriptors" } }, { - "path": "scripts/feature-scaffold/templates/src/application-core/src/main/java/dev/caskeleton/application/__feature__/Create__Feature__UseCase.java.tmpl", + "path": "scripts/feature-scaffold/templates/src/application/core/src/main/java/dev/caskeleton/application/__feature__/Create__Feature__UseCase.java.tmpl", "fact": "권한, 이름 검사, 쓰기 순서다. 거절은 쓰기 전에 일어난다", "copiedTo": { "file": "scripts/create-feature-write-slice.ts", "symbol": "refusedBeforeWrite" } } + ], + "codeSources": [ + { + "path": "src/application/fileserver/src/main/java/dev/caskeleton/application/fileserver/api/error/FileserverErrorCode.java", + "fact": "작업이 파일을 게시하기 전에 내는 5xx: PARTIAL_WRITE, ATOMIC_PUBLISH_UNSUPPORTED, STORAGE_UNAVAILABLE, SERVER_BUSY, STORAGE_FULL", + "copiedTo": { "file": "src/adapters/http/fileserver-upload.ts", "symbol": "NOT_APPLIED_5XX_CODES" }, + "codes": ["PARTIAL_WRITE", "ATOMIC_PUBLISH_UNSUPPORTED", "STORAGE_UNAVAILABLE", "SERVER_BUSY", "STORAGE_FULL"] + }, + { + "path": "src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/config/BlockingTransferExecutor.java", + "fact": "전송 pool 포화는 작업 전 503 SERVER_BUSY, 대기 시간 초과는 작업 단계와 상관없는 504 TRANSFER_TIMEOUT", + "copiedTo": { "file": "src/adapters/http/fileserver-upload.ts", "symbol": "NOT_APPLIED_5XX_CODES" } + }, + { + "path": "src/application/fileserver/src/main/java/dev/caskeleton/application/fileserver/quota/TransferAdmissionController.java", + "fact": "instance 전송 permit 포화는 use case 시작 때의 503 SERVER_BUSY", + "copiedTo": { "file": "src/adapters/http/fileserver-upload.ts", "symbol": "NOT_APPLIED_5XX_CODES" } + }, + { + "path": "src/application/fileserver/src/main/java/dev/caskeleton/application/fileserver/upload/UploadFileApplicationUseCase.java", + "fact": "모호하지 않은 실패는 업로드를 취소한다. 4xx는 READY 파일을 남기지 않는다", + "copiedTo": { "file": "src/adapters/http/fileserver-upload.ts", "symbol": "fileserverFailureEffect" } + } ] }, "frontend": { "contractDocument": "docs/architecture/backend-api-and-server-state-contract.md", "contractSections": ["4.1", "6", "6.1"], - "readers": ["src/adapters/http/backend-envelope.ts"] + "readers": ["src/adapters/http/backend-envelope.ts", "src/adapters/http/fileserver-upload.ts"] }, "tables": { "idempotencyAnswers": "config/contracts/backend-idempotency-answers.json", "backendExcerpt": "config/contracts/backend-http-contract-excerpt.json" }, - "notCopied": [], + "notCopied": [ + { + "section": "4", + "code": "OPERATION_NOT_FOUND", + "reason": "durable operation 조회(`DurableOperationController`)의 404다. 쓰기의 적용 여부 답이 아니고, 프론트는 그 조회를 부르지 않는다" + } + ], "owner": "frontend-platform", - "comparedOn": "2026-11-05" + "comparedOn": "2026-11-13" } diff --git a/config/contracts/backend-http-contract-excerpt.json b/config/contracts/backend-http-contract-excerpt.json index 8c335ae8..dba7b33c 100644 --- a/config/contracts/backend-http-contract-excerpt.json +++ b/config/contracts/backend-http-contract-excerpt.json @@ -2,7 +2,7 @@ "schemaVersion": 1, "source": { "repository": "clean-architecture-backend-template", - "commit": "45d2a478b800586f1d84151723629a560265d58e", + "commit": "d32b4b53de734aca7d76dc08acf6e97bea899672", "document": "docs/web/http-contract.md" }, "sections": { @@ -27,10 +27,11 @@ [ "| 코드 | status | category | `retryable` | `Retry-After` | 언제 |", "| --- | --- | --- | --- | --- | --- |", - "| `REQUEST_TIMEOUT` | 503 | `TRANSIENT_DEPENDENCY` | `true` | 없음 | 비동기 요청(`Callable`·`DeferredResult`·스트리밍)이 시간 안에 끝나지 않았다. GraphQL도 같은 이름을 쓰지만 그쪽 `category`는 GraphQL 전용 어휘 `TIMEOUT`이다(`src/adapter/inbound/graphql/README.md`) |", + "| `REQUEST_TIMEOUT` | 503 | `TRANSIENT_DEPENDENCY` | `true` | 없음 | 비동기 요청(`Callable`·`DeferredResult`·스트리밍)이 시간 안에 끝나지 않았다. 그 밖의 503(필터의 `sendError(503)` 등)은 공용 `SERVER_BUSY`다. GraphQL도 같은 이름을 쓰지만 그쪽 `category`는 GraphQL 전용 어휘 `TIMEOUT`이다(`src/adapter/inbound/graphql/README.md`) |", "| `IDEMPOTENCY_KEY_INVALID` | 400 | `VALIDATION` | `false` | 없음 | 2절 |", "| `RATE_LIMIT_UNAVAILABLE` | 503 | `TRANSIENT_DEPENDENCY` | `true` | 있음 | rate-limit 저장소 응답 없음(`docs/web/runbook.md`) |", - "| `RATE_LIMIT_INCOMPATIBLE` | 503 | `INTERNAL` | `false` | 없음 | rate-limit 제공자가 계약과 맞지 않음 |" + "| `RATE_LIMIT_INCOMPATIBLE` | 503 | `INTERNAL` | `false` | 없음 | rate-limit 제공자가 계약과 맞지 않음 |", + "| `OPERATION_NOT_FOUND` | 404 | `NOT_FOUND` | `false` | 없음 | durable operation 조회(`DurableOperationController`)에서 그 operation이 없거나 다른 호출자의 것이다. 둘을 가르지 않는다 |" ] ] } diff --git a/config/contracts/backend-idempotency-answers.json b/config/contracts/backend-idempotency-answers.json index 57130d0e..757cbfb7 100644 --- a/config/contracts/backend-idempotency-answers.json +++ b/config/contracts/backend-idempotency-answers.json @@ -2,7 +2,7 @@ "schemaVersion": 1, "source": { "repository": "clean-architecture-backend-template", - "commit": "45d2a478b800586f1d84151723629a560265d58e", + "commit": "d32b4b53de734aca7d76dc08acf6e97bea899672", "document": "docs/web/http-contract.md" }, "answers": [ diff --git a/docs/architecture/backend-api-and-server-state-contract.md b/docs/architecture/backend-api-and-server-state-contract.md index 2f1e2083..b8920d0d 100644 --- a/docs/architecture/backend-api-and-server-state-contract.md +++ b/docs/architecture/backend-api-and-server-state-contract.md @@ -151,7 +151,7 @@ Envelope의 모양과 키 존재 규칙은 짝 백엔드 템플릿 문서가 정 - 정본: [`clean-architecture-backend-template/docs/web/http-contract.md`](../../../clean-architecture-backend-template/docs/web/http-contract.md) 1절 "Envelope 키 존재 규칙" -- 기준 커밋: 백엔드 `45d2a478`. 기계가 읽는 정본은 +- 기준 커밋: 백엔드 `d32b4b53`. 기계가 읽는 정본은 `config/contracts/backend-contract-pin.json`(repo, 전체 SHA, 대조한 절 §1·§2·§4, 담당)이다. 백엔드 §2 표와 §4의 503 셋(`REQUEST_TIMEOUT`, `RATE_LIMIT_UNAVAILABLE`, `RATE_LIMIT_INCOMPATIBLE`)은 @@ -163,7 +163,8 @@ Envelope의 모양과 키 존재 규칙은 짝 백엔드 템플릿 문서가 정 - 백엔드 §2·§4 표의 행은 pin 커밋 그대로 `config/contracts/backend-http-contract-excerpt.json`에 옮겨 두었다. 같은 테스트가 답 표의 code·status를 이 사본과 대조한다. 사본에만 있는 행은 답 표에 옮기거나 pin의 - `notCopied`에 이유와 함께 적는다(지금은 없다). pin의 + `notCopied`에 이유와 함께 적는다. 지금은 §4의 404 `OPERATION_NOT_FOUND` 하나다(durable + operation 조회의 답이라 쓰기의 적용 여부와 무관하고, 프론트는 그 조회를 부르지 않는다). pin의 `sectionsCompared`의 §4에서 답 표가 옮긴 행은 503 셋(`REQUEST_TIMEOUT`, `RATE_LIMIT_UNAVAILABLE`, `RATE_LIMIT_INCOMPATIBLE`)이다. `IDEMPOTENCY_KEY_INVALID`는 §2 행으로 옮겼다. @@ -177,6 +178,11 @@ Envelope의 모양과 키 존재 규칙은 짝 백엔드 템플릿 문서가 정 pin의 `backend.scaffoldSources`에 있고, 각 항목이 옮긴 곳(프론트 파일과 이름)을 적는다. drift 검사는 pin 뒤 HEAD에서 이 파일들이 바뀌었는지도 보고, 바뀐 파일마다 다시 볼 프론트 위치를 말하며 1로 끝난다(1105/16-02). +- Fileserver 업로드 client가 읽는 백엔드 code 파일(`FileserverErrorCode` 등)은 pin의 + `backend.codeSources`에 있다. 게시 전 5xx 표는 그 행의 `codes`에 옮겨 두었고, + `tests/unit/backend-contract-pin.test.ts`가 `fileserver-upload.ts`의 표와 대조한다. drift 검사는 + 이 파일들도 pin 뒤 HEAD에서 바뀌었는지 본다(1105/01-02). pin이 적은 경로가 pin 커밋에 없으면 + (백엔드가 폴더를 옮겼다) 그것도 1이다. - 프론트에서 Envelope를 읽는 곳: `src/adapters/http/backend-envelope.ts`(스키마와 해석). V3 실행기는 descriptor가 `responseEnvelope: "ENVELOPE_V1"`일 때 쓴다. `create:feature`가 만든 기능은 이 값을 선언한다. Envelope가 없는 백엔드의 @@ -267,7 +273,7 @@ backend idempotency를 대체하지 않는다. - 정본: [`clean-architecture-backend-template/docs/web/http-contract.md`](../../../clean-architecture-backend-template/docs/web/http-contract.md) 2절 "멱등성 응답", 4절 "web 전용 오류 코드" -- 기준 커밋: 4.1절과 같다(백엔드 `45d2a478`, `config/contracts/backend-contract-pin.json`). +- 기준 커밋: 4.1절과 같다(백엔드 `d32b4b53`, `config/contracts/backend-contract-pin.json`). - 프론트가 그 응답을 읽는 곳: - 키 생성·검사: `src/contracts/mutation-intent.ts` `isValidIdempotencyKey` - 결과 불명 재전송이 같은 키를 쓰고 `Retry-After`까지 기다리는 곳: @@ -293,24 +299,29 @@ mutation이 400·409·422로 실패하면 프론트는 그 요청이 적용됐 읽었다. 처리 중·불일치 판정은 그대로 action 전이고 줄 번호만 옮겼다. `45d2a478`에서는 바뀐 `GlobalExceptionHandler`(로그 줄 정리)와 `IdempotencyExecutor`를 다시 읽었다. 인용한 블록의 내용은 그대로이고 줄 번호만 옮겼다. §2는 처리 중(PostgreSQL 저장소는 409 대신 -기다림)과 `IDEMPOTENCY_UNAVAILABLE`(lease 만료로 시작 거절) 설명만 늘었고 code·status·재시도는 같다. 같은 code가 쓰기 전과 +기다림)과 `IDEMPOTENCY_UNAVAILABLE`(lease 만료로 시작 거절) 설명만 늘었고 code·status·재시도는 같다. +`d32b4b53`에서는 계층 폴더 재배치(`application-core` 모듈이 +`clean-architecture-backend-template/src/application/core/`로 가는 식, 내용 같음)와 샘플 모듈 +`sample-portfolio` 삭제를 따라 근거를 다시 찾았다. 판정은 바뀌지 않았다. 샘플과 함께 +사라진 근거(참조 도메인 code, `WorkLogWebMapper`·`RepoStatsAclMapper`, `PosterImagePublicationController`)는 +표에서 뺐다. 400·409·422 code 집합(`clean-architecture-backend-template/docs/registries/error-codes.yaml`)은 같다. 같은 code가 쓰기 전과 뒤에서 모두 나오면 "쓰기 뒤 가능"으로 둔다. 프론트는 code만 보고 둘을 가를 수 없다. | code (status) | 나오는 곳 | 단계 | 프론트 결과 | 백엔드 파일:줄 | | --- | --- | --- | --- | --- | -| `VALIDATION_FAILED` (400), details = 필드 목록 | 요청 본문 `@Valid` 실패, 컨트롤러 파라미터 제약 실패. 컨트롤러 메서드가 불리기 전 | 쓰기 전 | `NOT_APPLIED` | `GlobalExceptionHandler.java:205-218`, `:333-355` | -| `VALIDATION_FAILED` (400), details = 필드 목록 | `ConstraintViolationException`. 어느 층에서 던져도 이 handler가 받는다. 요청 경로에서 던지는 코드는 없다(application bean에 `@Validated` 없음, JPA entity에 Bean Validation 제약 없음, 직접 throw 없음) | 쓰기 전(현재 출처 없음) | `NOT_APPLIED` | `GlobalExceptionHandler.java:101-106` | -| `VALIDATION_FAILED` (400), details = `{cause}` 또는 없음 | 본문을 읽지 못함(`HttpMessageNotReadableException`) | 쓰기 전 | `NOT_APPLIED` | `GlobalExceptionHandler.java:220-238` | -| `VALIDATION_FAILED` (400), details = `{field, code}` | 페이지·정렬 파라미터. 목록 GET 컨트롤러가 use case 전에 검사한다 | 쓰기 전 | `NOT_APPLIED` | `GlobalExceptionHandler.java:149-153`, `PageParams.java:27-33`, `SortParam.java:16-43` | -| `IDEMPOTENCY_KEY_INVALID` (400) | KEYED 컨트롤러 첫 줄의 키 파싱 | 쓰기 전 | `NOT_APPLIED` | `IdempotencyKeyHeader.java:32-38`, `PosterImagePublicationController.java:64` | -| `IDEMPOTENT_REQUEST_MISMATCH` (422) | 멱등성 executor가 action 전에 판정 | 쓰기 전 | `NOT_APPLIED` | `IdempotencyExecutor.java:127-128`, `:166-167` | -| `IDEMPOTENT_IN_FLIGHT` (409) | 멱등성 executor가 action 전에 판정. 같은 키의 앞선 요청이 실행 중이다 | 이번 요청은 쓰기 전. 앞선 요청은 적용될 수 있다 | `MAYBE_APPLIED` | `IdempotencyExecutor.java:129-130`, `:168-169` | -| `BAD_PARAMETER` (400) | 타입 변환 실패, 필수 파라미터·헤더 없음(쓰기 전). **어느 층이든 `IllegalArgumentException`**(use case·domain 포함) | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `GlobalExceptionHandler.java:92-99`, `:108-116`, `:384-404`, `HttpStatusErrorCodes.java:33-34` | -| `MAPPING_FAILED` (400) | web 매퍼(쓰기 전), outbound ACL 매퍼(use case 안), 멱등성 응답 직렬화(action이 끝난 뒤) | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `WorkLogWebMapper.java:36`, `RepoStatsAclMapper.java:14`, `JsonIdempotentResponseCodec.java:32`, `IdempotencyExecutor.java:276` | +| `VALIDATION_FAILED` (400), details = 필드 목록 | 요청 본문 `@Valid` 실패, 컨트롤러 파라미터 제약 실패. 컨트롤러 메서드가 불리기 전 | 쓰기 전 | `NOT_APPLIED` | `GlobalExceptionHandler.java:228-241`, `:361-383` | +| `VALIDATION_FAILED` (400), details = 필드 목록 | `ConstraintViolationException`. 어느 층에서 던져도 이 handler가 받는다. application bean에 `@Validated`가 없고 JPA entity에 Bean Validation 제약이 없다. 직접 던지는 곳은 web-advanced patch 적용 하나다(`PatchBodies.java:49-51`, 컨트롤러가 patch 결과를 use case에 넘기기 전) | 쓰기 전 | `NOT_APPLIED` | `GlobalExceptionHandler.java:105-110` | +| `VALIDATION_FAILED` (400), details = 필드 목록 | 알림 제출·템플릿 컨트롤러가 본문에서 use case 전에 던지는 필드 거절(`NotificationFieldRejectedException`) | 쓰기 전 | `NOT_APPLIED` | `NotificationSubmissionController.java:72`, `:95`, `NotificationTemplateController.java:76-81` | +| `VALIDATION_FAILED` (400), details = `{cause}` 또는 없음 | 본문을 읽지 못함(`HttpMessageNotReadableException`) | 쓰기 전 | `NOT_APPLIED` | `GlobalExceptionHandler.java:248-266` | +| `VALIDATION_FAILED` (400), details = `{field, code}` | 페이지·정렬 파라미터. 목록 GET 컨트롤러가 use case 전에 검사한다 | 쓰기 전 | `NOT_APPLIED` | `GlobalExceptionHandler.java:161-165`, `PageParams.java:27-33`, `SortParam.java:16-43` | +| `IDEMPOTENCY_KEY_INVALID` (400) | KEYED 컨트롤러 첫 줄의 키 파싱. main에는 이 헤더를 읽는 운영 컨트롤러가 없고, 시험 fixture가 그 모양을 보인다 | 쓰기 전 | `NOT_APPLIED` | `IdempotencyKeyHeader.java:32-38`, `FaultFixtureController.java:58` | +| `IDEMPOTENT_REQUEST_MISMATCH` (422) | 멱등성 executor가 action 전에 판정 | 쓰기 전 | `NOT_APPLIED` | `IdempotencyExecutor.java:129-130`, `:168-169` | +| `IDEMPOTENT_IN_FLIGHT` (409) | 멱등성 executor가 action 전에 판정. 같은 키의 앞선 요청이 실행 중이다 | 이번 요청은 쓰기 전. 앞선 요청은 적용될 수 있다 | `MAYBE_APPLIED` | `IdempotencyExecutor.java:131-132`, `:170-171` | +| `BAD_PARAMETER` (400) | 타입 변환 실패, 필수 파라미터·헤더 없음(쓰기 전). **어느 층이든 `IllegalArgumentException`**(use case·domain 포함) | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `GlobalExceptionHandler.java:94-103`, `:118-126`, `:412-445`, `HttpStatusErrorCodes.java:47-48` | +| `MAPPING_FAILED` (400) | 멱등성 응답 직렬화(action이 끝난 뒤)와 재생할 응답의 역직렬화(action 전) | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `JsonIdempotentResponseCodec.java:32`, `:41`, `IdempotencyExecutor.java:279` | | `DB_SERIALIZATION_FAILURE`, `DB_DEADLOCK`, `DB_LOCK_TIMEOUT`, `DB_NULL_VIOLATION`, `DB_FK_VIOLATION`, `DB_UNIQUE_VIOLATION`, `DB_CHECK_VIOLATION`, `DB_OPTIMISTIC_CONFLICT` (409) | persistence 어댑터가 SQL·JPA 실패를 바꾼 것. 트랜잭션 안이나 commit에서 | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `FailureCategory.java:86-102`, `StandardSqlStateErrorMapping.java:46-52`, `PersistenceExceptionTranslator.java:133` | | `LOCK_ACQUISITION_TIMEOUT` (409) | 분산 락 대기 초과. use case 안 | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `LockRegistryDistributedLock.java:50`, `:53` | -| 참조 도메인 `WORKLOG_INVALID`, `POSTER_INVALID_STATE`, `POSTER_IMAGE_REQUIRED` (400), `WORKLOG_CONFLICT`, `POSTER_ALREADY_EXISTS`, `POSTER_IMAGE_ALREADY_PUBLISHED` (409) | application·domain 예외 | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `DomainExceptionHandler.java:52-90` | | 선택 모듈 web-advanced `PATCH_REJECTED` (400), `PATCH_TEST_FAILED` (409) | patch 라이브러리. 부르는 코드가 단계를 정한다 | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `clean-architecture-backend-template/src/adapter/inbound/web-advanced/README.md` 「오류 응답」 | | 선택 모듈 fileserver `BAD_REQUEST` (400), `FILE_ALREADY_EXISTS`, `FILE_NOT_READY`, `UPLOAD_OFFSET_MISMATCH`, `CONCURRENT_MODIFICATION` (409), `INTEGRITY_MISMATCH`, `MALWARE_DETECTED`, `INVALID_PATH`, `PATH_OUTSIDE_NAMESPACE` (422) | application·outbound 층. `INTEGRITY_MISMATCH`·`MALWARE_DETECTED`는 레코드를 `REJECTED`로 쓴 뒤 던진다 | 쓰기 뒤 가능 | `MAYBE_APPLIED` | `FileserverErrorCode.java:26-44`, `FinalizeUploadApplicationUseCase.java:211-224`, `:336-341` | @@ -336,28 +347,34 @@ mutation이 400·409·422로 실패하면 프론트는 그 요청이 적용됐 503 `RATE_LIMIT_INCOMPATIBLE`(rate-limit 제공자가 계약과 맞지 않음)은 status와 code가 함께 맞으면 기능 분류기와 상관없이 `NOT_APPLIED`다(1105/03-02, `backend-envelope.ts` `REFUSED_BEFORE_WRITE`). 백엔드 `RateLimitInterceptor.java`의 `preHandle`이 컨트롤러 전에 - `false`를 돌려주며 낸다. `45d2a478`의 main 소스에서 이 두 code를 내는 곳은 그 두 - 줄뿐이다. KEYED·NEVER는 자동 재전송이 없다. IDEMPOTENT 쓰기는 `retryBudget` 안에서 + `false`를 돌려주며 낸다. `d32b4b53`의 main 소스에서 이 두 code를 내는 곳은 그 두 + 줄뿐이다(`:58`, `:63`). KEYED·NEVER는 자동 재전송이 없다. IDEMPOTENT 쓰기는 `retryBudget` 안에서 `Retry-After`(5초 이하) 뒤 다시 보낸다. 실행기는 status로 판단하므로 백엔드가 `retryable: false`로 보내는 `RATE_LIMIT_INCOMPATIBLE`도 다시 보낸다 (`tests/integration/http-execution-v3-envelope.test.ts`, 1106/03-02). 남은 위험(추론, 실행 확인 안 함): Spring MVC는 비동기 처리(`Callable`·`DeferredResult`)가 끝난 뒤의 ASYNC 재디스패치에서도 interceptor의 `preHandle`을 다시 부른다. 그 interceptor는 dispatcher 종류를 보지 않으므로 비동기 쓰기 - 컨트롤러라면 이 503(그리고 429)이 쓰기 뒤에도 나올 수 있다. `45d2a478`에는 Envelope을 + 컨트롤러라면 이 503(그리고 429)이 쓰기 뒤에도 나올 수 있다. `d32b4b53`에도 Envelope을 돌려주는 비동기 쓰기 컨트롤러가 없다(web-advanced 스트리밍과 fileserver 전송뿐). +- 서버 포화의 503 `SERVER_BUSY`(백엔드 `697e62e8c`부터, §4 아래 목록)는 V3 표에 없다. 그래서 + 기능 분류기의 판정을 따르고, 분류기가 없으면 결과 불명이다. 대부분 컨트롤러 전에 나오지만 + (`VirtualThreadAdmissionFilter`), 상태만 정해진 모든 503도 이 code가 되어(`HttpStatusErrorCodes.java:45`) + 단계를 code로 가를 수 없다. Fileserver 업로드 client는 따로 읽는다(아래). - 파일 위치(백엔드 repo `clean-architecture-backend-template` 기준): - `GlobalExceptionHandler.java`, `HttpStatusErrorCodes.java`: `clean-architecture-backend-template/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/error/` - `PageParams.java`, `SortParam.java`: 같은 모듈 `.../web/pagination/` - `IdempotencyKeyHeader.java`: 같은 모듈 `.../web/http/` - - `IdempotencyExecutor.java`: `clean-architecture-backend-template/src/application-core/src/main/java/dev/caskeleton/application/idempotency/` + - `IdempotencyExecutor.java`: `clean-architecture-backend-template/src/application/core/src/main/java/dev/caskeleton/application/idempotency/` - `JsonIdempotentResponseCodec.java`: `clean-architecture-backend-template/src/adapter/inbound/web-advanced/.../advanced/idempotency/` - - `FailureCategory.java`, `StandardSqlStateErrorMapping.java`, + - `FailureCategory.java`(같은 이름이 여럿이다. persistence의 것), `StandardSqlStateErrorMapping.java`, `PersistenceExceptionTranslator.java`, `LockRegistryDistributedLock.java`: `clean-architecture-backend-template/src/adapter/outbound/persistence-jpa/` - - `PosterImagePublicationController.java`, `WorkLogWebMapper.java`, - `RepoStatsAclMapper.java`, `DomainExceptionHandler.java`: `clean-architecture-backend-template/src/sample-portfolio/` - - `FileserverErrorCode.java`, `FinalizeUploadApplicationUseCase.java`: - `clean-architecture-backend-template/src/application-fileserver/` + - `PatchBodies.java`: `clean-architecture-backend-template/src/adapter/inbound/web-advanced/.../advanced/patch/` + - `NotificationSubmissionController.java`, `NotificationTemplateController.java`: + `clean-architecture-backend-template/src/adapter/inbound/web-notification/` + - `FaultFixtureController.java`: `clean-architecture-backend-template/src/adapter/inbound/web/src/testFixtures/` (시험 fixture) + - `FileserverErrorCode.java`, `FinalizeUploadApplicationUseCase.java`, `UploadFileApplicationUseCase.java`, + `TransferAdmissionController.java`: `clean-architecture-backend-template/src/application/fileserver/` - Fileserver 한 번 업로드(`POST /v1/files`)는 V3 실행기가 아니라 `src/adapters/http/fileserver-upload.ts`의 client가 부른다(1105/01-02). 이 client는 위 표의 fileserver 행과 달리 4xx를 `NOT_APPLIED`로 본다. 업로드 use case @@ -368,9 +385,12 @@ mutation이 400·409·422로 실패하면 프론트는 그 요청이 적용됐 - 멱등성 code와 V3 표(`REFUSED_BEFORE_WRITE`, `MAYBE_APPLIED_ANSWERS`)에 있는 답은 client도 V3 표로 판정한다. 그래서 503 `IDEMPOTENCY_UNAVAILABLE`은 `MAYBE_APPLIED`다. `tests/integration/fileserver-upload.test.ts`가 복사한 답 표의 행마다 둘이 같은지 본다. - - 5xx는 작업 스레드가 게시 전에 내는 code 넷(`PARTIAL_WRITE`, - `ATOMIC_PUBLISH_UNSUPPORTED`, `STORAGE_UNAVAILABLE`, `STORAGE_FULL`)만 - `NOT_APPLIED`다. 504 `TRANSFER_TIMEOUT`은 `MAYBE_APPLIED`다. 대기 스레드가 + - 5xx는 파일을 게시하기 전에 나는 code 다섯(`PARTIAL_WRITE`, + `ATOMIC_PUBLISH_UNSUPPORTED`, `STORAGE_UNAVAILABLE`, `SERVER_BUSY`, `STORAGE_FULL`)만 + `NOT_APPLIED`다. `SERVER_BUSY`는 instance 전송 permit과 전송 pool이 찼을 때 작업 전에 + 낸다(`TransferAdmissionController.java:79`, `BlockingTransferExecutor.java:61`. 백엔드 + `697e62e8c` 전에는 429 `TRANSFER_ADMISSION_REJECTED`였다). 이 표는 pin의 `backend.codeSources`에 + 옮겨 두었다. 504 `TRANSFER_TIMEOUT`은 `MAYBE_APPLIED`다. 대기 스레드가 작업 단계와 상관없이 내고, 게시 rename과 `READY` 커밋은 interrupt로 멈추지 않는다 (`BlockingTransferExecutor.java`, `FinalizeUploadApplicationUseCase.java`). 백엔드는 이 code를 `retryable: true`, `ambiguous` 없이 보낸다. 이 차이는 백엔드 결정으로 남는다. @@ -391,7 +411,7 @@ mutation이 400·409·422로 실패하면 프론트는 그 요청이 적용됐 `LOCK_ACQUISITION_TIMEOUT`, fileserver code)도 적을 수 없다(1105/03-01). 계약 조립이 거절하고 실행기도 무시한다. 목록은 `src/contracts/external-contract-runtime.ts`의 `PLATFORM_CODES_POSSIBLY_AFTER_WRITE`이고, `tests/unit/backend-contract-pin-document.test.ts`가 - 이 표의 "쓰기 뒤 가능" 행과 대조한다. 참조 도메인 code와 web-advanced patch code는 + 이 표의 "쓰기 뒤 가능" 행과 대조한다. web-advanced patch code는 엔드포인트가 단계를 정하므로 그 엔드포인트를 확인한 기능 작성자가 적을 수 있다. 이 표에 "쓰기 뒤 가능" 플랫폼 code를 더하면 그 목록도 같은 변경에서 고친다. - `responseEnvelope: "ENVELOPE_V1"`가 아닌 operation에는 적을 수 없다. 실행기가 @@ -406,7 +426,7 @@ mutation이 400·409·422로 실패하면 프론트는 그 요청이 적용됐 백엔드에 붙이는 Envelope operation은 `src/adapters/http/backend-envelope.ts`의 표가 400·409·422를 정한다(`3261208`). -남은 위험: "쓰기 전"은 현재 코드에서 그 handler에 닿는 출처를 센 결과다. 백엔드가 +남은 위험: "쓰기 전"은 현재 코드(`d32b4b53`)에서 그 handler에 닿는 출처를 센 결과다. 백엔드가 application bean에 `@Validated`를 달거나 JPA entity에 Bean Validation 제약을 넣으면, 필드 목록이 있는 400 `VALIDATION_FAILED`가 use case 안에서도 나온다. 백엔드에는 이것을 막는 검사가 없다. diff --git a/docs/architecture/optional-adapter-recipes.md b/docs/architecture/optional-adapter-recipes.md index 19e66d3b..1f593690 100644 --- a/docs/architecture/optional-adapter-recipes.md +++ b/docs/architecture/optional-adapter-recipes.md @@ -124,9 +124,8 @@ type은 facade 밖으로 노출하지 않는다. SSOT다. 문서와 catalog가 다르면 gate가 검사하는 catalog를 우선 고치고 이 표도 같이 갱신한다. -Service Worker를 켤 때 확인할 것(06-05). 템플릿은 1·6·7, 2의 시작 실패 -이벤트, 2의 `observe`와 3을 제품 소유 파일에서 잇는 자리를 갖고 있다. 4·5를 -잇는 제품 소유 자리는 아직 없다. +Service Worker를 켤 때 확인할 것(06-05). 템플릿은 1·6·7·8, 2의 시작 실패 +이벤트를 갖고 있다. 2의 `observe`와 3·4·5는 제품 소유 파일에서 잇는 자리가 있다. 1. 제품 소유 파일 `src/features/product-capabilities.ts`의 `SERVICE_WORKER`를 `ACTIVE`로 바꾼다. `scripts/build-frontend.ts`가 worker 빌드를 추가로 돈다. @@ -138,9 +137,7 @@ Service Worker를 켤 때 확인할 것(06-05). 템플릿은 1·6·7, 2의 시 (`src/bootstrap/optional-runtime-host.ts`). 실제 composition에서 첫 설치가 실패하면 이벤트가 1건 나가는 것은 `tests/component/runtime-composition-service-worker-telemetry.test.ts`가 - 확인한다. 템플릿이 연결하지 않은 것은 셋이다. 업데이트 설치 실패 - (`watchForUpdates`, `src/adapters/service-worker/service-worker-page-controller.ts`)는 - 이벤트를 남기지 않는다. page controller의 `observe`는 제품이 + 확인한다. 템플릿이 연결하지 않은 것은 둘이다. page controller의 `observe`는 제품이 `src/bootstrap/product-composition.ts`의 `composeProduct`에서 `serviceWorker.observe`로 돌려준다(1103/09-05). 템플릿 조립이 그것을 optional host에 넘기고, 던지면 무시한다. `OptionalRuntimeHost.health()`는 `src` 안에서 @@ -152,12 +149,17 @@ Service Worker를 켤 때 확인할 것(06-05). 템플릿은 1·6·7, 2의 시 값이 page controller에 닿는 것은 `tests/component/runtime-composition-service-worker-product-wiring.test.ts`가 확인한다. -4. 활성화 UI: `ServiceWorkerRuntimeHost.onUpdateWaiting`을 구독하고, 사용자가 - 동의하면 `requestActivation()`을 부른다(`src/contracts/service-worker.ts`). -5. reload 처리: `onReloadRequired`를 구독해 reload를 안내한다. -6. 끄기·롤백·제거: `docs/operations/release-cache-rollback.md`의 Service Worker +4. 활성화 UI: `composeProduct`가 `serviceWorker.onUpdateWaiting`을 돌려준다. 템플릿 + 조립이 `ServiceWorkerRuntimeHost.onUpdateWaiting`을 worker 시작 전에 구독해 그것을 + 부르고, 받은 `activate()`는 `requestActivation()`이다. 사용자가 동의하면 부른다 + (1103/09-05). +5. reload 처리: `serviceWorker.onReloadRequired`로 reload를 안내한다. 템플릿 조립이 + `onReloadRequired`를 구독해 부른다. +6. 갱신 실패: 설치에 실패한 갱신(`update_install` `REDUNDANT`)과 실패한 주기 검사 + (`update_check` `FAILED`)도 `observe`로 온다(0925/06-05). +7. 끄기·롤백·제거: `docs/operations/release-cache-rollback.md`의 Service Worker 절차. `service-worker.js`는 `Cache-Control: no-cache`로 서빙한다. -7. 실제 브라우저 검사: `tests/e2e/service-worker-update.spec.ts`와 +8. 실제 브라우저 검사: `tests/e2e/service-worker-update.spec.ts`와 `service-worker-recovery.spec.ts`를 제품 구성으로 돌린다. helper는 이미 `ACTIVE`인 선택을 그대로 쓰고, 캐시 단언은 빌드가 만든 사전 캐시 목록과 비교한다. 준비 단계에서 실패하면 helper(`tests/e2e/support/service-worker-builds.ts`) diff --git a/docs/manual/02-decision-tables.md b/docs/manual/02-decision-tables.md index 529fbabf..d82acf60 100644 --- a/docs/manual/02-decision-tables.md +++ b/docs/manual/02-decision-tables.md @@ -436,7 +436,7 @@ export function mapInvoiceCreateProblem( - 빈 파일은 보내지 않는다. 짝 백엔드 기본 검증기가 빈 파일을 거절하기 때문이다. `VALIDATION_REJECTED`, code `FILE_EMPTY`, `NOT_STARTED`다. - 실패 `effect`: - `NOT_STARTED`: 보내지 않았다. 입력, 크기, 자격 증명에서 거절했다. - - `NOT_APPLIED`: 서버가 거절했고 파일은 없다. Fileserver는 모호하지 않은 실패에서 업로드를 취소한다. 아래 `MAYBE_APPLIED` 경우를 뺀 4xx와, 5xx 중 작업 스레드가 게시 전에 내는 code 넷(`PARTIAL_WRITE`, `ATOMIC_PUBLISH_UNSUPPORTED`, `STORAGE_UNAVAILABLE`, `STORAGE_FULL`)이다. + - `NOT_APPLIED`: 서버가 거절했고 파일은 없다. Fileserver는 모호하지 않은 실패에서 업로드를 취소한다. 아래 `MAYBE_APPLIED` 경우를 뺀 4xx와, 5xx 중 파일을 게시하기 전에 나는 code 다섯(`PARTIAL_WRITE`, `ATOMIC_PUBLISH_UNSUPPORTED`, `STORAGE_UNAVAILABLE`, `SERVER_BUSY`, `STORAGE_FULL`)이다. `SERVER_BUSY`(503)는 서버의 전송 permit이나 작업 pool이 찬 거절이고 `retryable: true`다. - `MAYBE_APPLIED`: 올라갔을 수도 있다. 응답을 잃음, 시간 초과, `details.ambiguous: true`, 그 밖의 5xx다. 504 `TRANSFER_TIMEOUT`도 여기 든다. 백엔드는 대기 시간이 지나면 작업이 어느 단계에 있든 이 code를 내고, 작업은 그 뒤에 끝나 `READY`가 될 수 있다. 다시 보낼 때는 같은 `idempotencyKey`를 쓴다. - 멱등성 응답(`IDEMPOTENT_*`, `IDEMPOTENCY_*`)과 V3 표에 있는 web 공통 응답은 V3 실행기와 같은 표(`backend-envelope.ts`, 4절)로 판정한다. 400 `IDEMPOTENCY_KEY_INVALID`·422 `IDEMPOTENT_REQUEST_MISMATCH`는 `NOT_APPLIED`, 409 `IDEMPOTENT_IN_FLIGHT`·503 `IDEMPOTENCY_UNAVAILABLE`·503 `IDEMPOTENCY_COMPLETION_UNKNOWN`·500 `IDEMPOTENCY_RECOVERY_REQUIRED`는 `MAYBE_APPLIED`다. - `APPLIED_CONFIRMED`: 서버는 만들었다고 답했지만 응답을 읽지 못했다. 다시 올리지 않는다. @@ -445,77 +445,74 @@ export function mapInvoiceCreateProblem( - client는 스스로 다시 보내지 않는다. `retryable: true`이고 `retryAfterMs`가 있으면 그만큼 기다린 뒤 기능이 다시 부른다. 서버가 상한(`maxRetryAfterMs`, 기본 30초)보다 길게 기다리라고 하면 `retryable: false`다. - `MAYBE_APPLIED`는 언제나 `retryable: false`다. 백엔드가 Envelope에 `retryable: true`와 `Retry-After`를 붙여도(504 `TRANSFER_TIMEOUT`) 기능이 자동으로 다시 부르지 않는다. 아래 주의대로 먼저 확인한다. -**주의 — 멱등 키**: 짝 백엔드(`45d2a478`)의 `POST /v1/files`는 멱등 키를 읽지 않는다(업로드 use case가 `NOT_IDEMPOTENT`). +**주의 — 멱등 키**: 짝 백엔드(pin `d32b4b53`)의 `POST /v1/files`는 멱등 키를 읽지 않는다(업로드 use case가 `NOT_IDEMPOTENT`). - 그래서 `MAYBE_APPLIED` 뒤 다시 보내면 같은 파일이 두 개 생길 수 있다. - 같은 키 재전송이 중복을 막는 것은 배포가 업로드를 백엔드 멱등성 executor 뒤에 둘 때뿐이다. - 그 전에는 다시 보내기 전에 업무 데이터(파일 목록 등)로 먼저 확인한다. -**어디에 적나**: 두 곳이다. +**어디에 적나**: 두 곳이다. 템플릿 파일은 고치지 않는다. -1. `src/bootstrap/product-composition.ts`: client를 만들 재료(주소, 인증 프로필, 자격 증명, 크기 상한)를 capability로 넘긴다. client 코드는 넘기지 않는다. 기능 adapter는 기능 runtime과 함께 늦게 적재되므로, 업로드 코드가 boot 번들이 아니라 기능 chunk에 든다. -2. 기능 `adapters/create--feature-input.ts`: `needs`에 그 capability를 적고, 거기서 `createFileserverUploadClient`를 부른다. +1. `src/bootstrap/product-composition.ts`: client를 만들 재료(주소, 인증 프로필, 자격 증명, 크기 상한)를 capability `fileserverUpload`로 넘긴다. client 코드는 넘기지 않는다. 기능 adapter는 기능 runtime과 함께 늦게 적재되므로, 업로드 코드가 boot 번들이 아니라 기능 chunk에 든다. + - 그 타입은 템플릿이 `FeaturePlatformCapabilities`에 opt-in 키로 선언해 두었다(`src/features/feature-adapter-contribution.ts`, `indexedDb`와 같다). `declare module`로 보강하지 않는다. `check:types:node`가 그 보강을 보지 못한다(매뉴얼 03). + - 자격 증명은 `context.credentials`를 펼친다. V3 요청과 같은 주인(scope fence → ANONYMOUS 프로필 → `credentialProviders` → 템플릿 세션)이 헤더를 붙이고, 업로드의 401도 V3 401과 같은 곳(제품 provider의 자격 증명이면 `onCredentialRejected`, 템플릿 세션의 것이면 세션)으로 간다. +2. 기능 `adapters/`: `create--feature-input.ts`의 `needs`에 `fileserverUpload`를 더하고, 받은 값으로 `createFileserverUploadClient`를 부른다. + ```ts -// src/bootstrap/product-composition.ts (제품 소유). BACKEND_SESSION은 -// src/contracts/product-contracts.ts에 더한 쿠키 세션 프로필이다. -import type { FileserverUploadClientDependencies } from "../adapters/http/index.ts"; -import { PRODUCT_REST_AUTH_PROFILES } from "../contracts/product-contracts.ts"; -// 파일에 이미 있는 import에 ProductCredentialProvider를 더한다. -import type { ProductCredentialProvider } from "./product-composition-contract.ts"; +// JWT·Keycloak 모드(템플릿 세션의 bearer, EXTERNAL_BEARER)의 예다. +import { REST_AUTH_PROFILES } from "../contracts/rest-profiles.ts"; +import type { + ProductComposition, + ProductCompositionContext, + ProductSessionOwner, + ProductSessionOwnerContext, +} from "./product-composition-contract.ts"; -declare module "../features/feature-adapter-contribution.ts" { - interface FeaturePlatformCapabilities { - readonly fileserverUpload: FileserverUploadClientDependencies; - } +export function composeProductSessionOwner( + context: ProductSessionOwnerContext, +): ProductSessionOwner { + return null; } export function composeProduct(context: ProductCompositionContext) { - const sessionCredentials: ProductCredentialProvider = () => { - if (!context.isScopeReady()) return { kind: "SCOPE_FENCED" }; - const csrf = context.readCookie("XSRF-TOKEN"); - return csrf === undefined - ? { kind: "UNAUTHENTICATED" } - : { kind: "READY", headers: { "x-xsrf-token": csrf } }; - }; return { capabilities: { fileserverUpload: { + ...context.credentials, baseUrl: context.config.API_BASE_URL, - authProfile: PRODUCT_REST_AUTH_PROFILES.BACKEND_SESSION, - attachCredentials: sessionCredentials, + authProfile: REST_AUTH_PROFILES.EXTERNAL_BEARER, maxFileBytes: 20 * 1024 * 1024, ...(context.fetcher === undefined ? {} : { fetcher: context.fetcher }), }, }, - credentialProviders: { BACKEND_SESSION: sessionCredentials }, - // BACKEND_SESSION은 세션 쿠키 그 자체다. 그 401은 세션을 로그아웃시킨다(5절). - onCredentialRejected: () => context.notifySessionUnauthenticated(), + credentialProviders: {}, } satisfies ProductComposition; } ``` + ```ts -// src/features//adapters/create--feature-input.ts -import { createFileserverUploadClient } from "../../../adapters/http/index.ts"; -import { defineFeatureAdapterContribution } from "../../feature-adapter-contribution.ts"; +import { + createFileserverUploadClient, + type FileserverUploadClient, +} from "../../../adapters/http/index.ts"; +import type { FeatureCapabilitySelection } from "../../feature-adapter-contribution.ts"; -export const createAttachmentFeatureInput = defineFeatureAdapterContribution({ - featureId: "attachment", - needs: ["http", "fileserverUpload"], - createInput: ({ http, fileserverUpload }) => { - const uploads = createFileserverUploadClient(fileserverUpload); - return { - featureId: "attachment", - // 기능 port 구현이 uploads.upload({ source, filename, mediaType, idempotencyKey, signal })를 부른다. - input: { /* … */ }, - }; - }, -}); +// create-invoice-feature-input.ts가 needs: ["http", "fileserverUpload"]로 받은 값을 넘긴다. +// 기능 port 구현이 uploads.upload({ source, filename, mediaType, idempotencyKey, signal })를 부른다. +export function createInvoiceAttachmentUploads({ + fileserverUpload, +}: FeatureCapabilitySelection<["fileserverUpload"]>): FileserverUploadClient { + return createFileserverUploadClient(fileserverUpload); +} ``` +- 이 두 조각도 `tests/unit/manual-code-blocks.test.ts`가 저장소 사본에 넣어 타입 검사한다. `product-composition.ts`는 제품 소유 파일이라 조각이 파일 전체를 바꾼다. +- 쿠키 세션 모드(Redis session, BFF)는 `authProfile`을 `src/contracts/product-contracts.ts`에 더한 쿠키 프로필(예: `BACKEND_SESSION`)로 바꾸고, `credentialProviders`에 그 프로필의 provider(XSRF 쿠키를 헤더로 붙이는 함수)를 둔다. `context.credentials`가 그 provider를 부른다. 그 provider는 세션 쿠키 자체를 보내므로 `onCredentialRejected: () => context.notifySessionUnauthenticated()`로 401을 세션에 알린다(5절). +- `context.credentials`를 펼치지 않고 `attachCredentials`만 직접 주면 업로드의 401이 아무에게도 가지 않는다. 화면은 로그인 상태로 남고 업로드만 `AUTH_REQUIRED`로 실패한다(매뉴얼 04). - `baseUrl`은 끝이 `/`여야 한다. `v1/files`를 그 아래에 붙인다. 경로가 base 밖으로 나가면 조립할 때 `TypeError`다. -- 자격 증명 함수는 V3 실행기의 `attachCredentials`와 계약이 같다. 같은 프로필의 `credentialProviders`를 그대로 쓴다. 프로필이 허락하지 않은 헤더를 주면 보내지 않고 `AUTH_INTEGRATION_FAILURE`다. +- 자격 증명 함수는 V3 실행기의 `attachCredentials`와 계약이 같다. 프로필이 허락하지 않은 헤더를 주면 보내지 않고 `AUTH_INTEGRATION_FAILURE`다. **틀리면** @@ -523,5 +520,5 @@ export const createAttachmentFeatureInput = defineFeatureAdapterContribution({ - 파일이 `maxFileBytes`보다 크면 읽기 전에 `FILE_TOO_LARGE`(`NOT_STARTED`)다. 비어 있으면 `FILE_EMPTY`(`NOT_STARTED`)다. - 202 응답을 모두 "검사 중"으로 보이면 `QUARANTINED` 파일의 화면이 끝나지 않는다. state마다 따로 보인다. - 멱등성·web 공통 응답의 판정은 V3 표를 그대로 쓴다. `tests/integration/fileserver-upload.test.ts`가 pin 옆에 복사한 백엔드 답 표(`config/contracts/backend-idempotency-answers.json`)의 행마다 client와 V3 표가 같은지 본다. pin을 옮기면 같이 다시 돈다. -- 백엔드가 Fileserver 응답 모양이나 Fileserver 자신의 code를 바꾸면 검사가 잡지 못한다. 그 표(`fileserver-upload.ts`의 `NOT_APPLIED_5XX_CODES`)는 백엔드 `45d2a478`(pin) 코드를 읽은 것이다. 백엔드 SHA가 바뀌면 `FileserverErrorCode`, `BlockingTransferExecutor`, 게시 경로를 같이 다시 본다. 4xx를 `NOT_APPLIED`로 보는 이유는 [계약 문서](../architecture/backend-api-and-server-state-contract.md) 6.1절에 있다. +- 백엔드가 Fileserver 응답 모양을 바꾸면 검사가 잡지 못한다. Fileserver 자신의 code 표(`fileserver-upload.ts`의 `NOT_APPLIED_5XX_CODES`)는 백엔드 pin 코드를 읽은 것이고, 읽은 파일과 표를 pin의 `backend.codeSources`에 적어 두었다. `tests/unit/backend-contract-pin.test.ts`가 둘을 대조하고, `check:backend-contract-drift`가 pin 뒤 백엔드에서 그 파일이 바뀌면 알린다. 4xx를 `NOT_APPLIED`로 보는 이유는 [계약 문서](../architecture/backend-api-and-server-state-contract.md) 6.1절에 있다. - 테스트 예: `tests/integration/fileserver-upload.test.ts`(백엔드 코드가 답하는 대로 답하는 MSW. 백엔드 문서는 202 `VERIFYING`만 적는다). diff --git a/docs/manual/03-outside-feature-folder.md b/docs/manual/03-outside-feature-folder.md index 9b9cd26c..c8b939d9 100644 --- a/docs/manual/03-outside-feature-folder.md +++ b/docs/manual/03-outside-feature-folder.md @@ -117,6 +117,7 @@ release admission refused for staging: - `tests/e2e/accessibility.spec.ts`: 기능마다 고치지 않는다. 경로 파라미터와 API 응답을 설치된 라우트·descriptor에서 만든다. 보호 페이지가 설치된 GET이 아닌 요청을 그리기 전에 보낼 때만 손본다. 자세한 동작은 [01 문서 6단계](01-add-a-feature.md#6단계-라우트). - `src/features/product-capabilities.ts`: `needs`에 템플릿이 만들지 않는 capability를 적었을 때. 그 capability의 타입을 `ProductFeaturePlatformCapabilities`에 적는다. - `product-composition.ts` 안에서 `FeaturePlatformCapabilities`를 보강(`declare module`)하면 `check:types:node`가 그 키를 보지 못한다. + - 템플릿이 타입만 선언한 opt-in 키(`indexedDb`, 짝 백엔드 업로드 `fileserverUpload`)는 여기 다시 적지 않는다. `product-composition.ts`에서 값만 돌려준다([02 결정표 7절](02-decision-tables.md#7-파일-업로드)). - `src/bootstrap/product-composition.ts`: 위 capability의 값을 돌려줄 때. 제품 인증 프로필의 자격 증명도 여기서 준다. - 로그아웃·계정 전환 때 닫아야 하는 것(파일 runtime 등)은 `scopeParticipants`로 돌려준다. 예제: `recipes/frontend-capabilities/browser-file-session-capability.ts`. - `label`은 `browser-files` 같은 소문자 kebab-case 토큰으로 쓴다. 다른 형식이면 조립이 `TypeError`로 멈춘다. @@ -176,12 +177,14 @@ src/features/product-capabilities.ts (SERVICE_WORKER = ACTIVE) serviceWorker: { blockers: [() => hasUnsavedEdits()], observe: (observation) => reportServiceWorker(observation), + onUpdateWaiting: (activate) => showUpdateNotice({ onAccept: activate }), + onReloadRequired: () => showReloadNotice(), }, } satisfies ProductComposition; } ``` -- 템플릿이 아직 연결하지 않은 것: 활성화 화면(`onUpdateWaiting`·`requestActivation()`). 확인할 것 목록은 `docs/architecture/optional-adapter-recipes.md`의 "Service Worker를 켤 때 확인할 것"에 있다. +- 활성화 화면도 같은 자리다(1103/09-05). `onUpdateWaiting`은 새 버전이 설치되어 기다릴 때(worker가 시작할 때 이미 기다리고 있던 것도) 불리고, 받은 `activate()`가 `requestActivation()`이다. 그래서 `blockers`가 그대로 걸린다. `onReloadRequired`는 다른 빌드의 worker가 넘겨받았을 때 불린다. 둘 다 던져도 worker 흐름은 바뀌지 않는다. 화면(`showUpdateNotice` 등)은 제품 것이다. 확인할 것 목록은 `docs/architecture/optional-adapter-recipes.md`의 "Service Worker를 켤 때 확인할 것"에 있다. - realtime·Web Worker·오프라인 명령을 고르면 조립이 `Selected optional capabilities have no runtime to start them`로 거절한다. 템플릿 조립에 아직 그 런타임이 없다. ### Web Worker를 들일 때 tsconfig 더하기 diff --git a/docs/manual/04-paired-backend-session.md b/docs/manual/04-paired-backend-session.md index 9a9b6b2c..3602578f 100644 --- a/docs/manual/04-paired-backend-session.md +++ b/docs/manual/04-paired-backend-session.md @@ -7,7 +7,7 @@ - 템플릿에는 demo owner만 있다. demo는 `APP_ENV=local`에서만 켜지고, 그 표식 토큰은 백엔드 JWT 검증을 통과하지 못한다. - `AUTH_MODE: "external"`인데 owner가 없으면 세션은 `integration-failed`로 닫히고, 인증이 필요한 화면은 "로그인 연동이 필요합니다"를 보인다. -이 문서의 백엔드 사실은 백엔드 `bbe944bd` 기준이다. 백엔드가 인증 설정을 바꾸면 이 문서와 recipe를 함께 맞춘다. +이 문서의 백엔드 사실은 짝 계약 pin(`config/contracts/backend-contract-pin.json`, 지금 백엔드 `d32b4b53`) 기준이다. pin을 옮기거나 백엔드가 인증 설정을 바꾸면 이 문서와 recipe를 함께 맞춘다. --- @@ -26,9 +26,9 @@ 백엔드 근거 위치: - 두 모드의 보안 체인: `clean-architecture-backend-template/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/auth/SecurityConfig.java` -- 쿠키·CSRF 이름과 모드 기본값: `clean-architecture-backend-template/src/app-bootstrap/src/main/resources/config/security.yml` -- local issuer·audience·CORS: `clean-architecture-backend-template/src/app-bootstrap/src/main/resources/application-local.yml` -- realm: `clean-architecture-backend-template/infra/keycloak/realms/ca-skeleton-realm.json` +- 쿠키·CSRF 이름과 모드 기본값: `clean-architecture-backend-template/src/bootstrap/app/src/main/resources/config/security.yml` +- local issuer·audience·CORS: `clean-architecture-backend-template/src/bootstrap/app/src/main/resources/application-local.yml` +- realm: `clean-architecture-backend-template/compose/keycloak/realms/ca-skeleton-realm.json` --- @@ -108,7 +108,7 @@ realm JSON의 `clients`에 넣거나 Keycloak 관리 화면에서 같은 값으 } ``` -- audience mapper가 꼭 있어야 한다. 백엔드는 access token의 `aud`에 `APP_SECURITY_JWT_AUDIENCE`(local 기본 `ca-skeleton-api`)가 없으면 401 `AUTH_AUDIENCE_MISMATCH`로 거부한다. +- audience mapper가 꼭 있어야 한다. 백엔드는 access token의 `aud`에 `APP_SECURITY_JWT_AUDIENCE`(local 기본 `ca-skeleton-api`, 쉼표로 여럿을 적으면 하나만 맞아도 된다)가 없으면 401 `AUTH_AUDIENCE_MISMATCH`로 거부한다. - `webOrigins`는 브라우저가 토큰 엔드포인트를 부를 때의 CORS 허용이다. - realm에는 사람 사용자가 없다. local에서는 관리 화면에서 사용자를 하나 만들고 realm role `user`를 준다. - 백엔드 권한은 `realm_access.roles`와 `resource_access.ca-skeleton-api.roles`에서 온다. 쓰기 권한이 필요하면 그 사용자에게 `ca-skeleton-api`의 client role을 준다(`clean-architecture-backend-template/docs/manual/07-authorization.md`). @@ -189,6 +189,7 @@ export function composeProductSessionOwner( ``` - 서버 401이 세션에 닿는 길은 4.3의 `onCredentialRejected` 한 줄뿐이다. 템플릿은 제품 provider가 낸 자격 증명의 401을 제품에만 알린다([02 결정표](02-decision-tables.md) 5절). 이 줄을 빼면 서버 세션이 끝나도(Redis TTL 만료, 다른 탭·서버에서 로그아웃) 화면은 로그인 상태로 남고, 요청마다 `AUTH_REQUIRED` 실패 화면만 보인다. +- Fileserver 업로드처럼 제품이 직접 보내는 요청도 같은 길을 쓴다. 업로드 capability에 `context.credentials`를 펼치면 그 401도 `onCredentialRejected`로 간다([02 결정표](02-decision-tables.md) 7절). - CSRF: 다른 사이트가 사용자의 쿠키로 쓰기를 보내는 공격이다. 백엔드는 스크립트가 읽을 수 있는 `XSRF-TOKEN` 쿠키를 주고, 쓰기 요청의 `X-XSRF-TOKEN` 헤더가 그 값과 같은지 본다. 다른 사이트의 스크립트는 이 쿠키를 읽지 못한다. - 백엔드는 plain 방식이다(`CsrfTokenRequestAttributeHandler`). 쿠키 값을 그대로 헤더에 넣는다. diff --git a/recipes/session-owners/oidc-pkce-session-owner.ts b/recipes/session-owners/oidc-pkce-session-owner.ts index 07a04b4c..543f3734 100644 --- a/recipes/session-owners/oidc-pkce-session-owner.ts +++ b/recipes/session-owners/oidc-pkce-session-owner.ts @@ -34,7 +34,7 @@ import { STORAGE_REGISTRY } from "../../src/contracts/storage-keys.ts"; * State transitions follow `SessionState` in * `src/application/ports/auth-session-port.ts`. * - * The backend's realm (`infra/keycloak/realms/ca-skeleton-realm.json` there) + * The backend's realm (`compose/keycloak/realms/ca-skeleton-realm.json` there) * has only a confidential service client; a product registers the public * client this owner signs in with. Copy this file into `src/bootstrap/` and * return it from `composeProductSessionOwner`; `docs/manual/04-paired-backend-session.md` diff --git a/scripts/check-backend-contract-drift.ts b/scripts/check-backend-contract-drift.ts index 59538215..e9c1416c 100644 --- a/scripts/check-backend-contract-drift.ts +++ b/scripts/check-backend-contract-drift.ts @@ -23,13 +23,16 @@ import { * (`backend.scaffoldSources`) that `create:feature --with-create` copies * four facts from (path plural rule, name limit, error codes, check * order). Each changed file names the frontend copy to recheck. + * 5. 1105/01-02: nor have the backend code files (`backend.codeSources`) + * the frontend reads a code table from, such as the Fileserver codes the + * upload client reads as refused before publishing. * * corepack pnpm check:backend-contract-drift [--backend ] [--write-excerpt] * * `--write-excerpt` copies the excerpt from the pinned commit first: run it * after moving the pin, then fix the answer table until this passes. * - * Exit 0: all four hold. Exit 1: one does not; the output names the rows or + * Exit 0: all five hold. Exit 1: one does not; the output names the rows or * files. Recheck the frontend contract 6.1 table, the answer table, the * excerpt, the generator copies and the pin in one change. Exit 2: nothing * was compared (no checkout, or the pinned commit or document is missing), @@ -46,12 +49,15 @@ type ScaffoldSource = Readonly<{ copiedTo: Readonly<{ file: string; symbol: string }>; }>; +type CodeSource = ScaffoldSource & Readonly<{ codes?: readonly string[] }>; + type Pin = Readonly<{ backend: Readonly<{ repository: string; commit: string; document: string; scaffoldSources?: readonly ScaffoldSource[]; + codeSources?: readonly CodeSource[]; }>; tables: Readonly<{ idempotencyAnswers: string; backendExcerpt: string }>; notCopied: readonly NotCopiedRow[]; @@ -103,6 +109,7 @@ function main(): void { const directory = backendDirectory(pin); const { commit, document } = pin.backend; const scaffoldSources = pin.backend.scaffoldSources ?? []; + const codeSources = pin.backend.codeSources ?? []; if (!existsSync(path.join(directory, ".git"))) { cannotCompare( `No ${pin.backend.repository} checkout at ${directory}; pass --backend . test:unit holds the answer table to ${pin.tables.backendExcerpt}, and only this script holds that copy to the backend.`, @@ -136,6 +143,13 @@ function main(): void { } const excerpt = readJson(pin.tables.backendExcerpt); const failures: string[] = []; + // A copied source the pinned commit does not have is a path the pin got + // wrong (a moved file), and a diff against HEAD would read it as deleted. + for (const source of [...scaffoldSources, ...codeSources]) { + if (git(directory, "cat-file", "-e", `${commit}:${source.path}`).status !== 0) { + failures.push(`${source.path} is not in the pinned ${commit.slice(0, 12)}: fix its path in ${PIN_PATH}`); + } + } const source = excerpt.source; if (source.repository !== pin.backend.repository || source.commit !== commit || source.document !== document) { @@ -167,14 +181,19 @@ function main(): void { } } // 1105/16-02. The generator's copies of backend scaffold facts. - for (const scaffold of scaffoldSources) { - const scaffoldDiff = git(directory, "diff", "--unified=0", `${commit}..HEAD`, "--", scaffold.path); - if (scaffoldDiff.stdout.trim() === "") continue; + // 1105/01-02. The frontend's copies of backend code tables. + const sources = [ + ...scaffoldSources.map((source) => ({ source, kind: "scaffold", reader: "the generator" })), + ...codeSources.map((source) => ({ source, kind: "code", reader: "the frontend" })), + ]; + for (const { source, kind, reader } of sources) { + const sourceDiff = git(directory, "diff", "--unified=0", `${commit}..HEAD`, "--", source.path); + if (sourceDiff.stdout.trim() === "") continue; failures.push( - `scaffold source ${scaffold.path} changed between the pin ${commit.slice(0, 12)} and HEAD ${headCommit.slice(0, 12)}`, + `${kind} source ${source.path} changed between the pin ${commit.slice(0, 12)} and HEAD ${headCommit.slice(0, 12)}`, ); failures.push( - ` the generator copies "${scaffold.fact}" from it: recheck ${scaffold.copiedTo.symbol} in ${scaffold.copiedTo.file}`, + ` ${reader} copies "${source.fact}" from it: recheck ${source.copiedTo.symbol} in ${source.copiedTo.file}`, ); } } @@ -183,14 +202,14 @@ function main(): void { console.log( headCommit === commit ? `Backend contract drift: ${directory} is at the pinned ${commit.slice(0, 12)}; the excerpt and the answer table match it` - : `Backend contract drift: HEAD ${headCommit.slice(0, 12)} is past the pin ${commit.slice(0, 12)}, ${document} and ${scaffoldSources.length} scaffold sources unchanged; the excerpt and the answer table match it`, + : `Backend contract drift: HEAD ${headCommit.slice(0, 12)} is past the pin ${commit.slice(0, 12)}, ${document}, ${scaffoldSources.length} scaffold sources and ${codeSources.length} code sources unchanged; the excerpt and the answer table match it`, ); return; } console.error("Backend contract drift:"); for (const failure of failures) console.error(` ${failure}`); console.error( - `Recheck docs/architecture/backend-api-and-server-state-contract.md 6.1, ${pin.tables.idempotencyAnswers}, ${pin.tables.backendExcerpt}, the generator copies of changed scaffold sources and ${PIN_PATH} together.`, + `Recheck docs/architecture/backend-api-and-server-state-contract.md 6.1, ${pin.tables.idempotencyAnswers}, ${pin.tables.backendExcerpt}, the copies of changed scaffold and code sources and ${PIN_PATH} together.`, ); process.exitCode = 1; } diff --git a/scripts/generate-service-worker-assets.ts b/scripts/generate-service-worker-assets.ts index 7f949d13..62c601e1 100644 --- a/scripts/generate-service-worker-assets.ts +++ b/scripts/generate-service-worker-assets.ts @@ -94,6 +94,13 @@ export async function collectStaticAssets( }); } + // 0925/06-08. Nothing under the directory means vite.config.ts moved the + // hashed files (`build.assetsDir`) away from the one the worker reads. + if (assets.length === 0) { + throw new Error( + `No hashed static asset under ${BUILD_ASSET_DIRECTORY} in the build: vite.config.ts build.assetsDir must name the directory BUILD_ASSET_DIRECTORY (src/contracts/service-worker.ts) names.`, + ); + } // 1112/06-02. The count and the bound, so the failure says how far over // it is. Each generated feature adds its lazy chunks here: with the Service // Worker on, the asset bound can come before the initial JavaScript budget. diff --git a/src/adapters/http/fileserver-upload.ts b/src/adapters/http/fileserver-upload.ts index 5e21d39d..a95113e9 100644 --- a/src/adapters/http/fileserver-upload.ts +++ b/src/adapters/http/fileserver-upload.ts @@ -37,8 +37,8 @@ import type { AuthOperationContext } from "./http-execution-v3.ts"; /** * 2026-11-03 01-01. A client for the paired backend Fileserver's multipart - * single upload, `POST /v1/files` (clean-architecture-backend-template - * `45d2a478`, the commit config/contracts/backend-contract-pin.json pins; + * single upload, `POST /v1/files` (clean-architecture-backend-template at + * the commit config/contracts/backend-contract-pin.json pins; * docs/fileserver/http-contract.md and its code; Envelope and idempotency in * docs/web/http-contract.md §1–§2). * @@ -115,7 +115,7 @@ export type FileserverUploadRequest = Readonly<{ mediaType?: string; /** * Sent as `Idempotency-Key`. After a `MAYBE_APPLIED` failure, resend with - * the same key and never a new one. At `45d2a478` the backend runs + * the same key and never a new one. At the pinned backend commit it runs * `POST /v1/files` without its idempotency executor, so the key protects * only a deployment that routes the upload through it. */ @@ -143,6 +143,16 @@ export type FileserverUploadClientDependencies = Readonly<{ }>, context: AuthOperationContext, ): Promise | CredentialPatchOutcome; + /** + * 1112/07-01. Called once when the server answers an upload 401, with the + * operation and the profile, before the `AUTH_REQUIRED` failure returns. + * The V3 executor's 401 goes to whoever supplied the credential; pass the + * composition's `credentials` (both fields) so the upload's goes the same + * way. A throw is ignored. + */ + onUnauthenticated?( + binding: Readonly<{ operationId: string; authProfileId: string }>, + ): void; /** A larger file is refused before it is read. */ maxFileBytes: number; fetcher?: typeof fetch; @@ -179,10 +189,11 @@ const MAX_FILENAME_LENGTH = 255; * its worker raises except an ambiguous completion, and the Fileserver * contract marks a failure that may already have taken effect with * `details.ambiguous`. So a 4xx Envelope is NOT_APPLIED unless it says - * otherwise. A 5xx stays MAYBE_APPLIED except these codes, which the worker + * otherwise. A 5xx stays MAYBE_APPLIED except these codes, which the backend * raises before the file is published (`FileserverErrorCode`, - * `AtomicMoveContentPublisher`). Recheck the list when the pinned backend - * commit moves; contract §6.1 says why the 4xx reading differs from its + * `AtomicMoveContentPublisher`). The pin names those backend files + * (`backend.codeSources`), so check:backend-contract-drift says when one + * changes; contract §6.1 says why the 4xx reading differs from its * fileserver row. * * 1105/01-02. 504 TRANSFER_TIMEOUT is not here. The waiting servlet thread @@ -195,9 +206,23 @@ const NOT_APPLIED_5XX_CODES: ReadonlySet = new Set([ "PARTIAL_WRITE", "ATOMIC_PUBLISH_UNSUPPORTED", "STORAGE_UNAVAILABLE", + // 1112/02-05. From backend `697e62e8c` the instance permit and the transfer + // pool answer a full server with 503 SERVER_BUSY where they answered 429 + // TRANSFER_ADMISSION_REJECTED, still before the work runs + // (`TransferAdmissionController`, `BlockingTransferExecutor`). + "SERVER_BUSY", "STORAGE_FULL", ]); +/** + * 1105/01-02. The codes above, for the test that holds them to the copy the + * pin keeps beside the backend files they were read from + * (config/contracts/backend-contract-pin.json `backend.codeSources`). + */ +export function notAppliedFileserver5xxCodes(): readonly string[] { + return Object.freeze([...NOT_APPLIED_5XX_CODES]); +} + /** * 1105/01-02. The web contract's own answers (idempotency §2, and the other * codes the V3 table lists) read as the V3 executor reads them, so the same @@ -320,6 +345,7 @@ type Settings = Readonly<{ url: string; authProfile: RestAuthProfile; attachCredentials: FileserverUploadClientDependencies["attachCredentials"]; + onUnauthenticated: FileserverUploadClientDependencies["onUnauthenticated"]; maxFileBytes: number; timeoutMs: number; minTransferBytesPerSecond: number; @@ -363,6 +389,12 @@ function snapshotDependencies( if (typeof dependencies.attachCredentials !== "function") { invalid("attachCredentials"); } + if ( + dependencies.onUnauthenticated !== undefined && + typeof dependencies.onUnauthenticated !== "function" + ) { + invalid("onUnauthenticated"); + } const positive = (value: number | undefined, fallback: number, field: string) => { const resolved = value ?? fallback; return Number.isSafeInteger(resolved) && resolved > 0 @@ -377,6 +409,7 @@ function snapshotDependencies( requiredCredentialHeaders: Object.freeze([...profile.requiredCredentialHeaders]), }), attachCredentials: dependencies.attachCredentials, + onUnauthenticated: dependencies.onUnauthenticated, maxFileBytes: positive(dependencies.maxFileBytes, 0, "maxFileBytes"), timeoutMs: positive(dependencies.timeoutMs, DEFAULTS.timeoutMs, "timeoutMs"), minTransferBytesPerSecond: positive( @@ -608,6 +641,19 @@ async function credentialHeaders( } } +function reportUnauthenticated(settings: Settings): void { + try { + settings.onUnauthenticated?.( + Object.freeze({ + operationId: FILESERVER_UPLOAD_OPERATION_ID, + authProfileId: settings.authProfile.authProfileId, + }), + ); + } catch { + // A hook defect cannot change the upload's own outcome. + } +} + async function readAnswer( response: Response, attempt: AbortableOperation, @@ -616,6 +662,9 @@ async function readAnswer( sentBytes: number, ): Promise> { const status = response.status; + // 1112/07-01. The server's verdict on the credential this upload carried, + // whatever the body says, as a V3 401 is. + if (status === 401) reportUnauthenticated(settings); const created = status === 201 || status === 202; // A 2xx the contract does not list says something happened; what is unknown. const effect: FailureEffectCertainty = created diff --git a/src/adapters/service-worker/service-worker-entry.ts b/src/adapters/service-worker/service-worker-entry.ts index de2614d6..35dd72a7 100644 --- a/src/adapters/service-worker/service-worker-entry.ts +++ b/src/adapters/service-worker/service-worker-entry.ts @@ -9,7 +9,10 @@ import { createServiceWorkerRuntime, type WorkerScopeLike, } from "./service-worker-lifecycle.ts"; -import { parseServiceWorkerMessage } from "./service-worker-protocol.ts"; +import { + createServiceWorkerMessage, + parseServiceWorkerMessage, +} from "./service-worker-protocol.ts"; /** * §17.1. The one physical worker entry for this scope. @@ -166,12 +169,14 @@ if (handlers.includes("OFFLINE_SYNC_WAKEUP")) { event.waitUntil( self.clients.matchAll({ type: "window" }).then((clients) => { for (const client of clients) { - client.postMessage({ - protocolVersion: 1, - kind: "SYNC_WAKE_OBSERVED", - messageId: crypto.randomUUID(), - sourceBuildId: identity.buildId, - }); + // 1101 R3. Built like every other message, so a protocol version + // change reaches this one too. + client.postMessage( + createServiceWorkerMessage({ + kind: "SYNC_WAKE_OBSERVED", + sourceBuildId: identity.buildId, + }), + ); } }), ); diff --git a/src/adapters/service-worker/service-worker-lifecycle.ts b/src/adapters/service-worker/service-worker-lifecycle.ts index 61ece109..eda14a52 100644 --- a/src/adapters/service-worker/service-worker-lifecycle.ts +++ b/src/adapters/service-worker/service-worker-lifecycle.ts @@ -161,12 +161,12 @@ export function createServiceWorkerRuntime( const previous = highestOld?.cacheName ?? oldCaches.at(-1) ?? null; // Q-6.6-9. Stale caches go first: when storage is full the marker write // below is what fails, and deleting is the only way space comes back. + // The current cache and one previous one (the rollback target) stay. const stale = selectCachesToDelete(names, current, previous); let deleted = 0; for (const name of stale) { if (await scope.caches.delete(name).catch(() => false)) deleted += 1; } - void SERVICE_WORKER_BOUNDS.retainedPreviousCaches; if ( !currentMarker || currentMarker.activationSequence < (highestOld?.activationSequence ?? 0) diff --git a/src/adapters/service-worker/service-worker-page-controller.ts b/src/adapters/service-worker/service-worker-page-controller.ts index c9c5f1e1..016025f6 100644 --- a/src/adapters/service-worker/service-worker-page-controller.ts +++ b/src/adapters/service-worker/service-worker-page-controller.ts @@ -188,6 +188,9 @@ export function createServiceWorkerPageController( if (registration.waiting) { observe("register", "UPDATE_WAITING"); + // 1103/09-05. The waiting update was installed before this page looked; + // its listeners hear it as they hear one found later. + notify(updateWaitingListeners); return Object.freeze({ kind: "UPDATE_WAITING" as const }); } // R-6.4. On a first visit `register()` resolves while the only worker is @@ -339,6 +342,10 @@ export function createServiceWorkerPageController( watched.active ) { notify(updateWaitingListeners); + } else if (worker.state === "redundant" && watched.active) { + // 0925/06-05. An update that failed to install leaves this page on + // its build with nothing waiting; only this record says why. + observe("update_install", "REDUNDANT"); } }); }; @@ -357,7 +364,9 @@ export function createServiceWorkerPageController( updateTimer = setInterval(() => { if (page?.visibilityState === "hidden") return; void registration?.update().catch(() => { - // A failed update check never fails a product flow. + // A failed update check never fails a product flow. 0925/06-05: it is + // recorded, so a deployment that never updates says so. + observe("update_check", "FAILED"); }); }, SERVICE_WORKER_BOUNDS.updateCheckIntervalMs); } diff --git a/src/adapters/service-worker/service-worker-protocol.ts b/src/adapters/service-worker/service-worker-protocol.ts index 45ebec3b..2146446d 100644 --- a/src/adapters/service-worker/service-worker-protocol.ts +++ b/src/adapters/service-worker/service-worker-protocol.ts @@ -13,9 +13,6 @@ import { */ const MESSAGE_KINDS: ReadonlySet = new Set([ - "PAGE_HELLO", - "WORKER_HELLO_ACK", - "UPDATE_READY", "ACTIVATE_REQUEST", "ACTIVATE_ACCEPTED", "ACTIVATE_REJECTED", diff --git a/src/adapters/service-worker/service-worker-static-assets.ts b/src/adapters/service-worker/service-worker-static-assets.ts index 4affcdb0..51955ebe 100644 --- a/src/adapters/service-worker/service-worker-static-assets.ts +++ b/src/adapters/service-worker/service-worker-static-assets.ts @@ -125,6 +125,9 @@ export function validateStaticAssetManifest( ) { return rejected("MANIFEST_INVALID"); } + // 0925/06-08. A build whose `build.assetsDir` left `BUILD_ASSET_DIRECTORY` + // generates no assets; installing that would serve nothing, silently. + if (manifest.assets.length === 0) return rejected("MANIFEST_INVALID"); if (manifest.assets.length > bounds.assets) { return rejected("ASSET_COUNT_EXCEEDED"); } @@ -233,6 +236,7 @@ async function installCandidate( const queue = [...manifest.assets]; let failure: InstallOutcome | null = null; + const previous = await previousStaticCaches(dependencies.caches, cacheName); const worker = async (): Promise => { for (;;) { @@ -244,7 +248,9 @@ async function installCandidate( } const asset = queue.shift(); if (!asset) return; - const outcome = await storeAsset(asset, cache, dependencies, signal); + const outcome = (await reuseVerifiedAsset(asset, cache, previous, dependencies, signal)) + ? null + : await storeAsset(asset, cache, dependencies, signal); if (outcome) { failure ??= outcome; abortController.abort(); @@ -265,6 +271,67 @@ async function installCandidate( }); } +/** + * 1101/06-05. The verified caches of earlier releases still in this origin, + * newest last. Each asset URL is content-hashed, so an unchanged file keeps + * its URL from release to release. + */ +async function previousStaticCaches( + caches: InstallDependencies["caches"], + cacheName: string, +): Promise { + try { + const names = ((await caches.keys?.()) ?? []).filter( + (name) => isOwnedStaticCacheName(name) && name !== cacheName, + ); + return Object.freeze(await Promise.all(names.map((name) => caches.open(name)))); + } catch { + return Object.freeze([]); + } +} + +/** + * 1101/06-05. Copies an asset an earlier release already cached instead of + * downloading it again, after checking its bytes against this manifest's + * digest exactly as a download is checked. Anything else (no copy, another + * size or digest, a cache that throws) is a miss and the asset is fetched. + */ +async function reuseVerifiedAsset( + asset: StaticAssetManifestV1["assets"][number], + cache: Cache, + previous: readonly Cache[], + dependencies: InstallDependencies, + signal: AbortSignal, +): Promise { + for (const candidate of [...previous].reverse()) { + if (signal.aborted) return false; + try { + const found = await abortable(Promise.resolve(candidate.match(asset.url)), signal); + if (found === ABORTED) return false; + if (!found || found.status !== 200) continue; + // The copy keeps its stored headers, so they pass the download's check. + if (!contentTypeMatches(found, asset.contentType)) continue; + const body = await readBoundedBody(found, asset.bytes, signal); + if (!body.ok) continue; + const digest = await abortable(Promise.resolve(dependencies.digest(body.bytes)), signal); + if (digest === ABORTED) return false; + if (digest !== asset.sha256) continue; + await cache.put( + asset.url, + new Response(body.bytes.slice(), { + status: found.status, + statusText: found.statusText, + headers: found.headers, + }), + ); + return true; + } catch { + // A broken earlier cache is a miss, never an install failure. + } + } + return false; +} + async function storeAsset( asset: StaticAssetManifestV1["assets"][number], cache: Cache, @@ -298,18 +365,7 @@ async function storeAsset( if (response.status !== 200 || response.type === "opaque") { return rejected("STATUS_INVALID"); } - const contentType = - response.headers.get("content-type")?.split(";", 1)[0]?.trim().toLowerCase() ?? - ""; - const expectedType = asset.contentType.toLowerCase(); - if ( - contentType !== expectedType && - // R-6.5. Servers still send `application/javascript` for `.js`. - !( - JAVASCRIPT_MIME_TYPES.has(contentType) && - JAVASCRIPT_MIME_TYPES.has(expectedType) - ) - ) { + if (!contentTypeMatches(response, asset.contentType)) { return rejected("CONTENT_TYPE_INVALID"); } @@ -347,6 +403,18 @@ async function storeAsset( return null; } +function contentTypeMatches(response: Response, expected: string): boolean { + const contentType = + response.headers.get("content-type")?.split(";", 1)[0]?.trim().toLowerCase() ?? + ""; + const expectedType = expected.toLowerCase(); + return ( + contentType === expectedType || + // R-6.5. Servers still send `application/javascript` for `.js`. + (JAVASCRIPT_MIME_TYPES.has(contentType) && JAVASCRIPT_MIME_TYPES.has(expectedType)) + ); +} + /** WHATWG MIME Sniffing: every essence that denotes a JavaScript MIME type. */ const JAVASCRIPT_MIME_TYPES: ReadonlySet = new Set([ "application/ecmascript", diff --git a/src/adapters/web-push/inbound/notification-click-adapter.ts b/src/adapters/web-push/inbound/notification-click-adapter.ts index 4faab467..af343889 100644 --- a/src/adapters/web-push/inbound/notification-click-adapter.ts +++ b/src/adapters/web-push/inbound/notification-click-adapter.ts @@ -7,7 +7,10 @@ import { type WebPushObserver, type WebPushResult, } from "../../../contracts/web-push.ts"; -import type { PushAssociationFenceStore } from "../push-association-fence-store.ts"; +import { + type PushAssociationFenceStore, + validateActivePushFence, +} from "../push-association-fence-store.ts"; import { decodeNotificationClickData } from "../push-codec.ts"; import type { WebPushNotificationRegistry } from "../notification-registry.ts"; import { @@ -353,30 +356,17 @@ export function createNotificationClickAdapter(dependencies: Readonly<{ ); } - async function validateActiveFence( + function validateActiveFence( associationEpoch: string, releaseEpoch: string, signal: AbortSignal, ): Promise> { - const control = await dependencies.fenceStore.read({ signal }); - if (!control.ok) return control; - if ( - !control.value || - control.value.control.association.state !== "ACTIVE" || - control.value.control.association.associationEpoch !== - associationEpoch - ) { - return webPushFailure( - "ASSOCIATION_MISMATCH", - "NOTIFICATION_CLICK", - ); - } - return control.value.control.releaseEpoch === releaseEpoch - ? webPushSuccess(undefined) - : webPushFailure( - "RELEASE_MISMATCH", - "NOTIFICATION_CLICK", - ); + return validateActivePushFence( + dependencies.fenceStore, + { associationEpoch, releaseEpoch }, + "NOTIFICATION_CLICK", + signal, + ); } } diff --git a/src/adapters/web-push/inbound/push-event-adapter.ts b/src/adapters/web-push/inbound/push-event-adapter.ts index 9b15f5b0..0ced1eaa 100644 --- a/src/adapters/web-push/inbound/push-event-adapter.ts +++ b/src/adapters/web-push/inbound/push-event-adapter.ts @@ -6,7 +6,10 @@ import { type WebPushObserver, type WebPushResult, } from "../../../contracts/web-push.ts"; -import type { PushAssociationFenceStore } from "../push-association-fence-store.ts"; +import { + type PushAssociationFenceStore, + validateActivePushFence, +} from "../push-association-fence-store.ts"; import { clickDataFromHint, decodeWebPushHint, @@ -193,23 +196,16 @@ export function createPushEventAdapter(dependencies: Readonly<{ return webPushSuccess(undefined); } - async function validateActiveFence( + function validateActiveFence( associationEpoch: string, releaseEpoch: string, signal: AbortSignal, ): Promise> { - const control = await dependencies.fenceStore.read({ signal }); - if (!control.ok) return control; - if ( - !control.value || - control.value.control.association.state !== "ACTIVE" || - control.value.control.association.associationEpoch !== - associationEpoch - ) { - return webPushFailure("ASSOCIATION_MISMATCH", "PUSH_HANDLE"); - } - return control.value.control.releaseEpoch === releaseEpoch - ? webPushSuccess(undefined) - : webPushFailure("RELEASE_MISMATCH", "PUSH_HANDLE"); + return validateActivePushFence( + dependencies.fenceStore, + { associationEpoch, releaseEpoch }, + "PUSH_HANDLE", + signal, + ); } } diff --git a/src/adapters/web-push/push-association-fence-store.ts b/src/adapters/web-push/push-association-fence-store.ts index 6bf49044..5cfb5f39 100644 --- a/src/adapters/web-push/push-association-fence-store.ts +++ b/src/adapters/web-push/push-association-fence-store.ts @@ -144,6 +144,32 @@ export interface PushAssociationFenceStore { close(): void; } +/** + * 1101 R2. The fence a push and a notification click both pass before they + * act: an ACTIVE association with the same epoch, then the same release. + * One copy, so the two inbound adapters cannot drift apart. + */ +export async function validateActivePushFence( + fenceStore: Pick, + expected: Readonly<{ associationEpoch: string; releaseEpoch: string }>, + operation: WebPushOperation, + signal: AbortSignal, +): Promise> { + const control = await fenceStore.read({ signal }); + if (!control.ok) return control; + if ( + !control.value || + control.value.control.association.state !== "ACTIVE" || + control.value.control.association.associationEpoch !== + expected.associationEpoch + ) { + return webPushFailure("ASSOCIATION_MISMATCH", operation); + } + return control.value.control.releaseEpoch === expected.releaseEpoch + ? webPushSuccess(undefined) + : webPushFailure("RELEASE_MISMATCH", operation); +} + export type PushAssociationFenceStoreDependencies = Readonly<{ repository: PushControlRepository; idempotencyKeyFactory?: () => string; diff --git a/src/bootstrap/create-runtime-composition.ts b/src/bootstrap/create-runtime-composition.ts index a6eea582..e6a660d3 100644 --- a/src/bootstrap/create-runtime-composition.ts +++ b/src/bootstrap/create-runtime-composition.ts @@ -68,11 +68,17 @@ export async function createRuntimeComposition( : {}), }); + const disconnectProductServiceWorker = connectProductServiceWorker( + optional.serviceWorker, + productServiceWorker, + ); + return Object.freeze({ ...root, capabilities, optional, async dispose(): Promise { + disconnectProductServiceWorker(); // §20.3. Optional runtime first, then the base infrastructure: the query // cache is cleared only after realtime and worker admission has closed, // so a late effect cannot repopulate a cleared cache. @@ -113,3 +119,42 @@ function serviceWorkerWiring( : {}), }; } + +/** + * 1103/09-05. The product's update notice and reload prompt, subscribed + * before the worker starts so a waiting update found at start reaches them. + * Their throws are product code and are dropped. Returns the unsubscribe. + */ +function connectProductServiceWorker( + host: OptionalRuntimeHost["serviceWorker"], + wiring: ProductServiceWorkerWiring | null | undefined, +): () => void { + if (!host || !wiring) return () => {}; + const unsubscribes: (() => void)[] = []; + const { onUpdateWaiting, onReloadRequired } = wiring; + if (onUpdateWaiting && host.onUpdateWaiting) { + unsubscribes.push( + host.onUpdateWaiting(() => { + try { + onUpdateWaiting(() => host.requestActivation()); + } catch { + // A failing product notice never changes the worker's outcome. + } + }), + ); + } + if (onReloadRequired && host.onReloadRequired) { + unsubscribes.push( + host.onReloadRequired(() => { + try { + onReloadRequired(); + } catch { + // As above. + } + }), + ); + } + return () => { + for (const unsubscribe of unsubscribes.splice(0)) unsubscribe(); + }; +} diff --git a/src/bootstrap/product-composition-contract.ts b/src/bootstrap/product-composition-contract.ts index ac34414c..1a47e27f 100644 --- a/src/bootstrap/product-composition-contract.ts +++ b/src/bootstrap/product-composition-contract.ts @@ -3,6 +3,7 @@ import type { ContractHttpExecutorDependencies, InstalledHttpOperationExecutor, } from "../adapters/http/index.ts"; +import type { ServiceWorkerActivationOutcome } from "../contracts/service-worker.ts"; import type { FeaturePlatformCapabilities } from "../features/feature-adapter-contribution.ts"; import type { RuntimeConfig } from "./runtime-config-schema.ts"; @@ -78,6 +79,27 @@ export type TemplatePlatformCapabilityId = "http" | "telemetry"; export type ProductCredentialProvider = ContractHttpExecutorDependencies["attachCredentials"]; +/** + * 1112/07-01. The template's own credentials for a request the product sends + * itself rather than through `http`, such as a Fileserver upload + * (`FileserverUploadClientDependencies`): spread it into that capability. + * + * - `attachCredentials` decides as the V3 executor's does: the scope fence, + * then the ANONYMOUS profile, then `credentialProviders`, then the template + * session (an `EXTERNAL_BEARER` upload gets the session owner's bearer this + * way), then the fence again. + * - `onUnauthenticated` takes the server's 401 to that request the same way + * a V3 401 goes: to `onCredentialRejected` for a product provider's + * credential, to the template session for its own, to nobody for an + * ANONYMOUS one. + */ +export type ProductRequestCredentials = Readonly<{ + attachCredentials: ProductCredentialProvider; + onUnauthenticated( + binding: Readonly<{ operationId: string; authProfileId: string }>, + ): void; +}>; + export type ProductCompositionContext = Readonly<{ /** Validated runtime config, product keys included. */ config: RuntimeConfig; @@ -98,6 +120,11 @@ export type ProductCompositionContext = Readonly<{ * credential is not the session's, such as another API's token. */ notifySessionUnauthenticated(): void; + /** + * 1112/07-01. Call it per request: called while `composeProduct` runs it + * throws a `TypeError`. + */ + credentials: ProductRequestCredentials; }>; /** @@ -136,6 +163,21 @@ export type ProductServiceWorkerWiring = Readonly<{ * `client_drain`, ...), each with its outcome. A throw is ignored. */ observe?(observation: Readonly<{ event: string; outcome: string }>): void; + /** + * 1103/09-05. An update finished installing and waits for this tab, found + * when the worker starts or later: show the product's "new version" notice + * and call `activate()` when the user agrees. `activate()` is + * `requestActivation()`, so `blockers` still apply. A throw is ignored. + */ + onUpdateWaiting?( + activate: () => Promise, + ): void; + /** + * 1103/09-05. A worker of another build took over (this tab asked, or + * another one did), so this page runs old code: ask the user to reload, or + * reload. A throw is ignored. + */ + onReloadRequired?(): void; }>; export type ProductComposition = Readonly<{ diff --git a/src/bootstrap/runtime-adapters.ts b/src/bootstrap/runtime-adapters.ts index 5923f0ef..6b3d1ebe 100644 --- a/src/bootstrap/runtime-adapters.ts +++ b/src/bootstrap/runtime-adapters.ts @@ -68,6 +68,7 @@ import { } from "./product-composition.ts"; import type { ProductComposition, + ProductCredentialProvider, ProductScopeParticipant, } from "./product-composition-contract.ts"; import { createProductSessionOwnerContext } from "./product-session-owner-context.ts"; @@ -535,60 +536,83 @@ export async function createRuntimeAdapters( diagnostics, telemetry, }); - const contractHttp = createRuntimeContractHttpExecutor(config, { - fetcher: context.fetcher, - async attachCredentials(operation, authContext) { + /** + * 1112/02-10. Who supplies the credential of an auth profile, and so who + * hears the server's 401 to it. `attachCredentials` and + * `reportServerUnauthenticated` both read this one decision. 09-01: an + * ANONYMOUS profile admits no credential header at all, so nobody supplies + * one. 09-02: a product provider answers for its own profiles before the + * session. Every other profile needs the session and never downgrades to + * anonymous. `productCredentialProviders` is set below, before any request + * can run. + */ + let productComposed = false; + function credentialOwner(authProfileId: string): "NONE" | "PRODUCT" | "SESSION" { + // `context.credentials` is for requests: called while `composeProduct` + // runs, the provider table does not exist yet. + if (!productComposed) { + throw new TypeError( + "context.credentials is called per request, not while composeProduct runs.", + ); + } + if (INSTALLED_REST_AUTH_PROFILES.get(authProfileId)?.transport === "ANONYMOUS") { + return "NONE"; + } + return Object.hasOwn(productCredentialProviders, authProfileId) + ? "PRODUCT" + : "SESSION"; + } + const attachCredentials: ProductCredentialProvider = async ( + operation, + authContext, + ) => { + // Decided first (it reads no state); nothing is asked before the fence. + const owner = credentialOwner(operation.authProfileId); + if (serverStateScope.getPhase() !== "READY") { + return Object.freeze({ kind: "SCOPE_FENCED" as const }); + } + if (owner === "NONE") { + return Object.freeze({ kind: "READY" as const, headers: {} }); + } + // A throw is left to the executor, which closes it as + // CREDENTIAL_OWNER_FAILED. + if (owner === "PRODUCT") { + const provider = productCredentialProviders[operation.authProfileId]; + const answer = await provider(operation, authContext); + return serverStateScope.getPhase() === "READY" + ? answer + : Object.freeze({ kind: "SCOPE_FENCED" as const }); + } + const state = authSession.getState(); + if (state === "integration-failed") { + return Object.freeze({ kind: "UNAVAILABLE" as const }); + } + if (state !== "authenticated") { + return Object.freeze({ kind: "UNAUTHENTICATED" as const }); + } + try { + const patch = await authSession.credentialPatch( + { + origin: new URL(config.API_BASE_URL).origin, + method: operation.method, + operationId: operation.operationId, + }, + authContext, + ); if (serverStateScope.getPhase() !== "READY") { return Object.freeze({ kind: "SCOPE_FENCED" as const }); } - // 09-01. The operation's installed profile decides first, the session - // second. An ANONYMOUS profile admits no credential header at all, so it - // goes out bare in every session state and never reaches the owner. Every - // other profile still needs a session and never downgrades to anonymous. - if ( - INSTALLED_REST_AUTH_PROFILES.get(operation.authProfileId)?.transport === - "ANONYMOUS" - ) { - return Object.freeze({ kind: "READY" as const, headers: {} }); - } - // 09-02. A product provider answers for its own profiles, between the - // checks above and the session. A throw is left to the executor, which - // closes it as CREDENTIAL_OWNER_FAILED. `productCredentialProviders` is - // set below, before any request can run. - if (Object.hasOwn(productCredentialProviders, operation.authProfileId)) { - const provider = productCredentialProviders[operation.authProfileId]; - const answer = await provider(operation, authContext); - return serverStateScope.getPhase() === "READY" - ? answer - : Object.freeze({ kind: "SCOPE_FENCED" as const }); - } - const state = authSession.getState(); - if (state === "integration-failed") { - return Object.freeze({ kind: "UNAVAILABLE" as const }); - } - if (state !== "authenticated") { - return Object.freeze({ kind: "UNAUTHENTICATED" as const }); - } - try { - const patch = await authSession.credentialPatch( - { - origin: new URL(config.API_BASE_URL).origin, - method: operation.method, - operationId: operation.operationId, - }, - authContext, - ); - if (serverStateScope.getPhase() !== "READY") { - return Object.freeze({ kind: "SCOPE_FENCED" as const }); - } - return Object.freeze({ - kind: "READY" as const, - headers: patch.headers, - }); - } catch { - return Object.freeze({ kind: "UNAVAILABLE" as const }); - } - }, + return Object.freeze({ + kind: "READY" as const, + headers: patch.headers, + }); + } catch { + return Object.freeze({ kind: "UNAVAILABLE" as const }); + } + }; + const contractHttp = createRuntimeContractHttpExecutor(config, { + fetcher: context.fetcher, + attachCredentials, observe: observeHttpExecution, }); // 15-01. Filled one feature at a time as feature runtimes load; an @@ -597,21 +621,24 @@ export async function createRuntimeAdapters( const contractRegistry = createInstalledContractRegistry(); /** * 1103/09-01. A 401 judges the credential the request carried, so it goes to - * whoever supplied it, decided in the same order as `attachCredentials`. An - * ANONYMOUS request carried none: nobody is told. A product provider's - * credential: the product is told, the session is not. Only the session's - * own credential signs the session out. + * whoever supplied it (`credentialOwner`). An ANONYMOUS request carried + * none: nobody is told. A product provider's credential: the product is + * told, the session is not. Only the session's own credential signs the + * session out. */ function reportServerUnauthenticated( - authProfileId: string, binding: Readonly<{ operationId: string; authProfileId: string }>, ): void { - if (INSTALLED_REST_AUTH_PROFILES.get(authProfileId)?.transport === "ANONYMOUS") { - return; - } - if (Object.hasOwn(productCredentialProviders, authProfileId)) { + const owner = credentialOwner(binding.authProfileId); + if (owner === "NONE") return; + if (owner === "PRODUCT") { try { - onProductCredentialRejected?.(Object.freeze(binding)); + onProductCredentialRejected?.( + Object.freeze({ + operationId: binding.operationId, + authProfileId: binding.authProfileId, + }), + ); } catch { // A product hook defect cannot change the contract execution outcome. } @@ -673,7 +700,7 @@ export async function createRuntimeAdapters( // dispatch for lack of a credential carries no response metadata; telling // the owner would overwrite a recovering session and re-fence the scope. if (outcome.kind === "UNAUTHENTICATED" && outcome.metadata !== undefined) { - reportServerUnauthenticated(executableContract.frontend.authProfileId, { + reportServerUnauthenticated({ operationId: executableContract.contract.operationId, authProfileId: executableContract.frontend.authProfileId, }); @@ -703,12 +730,19 @@ export async function createRuntimeAdapters( // credential: the verdict reportServerUnauthenticated gives the session's // own 401. notifySessionUnauthenticated: () => authSession.onUnauthenticated(), + // 1112/07-01. The same owner and 401 routing for a request the product + // sends itself, such as a Fileserver upload. + credentials: Object.freeze({ + attachCredentials, + onUnauthenticated: reportServerUnauthenticated, + }), }) satisfies ProductComposition; // Read through the contract type: the product's own return type omits the // optional fields when the product does not use them, and `product` keeps // its narrow type above so a missing capability still fails the typecheck. const productContract: ProductComposition = product; const productCredentialProviders = productContract.credentialProviders; + productComposed = true; const onProductCredentialRejected = productContract.onCredentialRejected; for (const participant of productContract.scopeParticipants ?? []) { // 1105/02-01. The label names the participant in diagnostics, so it must diff --git a/src/contracts/service-worker.ts b/src/contracts/service-worker.ts index 85d4deeb..8140fbe3 100644 --- a/src/contracts/service-worker.ts +++ b/src/contracts/service-worker.ts @@ -23,9 +23,6 @@ export const SERVICE_WORKER_BOUNDS = Object.freeze({ */ activationReplySlackMs: 5_000, updateCheckIntervalMs: 6 * 60 * 60 * 1_000, - retainedPreviousCaches: 1, - reloadGuardBytes: 512, - reloadGuardTtlMs: 10 * 60 * 1_000, }); export type ServiceWorkerHandlerId = @@ -64,9 +61,6 @@ export type ServiceWorkerProtocolIdentity = Readonly<{ }>; export type ServiceWorkerMessageKind = - | "PAGE_HELLO" - | "WORKER_HELLO_ACK" - | "UPDATE_READY" | "ACTIVATE_REQUEST" | "ACTIVATE_ACCEPTED" | "ACTIVATE_REJECTED" diff --git a/src/features/feature-adapter-contribution.ts b/src/features/feature-adapter-contribution.ts index 40dcbb85..4d6a9af7 100644 --- a/src/features/feature-adapter-contribution.ts +++ b/src/features/feature-adapter-contribution.ts @@ -3,6 +3,7 @@ import type { ApplicationFeatureInputs, } from "../application/ports/in/application-api.ts"; import type { + FileserverUploadClientDependencies, InstalledHttpOperationExecutor, } from "../adapters/http/index.ts"; import type { TelemetryPort } from "../platform/telemetry/telemetry-port.ts"; @@ -57,6 +58,16 @@ export interface FeaturePlatformCapabilities extends ProductFeaturePlatformCapabilities { readonly http: InstalledHttpOperationExecutor; readonly indexedDb: IndexedDbRepositoryProvider; + /** + * 1112/09-01. Opt-in like `indexedDb`: the template types it and never + * builds it. A product that uploads to the paired backend's Fileserver + * returns it from `src/bootstrap/product-composition.ts` (manual 02 §7), + * and a feature that lists it in `needs` calls `createFileserverUploadClient` + * with it. Typed here rather than in `product-capabilities.ts`, which this + * file imports: that file reading the type from here would be an import + * cycle. + */ + readonly fileserverUpload: FileserverUploadClientDependencies; /** scale-architecture.md §24. Provider-neutral, bounded, fail-open feature telemetry. */ readonly telemetry: TelemetryPort; } diff --git a/tests/component/runtime-composition-service-worker-product-wiring.test.ts b/tests/component/runtime-composition-service-worker-product-wiring.test.ts index 440de1f3..995c61dc 100644 --- a/tests/component/runtime-composition-service-worker-product-wiring.test.ts +++ b/tests/component/runtime-composition-service-worker-product-wiring.test.ts @@ -2,6 +2,7 @@ import { describe, expect, it, vi } from "vitest"; +import { createServiceWorkerMessage } from "../../src/adapters/service-worker/service-worker-protocol.ts"; import { createRuntimeComposition } from "../../src/bootstrap/create-runtime-composition.ts"; import type { ProductComposition } from "../../src/bootstrap/product-composition-contract.ts"; @@ -16,6 +17,9 @@ import type { ProductComposition } from "../../src/bootstrap/product-composition const product = vi.hoisted(() => ({ observed: [] as Array>, dirty: true, + /** 1103/09-05. Each `activate` the product's update notice received. */ + updates: [] as Array<() => Promise>, + reloads: 0, })); vi.mock("../../src/features/installed-runtime-capabilities.ts", async (importOriginal) => { @@ -46,6 +50,14 @@ vi.mock("../../src/bootstrap/product-composition.ts", () => ({ // The composition drops a throwing product sink. throw new Error("product sink failure"); }, + onUpdateWaiting(activate) { + product.updates.push(activate); + throw new Error("product notice failure"); + }, + onReloadRequired() { + product.reloads += 1; + throw new Error("product prompt failure"); + }, }, }), })); @@ -98,7 +110,10 @@ async function fetcher(input: RequestInfo | URL): Promise { } /** This page's worker is active and the next build's is waiting. */ -function updateWaitingContainer(): ServiceWorkerContainer { +function updateWaitingContainer(): ServiceWorkerContainer & { + /** Delivers a worker message to the page, as from the waiting worker. */ + dispatchFromWaiting(data: unknown): void; +} { const worker = (scriptURL: string, state: string) => ({ scriptURL, state, @@ -106,13 +121,16 @@ function updateWaitingContainer(): ServiceWorkerContainer { addEventListener() {}, removeEventListener() {}, }); + let waiting: ReturnType | null = null; + const messageListeners = new Set<(event: MessageEvent) => void>(); const register = vi.fn( async (scriptURL: string | URL, options?: RegistrationOptions) => { const script = new URL(scriptURL, origin).href; + waiting = worker(script, "installed"); return { scope: new URL(options?.scope ?? "/", origin).href, installing: null, - waiting: worker(script, "installed"), + waiting, active: worker(script, "activated"), addEventListener() {}, removeEventListener() {}, @@ -125,9 +143,17 @@ function updateWaitingContainer(): ServiceWorkerContainer { register, getRegistration: vi.fn(async () => undefined), getRegistrations: vi.fn(async () => []), - addEventListener() {}, - removeEventListener() {}, - } as unknown as ServiceWorkerContainer; + addEventListener(type: string, listener: (event: MessageEvent) => void) { + if (type === "message") messageListeners.add(listener); + }, + removeEventListener(type: string, listener: (event: MessageEvent) => void) { + if (type === "message") messageListeners.delete(listener); + }, + dispatchFromWaiting(data: unknown) { + const event = { data, origin, source: waiting } as unknown as MessageEvent; + for (const listener of messageListeners) listener(event); + }, + } as unknown as ServiceWorkerContainer & { dispatchFromWaiting(data: unknown): void }; } describe("1103/09-05 the product wires the worker in product-composition.ts", () => { @@ -160,3 +186,64 @@ describe("1103/09-05 the product wires the worker in product-composition.ts", () } }); }); + +describe("1103/09-05 the product's update notice and reload prompt", () => { + it("are called from product-composition.ts alone, and their throws are dropped", async () => { + product.updates = []; + product.reloads = 0; + product.dirty = false; + const container = updateWaitingContainer(); + const composition = await createRuntimeComposition({ + fetcher, + host: { + location: { origin }, + navigator: { serviceWorker: container }, + }, + }); + + try { + await composition.optional.startAfterMount(); + // The update was waiting when the worker started. + expect(product.updates).toHaveLength(1); + + container.dispatchFromWaiting( + createServiceWorkerMessage({ + kind: "ACTIVATED_RELOAD_REQUIRED", + sourceBuildId: "next-build", + }), + ); + expect(product.reloads).toBe(1); + } finally { + await composition.dispose(); + product.dirty = true; + } + // Disposed: the product hears nothing more. + container.dispatchFromWaiting( + createServiceWorkerMessage({ + kind: "ACTIVATED_RELOAD_REQUIRED", + sourceBuildId: "next-build", + }), + ); + expect(product.reloads).toBe(1); + }); + + it("hands the notice an activate that is requestActivation, blockers included", async () => { + product.updates = []; + const composition = await createRuntimeComposition({ + fetcher, + host: { + location: { origin }, + navigator: { serviceWorker: updateWaitingContainer() }, + }, + }); + + try { + await composition.optional.startAfterMount(); + await expect(product.updates[0]?.()).resolves.toEqual({ + kind: "BLOCKED_DIRTY_CLIENT", + }); + } finally { + await composition.dispose(); + } + }); +}); diff --git a/tests/integration/fileserver-upload.test.ts b/tests/integration/fileserver-upload.test.ts index 0c9da0a4..dec29b91 100644 --- a/tests/integration/fileserver-upload.test.ts +++ b/tests/integration/fileserver-upload.test.ts @@ -16,7 +16,7 @@ import type { RestAuthProfile } from "../../src/contracts/rest-profiles.ts"; /** * 2026-11-03 01-01. The paired backend Fileserver's `POST /v1/files`, answered - * as clean-architecture-backend-template `45d2a478` (the pin) answers it in + * as clean-architecture-backend-template at the pinned commit answers it in * code, not only as its docs/fileserver/http-contract.md lists it. * * 1105/01-01. The document lists 202 VERIFYING alone. The code verifies the @@ -381,6 +381,8 @@ describe("Fileserver multipart upload — Envelope failures", () => { // 1105/01-02. As the V3 table reads it: only an unknown result keeps the key. { status: 503, code: "IDEMPOTENCY_UNAVAILABLE", category: "TRANSIENT_DEPENDENCY", retryable: true, kind: "SERVER_FAILURE", effect: "MAYBE_APPLIED", clientRetryable: false }, { status: 503, code: "IDEMPOTENCY_COMPLETION_UNKNOWN", category: "TRANSIENT_DEPENDENCY", retryable: true, kind: "SERVER_FAILURE", effect: "MAYBE_APPLIED", clientRetryable: false }, + // 1112/02-05. A full server, refused before the work runs (backend 697e62e8c). + { status: 503, code: "SERVER_BUSY", category: "TRANSIENT_DEPENDENCY", retryable: true, kind: "SERVER_FAILURE", effect: "NOT_APPLIED", clientRetryable: true }, { status: 507, code: "STORAGE_FULL", category: "TRANSIENT_DEPENDENCY", retryable: false, kind: "SERVER_FAILURE", effect: "NOT_APPLIED", clientRetryable: false }, // 1105/01-02. Raised by the waiting thread at any stage of the work, which // may still publish the file: the backend's own retryable:true does not @@ -409,6 +411,38 @@ describe("Fileserver multipart upload — Envelope failures", () => { }, ); + // 1112/07-01. A 401 is the server's verdict on the credential the upload + // carried; the composition hears it through `onUnauthenticated`. + it("tells onUnauthenticated once about a 401, and about nothing else", async () => { + const onUnauthenticated = vi.fn(); + answer({ status: 401, body: failureEnvelope("UNAUTHENTICATED", "AUTH", false) }); + + const result = await client({ onUnauthenticated }).client.upload(upload()); + + expect(result).toMatchObject({ ok: false, error: { kind: "AUTH_REQUIRED" } }); + expect(onUnauthenticated).toHaveBeenCalledExactlyOnceWith({ + operationId: "FILESERVER_UPLOAD", + authProfileId: expect.any(String), + }); + + onUnauthenticated.mockClear(); + answer({ status: 403, body: failureEnvelope("ACCESS_DENIED", "AUTHZ", false) }); + await client({ onUnauthenticated }).client.upload(upload()); + expect(onUnauthenticated).not.toHaveBeenCalled(); + }); + + it("keeps the 401 outcome when onUnauthenticated throws", async () => { + answer({ status: 401, body: failureEnvelope("UNAUTHENTICATED", "AUTH", false) }); + + const result = await client({ + onUnauthenticated: () => { + throw new Error("hook defect"); + }, + }).client.upload(upload()); + + expect(result).toMatchObject({ ok: false, error: { kind: "AUTH_REQUIRED" } }); + }); + it("carries no traceId when the failure Envelope has none", async () => { const envelope = failureEnvelope("STORAGE_UNAVAILABLE", "TRANSIENT_DEPENDENCY", true); answer({ diff --git a/tests/unit/backend-contract-drift.test.ts b/tests/unit/backend-contract-drift.test.ts index 2917d909..1b211661 100644 --- a/tests/unit/backend-contract-drift.test.ts +++ b/tests/unit/backend-contract-drift.test.ts @@ -113,6 +113,16 @@ const SCAFFOLD_SOURCES = [ copiedTo: { file: "scripts/create-feature-write-slice.ts", symbol: "BACKEND_NAME_MAX_LENGTH" }, }, ]; +/** 1105/01-02. A backend code file the frontend reads a code table from. */ +const FILESERVER_CODES = + "src/application/fileserver/src/main/java/dev/caskeleton/application/fileserver/api/error/FileserverErrorCode.java"; +const CODE_SOURCE = { + path: FILESERVER_CODES, + fact: "5xx before publishing", + copiedTo: { file: "src/adapters/http/fileserver-upload.ts", symbol: "NOT_APPLIED_5XX_CODES" }, + codes: ["PARTIAL_WRITE"], +}; +const CODE_SOURCES = [CODE_SOURCE]; async function commitFiles( backend: string, @@ -139,6 +149,10 @@ async function drift( scaffoldHead?: string; /** 1105/16-02. A file the pin does not name, in that later commit. */ otherHead?: string; + /** 1105/01-02. The Fileserver code file in that later commit. */ + codeHead?: string; + /** S-05. Code sources the pin names, by default the one the backend has. */ + codeSources?: readonly (typeof CODE_SOURCE)[]; /** Where the script looks for the backend instead of the fake one. */ backend?: string; flags?: readonly string[]; @@ -153,6 +167,7 @@ async function drift( { [DOCUMENT]: contractDocument(SECTIONS), [AGGREGATE]: "public static final int NAME_MAX_LENGTH = 100;\n", + [FILESERVER_CODES]: "PARTIAL_WRITE(500)\n", "README.md": "backend\n", }, "pinned", @@ -161,6 +176,7 @@ async function drift( ...(options.head === undefined ? {} : { [DOCUMENT]: options.head }), ...(options.scaffoldHead === undefined ? {} : { [AGGREGATE]: options.scaffoldHead }), ...(options.otherHead === undefined ? {} : { "README.md": options.otherHead }), + ...(options.codeHead === undefined ? {} : { [FILESERVER_CODES]: options.codeHead }), }; if (Object.keys(later).length > 0) await commitFiles(backend, later, "after the pin"); @@ -175,7 +191,12 @@ async function drift( }; await write("config/contracts/backend-contract-pin.json", { schemaVersion: 1, - backend: { ...source, sectionsCompared: ["1", "2", "4"], scaffoldSources: SCAFFOLD_SOURCES }, + backend: { + ...source, + sectionsCompared: ["1", "2", "4"], + scaffoldSources: SCAFFOLD_SOURCES, + codeSources: options.codeSources ?? CODE_SOURCES, + }, frontend: { contractDocument: "docs/architecture/backend-api-and-server-state-contract.md", contractSections: ["4.1", "6", "6.1"], @@ -328,6 +349,35 @@ describe("check:backend-contract-drift scaffold sources (1105/16-02)", { timeout expect(result.stderr).toBe(""); expect(result.status).toBe(0); - expect(result.stdout).toContain("1 scaffold sources unchanged"); + expect(result.stdout).toContain("1 scaffold sources and 1 code sources unchanged"); + }); +}); + +/** + * 1105/01-02. The upload client reads some Fileserver 5xx codes as refused + * before publishing. That table was read by hand from the backend, outside + * every pin comparison, so a backend code change left it with no signal. + * + * 1112/02-05. A source path the pinned commit does not have (the backend moved + * its folders) was read as a deletion between the pin and HEAD, and a pin + * that named the old path at the new commit compared nothing. + */ +describe("check:backend-contract-drift code sources (1105/01-02, 1112/02-05)", { timeout: childProcessTimeout(502) }, () => { + it("reports a code source the frontend copies a table from, with where the copy is", async () => { + const result = await drift({ codeHead: "PARTIAL_WRITE(503)\n" }); + + expect(result.status, result.stdout + result.stderr).toBe(1); + expect(result.stderr).toContain(`code source ${FILESERVER_CODES} changed`); + expect(result.stderr).toContain( + "recheck NOT_APPLIED_5XX_CODES in src/adapters/http/fileserver-upload.ts", + ); + }); + + it("fails on a source the pinned commit does not have", async () => { + const moved = "src/application-fileserver/FileserverErrorCode.java"; + const result = await drift({ codeSources: [{ ...CODE_SOURCE, path: moved }] }); + + expect(result.status, result.stdout + result.stderr).toBe(1); + expect(result.stderr).toContain(`${moved} is not in the pinned`); }); }); diff --git a/tests/unit/backend-contract-pin-document.test.ts b/tests/unit/backend-contract-pin-document.test.ts index 28543d43..4ff65ca6 100644 --- a/tests/unit/backend-contract-pin-document.test.ts +++ b/tests/unit/backend-contract-pin-document.test.ts @@ -39,20 +39,12 @@ function codesPossiblyAfterWrite(): ReadonlySet { } /** - * Rows of that table whose stage the endpoint decides: the reference domain's - * codes and web-advanced's patch codes ("부르는 코드가 단계를 정한다"). A - * feature author who checked the endpoint may declare them. + * Rows of that table whose stage the endpoint decides: web-advanced's patch + * codes ("부르는 코드가 단계를 정한다"). A feature author who checked the + * endpoint may declare them. 1112/02-05: the reference domain's codes went + * with the backend sample module, and with them their row. */ -const FEATURE_DECIDED_CODES: readonly string[] = [ - "WORKLOG_INVALID", - "POSTER_INVALID_STATE", - "POSTER_IMAGE_REQUIRED", - "WORKLOG_CONFLICT", - "POSTER_ALREADY_EXISTS", - "POSTER_IMAGE_ALREADY_PUBLISHED", - "PATCH_REJECTED", - "PATCH_TEST_FAILED", -]; +const FEATURE_DECIDED_CODES: readonly string[] = ["PATCH_REJECTED", "PATCH_TEST_FAILED"]; describe("platform codes no operation may declare as refused before its write", () => { it("are the 6.1 table's possibly-after-write codes outside the feature-decided rows", () => { diff --git a/tests/unit/backend-contract-pin.test.ts b/tests/unit/backend-contract-pin.test.ts index 71a9d39d..965043d8 100644 --- a/tests/unit/backend-contract-pin.test.ts +++ b/tests/unit/backend-contract-pin.test.ts @@ -13,6 +13,7 @@ import { maybeAppliedAnswerRows, refusedBeforeWriteRows, } from "../../src/adapters/http/backend-envelope.ts"; +import { notAppliedFileserver5xxCodes } from "../../src/adapters/http/fileserver-upload.ts"; /** * 1103/12-06. The paired backend's contract is pinned in a file a machine @@ -56,6 +57,22 @@ const pinSchema = z .strict(), ) .min(1), + // 1105/01-02. Backend code files the frontend reads a code table from; + // `codes` is the copied table where the frontend keeps one. + codeSources: z + .array( + z + .object({ + path: z.string().min(1), + fact: z.string().min(1), + copiedTo: z + .object({ file: z.string().min(1), symbol: z.string().min(1) }) + .strict(), + codes: z.array(z.string().regex(/^[A-Z0-9_]{1,64}$/u)).min(1).optional(), + }) + .strict(), + ) + .min(1), }) .strict(), frontend: z @@ -211,6 +228,28 @@ describe("paired backend contract pin", () => { ); }); + /** + * 1105/01-02. The upload client reads some Fileserver 5xx codes as refused + * before publishing. The pin keeps that table beside the backend files it + * was read from, so a code that changes on either side fails here, and + * check:backend-contract-drift says when one of those files changes. + */ + it("holds the upload client's Fileserver 5xx table to the pin's copy", () => { + const paths = pin.backend.codeSources.map((source) => source.path); + expect(new Set(paths).size).toBe(paths.length); + for (const source of pin.backend.codeSources) { + expect(readFileSync(source.copiedTo.file, "utf8"), source.path).toContain( + source.copiedTo.symbol, + ); + expect(pin.frontend.readers, source.path).toContain(source.copiedTo.file); + } + const tables = pin.backend.codeSources.filter( + (source) => source.copiedTo.symbol === "NOT_APPLIED_5XX_CODES" && source.codes !== undefined, + ); + expect(tables).toHaveLength(1); + expect([...notAppliedFileserver5xxCodes()].sort()).toEqual([...(tables[0]?.codes ?? [])].sort()); + }); + it("copies each backend answer once", () => { const keys = table.answers.map((answer) => `${answer.status} ${answer.code}`); expect(new Set(keys).size).toBe(keys.length); diff --git a/tests/unit/manual-code-blocks.test.ts b/tests/unit/manual-code-blocks.test.ts index dc18a37d..438e4ab8 100644 --- a/tests/unit/manual-code-blocks.test.ts +++ b/tests/unit/manual-code-blocks.test.ts @@ -30,12 +30,22 @@ import { childProcessTimeout } from "../helpers/child-process-timeout.ts"; * well have built `invoice-feature`. So the copy gets the reserved probe * feature instead, and every block and check is renamed to it on the way in * (`renameFeatureText`): paths, constants, types and words alike. + * + * 1112/09-01. A block may also be a whole product-owned file the template + * ships empty, such as the upload composition of manual 02 §7: it replaces + * that file in the copy. */ const MANUAL = "docs/manual"; const FEATURE_ID = MANUAL_PROBE_FEATURE_ID; const toProbe = (text: string) => renameFeatureText(text, MANUAL_EXAMPLE_FEATURE_ID, FEATURE_ID); const CHECKS = "tests/fixtures/manual-code-blocks"; const MARKED_BLOCK = /\n```tsx?\n([\s\S]*?)\n```/gu; +/** Product-owned files a block may replace whole; every other block adds a file. */ +const PRODUCT_OWNED_FILES: ReadonlySet = new Set([ + "src/bootstrap/product-composition.ts", + "src/contracts/product-contracts.ts", + "src/features/product-capabilities.ts", +]); async function manualDocuments(directory: string): Promise { const documents: string[] = []; @@ -90,6 +100,8 @@ describe("docs/manual code blocks, pasted into a generated feature", () => { const targets = [...(await markedBlocks()).keys()].sort(); expect(targets).toEqual([ + "src/bootstrap/product-composition.ts", + "src/features/invoice-feature/adapters/invoice-attachment-uploads.ts", "src/features/invoice-feature/adapters/invoice-problem-mapping.ts", "src/features/invoice-feature/contracts/invoice-list-search.ts", "src/features/invoice-feature/contracts/invoice-problem-details.ts", @@ -114,7 +126,9 @@ describe("docs/manual code blocks, pasted into a generated feature", () => { for (const [target, block] of blocks) { const file = path.join(root, toProbe(target)); // A block adds a file; it never stands in for one the command wrote. - expect(existsSync(file), `${target} exists before the block is pasted`).toBe(false); + expect(existsSync(file), `${target} exists before the block is pasted`).toBe( + PRODUCT_OWNED_FILES.has(target), + ); await mkdir(path.dirname(file), { recursive: true }); await writeFile(file, toProbe(block)); } diff --git a/tests/unit/runtime-adapters-credential-order.test.ts b/tests/unit/runtime-adapters-credential-order.test.ts index f47a84e9..d1210e8b 100644 --- a/tests/unit/runtime-adapters-credential-order.test.ts +++ b/tests/unit/runtime-adapters-credential-order.test.ts @@ -1,7 +1,14 @@ import { afterEach, describe, expect, it, vi } from "vitest"; -import type { InstalledHttpOperationExecutor } from "../../src/adapters/http/index.ts"; -import type { ProductCredentialProvider } from "../../src/bootstrap/product-composition-contract.ts"; +import { + createFileserverUploadClient, + type InstalledHttpOperationExecutor, +} from "../../src/adapters/http/index.ts"; +import type { + ProductCompositionContext, + ProductCredentialProvider, +} from "../../src/bootstrap/product-composition-contract.ts"; +import { REST_AUTH_PROFILES } from "../../src/contracts/rest-profiles.ts"; import { createRuntimeAdapters } from "../../src/bootstrap/runtime-adapters.ts"; import { TEST_LIST_HTTP_CONTRACT } from "../helpers/external-contract-fixture.ts"; import { testRuntimeConfig } from "../helpers/runtime-config.ts"; @@ -22,6 +29,8 @@ const fixture = vi.hoisted(() => ({ http: undefined as InstalledHttpOperationExecutor | undefined, providers: {} as Record, onCredentialRejected: undefined as ((binding: unknown) => void) | undefined, + context: undefined as unknown, + onCompose: undefined as ((context: unknown) => void) | undefined, withProfile( contract: T, operationId: string, @@ -80,13 +89,17 @@ vi.mock("../../src/features/installed-feature-adapters.ts", async (importOrigina /** The product-owned file, filled the way a product fills it. */ vi.mock("../../src/bootstrap/product-composition.ts", () => ({ composeProductSessionOwner: () => null, - composeProduct: () => ({ + composeProduct: (context: unknown) => { + fixture.context = context; + fixture.onCompose?.(context); + return { capabilities: {}, credentialProviders: fixture.providers, ...(fixture.onCredentialRejected === undefined ? {} : { onCredentialRejected: fixture.onCredentialRejected }), - }), + }; + }, })); type Runtime = Parameters[0]["runtime"]; @@ -178,6 +191,8 @@ afterEach(() => { fixture.http = undefined; fixture.providers = {}; fixture.onCredentialRejected = undefined; + fixture.context = undefined; + fixture.onCompose = undefined; }); async function compose( @@ -418,3 +433,168 @@ describe("1103/09-01 a 401 to a product provider's credential", () => { expect(rejected).not.toHaveBeenCalled(); }); }); + +/** + * 1112/02-10, 1112/07-01. Whoever supplies a request's credential hears the + * server's 401 to it, for a V3 request and for an upload the product sends + * through `context.credentials`, one profile kind per row. The two answers + * come from one decision in the composition root; an order changed on one + * side only fails a row here. + */ +describe("1112/02-10 the credential's owner is the 401's owner", () => { + const unauthorized = () => + Response.json( + { + success: false, + error: { code: "UNAUTHENTICATED", category: "AUTH", message: "x", retryable: false }, + meta: { requestId: "req-1" }, + }, + { status: 401 }, + ); + + function uploadSource() { + const bytes = new TextEncoder().encode("file"); + return { + byteLength: bytes.byteLength, + async *stream() { + yield { ok: true as const, value: bytes }; + }, + }; + } + + async function upload( + authProfile: (typeof REST_AUTH_PROFILES)[keyof typeof REST_AUTH_PROFILES], + fetcher: typeof fetch, + ) { + const context = fixture.context as ProductCompositionContext | undefined; + if (!context) throw new Error("The product composition was not called"); + const client = createFileserverUploadClient({ + ...context.credentials, + baseUrl: "http://localhost:8080/", + authProfile, + maxFileBytes: 1024, + fetcher, + }); + return client.upload({ source: uploadSource(), signal: new AbortController().signal }); + } + + const ROWS = [ + { + owner: "nobody, for an ANONYMOUS profile", + providers: {} as Record, + operation: ANONYMOUS_OPERATION, + profile: REST_AUTH_PROFILES.ANONYMOUS, + sentAuthorization: null, + product: 0, + session: 0, + }, + { + owner: "the product, for a provider's profile", + providers: { EXTERNAL_BEARER: productToken }, + operation: PROFILE_OPERATION, + profile: REST_AUTH_PROFILES.EXTERNAL_BEARER, + sentAuthorization: "Bearer product-token", + product: 1, + session: 0, + }, + { + owner: "the session, for its own profile", + providers: {}, + operation: PROFILE_OPERATION, + profile: REST_AUTH_PROFILES.EXTERNAL_BEARER, + sentAuthorization: "Bearer owner-token", + product: 0, + session: 1, + }, + ] as const; + + it.each(ROWS)("V3: $owner", async (row) => { + const owner = externalOwner(); + const session = vi.spyOn(owner, "notifyUnauthenticated"); + const product = vi.fn(); + fixture.providers = row.providers; + fixture.onCredentialRejected = product; + const { http, fetcher } = await compose( + "external", + { __CA_FRONTEND_AUTH_OWNER__: owner }, + unauthorized, + ); + + const outcome = await http.execute(row.operation, { limit: 1 }, { routeId: "TEST_ROUTE" }); + + expect(outcome.kind).toBe("UNAUTHENTICATED"); + expect(new Headers(fetcher.mock.calls[0]?.[1]?.headers).get("authorization")).toBe( + row.sentAuthorization, + ); + expect(product).toHaveBeenCalledTimes(row.product); + expect(session).toHaveBeenCalledTimes(row.session); + }); + + it.each(ROWS)("upload: $owner", async (row) => { + const owner = externalOwner(); + const session = vi.spyOn(owner, "notifyUnauthenticated"); + const product = vi.fn(); + fixture.providers = row.providers; + fixture.onCredentialRejected = product; + await compose("external", { __CA_FRONTEND_AUTH_OWNER__: owner }); + const uploads = vi.fn(async (_input: RequestInfo | URL, _init?: RequestInit) => + unauthorized(), + ); + + const result = await upload(row.profile, uploads as unknown as typeof fetch); + + expect(result).toMatchObject({ ok: false, error: { kind: "AUTH_REQUIRED" } }); + expect(uploads).toHaveBeenCalledOnce(); + expect(new Headers(uploads.mock.calls[0]?.[1]?.headers).get("authorization")).toBe( + row.sentAuthorization, + ); + expect(product).toHaveBeenCalledTimes(row.product); + if (row.product === 1) { + expect(product).toHaveBeenCalledWith({ + operationId: "FILESERVER_UPLOAD", + authProfileId: "EXTERNAL_BEARER", + }); + } + expect(session).toHaveBeenCalledTimes(row.session); + }); + + it("upload: a fenced scope sends nothing, with the session's bearer profile", async () => { + // The demo session's sign-in fences the scope synchronously (row 1 above). + const { adapters } = await compose("demo"); + void adapters.outputPorts.session.beginSignIn(); + const uploads = vi.fn(async () => unauthorized()); + + const result = await upload( + REST_AUTH_PROFILES.EXTERNAL_BEARER, + uploads as unknown as typeof fetch, + ); + + expect(result).toMatchObject({ ok: false, error: { kind: "SCOPE_GENERATION_CHANGED" } }); + expect(uploads).not.toHaveBeenCalled(); + }); +}); + +describe("1112/07-01 context.credentials while composing", () => { + it("says it is called per request instead of failing on the provider table", async () => { + let attempt: Promise | undefined; + let reported: unknown; + fixture.onCompose = (context) => { + const { credentials } = context as ProductCompositionContext; + attempt = Promise.resolve( + credentials.attachCredentials( + { operationId: "X", authProfileId: "EXTERNAL_BEARER", method: "POST" }, + { signal: new AbortController().signal, deadlineAtMonotonicMs: 0 }, + ), + ); + try { + credentials.onUnauthenticated({ operationId: "X", authProfileId: "EXTERNAL_BEARER" }); + } catch (error) { + reported = error; + } + }; + await compose("demo"); + + await expect(attempt).rejects.toThrow(/per request/u); + expect(reported).toBeInstanceOf(TypeError); + }); +}); diff --git a/tests/unit/service-worker-asset-directory.test.ts b/tests/unit/service-worker-asset-directory.test.ts new file mode 100644 index 00000000..29f725f5 --- /dev/null +++ b/tests/unit/service-worker-asset-directory.test.ts @@ -0,0 +1,25 @@ +import { describe, expect, it } from "vitest"; + +import { BUILD_ASSET_DIRECTORY } from "../../src/contracts/service-worker.ts"; +import viteConfig from "../../vite.config.ts"; + +/** + * 0925/06-08. The Service Worker precache, its previous-release fallback and + * the hosting probe read `BUILD_ASSET_DIRECTORY`; Vite writes the hashed + * files to `build.assetsDir`. A product that changed only the Vite setting + * got a worker with an empty precache and a probe that checked nothing, with + * every gate green. The two are held equal here, and the worker generator and + * install refuse an empty asset set besides. + */ +const VITE_DEFAULT_ASSETS_DIR = "assets"; + +describe("0925/06-08 the build's asset directory is the worker's", () => { + it("vite.config.ts build.assetsDir names BUILD_ASSET_DIRECTORY", async () => { + const config = + typeof viteConfig === "function" + ? await viteConfig({ command: "build", mode: "production", isSsrBuild: false, isPreview: false }) + : viteConfig; + + expect(`${config.build?.assetsDir ?? VITE_DEFAULT_ASSETS_DIR}/`).toBe(BUILD_ASSET_DIRECTORY); + }); +}); diff --git a/tests/unit/service-worker-update-observation.test.ts b/tests/unit/service-worker-update-observation.test.ts new file mode 100644 index 00000000..871f9bf2 --- /dev/null +++ b/tests/unit/service-worker-update-observation.test.ts @@ -0,0 +1,239 @@ +import { afterEach, describe, expect, it, vi } from "vitest"; + +import { createServiceWorkerPageController } from "../../src/adapters/service-worker/index.ts"; +import { installStaticAssets } from "../../src/adapters/service-worker/service-worker-static-assets.ts"; +import { + SERVICE_WORKER_BOUNDS, + SERVICE_WORKER_SCRIPT_PATH, +} from "../../src/contracts/service-worker.ts"; + +/** + * 0925/06-05. An update that failed to install (the new worker went + * `redundant`) and a periodic update check that failed left no record: the + * page stayed on its build and nothing said why. + * + * 1103/09-05. An update already waiting when the page registered was reported + * only as the start outcome, so a product notice subscribed to + * `onUpdateWaiting` never heard of it. + */ + +const ORIGIN = "https://app.example"; + +class FakeWorker extends EventTarget { + readonly scriptURL = `${ORIGIN}/${SERVICE_WORKER_SCRIPT_PATH}`; + constructor(public state: ServiceWorkerState) { + super(); + } + postMessage(): void {} + move(state: ServiceWorkerState): void { + this.state = state; + this.dispatchEvent(new Event("statechange")); + } +} + +function browser(options: Readonly<{ waiting?: boolean; update?: () => Promise }> = {}) { + const registration = Object.assign(new EventTarget(), { + scope: `${ORIGIN}/`, + installing: null as FakeWorker | null, + waiting: options.waiting ? new FakeWorker("installed") : null, + active: new FakeWorker("activated"), + update: vi.fn(options.update ?? (async () => {})), + }); + const container = { + controller: registration.active, + register: vi.fn(async () => registration), + addEventListener() {}, + removeEventListener() {}, + }; + return { registration, container }; +} + +function controllerFor(container: unknown) { + const observed: Array> = []; + const controller = createServiceWorkerPageController({ + selection: { mode: "ACTIVE", scriptPath: SERVICE_WORKER_SCRIPT_PATH, handlers: [] }, + disabledCleanup: false, + routerBasePath: "/", + origin: ORIGIN, + buildId: "page-build", + container: container as ServiceWorkerContainer, + observe: (observation) => observed.push(observation), + }); + return { controller, observed }; +} + +afterEach(() => { + vi.useRealTimers(); +}); + +describe("0925/06-05 update failures are observed", () => { + it("records an update whose install failed", async () => { + const { registration, container } = browser(); + const { controller, observed } = controllerFor(container); + await controller.start(); + + const update = new FakeWorker("installing"); + registration.installing = update; + registration.dispatchEvent(new Event("updatefound")); + update.move("redundant"); + + expect(observed).toContainEqual({ event: "update_install", outcome: "REDUNDANT" }); + await controller.stop(); + }); + + it("records a periodic update check that failed", async () => { + vi.useFakeTimers(); + const { container } = browser({ + update: async () => { + throw new TypeError("network"); + }, + }); + const { controller, observed } = controllerFor(container); + await controller.start(); + + await vi.advanceTimersByTimeAsync(SERVICE_WORKER_BOUNDS.updateCheckIntervalMs); + + expect(observed).toContainEqual({ event: "update_check", outcome: "FAILED" }); + await controller.stop(); + }); + + it("records nothing for an update that installed", async () => { + const { registration, container } = browser(); + const { controller, observed } = controllerFor(container); + const waiting = vi.fn(); + controller.onUpdateWaiting?.(waiting); + await controller.start(); + + const update = new FakeWorker("installing"); + registration.installing = update; + registration.dispatchEvent(new Event("updatefound")); + registration.waiting = update; + update.move("installed"); + + expect(waiting).toHaveBeenCalledOnce(); + expect(observed.some(({ event }) => event.startsWith("update_"))).toBe(false); + await controller.stop(); + }); +}); + +describe("1103/09-05 an update waiting at start reaches onUpdateWaiting", () => { + it("tells the listener once, with the UPDATE_WAITING start outcome", async () => { + const { container } = browser({ waiting: true }); + const { controller } = controllerFor(container); + const waiting = vi.fn(); + controller.onUpdateWaiting?.(waiting); + + await expect(controller.start()).resolves.toEqual({ kind: "UPDATE_WAITING" }); + + expect(waiting).toHaveBeenCalledOnce(); + await controller.stop(); + }); +}); + +/** + * 1101/06-05. Every release downloaded the whole asset set again with + * `no-store`, even the files whose content-hashed names it shared with the + * release before. A verified copy in an earlier release's cache is reused; + * the download stays for a file that is new, missing or no longer matches. + */ +describe("1101/06-05 an earlier release's verified asset is reused", () => { + const CURRENT = `ca-static-v1-${"a".repeat(16)}`; + const PREVIOUS = `ca-static-v1-${"c".repeat(16)}`; + const kept = new TextEncoder().encode("kept"); + const fresh = new TextEncoder().encode("fresh"); + /** A fake digest: one hex digit per content. */ + const DIGESTS: Readonly> = { kept: "1", fresh: "2", tamp: "3" }; + const digestOf = (bytes: Uint8Array) => + `sha256:${(DIGESTS[new TextDecoder().decode(bytes)] ?? "f").repeat(64)}`; + const asset = (name: string, bytes: Uint8Array) => ({ + url: `${ORIGIN}/assets/${name}`, + sha256: digestOf(bytes) as `sha256:${string}`, + bytes: bytes.byteLength, + contentType: "text/javascript", + }); + const manifest = { + schemaVersion: 1 as const, + buildId: "worker-build", + releaseId: "release-2", + setDigest: `sha256:${"a".repeat(64)}` as const, + assets: [asset("kept", kept), asset("fresh", fresh)], + }; + + async function install( + previous: Readonly>, + previousContentType = "text/javascript", + ) { + const put = vi.fn(async () => {}); + const previousCache = { + match: vi.fn(async (url: string) => { + const bytes = previous[url]; + return bytes + ? new Response(bytes.slice(), { headers: { "content-type": previousContentType } }) + : undefined; + }), + }; + const fetcher = vi.fn(async (input: RequestInfo | URL) => { + const bytes = String(input).endsWith("kept") ? kept : fresh; + return new Response(bytes.slice(), { headers: { "content-type": "text/javascript" } }); + }); + const result = await installStaticAssets(manifest, { + caches: { + open: vi.fn(async (name: string) => + (name === PREVIOUS ? previousCache : { put }) as unknown as Cache, + ), + delete: vi.fn(async () => true), + keys: vi.fn(async () => [PREVIOUS]), + }, + fetcher: fetcher as unknown as typeof fetch, + digest: vi.fn(async (bytes: Uint8Array) => digestOf(bytes)), + }); + return { result, fetched: fetcher.mock.calls.map(([input]) => String(input)), put }; + } + + it("copies the unchanged file and downloads only the new one", async () => { + const { result, fetched, put } = await install({ [`${ORIGIN}/assets/kept`]: kept }); + + expect(result).toEqual({ kind: "INSTALLED", cacheName: CURRENT, assets: 2 }); + expect(fetched).toEqual([`${ORIGIN}/assets/fresh`]); + expect(put).toHaveBeenCalledTimes(2); + }); + + it("downloads a file whose earlier copy was stored with another content type", async () => { + const { fetched } = await install({ [`${ORIGIN}/assets/kept`]: kept }, "text/css"); + + expect(fetched.sort()).toEqual([`${ORIGIN}/assets/fresh`, `${ORIGIN}/assets/kept`]); + }); + + it("downloads a file whose earlier copy no longer matches its digest", async () => { + const { result, fetched } = await install({ + [`${ORIGIN}/assets/kept`]: new TextEncoder().encode("tamp"), + }); + + expect(result).toMatchObject({ kind: "INSTALLED" }); + expect(fetched.sort()).toEqual([`${ORIGIN}/assets/fresh`, `${ORIGIN}/assets/kept`]); + }); +}); + +describe("0925/06-08 an empty asset manifest is refused", () => { + it("does not install a worker that would serve nothing", async () => { + const fetcher = vi.fn(); + + await expect( + installStaticAssets( + { + schemaVersion: 1, + buildId: "worker-build", + releaseId: "release-2", + setDigest: `sha256:${"a".repeat(64)}`, + assets: [], + }, + { + caches: { open: vi.fn(), delete: vi.fn(async () => true) }, + fetcher: fetcher as unknown as typeof fetch, + digest: vi.fn(), + }, + ), + ).resolves.toEqual({ kind: "REJECTED", code: "MANIFEST_INVALID" }); + expect(fetcher).not.toHaveBeenCalled(); + }); +});