From 016597ac78055058fad05e2de6b2f9b0921e858c Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Mon, 28 Sep 2026 14:46:30 +0900 Subject: [PATCH] =?UTF-8?q?review-followup=20Wave=202:=20=EC=A0=95?= =?UTF-8?q?=ED=95=A9=EC=84=B1=20=EC=88=98=EC=A0=95=20=ED=86=B5=ED=95=A9?= =?UTF-8?q?=EA=B3=BC=20=EA=B2=80=EC=A6=9D,=20=ED=98=84=ED=99=A9=ED=91=9C?= =?UTF-8?q?=C2=B7=EC=9E=AC=EA=B0=9C=20=ED=94=84=EB=A1=AC=ED=94=84=ED=8A=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 13개 작업 묶음(P1–P13)의 W2 커밋을 합치고 전체 게이트로 검증했다. - 묶음별 정합성 수정(notification dispatch·recovery, object storage staged publication, fileserver 복구·정리, gRPC 플랫폼, Redis 분류·lease TTL, JPA outbox claim 순서·durable operation HTTP, web 요청 id·category 필수, graphql 에러 mapper, Mongo profile 바인딩, build 소스 보존 게이트·compose smoke info 확인) - 통합 때 드러난 3건 수정: outbox claim 테스트 fixture의 가짜 envelope hash, sample scan이 새 operation controller를 등록하던 문제, SpotBugs aux classpath 파일이 truncate되지 않아 로컬에서 ".jar.jar"로 실패하던 문제 - 현황표: 묶음 결과 반영, 소유자 결정 21–27, 후속 발견 결함 47행, 요약 갱신 - docs/capability-status.md 「제거된 코드」에 85행 추가 - 묶음 결과 파일·에이전트 지시·스크립트를 docs로 옮기고 desktop 재개 프롬프트 추가 검증: check, ci verifyDependencyLocks, mainCheck, architecture/public path/env keys/config contract, bootstrap·sample integration/system, build-logic·build-tools test, optional-platforms ci, qualificationBootJar 통과. integrationCheck는 이번 작업 전에도 실패하던 lane(Redis topology 모드 인자, httpclient failure injection, AWS 보호 lane)만 실패. Co-Authored-By: Claude Opus 5.5 (1M context) --- docs/capability-status.md | 89 ++- docs/fileserver/configuration.md | 7 +- docs/fileserver/http-contract.md | 2 +- docs/httpclient/operations.md | 5 +- docs/messaging/configuration-reference.md | 6 + docs/messaging/outbox-inbox.md | 18 +- docs/messaging/retry-dlq-redrive.md | 9 + docs/mongodb/consistency-transaction-guide.md | 5 + docs/notification/api-surface-snapshot.txt | 3 +- docs/registries/env-keys.yaml | 7 +- .../2026-09-25-review-followup-results/P1.md | 51 ++ .../2026-09-25-review-followup-results/P10.md | 29 + .../2026-09-25-review-followup-results/P11.md | 50 ++ .../2026-09-25-review-followup-results/P12.md | 29 + .../2026-09-25-review-followup-results/P13.md | 19 + .../2026-09-25-review-followup-results/P2.md | 56 ++ .../2026-09-25-review-followup-results/P3.md | 50 ++ .../2026-09-25-review-followup-results/P4.md | 50 ++ .../2026-09-25-review-followup-results/P5.md | 51 ++ .../2026-09-25-review-followup-results/P6.md | 39 ++ .../2026-09-25-review-followup-results/P7.md | 33 ++ .../2026-09-25-review-followup-results/P8.md | 31 + .../2026-09-25-review-followup-results/P9.md | 43 ++ .../2026-09-25-review-followup-status.md | 493 +++++++++------- ...026-09-28-review-followup-resume-prompt.md | 79 +++ docs/study/postgresql-jpa-walkthrough.ko.md | 3 +- .../agent-brief.md | 47 ++ .../apply_results.py | 87 +++ .../by_area.py | 92 +++ .../plans/2026-09-25-review-followup.md | 44 +- docs/web/repository-adaptation.md | 13 +- infra/keycloak/realms/ca-skeleton-realm.json | 9 +- scripts/run-compose-runtime-smoke.sh | 52 +- scripts/verify-compose-profile-contracts.sh | 24 +- src/README.md | 9 +- src/adapter/inbound/graphql/CLAUDE.md | 11 +- .../GraphQlPlatformAutoConfiguration.java | 36 +- .../graphql/context/TenantContext.java | 14 +- .../cost/GraphQlDocumentShapeAnalyzer.java | 13 +- .../graphql/error/GraphQlErrorCode.java | 6 +- .../error/GraphQlExceptionResolver.java | 11 + .../GraphQlDataFetcherExceptionResolver.java | 10 +- .../GraphQlPlatformInstrumentation.java | 11 +- .../GraphQlPlatformRejectionMapper.java | 33 +- .../GraphQlPlatformWebInterceptor.java | 12 +- .../runtime/GraphQlWireErrorMapper.java | 43 +- .../GraphQlRequestBodyLimitFilter.java | 19 +- .../src/main/resources/config/graphql.yml | 8 + .../GraphQlPlatformExecutionPathTest.java | 42 ++ .../GraphQlDeploymentModeContractTest.java | 30 + .../context/GraphQlRequestContextTest.java | 22 + .../cost/GraphQlFragmentReachabilityTest.java | 22 + .../error/GraphQlErrorCodeCatalogTest.java | 8 +- .../error/GraphQlExceptionResolverTest.java | 37 ++ .../GraphQlRequestStageErrorMappingTest.java | 186 ++++++ .../runtime/GraphQlWireErrorMapperTest.java | 40 ++ src/adapter/inbound/grpc/CLAUDE.md | 9 +- src/adapter/inbound/grpc/README.md | 6 +- .../grpc/GrpcAuthenticationInterceptor.java | 15 +- .../GrpcExceptionHandlingInterceptor.java | 17 +- .../inbound/grpc/GrpcServerConfig.java | 6 +- .../inbound/grpc/GrpcServerSettings.java | 4 +- .../GrpcAuthenticationInterceptorTest.java | 83 +++ .../GrpcExceptionHandlingInterceptorTest.java | 25 + .../inbound/grpc/GrpcP1BoundaryWireTest.java | 44 +- .../inbound/grpc/GrpcSafeActivationTest.java | 52 +- .../grpc/GrpcServerRunnerBootTest.java | 18 +- .../fileserver/draft12/Draft12Headers.java | 1 + .../draft12/Draft12UploadController.java | 56 +- .../web/fileserver/tus/TusController.java | 7 +- .../draft12/Draft12ProtocolTest.java | 40 ++ .../testkit/RecordingFinalizeService.java | 11 +- .../tus/TusProtocolContractTest.java | 13 + .../NotificationSubmissionController.java | 9 +- .../SubmitNotificationHttpRequest.java | 3 +- .../NotificationSubmissionControllerTest.java | 50 ++ src/adapter/inbound/web/README.md | 14 +- src/adapter/inbound/web/build.gradle | 3 + .../error/ClientSafeValidationDetails.java | 10 +- .../web/error/GlobalExceptionHandler.java | 2 +- .../web/filter/RequestLoggingFilter.java | 82 +-- .../web/mvc/filter/WebMvcRequestIdFilter.java | 84 ++- .../operation/DurableOperationController.java | 158 +++++ .../OperationAcceptedHttpResponse.java | 20 + .../OperationCanceledHttpResponse.java | 9 + .../web/operation/OperationErrorCode.java | 31 + .../web/operation/OperationHttpResponse.java | 77 +++ .../operation/SubmitOperationHttpRequest.java | 18 + .../web/auth/SecurityModeWebContractTest.java | 28 + .../envelope/EnvelopeMetaIntegrationTest.java | 6 +- .../web/error/GlobalExceptionHandlerTest.java | 29 + .../web/filter/RequestLoggingFilterTest.java | 301 ++-------- .../mvc/filter/WebMvcRequestIdFilterTest.java | 122 ++++ .../DurableOperationControllerTest.java | 246 ++++++++ .../PipelineOrderFixtureApplication.java | 6 +- src/adapter/outbound/cache-redis/README.md | 18 +- .../redis/RedisSemanticFailureLogger.java | 50 +- .../redis/cache/RedisCacheRegionAdapter.java | 36 +- .../capability/RedisCapabilitySettings.java | 9 - .../capability/RedisRateLimitConfig.java | 19 +- .../RedisSemanticScriptAclProbe.java | 17 +- .../RedisIdempotencyStoreAdapter.java | 39 +- .../lease/RedisDistributedLeaseAdapter.java | 57 +- .../redis/ratelimit/RateLimitScripts.java | 38 +- .../config/module-defaults/cache-redis.yml | 11 +- .../redis/LiveRedisSemanticPortsTest.java | 65 ++- .../redis/RedisSemanticFailureLoggerTest.java | 73 +++ .../cache/RedisCacheRegionAdapterTest.java | 70 +++ .../RedisCapabilityCompositionTest.java | 18 + .../RedisSemanticScriptAclProbeTest.java | 2 +- .../RedisIdempotencyStoreAdapterTest.java | 109 +++- .../RedisDistributedLeaseAdapterTest.java | 177 +++++- ...FileserverStorageGatewayConfiguration.java | 6 +- .../local/AtomicMoveContentPublisher.java | 2 +- .../local/LocalBlockingContentStore.java | 69 ++- .../local/LocalCleanupContentGateway.java | 13 +- .../local/LocalUploadContentGateway.java | 6 + .../MetadataPointerContentPublisher.java | 2 +- .../platform/local/StreamingDigest.java | 5 + .../platform/local/LocalAppendEngineTest.java | 45 +- .../LocalStorageGatewayContractTest.java | 11 +- .../HttpRetryBudgetExhaustedException.java | 16 + .../error/HttpRuntimeDrainingException.java | 16 + .../error/HttpUnknownTransportException.java | 18 + .../auth/OAuth2CredentialProvider.java | 16 +- .../auth/SingleFlightTokenLoader.java | 19 +- .../restclient/DefaultGenericHttpGateway.java | 7 +- .../StableBlockingExceptionMapper.java | 5 +- .../config/module-defaults/httpclient.yml | 8 + .../auth/OAuth2CredentialProviderTest.java | 141 +++++ .../auth/SingleFlightTokenLoaderTest.java | 58 ++ .../DefaultGenericHttpGatewayTest.java | 90 +++ .../StableBlockingExceptionMapperTest.java | 32 + .../httpclient/testkit/TestGateways.java | 54 +- .../outbound/messaging-kafka/README.md | 3 +- .../kafka/KafkaSenderAutoConfiguration.java | 10 +- .../config/module-defaults/messaging.yml | 20 +- .../kafka/KafkaCapabilityActivationTest.java | 3 +- .../kafka/KafkaSenderInterruptionTest.java | 42 ++ .../core/OutboundMessagePublisher.java | 6 +- .../outbox/OutboxMessagePublishAdapter.java | 6 +- ...latformIntegrationEventPublishAdapter.java | 8 +- .../core/OutboundMessagePublisherTest.java | 29 + .../OutboxCanonicalPublishRoutingTest.java | 5 +- .../OutboxMessagePublishAdapterTest.java | 20 + ...ormIntegrationEventPublishAdapterTest.java | 26 +- .../NotificationPlatformRegistriesConfig.java | 13 +- .../NotificationProviderAssembly.java | 5 + .../ProviderCallbackAssembler.java | 12 + .../SesProviderCallbackAssembler.java | 7 + .../SmtpProviderRuntimeAssembler.java | 37 +- .../platform/dispatch/ProviderRuntime.java | 61 +- .../RegistryProviderRuntimeControl.java | 5 +- .../platform/provider/EmailRecipients.java | 59 ++ .../ses/SesNotificationProviderAdapter.java | 11 +- .../smtp/SmtpNotificationProviderAdapter.java | 11 +- .../NotificationProviderAssemblyTest.java | 110 ++++ .../SmtpProviderRuntimeAssemblerTest.java | 8 + .../dispatch/ProviderRuntimeStateTest.java | 51 ++ .../SmtpNotificationProviderAdapterTest.java | 29 + .../ObjectStorageCapabilityAssembler.java | 43 +- .../config/RoutingObjectMutationAdapter.java | 7 + .../config/RoutingObjectReadAdapter.java | 7 +- .../RoutingObjectScanMaintenanceAdapter.java | 25 +- .../ObjectPublicationHandoffRecord.java | 10 + .../LocalDevObjectControlStore.java | 40 +- .../ObjectPublicationHandoffService.java | 18 +- .../kernel/StagedObjectPublicationKernel.java | 170 ++++-- .../ObjectStorageCapabilityAssemblerTest.java | 99 ++++ .../LocalDevObjectStorageRecoveryTest.java | 54 ++ .../StagedObjectPublicationLifecycleTest.java | 551 ++++++++++++++---- .../s3/S3AsyncResponseBodyBridgeTest.java | 205 ++++--- .../fileserver/JpaFileMetadataStore.java | 12 +- .../repository/FileTransitionRepository.java | 11 +- .../outbound/persistence-jpa/README.md | 29 +- .../h2/H2OutboxClaimRepository.java | 12 +- .../platform/inbox/InboxItemEntity.java | 16 +- .../inbox/InboxItemJpaRepository.java | 3 + .../DurableOperationJpaRepository.java | 4 +- .../DurableOperationStoreAdapter.java | 28 +- .../outbox/CanonicalOutboxAppendAdapter.java | 6 + .../outbox/OutboxEventJpaRepository.java | 31 +- .../persistence/outbox/OutboxReaper.java | 25 +- .../outbox/OutboxStoreAdapter.java | 40 +- .../outbox/entity/OutboxEventEntity.java | 30 +- .../PostgreSqlOutboxClaimRepository.java | 19 +- .../JpaDangerousConfigurationGuard.java | 40 +- .../startup/JpaPlatformReport.java | 3 +- .../startup/JpaSafetySettings.java | 12 +- .../transaction/SpringTransactionPort.java | 6 + .../module-defaults/persistence-jpa.yml | 9 + ...tbox_event_unpublished_aggregate_order.sql | 8 + ...rationSubmissionOutboxIntegrationTest.java | 205 +++++++ ...ileserverMetadataStoreIntegrationTest.java | 20 + .../PostgreSqlInboxCutoffIntegrationTest.java | 86 ++- ...gacyOutboxRowLifecycleIntegrationTest.java | 35 +- .../PostgreSqlMigrationIntegrationTest.java | 2 +- ...boxClaimAndMaintenanceIntegrationTest.java | 268 +++++++++ .../persistence/h2/H2ClaimSqlTest.java | 62 ++ .../platform/inbox/InboxItemEntityTest.java | 46 ++ .../CanonicalOutboxAppendAdapterTest.java | 33 +- .../persistence/outbox/OutboxReaperTest.java | 53 +- .../outbox/OutboxStoreAdapterTest.java | 40 +- .../JpaDangerousConfigurationGuardTest.java | 30 +- .../OpenInViewSafetyValidatorTest.java | 11 + .../SpringTransactionPortTest.java | 14 + .../resources/db/applied-migrations.sha256 | 1 + .../outbound/persistence-mongo/README.md | 9 +- ...MongoDefaultsEnvironmentPostProcessor.java | 2 +- .../MongoPlatformHealthIndicator.java | 11 +- .../autoconfigure/MongoPlatformSettings.java | 22 +- .../autoconfigure/MongoStartupValidator.java | 8 +- ...rofileClientSettingsAutoConfiguration.java | 15 +- .../imperative/bulk/MongoBulkExecutor.java | 79 ++- .../imperative/bulk/MongoBulkWritePlan.java | 35 +- .../MongoCollectionMigrationLock.java | 12 +- .../src/main/resources/config/mongo.yml | 16 +- .../migration/MongoMigrationLaneTest.java | 28 + .../mongo/rs/MongoBulkMappingLaneTest.java | 157 +++++ .../mongo/MongoConnectionSourceRuleTest.java | 8 +- ...oPlatformHealthMeasuresTheClusterTest.java | 3 +- .../MongoPlatformPropertiesTest.java | 27 +- .../MongoStartupValidatorTest.java | 67 ++- .../MongoClientSettingsFactoryTest.java | 3 +- ...leClientSettingsAutoConfigurationTest.java | 32 +- .../bulk/BulkSharesTheAtomicPolicyTest.java | 8 +- .../imperative/bulk/MongoBulkOutcomeTest.java | 23 +- .../sdk/config/RedisCorrectnessRoles.java | 24 + .../sdk/config/RedisHealthContributor.java | 79 ++- .../sdk/config/RedisSdkAutoConfiguration.java | 24 +- .../sdk/config/LiveRedisCompositionTest.java | 50 +- .../config/RedisHealthContributorTest.java | 136 +++++ .../InMemoryRedisCommandGateway.java | 25 +- src/app-bootstrap/CLAUDE.md | 6 +- src/app-bootstrap/README.md | 21 +- src/app-bootstrap/build.gradle | 1 + ...leOperationCompositionIntegrationTest.java | 239 ++++++++ .../operation/DurableOperationConfig.java | 65 +++ .../autoconfigure/outbox/OutboxConfig.java | 5 +- .../autoconfigure/outbox/OutboxMetrics.java | 5 + .../autoconfigure/outbox/OutboxSettings.java | 6 +- .../security/ManagementSecurityConfig.java | 5 - ...ot.autoconfigure.AutoConfiguration.imports | 1 + .../main/resources/config/observability.yml | 18 +- .../src/main/resources/config/security.yml | 4 + .../outbox/OutboxConfigTest.java | 17 + .../outbox/OutboxSettingsTest.java | 2 +- .../contract/ActuatorSecurityHttpTest.java | 45 +- .../ConfigurationNamespaceContractTest.java | 5 +- ...anagementActuatorSecurityContractTest.java | 14 +- .../OperationalContractRuntimeTest.java | 30 +- .../idempotency/IdempotencyExecutor.java | 37 +- .../messaging/contract/Sha256.java | 12 + .../event/ValidatedIntegrationEvent.java | 8 +- .../operation/DurableOperationStorePort.java | 5 +- .../DurableOperationSubmitResult.java | 21 + .../operation/OperationCommand.java | 13 + .../SubmitDurableOperationUseCase.java | 7 +- .../application/outbox/OutboxStorePort.java | 9 +- .../idempotency/IdempotencyExecutorTest.java | 48 ++ .../event/ValidatedIntegrationEventTest.java | 91 ++- .../GetDurableOperationUseCaseTest.java | 2 +- .../SubmitDurableOperationUseCaseTest.java | 12 + .../ClaimedOutboxEventContractTest.java | 5 +- .../DurableOperationStoreContract.java | 75 ++- .../InMemoryDurableOperationStore.java | 7 +- .../outbox/testkit/InMemoryOutboxStore.java | 4 +- .../admin/DefaultFileserverAdminService.java | 16 +- .../api/content/FinalizeContentCommand.java | 18 +- .../api/metadata/FileRecordMutation.java | 16 + .../fileserver/api/metadata/QuotaScope.java | 12 +- .../cleanup/CleanupContentGateway.java | 7 + .../cleanup/DefaultCleanupService.java | 81 ++- .../fileserver/cleanup/FileRetirement.java | 64 ++ .../DefaultFileLifecycleService.java | 28 +- .../DefaultTransferAdmissionController.java | 55 +- .../upload/DefaultFinalizeUploadService.java | 47 +- .../DefaultUploadApplicationService.java | 44 +- .../upload/UploadContentGateway.java | 9 + .../admin/FileserverAdminServiceTest.java | 16 + .../cleanup/CleanupServiceTest.java | 55 ++ .../TransferAdmissionControllerTest.java | 79 +-- .../testkit/FakeCleanupContentGateway.java | 14 + .../testkit/FakeUploadContentGateway.java | 7 +- .../upload/FinalizeUploadServiceTest.java | 48 ++ .../upload/UploadApplicationServiceTest.java | 120 +++- .../admin/AdminOperationExecutor.java | 65 ++- .../NotificationAdminApplicationService.java | 31 +- .../dispatch/DispatchGuardOutcome.java | 17 +- .../dispatch/DispatchOutcomeRecorder.java | 58 +- .../platform/dispatch/DispatchPipeline.java | 4 +- .../dispatch/LeaseRecoveryService.java | 11 + .../dispatch/NotificationDispatchService.java | 59 +- .../dispatch/ReconciliationService.java | 60 +- .../admin/AdminOperationExecutorTest.java | 33 ++ ...tificationAdminApplicationServiceTest.java | 87 ++- ...eptNotificationApplicationUseCaseTest.java | 23 + .../dispatch/DispatchOutcomeRecorderTest.java | 228 +++++++- .../dispatch/LeaseRecoveryServiceTest.java | 54 ++ .../NotificationDispatchServiceTest.java | 136 +++++ .../dispatch/NotificationPlatformNoops.java | 17 +- .../dispatch/ReconciliationServiceTest.java | 116 ++++ .../architecture/ArchitecturePlugin.java | 32 +- .../architecture/GitCommandResult.java | 3 - .../VerifyNoIgnoredSourcePackagesTask.java | 80 ++- .../quality/QualityConventionsPlugin.java | 12 + ...NoIgnoredSourcePackagesFunctionalTest.java | 122 ++++ src/composition/fileserver-platform/README.md | 3 +- .../fileserver-platform/build.gradle | 6 + .../fileserver-platform/gradle.lockfile | 12 + .../FileserverCleanupConfiguration.java | 10 +- .../fileserver/FileserverCleanupWorker.java | 45 +- .../config/module-defaults/fileserver.yml | 8 + .../FileserverCleanupWorkerTest.java | 64 ++ .../FileserverStructuredLoggingTest.java | 22 +- .../config/module-defaults/notification.yml | 9 + src/config/architecture/modules.json | 1 + .../runtime/compose-profile-contracts.json | 105 ++-- .../src/main/resources/envoy/envoy.yaml | 16 +- .../compat/GrpcWebCompatibilityTest.java | 56 ++ .../grpc/admin/GrpcServiceHealthRegistry.java | 14 +- .../admin/GrpcServiceHealthRegistryTest.java | 48 ++ .../client/GrpcChannelRuntimeRegistry.java | 20 +- .../GrpcChannelRuntimeRegistryTest.java | 54 ++ .../grpc/client/GrpcTypedStubFactoryTest.java | 6 +- .../grpc/api/deadline/GrpcDeadlineBudget.java | 81 ++- .../api/ledger/GrpcOperationIdentity.java | 25 + .../api/deadline/GrpcDeadlineBudgetTest.java | 51 +- .../api/ledger/GrpcOperationIdentityTest.java | 44 ++ .../grpc/ledger/JpaGrpcOperationLedger.java | 14 +- .../GrpcOperationLedgerRepositoryTest.java | 31 +- .../grpc/context/GrpcContextBinder.java | 11 +- .../grpc/resilience/GrpcRetryCoordinator.java | 6 +- .../resilience/GrpcWaitForReadyValidator.java | 8 +- .../GrpcCredentialRotationManager.java | 40 +- .../streaming/GrpcSerializedStreamWriter.java | 39 +- .../grpc/streaming/GrpcStreamAdmission.java | 7 +- .../grpc/streaming/GrpcStreamWriteResult.java | 8 +- .../grpc/context/GrpcContextBinderTest.java | 27 + .../GrpcWaitForReadyValidatorTest.java | 2 +- .../GrpcCredentialRotationManagerTest.java | 91 +++ .../GrpcSerializedStreamWriterTest.java | 63 +- .../GrpcStreamAdmissionConcurrencyTest.java | 13 + .../grpc/server/GrpcAdmissionController.java | 63 +- .../server/GrpcAdmissionControllerTest.java | 55 ++ .../messaging/inbox/InboxPostgresIT.java | 2 +- .../messaging/inbox/InboxCleanupJob.java | 4 +- .../messaging/inbox/JdbcInboxRepository.java | 14 - .../inbox/IdempotentConsumerTest.java | 9 +- .../messaging/inbox/InboxOperationsTest.java | 23 +- .../kafka/KafkaConsumerRegistrar.java | 155 ++++- .../kafka/KafkaQuarantinePublisher.java | 17 +- .../kafka/KafkaConsumerRegistrarTest.java | 255 ++++++-- .../messaging/outbox/OutboxPostgresIT.java | 36 +- .../outbox/JdbcOutboxRepository.java | 40 +- .../messaging/outbox/OutboxCleanupJob.java | 8 +- .../messaging/outbox/OutboxRelay.java | 58 +- .../messaging/outbox/OutboxRelayWorker.java | 11 +- ...5__messaging_outbox_ordering_key_index.sql | 9 + .../outbox/OutboxOperationsTest.java | 25 +- .../messaging/outbox/OutboxRelayTest.java | 56 +- .../outbox/OutboxRelayWorkerTest.java | 21 +- .../messaging/policy/InFlightLimiter.java | 15 +- .../policy/MessagingAdmissionController.java | 19 +- .../reliability/InboxRepository.java | 10 +- .../reliability/OutboxRepository.java | 16 +- .../runtime/DefaultMessagePublisher.java | 21 +- .../runtime/DefaultMessagePublisherTest.java | 83 +++ .../KafkaMessagingAutoConfiguration.java | 69 ++- ...ssagingLiveRoundTripQualificationTest.java | 3 +- ...ssagingSecuredBrokerQualificationTest.java | 1 - .../DefaultReactiveMessagePublisher.java | 6 +- ...MessagingReliabilityAutoConfiguration.java | 27 + .../autoconfigure/BrokerAccessListTest.java | 1 - .../KafkaProducerConfigTest.java | 96 +++ .../KafkaProducerSecurityTest.java | 2 - .../MessagingAutoConfigurationTest.java | 4 +- .../MessagingConfigurationBindingTest.java | 4 +- .../MessagingOutboxRelayLifecycleTest.java | 54 +- .../MessagingStarterOffContractTest.java | 15 +- .../autoconfigure/ReactiveFacadeTest.java | 28 + src/optional-platforms/build.gradle | 4 +- src/sample-portfolio/README.md | 6 +- .../portfolio/SamplePortfolioApplication.java | 8 +- .../web/controller/WorkLogController.java | 32 +- .../web/error/DomainExceptionHandler.java | 10 + .../inbound/web/mapper/WorkLogWebMapper.java | 7 +- .../command/UpdateWorkLogCommand.java | 12 +- .../WorkLogVersionMismatchException.java | 13 + .../worklog/UpdateWorkLogUseCase.java | 5 + .../src/main/resources/application.yml | 4 +- .../controller/WorkLogControllerWireTest.java | 66 ++- .../command/CommandSelfValidationTest.java | 9 +- .../worklog/WorkLogUseCasesTest.java | 57 +- .../SampleSchemaOwnershipDefaultsTest.java | 36 ++ 395 files changed, 12488 insertions(+), 2394 deletions(-) create mode 100644 docs/reviews/2026-09-25-review-followup-results/P1.md create mode 100644 docs/reviews/2026-09-25-review-followup-results/P10.md create mode 100644 docs/reviews/2026-09-25-review-followup-results/P11.md create mode 100644 docs/reviews/2026-09-25-review-followup-results/P12.md create mode 100644 docs/reviews/2026-09-25-review-followup-results/P13.md create mode 100644 docs/reviews/2026-09-25-review-followup-results/P2.md create mode 100644 docs/reviews/2026-09-25-review-followup-results/P3.md create mode 100644 docs/reviews/2026-09-25-review-followup-results/P4.md create mode 100644 docs/reviews/2026-09-25-review-followup-results/P5.md create mode 100644 docs/reviews/2026-09-25-review-followup-results/P6.md create mode 100644 docs/reviews/2026-09-25-review-followup-results/P7.md create mode 100644 docs/reviews/2026-09-25-review-followup-results/P8.md create mode 100644 docs/reviews/2026-09-25-review-followup-results/P9.md create mode 100644 docs/reviews/2026-09-28-review-followup-resume-prompt.md create mode 100644 docs/superpowers/plans/2026-09-25-review-followup-tools/agent-brief.md create mode 100644 docs/superpowers/plans/2026-09-25-review-followup-tools/apply_results.py create mode 100644 docs/superpowers/plans/2026-09-25-review-followup-tools/by_area.py create mode 100644 src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlRequestStageErrorMappingTest.java create mode 100644 src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlWireErrorMapperTest.java create mode 100644 src/adapter/inbound/grpc/src/test/java/dev/caskeleton/adapter/inbound/grpc/GrpcAuthenticationInterceptorTest.java create mode 100644 src/adapter/inbound/web-notification/src/test/java/dev/caskeleton/adapter/inbound/web/notification/platform/submission/NotificationSubmissionControllerTest.java create mode 100644 src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/operation/DurableOperationController.java create mode 100644 src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/operation/OperationAcceptedHttpResponse.java create mode 100644 src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/operation/OperationCanceledHttpResponse.java create mode 100644 src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/operation/OperationErrorCode.java create mode 100644 src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/operation/OperationHttpResponse.java create mode 100644 src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/operation/SubmitOperationHttpRequest.java create mode 100644 src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/operation/DurableOperationControllerTest.java create mode 100644 src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/RedisSemanticFailureLoggerTest.java create mode 100644 src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/api/error/HttpRetryBudgetExhaustedException.java create mode 100644 src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/api/error/HttpRuntimeDrainingException.java create mode 100644 src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/api/error/HttpUnknownTransportException.java create mode 100644 src/adapter/outbound/httpclient/src/test/java/dev/caskeleton/adapter/outbound/httpclient/auth/OAuth2CredentialProviderTest.java create mode 100644 src/adapter/outbound/httpclient/src/test/java/dev/caskeleton/adapter/outbound/httpclient/restclient/StableBlockingExceptionMapperTest.java create mode 100644 src/adapter/outbound/messaging-kafka/src/test/java/dev/caskeleton/adapter/outbound/messaging/kafka/KafkaSenderInterruptionTest.java create mode 100644 src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/provider/EmailRecipients.java create mode 100644 src/adapter/outbound/objectstorage/src/test/java/dev/caskeleton/adapter/outbound/objectstorage/config/ObjectStorageCapabilityAssemblerTest.java create mode 100644 src/adapter/outbound/persistence-jpa/src/main/resources/db/migration/postgresql/V18__outbox_event_unpublished_aggregate_order.sql create mode 100644 src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/operation/DurableOperationSubmissionOutboxIntegrationTest.java create mode 100644 src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlOutboxClaimAndMaintenanceIntegrationTest.java create mode 100644 src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/notification/platform/inbox/InboxItemEntityTest.java create mode 100644 src/adapter/outbound/persistence-mongo/src/mongoIntegrationTest/java/dev/caskeleton/adapter/outbound/mongo/rs/MongoBulkMappingLaneTest.java create mode 100644 src/adapter/outbound/redis-runtime/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/config/RedisHealthContributorTest.java create mode 100644 src/app-bootstrap/src/integrationTest/java/dev/caskeleton/bootstrap/integration/operation/DurableOperationCompositionIntegrationTest.java create mode 100644 src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/operation/DurableOperationConfig.java create mode 100644 src/application-core/src/main/java/dev/caskeleton/application/operation/DurableOperationSubmitResult.java create mode 100644 src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/cleanup/FileRetirement.java delete mode 100644 src/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/GitCommandResult.java create mode 100644 src/build-logic/src/test/java/dev/caskeleton/buildlogic/architecture/VerifyNoIgnoredSourcePackagesFunctionalTest.java create mode 100644 src/composition/fileserver-platform/src/test/java/dev/caskeleton/composition/fileserver/FileserverCleanupWorkerTest.java create mode 100644 src/grpc/grpc-core-api/src/test/java/dev/caskeleton/grpc/api/ledger/GrpcOperationIdentityTest.java create mode 100644 src/grpc/grpc-policy/src/test/java/dev/caskeleton/grpc/security/GrpcCredentialRotationManagerTest.java create mode 100644 src/grpc/grpc-server/src/test/java/dev/caskeleton/grpc/server/GrpcAdmissionControllerTest.java create mode 100644 src/messaging/messaging-outbox-jdbc-postgresql/src/main/resources/db/migration/messaging/V1005__messaging_outbox_ordering_key_index.sql create mode 100644 src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaProducerConfigTest.java create mode 100644 src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/application/exception/WorkLogVersionMismatchException.java create mode 100644 src/sample-portfolio/src/test/java/dev/caskeleton/sample/portfolio/bootstrap/persistence/SampleSchemaOwnershipDefaultsTest.java diff --git a/docs/capability-status.md b/docs/capability-status.md index f1f147be..7c6c3fb5 100644 --- a/docs/capability-status.md +++ b/docs/capability-status.md @@ -39,7 +39,7 @@ lanes and CI; it is not a deployment artifact. | GraphQL transport | `backend.graphql.enabled` / `APP_GRAPHQL_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:inbound:graphql')`) | leaf-level | On when present; `false` also excludes Spring GraphQL's own auto-configuration, so no `/graphql` (`GraphQlCapabilityActivationTest`). `graphqlTransportQualificationTest` runs the HTTP boundary. The deployment-mode/runtime-profile rule is the module's own `GraphQlPlatformStartupValidator`. The default jar does not ship GraphQL, so a compose lane that exercises it runs the qualification jar. | | Object storage | `app.object-storage.enabled` (no `APP_*` row), `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:objectstorage')`) | MinIO only | Own `ObjectStorageAutoConfiguration` (was bound through bootstrap's properties scan); on when present, `false` leaves only the explicit legacy seam (`ObjectStorageAutoConfigurationTest`). `app-bootstrap:integrationTest` assembles it against digest-pinned MinIO. | | gRPC platform | — (build-level) | yes | **no** | yes | Absent from the main build entirely: `optional-platforms` is a separate Gradle build, so the switch is the `include`, not an environment variable. `-p optional-platforms ci` runs on every PR and `integrationCheck` certifies the operation ledger against real PostgreSQL. | -| gRPC transport (`adapter:inbound:grpc`) | `ca-skeleton.grpc.enabled` (no `APP_*` row), `true` | yes | yes (one line: `runtimeOnly project(':adapter:inbound:grpc')`) | leaf-level | Own `AutoConfiguration.imports` (`GrpcServerConfig`); on when present, and the loopback plaintext listener still needs `ca-skeleton.grpc.allow-insecure-local=true` (`GrpcSafeActivationTest`, `grpcTransportQualificationTest`). | +| gRPC transport (`adapter:inbound:grpc`) | `ca-skeleton.grpc.server.enabled` (no `APP_*` row), `true` | yes | yes (one line: `runtimeOnly project(':adapter:inbound:grpc')`) | leaf-level | Own `AutoConfiguration.imports` (`GrpcServerConfig`); on when present, and the loopback plaintext listener still needs `ca-skeleton.grpc.server.allow-insecure-local=true` (`GrpcSafeActivationTest`, `grpcTransportQualificationTest`). | | WebSocket transport | `app.websocket.enabled` / `APP_WEBSOCKET_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:inbound:websocket')`) | — | Own `AutoConfiguration.imports` (`WebSocketConfig`), on in a servlet app when present (`WebSocketAutoConfigurationTest`); `ConditionalTransportBuildContractTest` asserts it has no default production edge. | | Web Advanced library (`adapter:inbound:web-advanced`) | — (build-level; three `backend.web.advanced.*.enabled` switches inside) | yes | **no** | — | No composition root depends on it; `app-bootstrap` takes it `testRuntimeOnly` for the ArchUnit import. No real-provider lane: `webAdvancedTest` (the `web-advanced` tag, run by `release.yml` → `web-stable-release-gate`) is unit and context-runner level. The Nginx lane went with the proxy library on 2026-09-25. | @@ -71,6 +71,8 @@ web 경로의 `W/`는 `src/adapter/inbound/web/src/main/java/dev/caskeleton/adap 복구가 필요하면 표의 커밋에서 경로를 꺼낸다(`git show <커밋>:<경로>`). +리뷰 후속 작업(2026-09-25~28, `docs/superpowers/plans/2026-09-25-review-followup.md`)에서 지운 것은 마지막으로 존재한 커밋이 `6d27356e`인 행으로 표 끝에 이어 붙였다. + | 대상 | 경로 | 마지막으로 존재한 커밋 | 이유 | | --- | --- | --- | --- | | 파일 publication R1/R2 어댑터(`FileserverR2Config`, `FileExportConfig`, local-persistent provider 등 31개)와 테스트 | `src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/*.java`, 같은 위치의 `src/test` 루트 파일 | `208077fd` | 조립 경로 없음(component scan 밖, 호출자 없음) | @@ -254,3 +256,88 @@ web 경로의 `W/`는 `src/adapter/inbound/web/src/main/java/dev/caskeleton/adap | 끄는 장치 테스트: `AdapterActivationEndpointTest`, `AdapterActivationReportShapeTest`, `CapabilityDependencyValidatorTest`, `MasterSwitchRegistryContractTest`, `ShippedRuntimeFacadePresenceTest`, `DisabledAdapterSentinelTest`, `OptionalAdapterBeanGatingTest`, `AutoConfigurationReachabilityParityTest`, `RedisOptionalityContractTest`, persistence-jpa `OutboxMasterSwitchWiringContractTest` | `src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/{activation,contract}/`, `src/app-bootstrap/src/test/java/dev/caskeleton/adapter/outbound/`, `src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/outbox/` | `208077fd` | W4-5: 기본 jar에 실린 capability가 꺼져 있음을 증명하던 테스트. 이제 기본 조립에 없는 것이 꺼진 상태이고, 각 leaf가 "있으면 켜짐 / `enabled=false`면 꺼짐"을 스스로 증명한다 | | systemTest `activation/AdapterActivationInventory`, `DependencyErrorStartupContractTest`, `FiveAdapterOffInventoryTest`, `MasterSwitchEnvironmentPostProcessorTest` | `src/app-bootstrap/src/systemTest/java/dev/caskeleton/bootstrap/activation/` | `208077fd` | W4-5: 다섯 어댑터를 모두 싣고 끈 기동과 의존 오류 메시지를 확인하던 lane. 기본 조립 기동은 systemTest `composition/DefaultCompositionBootTest`(local/dev/prod, capability bean 0개)가, capability별 켜짐/꺼짐은 각 leaf의 activation 테스트가 본다 | | bootstrap `GraphQlDeploymentModeRegistryParityTest` | `src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/activation/GraphQlDeploymentModeRegistryParityTest.java` | `208077fd` | W4-5: 규칙(deployment mode ↔ runtime profile)이 graphql `GraphQlPlatformStartupValidator`로 옮겨 가면서 테스트도 graphql leaf의 같은 이름 테스트로 옮김 | +| `OutboxRepository.purgePublishedBefore(Instant)`, `InboxRepository.purgeProcessedBefore(Instant)`와 JDBC 구현 | `src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/{Outbox,Inbox}Repository.java`, `src/messaging/messaging-{outbox,inbox}-jdbc-postgresql/src/main/java/.../Jdbc{Outbox,Inbox}Repository.java` | `6d27356e` | M-6: 개수 제한 없는 단일 DELETE. bounded 버전만 남김 | +| JAAS 문자열에 사용자 이름·비밀번호를 넣던 코드(`jaas`, `scramJaas`, `plainJaas`, `escapeJaas`)와 그 테스트 `aSecretWithQuotesIsEscaped`, `aSecretWithAControlCharacterIsRefused` | `src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaSecurityConfigurer.java`, `.../KafkaSecurityConfigurerTest.java` | `6d27356e` | M-2d/M-2f: 자격 증명이 JAAS에 들어가지 않으므로 escape할 값이 없음. callback handler로 대체 | +| `CredentialRuntime` 5-인자 생성자 | `src/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/CredentialRuntime.java` | `6d27356e` | username을 받는 생성자로 대체, 호출자는 registry 하나 | +| `BrokerCredentialProfile.MutualTls(String)` 1-인자 형태 | `src/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/BrokerCredentialProfile.java` | `6d27356e` | key store 없는 MUTUAL_TLS는 동작할 수 없음. `(credentialId, keyStoreLocation, keyStoreType)`으로 대체 | +| 테스트 `handlerTimeoutCancelsTheOutstandingHandlerBeforeThePartitionPermitIsReleased` | `src/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrarTest.java` | `6d27356e` | M-3: CompletableFuture cancel을 단언해 결함을 고정하던 테스트 | +| `spring.kafka.bootstrap-servers` 모듈 기본값, compose 계약의 `SPRING_KAFKA_BOOTSTRAP_SERVERS` 3곳, producer의 `Environment` 인자 | `src/adapter/outbound/messaging-kafka/src/main/resources/config/module-defaults/messaging.yml`, `src/config/runtime/compose-profile-contracts.json`, `src/messaging/messaging-spring-boot-starter-kafka/.../KafkaMessagingAutoConfiguration.java` | `6d27356e` | M-2b: broker 주소 출처를 `app.messaging.brokers.` 하나로 | +| direct 전송·direct multipart 조정자와 보조 타입 14개(`DirectTransferCoordinator`, `DirectMultipartCoordinator`, `DirectGrantProvider`, `DirectMultipartProvider`, `DirectGrantReplayCache`, `DirectMultipartGrantLedger`, `DirectMultipartCompletionVerifier`, `DirectPartAcknowledgementVerifier`, `DirectPublishedObjectResolver`, `DirectTransferPolicy`, `DirectTransferCorsPolicy`, `DirectTransferSessionRecord`, `DirectGrantGeneration`, `PresignedGrantRedactor`) | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/direct/` | `6d27356e` | main 호출자 0, 조립 경로 없음(소유자 결정 D1·D-7a) | +| managed multipart 5개(`ManagedMultipartCoordinator`, `MultipartOperationResolver`, `MultipartPartLedger`, `MultipartUploadPlan`, `MultipartCompletionEvidence`) | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/multipart/` | `6d27356e` | main 호출자 0 | +| S3 direct·multipart·presigner·operation resolver 6개(`S3DirectTransferProvider`, `S3DirectMultipartProvider`, `S3ManagedMultipartProvider`, `S3DirectCompletionVerifier`, `S3PresignerFactory`, `S3ObjectOperationResolver`) | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/s3/` | `6d27356e` | 위 조정자만 쓰던 provider. contribution이 만들기만 하고 아무도 꺼내 쓰지 않았다 | +| operation 해결·epoch 커널 5개(`ObjectOperationResolutionService`, `ObjectOperationEpochRecord`, `ObjectOperationEpochState`, `DirectGrantSessionState`, `MultipartUploadState`)와 `ObjectOperationStateMachine.advanceDirectGrant/advanceMultipart`, `PendingObjectEffect.Kind`의 DIRECT_*·MULTIPART_* 값, `ObjectRequestFingerprintCodec.OperationKind`의 DIRECT_*·MULTIPART_* 값 | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/kernel/`, `.../codec/ObjectRequestFingerprintCodec.java` | `6d27356e` | 삭제된 조정자 전용. fingerprint 정규 바이트 형식(`direct-parameter` 줄 포함)은 기존 기록 호환을 위해 유지 | +| direct/multipart control record 5종(`ObjectDirectSessionRecord`, `ObjectDirectMultipartSessionRecord`, `ObjectDirectMultipartGrantRecord`, `ObjectMultipartSessionRecord`, `ObjectMultipartPartRecord`)과 codec 분기·`Family` 값, `ObjectControlKeyCodec.{multipart,directSession,multipartPart,directMultipartGrant,operationEpoch}`, `ObjectHandleCodec.{directUpload,multipart,partReceipt}` | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/control/`, `.../codec/` | `6d27356e` | 삭제된 조정자만 쓰던 영속 레코드. 이 family를 쓴 조립 경로가 없어 저장된 레코드도 없다 | +| capability 값 `DIRECT_UPLOAD`·`DIRECT_MULTIPART` | `ObjectStorageProvider.Capability`, `application-objectstorage/.../model/ObjectCapabilityRequirement.java` | `6d27356e` | 구현이 사라진 뒤에도 설정하면 조용히 무시되는 옵션이 된다(capability 규칙 3) | +| `SelectedObjectStorageProviderFactory`의 `managedMultipart/directTransfer/directMultipart` 슬롯·getter·생성자 3개 | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/config/SelectedObjectStorageProviderFactory.java` | `6d27356e` | 테스트만 호출(`S3ProviderCompositionTest`) | +| `S3ClientPolicy.{requireSdkCompatibleMpuObjectSize,requirePartCount,requirePartSize}`, `MINIMUM_NON_FINAL_PART_BYTES` | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/s3/S3ClientPolicy.java` | `6d27356e` | multipart provider 전용 | +| 포트 `DirectObjectUploadPort`·`DirectObjectDownloadGrantPort`·`DirectMultipartUploadPort` | `src/application-objectstorage/src/main/java/dev/caskeleton/application/objectstorage/port/` | `6d27356e` | 구현·소비자 0 | +| direct/multipart 요청·응답 타입 15개(`Direct{Upload,Download}Grant`, `DirectUploadCompletion{Request,Receipt}`, `Direct{Upload,Download}GrantRequest`, `Multipart{Start,Complete,Abort}Request`, `MultipartPartAcknowledgement`, `MultipartReceipt`, `MultipartSession`, `PartUploadGrant{,Request}`)과 `ObjectModelSupport.{immutableHeaders,requireExpiry}` | `src/application-objectstorage/src/main/java/dev/caskeleton/application/objectstorage/{model,request}/` | `6d27356e` | 삭제된 포트 전용 | +| 식별자 `DirectTransferSessionId`·`MultipartPartNumber`·`PartReceiptToken`, `ObjectIdentitySupport.requirePartReceipt` | `src/application-objectstorage/src/main/java/dev/caskeleton/application/objectstorage/identity/` | `6d27356e` | 삭제된 포트·레코드 전용 | +| `RoutingObjectDirectGrantAdapter` | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/config/RoutingObjectDirectGrantAdapter.java` | `6d27356e` | private 생성자만 있는 빈 클래스, 참조 0 (D-7b) | +| `ObjectStorageMaintenanceCapabilityConfig` | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/config/ObjectStorageMaintenanceCapabilityConfig.java` | `6d27356e` | 빈 `@Configuration` (D-7b) | +| `ObjectPurgeMaintenancePort`, `ObjectPurgeRequest` | `src/application-objectstorage/src/main/java/dev/caskeleton/application/objectstorage/{port,request}/` | `6d27356e` | 구현 0 (D-7c) | +| 삭제 코드 전용 테스트 17개(`direct/` 6개, `multipart/` 2개, `ObjectOperationEpochTest`, `ObjectMutationResponseLossTest`, `S3{DirectMultipart,DirectTransfer,ManagedMultipart}ProviderTest`, `S3ObjectOperationResolverTest`, `MinioDirectTransfer{Contract,Fault}Test`, `S3SdkApiCharacterizationTest.sdkMultipartIntegerPartCountAndMinimumPartBoundariesFailClosed`) | `src/adapter/outbound/objectstorage/src/test/java/dev/caskeleton/adapter/outbound/objectstorage/` | `6d27356e` | 대상 코드 삭제 | +| `AwsS3DirectMutationPreconditionsTest`와 workflow 입력 `run_protected_aws_direct_mutation`·env `OBJECT_STORAGE_AWS_DIRECT_MUTATION_ENABLED` | `src/adapter/outbound/objectstorage/src/objectStorageAwsQualificationTest/.../AwsS3DirectMutationPreconditionsTest.java`, `.github/workflows/object-storage-qualification.yml` | `6d27356e` | direct 전송 lane의 별도 권한 검사. direct 코드가 없으니 검사할 대상이 없다 | +| APNs provider adapter(4 클래스)와 테스트 | `src/adapter/outbound/notification/src/{main,test}/java/dev/caskeleton/adapter/outbound/notification/platform/provider/apns/` | `6d27356e` | assembler 없음 — 켜면 기동 실패. S4-#3a | +| FCM provider adapter(10 클래스)와 테스트 | `…/platform/provider/fcm/` | `6d27356e` | 같은 이유. S4-#3a | +| Twilio provider adapter(9 클래스)와 테스트 | `…/platform/provider/twilio/` | `6d27356e` | 같은 이유. S4-#3a | +| Web Push provider adapter(10 클래스)와 테스트 | `…/platform/provider/webpush/` | `6d27356e` | 같은 이유. S4-#3a | +| Webhook provider adapter(3 클래스)와 테스트 | `…/platform/provider/webhook/` | `6d27356e` | 같은 이유. S4-#3a | +| `SesSuppressionUpdater` | `…/platform/provider/ses/SesSuppressionUpdater.java` | `6d27356e` | main 참조 0. suppression은 projection side-effect 경로가 담당. S4-#3a | +| `ProviderType.APNS/FCM/TWILIO/WEB_PUSH/WEBHOOK` | `…/platform/autoconfigure/ProviderType.java` | `6d27356e` | 조립할 수 없는 종류. 이제 binding에서 unknown type으로 실패 | +| provider 설정 필드 `topic`, `vapid-public-key`, `callback-signing-secret-ref` | `…/platform/autoconfigure/NotificationPlatformSettings.java` (Provider) | `6d27356e` | 삭제된 5종만 읽던 키. capability 규칙 3(동작 안 하는 옵션은 키를 두지 않음) | +| `SecretPurpose.VAPID_SIGNING`, 설정 `secrets.vapid-signing-key`·`active-key-ids.VAPID_SIGNING`, env `APP_NOTIFICATION_PLATFORM_VAPID_SIGNING_KEY`·`APP_NOTIFICATION_PLATFORM_VAPID_SIGNING_KEY_ID` | `src/application-notification/…/platform/security/SecretPurpose.java`, `src/composition/notification-platform/src/main/resources/config/module-defaults/notification.yml`, `src/.env.example`, `docs/registries/env-keys.yaml`, `docs/registries/secrets-classification.yaml`, `scripts/run-compose-runtime-smoke.sh` | `6d27356e` | Web Push 삭제로 소비자 0 | +| Twilio·FCM·APNs·Web Push runbook 절, support-matrix·module-mapping 행 | `docs/notification/provider-runbooks.md`, `docs/notification/support-matrix.md`, `docs/notification/module-mapping.md`, `docs/notification/configuration-reference.md` | `6d27356e` | 설명 대상 코드 삭제 | +| tus `Upload-Defer-Length: 1` 수락 분기 | `src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/tus/TusRequestParser.java` `declaredLength` | `6d27356e` | C-5c. 길이를 나중에 확정할 PATCH가 없어 끝나지 않는 upload만 만들었다. 이제 400 | +| 테스트 `aDeferredLengthUploadIsNeverAutoFinalized` | `src/adapter/inbound/web-fileserver/src/test/java/dev/caskeleton/adapter/inbound/web/fileserver/tus/TusProtocolContractTest.java` | `6d27356e` | 위 분기를 전제로 한 테스트. `aCreateThatDefersItsLengthIsRefusedBecauseTheExtensionIsNotOffered`로 대체 | +| 테스트 `scopeSemaphoreRegistryIsBoundedAndOverflowScopesShareConservativeCapacity` | `src/application-fileserver/src/test/java/dev/caskeleton/application/fileserver/quota/TransferAdmissionControllerTest.java` | `6d27356e` | C-9b. 유휴 scope가 overflow로 몰린다는 옛 동작을 단언. `theScopeRegistryStaysBoundedAsCallersComeAndGo`로 대체 | +| lifecycle delete·admin forceDelete·cancel의 retire 복사본 | `DefaultFileLifecycleService.delete`, `DefaultFileserverAdminService.forceDelete`, `DefaultUploadApplicationService.cancel` 본문 | `6d27356e` | S1-#5. `cleanup/FileRetirement` 하나로 합침 | +| `GrpcStableModuleCatalog`(+`GrpcStableModuleCatalogTest`) | `src/grpc/grpc-core-api/src/main/java/dev/caskeleton/grpc/core/GrpcStableModuleCatalog.java` | `6d27356e` | leaf 목록을 core-api에 재기술(registry SSOT 중복), main 호출자 0 (S7-#4) | +| `GrpcStableBuildInvariant` | `src/grpc/grpc-core-api/src/main/java/dev/caskeleton/grpc/core/GrpcStableBuildInvariant.java` | `6d27356e` | 상수 반환·항상 빈 set으로만 불림. 격리는 `verifyCleanArchitectureDependencies`가 강제 (S7-#4, N-9b/c) | +| `GrpcPlatformStartupValidator.validateAdvancedIsolation` + `stableModuleDependencies` 파라미터 | `src/grpc/grpc-spring-boot-starter/src/main/java/dev/caskeleton/grpc/boot/GrpcPlatformStartupValidator.java` | `6d27356e` | 항상 `Set.of()`로 호출돼 항상 통과 (N-9b) | +| `GrpcAdvancedModuleGuard.requireStableStarterIsClean`, `advancedModules` | `src/grpc-advanced/grpc-advanced-bootstrap/src/main/java/dev/caskeleton/grpc/advanced/bootstrap/GrpcAdvancedModuleGuard.java` | `6d27356e` | 삭제된 catalog/invariant 위임, main 호출자 0 | +| `GrpcApplicationBoundaryRules`, `GrpcRawApiImportRule`, `GrpcServiceAdapterMarker`(+`GrpcApplicationBoundaryRulesTest`) | `src/grpc/grpc-server/src/main/java/dev/caskeleton/grpc/architecture/` | `6d27356e` | 문자열로 ArchUnit 흉내, 자기 테스트의 합성 입력만 검사. 경계 규칙은 app-bootstrap ArchUnit이 검사 | +| `GrpcKotlinCompatibilityGate`, `GrpcKotlinProfile` | `src/grpc-advanced/grpc-advanced-compat/src/main/java/dev/caskeleton/grpc/advanced/kotlin/` | `6d27356e` | `supportableHere()` 상수 false, main 호출자 0 | +| `GrpcWebCompatibilityGate` | `src/grpc-advanced/grpc-advanced-compat/src/main/java/dev/caskeleton/grpc/advanced/web/GrpcWebCompatibilityGate.java` | `6d27356e` | 상수 메서드 + main 호출자 0(`GrpcWebRpcSupport.require`가 같은 규칙) | +| `GrpcServletStartupValidator`, `GrpcServletCapabilityMatrix`, `GrpcServletCompatibilityProfile`(+`GrpcServletStartupValidatorTest`) | `src/grpc-advanced/grpc-advanced-compat/src/main/java/dev/caskeleton/grpc/advanced/servlet/` | `6d27356e` | Servlet 전송 코드 없이 상수 matrix·gate만 있던 패키지, main 호출자 0 | +| `GrpcEdition2024Gate`, `GrpcEdition2026Guard` | `src/grpc-advanced/grpc-advanced-edition/src/main/java/dev/caskeleton/grpc/advanced/edition/` | `6d27356e` | 상수 반환 gate·무조건 throw guard, main 호출자 0 | +| `GrpcResolverSafetyPolicy.acceptAfterClose`, `mayCarryBusinessMetadata`; `CREDENTIAL_SHAPED` 정규식 | `src/grpc-advanced/grpc-advanced-resilience/src/main/java/dev/caskeleton/grpc/advanced/discovery/GrpcResolverSafetyPolicy.java` | `6d27356e` | 상수 메서드(S7-#4) / 부분일치 정규식이 정상 키를 거부(N-4, W1 커밋) | +| `GrpcXdsStartupGuard` + 테스트 리소스 `xds/bootstrap.json` | `src/grpc-advanced/grpc-advanced-resilience/src/main/java/dev/caskeleton/grpc/advanced/xds/GrpcXdsStartupGuard.java` | `6d27356e` | 상수 메서드 포함 guard, main 호출자 0 | +| `GrpcAdvancedInfrastructureTestkit` | `src/grpc-advanced/grpc-advanced-diagnostics/src/main/java/dev/caskeleton/grpc/advanced/diagnostics/GrpcAdvancedInfrastructureTestkit.java` | `6d27356e` | capability별 인프라 목록 상수, main 호출자 0 (문서 표로 대체) | +| 설정 키 `ca-skeleton.capabilities.rate-limit.default-policy-id` (+ `RedisCapabilitySettings.RateLimit.defaultPolicyId` getter/setter) | `src/adapter/outbound/cache-redis/src/main/resources/config/module-defaults/cache-redis.yml`, `src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/capability/RedisCapabilitySettings.java` | `6d27356e` | S6-#6b: 같은 env 키에 두 설정 키가 묶여 있었다. `app.rate-limit.default-policy-id` 하나로 통일 | +| `SmtpProviderRuntimeAssembler.capabilities()` (SMTP capability 사본) | `src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/SmtpProviderRuntimeAssembler.java` | `6d27356e` | 어댑터 `capabilities()`와 값이 달랐다(S4-#4a). 이제 snapshot이 어댑터 값을 쓴다 | +| actuator `loggers` 노출과 `POST`/`DELETE /actuator/loggers/**` `denyAll` 규칙 | `src/app-bootstrap/src/main/resources/config/observability.yml`, `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/management/security/ManagementSecurityConfig.java` | `6d27356e` | actuator 체인에 인증 수단이 없어 어떤 자격증명으로도 도달할 수 없었다(L-7a) | +| `IdempotencyExecutor.preserveUnknown` | `src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyExecutor.java` | `6d27356e` | `recordFailure`로 대체했다(A-8b) | +| `GraphQlExecutionProfile`(BLOCKING_MVC·REACTIVE_WEBFLUX·MIXED_CONTROLLED), `GraphQlExecutionProfileException` | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/execution/` | `6d27356e` | D4: servlet 단일 스택이라 고를 프로파일이 없음 | +| `GraphQlRuntimeTransport`와 `GraphQlPlatformAutoConfiguration`의 `ServletRuntimeDetection`·`ReactiveRuntimeDetection`, `GraphQlPlatformRuntime.transport` | `.../graphql/autoconfigure/` | `6d27356e` | D4: 프로파일과 실행 서버 대조가 필요 없어짐 | +| `GraphQlBlockingBridge`, `GraphQlBlockingBridgeFullException`, `GraphQlBatchLoaderRegistrar`의 bridge·profile 인자, `GraphQlBlockingBridgeTest` | `.../graphql/runtime/`, `src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/runtime/` | `6d27356e` | D4: event loop 에서 blocking 작업을 빼내는 bridge. servlet 에서는 호출 스레드 inline 실행(J-4b 결함 경로) | +| 설정 `backend.graphql.execution-profile`(`APP_GRAPHQL_EXECUTION_PROFILE`), `backend.graphql.unbridged-blocking-resolvers`와 validator의 reactive 검사 | `GraphQlPlatformSettings.java`, `GraphQlPlatformStartupValidator.java`, `src/main/resources/config/graphql.yml`, `docs/registries/env-keys.yaml`, `src/.env.example` | `6d27356e` | D4: 동작할 수 없는 옵션은 키를 두지 않는다 | +| 테스트: `GraphQlTransportNeutralityTest`의 context 기반 프로파일 케이스 7개, `GraphQlBatchLoaderRegistrationTest` reactive·bridge 2건, `GraphQlPlatformStartupValidatorTest.aBlockingResolverWithoutABridgeCannotRunOnTheReactiveProfile` | `src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/` | `6d27356e` | 대상 코드 삭제 | +| `GraphQlPlatformRejectionMapper.map`(unknown → INTERNAL_ERROR 정적 메서드) | `.../graphql/runtime/GraphQlPlatformRejectionMapper.java` | `6d27356e` | 모든 경로가 `GraphQlWireErrorMapper.map`을 쓰게 되어 호출자 없음 (`mapFieldFailure`는 `map`으로 이름 변경) | +| `JpaDangerousConfigurationGuard`의 OSIV 검사 분기와 `OPEN_IN_VIEW_KEY` 상수 | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/startup/JpaDangerousConfigurationGuard.java` | `6d27356e` | S6-#3b. `OpenInViewSafetyValidator`가 모든 profile에서 먼저 거부하므로 local 예외가 도달 불가능한 죽은 코드 | +| `OutboxEventJpaRepository.deletePublishedBefore`(무제한 단일 DELETE) | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/outbox/OutboxEventJpaRepository.java` | `6d27356e` | E-8b. 배치 삭제 `deletePublishedBatch`로 교체 | +| rate-limit client IP 모드 (`RateLimitClientIpMode`, `ClientIpResolver`, `ClientIpResolverFactory`, `ForwardedHeaderClientIpResolver`, `RemoteAddrClientIpResolver`)와 설정 `app.rate-limit.client-ip-mode` / env `APP_RATE_LIMIT_CLIENT_IP_MODE` | `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/ratelimit/` | `6d27356e` | I-5a·NEW-10c: `FORWARDED_HEADERS_TRUSTED`가 호출자가 쓰는 XFF 맨 왼쪽 값을 키로 씀. 운영 정본은 `server.forward-headers-strategy=native` + `server.tomcat.remoteip.internal-proxies`의 `getRemoteAddr()` 하나 | +| `RequestLoggingFilter`의 request/correlation/trace id 발급·MDC 기록·응답 헤더 | `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/filter/RequestLoggingFilter.java` | `6d27356e` | I-4a·I-4b: `WebMvcRequestIdFilter`로 이동(두 필터가 trace를 따로 만들던 것 제거) | +| 알림 제출 category 기본값 `"transactional"` | `src/adapter/inbound/web-notification/.../submission/NotificationSubmissionController.java` | `6d27356e` | I-6a 결정 13 | +| `WorkLogController.requireIfMatch`(트랜잭션 밖 get 후 비교) | `src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/adapter/inbound/web/controller/WorkLogController.java` | `6d27356e` | S6-#11b: 비교를 update 유스케이스 트랜잭션 안으로 | +| reactive gateway·SSE·streaming·runtime 패키지 (`DefaultReactiveHttpGateway`, `ReactiveHttpGateway`, `DefaultReactiveSseGateway`, `ReactiveSseGateway`, `ReactiveStreamingGateway`, `ReactiveAttemptExecutor`, `ReactiveClientRuntime`, `WebClientRuntimeFactory`, `WebClientBodyWriter`, `WebClientResponseMapper`, `BoundedDataBufferFlux`, `FirstByteDeliveryGuard`, `MultipartReplayability`, `ReactiveBodySource`, `SseIdleTimeoutException`, `SseOperation`, `SseReconnectPolicy`) | `src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/webclient/` | `6d27356e` | 결정 9: httpclient reactive 스택 삭제, blocking 경로 하나만 유지 | +| Reactor Netty transport (`ReactorNettyTransportProvider`, `ReactorHttpClientFactory`, `ReactorConnectionProviderFactory`, `ReactorFailureClassifier`, `ReactorPoolMetricsBinder`) | `.../httpclient/reactor/` | `6d27356e` | 결정 9 | +| reactive 자격증명 (`ReactiveCredentialProviderRegistry`, `ReactiveRequestCredentialProvider`) | `.../httpclient/auth/` | `6d27356e` | 결정 9 | +| reactive 재시도·resilience (`ReactiveAttemptResiliencePipeline`, `ReactiveLogicalCall`, `ReactiveRetryCoordinator`) | `.../httpclient/resilience/` | `6d27356e` | 결정 9 | +| reactive typed client (`DefaultReactiveHttpServiceRegistry`, `ReactiveHttpServiceRegistry`, `ReactiveKernelHttpExchangeAdapter`, `ReactiveOperationContext`, `ReactiveServiceInvocationHandler`), `ServiceOperationDescriptor.reactive` 플래그와 blocking/reactive 혼합 검사 | `.../httpclient/service/` | `6d27356e` | 결정 9 | +| reactive transport SPI (`ReactiveTransportProvider`, `ReactiveTransportCapabilities`), `TransportCapabilityValidator`의 reactive overload | `.../httpclient/transport/` | `6d27356e` | 결정 9 | +| 설정 키 `app.httpclient.clients[N].api`(`APP_HTTPCLIENT_CLIENTS_N_API`)와 `ClientApiType`, `TransportType.REACTOR_NETTY`, actuator `api` 항목 | `.../httpclient/profile/ClientApiType.java`, `docs/httpclient/env-fields.yaml` | `6d27356e` | 남은 값이 하나뿐인 키(동작하지 않는 옵션은 키를 두지 않음). H2 전용 프로필은 이제 모든 transport에서 `HTTP2_REQUIRED_TRANSPORT_UNSUPPORTED` | +| 기동 위반 코드 `REACTIVE_REDIRECT_UNSUPPORTED`, `REACTIVE_AUTHENTICATION_UNSUPPORTED`, `DYNAMIC_TARGET_PROFILE_API_UNSUPPORTED` | `.../profile/ClientProfileValidator.java`, `.../autoconfigure/HttpClientStartupValidator.java` | `6d27356e` | reactive 프로필이 없어 판정 대상 없음 | +| reactive bean (`httpClientReactiveTransportProviders`, `httpClientReactiveCredentialProvider`, `ReactiveAttemptExecutor`, `reactiveHttpGateway`, `ReactiveHttpServiceRegistry`, `ReactiveStreamingGateway`, `ReactiveSseGateway`) | `.../httpclient/autoconfigure/` | `6d27356e` | 결정 9 | +| reactive 테스트 (`BlockHoundEventLoopTest`, `DefaultReactiveHttpGatewayTest`, `FirstByteRetryBoundaryTest`, `ReactiveSseGatewayTest`, `ReactiveStreamingLifecycleTest`, `ReactiveRetryCoordinatorTest`, `ReactiveHttpServiceRegistryTest`, `ReactiveAuthenticationContractTest`, `BlockingReactiveSignatureSeparationTest`), 계약·protocol 테스트의 reactor case | `src/adapter/outbound/httpclient/src/test/java/...` | `6d27356e` | 대상 코드 삭제. forward proxy 경로 테스트는 blocking(Apache)으로 옮김(`ForwardProxyContractTest.gatewayRoutesTheCallThroughTheConfiguredForwardProxy`) | +| reactive testkit (`ReactiveTestGateways`, `ReactiveTransportContract`, `ReactiveEventsClient`, `MixedSignatureClient`, `NettyLeakDetectionExtension`, `EventPayload`, `MockHttpServer.enqueueSse`, `ClientProfiles.reactor`, `HttpClientContract.blockHoundSelected`) | `src/adapter/outbound/httpclient/src/testFixtures/java/...` | `6d27356e` | 대상 코드 삭제 | +| `Http2StreamSaturationTest`(Reactor Netty 전용), `ReactiveClientBenchmark` | `.../src/httpClientPerformanceTest/...`, `.../src/jmh/...` | `6d27356e` | 대상 transport 삭제 | +| `httpClientBlockHoundTest` lane, `check` 의존, 계약 lane 기본 transport의 `reactor`, `io.netty.leakDetection.level` 시스템 속성 | `src/adapter/outbound/httpclient/build.gradle` | `6d27356e` | reactor event loop이 없어 검증 대상 없음 | +| 의존 `spring-webflux`, `reactor-core`, `reactor-netty-http`, `reactor-test`, `blockhound`, testFixtures `netty-common`·`logback-classic`·`reactor-core`, 카탈로그 `blockhound` | `src/adapter/outbound/httpclient/build.gradle`, `src/gradle/libs.versions.toml` | `6d27356e` | 결정 9 | +| CI matrix `transport: reactor`, release의 `httpClientBlockHoundTest` | `.github/workflows/pr-adapters.yml`, `.github/workflows/release.yml` | `6d27356e` | 없는 lane·transport 호출 제거 | +| `MongoBulkWritePlan.estimatedEncodedBytes` (plan 생성 시 `toJson()` 크기 추정) | `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/imperative/bulk/MongoBulkWritePlan.java` | `6d27356e` | 매핑 전 값에 codec이 없어 실패(F-4b). 매핑된 문서의 실제 BSON 크기 검사(`MongoBulkExecutor.mappedWrites`)로 대체 | +| `MongoCsfleClientFactory.settingsFor`의 `encryptedFieldsMapJson` 인자 | `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/advanced/encryption/csfle/MongoCsfleClientFactory.java` | `6d27356e` | 호출자 JSON을 schema로 쓰던 경로(F-5b). `profile.fields()`에서 생성 | +| 설정 키 `ca-skeleton.persistence-mongo.active-profile` | `src/adapter/outbound/persistence-mongo/src/main/resources/config/mongo.yml` | `6d27356e` | `ca-skeleton.persistence-mongo.platform.active-profile`로 이동(F-2a, `MongoPlatformSettings`에 한 번 바인딩). env 키는 그대로 | +| `GitCommandResult` record | `src/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/GitCommandResult.java` | `6d27356e` | O-3b에서 git 호출이 exit code를 직접 판정하는 `checkIgnore` 하나로 줄어 쓰는 곳이 없음 | +| `git rev-parse --show-toplevel` 호출(checkout 판정) | `VerifyNoIgnoredSourcePackagesTask.java` | `6d27356e` | 실패하면 "checkout 아님"으로 읽혀 게이트가 통과하던 원인. `.git` 존재 판정으로 대체 | +| compose 계약 필드 `expectedSwitchesOn` | `src/config/runtime/compose-profile-contracts.json` | `6d27356e` | 읽는 코드가 없던 필드. `expectedCapabilitiesOn`(info 이름)으로 재정의 | diff --git a/docs/fileserver/configuration.md b/docs/fileserver/configuration.md index b7461e2b..2e7c40e4 100644 --- a/docs/fileserver/configuration.md +++ b/docs/fileserver/configuration.md @@ -117,7 +117,7 @@ Set `inline-safe-profile: true` only when downloads are never served inline from | Key | Default | Meaning | | --- | --- | --- | | `instance-upload-permits` | `16` | concurrent uploads this node admits | -| `scope-upload-permits` | `4` | concurrent uploads one namespace admits | +| `scope-upload-permits` | `4` | concurrent uploads one caller (principal) admits; over it is a retryable `429` | | `direct-download-permits` | `64` | concurrent non-delegated downloads | | `soft-high-water` | `0.70` | storage fraction at which pressure is reported | | `hard-high-water` | `0.85` | storage fraction at which uploads are refused | @@ -141,6 +141,11 @@ without it still queues cleanup items; another node or an operator reclaims them eight times is abandoned rather than retried forever — it stays visible to an operator, parked rather than discarded. +Each pass also expires uploads whose `expiresAt` has passed (the record becomes `EXPIRED` and its +staged bytes are queued), purges orphans the admin plane retired to quarantine, and runs +reconciliation over stale `UPLOADED`/`VERIFYING`/`FAILED` records, so an ambiguous publish settles +without an operator. + ## Management plane — `admin` | Key | Default | Meaning | diff --git a/docs/fileserver/http-contract.md b/docs/fileserver/http-contract.md index 05589e22..8405fd1c 100644 --- a/docs/fileserver/http-contract.md +++ b/docs/fileserver/http-contract.md @@ -56,7 +56,7 @@ port rather than the public one. | `401` | unauthenticated | | `403` / `404` | denied, or hidden under the existence-hiding profile | | `409` | state, offset, or lease conflict | -| `410` | expired upload resource | +| `410` | expired or ended (cancelled, rejected, quarantined) upload resource | | `411` | `require-content-length` profile with no length | | `412` | precondition failed | | `413` | size or quota policy violation | diff --git a/docs/httpclient/operations.md b/docs/httpclient/operations.md index 1147bd59..f735e861 100644 --- a/docs/httpclient/operations.md +++ b/docs/httpclient/operations.md @@ -105,7 +105,10 @@ evidence, replayability, stage, retryability, attempt, elapsed, remaining deadli | `HttpDeadlineExceededException` | the effective deadline was reached | never | | `HttpCircuitOpenException` | the upstream circuit is open | never | | `HttpBulkheadRejectedException` | no attempt or logical admission permit was available | never | -| `HttpRateLimitRejectedException` | the local attempt rate limit or retry budget rejected the attempt | never | +| `HttpRateLimitRejectedException` | the local attempt rate limiter rejected the attempt | never | +| `HttpRetryBudgetExhaustedException` | the per-upstream retry budget refused a further attempt | never | +| `HttpRuntimeDrainingException` | the profile's runtime was retired (certificate rotation) before a granted retry started | never — a new call runs on the replacement | +| `HttpUnknownTransportException` | the engine failed in a way no category above describes; the metadata evidence, not the type, says whether it was sent | never | | `HttpAmbiguousExecutionException` | a non-idempotent request was sent and the outcome is unknown | never — reconcile instead | ## Traces diff --git a/docs/messaging/configuration-reference.md b/docs/messaging/configuration-reference.md index 0e3c748f..2dd4be8f 100644 --- a/docs/messaging/configuration-reference.md +++ b/docs/messaging/configuration-reference.md @@ -166,6 +166,12 @@ app: `kafka`뿐이다. 위 예시가 `production: false`인 것은 이 페이지가 그대로 실행되는 fixture이기 때문이며, 실 배포는 셋 다 참이다. +Kafka producer는 이 항목 하나로 만든다. `bootstrap-servers`, `acks`, `enable-idempotence`, +`max-in-flight-requests-per-connection`, `delivery-timeout`이 그대로 client 설정이 된다. +`spring.kafka.bootstrap-servers`는 읽지 않는다. type이 `kafka`인 항목이 정확히 하나가 아니면 기동에 +실패한다. `send()`가 metadata를 기다리며 호출 스레드를 막는 시간(`max.block.ms`)은 기본 publish +timeout(5s)이다. + ## 보안 ```yaml diff --git a/docs/messaging/outbox-inbox.md b/docs/messaging/outbox-inbox.md index d4b68ab7..fede443b 100644 --- a/docs/messaging/outbox-inbox.md +++ b/docs/messaging/outbox-inbox.md @@ -21,7 +21,7 @@ Flyway version `1000..1999`를 예약해서 애플리케이션의 일반적인 classpath:db/migration/messaging ``` -현재 순서는 `V1001..V1004`(outbox/admin)와 `V1101`(inbox)이다. starter 테스트가 두 JDBC +현재 순서는 `V1001..V1005`(outbox/admin)와 `V1101`(inbox)이다. starter 테스트가 두 JDBC 모듈을 실제 combined classpath로 올려 version 중복과 예약 대역 이탈을 검사한다. 개별 DDL의 의미와 전환 순서는 [migration-guide.md](migration-guide.md)를 따른다. @@ -46,6 +46,11 @@ leaseBatch(100, 30s) -- lease로 다중 relay 인스턴스 안전 → REJECTED → markFailed ``` +row 하나의 실패는 그 row에서 끝난다. envelope로 만들 수 없는 row(예약 header `msg.*`를 담은 row +등)는 `FAILED`가 되고, publisher가 예외를 던지면 결과를 모르므로 `AMBIGUOUS`가 된다. 같은 batch의 +나머지 row는 그대로 publish된다. pass 전체가 실패하면(DB 연결 등) WARN 로그를 남기고 +`messaging.outbox.relay.failed.passes` 카운터를 올린다. + ### 핵심 규칙: ambiguous는 같은 messageId로 재시도 새 id를 발급하면 "전달됐을 수도 있는 메시지"가 "확실히 두 번째인 메시지"가 되어 @@ -61,8 +66,16 @@ status IN ('PENDING','AMBIGUOUS','IN_FLIGHT') AND (lease_expires_at IS NULL OR lease_expires_at <= now) AND next_attempt_at <= now AND attempts < maxAttempts + AND (ordering_key IS NULL + OR 같은 destination·ordering_key의 더 오래된 미완료 row가 없음) ``` +`ordering_key`가 있는 row는 같은 key의 더 오래된 row가 `PENDING`·`AMBIGUOUS`·`IN_FLIGHT`인 동안 +claim되지 않는다. 이 조건이 없으면 두 relay가 같은 key의 두 row를 나눠 가져가거나, AMBIGUOUS로 +재시도되는 row보다 뒤의 row가 먼저 나간다(`OutboxPostgresIT#aNewerRowWaitsWhileAnOlderRowWithTheSameOrderingKeyIsUnfinished`). +`V1005`의 partial index가 이 확인을 받친다. 더 오래된 row가 `FAILED`·`EXHAUSTED`가 되면 뒤의 row는 +진행한다. + `IN_FLIGHT`가 목록에 있는 것이 핵심이다. relay가 publish 도중 죽으면 row는 `IN_FLIGHT`로 남는데, 이를 제외하면 그 메시지는 **영원히** 발행되지 않는다 — outbox가 막으려던 바로 그 실패다. 대신 lease가 만료됐을 때만 회수하므로, 살아 있는 relay가 들고 있는 row는 회수되지 않는다. @@ -107,6 +120,9 @@ message_id만으로 중복 제거하면 같은 event를 소비하는 두 번째 broker의 최대 redelivery window보다 **길어야** 한다. row를 먼저 지우면 늦게 도착한 redelivery가 두 번 처리된다. +outbox·inbox cleanup job은 한 번에 최대 1,000행씩 지우고, 지운 수가 1,000보다 적으면 멈춘다. +repository port에는 개수 제한 없는 삭제 메서드가 없다. + ## CDC 대안 relay는 polling 하나뿐이다. Debezium Event Router 매핑(`DebeziumOutboxEventRouter` 등)은 조립하는 diff --git a/docs/messaging/retry-dlq-redrive.md b/docs/messaging/retry-dlq-redrive.md index 39355e65..9d64b635 100644 --- a/docs/messaging/retry-dlq-redrive.md +++ b/docs/messaging/retry-dlq-redrive.md @@ -49,6 +49,15 @@ full jitter는 `[0, delay]` 균등 분포다. jitter가 없으면 같은 초에 pause-and-seek는 메시지가 로그의 자기 자리를 떠나지 않는다. partition을 멈추고, 기다리고, 같은 offset으로 seek해 재전달한다. 뒤의 메시지도 함께 기다리며 이것이 의도된 동작이다. +`KafkaConsumerRegistrar`가 handler 실패(예외, settle 없이 끝남, timeout)를 다루는 방식: + +- 재전달은 destination `retry`의 backoff 뒤에 한다. 최소 1초. 0초 재시도는 없다. +- 같은 offset의 실패 횟수가 `retry.maxAttempts`에 닿으면 `KafkaQuarantinePublisher`에 쓰고, + 쓰기가 확인되면 offset을 넘긴다. quarantine이 없으면 backoff로 계속 재시도한다(메시지를 버리지 + 않는다). 그래서 `production` destination은 quarantine 없이 만들 수 없다(`KAFKA_QUARANTINE_REQUIRED`). +- handler timeout이 지나도 handler가 끝날 때까지 partition slot을 잡고 있는다. `CompletableFuture`를 + cancel해도 handler는 멈추지 않으므로, slot을 먼저 풀면 같은 offset이 두 번 동시에 돈다. + ## RabbitMQ: delayed retry queue core broker에 per-message delay가 없으므로 **TTL + DLX**로 구현한다. diff --git a/docs/mongodb/consistency-transaction-guide.md b/docs/mongodb/consistency-transaction-guide.md index bff0f3e3..17771a94 100644 --- a/docs/mongodb/consistency-transaction-guide.md +++ b/docs/mongodb/consistency-transaction-guide.md @@ -120,3 +120,8 @@ driver type. unordered bulk write that partially fails is `PARTIAL_BULK_WRITE`, not a failure: some documents were written. The result's per-item outcomes say which indexes succeeded and which failed, so a caller can resume rather than replay. + +`execute(context, documentType, plan)` maps every filter and update through the document type, as +the single-document path does, so `@Field` names and registered converters (`DomainDocumentId`, +`BigInteger`) mean the same thing in a batch. The command's byte ceiling is measured on those mapped +documents before anything is sent. diff --git a/docs/notification/api-surface-snapshot.txt b/docs/notification/api-surface-snapshot.txt index 3ad1fe19..0aa046fa 100644 --- a/docs/notification/api-surface-snapshot.txt +++ b/docs/notification/api-surface-snapshot.txt @@ -2,7 +2,7 @@ # Every top-level public type under the platform packages. Growth is a reviewed change. # Update only after review with: # ./gradlew :adapter:outbound:notification:updateNotificationApiSurface -PapproveNotificationApiSurfaceChange -# types: 379 +# types: 380 dev.caskeleton.adapter.outbound.notification.NotificationConfig dev.caskeleton.adapter.outbound.notification.NotificationRoutesSettings dev.caskeleton.adapter.outbound.notification.core.FailOpenNotificationProvider @@ -59,6 +59,7 @@ dev.caskeleton.adapter.outbound.notification.platform.observation.NotificationHe dev.caskeleton.adapter.outbound.notification.platform.observation.NotificationHealthSnapshot dev.caskeleton.adapter.outbound.notification.platform.observation.NotificationServingThresholds dev.caskeleton.adapter.outbound.notification.platform.provider.EmailAttachments +dev.caskeleton.adapter.outbound.notification.platform.provider.EmailRecipients dev.caskeleton.adapter.outbound.notification.platform.provider.ProviderResults dev.caskeleton.adapter.outbound.notification.platform.provider.UnconfiguredAttachmentResolver dev.caskeleton.adapter.outbound.notification.platform.provider.http.JdkNotificationHttpGateway diff --git a/docs/registries/env-keys.yaml b/docs/registries/env-keys.yaml index 0d2e859a..3b8635f5 100644 --- a/docs/registries/env-keys.yaml +++ b/docs/registries/env-keys.yaml @@ -2945,8 +2945,9 @@ env_keys: - name: APP_MESSAGING_KAFKA_BROKERS # source: feature-domain-event-outbox-contract — "Kafka는 optional integration adapter" # (broker 활성화 시 endpoint 필요) - # Also feeds spring.kafka.bootstrap-servers (the messaging platform's Kafka transport) through - # the Kafka module's config/module-defaults/messaging.yml, so one key addresses both paths. + # Also feeds app.messaging.brokers.kafka.bootstrap-servers (the messaging platform's Kafka + # transport) through the Kafka module's config/module-defaults/messaging.yml, so one key + # addresses both paths. spring.kafka.bootstrap-servers is not read. type: csv_list default: null allowed_values: null @@ -3472,7 +3473,7 @@ env_keys: required_test: fileserver-platform:off-state-zero-side-effects-and-env-round-trip - name: APP_FILESERVER_PLATFORM_QUOTA_SCOPE_UPLOAD_PERMITS - # Concurrent uploads admitted per namespace. + # Concurrent uploads admitted per caller (principal). type: integer default: 4 allowed_values: null diff --git a/docs/reviews/2026-09-25-review-followup-results/P1.md b/docs/reviews/2026-09-25-review-followup-results/P1.md new file mode 100644 index 00000000..4f07ecff --- /dev/null +++ b/docs/reviews/2026-09-25-review-followup-results/P1.md @@ -0,0 +1,51 @@ +## 행 결과 +| ID | 결과 | 근거 | +|---|---|---| +| M-2c | 완료 | `BrokerAccessListTest.aDeclaredDestinationTheSecurityEntryDoesNotListIsRejectedAsForbidden` FAIL("Expecting Optional[PUBLISH_PREPARATION_FAILED] to contain PUBLISH_FORBIDDEN" — 목록 밖 destination이 접근 검사를 통과) → PASS. `messagingDestinationAccess`가 선언 destination 중 해당 broker security 항목의 `access.publishable`에 있는 것만 허용: `src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingCoreAutoConfiguration.java:422`. security 항목이 없는 broker는 기존대로 선언 destination 전부. 빈 목록이면 publish 불가(문서화: `docs/messaging/configuration-reference.md` 보안 절, `docs/messaging/security.md` ACL 절) | +| M-2d | 완료 | `KafkaProducerSecurityTest.theProducerAuthenticatesAsTheUsernameTheProviderReturnsNotAsTheCredentialId` FAIL(JAAS가 `username="kafka-producer"`=credential id, `password=` 고정, callback handler 없음) → PASS. `CredentialProvider.username(credentialId)` 추가(`src/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/CredentialProvider.java:43`), `CredentialRuntime.username()`, SASL 사용자 이름이 없으면 기동 실패 `SASL_USERNAME_MISSING`(`KafkaSecurityConfigurerTest.aSaslCredentialWhoseProviderNamesNoUserIsRefused`). 실제 lane: `MessagingSecuredBrokerQualificationTest.aPublishIsConfirmedByAPrivateCaBrokerThatRequiresSaslAsTheProviderUser` PASS, 확인용으로 provider 사용자 이름을 틀리게 바꾸면 REJECTED(broker가 SASL을 실제로 검사함) | +| M-2e | 완료 | NEW-4b와 같은 결함, 한 번 수정. `KafkaProducerSecurityTest.aPrivateCaTrustStoreReachesTheProducer`·`mutualTlsPresentsTheProducerKeyStoreUnlockedByItsCredential`·`mutualTlsOnABrokerWithoutTlsFailsStartup` FAIL("trust-store.location binds nothing") → PASS, `mutualTlsWithoutAKeyStoreFailsStartupNamingTheKey` PASS, `KafkaSecurityConfigurerTest.aTrustStoreOnABrokerWithoutTlsIsRefused` PASS. 설정: `app.messaging.security..trust-store.{location,type,password-credential-id}`, `.key-store.{location,type}`(`BrokerSecuritySettings.java`), 모델 `BrokerTrustStore`(신규), `BrokerCredentialProfile.MutualTls(credentialId, keyStoreLocation, keyStoreType)`(`BrokerCredentialProfile.java:58`), Kafka 설정 `ssl.truststore.*`/`ssl.keystore.*`(`KafkaSecurityConfigurer.java:102,129`). key-store 없는 MUTUAL_TLS·TLS 꺼진 MUTUAL_TLS·TLS 꺼진 trust-store는 기동 실패(평문 fallback 없음, `MessagingConfigurationCompiler.java:276`, `KafkaSecurityConfigurer.java:190`). 실제 lane: 테스트 시점에 keytool로 만든 사설 CA로 서명된 broker 두 개 — SASL_SSL, `ssl.client.auth=required` SSL — 로 publish CONFIRMED(`MessagingSecuredBrokerQualificationTest` 2건). trust-store 생략은 JVM 기본 trust store(공인 CA broker용, 문서화) | +| M-2f | 완료 | NEW-4d와 같은 결함, NEW-4d 방향(`sasl.client.callback.handler.class`) 채택. `KafkaProducerSecurityTest.aRotatedPasswordReachesTheNextAuthenticationWithoutRebuildingTheProducer` FAIL(callback handler 없음, 비밀번호가 JAAS 문자열에 고정) → PASS. JAAS는 login module 이름만(`... required;`), `KafkaCredentialCallbackHandler`가 인증마다 `CredentialRuntimeRegistry`에서 사용자 이름·비밀번호를 읽음(`src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaCredentialCallbackHandler.java:62`, `KafkaSecurityConfigurer.java:156`). producer를 바꾸지 않으므로 transport generation 1 유지 — 주석 정정(`KafkaMessagingAutoConfiguration.java:277`), Javadoc 정정(`KafkaSecurityConfigurer.java:15-30`), `docs/messaging/security.md` Rotation 절. 한계(문서화): registry는 provider가 만료 시각을 줄 때만 다시 가져옴, key/trust store 비밀번호는 client 재생성(재기동) 필요 | +| NEW-4b | 완료 | M-2e 행과 같은 수정·테스트 | +| NEW-4d | 완료 | M-2f 행과 같은 수정·테스트 | +| M-2b | 완료 | NEW-4c와 같은 결함. 결정대로 `spring.kafka.bootstrap-servers` 의존 제거(NEW-4c의 "spring.kafka fallback + 불일치 시 실패" 추천은 이 결정으로 대체). `KafkaProducerConfigTest.theProducerConnectsToTheBrokerEntryAddressesNotToSpringKafka`·`aBrokerWithoutAnEntryFailsStartupNamingTheKey` FAIL(broker 항목이 있어도 spring.kafka가 없으면 기동 실패 / spring.kafka만으로 기동) → PASS. producer는 type=kafka인 `app.messaging.brokers.` 항목 정확히 하나에서 만든다(`src/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaMessagingAutoConfiguration.java:150-205`). 모듈 기본값이 `APP_MESSAGING_KAFKA_BROKERS`를 `app.messaging.brokers.kafka.bootstrap-servers`로 연결(`src/adapter/outbound/messaging-kafka/src/main/resources/config/module-defaults/messaging.yml`), `KafkaCapabilityActivationTest` 2건 PASS. 함께 수정: `docs/registries/env-keys.yaml`(APP_MESSAGING_KAFKA_BROKERS 주석), `src/README.md`, `src/adapter/outbound/messaging-kafka/README.md`, compose 계약(`src/config/runtime/compose-profile-contracts.json`에서 `SPRING_KAFKA_BOOTSTRAP_SERVERS` 3곳 삭제, `scripts/verify-compose-profile-contracts.sh` 18 lane 일치), `docs/messaging/configuration-reference.md`. env 키 이름은 바뀌지 않음(`.env.example` 변경 없음) | +| NEW-4c | 완료 | M-2b 행과 같은 수정·테스트 | +| M-3 | 완료 | `KafkaConsumerRegistrarTest.aTimedOutHandlerStillRunningIsNotDispatchedASecondTime` FAIL("Expected size: 1 but was: 2" — 첫 handler가 도는 중 같은 offset 재dispatch) → PASS, `aTimedOutHandlerIsRedeliveredOnceItFinishesWithoutSettling` PASS. timeout이면 `cancel` 없이 `handler.whenComplete`에서 requeue와 permit·work count 반환(`src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrar.java:374-395`). 방향보다 한 단계 더: requeue도 완료 시점으로 미룸(maxInFlight>1에서도 같은 offset 동시 실행 없음). 결함을 고정하던 기존 테스트 `handlerTimeoutCancelsTheOutstandingHandlerBeforeThePartitionPermitIsReleased`(cancel 여부 단언) 삭제 | +| M-4a | 완료 | `DefaultMessagePublisherTest.anOversizedPayloadIsRejectedAsNotRetryableInsteadOfThrown` FAIL(`MessageTooLargeException` 동기 throw) → PASS, `aSaturatedPermitPoolRejectsAsRetryableWithinTheCallersDeadline` FAIL(5초 안에 끝나지 않음) → PASS. admission을 try 안으로, 크기 초과 REJECTED retryable=false, backpressure REJECTED retryable=true(`src/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisher.java:226-236,333`) | +| M-4b | 완료 | `OutboxRelayTest.aRowThatCannotBecomeAnEnvelopeFailsWhileTheRestOfItsBatchPublishes` FAIL(예약 header row의 예외가 `runOnce` 밖으로) → PASS(`[FAILED, PUBLISHED]`), `aPublisherThatThrowsLeavesTheRowAmbiguousRatherThanStrandingTheBatch` FAIL → PASS. envelope 변환 실패는 `markFailed`, publisher 예외는 결과 불명이라 AMBIGUOUS(같은 id로 재시도, attempt 예산 적용)(`src/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/OutboxRelay.java:176-190,254`). CLAIM 시 attempts 증가는 하지 않음: row 단위 처리로 poison row 무한 재claim이 사라짐. relay 프로세스가 row 처리 중 죽는 경우는 lease 만료 재claim으로 남음 | +| M-4c | 완료 | `MessagingOutboxRelayLifecycleTest.aRelayPassThatFailsIsCountedOnTheMeterRegistry` FAIL(`MeterNotFoundException 'messaging.outbox.relay.failed.passes'`) → PASS. `FunctionCounter messaging.outbox.relay.failed.passes`(`src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingReliabilityAutoConfiguration.java:124`), 원인 포함 WARNING 로그(`System.Logger`, `OutboxRelayWorker.java:193`). 로그 자체는 자동 테스트 없음. `OutboxRelayWorkerTest.aFailedPassDoesNotEndTheLoop`는 pass 실패를 DB 장애(repository 예외)로 재현하도록 변경(publisher 예외는 이제 row에서 처리됨) | +| M-5a | 완료 | `KafkaProducerConfigTest.theProducerStopsWaitingForMetadataWithinTheDefaultPublishDeadline` FAIL → PASS(`max.block.ms` = `PublishOptions.defaults().timeout()` 5s, `KafkaMessagingAutoConfiguration.java:186`), permit 대기를 남은 budget으로 제한(`InFlightLimiter.java:63`, `MessagingAdmissionController.java:91`, `DefaultMessagePublisher.java:232`), 테스트 `DefaultMessagePublisherTest.aSaturatedPermitPoolRejectsAsRetryableWithinTheCallersDeadline` | +| M-5b | 완료 | `ReactiveFacadeTest.theBlockingPublishRunsOffTheSubscribingThread` FAIL("Expected not same: Thread[#1,Test worker]") → PASS. `.subscribeOn(Schedulers.boundedElastic())`(`src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/DefaultReactiveMessagePublisher.java:41`) | +| M-6 | 완료 | `OutboxOperationsTest`·`InboxOperationsTest.cleanupAsksForBoundedBatchesAndStopsAtTheFirstShortOne` FAIL("Expecting [] to contain exactly [1000, ...]") → PASS. 두 job이 `(cutoff, 1000)`을 짧은 batch가 나올 때까지 반복(`OutboxCleanupJob.java:53`, `InboxCleanupJob.java:56`), port의 1-인자 purge와 JDBC 구현 삭제(`OutboxRepository`, `InboxRepository`, `JdbcOutboxRepository`, `JdbcInboxRepository`). PG lane `OutboxPostgresIT.retentionRemovesOnlyPublishedRows`·`InboxPostgresIT.retentionRemovesOldRows` bounded 호출로 PASS | +| M-7 | 완료 | `KafkaConsumerRegistrarTest.aFailedHandlerWaitsOutItsBackoffBeforeThePartitionIsReadAgain` FAIL(즉시 resume) → PASS, `aHandlerThatSpendsItsAttemptBudgetIsQuarantinedAndCommittedPast` FAIL("Expecting Optional to contain 11L but was empty") → PASS, `aProductionDestinationWithoutAQuarantineIsRefused` FAIL(거부 없음) → PASS. offset별 실패 횟수, `BackoffCalculator` 지연(최소 1초), `retry.maxAttempts` 도달 시 quarantine 후 commit, quarantine 없으면 backoff로 계속 재시도, production destination에 quarantine이 없으면 생성자에서 `KAFKA_QUARANTINE_REQUIRED`(`KafkaConsumerRegistrar.java:185,695`), `KafkaQuarantinePublisher.unavailable()`을 단일 인스턴스로. 재시도 시각은 주입 가능한 `InstantSource`. 참고: consumer는 아직 starter가 조립하지 않음(결정 10, Wave 3) | +| M-11 | 완료 | `OutboxPostgresIT.aNewerRowWaitsWhileAnOlderRowWithTheSameOrderingKeyIsUnfinished`(실제 PostgreSQL) — 새 조건을 끈 SQL로 FAIL(같은 key의 뒤 row까지 3건 claim) → PASS. 최소 수정(기동 거부) 대신 claim 제외를 택함: relay는 기동 때 어떤 destination이 outbox로 나가는지 알 수 없다. CLAIM에 "같은 destination·ordering_key의 더 오래된 PENDING/AMBIGUOUS/IN_FLIGHT row가 없을 것" 조건과 `(created_at, message_id)` 순서(`src/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/JdbcOutboxRepository.java:113-140`), 새 migration `V1005__messaging_outbox_ordering_key_index.sql`(messaging 예약 대역, `md5(ordering_key)` partial index). `twoRelaysClaimingConcurrently...` fixture는 서로 다른 key로 변경. `leaseBatch`(main 호출자 없음)에는 적용 안 함 | +| S6-#2b | 완료 | 기본값 불일치만 수정(조립 위치 이동은 X1-#1i, Wave 3 3-C). `OutboxSettingsTest.bindsAllSixDefaultsWhenFieldsAreNull` FAIL("Expecting value to be false but was true") → PASS, `OutboxConfigTest.withoutTheRelayKeyTheRelaySchedulerIsNotAssembled` FAIL(scheduler 조립됨) → PASS. `matchIfMissing` 삭제(`src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/outbox/OutboxConfig.java:69`), null 기본값 false(`OutboxSettings.java:37`), `src/app-bootstrap/README.md` 문구 | +| S6-lead-3 | 남음 | 이유: sample을 `OutboxAppendPort`로 옮기려면 `ValidatedIntegrationEvent`를 만들 encoder가 있어야 하는데 템플릿에 없다(`IntegrationEventEncoderPort` 구현 0). 결정 7(템플릿 JSON encoder 제공 + legacy 포트 삭제)이 Wave 3 3-C 작업. sample의 legacy 포트 사용처 3곳(`CreateWorkLogUseCase`, `PosterEventPublisher`, `PosterImagePublicationEventPublisher`) | +| S7-lead-3 | 남음 | 이유: = X1 표 Kafka producer(legacy `KafkaSender` R0 경로). 결정 7로 Wave 3 3-C에서 경로째 삭제. 이번 묶음 지시대로 legacy seam은 손대지 않음 | + +## 제거된 코드 +| 대상 | 경로 | 마지막으로 존재한 커밋 | 이유 | +|---|---|---|---| +| `OutboxRepository.purgePublishedBefore(Instant)`, `InboxRepository.purgeProcessedBefore(Instant)`와 JDBC 구현 | `src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/{Outbox,Inbox}Repository.java`, `src/messaging/messaging-{outbox,inbox}-jdbc-postgresql/src/main/java/.../Jdbc{Outbox,Inbox}Repository.java` | `6d27356e` | M-6: 개수 제한 없는 단일 DELETE. bounded 버전만 남김 | +| JAAS 문자열에 사용자 이름·비밀번호를 넣던 코드(`jaas`, `scramJaas`, `plainJaas`, `escapeJaas`)와 그 테스트 `aSecretWithQuotesIsEscaped`, `aSecretWithAControlCharacterIsRefused` | `src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaSecurityConfigurer.java`, `.../KafkaSecurityConfigurerTest.java` | `6d27356e` | M-2d/M-2f: 자격 증명이 JAAS에 들어가지 않으므로 escape할 값이 없음. callback handler로 대체 | +| `CredentialRuntime` 5-인자 생성자 | `src/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/CredentialRuntime.java` | `6d27356e` | username을 받는 생성자로 대체, 호출자는 registry 하나 | +| `BrokerCredentialProfile.MutualTls(String)` 1-인자 형태 | `src/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/BrokerCredentialProfile.java` | `6d27356e` | key store 없는 MUTUAL_TLS는 동작할 수 없음. `(credentialId, keyStoreLocation, keyStoreType)`으로 대체 | +| 테스트 `handlerTimeoutCancelsTheOutstandingHandlerBeforeThePartitionPermitIsReleased` | `src/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrarTest.java` | `6d27356e` | M-3: CompletableFuture cancel을 단언해 결함을 고정하던 테스트 | +| `spring.kafka.bootstrap-servers` 모듈 기본값, compose 계약의 `SPRING_KAFKA_BOOTSTRAP_SERVERS` 3곳, producer의 `Environment` 인자 | `src/adapter/outbound/messaging-kafka/src/main/resources/config/module-defaults/messaging.yml`, `src/config/runtime/compose-profile-contracts.json`, `src/messaging/messaging-spring-boot-starter-kafka/.../KafkaMessagingAutoConfiguration.java` | `6d27356e` | M-2b: broker 주소 출처를 `app.messaging.brokers.` 하나로 | + +## 새로 발견한 결함 +- `P1-new-1` (고침) `src/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaMessagingAutoConfiguration.java` — broker 항목의 `acks`, `enable-idempotence`, `max-in-flight-requests-per-connection`, `delivery-timeout`을 검증만 하고 producer에는 하드코딩 값을 넣음(capability 기준 3 위반). 적용하자 기본 `delivery-timeout: 30s`가 Kafka 4의 `linger.ms(5) + request.timeout.ms(30s)` 조건에 걸려 producer 생성이 실패함 → `linger.ms=0`, `request.timeout.ms=min(30s, delivery-timeout)`으로 맞춤. 테스트 `KafkaProducerConfigTest.theProducerAppliesTheBrokerEntryDeliverySettings` FAIL → PASS +- `P1-new-2` (고침) `src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrar.java` — in-flight 천장·drain·pool 거부로 pause한 partition을 다시 resume하는 코드가 없음. ordered partition은 한 poll에 두 record를 받으면 첫 record 뒤 영구 정지. `resumeSaturated()`(`:463`) 추가. 테스트 `KafkaConsumerRegistrarTest.aPartitionPausedAtItsCeilingResumesOnceItsDeliveryFinishes` FAIL("Expected size: 2 but was: 1") → PASS +- `P1-new-3` (고침) 같은 파일 — requeue 재개 시각을 `Instant.now()`로, poll은 호출자가 준 `now`로 비교해 두 시계가 섞임(테스트에서 재시도가 영원히 안 풀리거나 즉시 풀림). `InstantSource` 하나로 통일(M-7 수정에 포함) +- 참고(결함 아님, 문서화): `CredentialRuntimeRegistry`는 provider가 만료 시각을 주지 않으면 credential을 다시 가져오지 않음 → 만료 시각 없는 credential은 rotation되지 않음(`docs/messaging/security.md`) + +## 검증 +- `./gradlew :messaging:messaging-{security,kafka,runtime-core,policy,outbox-jdbc-postgresql,inbox-jdbc-postgresql,reliability-api,spring-boot-starter,spring-boot-starter-kafka}:check :adapter:outbound:messaging-kafka:check :app-bootstrap:check` — 통과 (app-bootstrap test 455건, skip 5 기존 조건부; messaging·adapter 단위 테스트 전부 통과) +- `:messaging:messaging-spring-boot-starter:integrationTest`(실제 Kafka 4.1.0) — 3/3 통과: 기존 round trip + 사설 CA SASL_SSL + 사설 CA mTLS +- `:messaging:messaging-kafka:verifyMessagingCertificationEvidence`(messagingCertificationTest, Kafka+Toxiproxy) — 37/37 통과, 커밋된 manifest 변경 없음 +- `:messaging:messaging-outbox-jdbc-postgresql:integrationTest` 29/29, `:messaging:messaging-inbox-jdbc-postgresql:integrationTest` 6/6 (실제 PostgreSQL) +- `./gradlew architectureCheck :app-bootstrap:verifyEnvKeys` — 통과 +- `scripts/verify-compose-profile-contracts.sh` — 18 lane 일치 +- 실행 안 함: `verifyDependencyLocks`(의존성 변경 없음), 전체 `mainCheck`(묶음 범위 밖, 건드린 messaging lane만 실행) + +## 추가한 migration +- `src/messaging/messaging-outbox-jdbc-postgresql/src/main/resources/db/migration/messaging/V1005__messaging_outbox_ordering_key_index.sql` (messaging 예약 대역 1000–1999, persistence-jpa `applied-migrations.sha256` 대상 아님) diff --git a/docs/reviews/2026-09-25-review-followup-results/P10.md b/docs/reviews/2026-09-25-review-followup-results/P10.md new file mode 100644 index 00000000..49aba680 --- /dev/null +++ b/docs/reviews/2026-09-25-review-followup-results/P10.md @@ -0,0 +1,29 @@ +## 행 결과 +| ID | 결과 | 근거 | +|---|---|---| +| I-5a | 완료 | 커밋 `983cc832`(W1). 결정대로 `FORWARDED_HEADERS_TRUSTED` 모드 삭제. 비인증 키는 `getRemoteAddr()` 하나(`src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/ratelimit/RateLimitKeyResolver.java:45`). `RateLimitWebConfigTest.spoofedForwardedForDoesNotChangeTheUnauthenticatedKey`(Review Focus 3: 옛 `client-ip-mode=forwarded-headers-trusted`를 남긴 배포에서 위조 XFF 두 개를 보내도 키가 peer 주소 하나) FAIL(`Expecting actual ["9:CLIENT_IP\|12:198.51.100.1\|…", "…198.51.100.2…"] to contain exactly ["9:CLIENT_IP\|11:203.0.113.7\|…" ×2]`)→PASS. `server.forward-headers-strategy=framework`면 rate limit 켤 때 기동 거부(`RateLimitWebConfig.java:38`), `RateLimitWebConfigTest.frameworkForwardHeadersStrategyIsRefusedWhileRateLimiting` FAIL(`context started successfully`)→PASS. env 키 `APP_RATE_LIMIT_CLIENT_IP_MODE`·설정 키 `app.rate-limit.client-ip-mode` 삭제(`env-keys.yaml`, `.env.example`, `cache-redis.yml`, sample `application.yml`, README 2곳). `APP_SERVER_FORWARD_HEADERS_STRATEGY` allowed_values `[none, native]`, `.env.example` 값 `framework`→`native`, `server.yml` 주석에 `native` + `server.tomcat.remoteip.internal-proxies` 명시 | +| NEW-10c | 완료 | I-5a와 같은 수정(같은 커밋·테스트). 현황표 수정 방향(`trusted-proxies` CIDR 설정 추가)은 오케스트레이터 결정(모드 삭제 + native/internal-proxies)으로 대체. `.env.example`이 `framework`(모든 peer의 XFF를 믿음)를 기본으로 권하던 것도 이 행의 원인이라 `native`로 바꾸고 `framework`는 rate limit 기동 거부로 막음 | +| X2-P2-7b | 완료 | I-5a와 같은 결함. client IP 해석 경로가 `getRemoteAddr()` 하나만 남음(XFF를 직접 읽는 main 코드 grep 0건, `ForwardedHeaderClientIpResolver` 삭제). 남은 `web-notification/.../ExternalRequestUrlResolver`는 client IP가 아니라 URL(proto/host) 해석이고 이미 trusted proxy일 때만 읽는다. 그 forwarded 파싱 삭제·설정 통합은 현황표 I-5b(W3)가 소유해서 이번에 건드리지 않음 | +| I-8b | 완료 | NEW-10b와 같은 수정. `CorsSettingsTest.originThatIsNotExactlySchemeHostPortFailsWithTheEnvKeyName`(10개 입력) FAIL(`Expecting actual not to be null` — 예외 없음)→PASS, `exactOriginWithPortIsAccepted` PASS. `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/settings/CorsSettings.java:44,64`. 옛 validator 규칙 중 둘은 넣지 않음: "소문자만"(Spring `CorsConfiguration.checkOrigin`이 대소문자 무시 비교), "credentials면 allowedHeaders `*` 거부"(Spring은 `*`를 요청 헤더 목록으로 되돌려 주므로 credentials와 함께 동작한다 — 넣으면 지금 동작하는 기본값(`*`)을 깨뜨림) | +| NEW-10b | 완료 | `CorsSettings` compact constructor가 origin마다 `URI` 파싱: `http`/`https`, host 필수, path(끝 `/` 포함)·query·fragment·user info·와일드카드 호스트·`"null"` 거부, `*`는 기존대로 credentials 없을 때만. 메시지에 `APP_SECURITY_CORS_ORIGINS (ca-skeleton.cors.allowed-origins)`. 테스트는 I-8b 행 | +| NEW-10a | 완료 | `RequestBodyBoundaryTest.duplicateJsonKeyIsRejectedAsValidationFailure`(`{"role":"user","role":"admin"}` → 400 `VALIDATION_FAILED`) FAIL(`Status expected:<400> but was:<200>`)→PASS. `JsonMapperBuilderCustomizer`로 `StreamReadFeature.STRICT_DUPLICATE_DETECTION`(`src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/mvc/autoconfigure/WebMvcPlatformAutoConfiguration.java:84`). 위치는 현황표의 `WebAdapterAutoConfiguration` 대신 같은 leaf의 `WebMvcPlatformAutoConfiguration`(요청 경계 필터와 같이 servlet 앱 조건·`backend.web.mvc.enabled`에 묶이고, 테스트가 무거운 security 조립 없이 이 루트 하나로 검증됨) | +| I-2b | 완료 | `RequestBodyBoundaryTest.jsonBodyOverTheCeilingIsRejectedAsPayloadTooLarge` FAIL(`Response status expected:<413> but was:<200>`)→PASS, `jsonBodyWithinTheCeilingReachesTheController` PASS. 새 `JsonBodyLimitFilter`(`src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/mvc/filter/JsonBodyLimitFilter.java:33`): JSON 본문만(multipart·form·tus·콜백은 각자 상한), 선언 Content-Length 초과는 읽기 전에, chunked/거짓 길이는 스트림 계수로 `MaxUploadSizeExceededException` → 기존 핸들러 413 `PAYLOAD_TOO_LARGE` Envelope. Jackson이 bean 속성 안에서 이 예외를 감싸는 경우도 413(`GlobalExceptionHandler.java:281`), `GlobalExceptionHandlerTest.unreadableBodyCausedByTheSizeCeilingIsPayloadTooLarge` FAIL(`expected: 413 CONTENT_TOO_LARGE but was: 400 BAD_REQUEST`)→PASS, `JsonBodyLimitFilterTest` 2건. 상한은 `backend.web.mvc.max-json-body-size`(기본 1MB, `WebMvcPlatformSettings.java:31`). JSON 깊이는 Jackson 3.1 기본 `StreamReadConstraints`(maxNestingDepth 500, maxNumberLength 1000)가 Boot가 만든 mapper에 이미 적용되어 있어 따로 두지 않음(`MapperBuilder`에 factory 제약을 바꾸는 API가 없어 customizer로는 설정 불가). 문서·문자열 길이는 본문 상한이 막음 | +| I-2a | 완료 | `NotificationCallbackMvcControllerTest.aDeclaredOversizeBodyIsRefusedWithoutReadingIt`, `anUndeclaredOversizeBodyIsRefusedAfterReadingOneByteOverTheCeiling` FAIL(컴파일: `method callback … cannot be applied to given types` — `@RequestBody byte[]` 시그니처)→PASS. 컨트롤러가 `HttpServletRequest`만 받아 Content-Length 초과면 읽지 않고 413, 아니면 `readNBytes(max+1)`(`src/adapter/inbound/web-notification/src/main/java/dev/caskeleton/adapter/inbound/web/notification/platform/callback/NotificationCallbackMvcController.java:85,91`) | +| I-3b | 완료 | 커밋 `5c08d3be`(W2). `GlobalExceptionHandlerTest.classLevelConstraintViolationIsReportedAgainstTheRequest` FAIL(`expected: [{code=INVALID, field=request, message=Invalid value}] but was: []`)→PASS. `getAllErrors()`(`GlobalExceptionHandler.java:263`), `ClientSafeValidationDetails.from(ObjectError)`가 global error를 `field=request`로(`ClientSafeValidationDetails.java:56`) | +| I-4a | 완료 | request/correlation/trace/span id 발급·MDC·응답 헤더를 `WebMvcRequestIdFilter`(HIGHEST+10, Security 앞) 한 곳으로 이동(`src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/mvc/filter/WebMvcRequestIdFilter.java:95,103`), ERROR/ASYNC 재디스패치에 같은 값 복원. `SecurityModeWebContractTest.anUnauthenticatedRejectionCarriesTheAssignedRequestIdInItsMeta`(실제 JWT security 체인이 쓴 401 Envelope의 `meta.requestId` = `X-Request-Id`) FAIL(`expected: "13499754-…" but was: null`)→PASS. `WebMvcRequestIdFilterTest.assignedIdentifiersAreOnMdcDuringTheChainAndMatchWhatTheResponseCarries`·`inboundCorrelationIdLosesLineBreaksBeforeReachingMdc` FAIL(`No value present` / `expected "fooFAKE LOG" but was null`)→PASS, `mdcIsClearedWhenTheRequestLeavesTheFilter`·`anErrorRedispatchRestoresTheSameIdentifiersOnMdc` PASS. 순서: `OperationalContractRuntimeTest.requestIdFilterIsRegisteredAheadOfSpringSecurity`(`src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/runtime/OperationalContractRuntimeTest.java:135`, 슬라이스에 `SecurityFilterAutoConfiguration`을 넣어 실제 `springSecurityFilterChain` 등록과 비교) PASS. fixture 문제: `PipelineOrderFixtureApplication`은 의미 순서·async 1회 관측만 증명한다고 주석에 적고 실제 순서는 위 두 테스트가 맡음. `RequestLoggingFilter`는 principal을 읽으려고 보안 체인 안쪽에 남음 → 체인이 거절한 요청의 접근 로그 줄은 없고 entry point/access-denied handler의 `security failure` 로그(이제 request_id 포함)가 대신함 | +| I-4b | 완료 | trace는 `WebMvcRequestIdFilter`만 만든다(`TraceParent.parse` 또는 새 root, WebTraceId·MDC·응답 `traceparent`가 같은 값). `RequestLoggingFilterTest.assignsNoIdentifierOrTraceOfItsOwn` FAIL(`Expecting [X-Request-Id, X-Correlation-Id, traceparent] not to contain …`)→PASS, `WebMvcRequestIdFilterTest.responseTraceparentCarriesTheTraceIdTheFilterAssigned`·`validInboundTraceparentIsAdoptedWithItsSpanAndEchoed` FAIL(`NullPointerException` — 헤더 없음)→PASS. `RequestLoggingFilter`의 id/trace 생성 코드 삭제(`src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/filter/RequestLoggingFilter.java`), 옮겨진 테스트는 `WebMvcRequestIdFilterTest`로 | +| I-6a | 완료 | 결정 13. 컨트롤러의 `DEFAULT_CATEGORY="transactional"` 삭제, `request.category()`를 그대로 넘김(`NotificationSubmissionController.java:87`). 판정은 `AcceptNotificationCommand`(application-notification, `AcceptNotificationCommand.java:70`)가 → `IllegalArgumentException` → 400 `BAD_PARAMETER`. `NotificationSubmissionControllerTest.submissionWithoutCategoryIsRejectedBeforeTheUseCaseRuns` FAIL(`[500, 1]` — 유스케이스가 transactional로 호출됨)→PASS(`[400, 0]`), `AcceptNotificationApplicationUseCaseTest.anAcceptanceWithoutCategoryIsRefusedRatherThanDefaulted` PASS(소유자 명시) | +| S6-#11b | 완료 | `UpdateWorkLogCommand.expectedVersion`(`OptionalLong`, `sample-portfolio/.../application/command/UpdateWorkLogCommand.java:25`), 비교는 `UpdateWorkLogUseCase` 쓰기 트랜잭션 안(`UpdateWorkLogUseCase.java:43`, 불일치 → 새 `WorkLogVersionMismatchException` → `DomainExceptionHandler`가 412 `PRECONDITION_FAILED`). 컨트롤러는 헤더만 해석(`WorkLogController.java:211`). `WorkLogControllerWireTest.patchWithIfMatchDoesNotReadTheWorkLogOutsideTheUpdate` FAIL(`NoInteractionsWanted … GetWorkLogUseCase`)→PASS, `WorkLogUseCasesTest.staleExpectedVersionIsRefusedInsideTheUpdate`·`currentExpectedVersionAppliesTheUpdate`, `patchHandsTheIfMatchVersionToTheUpdateUseCase`, `patchWithStaleIfMatchReturns412`(유스케이스 예외 경로로 변경) PASS. 동작 변화: 여러 태그를 나열한 `If-Match`(예: `W/"1", W/"2"`)는 이제 읽지 않고 412(`patchWithAListIfMatchIsRefusedAs412`) — 이 리소스는 validator 하나만 내보냄 | + +## 제거된 코드 +| 대상 | 경로 | 마지막으로 존재한 커밋 | 이유 | +|---|---|---|---| +| rate-limit client IP 모드 (`RateLimitClientIpMode`, `ClientIpResolver`, `ClientIpResolverFactory`, `ForwardedHeaderClientIpResolver`, `RemoteAddrClientIpResolver`)와 설정 `app.rate-limit.client-ip-mode` / env `APP_RATE_LIMIT_CLIENT_IP_MODE` | `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/ratelimit/` | `6d27356e` | I-5a·NEW-10c: `FORWARDED_HEADERS_TRUSTED`가 호출자가 쓰는 XFF 맨 왼쪽 값을 키로 씀. 운영 정본은 `server.forward-headers-strategy=native` + `server.tomcat.remoteip.internal-proxies`의 `getRemoteAddr()` 하나 | +| `RequestLoggingFilter`의 request/correlation/trace id 발급·MDC 기록·응답 헤더 | `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/filter/RequestLoggingFilter.java` | `6d27356e` | I-4a·I-4b: `WebMvcRequestIdFilter`로 이동(두 필터가 trace를 따로 만들던 것 제거) | +| 알림 제출 category 기본값 `"transactional"` | `src/adapter/inbound/web-notification/.../submission/NotificationSubmissionController.java` | `6d27356e` | I-6a 결정 13 | +| `WorkLogController.requireIfMatch`(트랜잭션 밖 get 후 비교) | `src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/adapter/inbound/web/controller/WorkLogController.java` | `6d27356e` | S6-#11b: 비교를 update 유스케이스 트랜잭션 안으로 | + +## 새로 발견한 결함 +- `P10-new-1` (고침, W1): `src/.env.example:25`가 `APP_SERVER_FORWARD_HEADERS_STRATEGY=framework`를 권했다. `framework`는 Spring `ForwardedHeaderFilter`가 모든 peer의 `X-Forwarded-For`를 믿어 `getRemoteAddr()` 자체를 호출자가 고르게 하므로, rate-limit 모드와 상관없이 비인증 키를 우회할 수 있었다. `native`로 바꾸고 registry allowed_values에서 `framework`를 뺐으며, rate limit이 켜진 상태에서 `framework`면 기동을 거부한다(`RateLimitWebConfig.java:38`). 다만 rate limit이 꺼진 배포에서 `framework`를 막는 런타임 가드는 없다(설정 통합은 I-5b/W3). +- `P10-new-2` (고침, W2): `WebMvcRequestIdFilter`의 traceparent 정규식은 all-zero trace id 등을 받아들였고 `RequestLoggingFilter`의 `TraceParent.parse`는 거부해서, 같은 요청에서 두 필터가 다른 trace id를 가질 수 있었다(I-4b의 한 원인). 이제 `TraceParent.parse` 하나만 쓴다. +- `P10-new-3` (고침, W1): 옛 콜백 컨트롤러의 `@RequestBody byte[]`는 form POST(`application/x-www-form-urlencoded`, query string 없음)에서 Spring 7 `ServletServerHttpRequest.getBody()`가 요청 파라미터로 다시 만든 본문을 준다(`getBodyFromServletRequestParameters`, spring-web 7.0.9 bytecode로 확인). provider(예: Twilio form 콜백)가 서명한 원래 octet과 달라질 수 있어 클래스 주석의 "exact octets" 약속과 어긋났다. I-2a 수정으로 `getInputStream()`을 직접 읽어 해소. 실서버 form POST 검증은 I-2c(W4) 범위. diff --git a/docs/reviews/2026-09-25-review-followup-results/P11.md b/docs/reviews/2026-09-25-review-followup-results/P11.md new file mode 100644 index 00000000..94b78d3d --- /dev/null +++ b/docs/reviews/2026-09-25-review-followup-results/P11.md @@ -0,0 +1,50 @@ +# P11 결과 — HTTP client (`adapter:outbound:httpclient`) + H-8·H-9(messaging) + +worktree 브랜치 `worktree-agent-afdf5842812e13046`. 커밋: D `06764fcb`, W1 `c44030e8`, W2 `52511391`. +경로 약어: `HC` = `src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient`, +`MSG` = `src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging`. + +## 행 결과 +| ID | 결과 | 근거 | +|---|---|---| +| S3-#1 | 완료 | D 커밋 `06764fcb`에서 reactive 스택(WebClient·Reactor Netty)과 webflux·reactor·reactor-netty·reactor-test·blockhound 의존 삭제. blocking(RestClient) 경로 하나만 남음. `clients[N].api` 설정 키·`ClientApiType`·`TransportType.REACTOR_NETTY` 삭제, env-fields.yaml 행 삭제, lockfile 재생성(httpclient·app-bootstrap). Jetty HTTP/3 실험 transport는 reactive SPI에 묶여 있어 blocking SPI(`JettyClientHttpRequestFactory`)로 옮김(자동 조립 안 됨은 그대로) `HC/http3/JettyHttp3TransportProvider.java:49` | +| H-5a | 해당 없음(코드 삭제) | D `06764fcb`에서 `webclient/ReactiveAttemptExecutor` 삭제. blocking은 단계 기록함: `HC/restclient/BlockingAttemptExecutor.java:233,238`(`tracker.enter(REQUEST_BODY/RESPONSE_HEADERS)`)이 classifier로 전달 | +| H-5b | 해당 없음(코드 삭제) | D `06764fcb`에서 `WebClientResponseMapper`·`ReactorFailureClassifier` 삭제. blocking은 크기 초과를 `HC/restclient/ResponseSizeLimiter.java:42,50`에서 `HttpResponseTooLargeException`으로 던지고 `BlockingAttemptExecutor.java:303`이 `RESPONSE_TOO_LARGE`로 분류 | +| H-5c | 완료 | blocking 결함(`StableBlockingExceptionMapper`)이라 W2에서 수정. `StableBlockingExceptionMapperTest.unknownTransportFailureIsNotReportedAsAConnectFailure` FAIL(`expected HttpUnknownTransportException but was HttpConnectException`)→PASS. `HC/restclient/StableBlockingExceptionMapper.java:40`, 새 타입 `HC/api/error/HttpUnknownTransportException.java`. reactive 쪽 테스트는 코드 삭제로 없음 | +| H-7b | 해당 없음(코드 삭제) | D `06764fcb`에서 `ReactiveAttemptExecutor` 삭제. blocking `categoryOf`에는 세 case 있음 `HC/restclient/BlockingAttemptExecutor.java:308-310` | +| S3-#2a | 해당 없음(코드 삭제) | D `06764fcb`에서 `webclient/ReactiveStreamingGateway` 삭제. blocking 스트리밍은 deadline·credential·admission 적용 `HC/restclient/BlockingStreamingGateway.java:69,82,106` | +| H-2 | 완료 | `DefaultDynamicTargetGatewayTest.traceHeadersStayOffTheWireWhenThePolicyDisablesPropagation` FAIL(`Expecting actual: [true, true] to contain exactly [false, false]`)→PASS, 켜진 경우 `traceHeadersAreSentWhenThePolicyEnablesPropagation` PASS. `HC/dynamic/DefaultDynamicTargetGateway.java:186` | +| H-3a | 완료 | `DefaultDynamicTargetGatewayTest.seeOtherHopSendsAGetWithoutTheOriginalBody` FAIL(`["GET", "{"name":"grace"}"]` ≠ `["GET", ""]`)→PASS. `HC/dynamic/DefaultDynamicTargetGateway.java:155` | +| H-3b | 완료 | `DefaultDynamicTargetGatewayTest.temporaryRedirectWithAOneShotBodyIsRejectedAsNotReplayable` FAIL(`Expecting actual not to be null` — 예외 없이 재전송)→PASS. hop마다 `RedirectEvaluator` 판정 `HC/dynamic/DefaultDynamicTargetGateway.java:133-150`(거부 `:147`, 메트릭 outcome=거부 코드) | +| H-3c | 완료 | `DefaultDynamicTargetGatewayTest.crossOriginHopDropsTheCallerSuppliedApiKey` FAIL(`[true, true]` ≠ `[true, false]`)→PASS. `HC/dynamic/DefaultDynamicTargetGateway.java:162`. 수정 방향대로 `SensitiveHeaderStripper` 표준 이름만 제거함 — 관례 밖 이름의 호출자 헤더는 P11-new-4 | +| H-4a | 완료 | `BlockingRedirectCoordinatorTest.crossOriginHopDropsTheProfileCredentialHeader` FAIL(`[true, true]` ≠ `[true, false]`)→PASS. `HC/restclient/BlockingAttemptExecutor.java:187`(붙인 자격증명 헤더 이름을 stripper에 추가), `HC/security/SensitiveHeaderStripper.java:61`(`alsoStripping`, `withAdditional`은 이것에 위임 — H-4b(W3) 삭제 대상은 그대로). 참고: 기동 검증이 API key + `allowCrossOrigin`을 이미 거부하므로 방어 계층 수정 | +| H-6a | 완료 | `OAuth2CredentialProviderTest.aSlowRefreshDoesNotHoldUpAnotherRegistrationThatSharesItsBin` FAIL(`java.util.concurrent.TimeoutException` — 같은 bin의 다른 registration이 느린 refresh 뒤에서 대기)→PASS. `HC/auth/OAuth2CredentialProvider.java:65-69`(`cache.get` → lock 밖 `tokenLoader.load` → `cache.put`) | +| H-6b | 완료 | `SingleFlightTokenLoaderTest.aCallerThatJoinedLaterStillGetsTheTokenAfterAnEarlierCallerTimedOut` FAIL(`ExecutionException: CancellationException`)→PASS. timeout·interrupt 분기에서 `cancel(true)` 제거 `HC/auth/SingleFlightTokenLoader.java:81`, `CancellationException`→`HttpAuthenticationException` `:113` | +| H-8 | 완료 | `PlatformIntegrationEventPublishAdapterTest.aFailureOtherThanAnIncompatibleValueIsNotTurnedIntoARefusal` FAIL(`Expecting actual not to be null` — NPE가 REJECTED_BEFORE_SEND로 바뀜)→PASS. catch를 `IllegalArgumentException`으로 좁힘 `MSG/platformbridge/PlatformIntegrationEventPublishAdapter.java:62`; 나머지 예외는 전파되어 relay가 실제 원인 타입으로 재시도·보고. 수정 방향 중 "cause를 거부 결과에 싣기"는 하지 않음: 포트가 `OutboxPublishOutcome` enum만 돌려줘 원인을 실을 자리가 없고, 실으려면 application-core 포트·relay 변경(계층 밖)이 필요. 로그로 남기는 것도 예외 메시지를 운영 로그에 쓰지 않는 규칙(`Slf4jOutboxRelayFailureReportAdapter`)과 충돌 | +| H-9 | 완료 | `KafkaSenderInterruptionTest.anInterruptedAcknowledgementWaitRethrowsWithTheInterruptFlagRestored` FAIL(`[InterruptedException, false]`)→PASS, `OutboundMessagePublisherTest.anInterruptedSendIsSwallowedWithTheInterruptFlagKept`·`OutboxMessagePublishAdapterTest$FailClosedPath.anInterruptedSendKeepsTheRelayThreadInterrupted` FAIL(`Expecting value to be true but was false`)→PASS. `src/adapter/outbound/messaging-kafka/src/main/java/dev/caskeleton/adapter/outbound/messaging/kafka/KafkaSenderAutoConfiguration.java:115`, `MSG/core/OutboundMessagePublisher.java:41`, `MSG/outbox/OutboxMessagePublishAdapter.java:100`(삼키는 지점 두 곳 모두 복원) | +| S3-#13b | 완료 | `DefaultGenericHttpGatewayTest.anExhaustedRetryBudgetIsReportedAsItsOwnFailureNotARateLimit`·`aRetryRefusedByADrainingRuntimeIsReportedAsItsOwnFailureNotARateLimit` FAIL(`expected HttpRetryBudgetExhaustedException/HttpRuntimeDrainingException but was HttpRateLimitRejectedException`)→PASS. `HC/restclient/DefaultGenericHttpGateway.java:183,281`, 새 타입 `HC/api/error/HttpRetryBudgetExhaustedException.java`·`HttpRuntimeDrainingException.java`, `docs/httpclient/operations.md` 예외 표 갱신. 두 경로는 재시도 판정과 다음 attempt 사이의 경합에서만 도달하므로 테스트는 `TestGateways.forProfile(profile, transport, eligibility)`로 판정기를 주입해 재현 | + +## 제거된 코드 +| 대상 | 경로 | 마지막으로 존재한 커밋 | 이유 | +|---|---|---|---| +| reactive gateway·SSE·streaming·runtime 패키지 (`DefaultReactiveHttpGateway`, `ReactiveHttpGateway`, `DefaultReactiveSseGateway`, `ReactiveSseGateway`, `ReactiveStreamingGateway`, `ReactiveAttemptExecutor`, `ReactiveClientRuntime`, `WebClientRuntimeFactory`, `WebClientBodyWriter`, `WebClientResponseMapper`, `BoundedDataBufferFlux`, `FirstByteDeliveryGuard`, `MultipartReplayability`, `ReactiveBodySource`, `SseIdleTimeoutException`, `SseOperation`, `SseReconnectPolicy`) | `src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/webclient/` | `6d27356e` | 결정 9: httpclient reactive 스택 삭제, blocking 경로 하나만 유지 | +| Reactor Netty transport (`ReactorNettyTransportProvider`, `ReactorHttpClientFactory`, `ReactorConnectionProviderFactory`, `ReactorFailureClassifier`, `ReactorPoolMetricsBinder`) | `.../httpclient/reactor/` | `6d27356e` | 결정 9 | +| reactive 자격증명 (`ReactiveCredentialProviderRegistry`, `ReactiveRequestCredentialProvider`) | `.../httpclient/auth/` | `6d27356e` | 결정 9 | +| reactive 재시도·resilience (`ReactiveAttemptResiliencePipeline`, `ReactiveLogicalCall`, `ReactiveRetryCoordinator`) | `.../httpclient/resilience/` | `6d27356e` | 결정 9 | +| reactive typed client (`DefaultReactiveHttpServiceRegistry`, `ReactiveHttpServiceRegistry`, `ReactiveKernelHttpExchangeAdapter`, `ReactiveOperationContext`, `ReactiveServiceInvocationHandler`), `ServiceOperationDescriptor.reactive` 플래그와 blocking/reactive 혼합 검사 | `.../httpclient/service/` | `6d27356e` | 결정 9 | +| reactive transport SPI (`ReactiveTransportProvider`, `ReactiveTransportCapabilities`), `TransportCapabilityValidator`의 reactive overload | `.../httpclient/transport/` | `6d27356e` | 결정 9 | +| 설정 키 `app.httpclient.clients[N].api`(`APP_HTTPCLIENT_CLIENTS_N_API`)와 `ClientApiType`, `TransportType.REACTOR_NETTY`, actuator `api` 항목 | `.../httpclient/profile/ClientApiType.java`, `docs/httpclient/env-fields.yaml` | `6d27356e` | 남은 값이 하나뿐인 키(동작하지 않는 옵션은 키를 두지 않음). H2 전용 프로필은 이제 모든 transport에서 `HTTP2_REQUIRED_TRANSPORT_UNSUPPORTED` | +| 기동 위반 코드 `REACTIVE_REDIRECT_UNSUPPORTED`, `REACTIVE_AUTHENTICATION_UNSUPPORTED`, `DYNAMIC_TARGET_PROFILE_API_UNSUPPORTED` | `.../profile/ClientProfileValidator.java`, `.../autoconfigure/HttpClientStartupValidator.java` | `6d27356e` | reactive 프로필이 없어 판정 대상 없음 | +| reactive bean (`httpClientReactiveTransportProviders`, `httpClientReactiveCredentialProvider`, `ReactiveAttemptExecutor`, `reactiveHttpGateway`, `ReactiveHttpServiceRegistry`, `ReactiveStreamingGateway`, `ReactiveSseGateway`) | `.../httpclient/autoconfigure/` | `6d27356e` | 결정 9 | +| reactive 테스트 (`BlockHoundEventLoopTest`, `DefaultReactiveHttpGatewayTest`, `FirstByteRetryBoundaryTest`, `ReactiveSseGatewayTest`, `ReactiveStreamingLifecycleTest`, `ReactiveRetryCoordinatorTest`, `ReactiveHttpServiceRegistryTest`, `ReactiveAuthenticationContractTest`, `BlockingReactiveSignatureSeparationTest`), 계약·protocol 테스트의 reactor case | `src/adapter/outbound/httpclient/src/test/java/...` | `6d27356e` | 대상 코드 삭제. forward proxy 경로 테스트는 blocking(Apache)으로 옮김(`ForwardProxyContractTest.gatewayRoutesTheCallThroughTheConfiguredForwardProxy`) | +| reactive testkit (`ReactiveTestGateways`, `ReactiveTransportContract`, `ReactiveEventsClient`, `MixedSignatureClient`, `NettyLeakDetectionExtension`, `EventPayload`, `MockHttpServer.enqueueSse`, `ClientProfiles.reactor`, `HttpClientContract.blockHoundSelected`) | `src/adapter/outbound/httpclient/src/testFixtures/java/...` | `6d27356e` | 대상 코드 삭제 | +| `Http2StreamSaturationTest`(Reactor Netty 전용), `ReactiveClientBenchmark` | `.../src/httpClientPerformanceTest/...`, `.../src/jmh/...` | `6d27356e` | 대상 transport 삭제 | +| `httpClientBlockHoundTest` lane, `check` 의존, 계약 lane 기본 transport의 `reactor`, `io.netty.leakDetection.level` 시스템 속성 | `src/adapter/outbound/httpclient/build.gradle` | `6d27356e` | reactor event loop이 없어 검증 대상 없음 | +| 의존 `spring-webflux`, `reactor-core`, `reactor-netty-http`, `reactor-test`, `blockhound`, testFixtures `netty-common`·`logback-classic`·`reactor-core`, 카탈로그 `blockhound` | `src/adapter/outbound/httpclient/build.gradle`, `src/gradle/libs.versions.toml` | `6d27356e` | 결정 9 | +| CI matrix `transport: reactor`, release의 `httpClientBlockHoundTest` | `.github/workflows/pr-adapters.yml`, `.github/workflows/release.yml` | `6d27356e` | 없는 lane·transport 호출 제거 | + +## 새로 발견한 결함 +- `P11-new-1` — `app.httpclient.clients[N].timeout.streaming-idle`(`APP_HTTPCLIENT_CLIENTS_N_TIMEOUT_STREAMING_IDLE`)은 바인딩만 되고 main 코드 어디서도 읽지 않음(reactive 삭제 전에도 그랬음). `HC/profile/TimeoutSettings.java:25`, `docs/httpclient/configuration-reference.md`의 `streaming-idle` 행. 동작하지 않는 옵션은 키를 두지 않는 규칙 위반. 고치지 않음. +- `P11-new-2` — `scripts/verify-httpclient-docs.py:22`가 없는 경로 `src/app-bootstrap/.../autoconfigure/httpclient/HttpClientStartupValidator.java`를 읽어 `FileNotFoundError`로 실패함. 경로를 `.../httpclient/autoconfigure`로 바꿔 돌리면 `rotation-drain-timeout`이 `docs/httpclient/configuration-reference.md`에 없다는 drift 1건이 남음(이 묶음 변경과 무관, 그 외 drift 0). 고치지 않음(scripts는 P13 범위). +- `P11-new-3` — `httpClientFailureInjectionTest`의 `FailureInjectionContractTest.disabledProxyFailsBeforeARequestCanBeSent`가 이 머신에서 실패(`expected: NOT_SENT but was: SENT_NO_RESPONSE`). Docker userland proxy(`docker-proxy` 동작 중)가 꺼진 Toxiproxy 리스너의 published 포트 연결을 받은 뒤 닫으므로 client는 실제로 요청을 보낸 것으로 관찰함. 이 묶음은 evidence 분류 코드를 바꾸지 않음(lane은 `check` 밖, Docker 필요). 테스트가 Docker 네트워크 모드에 의존함. 고치지 않음. +- `P11-new-4` — Dynamic Target cross-origin hop은 `SensitiveHeaderStripper` 표준 이름(`authorization`·`cookie`·`x-api-key`·`api-key` 등)만 제거하므로, 호출자가 `HeaderPolicy`로 넘긴 관례 밖 이름의 자격증명 헤더(예: `X-Client-Key`)는 다음 origin으로 따라감 `HC/dynamic/DefaultDynamicTargetGateway.java:162`. cross-origin hop에서 호출자 헤더를 전부 버릴지는 결정 필요 — 승인자: 저장소 소유자. diff --git a/docs/reviews/2026-09-25-review-followup-results/P12.md b/docs/reviews/2026-09-25-review-followup-results/P12.md new file mode 100644 index 00000000..934e31fd --- /dev/null +++ b/docs/reviews/2026-09-25-review-followup-results/P12.md @@ -0,0 +1,29 @@ +## 행 결과 +| ID | 결과 | 근거 | +|---|---|---| +| F-1a | 완료 | `PolicyAwareMongoQueryBuilderTest.anOperatorShapedEqualityValueIsRefused`·`anOperatorShapedLowerBoundIsRefused`·`anOperatorShapedUpperBoundIsRefused`(각 6값: `Map.of("$ne","")`, `Document("$ne",null)`, `BsonDocument("$gt")`, `JsonObject("{$regex}")`, `Pattern`, `BsonRegularExpression`), `anEqualityValueThatIsACollectionIsRefusedInFavourOfWhereIn`, `aRegexHiddenInAMembershipListIsRefused` FAIL(`AssertionError: Expecting actual not to be null`, 23건)→PASS. 공용 검사 `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/query/MongoOperator.java:96`(`requireScalar`), 호출 `query/PolicyAwareMongoQueryBuilder.java:45,52,59,71`. 수정 방향과 차이: 새 공개 타입 `MongoQueryValues`는 API surface 한도(271, `-PraiseMongoApiSurfaceCeiling` 필요)에 걸려 기존 공개 enum `MongoOperator`의 인스턴스 메서드로 둠(surface 불변). `Pattern`·`BsonRegularExpression`도 거부(값 자리 정규식이 regex 정책 우회), `whereIn` 원소에도 적용. | +| F-1b | 완료 | `MongoAtomicOperationsTemplateTest.anOperatorDocumentAsTheIdentifierIsRefused`(`AtomicFilter.id(Map.of("$gt",""))`), `anOperatorDocumentAsAnExpectedStateIsRefused`, `anOperatorDocumentPassedToTheConstructorIsRefused` FAIL(`AssertionError` at `MongoAtomicOperationsTemplateTest.java:42`)→PASS. `imperative/atomic/AtomicFilter.java:36`(compact constructor에서 `MongoOperator.EQ::requireScalar`). 패키지 edge `imperative -> query`를 `MongoModuleBoundaryTest` matrix에 추가(DAG 유지). | +| F-5a | 완료 | `MongoCsfleClientFactoryTest.theSchemaIsKeyedByTheCollectionNamespace` — 재현 FAIL(`Expecting all elements of ["customers"] to match`)→PASS. `MongoCsfleProfile`에 `database` component 추가, `namespace()` = `database.collection`(`advanced/encryption/csfle/MongoCsfleProfile.java:23,67`), `MongoCsfleClientFactory.java:76`. | +| F-5b | 완료 | `MongoCsfleClientFactoryTest.theSchemaIsGeneratedFromTheFieldPolicies`(중첩 경로 `contact.email` → 중첩 `properties`, Random/Deterministic 알고리즘, keyId UUID) 재현 FAIL(`Expecting actual "{}" to contain "ssn"`)→PASS, `anAliasWithoutADataKeyIdIsRefused`, `aFieldInsideAnEncryptedParentIsRefused`. `encryptedFieldsMapJson` 인자 제거, 대신 `Map dataKeyIds`(alias→data key id: 자동 암호화 schema는 alias가 아니라 key id를 받으므로 호출자가 key vault에서 해석) — `MongoCsfleClientFactory.java:55,91`. Deterministic 필드는 `bsonType: string` 고정(`ponytail:` 주석, 비문자열 equality 필드가 생기면 정책에 타입 추가). | +| F-5c | 완료 | `MongoCsfleClientFactoryTest.theKeyVaultConnectsWithItsOwnCredential` 재현 FAIL(`Expecting actual not to be null` — `getKeyVaultMongoClientSettings()`)→PASS. 생성자가 `MongoCredentialResolver`를 받아 `profile.keyVaultCredential()`로 key vault `MongoClientSettings`를 만든다(`MongoCsfleClientFactory.java:40,64-73`). 실제 암호화 lane은 불가: 자동 암호화는 `mongocryptd` 또는 `crypt_shared`(MongoDB Enterprise 배포물)가 필요하고 lane이 쓰는 community `mongo:8.0` 이미지에는 없다. driver 쪽 `org.mongodb:mongodb-crypt`도 이 leaf 의존성에 없다(새 의존성·네트워크 다운로드 필요). 그래서 driver에 넘기는 `AutoEncryptionSettings`를 설정 단위 테스트로 검증함. F-5d(W4, 단위 테스트 추가)도 이 테스트로 사실상 충족. | +| X2-P1-1b | 완료 | `MongoProfileClientSettingsAutoConfigurationTest.aTypedProfileResolvesItsUriThroughTheApplicationSecretSource` FAIL(`IllegalStateException: MongoDB typed profiles are configured but no MongoCredentialResolver bean is available`)→PASS, `aSecretSourceWithoutTheReferencedKeyFailsClosed`. `src/config/architecture/modules.json:81-86`(`adapter-outbound-persistence-mongo` → `application-core`), `src/adapter/outbound/persistence-mongo/build.gradle:32`(`implementation project(':application-core')`), bridge bean `client/MongoProfileClientSettingsAutoConfiguration.java:57`(`@ConditionalOnBean(SecretSourcePort)`·`@ConditionalOnMissingBean(MongoCredentialResolver)`, `MongoCredentialResolver.fromSecretSource(secretSource::resolve)`), `security/MongoCredentialResolver.java:42`(key = `secret:///`의 ``, Redis·httpclient와 같은 규칙). `MongoRegistryPermissionParityTest`(app-bootstrap) PASS. 이유는 W1 커밋 메시지에 적음. | +| F-2a | 완료 | `MongoStartupValidatorTest.anInactiveProfileWithAnotherTopologyDoesNotFailStartup`(primary=REPLICA_SET 활성, local=STANDALONE) FAIL(`MongoOperationRejectedException: profile 'local' declares topology STANDALONE but is connected to REPLICA_SET`)→PASS, `MongoPlatformPropertiesTest.aProfileSetWhoseActiveNameMatchesNoneOfItsProfilesIsRefused`. `activeProfile`을 `MongoPlatformSettings` 첫 component로 한 번 바인딩(`autoconfigure/MongoPlatformSettings.java:34,74,83`), validator는 활성 profile만 비교(`autoconfigure/MongoStartupValidator.java:67`), customizer의 raw `getProperty` 제거(`client/MongoProfileClientSettingsAutoConfiguration.java:63,90`). 설정 키가 `ca-skeleton.persistence-mongo.active-profile` → `ca-skeleton.persistence-mongo.platform.active-profile`로 이동(`src/main/resources/config/mongo.yml:14`, EPP `MongoDefaultsEnvironmentPostProcessor.java:47`). env 키 `APP_PERSISTENCE_MONGO_ACTIVE_PROFILE`는 그대로라 `env-keys.yaml`·`.env.example` 변경 없음. | +| F-2b | 완료 | `MongoStartupValidatorTest.anInactiveProfileWithAnotherTopologyDoesNotMakeTheInstanceUnready` FAIL(`Expecting value to be true but was false`)→PASS. `autoconfigure/MongoPlatformHealthIndicator.java:89`(활성 profile 하나만 비교), health detail에 `activeProfile` 추가(`:83`). | +| F-4a | 완료 | 실제 Mongo lane `MongoBulkMappingLaneTest.aBulkUpdateWritesTheFieldUnderItsMappedName`(`mongoReplicaSetTest`) FAIL(`expected {_id=o-1, st=PAID} but was {_id=o-1, st=NEW, status=PAID}`)→PASS. `MongoBulkExecutor.execute(context, documentType, plan)`로 시그니처 변경, `QueryMapper`/`UpdateMapper`로 entity 매핑(`imperative/bulk/MongoBulkExecutor.java:68,130`). `bulkOps(...)`는 CSOT `withTimeout`을 잃어서 쓰지 않음. | +| F-4b | 완료 | 실제 Mongo lane `MongoBulkMappingLaneTest.aBulkUpdateCarriesValuesThatNeedAConverter`(`DomainDocumentId` id + `BigInteger` 값, `findById`로 왕복) FAIL(`CodecConfigurationException: Can't find a codec for ... DomainDocumentId`)→PASS. 크기 한도를 plan 생성자에서 executor로 옮겨 매핑된 문서를 collection codec으로 `RawBsonDocument` 인코딩한 실제 byte로 판정(`MongoBulkExecutor.java:150`), `MongoBulkWritePlan.estimatedEncodedBytes` 삭제. 한도 회귀 테스트는 `MongoBulkOutcomeTest.aPlanOverTheByteCeilingIsRefused`(hermetic, `mappedWrites` 직접 호출)로 이동. | +| F-8 | 완료 | 실제 Mongo lane `MongoMigrationLaneTest.aLeaseWriteThatFailsForAnotherReasonIsRaisedRatherThanReportedAsALostRace`(validator로 insert를 121 실패시킴) FAIL(`Expecting actual not to be null`)→PASS. `migration/MongoCollectionMigrationLock.java:116`. 수정 방향(`code == 11000`)보다 조금 넓게 `ErrorCategory.DUPLICATE_KEY`(11000·11001·12582, driver 정의)로 판정 — 같은 패키지 `MongoCollectionMigrationLedger.java:160`과 같은 기준. | + +커밋: W1 `ceddd6d1`(F-1a·F-1b·F-5a·F-5b·F-5c·X2-P1-1b), W2 `3dc06bba`(F-2a·F-2b·F-4a·F-4b·F-8). D 커밋 없음(결정된 삭제 대상 없음). + +검증(최종 상태 `3dc06bba`): `:adapter:outbound:persistence-mongo:check` 통과(test 80, mongoStableContractTest 464, 실패·skip 0), `verifyMongoApiSurface` 통과(271 유지), 실제 Mongo lane `mongoReplicaSetTest` 6·`mongoMigrationTest` 9·`mongoSecurityIntegrationTest` 10·`mongoCompatibilityTest` 2·`mongoFailoverTest` 6·`mongoPerformanceTest` 3 전부 통과, `architectureCheck`·`verifyDependencyLocks` 통과, `:app-bootstrap:verifyEnvKeys` OK, `:app-bootstrap:test --tests '*MongoRegistryPermissionParityTest'` 2건 통과(W1 시점). lockfile 변경 없음(application-core는 외부 의존성 없음). + +## 제거된 코드 +| 대상 | 경로 | 마지막으로 존재한 커밋 | 이유 | +|---|---|---|---| +| `MongoBulkWritePlan.estimatedEncodedBytes` (plan 생성 시 `toJson()` 크기 추정) | `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/imperative/bulk/MongoBulkWritePlan.java` | `6d27356e` | 매핑 전 값에 codec이 없어 실패(F-4b). 매핑된 문서의 실제 BSON 크기 검사(`MongoBulkExecutor.mappedWrites`)로 대체 | +| `MongoCsfleClientFactory.settingsFor`의 `encryptedFieldsMapJson` 인자 | `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/advanced/encryption/csfle/MongoCsfleClientFactory.java` | `6d27356e` | 호출자 JSON을 schema로 쓰던 경로(F-5b). `profile.fields()`에서 생성 | +| 설정 키 `ca-skeleton.persistence-mongo.active-profile` | `src/adapter/outbound/persistence-mongo/src/main/resources/config/mongo.yml` | `6d27356e` | `ca-skeleton.persistence-mongo.platform.active-profile`로 이동(F-2a, `MongoPlatformSettings`에 한 번 바인딩). env 키는 그대로 | + +## 새로 발견한 결함 +- `P12-new-1` (미수정, 코드 읽기로만 확인): bulk 경로가 `access.rawOperations().getCollection(...)`의 raw collection에 `bulkWrite`를 해서, `MongoConsistencyBinder`가 profile별 template에 `setWriteConcern`으로 건 write concern이 적용되지 않는다(Spring `MongoTemplate.getCollection`은 template write concern을 붙이지 않음). 위치 `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/imperative/bulk/MongoBulkExecutor.java:91`, write concern 설정 `imperative/MongoConsistencyBinder.java:78`. 고치려면 `ScopedAccess`가 profile write concern을 노출하고 bulk가 `withWriteConcern`을 붙여야 함(`MongoTemplate`에 public getter 없음). +- `F-1c`(W5, Javadoc "compile-time impossibility")는 F-1a를 고치면서 같은 파일 Javadoc을 "런타임 스칼라 검사"로 바꿔 사실상 해결(`query/PolicyAwareMongoQueryBuilder.java:16-20`). 현황표 갱신 때 참고. diff --git a/docs/reviews/2026-09-25-review-followup-results/P13.md b/docs/reviews/2026-09-25-review-followup-results/P13.md new file mode 100644 index 00000000..ee47be3e --- /dev/null +++ b/docs/reviews/2026-09-25-review-followup-results/P13.md @@ -0,0 +1,19 @@ +## 행 결과 +| ID | 결과 | 근거 | +|---|---|---| +| O-5b | 완료 | W1 `50cb2d9e`. `src/build-logic/build.gradle:9-12`, `src/build-tools/build.gradle:10-13`에 `dependencyLocking { lockAllConfigurations(); lockMode = STRICT }`. lockfile 커밋: `src/build-logic/gradle.lockfile`, `src/build-tools/gradle.lockfile`(+ `--write-locks`가 만든 `settings-gradle.lockfile` 2개, main build와 같은 형태). 재생성: `./gradlew -p build-logic dependencies --write-locks`(build-tools도 같음). 재현(FAIL): lockfile의 `spotless-plugin-gradle:8.6.0`을 `8.5.0`으로 바꾸고 `./gradlew -p build-logic compileJava` → `:compileJava FAILED ... Dependency version enforced by Dependency Locking`. 복원 후 `-p build-logic test` 80/80, `-p build-tools test` 35/35 통과. 범위 한계는 P13-new-1 참고. | +| O-3a | 완료 | `VerifyNoIgnoredSourcePackagesFunctionalTest.sourceInAnIgnoredPackageOfAnAuxiliarySourceSetFailsTheGate` FAIL(`UnexpectedBuildSuccess` — integrationTest source set 미검사)→PASS, `...sourceInAnIgnoredPackageOfTheSamplePortfolioFailsTheGate` FAIL(`found no Java sources at all; the gate would pass vacuously.` — sample 제외)→PASS. 수정: `src/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/ArchitecturePlugin.java:196-215` — 모든 project의 모든 `SourceSet.java.srcDirs`를 모으고 build 디렉터리 아래(생성 코드)만 뺀다. sample도 포함. 실제 저장소: main build 4784개 Java 소스 검사(이전 main/test·sample 제외 약 4117개), optional-platforms 341개, 둘 다 OK. | +| O-3b | 완료 | `VerifyNoIgnoredSourcePackagesFunctionalTest.gitFailingInsideACheckoutFailsTheGateInsteadOfPassing` FAIL(`UnexpectedBuildSuccess` — 깨진 `.git`에서 git exit 128인데 통과)→PASS. 수정: `VerifyNoIgnoredSourcePackagesTask.java:70,102-150` — checkout 여부를 git 출력이 아니라 상위 디렉터리의 `.git` 존재로 판단(`checkoutRoot`), checkout 안에서 `git check-ignore`가 실행 불가(`IOException`)거나 exit가 0/1이 아니면 `GradleException`. `.git`이 없는 소스 묶음만 기존처럼 이름 규칙만 적용. `rev-parse` 호출과 `GitCommandResult` 삭제. | +| O-3c | 완료 | `src/optional-platforms/build.gradle:38-40` — `ci`가 `verifyCleanArchitectureDependencies` 대신 `architectureCheck`(방향 + purity + `verifyNoIgnoredSourcePackages`)에 의존. 재현: `./gradlew -p optional-platforms ci --dry-run`에서 `verifyNoIgnoredSourcePackages` 0회 → 수정 후 포함. `./gradlew -p optional-platforms ci` BUILD SUCCESSFUL, `verifyNoIgnoredSourcePackages: OK — 341 Java sources`. | +| NEW-1a | 완료 | 방식: Spring Boot `management.info.env.enabled=true`(`src/app-bootstrap/src/main/resources/config/observability.yml:86-94`, `info.*` 트리만 노출, env 전체 아님)와, 각 capability 모듈이 자기 설정 파일에 `info.capabilities..enabled: ${<스위치 키>:}`을 싣는다. JPA는 `vendor: ${ca-skeleton.persistence.vendor:postgresql}`도 싣는다(vendor=postgresql이면 `JpaDataSourceProfileValidator`가 실제 DB가 PostgreSQL인지 기동 때 확인하므로 선택자=실제 DB). Java 코드 추가 없음, capability 모듈 8개의 yml만 추가: `persistence-jpa.yml`, `persistence-mongo/config/mongo.yml`, `messaging-kafka/.../messaging.yml`, `notification-platform/.../notification.yml`, `graphql/config/graphql.yml`, `cache-redis.yml`, `fileserver-platform/.../fileserver.yml`, `httpclient.yml`. 계약 재정의: `expectedSwitchesOn`(property 키) → `expectedCapabilitiesOn`(info 이름), 최상위 `capabilities` 카탈로그(8개) 추가, `$activationComment`/`$vendorComment` 갱신(`src/config/runtime/compose-profile-contracts.json:741-752`). smoke: `scripts/run-compose-runtime-smoke.sh:434-468` — health 응답 뒤 `/actuator/info`를 받아 ①보고된 capability 이름 집합 = 카탈로그(모듈 누락·info 꺼짐 검출, all-off lane이 빈 목록끼리 비교하는 헛검사가 안 되게) ②enabled=true 집합 = `expectedCapabilitiesOn` ③JPA가 켜졌으면 `vendor`, 아니면 `none` = `expectedPersistenceVendor`. 정적 검사 `scripts/verify-compose-profile-contracts.sh:133-146`(check 6): 카탈로그 밖 이름, JPA 켜짐/꺼짐과 맞지 않는 vendor를 거부. 실제 실행(Docker, qualification 이미지): 재현 — off-local이 persistence-jpa를 기대하도록 바꾼 계약에서 HEAD의 smoke는 `all 1 blocking lanes passed`(결함), 새 smoke는 `off-local: the application reports [] on, the contract expects [persistence-jpa]`로 FAIL. 실제 계약: `--lane off-local` passed(8개 모두 `enabled:"false"`), `--lane local-jpa` passed(`persistence-jpa {enabled:"true",vendor:"postgresql"}`), `--lane off-prod` passed. `--lane local-redis`는 info 검사(`redis enabled:"true"`)를 통과한 뒤 기존 3c 기동 로그 검사에서 실패(P13-new-2). 정적 검사: 실제 계약 18 lane 전부 match, 깨진 사본(카탈로그 밖 이름·JPA 켜짐+vendor none)은 두 lane FAIL. 한계: objectstorage·websocket·gRPC는 모든 lane에서 꺼지고 info에 보고하지 않는다(예전 activation endpoint도 보고하지 않던 셋). `ConfigurationNamespaceContractTest`의 허용 root에 프레임워크 namespace `info` 추가(`app-bootstrap/src/test/.../ConfigurationNamespaceContractTest.java:57-74`). | + +## 제거된 코드 +| 대상 | 경로 | 마지막으로 존재한 커밋 | 이유 | +|---|---|---|---| +| `GitCommandResult` record | `src/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/GitCommandResult.java` | `6d27356e` | O-3b에서 git 호출이 exit code를 직접 판정하는 `checkIgnore` 하나로 줄어 쓰는 곳이 없음 | +| `git rev-parse --show-toplevel` 호출(checkout 판정) | `VerifyNoIgnoredSourcePackagesTask.java` | `6d27356e` | 실패하면 "checkout 아님"으로 읽혀 게이트가 통과하던 원인. `.git` 존재 판정으로 대체 | +| compose 계약 필드 `expectedSwitchesOn` | `src/config/runtime/compose-profile-contracts.json` | `6d27356e` | 읽는 코드가 없던 필드. `expectedCapabilitiesOn`(info 이름)으로 재정의 | + +## 새로 발견한 결함 +- **P13-new-1** (미수정, O-5b의 남은 범위): included build lock은 build-logic·build-tools 자신의 configuration(compile/test)만 잠근다. main build가 plugin을 쓸 때의 settings·root buildscript classpath는 main build에서 따로 해석되고 잠기지 않는다. 증거: `./gradlew buildEnvironment`에서 `project :build-tools`의 `jackson-databind:3.0.2 -> 3.1.5`(lockfile은 3.0.2). 고치려면 `src/settings.gradle`·`src/build.gradle`·`src/optional-platforms/*`에 `buildscript { dependencyLocking { lockAllConfigurations() } }`와 `buildscript-gradle.lockfile`/`settings-gradle.lockfile` 재생성이 필요하고, Spring Boot plugin 버전을 올릴 때마다 main build 설정 단계가 lock 재생성을 요구하게 된다(소유자 판단 필요). +- **P13-new-2** (미수정, Redis/P6 영역·NEW-1b에서 드러날 항목): `local-redis` lane은 기동 로그 무음 검사(스크립트 3c)를 통과할 수 없다. lane 자신이 주는 `APP_REDIS_AUTHENTICATION_ANONYMOUS_ACCESS_ACCEPTED=true`와 advanced credential 미설정 때문에 `RedisSdkAutoConfiguration`이 기동 중 WARN 2줄(`Redis is running without credentials ...`, `no advanced credential reference is configured ...`)을 찍는다. 증거: `lane-local-redis` 로그 `local-redis: the startup log is not silent`. capability·info 검사는 통과했다. diff --git a/docs/reviews/2026-09-25-review-followup-results/P2.md b/docs/reviews/2026-09-25-review-followup-results/P2.md new file mode 100644 index 00000000..b3c035fb --- /dev/null +++ b/docs/reviews/2026-09-25-review-followup-results/P2.md @@ -0,0 +1,56 @@ +## 행 결과 +| ID | 결과 | 근거 | +|---|---|---| +| D-7a | 완료 | D 커밋 `2c7b3d25`(+ 문서 후속 `f8bf7b6d`). `direct/`·`multipart/` 패키지, S3 direct·multipart·presigner·operation resolver, `ObjectOperationResolutionService`·`ObjectOperationEpochRecord`, `Direct*Port` 3개와 그 요청·응답 타입 삭제(main −5,017줄, test −2,221줄). 삭제 전후 `git grep`으로 main 참조 0 확인(남은 언급은 `docs/reviews`·`docs/superpowers`·`docs/evidence`의 과거 기록뿐). 함께 정리: `SelectedObjectStorageProviderFactory`의 `Object` 슬롯 3개·생성자 3개(`config/SelectedObjectStorageProviderFactory.java`), S3 contribution의 presigner/direct/multipart 조립(`s3/S3ObjectStorageProviderContribution.java`), direct/multipart 전용 control record 5종과 codec 분기, `ObjectControlKeyCodec`·`ObjectHandleCodec` 메서드, 상태 enum. `DIRECT_UPLOAD`/`DIRECT_MULTIPART` capability 값은 제거해서, 설정에 남아 있으면 조용히 무시되지 않고 바인딩에서 실패한다. 남은 6개 control record family의 골든 digest는 삭제 전과 같다(`ObjectControlRecordCodecTest.everyRecordFamilyHasAFrozenGoldenEnvelopeDigest` PASS) — 유지되는 레코드의 저장 형식은 바뀌지 않았다. AWS lane `requires`에서 `AwsS3DirectMutationPreconditionsTest` 제거(`src/adapter/outbound/objectstorage/build.gradle:89`), workflow 입력 `run_protected_aws_direct_mutation` 제거(`.github/workflows/object-storage-qualification.yml`) | +| D-7b | 완료 | `2c7b3d25`. `RoutingObjectDirectGrantAdapter`, 빈 `ObjectStorageMaintenanceCapabilityConfig` 삭제, `ObjectStorageAutoConfiguration.java:21-25` import 목록에서 제거 | +| D-7c | 완료 | `2c7b3d25`. `ObjectPurgeMaintenancePort`와 전용 `ObjectPurgeRequest` 삭제, `ObjectStoragePortContractTest`의 purge 단언을 `scannerAndStagedPublicationAreSeparatePrivilegeSurfaces`로 정리 | +| D-1a | 완료 | `StagedObjectPublicationLifecycleTest$Abort.abortIsRejectedWhenTheOperationPublishedAfterAuthorization` FAIL(`Expecting message to be: "published operation cannot be aborted"` — 수정 전엔 데이터를 지운 뒤 terminate에서 다른 예외)→PASS, `…$Abort.rejectedAbortAfterPublicationKeepsThePublishedBytesReadable` FAIL(`ObjectStorageProviderException: local object is absent`)→PASS. `kernel/StagedObjectPublicationKernel.java:299-331`. 수정 방향과 다른 점: 새 상태 `ABORT_IN_PROGRESS`를 만들지 않고 `ABORTED` 자체를 retire 전에 CAS로 기록한다(영속 enum 추가 없음). 같은 fence 역할을 하고, 재시도는 D-2c 경로가 retire를 다시 시도해 crash 창을 메운다 | +| D-1b | 완료 | `…$AuthorizeAbort.authorizeAbortIsRejectedOnceTheReferenceIsPublished` FAIL(`Expecting actual not to be null`)→PASS. `kernel/ObjectPublicationHandoffService.java:101-123` | +| D-1c | 완료 | `…$FinalizePublication.finalizeAfterAbortWasAuthorizedIsRejected` FAIL(`Expecting actual not to be null`)→PASS. `ObjectFinalizeRequest`에 `handoffFence`·`claimant` 추가(`application-objectstorage/.../request/ObjectFinalizeRequest.java:15-32`), finalize가 활성·일치 lease 요구(`StagedObjectPublicationKernel.java:247-254`, `control/ObjectPublicationHandoffRecord.java:176` `heldBy`). 이미 PUBLISHED인 replay는 lease를 보지 않는다(release 뒤 reconcile 재호출이 계속 REPLAYED). sample 호출부 `sample-portfolio/.../poster/ReconcilePosterImageUploadUseCase.java:106-114` | +| D-6a | 완료 | `FilesystemObjectStorageAdapterTest.getRejectsAStoredObjectLargerThanTheReadCeiling` FAIL(`Expecting actual not to be null`)→PASS, `…putRejectsContentLargerThanTheReadCeiling` FAIL→PASS. `FilesystemObjectStorageAdapter.java:33,57,81`. 수정 방향과 다른 점: "설정 최대값" 대신 고정 상한 16 MiB 상수(`ponytail:` 주석). legacy seam(`@Deprecated(forRemoval=true)`)에는 크기 설정 키가 없고, 삭제 예정 seam에 새 설정 키·env 문서를 늘리지 않으려고 상수로 했다. put도 같은 상한으로 막아 "쓴 것은 항상 다시 읽힌다"를 유지 | +| D-6b | 완료 | `FilesystemObjectStorageAdapterTest.putReturnsALogicalLocationThatHidesTheServerPath` FAIL(`expected: objectstorage:posters/7/image but was: file:///tmp/junit-…/posters/7/image`)→PASS. `FilesystemObjectStorageAdapter.java:71`(`logicalLocation`). 결함을 굳히던 특성 테스트는 `LegacyObjectStorageBehaviorTest.filesystemReceiptNamesTheKeyInsteadOfTheServerPath`로 바꿈 | +| X2-P1-1a | 완료 | `S3ProviderCompositionTest.capabilityConfigResolvesS3CredentialsThroughTheSecretSourcePort` FAIL(`IllegalArgumentException: S3 provider binding is invalid: credential environment references did not resolve completely`)→PASS. `s3/S3ObjectStorageProviderContribution.java:33`(공개 생성자가 `SecretSourcePort`를 받고 `System::getenv` 제거), `config/ObjectStorageCapabilityConfig.java:47-51`(`ObjectProvider`를 자격 증명을 실제로 풀 때 조회 — secret backend 없는 local-only 조립도 기동됨). 새 설정·env 키 없음 | +| D-2a | 완료 | `…$ReleaseClaim.repeatedReleaseByTheSameClaimantReplays` FAIL(`IllegalStateException: publication handoff owner/fence is stale`)→PASS. `ObjectPublicationHandoffRecord.java:121-126`, `ObjectPublicationHandoffService.java:97,125-137`(바뀐 게 없으면 쓰지 않고 REPLAYED) | +| D-2b | 완료 | `…$AuthorizeAbort.repeatedAuthorizeAbortForTheSameFenceReplays` FAIL(`IllegalStateException: active or stale handoff cannot authorize abort`)→PASS. `ObjectPublicationHandoffRecord.java:142-147` | +| D-2c | 완료 | `…$Abort.repeatedAbortReplays` FAIL(`IllegalStateException: publication terminal transition is invalid`)→PASS. `StagedObjectPublicationKernel.java:317-323`. 수정 방향과 다른 점: provider 호출 전에 바로 REPLAYED를 주지 않고 retire를 한 번 더 시도한 뒤(이미 없으면 정상) REPLAYED — D-1a에서 ABORTED를 retire보다 먼저 기록하므로, 그 사이 crash가 바이트를 고아로 남기지 않게 하려는 것 | +| D-3a | 완료 | `…$Stage.stageRetriedAfterACrashBeforeTheStageRecordStagesTheObject` FAIL(`IllegalStateException: stage operation is not uploadable`)→PASS. `StagedObjectPublicationKernel.java:84-127`(DATA_UPLOADED면 저장된 객체를 inspect해서 stage 기록을 다시 만들고, 동시 재시도 충돌은 REPLAYED) | +| D-3b | 완료 | `…$FinalizePublication.finalizeSucceedsWhenVerifyWasRetriedAfterACrashBeforeTheOperationAdvanced` FAIL(`IllegalStateException: staged operation is not finalizable`)→PASS. `StagedObjectPublicationKernel.java:192-229`(REPLAYED 경로도 operation을 INTEGRITY_VERIFIED/SCAN_PENDING까지 전진) | +| D-3c | 완료 | `…$FinalizePublication.finalizeRetriedAfterACrashInReferencePublicationPublishes` FAIL(`staged operation is not finalizable`)→PASS. `StagedObjectPublicationKernel.java:262-285` | +| D-3d | 완료 | `…$FinalizePublication.finalizeSucceedsWhenTheCleanVerdictWasRetriedAfterACrash` FAIL(`staged operation is not finalizable`)→PASS. `config/RoutingObjectScanMaintenanceAdapter.java:92-115` | +| D-5 / X1-#8b | 완료 | `LocalDevObjectStorageRecoveryTest.aConcurrentReaderNeverSeesAPartiallyCreatedControlRecord` FAIL(`Expecting empty but was: [ObjectControlCorruptionException: control record is corrupt …]`)→PASS. `filesystem/LocalDevObjectControlStore.java:51-78`(temp 파일에 다 쓰고 `force` 후 `Files.createLink`). 동시성 재현이라 수정 전 FAIL은 확률적이다(300회 create/read 중 부분 파일 읽기 발생). 수정 뒤에는 부분 파일이 구조상 보이지 않는다 | +| D-9 | 완료 | `…$Inspect.scanGatedReferenceReportsItsCleanVerdict` FAIL(`Expecting actual: Optional[NOT_REQUIRED]`)→PASS. `config/RoutingObjectReadAdapter.java:53-58`. 이 보고가 참이 되려면 managed publish의 scan 우회를 막아야 해서 P2-new-1을 함께 고쳤다 | +| D-10 | 완료 | `ObjectStorageCapabilityAssemblerTest.closeReleasesProvidersInReverseCreationOrderAndKeepsEveryFailure` FAIL(`Expecting message to be: "close failed: a"`)→PASS. `config/ObjectStorageCapabilityAssembler.java:52-82,137-140`(provider를 생성 순서 `List`로 보관, 역순 close, 첫 실패에 나머지 `addSuppressed`; assemble 실패 경로도 같은 helper) | +| NEW-6 | 완료 | 결정적 FAIL 재현은 못 했다(부하 의존 간헐 실패, 실패 로그 없음). 원인인 벽시계 예산을 없앴다: 예산 `CallBudget.fromNow(365일)`, `get` 타임아웃은 1분 hang guard로만, bridge마다 새 `ReadOperation`, truncated/oversized 두 테스트로 분리. `adapter/outbound/objectstorage/src/test/.../s3/S3AsyncResponseBodyBridgeTest.java` 3/3 PASS | + +다른 묶음·Wave 행에 미친 영향(이 묶음 ID 아님, 오케스트레이터 참고): +- S4-#12(W3): `SelectedObjectStorageProviderFactory`의 `Object` 슬롯·`Class.cast` 제거됨. 남은 건 provider·controlStore·close 3개 필드뿐이라 `record ProviderInstance` 전환은 선택 사항. +- S1-#17a(W3): `DirectTransferSessionId`·`PartReceiptToken`(과 `MultipartPartNumber`) 삭제로 식별자 클래스가 줄었다. +- S4-#11b(W3): 빈 `RoutingObjectDirectGrantAdapter` 삭제분은 끝남. +- TEST-FAKE-ObjectControlStore(W4): `ManagedMultipartCoordinatorTest`·`ObjectMutationResponseLossTest`·`ObjectOperationEpochTest` 등 삭제로 fake 수가 줄었다. 새 `StagedObjectPublicationLifecycleTest`의 `CrashingControlStore`는 장애 주입용 wrapper다(실제 local store 위임). +- P13 영역 파일 `.github/workflows/object-storage-qualification.yml`을 고쳤다(삭제된 direct mutation 입력·env 제거). 통합 시 충돌 가능. + +## 제거된 코드 +| 대상 | 경로 | 마지막으로 존재한 커밋 | 이유 | +|---|---|---|---| +| direct 전송·direct multipart 조정자와 보조 타입 14개(`DirectTransferCoordinator`, `DirectMultipartCoordinator`, `DirectGrantProvider`, `DirectMultipartProvider`, `DirectGrantReplayCache`, `DirectMultipartGrantLedger`, `DirectMultipartCompletionVerifier`, `DirectPartAcknowledgementVerifier`, `DirectPublishedObjectResolver`, `DirectTransferPolicy`, `DirectTransferCorsPolicy`, `DirectTransferSessionRecord`, `DirectGrantGeneration`, `PresignedGrantRedactor`) | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/direct/` | `6d27356e` | main 호출자 0, 조립 경로 없음(소유자 결정 D1·D-7a) | +| managed multipart 5개(`ManagedMultipartCoordinator`, `MultipartOperationResolver`, `MultipartPartLedger`, `MultipartUploadPlan`, `MultipartCompletionEvidence`) | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/multipart/` | `6d27356e` | main 호출자 0 | +| S3 direct·multipart·presigner·operation resolver 6개(`S3DirectTransferProvider`, `S3DirectMultipartProvider`, `S3ManagedMultipartProvider`, `S3DirectCompletionVerifier`, `S3PresignerFactory`, `S3ObjectOperationResolver`) | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/s3/` | `6d27356e` | 위 조정자만 쓰던 provider. contribution이 만들기만 하고 아무도 꺼내 쓰지 않았다 | +| operation 해결·epoch 커널 5개(`ObjectOperationResolutionService`, `ObjectOperationEpochRecord`, `ObjectOperationEpochState`, `DirectGrantSessionState`, `MultipartUploadState`)와 `ObjectOperationStateMachine.advanceDirectGrant/advanceMultipart`, `PendingObjectEffect.Kind`의 DIRECT_*·MULTIPART_* 값, `ObjectRequestFingerprintCodec.OperationKind`의 DIRECT_*·MULTIPART_* 값 | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/kernel/`, `.../codec/ObjectRequestFingerprintCodec.java` | `6d27356e` | 삭제된 조정자 전용. fingerprint 정규 바이트 형식(`direct-parameter` 줄 포함)은 기존 기록 호환을 위해 유지 | +| direct/multipart control record 5종(`ObjectDirectSessionRecord`, `ObjectDirectMultipartSessionRecord`, `ObjectDirectMultipartGrantRecord`, `ObjectMultipartSessionRecord`, `ObjectMultipartPartRecord`)과 codec 분기·`Family` 값, `ObjectControlKeyCodec.{multipart,directSession,multipartPart,directMultipartGrant,operationEpoch}`, `ObjectHandleCodec.{directUpload,multipart,partReceipt}` | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/control/`, `.../codec/` | `6d27356e` | 삭제된 조정자만 쓰던 영속 레코드. 이 family를 쓴 조립 경로가 없어 저장된 레코드도 없다 | +| capability 값 `DIRECT_UPLOAD`·`DIRECT_MULTIPART` | `ObjectStorageProvider.Capability`, `application-objectstorage/.../model/ObjectCapabilityRequirement.java` | `6d27356e` | 구현이 사라진 뒤에도 설정하면 조용히 무시되는 옵션이 된다(capability 규칙 3) | +| `SelectedObjectStorageProviderFactory`의 `managedMultipart/directTransfer/directMultipart` 슬롯·getter·생성자 3개 | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/config/SelectedObjectStorageProviderFactory.java` | `6d27356e` | 테스트만 호출(`S3ProviderCompositionTest`) | +| `S3ClientPolicy.{requireSdkCompatibleMpuObjectSize,requirePartCount,requirePartSize}`, `MINIMUM_NON_FINAL_PART_BYTES` | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/s3/S3ClientPolicy.java` | `6d27356e` | multipart provider 전용 | +| 포트 `DirectObjectUploadPort`·`DirectObjectDownloadGrantPort`·`DirectMultipartUploadPort` | `src/application-objectstorage/src/main/java/dev/caskeleton/application/objectstorage/port/` | `6d27356e` | 구현·소비자 0 | +| direct/multipart 요청·응답 타입 15개(`Direct{Upload,Download}Grant`, `DirectUploadCompletion{Request,Receipt}`, `Direct{Upload,Download}GrantRequest`, `Multipart{Start,Complete,Abort}Request`, `MultipartPartAcknowledgement`, `MultipartReceipt`, `MultipartSession`, `PartUploadGrant{,Request}`)과 `ObjectModelSupport.{immutableHeaders,requireExpiry}` | `src/application-objectstorage/src/main/java/dev/caskeleton/application/objectstorage/{model,request}/` | `6d27356e` | 삭제된 포트 전용 | +| 식별자 `DirectTransferSessionId`·`MultipartPartNumber`·`PartReceiptToken`, `ObjectIdentitySupport.requirePartReceipt` | `src/application-objectstorage/src/main/java/dev/caskeleton/application/objectstorage/identity/` | `6d27356e` | 삭제된 포트·레코드 전용 | +| `RoutingObjectDirectGrantAdapter` | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/config/RoutingObjectDirectGrantAdapter.java` | `6d27356e` | private 생성자만 있는 빈 클래스, 참조 0 (D-7b) | +| `ObjectStorageMaintenanceCapabilityConfig` | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/config/ObjectStorageMaintenanceCapabilityConfig.java` | `6d27356e` | 빈 `@Configuration` (D-7b) | +| `ObjectPurgeMaintenancePort`, `ObjectPurgeRequest` | `src/application-objectstorage/src/main/java/dev/caskeleton/application/objectstorage/{port,request}/` | `6d27356e` | 구현 0 (D-7c) | +| 삭제 코드 전용 테스트 17개(`direct/` 6개, `multipart/` 2개, `ObjectOperationEpochTest`, `ObjectMutationResponseLossTest`, `S3{DirectMultipart,DirectTransfer,ManagedMultipart}ProviderTest`, `S3ObjectOperationResolverTest`, `MinioDirectTransfer{Contract,Fault}Test`, `S3SdkApiCharacterizationTest.sdkMultipartIntegerPartCountAndMinimumPartBoundariesFailClosed`) | `src/adapter/outbound/objectstorage/src/test/java/dev/caskeleton/adapter/outbound/objectstorage/` | `6d27356e` | 대상 코드 삭제 | +| `AwsS3DirectMutationPreconditionsTest`와 workflow 입력 `run_protected_aws_direct_mutation`·env `OBJECT_STORAGE_AWS_DIRECT_MUTATION_ENABLED` | `src/adapter/outbound/objectstorage/src/objectStorageAwsQualificationTest/.../AwsS3DirectMutationPreconditionsTest.java`, `.github/workflows/object-storage-qualification.yml` | `6d27356e` | direct 전송 lane의 별도 권한 검사. direct 코드가 없으니 검사할 대상이 없다 | + +## 새로 발견한 결함 +- **P2-new-1 (고침)** managed `publish`가 SCAN_CLEAN destination에서 scan 없이 게시한다 — `RoutingObjectMutationAdapter.publish`가 INTEGRITY_VERIFIED에서 곧바로 REFERENCE_PUBLISH_IN_PROGRESS로 가고 `requirePolicy`는 요구 수준이 같은지만 봤다. 이제 scan-gated destination이면 거부한다(`config/RoutingObjectMutationAdapter.java:437-443`). `StagedObjectPublicationLifecycleTest$ManagedPublish.managedPublishToAScanGatedDestinationIsRejected` FAIL(`Expecting actual not to be null`)→PASS. D-9의 CLEAN 보고가 참이 되려면 필요했다. +- **P2-new-2 (보류, 승인자: 저장소 소유자 결정 필요)** sample abort와 reconcile의 경합에서 intent가 멈춘다 — `AbortPosterImageUploadUseCase`(`sample-portfolio/.../poster/AbortPosterImageUploadUseCase.java:63-81,91`)는 DB에 ABORT_AUTHORIZED를 먼저 커밋한 뒤 저장소에 `authorizeAbort`를 부른다. 그 사이 reconcile이 finalize를 끝냈다면(TX3 전) D-1b로 저장소가 거부하고, `ReconcilePosterImageUploadUseCase`(`:100-102`)는 PENDING이 아닌 intent를 거부해서 게시된 객체가 붙지도 retire되지도 않는다. 수정 전에는 같은 경합이 게시된 바이트를 지웠다(더 나쁨). ABORT_AUTHORIZED + 게시됨을 SUPERSEDED/retire로 수렴시킬지 sample 흐름 결정이 필요하다. +- **P2-new-3 (남음)** S3 managed provider `retire`가 항상 UNSUPPORTED를 던진다(`s3/S3ManagedObjectProvider.java:121-125`). S3 profile은 `CONDITIONAL_RETIREMENT`를 주장할 수 있어 destination 컴파일은 통과한다. D-1a 순서에서 S3 abort는 ABORTED를 기록한 뒤 retire에서 실패한다(바이트 잔존, 재시도도 같은 실패). S3는 readiness 근거가 없어 배포 불가라 이번에 고치지 않았다. +- 참고(결함 아님): `docs/evidence/object-storage/batch-d-checkpoint.md:46-62`가 삭제된 테스트 클래스 이름을 실행 명령으로 적고 있다. 과거 시점 증거라 손대지 않았다(W5 문서 drift 후보). diff --git a/docs/reviews/2026-09-25-review-followup-results/P3.md b/docs/reviews/2026-09-25-review-followup-results/P3.md new file mode 100644 index 00000000..835665de --- /dev/null +++ b/docs/reviews/2026-09-25-review-followup-results/P3.md @@ -0,0 +1,50 @@ +# P3 notification — 결과 + +worktree 브랜치 `worktree-agent-a9bbc66a423c4d1fa`, 커밋 D `38d31b98`, W1 `12adea6e`, W2 `6db6214c`. + +검증: 4개 leaf `check` 통과, `:adapter:outbound:persistence-jpa:jpaPlatformContractTest` 208건·`postgresqlNotificationSchemaActivationIntegrationTest` 8건 통과(실패·skip 0), `architectureCheck` 통과, `:app-bootstrap:verifyEnvKeys` OK, `verifyNotificationApiSurface` 통과. 의존성 변경 없음(`verifyDependencyLocks` 미실행). 새 테스트는 application·adapter 단위 테스트이고 persistence-jpa(P9 leaf)에 PG 테스트를 추가하지는 않았다 — 변경은 기존 포트(`find`/`saveHeldBy`/`transition`)만 쓰고 그 JPA 동작은 위 PG lane이 이미 검증한다. +경로는 `src/` 기준 상대 경로를 줄였다: `ntf-adapter/` = `src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/`, `ntf-app/` = `src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/`. + +## 행 결과 +| ID | 결과 | 근거 | +|---|---|---| +| S4-#3a | 완료 | D 커밋 `38d31b98`. `provider/{apns,fcm,twilio,webpush,webhook}` main·test 삭제, `SesSuppressionUpdater` 삭제. `ProviderType`은 SES·SMTP만(`ntf-adapter/autoconfigure/ProviderType.java:26-30`). 5종만 쓰던 설정 필드 `topic`·`vapid-public-key`·`callback-signing-secret-ref` 삭제(`NotificationPlatformSettings.java` Provider), `SecretPurpose.VAPID_SIGNING`·`vapid-signing-key`·env 키 2개(`APP_NOTIFICATION_PLATFORM_VAPID_SIGNING_KEY`, `_KEY_ID`)를 `notification.yml`·`.env.example`·`env-keys.yaml`·`secrets-classification.yaml`·`scripts/run-compose-runtime-smoke.sh`에서 삭제. 문서: `docs/notification/{configuration-reference,support-matrix,module-mapping,provider-runbooks}.md`, `composition/notification-platform/README.md`. 새 테스트 `NotificationPlatformSettingsTest.aRemovedProviderTypeFailsStartupAsUnknown`(5종 → "unknown provider type"). API surface 416→379 재승인. `verifyEnvKeys` OK | +| B-2e | 완료 | `SnsCertificateCacheTest.aCertificateNotIssuedToSnsIsRefused` FAIL(`Expecting actual not to be null` — CN=sns.test.invalid 인증서의 키를 그대로 반환)→PASS. `ntf-adapter/autoconfigure/NotificationCallbackProviderConfig.java:89`(subject가 `CN=sns.amazonaws.com`/`.com.cn`이 아니면 거부), `:80` 유효기간 검사도 추가(P3-new-2) | +| B-6 | 완료 | `JdkNotificationHttpGatewaySecurityTest.aResponseBodyThatNeverEndsIsCutAtTheCapWithoutWaitingForItsEnd` FAIL(`TimeoutException` — 요청 timeout 10초가 지나도 끝나지 않는 body를 끝까지 기다려 JUnit 20초 timeout)→PASS. `ntf-adapter/provider/http/JdkNotificationHttpGateway.java:147-160`(`ofInputStream` + `readNBytes(max)` 후 close, 읽기는 호출 스레드에서 `Supplier`로) | +| B-7a | 완료 | `NotificationAdminApplicationServiceTest.aTenantScopedOperatorCannotReconcileAnotherTenantsAttempt` FAIL(`Expecting actual not to be null` — 예외 없이 진행)→PASS. `ntf-app/admin/NotificationAdminApplicationService.java:161-168`(attempt마다 소유 tenant 확인, 배치 중 하나라도 남의 것이면 아무것도 안 함). 없는 attemptId는 reconcile이 아무것도 하지 않으므로 검사 생략 | +| B-7b | 완료 | `NotificationAdminApplicationServiceTest.aTenantScopedOperatorCannotChangeAGlobalProviderState` FAIL(`Expecting actual not to be null`)→PASS. `ntf-app/admin/AdminAuthorizationGuard.java:58`(`requireGlobal`), 호출 `NotificationAdminApplicationService.java:305` | +| X2-P2-7b | 남음 | 이유: I-5a와 같은 결함·같은 파일(`src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/ratelimit/ForwardedHeaderClientIpResolver.java`)이고 소유 leaf `adapter:inbound:web`은 P10 범위다. 수정 방향도 갈린다(이 행: trusted proxy 확인 추가 / I-5a: 모드 자체 삭제 + native forward-headers). P3 leaf인 web-notification의 `ExternalRequestUrlResolver`는 이미 trusted proxy일 때만 forwarded 헤더를 쓴다. P10 I-5a 결과로 함께 닫는 것이 맞다. 설정 통합은 I-5b(W3) | +| B-3 | 완료 | `NotificationDispatchServiceTest.aTemplateThatCannotRenderFailsTheDeliveryInsteadOfLeavingItClaimed` FAIL(`TemplateVariableValidationException: TEMPLATE_VARIABLES_INVALID`가 dispatch 밖으로 새어 lease가 남음)→PASS. `ntf-app/dispatch/NotificationDispatchService.java:147-163`(render·profile의 재시도 불가 `NotificationException` → 수신자 FAILED + `lastFailureCategory`, lease 해제), `:201` `failBeforeAttempt`(fenced `saveHeldBy`). 수정 방향의 "제출 시 변수 스키마 검증"은 하지 않았다: poison pill을 닫는 것은 dispatch 쪽 처리이고(템플릿 내용·엔진 오류도 여기서 걸림), 제출 검증은 `NotificationSubmissionService` 생성자·조립 변경이 필요한 입력 품질 개선이다 | +| B-4a | 완료 | `LeaseRecoveryServiceTest.aDispatchingDeliveryWhoseAttemptsAllCompletedIsRequeued` FAIL(`Expecting actual: [] to contain exactly ... READY_TO_DISPATCH`)→PASS. `ntf-app/dispatch/LeaseRecoveryService.java:123-133`. 수정 방향(recovery에서 retry policy 재적용)보다 작게: recorder가 이미 결과를 수신자 행에 썼고 dispatch의 `RoutingDecisionEngine`이 그 사실(accepted면 stop→COMPLETED, ambiguous면 reconcile)로 다음 단계를 다시 정하므로 READY_TO_DISPATCH로 되돌리면 된다. recovery에 retry policy·profile 의존을 끌어오지 않는다 | +| B-4b | 완료 | `ReconciliationServiceTest.anUnsupportedAnswerParksADispatchingDeliveryForAnOperator`, `aFailedAnswerParksADispatchingDeliveryForAnOperator` FAIL(`Expecting actual: [DISPATCHING, Optional[2026-09-20T00:00:00Z]] to contain exactly [RECONCILIATION_REQUIRED, Optional.empty]`)→PASS. `ntf-app/dispatch/ReconciliationService.java:126,132,148`(`parkForOperator`: DISPATCHING인 수신자만 `RECONCILIATION_REQUIRED`·next 없음으로, 이미 끝난 수신자는 그대로 — `anUnsupportedAnswerLeavesAFinishedDeliveryAlone`) | +| B-5a | 완료 | `DispatchOutcomeRecorderTest.aLateMatchedCallbackProjectionIsNotOverwrittenByTheRecorder` FAIL(컴파일: `record(attempt, recipient, lease, …)` 시그니처 없음 — lease 인자를 요구하는 테스트)→PASS. fake 투영 저장소가 JPA처럼 수신자 행에 DELIVERED/DEVICE_DELIVERED를 올린다. `ntf-app/dispatch/DispatchOutcomeRecorder.java:122`(투영 뒤 수신자를 다시 읽고 recorder 소유 필드만 갱신) | +| B-5b | 완료 | `DispatchOutcomeRecorderTest.aRecorderThatLostItsLeaseWritesNothingToTheRecipient` FAIL(컴파일, 위와 같음)→PASS. `DispatchOutcomeRecorder.java:153` `saveHeldBy(updated, lease)`, 호출 `NotificationDispatchService.java:194`. 빈 결과(lease 상실)면 쓰지 않고, 이어지는 next-step 쓰기도 fenced라 no-op | +| B-7c | 완료 | `NotificationAdminApplicationServiceTest.reconcileAsksTheProviderWithNoTransactionOpen` FAIL(`Expecting actual: [true] to contain exactly [false]`)→PASS. `ntf-app/admin/AdminOperationExecutor.java:54`(`executeOutsideTransaction`: claim 트랜잭션 → 본문 트랜잭션 없이 → 결과 저장은 본문이 자기 트랜잭션에서), reconcile만 이 경로(`NotificationAdminApplicationService.java:183`). 실패 시 claim을 `FAILED` 결과로 닫음(`AdminOperationExecutorTest.anOperationThatFailsOutsideTheTransactionCompletesItsClaimAsFailed`) — 안 닫으면 같은 id가 영구 IN_PROGRESS. redrive·suppress·provider state는 DB/메모리 작업뿐이라 기존 단일 트랜잭션 유지 | +| B-9a | 완료 | `SmtpNotificationProviderAdapterTest.aNonEmailContactPointFailsBeforeTheCallStarts` FAIL(`Expecting actual throwable to be an instance of ProviderCallNotStartedException but was IllegalArgumentException`)→PASS. `ntf-adapter/provider/EmailRecipients.java`(reveal 실패·비 email → `ProviderCallNotStartedException(CONTACT_POINT_INVALID, INVALID_RECIPIENT)`), SMTP `SmtpNotificationProviderAdapter.java:86`, SES도 같은 결함이라 함께 `SesNotificationProviderAdapter.java:111`. 첨부 open 실패는 이미 `AttachmentUnavailable/IntegrityException`(preDispatch, ambiguous=false)이라 dispatch가 not-submitted로 처리 — 변경 불필요 | +| B-9b | 완료 | `NotificationDispatchServiceTest.aDeliveryBlockedByNotBeforeStaysScheduledForThatTime` FAIL(`Expecting Optional to contain: 2026-09-20T01:00:00Z but was empty`)→PASS. `ntf-app/dispatch/DispatchPipeline.java:60`(`Blocked`에 `notBefore`), `DispatchGuardOutcome.Blocked`에 `nextDispatchAt`, `NotificationDispatchService.java:142` | +| X1-#6e | 완료 | B-5a·B-5b와 같은 결함. 같은 수정·테스트(`DispatchOutcomeRecorder.java:122,153`) | +| S4-#3b | 완료 | `NotificationProviderAssemblyTest.anSesHardBounceIsProjectedRatherThanFailedForWantOfAProjector` FAIL(컴파일: `providerEventProjectorRegistry(AssembledPlatform, List)` 없음 — registry가 빈 bean 목록으로만 만들어지던 구조)→PASS(hard bounce → `DeliveryOutcome.BOUNCED`). 빈 슬롯 유지·연결: `ProviderCallbackAssembler.projector()` 추가, SES는 `SesDeliveryProjector`(`SesProviderCallbackAssembler.java:34`), assembly가 콜백을 만들 때 projector를 `AssembledPlatform.projectors`에 넣음(`NotificationProviderAssembly.java:134`, INGEST_ONLY 포함), registry는 `platform.projectors()` + 선언된 bean(`NotificationPlatformRegistriesConfig.java:46`). `SesSuppressionUpdater`는 소유자 승인 삭제(D)라 연결하지 않았다 — suppression은 `ProviderEventProjectionService`의 `NotificationSideEffectPort` 경로가 이미 처리 | +| NEW-8a | 완료 | B-4b와 같은 결함. 같은 수정·테스트(`ReconciliationService.java:148`). 수정 방향대로 `ambiguousAttemptExists`·attempt는 건드리지 않아 redrive는 계속 duplicate-risk 승인을 요구 | +| NEW-8b | 완료 | B-4a와 같은 결함. 같은 수정·테스트(`LeaseRecoveryService.java:123`). 방향의 "staleAfter 지나면 reconcile 호출" 대신 requeue: 모든 attempt가 완료라 provider에 물을 것이 없고, dispatch 라우팅이 기록된 결과로 다음 단계를 정한다. `expiredDispatching`이 이미 staleAfter로 거른다 | + +## 제거된 코드 +| 대상 | 경로 | 마지막으로 존재한 커밋 | 이유 | +|---|---|---|---| +| APNs provider adapter(4 클래스)와 테스트 | `src/adapter/outbound/notification/src/{main,test}/java/dev/caskeleton/adapter/outbound/notification/platform/provider/apns/` | `6d27356e` | assembler 없음 — 켜면 기동 실패. S4-#3a | +| FCM provider adapter(10 클래스)와 테스트 | `…/platform/provider/fcm/` | `6d27356e` | 같은 이유. S4-#3a | +| Twilio provider adapter(9 클래스)와 테스트 | `…/platform/provider/twilio/` | `6d27356e` | 같은 이유. S4-#3a | +| Web Push provider adapter(10 클래스)와 테스트 | `…/platform/provider/webpush/` | `6d27356e` | 같은 이유. S4-#3a | +| Webhook provider adapter(3 클래스)와 테스트 | `…/platform/provider/webhook/` | `6d27356e` | 같은 이유. S4-#3a | +| `SesSuppressionUpdater` | `…/platform/provider/ses/SesSuppressionUpdater.java` | `6d27356e` | main 참조 0. suppression은 projection side-effect 경로가 담당. S4-#3a | +| `ProviderType.APNS/FCM/TWILIO/WEB_PUSH/WEBHOOK` | `…/platform/autoconfigure/ProviderType.java` | `6d27356e` | 조립할 수 없는 종류. 이제 binding에서 unknown type으로 실패 | +| provider 설정 필드 `topic`, `vapid-public-key`, `callback-signing-secret-ref` | `…/platform/autoconfigure/NotificationPlatformSettings.java` (Provider) | `6d27356e` | 삭제된 5종만 읽던 키. capability 규칙 3(동작 안 하는 옵션은 키를 두지 않음) | +| `SecretPurpose.VAPID_SIGNING`, 설정 `secrets.vapid-signing-key`·`active-key-ids.VAPID_SIGNING`, env `APP_NOTIFICATION_PLATFORM_VAPID_SIGNING_KEY`·`APP_NOTIFICATION_PLATFORM_VAPID_SIGNING_KEY_ID` | `src/application-notification/…/platform/security/SecretPurpose.java`, `src/composition/notification-platform/src/main/resources/config/module-defaults/notification.yml`, `src/.env.example`, `docs/registries/env-keys.yaml`, `docs/registries/secrets-classification.yaml`, `scripts/run-compose-runtime-smoke.sh` | `6d27356e` | Web Push 삭제로 소비자 0 | +| Twilio·FCM·APNs·Web Push runbook 절, support-matrix·module-mapping 행 | `docs/notification/provider-runbooks.md`, `docs/notification/support-matrix.md`, `docs/notification/module-mapping.md`, `docs/notification/configuration-reference.md` | `6d27356e` | 설명 대상 코드 삭제 | + +## 새로 발견한 결함 +- `P3-new-1` (고침, W1): `ntf-app/admin/AdminAuthorizationGuard.java` `requireTenant`가 어떤 작업이든 거부 시 `AdminAccessDeniedException(SUPPRESS)`를 던졌다 — redrive·reconcile 거부가 SUPPRESS 권한 부족으로 보고됨. 실제 권한을 인자로 받게 고침(`:41`). +- `P3-new-2` (고침, W1): SNS 서명 인증서의 유효기간을 확인하지 않았다(`NotificationCallbackProviderConfig.java:80` `checkValidity()` 추가, B-2e와 함께). +- `P3-new-3` (안 고침): JDK HttpClient의 요청 timeout은 응답 body 읽기를 덮지 않는다. B-6 재현 테스트의 FAIL이 증거다(요청 timeout 10초가 지나도 body 대기가 끝나지 않아 JUnit 20초 timeout). 상한 전까지 body를 조금씩 흘리는 provider(또는 SNS 인증서 host)는 dispatch 스레드를 무기한 잡을 수 있다. 위치 `ntf-adapter/provider/http/JdkNotificationHttpGateway.java:79-82`(`send` 뒤 `body().get()`). 고치려면 body 읽기에 deadline이 필요하다(예: deadline에 stream을 닫는 타이머). 설계가 필요해 이번 범위에서 제외. +- `P3-new-4` (고침, W2): SES adapter도 B-9a와 같은 결함(비 email 연락처·reveal 실패가 ambiguous로 기록). 공용 `EmailRecipients`로 SMTP와 함께 고침. +- `P3-new-5` (안 고침): 라우트의 profile runtime이 사라진 경우 `gateway.profile()`이 `IllegalStateException`(`ntf-adapter/dispatch/ProviderRuntimeRegistry.java:50`)을 던져 B-3과 같은 경로(attempt row 전, lease 미해제 → requeue 반복)를 탄다. 설정 drift라 "고쳐질 때까지 재시도"로 볼 수도 있어 FAILED로 닫지 않았다. 판단 필요 시 소유자 결정. +- `P3-new-6` (안 고침): dispatch의 guard `Blocked` 전이와 routing stop 전이(`ntf-app/dispatch/NotificationDispatchService.java:138-142`, `applyRoutingStop`)는 lease fencing 없는 `transition`을 쓴다(B-5b와 같은 계열). provider 호출 전 짧은 구간이라 위험은 낮다. diff --git a/docs/reviews/2026-09-25-review-followup-results/P4.md b/docs/reviews/2026-09-25-review-followup-results/P4.md new file mode 100644 index 00000000..d03ca4c9 --- /dev/null +++ b/docs/reviews/2026-09-25-review-followup-results/P4.md @@ -0,0 +1,50 @@ +# P4 결과 — file server + +- worktree: `/home/donghyeon/workspace/desktop-server-git/clean-architecture-backend-template/.claude/worktrees/agent-a4be05fc0e42cb70c`, 브랜치 `worktree-agent-a4be05fc0e42cb70c` +- 커밋: `433bacdb` (W1), `ed2c0929` (W2). D 커밋 없음(P4는 결정된 삭제 없음). +- 새 migration: `src/adapter/outbound/persistence-fileserver/src/main/resources/db/migration/jpa/fileserver/V5__fileserver_file_owner.sql` (fileserver stream 버전 5). + `applied-migrations.sha256`에는 줄을 추가하지 않았다. 그 테스트(`AppliedMigrationImmutabilityTest`)는 persistence-jpa의 `src/main/resources/db/migration`만 읽고, fileserver migration은 persistence-fileserver leaf에 있다. 줄을 추가하면 `appliedMigrationsKeepTheBytesTheyWereAppliedWith`가 실패한다(아래 P4-new-1). +- registry edge 추가: `composition-fileserver-platform -> adapter-outbound-persistence-jpa` (NEW-11, W2 커밋 메시지에 이유). +- lockfile: `src/composition/fileserver-platform/gradle.lockfile` 재생성(+12줄). app-bootstrap lockfile은 변화 없음. + +## 행 결과 +| ID | 결과 | 근거 | +|---|---|---| +| C-2a | 완료 | `FinalizeUploadServiceTest.aQuarantineVerdictSchedulesNoCleanupOfTheStagedBytes` FAIL(`Expecting empty but was: [CleanupItem[... FAILED_VERIFICATION_CONTENT ...]]`)→PASS. `src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/upload/DefaultFinalizeUploadService.java:272`(REJECTED일 때만 staging cleanup 예약, QUARANTINE은 세션만 terminal) | +| C-2b | 완료 | `CleanupServiceTest.aStagingItemForAQuarantinedFileLeavesTheStagedBytesInPlace` FAIL(`Expecting value to be true but was false`)→PASS. `.../cleanup/DefaultCleanupService.java:197`(QUARANTINED면 삭제 없이 done) | +| C-5a | 완료 | `CleanupServiceTest.anUploadPastItsExpiryIsMovedToExpired` FAIL(`expected: EXPIRED but was: UPLOADING`)→PASS, `theStagedBytesOfAnExpiredUploadAreReclaimed` FAIL(`Expecting value to be false but was true`)→PASS, W2에서 `anUploadThatExpiredBeforeItsFirstAppendIsExpiredToo` FAIL(`expected: EXPIRED but was: CREATED`)→PASS. `DefaultCleanupService.java:125`(batch 시작 시 만료 열린 세션 terminal → CREATED/UPLOADING/FAILED 레코드 EXPIRED + `EXPIRED_UPLOAD` 예약). 반복 조회로 limit가 막히지 않게 `findExpired`는 terminal 세션 제외: `src/adapter/outbound/persistence-fileserver/.../repository/JpaUploadSessionRepository.java:19`, PG `PostgreSqlFileserverMetadataStoreIntegrationTest.aTerminatedExpiredSessionIsNotListedAgain` PASS | +| C-5c | 완료 | `TusProtocolContractTest.aCreateThatDefersItsLengthIsRefusedBecauseTheExtensionIsNotOffered` FAIL(`Status expected:<400> but was:<201>`)→PASS. `src/adapter/inbound/web-fileserver/.../tus/TusRequestParser.java:65`. 기존 `aDeferredLengthUploadIsNeverAutoFinalized`는 이 테스트로 대체 | +| C-8a | 완료 | 결정 14. `RoleBasedFileAccessPolicyTest.aCallerWithTheSameRolesIsDeniedAFileSomebodyElseOwns`(READ_METADATA·DOWNLOAD·APPEND·FINALIZE·DELETE·COPY·MOVE 7건), `theSamePrincipalInAnotherTenantIsDeniedTheFile`, `aFileWithNoRecordedOwnerIsDeniedToEveryDataPlaneCaller` 모두 FAIL(`Expecting actual not to be null` = 거부 안 됨)→PASS, `theOwnerIsGrantedEveryDataOperationWithoutAnException` PASS. `src/adapter/outbound/fileserver/.../security/RoleBasedFileAccessPolicy.java:74,86`. 모델: `FileOwner`(`.../api/metadata/FileOwner.java`), `FileRecord.owner`/`FileDescriptor.owner`/`FileRecordDraft.owner`, 생성 시 `context.subject().asOwner()`(`DefaultUploadApplicationService`, copy는 복사한 사람). 저장: `V5__fileserver_file_owner.sql`(`owner_principal_id varchar(256)`, `owner_tenant_id varchar(64)`), `FileEntity`·`FileEntityMapper`·`JpaFileMetadataStore.insert`. PG `aNewRecordKeepsTheOwnerItWasCreatedFor` PASS, `UploadApplicationServiceTest.aCreatedFileIsOwnedByTheCallerInItsTenant` PASS. **기존 행(owner NULL) 처리:** data plane에서는 누구에게도 허용하지 않는다(fail closed). 소유자를 추론할 근거가 없고, 역할 모델상 남의 파일에 대한 조치는 감사되는 관리 plane(force-delete·reverify, descriptor 없음)이 담당하기 때문이다. **ADMIN 예외:** 두지 않는다. 기존 역할 모델이 "admin은 write를 상속하지 않는다"이므로 data plane 연산은 admin 역할이어도 소유자 검사를 받는다. **anonymous read**가 켜진 배포는 전 파일 공개를 선택한 것이라 read 등급에서 소유자 검사를 건너뛴다(기존 의미 유지). **tenant:** subject 속성 `tenant`(`FileAccessSubject.TENANT_ATTRIBUTE`)와 비교한다. web 플랫폼은 아직 tenant를 해석하지 않아(`WebRequestContext`를 만드는 곳 없음) 현재는 양쪽 모두 비어 있고, transport가 속성을 채우면 그대로 적용된다. 문서 `docs/fileserver/security.md` 「Authorization」 | +| C-8b | 완료 | `FinalizeUploadServiceTest.aCallerTheFinalizeOperationIsDeniedToPublishesNothing` FAIL(`Expecting actual not to be null`)→PASS. `DefaultFinalizeUploadService.java:109`(digest·검증·publish 전에 FINALIZE 인가, 정책은 생성자 주입 — `composition/.../FileserverUploadServiceConfiguration`) | +| C-8c | 완료 | `FileserverAdminServiceTest.aCallerDeniedAdminReadsCannotSeeStorageHealth` FAIL(`Expecting actual not to be null`)→PASS. 새 `FileOperation.ADMIN_READ`(admin 등급, `RoleBasedFileAccessPolicy.java:102`), `DefaultFileserverAdminService.java:206`. `RoleBasedFileAccessPolicyTest.adminReadsNeedTheAdminRoleRatherThanTheReadRole` PASS | +| C-3a | 완료 | `FileserverCleanupWorkerTest.aRunReconcilesTheFilesWhoseOutcomeWasLeftOpen`, `aFailingCleanupBatchStillLetsReconciliationRun` — FAIL은 컴파일 실패(`constructor FileserverCleanupWorker ... cannot be applied`, reconciliation을 받을 방법이 없었음)→PASS. 별도 worker 대신 기존 `FileserverCleanupWorker`가 매 회차 cleanup 뒤 `reconcileRecoverable(maxItems)`를 독립 try로 실행(`src/composition/fileserver-platform/.../FileserverCleanupWorker.java`, `FileserverCleanupConfiguration`). 같은 `cleanup.enabled` 스위치를 쓴다(설정 키 추가 없음). recovery queue는 pending 중복을 갱신만 한다(`JpaRecoveryQueue.enqueue`) | +| C-3b | 완료 | `FinalizeUploadServiceTest.theContentKeyIsRecordedBeforeThePublishIsAttempted` FAIL(`Expecting Optional to contain a value but it was empty`)→PASS. `DefaultFinalizeUploadService.java:214`(UPLOADED→VERIFYING 전이에 `FileRecordMutation.intendedContentKey`), `UploadContentGateway.newContentKey()`, `FinalizeContentCommand.contentKey`(기존 4인자 생성자 유지), publisher가 그 key로 게시(`AtomicMoveContentPublisher`, `MetadataPointerContentPublisher`). 부수 조치: 검증은 staged bytes를 읽도록 `VerificationRequest.contentKey=empty`(미게시 key로 읽으면 RETRY 고착), 미게시 key의 content 정리는 quota를 회수하지 않음(`DefaultCleanupService.java:275`, `publishedAt` 있을 때만) | +| C-3c | 완료 | `FinalizeUploadServiceTest.anAmbiguousPublishIsQueuedForRecovery` FAIL(`... to contain entry PUBLISH_UNCONFIRMED`)→PASS. `DefaultFinalizeUploadService.java:130`(inNew로 recovery 기록 후 재던짐, 기록 실패는 suppressed) | +| C-3d | 완료 | NEW-3과 같은 결함. `TransactionPort`에 timeout 옵션이 없어 가장 작은 변경으로 `SpringTransactionPort`의 REQUIRES_NEW template에 30초 설정. `SpringTransactionPortTest.inNewBoundsItsTransactionToThirtySeconds` FAIL(`expected: 30 but was: -1`)→PASS. `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/transaction/SpringTransactionPort.java:62`. 포트 시그니처 변경 없음(구현·fake 수정 불필요). `verifyJpaApiSurface` OK | +| C-4a | 완료 | `UploadApplicationServiceTest.cancellingAPublishedUploadQueuesItsContentForReclamation` FAIL(`[CANCELLED_STAGING] to contain [DELETED_READY_CONTENT]`)→PASS. cancel이 `FileRetirement.retire(record, uploadId)`를 쓴다(`DefaultUploadApplicationService.java:265`): content key가 있으면 content 정리도 예약. 409 거부 대신 retire 재사용을 택함(삭제와 같은 DELETE 인가를 이미 거침) | +| C-4b | 완료 | `CleanupServiceTest.aCancelledUploadReachesDeletedOnceItsStagingIsReclaimed` FAIL(`expected: DELETED but was: DELETING`)→PASS. `DefaultCleanupService.java:218`(staging 정리와 같은 트랜잭션에서 content key 없는 DELETING→DELETED). quota release는 넣지 않았다: reservation은 upload에 연결되지 않은 scope 단위 TTL 장부이고 만료로 정리된다(`JpaQuotaCommitGateway` 설계 주석) | +| C-5b | 완료 | `CleanupServiceTest.aRetiredOrphanIsPurgedFromQuarantine` FAIL(`Expecting value to be false but was true`)→PASS. `CleanupContentGateway.purgeQuarantined` 추가, `DefaultCleanupService.java:243`, `LocalCleanupContentGateway.java:41`(ledger를 다시 확인하는 `OrphanScanPort.purgeQuarantined`에 위임). staging root scan은 하지 않았다(더 작은 수정): staging 객체는 항상 세션이 있고(세션 commit 뒤에만 생성), 이제 모든 세션 끝(cancel·reject·C-5a 만료, CREATED 포함)이 staging 정리를 예약하므로 scan이 찾을 대상은 대기 중인 정리 항목뿐이다. 예외 한 가지는 P4-new-4 | +| C-6 | 완료 | `UploadApplicationServiceTest.anAppendToACancelledUploadIsRefusedAsGone` FAIL(`Expecting actual throwable to be an instance of UploadExpiredException`, 실제는 재시도 가능한 lease 충돌)→PASS, `theStatusOfACancelledUploadIsGone` FAIL(`Expecting actual not to be null`)→PASS. `DefaultUploadApplicationService.java:332`(terminal → `UPLOAD_EXPIRED` 410), status도 `requireActiveSession`(`:245`) | +| C-7a | 완료 | `LocalAppendEngineTest.aReattachedHandleResumesTheRunningDigestInsteadOfRereadingThePrefix` FAIL(`Expecting Optional to contain a value but it was empty`)→PASS, 보호 테스트 `aRolledBackAppendLeavesTheCachedDigestDescribingOnlyTheSurvivingPrefix` PASS. `src/adapter/outbound/fileserver/.../local/LocalBlockingContentStore.java:61,187,437`(uploadId별 LRU 1024, 복사본으로 넣고 꺼냄, 실패·finalize·discard 시 제거), `StreamingDigest.copy()` | +| C-7b | 완료 | `TusProtocolContractTest.theCompletingPatchFinalizesOnTheTransferExecutor` FAIL(`"Test worker" to start with "fs-transfer-"`)→PASS. `TusController.java:180`, draft-12도 동일(`Draft12UploadController.java:151`). 파일 재읽기: C-7a 캐시로 `stagingDigest`가 보통 디스크를 읽지 않으므로 finalize의 전체 읽기는 `verifyStaged` 1회로 줄었다. `stagingDigest` 결과를 `verifyStaged`에 넘겨 그 1회까지 없애는 것은 하지 않았다 — 디스크에서 다시 증명한다는 게시 설계(`ContentPublishVerification` 주석)를 버리게 되고, finalize는 writer lease 없이 실행되기 때문 | +| C-9a | 완료 | `TransferAdmissionControllerTest.anExhaustedScopeIsARetryableAdmissionRejection` FAIL(`... to be an instance of TransferAdmissionRejectedException`)→PASS. `src/application-fileserver/.../quota/DefaultTransferAdmissionController.java:61` | +| C-9b | 완료 | `UploadApplicationServiceTest.admissionIsCountedPerCallerRatherThanPerNamespace` FAIL(`expected: null but was: QuotaExceededException`)→PASS. `DefaultUploadApplicationService.java:280`(`QuotaScope.ofPrincipal`, create·append). quota 예약은 namespace 그대로. principal 수가 무한하므로 표가 차면 유휴(모든 permit 반환) semaphore를 버린다(`DefaultTransferAdmissionController.java:123`, 조회+획득을 한 lock 안에서): `newCallersStillGetTheirOwnScopeOnceTheTableHasFilledWithIdleOnes` FAIL(`expected: null but was: QuotaEx...`)→PASS. 기존 `scopeSemaphoreRegistryIsBoundedAndOverflowScopesShareConservativeCapacity`는 이 동작과 모순이라 `theScopeRegistryStaysBoundedAsCallersComeAndGo`로 교체. env 설명 갱신(`docs/registries/env-keys.yaml` `..._SCOPE_UPLOAD_PERMITS`, `docs/fileserver/configuration.md`) | +| C-11 | 완료 | `Draft12ProtocolTest.aCreationBodyIsStoredAsTheFirstPartOfTheUpload` FAIL(`expected: "abc" but was: ""`)→PASS, `theFinalLengthComesFromUploadLengthRatherThanTheCreationBody` FAIL(`OptionalLong[3] to contain 6L`)→PASS. `Draft12UploadController.java:109,205`(`Upload-Length` 헤더, POST body는 offset 0 append, `Upload-Complete: ?1`이면 finalize). 한계: Content-Length 없는 chunked POST body는 저장하지 않는다 | +| S1-#5 | 완료 | `FileserverAdminServiceTest.forceDeletingAFileThatWasNeverPublishedRetiresItCompletely` FAIL(`expected: DELETED but was: DELETING`)→PASS. 세 호출부가 `src/application-fileserver/.../cleanup/FileRetirement.java:40` 하나를 쓴다: `DefaultFileLifecycleService.java:84`, `DefaultFileserverAdminService.java:167`, `DefaultUploadApplicationService.java:265`. `cleanup` 패키지에 둔 이유: 세 호출 패키지가 이미 cleanup을 의존하고 cleanup은 그들을 의존하지 않아 새 패키지 순환이 생기지 않는다 | +| S1-lead-6 | 완료 | SQL의 허용 상태 문자열을 없애고 `JpaFileMetadataStore`가 전이표(`FileStateMachine.canTransition(s, DELETING)`)에서 목록을 만들어 파라미터로 넘긴다: `src/adapter/outbound/persistence-fileserver/.../repository/FileTransitionRepository.java:73`, `JpaFileMetadataStore.java:56`. 동작이 바뀐 게 아니라 중복 제거라 FAIL 재현 대상이 없음. PG `aRecordInAStateWithNoDeletingEdgeIsNotMarkedDeleting`(VERIFYING 거부)·기존 `logicalDeleteMovesTheRecordOutOfPublicReadability` PASS | +| NEW-3 | 완료 | C-3d와 같은 수정·테스트. `SpringTransactionPort.java:62` | +| NEW-11 | 완료 | `src/composition/fileserver-platform/build.gradle`에 `runtimeOnly project(':adapter:outbound:persistence-jpa')`, `src/config/architecture/modules.json` edge 추가, README 갱신(`src/composition/fileserver-platform/README.md` 저장소 줄, `src/README.md:270` 표). `architectureCheck`·`verifyDependencyLocks` 통과. JPA 줄 없이 fileserver만 고른 조립의 기동 테스트는 추가하지 않았다: 모든 테스트 classpath(app-bootstrap integrationTest 포함)에 persistence-jpa가 이미 있어 "없는 조립"을 만들 수 없다. 대신 조립 lane `:app-bootstrap:integrationTest`(fileserver PG 왕복 포함 4건) 통과 | + +## 제거된 코드 +| 대상 | 경로 | 마지막으로 존재한 커밋 | 이유 | +|---|---|---|---| +| tus `Upload-Defer-Length: 1` 수락 분기 | `src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/tus/TusRequestParser.java` `declaredLength` | `6d27356e` | C-5c. 길이를 나중에 확정할 PATCH가 없어 끝나지 않는 upload만 만들었다. 이제 400 | +| 테스트 `aDeferredLengthUploadIsNeverAutoFinalized` | `src/adapter/inbound/web-fileserver/src/test/java/dev/caskeleton/adapter/inbound/web/fileserver/tus/TusProtocolContractTest.java` | `6d27356e` | 위 분기를 전제로 한 테스트. `aCreateThatDefersItsLengthIsRefusedBecauseTheExtensionIsNotOffered`로 대체 | +| 테스트 `scopeSemaphoreRegistryIsBoundedAndOverflowScopesShareConservativeCapacity` | `src/application-fileserver/src/test/java/dev/caskeleton/application/fileserver/quota/TransferAdmissionControllerTest.java` | `6d27356e` | C-9b. 유휴 scope가 overflow로 몰린다는 옛 동작을 단언. `theScopeRegistryStaysBoundedAsCallersComeAndGo`로 대체 | +| lifecycle delete·admin forceDelete·cancel의 retire 복사본 | `DefaultFileLifecycleService.delete`, `DefaultFileserverAdminService.forceDelete`, `DefaultUploadApplicationService.cancel` 본문 | `6d27356e` | S1-#5. `cleanup/FileRetirement` 하나로 합침 | + +## 새로 발견한 결함 +- **P4-new-1** (미수정) fileserver migration(`src/adapter/outbound/persistence-fileserver/src/main/resources/db/migration/jpa/fileserver/V1..V5`)은 불변성 테스트가 없다. `AppliedMigrationImmutabilityTest`는 persistence-jpa의 `src/main/resources/db/migration`만 읽는다(`src/adapter/outbound/persistence-jpa/src/test/java/.../migration/AppliedMigrationImmutabilityTest.java:25`). 그래서 V5 줄을 `applied-migrations.sha256`에 넣을 수 없었다(넣으면 그 테스트가 실패). C-10/S2-#11(persistence-fileserver 자체 테스트, W4)과 함께 풀 문제. +- **P4-new-2** (미수정) 재조정이 READY를 복원할 때 quota를 commit하지 않는다. `src/application-fileserver/.../recovery/DefaultFileReconciliationService.java` `reconcilePrePublishWithKey`는 VERIFYING→READY 전이만 하고 `QuotaCommitGateway.commit`이 없다. C-3a·C-3b로 이 경로가 실제로 실행되므로, 재조정으로 복구된 파일은 durable quota를 쓰지 않는다. +- **P4-new-3** (미수정) `DefaultFinalizeUploadService.advanceToVerifying`의 CREATED 분기가 CREATED→UPLOADED를 시도하지만 전이표에는 CREATED→UPLOADING뿐이라 `IllegalStateException`이 난다(`.../upload/DefaultFinalizeUploadService.java` `advanceToVerifying` 첫 if). +- **P4-new-4** (미수정) lifecycle delete(`DefaultFileLifecycleService.delete`)로 진행 중 upload(UPLOADING)를 지우면 레코드는 DELETED가 되지만 세션은 ACTIVE로 남고 staging 정리가 예약되지 않는다. 이후 만료 sweep도 레코드가 DELETED라 staging을 예약하지 않아 staged bytes가 남는다. `FileRetirement`에 upload를 찾는 방법(`StagingUploadLocator`)을 넘기면 풀린다. diff --git a/docs/reviews/2026-09-25-review-followup-results/P5.md b/docs/reviews/2026-09-25-review-followup-results/P5.md new file mode 100644 index 00000000..6a689a0d --- /dev/null +++ b/docs/reviews/2026-09-25-review-followup-results/P5.md @@ -0,0 +1,51 @@ +## 행 결과 +| ID | 결과 | 근거 | +|---|---|---| +| S7-#4 | 완료 | 삭제 커밋 `9b296c7c`(P5 D). 상수 gate·guard·catalog·invariant·testkit·문자열 ArchUnit 흉내 삭제(아래 「제거된 코드」). 전부 main 호출자 0이었다. `GrpcRawApiImportRule`·`GrpcApplicationBoundaryRules`는 자기 테스트의 합성 입력만 검사하고 저장소 코드를 검사하지 않아서 테스트로 옮기지 않고 삭제했다(inbound→outbound 규칙은 app-bootstrap ArchUnit `INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS`가 이미 검사). `GrpcResolverSafetyPolicy`는 상수 메서드 2개만 삭제. starter의 항상 통과하던 advanced 격리 검사도 함께 제거 `src/grpc/grpc-spring-boot-starter/src/main/java/dev/caskeleton/grpc/boot/GrpcPlatformStartupValidator.java:41`. 문서 갱신: `src/grpc/CLAUDE.md`, `src/grpc-advanced/CLAUDE.md`, `docs/runbooks/grpc-advanced-capabilities.md`, `docs/compatibility/grpc-advanced-support-matrix.md` | +| K-11a | 완료 | `WebSocketAutoConfigurationTest.clientChannelExecutorsAreBoundedByTheConfiguredQueueCapacity` FAIL(`[(2147483647, false), (2147483647, false)]` ≠ `[(64, true), (64, true)]`)→PASS. inbound·outbound 둘 다 스레드 CPU×2 고정(core=max), 큐 `app.websocket.channel-queue-capacity`(기본 10000, `@Positive`) `src/adapter/inbound/websocket/src/main/java/dev/caskeleton/adapter/inbound/websocket/stomp/WebSocketConfig.java:74,83`, `.../stomp/WebSocketSettings.java:32`. 새 env 키 `APP_WEBSOCKET_CHANNEL_QUEUE_CAPACITY`(`docs/registries/env-keys.yaml`, `src/.env.example`), `verifyEnvKeys` 통과. 커밋 `b39d3de0` | +| N-3 | 완료 | `GrpcPlatformAutoConfigurationContextTest.enabledPlatformWithoutAnEnvironmentRefusesToStartInsteadOfAssumingLocal` FAIL(`Expecting actual not to be null` — LOCAL 가정으로 기동 성공)→PASS. 기본값 제거 `src/grpc/grpc-spring-boot-starter/src/main/java/dev/caskeleton/grpc/boot/GrpcPlatformProperties.java:30`, 미설정 violation `.../GrpcPlatformStartupValidator.java:80`. 검증 전 생성되는 reflection 정책 bean은 environment가 없으면 PROD 바닥(비활성)으로 만든다 `.../GrpcPlatformAutoConfiguration.java`(reflection bean). 커밋 `b39d3de0` | +| N-4 | 완료 | `GrpcResolverSafetyPolicyTest.aServiceConfigWithRetryThrottlingIsAccepted` FAIL(`credential-shaped field` 위반)→PASS, `aServiceConfigThatTurnsOnRetriesIsRefused` FAIL(`Expected size: 1 but was: 0`)→PASS. 수정 방향과 다른 점: 이 leaf 클래스패스에 JSON 파서가 없고 새로 들이지 않기로 한 leaf라서, service config를 gRPC가 쓰는 파싱된 `Map`로 받게 바꿨다(`NameResolver.Helper.parseServiceConfig`와 같은 형태) `src/grpc-advanced/grpc-advanced-resilience/src/main/java/dev/caskeleton/grpc/advanced/discovery/GrpcResolverUpdate.java:17`. top-level 필드 allowlist `.../GrpcResolverSafetyPolicy.java:25,68`, `methodConfig`의 `retryPolicy`·`hedgingPolicy`는 거부(resolver는 catalog를 모르므로 검증 대신 거부) `:89`, `token` 부분일치 정규식 삭제. 커밋 `b39d3de0` | +| K-6 | 완료 | `GrpcP1BoundaryWireTest.aSuccessfullyCompletedCallStillRunsTheServiceOnCloseHandler`(실제 Netty, `setOnCloseHandler`) FAIL(`Expecting value to be true but was false`)→PASS, `GrpcExceptionHandlingInterceptorTest.aCancelAfterTheCallClosedStillReachesTheServiceListener` FAIL→PASS. gate는 onMessage/onHalfClose/onReady에만, onCancel/onComplete는 try/catch만 `src/adapter/inbound/grpc/src/main/java/dev/caskeleton/adapter/inbound/grpc/GrpcExceptionHandlingInterceptor.java:70,79`. 커밋 `a498ad84` | +| K-10b | 완료 | `GrpcAuthenticationInterceptorTest.aThrowingPolicyIsLoggedWithItsTypeAndMethodButNotItsMessage` FAIL(출력 `""`)→PASS. 예외 타입·메서드만 WARN, 메시지(자격 증명 가능)는 남기지 않음 `src/adapter/inbound/grpc/src/main/java/dev/caskeleton/adapter/inbound/grpc/GrpcAuthenticationInterceptor.java:44`. 커밋 `a498ad84` | +| N-2 | 완료 | `GrpcDeadlineBudgetTest.aBudgetRunsOutAsTimePassesAfterItWasCreated` FAIL(`Expecting value to be true but was false`, sleep 판)→PASS(주입 시계 판), `aDownstreamDerivedLaterGetsOnlyWhatIsLeftThen` 추가. 단조 시계의 절대 deadline + 주입 `LongSupplier` `src/grpc/grpc-core-api/src/main/java/dev/caskeleton/grpc/api/deadline/GrpcDeadlineBudget.java:44,93`. 방향과 다른 점: `remaining(now)` 대신 시계를 주입해 호출부 시그니처를 유지. budget이 살아 있게 되면서 두 번 읽기 경합이 생기는 곳을 한 번 읽기로 고침 `src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/resilience/GrpcRetryCoordinator.java:82`, `.../GrpcWaitForReadyValidator.java:39`. 커밋 `a498ad84` | +| N-5a | 완료 | `GrpcAdmissionControllerTest.racingCallersNeverGetPastTheConcurrencyAndQueueBounds` FAIL(`expected: 2 but was: 4`)→PASS. 두 카운터를 한 락으로(`tryAdmit`·`promoteFromQueue`·`release` 모두 check-then-act였음) `src/grpc/grpc-server/src/main/java/dev/caskeleton/grpc/server/GrpcAdmissionController.java:52`. 커밋 `a498ad84` | +| N-5b | 완료 | `GrpcCredentialRotationManagerTest.racingRotationsNeverLeaveAnOlderGenerationCurrent` FAIL(`expected: 4L but was: 3L`)→PASS, `aDrainCompletedDuringARotationNeverRevertsTheNewGeneration` FAIL(`expected: 3L but was: 2L`)→PASS. CAS 루프 `src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/security/GrpcCredentialRotationManager.java:108`, `completeDrain`은 `updateAndGet` `:126`. 커밋 `a498ad84` | +| N-5c | 완료 | `GrpcChannelRuntimeRegistryTest.racingRotationsDrainEveryReplacedRuntimeAndKeepTheNewestCurrent` FAIL(`"2 draining [1, 1]"`, `"3 draining [1, 1]"` 발생)→PASS. install/rotate/draining/retireQuiescent를 registry 락 하나로, drain 목록은 락 안의 `HashMap`/`ArrayList` `src/grpc/grpc-client/src/main/java/dev/caskeleton/grpc/client/GrpcChannelRuntimeRegistry.java:86`. 커밋 `a498ad84` | +| N-5d | 완료 | `GrpcServiceHealthRegistryTest.aServiceMarkedServingWhileDrainBeginsNeverReturnsTheInstanceToServing` FAIL(`[DRAINING/DRAINING, DRAINING/UNKNOWN, SERVING/SERVING]`)→PASS. 쓰기 메서드 전부 같은 락 `src/grpc/grpc-admin/src/main/java/dev/caskeleton/grpc/admin/GrpcServiceHealthRegistry.java:50,86`. 커밋 `a498ad84` | +| N-5e | 완료 | `GrpcStreamAdmissionConcurrencyTest.aCallerRefusedByTheGlobalBoundLeavesNoTrackedEntry` FAIL(`expected: 1 but was: 2`)→PASS. global 검사를 `computeIfAbsent` 앞으로 `src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/streaming/GrpcStreamAdmission.java:42`. 커밋 `a498ad84` | +| N-6a | 완료 | `GrpcSerializedStreamWriterTest.theByteBoundCountsEachPayloadsOwnSize` RED(테스트 컴파일 실패 — `LongSupplier`는 payload를 받지 못함)→PASS. `ToLongFunction` `src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/streaming/GrpcSerializedStreamWriter.java:74`. 커밋 `a498ad84` | +| N-6b | 완료 | `GrpcSerializedStreamWriterTest.aWriteWhileTheTransportIsNotReadyTellsTheProducerToPause` RED(컴파일 실패 — 결과 값 없음)→PASS. `GrpcStreamWriteResult.ACCEPTED_PAUSE`(queued=true) `.../GrpcSerializedStreamWriter.java:103`. 커밋 `a498ad84` | +| N-6c | 완료 | `GrpcSerializedStreamWriterTest.flushStopsWhenTheTransportStopsBeingReady` RED(컴파일 실패 — readiness 인자 없음)→PASS. `flush(BooleanSupplier)`가 메시지마다 ready 확인, 남은 바이트 정확히 차감 `.../GrpcSerializedStreamWriter.java:133`. 커밋 `a498ad84` | +| N-7 | 완료 | `GrpcContextBinderTest.wrappedWorkSeesTheSubmittingCallsCancellationOnAnotherThread` FAIL(`Expecting AtomicBoolean(false) to have value: true`)→PASS. `Context.current()` 전체를 캡처해 `captured.wrap(work)` `src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/context/GrpcContextBinder.java:97`. 커밋 `a498ad84` | +| N-8a | 완료 | 실제 Envoy v1.31 `--mode validate`: 수정 전 `No TLS certificates found for server context`, 수정 후 `configuration ... OK`(임시 자체서명 인증서를 placeholder 경로에 마운트). `GrpcWebCompatibilityTest.theReferenceProxyTerminatesTlsWithACertificate` FAIL→PASS. `src/grpc-advanced/grpc-advanced-compat/src/main/resources/envoy/envoy.yaml:62`. 커밋 `a498ad84` | +| N-8b | 완료 | `GrpcWebCompatibilityTest.theReferenceProxyExposesEveryTrailerThePlatformSends`(`GrpcErrorMapper`·`GrpcValidationInterceptor` 상수와 대조) FAIL(`error-code,error-category`만 있음)→PASS, `theReferenceProxyLetsTheBrowserSendItsDeadlineAndClientHeaders` FAIL→PASS. `envoy.yaml:41,43` | +| N-8c | 완료 | `GrpcWebCompatibilityTest.theReferenceRouteLeavesStreamLengthToTheCallersDeadline` FAIL→PASS. route `timeout: 0s` + `max_stream_duration.grpc_timeout_header_max: 0s` `envoy.yaml:34,36`(Envoy validate 통과) | +| N-11a | 완료 | `GrpcOperationLedgerRepositoryTest.aConflictWhoseRowVanishedBeforeTheReadIsNotTakenAsOwnership` FAIL(`Expecting actual not to be null`)→PASS. 0행 + 조회 실패면 `IllegalStateException` `src/grpc/grpc-operation-ledger-jpa/src/main/java/dev/caskeleton/grpc/ledger/JpaGrpcOperationLedger.java:58`. PG lane(`integrationCheck`) 18건 통과. 커밋 `a498ad84` | +| N-11b | 완료 | 리뷰의 "`sha256:` 형식 검증 안 거침"은 틀림(`GrpcOperationIdentity.java:29`가 검사) — 길이만 고침. `GrpcOperationIdentityTest.aCallerFingerprintWiderThanItsLedgerColumnIsRefused`·`anIdentityWhoseStorageKeyWouldNotFitTheLedgerIsRefused` FAIL(`Expecting actual not to be null`)→PASS. V001 컬럼 폭(caller 256, method 256, hash 80, storage key 512)으로 compact constructor에서 거부 `src/grpc/grpc-core-api/src/main/java/dev/caskeleton/grpc/api/ledger/GrpcOperationIdentity.java:24,40`. migration 변경 없음. 커밋 `a498ad84` | +| X1-지도-Admission / in-flight | 완료 | N-5a와 같은 수정. `Semaphore` 대신 한 락: in-flight와 queued 두 카운터를 한 결정에서 함께 봐야 해서 semaphore 두 개로는 원자적으로 안 된다. `GrpcAdmissionController.java:52`, `GrpcAdmissionControllerTest` | +| X1-#10a | 완료 | 위와 같음(동시 호출 수 > 한도 테스트 `GrpcAdmissionControllerTest.racingCallersNeverGetPastTheConcurrencyAndQueueBounds`, optional build) | +| X2-P1-3b | 완료 | `GrpcSafeActivationTest.theVendorPlatformNamespaceBesideTheAdapterDoesNotFailItsStrictBinding` FAIL(`UnboundConfigurationPropertiesException: The elements [ca-skeleton.grpc.platform.enabled] were left unbound`)→PASS. 어댑터 prefix `ca-skeleton.grpc` → `ca-skeleton.grpc.server` `src/adapter/inbound/grpc/src/main/java/dev/caskeleton/adapter/inbound/grpc/GrpcServerSettings.java:17`, `GrpcServerConfig.java`. 어댑터 키는 env-keys registry에 행이 없었다(추가·수정 없음). 갱신: `src/adapter/inbound/grpc/{CLAUDE,README}.md`, `src/README.md:269`(env `CA_SKELETON_GRPC_SERVER_ALLOW_INSECURE_LOCAL`). **오케스트레이터 할 일:** `docs/capability-status.md:42`의 `ca-skeleton.grpc.enabled`·`ca-skeleton.grpc.allow-insecure-local`을 `.server.` 경로로. Wave 3-B(`app.*`)에서도 `app.grpc.server`처럼 벤더 prefix와 형제로 둬야 같은 충돌이 다시 안 생긴다. 커밋 `a498ad84` | +| N-9b | 해당 없음(코드 삭제) | P5 목록 밖이지만 D 삭제로 함께 닫힘: `validateAdvancedIsolation`과 `stableModuleDependencies` 파라미터 삭제(`GrpcStableBuildInvariant` 삭제에 따른 것). 커밋 `9b296c7c` | +| N-9c | 완료 | P5 목록 밖이지만 D에서 함께 닫힘: runtime 강제를 적던 문장을 build-time만으로 정정 `src/grpc/CLAUDE.md`(Stable 범위 절), `src/grpc-advanced/CLAUDE.md:18-19`. 커밋 `9b296c7c` | + +## 제거된 코드 +| 대상 | 경로 | 마지막으로 존재한 커밋 | 이유 | +|---|---|---|---| +| `GrpcStableModuleCatalog`(+`GrpcStableModuleCatalogTest`) | `src/grpc/grpc-core-api/src/main/java/dev/caskeleton/grpc/core/GrpcStableModuleCatalog.java` | `6d27356e` | leaf 목록을 core-api에 재기술(registry SSOT 중복), main 호출자 0 (S7-#4) | +| `GrpcStableBuildInvariant` | `src/grpc/grpc-core-api/src/main/java/dev/caskeleton/grpc/core/GrpcStableBuildInvariant.java` | `6d27356e` | 상수 반환·항상 빈 set으로만 불림. 격리는 `verifyCleanArchitectureDependencies`가 강제 (S7-#4, N-9b/c) | +| `GrpcPlatformStartupValidator.validateAdvancedIsolation` + `stableModuleDependencies` 파라미터 | `src/grpc/grpc-spring-boot-starter/src/main/java/dev/caskeleton/grpc/boot/GrpcPlatformStartupValidator.java` | `6d27356e` | 항상 `Set.of()`로 호출돼 항상 통과 (N-9b) | +| `GrpcAdvancedModuleGuard.requireStableStarterIsClean`, `advancedModules` | `src/grpc-advanced/grpc-advanced-bootstrap/src/main/java/dev/caskeleton/grpc/advanced/bootstrap/GrpcAdvancedModuleGuard.java` | `6d27356e` | 삭제된 catalog/invariant 위임, main 호출자 0 | +| `GrpcApplicationBoundaryRules`, `GrpcRawApiImportRule`, `GrpcServiceAdapterMarker`(+`GrpcApplicationBoundaryRulesTest`) | `src/grpc/grpc-server/src/main/java/dev/caskeleton/grpc/architecture/` | `6d27356e` | 문자열로 ArchUnit 흉내, 자기 테스트의 합성 입력만 검사. 경계 규칙은 app-bootstrap ArchUnit이 검사 | +| `GrpcKotlinCompatibilityGate`, `GrpcKotlinProfile` | `src/grpc-advanced/grpc-advanced-compat/src/main/java/dev/caskeleton/grpc/advanced/kotlin/` | `6d27356e` | `supportableHere()` 상수 false, main 호출자 0 | +| `GrpcWebCompatibilityGate` | `src/grpc-advanced/grpc-advanced-compat/src/main/java/dev/caskeleton/grpc/advanced/web/GrpcWebCompatibilityGate.java` | `6d27356e` | 상수 메서드 + main 호출자 0(`GrpcWebRpcSupport.require`가 같은 규칙) | +| `GrpcServletStartupValidator`, `GrpcServletCapabilityMatrix`, `GrpcServletCompatibilityProfile`(+`GrpcServletStartupValidatorTest`) | `src/grpc-advanced/grpc-advanced-compat/src/main/java/dev/caskeleton/grpc/advanced/servlet/` | `6d27356e` | Servlet 전송 코드 없이 상수 matrix·gate만 있던 패키지, main 호출자 0 | +| `GrpcEdition2024Gate`, `GrpcEdition2026Guard` | `src/grpc-advanced/grpc-advanced-edition/src/main/java/dev/caskeleton/grpc/advanced/edition/` | `6d27356e` | 상수 반환 gate·무조건 throw guard, main 호출자 0 | +| `GrpcResolverSafetyPolicy.acceptAfterClose`, `mayCarryBusinessMetadata`; `CREDENTIAL_SHAPED` 정규식 | `src/grpc-advanced/grpc-advanced-resilience/src/main/java/dev/caskeleton/grpc/advanced/discovery/GrpcResolverSafetyPolicy.java` | `6d27356e` | 상수 메서드(S7-#4) / 부분일치 정규식이 정상 키를 거부(N-4, W1 커밋) | +| `GrpcXdsStartupGuard` + 테스트 리소스 `xds/bootstrap.json` | `src/grpc-advanced/grpc-advanced-resilience/src/main/java/dev/caskeleton/grpc/advanced/xds/GrpcXdsStartupGuard.java` | `6d27356e` | 상수 메서드 포함 guard, main 호출자 0 | +| `GrpcAdvancedInfrastructureTestkit` | `src/grpc-advanced/grpc-advanced-diagnostics/src/main/java/dev/caskeleton/grpc/advanced/diagnostics/GrpcAdvancedInfrastructureTestkit.java` | `6d27356e` | capability별 인프라 목록 상수, main 호출자 0 (문서 표로 대체) | + +## 새로 발견한 결함 +- `P5-new-1` — `src/grpc-advanced/grpc-advanced-compat/src/main/resources/envoy/envoy.yaml:37`(virtual host `cors`): Envoy v1.31 validate가 `VirtualHost.cors`를 deprecated("will be removed soon")로 경고한다. per-filter `typed_per_filter_config`의 `CorsPolicy`로 옮겨야 한다. 안 고침(N-8d가 이 파일을 W3에서 옮길 때 같이). +- `P5-new-2` — `src/grpc/grpc-core-api/src/main/java/dev/caskeleton/grpc/core/GrpcMethodName.java`: `parse`는 전체 이름을 256자로 제한하지만 생성자는 service·method를 각각 256자로만 제한해 canonical이 최대 513자가 된다. ledger 쪽은 N-11b에서 막았지만 타입 자체의 두 경로가 다르다. 안 고침. +- `P5-new-3` — `src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/security/GrpcCredentialRotationManager.java:125` `completeDrain()`이 인자 없이 "지금 draining인 것"을 지워서, 그 사이 새 rotation이 시작한 drain(방금 교체된 세대)을 일찍 끝낼 수 있다. 경합 자체(현재 세대 되돌림)는 N-5b로 고쳤고, 이건 API 문제(`completeDrain(generation)`)라 안 고침. +- `P5-new-4` — `src/grpc-advanced/grpc-advanced-{resilience,compat,edition,streaming}/build.gradle`: `api project(':grpc-advanced:grpc-advanced-bootstrap')`를 main이 쓰지 않는다(resilience는 `GrpcXdsStartupGuard` 삭제로 새로 0, 나머지 셋은 원래 0). build 줄과 registry edge 정리는 W3 구조 작업. 안 고침. diff --git a/docs/reviews/2026-09-25-review-followup-results/P6.md b/docs/reviews/2026-09-25-review-followup-results/P6.md new file mode 100644 index 00000000..ed7267b4 --- /dev/null +++ b/docs/reviews/2026-09-25-review-followup-results/P6.md @@ -0,0 +1,39 @@ +# P6 결과 — Redis (`adapter:outbound:redis-runtime`, `adapter:outbound:redis-sdk`, `adapter:outbound:cache-redis`) + +worktree 브랜치 `worktree-agent-a6ab0657d876ae6b9`. 커밋: `22f28a3e`(W1), `5761314d`(W2). D 없음. + +## 행 결과 +| ID | 결과 | 근거 | +|---|---|---| +| NEW-5a | 완료 | W1 `22f28a3e`. `infra/redis-sdk/acl/application-advanced.acl:1`, `infra/redis-sdk/acl/all-accounts.acl:3`에 `+time` 추가(`admin-readonly`는 이미 있음). probe가 `redis.call('TIME')`을 실제 실행: `cache-redis/.../capability/RedisSemanticScriptAclProbe.java:29-38`. 단위 `RedisSemanticScriptAclProbeTest.anAccountDeniedACommandTheScriptsCallFailsStartup[TIME]` FAIL(`Expecting actual not to be null`)→PASS. 실제 Redis `LiveRedisSemanticScriptAclProbeTest.theAdvancedAccountPassesTheStartupProbe`: 새 probe + 옛 ACL에서 FAIL(`ERR ACL failure in script: User ca-skeleton-application-advanced has no permissions to run the 'time' command`) → ACL 수정 후 PASS. 이 클래스를 `cache-redis/build.gradle` `redisTopologyLane` standalone·cluster 필수 클래스에 등록. `infra/redis-sdk/acl/README.md`에 `+time` 이유 기록 | +| G-1b | 완료 | NEW-5c와 같은 수정(아래) | +| NEW-5c | 완료 | 멱등성 `RedisIdempotencyStoreAdapter.java:132,258,319,356,505`, lease `RedisDistributedLeaseAdapter.java:175,239,368,409`에 `catch (RedisOperationException)` + `!metadata().ambiguousExecution()` → `Unavailable`/`UNAVAILABLE`(lease는 `UNAVAILABLE_BEFORE_SEND`, renew/release는 handle을 ACTIVE로 유지). 테스트: `RedisIdempotencyStoreAdapterTest.aSaturatedScriptLaneRefusesTheClaimAsUnavailable`(FAIL `Indeterminate[...] to be an instance of Unavailable`→PASS), `aSaturatedScriptLaneRefusesOwnerTransitionsAsUnavailable`[markExecutionStarted/renew/complete/markFailed/releaseBeforeExecution](FAIL `expected: UNAVAILABLE but was: INDETERMINATE`→PASS), `RedisDistributedLeaseAdapterTest.aSaturatedScriptLaneRefusesAcquireBeforeSend`/`aSaturatedScriptLaneRefusesInspectBeforeSend`/`aRenewRefusedBeforeSendLeavesTheHandleActive`/`aReleaseRefusedBeforeSendLeavesTheHandleActive`(FAIL `expected: Unavailable[category=UNAVAILABLE_BEFORE_SEND] but was: Indeterminate`→PASS). 현황표 수정 방향의 테스트 제안(`runtime(false)`)은 틀렸다: 그 경우 EVALSHA가 서버까지 가서 NOPERM으로 거부되므로 not-sent가 아니다. 대신 SCRIPT lane을 포화시킨 owner(`RedisRuntimeOwner.borrow`가 `RedisCommandRejectedException`)로 재현했다. openLane 실패 같은 타입 없는 예외는 기존대로 Indeterminate(기존 `anUnreachableRedisIsIndeterminate` 유지) | +| S3-#4a | 완료 | 멱등성·lease는 NEW-5c 수정. cache는 현황표 근거("lane 거절도 Indeterminate")가 사실과 다름: cache는 이미 lane 거절을 `DEGRADED_UNAVAILABLE`(=안 보냄)로 돌려준다. 빠진 쪽은 반대 방향이었다 — 보낸 뒤 응답을 잃은 쓰기도 `DEGRADED_UNAVAILABLE`였다. `RedisCacheRegionAdapter.java:241,294,314,328`에 `sent` 플래그를 두어 쓰기 명령을 보낸 뒤의 실패는 `INDETERMINATE`, 그 전(lane 거절·연결·generation 조회)은 `DEGRADED_UNAVAILABLE`. 테스트 `RedisCacheRegionAdapterTest.aWriteWhoseReplyWasLostIsIndeterminate`/`anInvalidationWhoseReplyWasLostIsIndeterminate`/`aRegionInvalidationWhoseReplyWasLostIsIndeterminate` FAIL(`expected: INDETERMINATE but was: DEGRADED_UNAVAILABLE`)→PASS, 가드 `aWriteThatFailedBeforeItsSetWasSentDegrades` PASS | +| G-1c | 완료 | `redis-runtime/.../config/RedisHealthContributor.java:108`: borrow 거부(`RedisCommandRejectedException`)는 owner가 OPEN이면 `saturated`(reachable=true, UP), 아니면 `shutting-down`. `RedisHealthContributorTest.aSaturatedLaneIsLoadNotAnOutage` FAIL(`[false, "unreachable"]` ≠ `[true, "saturated"]`)→PASS. 트레이드오프(Redis가 멈춰 lane이 계속 가득 차면 saturated로 보임)는 클래스 javadoc에 기록 — 해당 요청은 timeout 후 fail-closed | +| G-2a | 완료 | `RateLimitScripts.java:55`(fixed-window `start`/`count` 두 필드 덮어쓰기), `:90`(sliding-counter `start`/`cur`/`prev` 회전), `:36-44` 주석을 실제 동작(히트마다 PEXPIRE, 상태 크기 고정)으로 수정. in-memory fake(`redis-runtime` testFixtures `InMemoryRedisCommandGateway` fixedWindow/slidingCounter)도 같은 레이아웃으로. 실제 Redis `LiveRedisSemanticPortsTest.windowCounterStateDoesNotGrowAcrossSkippedWindows`[FIXED_WINDOW, SLIDING_COUNTER] FAIL(`expected: 1L but was: 4L`)→PASS. 배포 시 기존 per-window 필드 키는 카운터가 한 번 리셋되고 옛 필드는 늘지 않은 채 TTL로 사라짐 | +| G-3a | 완료 | `RedisDistributedLeaseAdapter.java:169`: status 2 replay handle은 `observedValidityOf(reply.remainingMillis())`. `RedisDistributedLeaseAdapterTest.aReplayedAcquireKeepsOnlyTheServersRemainingTtl` FAIL(`30S to be less than or equal to 10S`)→PASS. 소유자 결정 8대로 lease 포트 유지 | +| G-3b | 완료 | `RedisDistributedLeaseAdapter.java:148`(tryAcquire), `:341`(renew): `localValidityOf`를 `owner.borrow` 전에 호출, IAE는 호출자에게 전파. `aTtlWithinTheDriftBudgetIsRejectedBeforeReachingRedis`·`aRenewTtlWithinTheDriftBudgetIsRejectedBeforeReachingRedis`(FAIL `Expecting actual not to be null`→PASS), `aTtlWithinTheDriftBudgetLeavesTheResourceFree`(FAIL: `Owned[...]` to be an instance of `Absent`→PASS) | +| G-9a | 완료 | `RedisSemanticFailureLogger.java:28,58`: once-per-JVM `Set` → key별 마지막 WARN 시각 맵, `WARN_INTERVAL`(1분)마다 다시 WARN. 테스트용 package-private `report(..., nowNanos)`. `RedisSemanticFailureLoggerTest.aContinuingFailureWarnsAgainOnceTheWindowHasPassed` FAIL(`Expected size: 2 but was: 1`)→PASS | +| G-9b | 완료 | `RedisSemanticFailureLogger.java:39`: `ExecutionException`/`CompletionException` cause를 풀어 기록. `aWrappedFailureIsReportedByItsCause` FAIL(`expected "IllegalStateException" but was "ExecutionException"`)→PASS | +| G-10a | 완료 | `RedisSemanticScriptAclProbe.java:29-38`: probe key에서 `TIME`→`HSET`→`PEXPIRE`→`HGET`→`DEL`을 실행하고 읽은 값이 쓴 값과 같을 때만 `{1}`. `anAccountDeniedACommandTheScriptsCallFailsStartup`[HSET/PEXPIRE/HGET/DEL] FAIL→PASS. 실제 Redis standalone·cluster에서 `LiveRedisSemanticScriptAclProbeTest` 2건 PASS. 테스트 ACL `+time`은 NEW-5a(W1)에서 추가 | +| G-10b | 완료 | `RedisCorrectnessRoles.java:71` `anyScriptRoleSelected`(idempotency/rate-limit/lease), `RedisSdkAutoConfiguration.java:296`: 스크립트 role이 선택되면 `redisRequired`가 SCRIPT lane에서 `SCRIPT LOAD`+`EVALSHA`(`return 1`, key `:probe:{health}:script`)도 확인(`RedisHealthContributor.java:92`). 실제 Redis `LiveRedisCompositionTest.aBrokenAdvancedAccountTakesRequiredRedisDown` FAIL(`expected: DOWN but was: UP`)→PASS, `aWorkingAdvancedAccountKeepsRequiredRedisUp` PASS. 단위 `RedisHealthContributorTest.aScriptLaneItsAccountCannotRunIsUnreachable` PASS | +| S6-#6b | 완료 | 두 키 모두 읽히고 있었다(web `EdgeRateLimitTransportSettings`가 `app.rate-limit.*`, cache-redis `RedisRateLimitConfig`가 `ca-skeleton.capabilities.rate-limit.default-policy-id`). 소유자 결정 16(`app.*` 통일)에 맞춰 `app.rate-limit.default-policy-id` 하나만 남김: `cache-redis.yml:65` 줄과 `RedisCapabilitySettings.RateLimit.defaultPolicyId` 삭제, `RedisRateLimitConfig.java:34,60`이 `app.rate-limit.default-policy-id`로 검증. env 키 `APP_RATE_LIMIT_DEFAULT_POLICY_ID`는 그대로(`env-keys.yaml`·`.env.example` 변경 없음). `RedisCapabilityCompositionTest.aDefaultPolicyTheLimiterDoesNotHaveIsRefusedAtStartup` FAIL(`Expecting actual not to be null`)→PASS | +| NEW-5b | 완료 | `LiveRedisSemanticPortsTest.java:193`: token-bucket adapter 시계 `Clock.offset(+1h)` → `Clock.systemUTC()`. `tokenBucketWithNonDivisibleRefillUsesIntegerExpiry` FAIL(W1 후에도 `AssertionError at :194`)→PASS. 기존 실패 4건(`theIdempotencyStoreClaimsOnceUnderTheAdvancedAccount`, `idempotencyLeaseExpiryUsesRedisTimeAcrossSkewedCallers`, `theRateLimiterEnforcesUnderTheAdvancedAccount`, `tokenBucketWithNonDivisibleRefillUsesIntegerExpiry`) 모두 PASS: 앞의 3건은 NEW-5a ACL, 마지막은 NEW-5b | + +집계: 완료 14 / 해당 없음 0 / 보류 0 / 남음 0. + +### 검증 (worktree, `--max-workers=2`) +- `:adapter:outbound:redis-runtime:check :adapter:outbound:redis-sdk:check :adapter:outbound:cache-redis:check` — BUILD SUCCESSFUL. test: runtime 49/49, sdk 312/312, cache-redis 100/100. +- `redisTopologyTest` standalone(redis 7.4, 새로 띄운 컨테이너, ACL 파일 기동 시 로드): runtime 7/7, sdk 14/14, cache-redis 12/12(`LiveRedisSemanticPortsTest` 10, `LiveRedisSemanticScriptAclProbeTest` 2). 시작 전 기준선: cache-redis 8건 중 4건 실패. +- `redisTopologyTest` cluster(infra/redis-sdk/cluster, 7100): runtime 7/7, sdk 18/18, cache-redis 12/12. +- `architectureCheck :app-bootstrap:verifyEnvKeys` — BUILD SUCCESSFUL. +- sentinel·tls lane은 이 머신에서 실행하지 않음(sentinel은 host network 다중 노드, tls는 cache-redis가 선언하지 않는 lane). `LiveRedisCompositionTest`의 새 2건은 sentinel lane에도 태그돼 있다. + +## 제거된 코드 +| 대상 | 경로 | 마지막으로 존재한 커밋 | 이유 | +|---|---|---|---| +| 설정 키 `ca-skeleton.capabilities.rate-limit.default-policy-id` (+ `RedisCapabilitySettings.RateLimit.defaultPolicyId` getter/setter) | `src/adapter/outbound/cache-redis/src/main/resources/config/module-defaults/cache-redis.yml`, `src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/capability/RedisCapabilitySettings.java` | `6d27356e` | S6-#6b: 같은 env 키에 두 설정 키가 묶여 있었다. `app.rate-limit.default-policy-id` 하나로 통일 | + +## 새로 발견한 결함 +- `P6-new-1` (고침, W2): `src/adapter/outbound/cache-redis/README.md` 「Useful focused checks」가 `./gradlew :app-bootstrap:test --tests '*RedisSemanticScriptAclProbeTest'`를 안내했지만 그 테스트는 cache-redis leaf에 있다. `:adapter:outbound:cache-redis:test`로 수정. 같은 README의 probe 설명(`return {1}`)도 현재 동작으로 갱신. +- `P6-new-2` (미수정, 판단 필요): `IdempotencyExecutor`(application-core)는 `complete`가 `UNAVAILABLE`이면 곧바로 `IdempotencyUnavailableException`을 던진다(`IdempotencyExecutor.java:228`). 이번 수정으로 SCRIPT lane 포화 시 complete가 `INDETERMINATE`(재조정 경로) 대신 `UNAVAILABLE`을 받으므로, 효과는 이미 일어났는데 레코드는 EXECUTING으로 남고 호출자는 unavailable 오류를 받는다. 포트 의미상 `UNAVAILABLE`(아무것도 안 바뀜)이 맞는 분류이고, 포화 상태에서는 재조정 inspect도 같은 lane이라 실패하므로 결과는 이전과 사실상 같다. executor가 complete `UNAVAILABLE`을 재시도/재조정할지는 application-core 정책 결정 — 승인자: 저장소 소유자 결정 필요. diff --git a/docs/reviews/2026-09-25-review-followup-results/P7.md b/docs/reviews/2026-09-25-review-followup-results/P7.md new file mode 100644 index 00000000..b2efe92b --- /dev/null +++ b/docs/reviews/2026-09-25-review-followup-results/P7.md @@ -0,0 +1,33 @@ +## 행 결과 +| ID | 결과 | 근거 | +|---|---|---| +| A-1a | 완료 | `FailOpenDependencyLoggerTest.failureLogKeepsOnlyTheExceptionTypeAndDropsTheRecipientAndWebhookUrlInItsMessage` FAIL→PASS (FAIL: `error="RuntimeException: 550 rejected alice@example.com via https://hooks.slack.com/services/T000/B000/XXXX"`는 `error="RuntimeException"`를 포함하지 않음). `src/adapter/outbound/support/src/main/java/dev/caskeleton/adapter/outbound/support/FailOpenDependencyLogger.java:40-51` — `error="{}"`에 `getSimpleName()`만 넣음. 커밋 `9a05d686` (W1) | +| A-1b | 완료 | 같은 테스트(`FailOpenDependencyLoggerTest.java:64-79`)가 예외 메시지에 `alice@example.com`·`https://hooks.slack.com/services/...`를 넣고 렌더된 로그에 둘 다 없음을 단언한다. 수정 전 FAIL 확인. 커밋 `9a05d686` | +| TEST-F-2c | 완료 | `RoutingNotifierTest.failingProvider`가 `"POST " + WEBHOOK_URL + " rejected " + n.recipient()`를 던진다(`RoutingNotifierTest.java:54,134`). `failOpenProviderLogsFailureWithProviderIdAndNoPii`·`piiNeverReachesLogOnSendFailure`가 수신자(`alice@example.com`)와 webhook URL이 로그에 없음을 단언한다. 수정 전 둘 다 FAIL(`not to contain: "alice@example.com"`) → PASS. `FailOpenDependencyLoggerTest` 쪽은 A-1b. 같은 결함이 있던 `NotificationAdapterTest.failingProvider`도 수신자를 메시지에 넣게 고쳤다(`NotificationAdapterTest.java:80`, 두 테스트 FAIL→PASS). 커밋 `9a05d686` | +| A-7a | 완료 | `ValidatedIntegrationEventTest.envelopeHashThatIsNotTheSha256OfTheEnvelopeBytesIsRefused` FAIL(`Expecting actual not to be null`)→PASS. DB 복원 경로는 `OutboxStoreAdapterTest.claimBatchRefusesACanonicalRowWhoseStoredEnvelopeHashIsNotItsBytesHash`가 PASS(`invalid canonical outbox metadata…` + 원인 메시지 확인). 코드: `src/application-core/src/main/java/dev/caskeleton/application/messaging/event/ValidatedIntegrationEvent.java:85-89`. 계산은 새로 만든 `Sha256.of(byte[])`(`src/application-core/src/main/java/dev/caskeleton/application/messaging/contract/Sha256.java:21-29`)로 한다. 임의 해시로 이벤트를 만들던 테스트 픽스처 5곳을 `Sha256.of(envelope)`로 바꿨다(application-core 1, messaging 2, persistence-jpa 2). 커밋 `3a39b6b5` (W2) | +| A-7b | 완료 | `ValidatedIntegrationEventTest.correlationIdLongerThan128CharactersIsRefused`·`causationIdLongerThan128CharactersIsRefused` FAIL→PASS. 경계값 테스트 `correlationIdOf128CharactersIsAccepted` PASS. `ValidatedIntegrationEvent.java:36-37` `{0,127}` — outbox `correlation_id`·`causation_id` varchar(128)과 같다. 커밋 `3a39b6b5` | +| A-8b | 완료 | `IdempotencyExecutorTest.aStoreFailureWhileRecordingTheActionFailureIsSuppressedUnderIt` 3건(thrown / effect unknown / retryable no effect) FAIL(`IllegalStateException: store unavailable … to refer to the same object`)→PASS. `src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyExecutor.java:197-219,273-289` — `markFailed` 호출 세 곳을 `recordFailure` 하나로 모았다. store 예외는 원래 예외에 `addSuppressed`로 붙는다. 현황표는 `preserveUnknown` 두 곳만 적었지만 `RetryableNoEffect` 경로도 같은 결함이라 함께 고쳤다. 커밋 `3a39b6b5` | +| X1-#1d | 남음 | 이유: E-5a·E-5b와 같은 변경이다(같은 SQL, `PostgreSqlOutboxClaimRepository`·`H2OutboxClaimRepository`, 새 migration). P9 W2가 이미 작업 중이다 — P9 worktree `agent-adbb19427d5d1740b`의 미커밋 `PostgreSqlOutboxClaimRepository`에 canonical `(tenant_scope, aggregate_type, aggregate_id)` + `(aggregate_sequence, event_index)` gate가 들어가 있다. 여기서 따로 구현하면 cherry-pick 충돌과 migration 번호 중복이 생긴다. 통합 때 P9의 E-5a·E-5b 결과로 함께 닫는다 | +| S4-#4a | 완료 | `SmtpProviderRuntimeAssemblerTest.theAssembledProfileDeclaresTheAdaptersOwnCapabilities` FAIL(`maxPayloadBytes=26214400` vs `25000000`)→PASS. assembler에 있던 capability 사본 `capabilities()`를 지우고, snapshot이 SES처럼 `adapter.capabilities()`를 쓴다: `src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/SmtpProviderRuntimeAssembler.java:108,115-134`. 값은 어댑터 쪽(25,000,000 B, 1일) 하나로 정했다. P3가 바꾼 테스트 `profile()` 줄은 건드리지 않았다. 커밋 `3a39b6b5` | +| S4-#14a | 완료 | `ProviderRuntimeStateTest.anOperatorStateDoesNotLetResumeClearAnAuthenticationFailure`(DISABLED·DRAINING) FAIL→PASS. `aLateAuthenticationFailureDoesNotOverwriteAnOperatorState`(DISABLED·DRAINING) FAIL(`expected DISABLED but was AUTHENTICATION_FAILED`)→PASS. 전이 규칙은 `ProviderRuntime.moveTo` 한 곳에 있다(`src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/dispatch/ProviderRuntime.java:229-255`). AUTH_FAILED는 rotation(새 runtime)으로만 벗어나고, DISABLED/DRAINING은 인증 실패로 덮이지 않는다. `markAuthenticationFailed`가 이제 적용 여부를 boolean으로 돌려준다. `RegistryProviderRuntimeControl.java:36`은 그 값을 그대로 반환한다(전에는 항상 true). notification API surface(type 목록)는 바뀌지 않았다(`verifyNotificationApiSurface` 통과). 커밋 `3a39b6b5` | +| L-7a | 완료 | 실제 배포 yml을 읽는 `ManagementActuatorSecurityContractTest.applicationYmlExposureIncludePinsAllowlistExactly`·`applicationYmlPinsShowDetailsNeverAndShutdownDisabled` FAIL→PASS. `ActuatorSecurityHttpTest.loggersEndpointIsNotExposed`(인증된 사용자도 404)·`actuatorLinksChallengeUnauthenticatedCallerWith401`(D3 401 확인 대상을 `/actuator` 링크로 옮김) PASS. 변경: `src/app-bootstrap/src/main/resources/config/observability.yml:36`(`include: health,prometheus,info`), `:44`(`show-details: never`), `ManagementSecurityConfig.java:33-37`(loggers `denyAll` 규칙 삭제). `src/app-bootstrap/README.md` 해당 절도 고쳤다. P10이 바꾼 `observability.yml:151` 줄은 건드리지 않았다. 커밋 `3a39b6b5` | +| L-8a | 완료 | `SampleSchemaOwnershipDefaultsTest.sampleDefaultsLeaveTheSchemaToFlyway[spring.flyway.out-of-order]` FAIL(`"true"`)→PASS. `src/sample-portfolio/src/main/resources/application.yml:45` `out-of-order: false`. 커밋 `3a39b6b5` | +| L-8b | 완료 | 같은 테스트 `[spring.jpa.hibernate.ddl-auto]` FAIL(`${APP_DATASOURCE_DDL_AUTO:update}`)→PASS. `application.yml:53` `${APP_DATASOURCE_DDL_AUTO:validate}` — env registry 기본값 `validate`와 같아졌다. env 키 변경은 없다(`verifyEnvKeys` 통과). 커밋 `3a39b6b5` | + +## 제거된 코드 +| 대상 | 경로 | 마지막으로 존재한 커밋 | 이유 | +|---|---|---|---| +| `SmtpProviderRuntimeAssembler.capabilities()` (SMTP capability 사본) | `src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/SmtpProviderRuntimeAssembler.java` | `6d27356e` | 어댑터 `capabilities()`와 값이 달랐다(S4-#4a). 이제 snapshot이 어댑터 값을 쓴다 | +| actuator `loggers` 노출과 `POST`/`DELETE /actuator/loggers/**` `denyAll` 규칙 | `src/app-bootstrap/src/main/resources/config/observability.yml`, `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/management/security/ManagementSecurityConfig.java` | `6d27356e` | actuator 체인에 인증 수단이 없어 어떤 자격증명으로도 도달할 수 없었다(L-7a) | +| `IdempotencyExecutor.preserveUnknown` | `src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyExecutor.java` | `6d27356e` | `recordFailure`로 대체했다(A-8b) | + +## 새로 발견한 결함 +- `P7-new-1` — `src/adapter/outbound/notification/src/test/java/dev/caskeleton/adapter/outbound/notification/core/NotificationAdapterTest.java:65-82`: `RoutingNotifierTest`와 같은, 절대 실패하지 않는 PII 단언이 있었다(`"provider-failure"`). 고쳤다(W1 `9a05d686`). +- `P7-new-2` — `IdempotencyExecutor`의 `RetryableNoEffect` 경로도 `markFailed`가 예외를 던지면 원래 action 예외를 잃었다. A-8b와 함께 고쳤다(W2 `3a39b6b5`). +- `P7-new-3` — `src/sample-portfolio/src/main/resources/db/sample-migration/V2__work_log.sql:26-27`의 주석은 "local dev relies on ddl-auto=update"라고 적혀 있다. 실제로는 `SamplePostgreSqlPersistenceConfig.sampleMigrationStrategy`가 sample schema를 migrate한다. 이미 적용된 migration이라 파일 바이트는 바꾸지 않았다(고치지 않음, Wave 5 문서 정리 후보). +- `P7-new-4`(다른 묶음과 겹치는 부분) — L-7a로 `show-details: never`가 되면 `show-components`도 따라서 never가 된다. 그러면 `/actuator/health` 응답에 component가 나오지 않는다. P13 `NEW-1a`(compose smoke가 켜진 capability를 확인)는 health component 대신 `info` 경로를 써야 한다. + +## 검증 (이 worktree, `--max-workers=2`) +- `:application-core:check :adapter:outbound:support:check :adapter:outbound:notification:check :adapter:outbound:messaging:check :adapter:outbound:persistence-jpa:check :app-bootstrap:check :sample-portfolio:check` — BUILD SUCCESSFUL. unit test: application-core 214, support 29, notification 399(skip 1), messaging 41, persistence-jpa 477, app-bootstrap 452(skip 5), sample-portfolio 285. 실패 0 +- `:app-bootstrap:integrationTest`(4) `:sample-portfolio:integrationTest`(49, Testcontainers PostgreSQL) `:sample-portfolio:systemTest`(3) `architectureCheck`(app-bootstrap architectureTest 180 포함) `:app-bootstrap:verifyEnvKeys` — BUILD SUCCESSFUL. 실패 0 +- `:adapter:outbound:notification:verifyNotificationApiSurface` — 통과 diff --git a/docs/reviews/2026-09-25-review-followup-results/P8.md b/docs/reviews/2026-09-25-review-followup-results/P8.md new file mode 100644 index 00000000..c31feaf2 --- /dev/null +++ b/docs/reviews/2026-09-25-review-followup-results/P8.md @@ -0,0 +1,31 @@ +## 행 결과 +| ID | 결과 | 근거 | +|---|---|---| +| J-8 | 완료 | `runtime/GraphQlDocumentAuthorizationHandlerTest.aProtectedFieldOnARenamedRootTypeIsStillDenied`(query·mutation 2건), `aContextWithoutASchemaIsRefusedInsteadOfGuessingRootNames` FAIL(`Expecting actual not to be null` — 거부 없이 통과) → PASS. root 이름을 `context.schema().getQueryType()/getMutationType()/getSubscriptionType()`에서 읽고, schema나 해당 root가 없으면 `IllegalStateException`(→ INTERNAL_ERROR, fail-closed). `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlDocumentAuthorizationHandler.java:68,87`. 커밋 `0392d8c9` | +| J-2 | 완료 | `cost/GraphQlFragmentReachabilityTest.typenameIsNotTreatedAsIntrospection`(3건) FAIL(`selectsIntrospection`이 true) → PASS, systemTest `runtime/GraphQlPlatformExecutionPathTest.typenameIsAnsweredWhenTheClientProfileForbidsIntrospection`(introspection 금지 profile + `{ _health __typename }`) FAIL(`GRAPHQL_DOCUMENT_SHAPE_REJECTED`/`INTROSPECTION` 에러) → PASS. `__schema`/`__type`만 차단. `.../cost/GraphQlDocumentShapeAnalyzer.java:50,221`. 커밋 `aa5f4d90` | +| J-3a | 완료 | `error/GraphQlExceptionResolverTest.aMaskedFailureIsLoggedOnceAtErrorWithItsExecutionId` FAIL(`Expected size: 1 but was: 0`) → PASS. 마스킹 분기에서 `graphql failure masked as INTERNAL_ERROR (executionId=…)` + 예외를 ERROR 한 번. 모든 경로가 이 분기를 거치게 된 것은 S5-#6a 수정 덕분. `.../error/GraphQlExceptionResolver.java:61`. 커밋 `aa5f4d90` | +| J-4a | 완료 | `runtime/GraphQlWireErrorMapperTest.dataLoaderFailuresKeepAPlatformCode`(2건) FAIL(`["INTERNAL_ERROR","INTERNAL"]`) → PASS. batch timeout → `REQUEST_TIMEOUT`/TIMEOUT, missing key → 새 platform code `GRAPHQL_BATCH_KEY_MISSING`/BUSINESS. `.../runtime/GraphQlPlatformRejectionMapper.java:106,113`, `.../error/GraphQlErrorCode.java:48,72`, `GraphQlErrorCodeCatalogTest` 갱신. Spring GraphQL `ExceptionResolversExceptionHandler`가 `CompletionException`을 벗겨 넘기는 것 확인(2.0.5 소스). 커밋 `aa5f4d90` | +| J-4b | 해당 없음(코드 삭제) | bridge 포화 경로(`GraphQlBlockingBridge`·`Schedulers.fromExecutor`)는 event loop 전용이라 D4(servlet 단일)에 맞춰 삭제. 남은 경로는 호출 스레드 inline(`Mono.fromCallable`)이라 예외가 그대로 mapper에 도달(J-4a 매핑 적용). 삭제 커밋 `6390bf89` | +| J-9a | 완료 | 재현됨. systemTest `runtime/GraphQlPlatformExecutionPathTest.aChunkedBodyOverTheRawCapIsRefusedWith413`(Content-Length 없는 chunked 200KB 본문) FAIL(`expected: 413 but was: 500`) → PASS. 원인: `FrameworkServlet`(spring-webmvc 7.0.9 `FrameworkServlet.java:1006-1008`)이 decoder 안에서 던진 unchecked `BodyTooLargeException`을 `ServletException("Request processing failed")`으로 감쌈. `IOException/ServletException/RuntimeException`을 잡아 cause chain(최대 16단계)에서 찾으면 413, 아니면 그대로 rethrow. `.../runtime/servlet/GraphQlRequestBodyLimitFilter.java:85,98`. 커밋 `aa5f4d90` | +| J-12 | 완료 | `autoconfigure/GraphQlDeploymentModeContractTest.aProductionModeRefusesTheAnonymousPrincipalResolver`(PRODUCTION_INTERNAL·PUBLIC) FAIL(`to have failed but context started successfully`) → PASS, `aProductionModeWithAnExplicitPolicyAndResolverStarts` PASS. 기본 `graphQlPrincipalResolver` bean이 production이면 `GraphQlPlatformConfigurationException`(mode 없으면 REQUIRED_MESSAGE). `.../autoconfigure/GraphQlPlatformAutoConfiguration.java:243`. 커밋 `aa5f4d90` | +| X2-P2-6b (J-12와 한 행) | 남음 | 이유: 나머지 수정 방향(`AuthorizationPrincipal`에 tenant 추가해 모든 inbound가 생성, gRPC `GrpcAuthenticationPolicy` boolean 교체, 가명을 `UserPrincipalPseudonymizerPort` 하나로)은 application-core·gRPC·graphql을 함께 바꾸는 공통 작업이라 Wave 3 3-D(tenant 값 타입)와 같이 해야 함. GraphQL 기본 Spring Security `Authentication` → principal resolver는 tenant를 어느 claim에서 읽을지 정해야 해서 이번에 만들지 않음(production은 이제 resolver 없이 기동 거부) | +| S5-#6a | 완료 | `runtime/GraphQlRequestStageErrorMappingTest.anApiErrorCarrierFromThePrincipalResolverKeepsItsCode`, `anApiErrorCarrierFromAPipelineStageKeepsItsCode` FAIL(`expected "TENANT_SUSPENDED" but was "INTERNAL_ERROR"`) → PASS. 두 테스트 모두 auto-configuration이 만든 bean으로 돌려 "세 곳이 mapper bean을 받는다"를 검증. `GraphQlWireErrorMapper.map(Throwable, ctx)`(플랫폼 거부 → ApiErrorCarrier → application 매핑) + `toGraphQlError`(carrier는 category로 classification) 하나로 interceptor·instrumentation·field resolver가 모두 이것을 씀. `.../runtime/GraphQlWireErrorMapper.java:61,79`, `GraphQlPlatformWebInterceptor.java:168`, `GraphQlPlatformInstrumentation.java:89`, `GraphQlDataFetcherExceptionResolver`, 주입 `GraphQlPlatformAutoConfiguration.java:357,413`. 호출자가 없어진 `GraphQlPlatformRejectionMapper.map` 삭제. 커밋 `aa5f4d90` | +| NEW-9a | 완료 | S5-#6a와 같은 결함, 같은 수정·같은 테스트. 수정 방향 중 category switch 3개(`GraphQlWireErrorMapper.category`·`clientMessage`, `GraphQlWireErrors.classificationOf`)를 EnumMap 표 하나로 합치는 일은 지시대로 하지 않음 — Wave 3 3-A(Category별 한국어 문구 표를 shared-contract에)에서 `clientMessage`가 그 표로 대체되므로 그때 함께. 커밋 `aa5f4d90` | +| S5-lead-3 | 남음 | 이유: 공통 tenant 값 타입(shared-contract/application-core)을 만들고 web·graphql(그리고 messaging·persistence·notification의 tenant 타입)이 담게 하는 일은 계획서 Wave 3 3-D 「tenant 값 타입」 공통 작업이고 web은 P10 범위. 이번에는 증상만 막음: GraphQL `TenantContext` 검증을 web과 같은 문법 `[A-Za-z0-9][A-Za-z0-9_.-]{0,63}`으로 맞춰 "한 전송만 통과하는 tenant"를 없앰. `context/GraphQlRequestContextTest.aTenantTheWebTransportRefusesIsRefusedHereToo`(4건) FAIL(`Expecting actual not to be null`) → PASS. `.../context/TenantContext.java:38`. 커밋 `aa5f4d90` | + +## 제거된 코드 +| 대상 | 경로 | 마지막으로 존재한 커밋 | 이유 | +|---|---|---|---| +| `GraphQlExecutionProfile`(BLOCKING_MVC·REACTIVE_WEBFLUX·MIXED_CONTROLLED), `GraphQlExecutionProfileException` | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/execution/` | `6d27356e` | D4: servlet 단일 스택이라 고를 프로파일이 없음 | +| `GraphQlRuntimeTransport`와 `GraphQlPlatformAutoConfiguration`의 `ServletRuntimeDetection`·`ReactiveRuntimeDetection`, `GraphQlPlatformRuntime.transport` | `.../graphql/autoconfigure/` | `6d27356e` | D4: 프로파일과 실행 서버 대조가 필요 없어짐 | +| `GraphQlBlockingBridge`, `GraphQlBlockingBridgeFullException`, `GraphQlBatchLoaderRegistrar`의 bridge·profile 인자, `GraphQlBlockingBridgeTest` | `.../graphql/runtime/`, `src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/runtime/` | `6d27356e` | D4: event loop 에서 blocking 작업을 빼내는 bridge. servlet 에서는 호출 스레드 inline 실행(J-4b 결함 경로) | +| 설정 `backend.graphql.execution-profile`(`APP_GRAPHQL_EXECUTION_PROFILE`), `backend.graphql.unbridged-blocking-resolvers`와 validator의 reactive 검사 | `GraphQlPlatformSettings.java`, `GraphQlPlatformStartupValidator.java`, `src/main/resources/config/graphql.yml`, `docs/registries/env-keys.yaml`, `src/.env.example` | `6d27356e` | D4: 동작할 수 없는 옵션은 키를 두지 않는다 | +| 테스트: `GraphQlTransportNeutralityTest`의 context 기반 프로파일 케이스 7개, `GraphQlBatchLoaderRegistrationTest` reactive·bridge 2건, `GraphQlPlatformStartupValidatorTest.aBlockingResolverWithoutABridgeCannotRunOnTheReactiveProfile` | `src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/` | `6d27356e` | 대상 코드 삭제 | +| `GraphQlPlatformRejectionMapper.map`(unknown → INTERNAL_ERROR 정적 메서드) | `.../graphql/runtime/GraphQlPlatformRejectionMapper.java` | `6d27356e` | 모든 경로가 `GraphQlWireErrorMapper.map`을 쓰게 되어 호출자 없음 (`mapFieldFailure`는 `map`으로 이름 변경) | + +## 새로 발견한 결함 +- `P8-new-1` (미수정): `GraphQlBatchLoadException`(per-key 실패, adopter가 준 `errorCode`)을 mapper가 모른다 → `INTERNAL_ERROR`로 가려지고 adopter code가 사라짐. `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/dataloader/GraphQlBatchResultMapper.java:131`, 매핑 없음 `.../runtime/GraphQlPlatformRejectionMapper.java`. 코드를 그대로 wire에 내보내도 되는지(검증되지 않은 adopter 문자열) 결정 후 `GraphQlErrorCode.of(...)`로 매핑. +- `P8-new-2` (미수정): instrumentation 이 platform context 없이 온 요청(= interceptor 미배선 설정 오류)을 `INTERNAL_ERROR`+`PLATFORM_CONTEXT`로 거부하지만 로그를 남기지 않아, 잘못 조립된 배포가 모든 요청을 조용히 실패시킨다. `.../runtime/GraphQlPlatformInstrumentation.java:65-70`. +- `P8-new-3` (고침, 문서): graphql `CLAUDE.md` 「Error mapping」 절이 없는 클래스 `GraphqlExceptionResolver`와 "비-carrier 예외는 null 반환"을 설명하고 있었음. 현재 경로(한 mapper, 마스킹+로그)로 고침. 커밋 `aa5f4d90`. +- `P8-new-4` (미수정, W5 문서): 이번 D 삭제 대상(`GraphQlRuntimeTransport`, `GraphQlExecutionProfile`, `GraphQlBlockingBridge`)을 설명하는 학습 문서가 남아 있음 — `docs/study/graphql-walkthrough.ko.md:157,461,871,1078`(결정 6 대상), `docs/graphql-superpowers-package/**`. +- 참고: brief가 적은 graphql reactive 잔재(`REACTIVE` 런타임 감지·`REACTIVE_WEBFLUX`)는 J-4b가 건드리는 bridge와 한 묶음이라 D 커밋 `6390bf89`에서 지웠다. diff --git a/docs/reviews/2026-09-25-review-followup-results/P9.md b/docs/reviews/2026-09-25-review-followup-results/P9.md new file mode 100644 index 00000000..b75dd824 --- /dev/null +++ b/docs/reviews/2026-09-25-review-followup-results/P9.md @@ -0,0 +1,43 @@ +## 행 결과 +| ID | 결과 | 근거 | +|---|---|---| +| E-10a | 완료 | `TenantAwareRepositoryGuardTest.openingAnAdminScopeRecordsItsReasonInTheAuditSink` FAIL(컴파일: "constructor TenantAwareRepositoryGuard ... cannot be applied", audit sink 없음)→PASS, `anAuditSinkThatFailsLeavesNoAdminScopeOpen` PASS. 생성자가 `Consumer` audit sink를 받고 scope를 열기 전에 사유를 기록: `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/experimental/tenant/TenantAwareRepositoryGuard.java:31,56`. PG `TenantColumnIsolationTest`(jpa-contract) 통과 | +| E-10c | 완료 | `SchemaMultiTenantConnectionProviderTest.aFailedResetAbortsTheConnectionSoThePoolCannotLendItOutWithTheTenantSchema` FAIL("WantedButNotInvoked: connection.abort")→PASS, `aFailedResetReachesTheCaller` PASS. reset 실패 시 `abort(Runnable::run)` 후 close, 예외 전파: `.../experimental/schema/SchemaMultiTenantConnectionProvider.java:60-74`. Hikari는 abort된 커넥션을 close 때 evict한다(javap로 `ProxyConnection`이 abort를 가로채지 않음 확인) | +| E-2b | 완료 | NEW-7a와 같은 결함·같은 수정. 아래 NEW-7a 행 참고 | +| E-3a | 완료 | `CanonicalOutboxAppendAdapterTest.appendOutsideACallerTransactionIsRefusedBeforeAnyWrite` FAIL("Expecting actual not to be null")→PASS. `.../outbox/CanonicalOutboxAppendAdapter.java:40-44` 첫 줄에 caller 트랜잭션 guard(형제 `OutboxStoreAdapter`와 같은 메시지) | +| E-4a | 완료 | 실제 PG `PostgreSqlInboxCutoffIntegrationTest.markAllReadLeavesAnUnreadArchivedItemArchived` FAIL(`[2, READ]` ≠ `[1, ARCHIVED]`)→PASS. 서브쿼리에 `AND state NOT IN ('ARCHIVED','EXPIRED','DELETED')`: `.../notification/platform/inbox/InboxItemJpaRepository.java:91-93`. 이 테스트 클래스는 SQL 사본을 실행하고 있어서(결함이 안 보였던 이유) repository `@Query` 값을 읽어 실행하도록 바꿈 | +| E-4b | 완료 | `InboxItemEntityTest.markReadLeavesAnItemThatLeftTheInboxWhereItIs` / `markSeen...` (ARCHIVED·EXPIRED·DELETED 각 3건) FAIL(`[true, READ]`/`[true, SEEN]`)→PASS. `.../inbox/InboxItemEntity.java` `leftTheInbox()` 가드 | +| E-5a | 완료 | 실제 PG `PostgreSqlOutboxClaimAndMaintenanceIntegrationTest.canonicalEventsSharingAnOccurredAtAreClaimedOneAtATimeInAggregateOrder` FAIL(3건 동시 claim)→PASS, H2 `H2ClaimSqlTest.claimsCanonicalEventsSharingAnOccurredAtOneAtATimeInAggregateOrder` PASS. canonical 쌍은 `(aggregate_sequence, event_index)`로 head 판정·정렬: `.../postgresql/PostgreSqlOutboxClaimRepository.java:25-50`, `.../h2/H2OutboxClaimRepository.java:26-47`. 인덱스 새 migration `V18__outbox_event_unpublished_aggregate_order.sql` + `applied-migrations.sha256` 1줄, `PostgreSqlMigrationIntegrationTest` 버전 목록에 18 추가. legacy row가 낀 쌍은 기존 `occurred_at` 비교 유지(`equalTimestampRowsAreClaimedTogetherLegacyFifoLimitationCharacterization` 그대로 통과) | +| E-5b | 완료 | 실제 PG `aDeadCanonicalRowOfAnotherTenantOrTypeDoesNotBlockTheSameAggregateId` FAIL(`[]`)→PASS. E-5a와 같은 SQL 변경(canonical 쌍은 tenant_scope·aggregate_type까지 같아야 같은 aggregate) | +| E-7 | 완료 | `OutboxStoreAdapterTest.claimBatchMovesAnUnreadableRowToDeadAndClaimsTheRestOfTheBatch` FAIL(IllegalStateException partial canonical)→PASS, 실제 PG `anUnreadableCanonicalRowDoesNotStopTheRestOfTheBatchFromBeingClaimed`·`anUnreadableCanonicalRowIsMovedToDeadByTheClaim` FAIL(projection mismatch 예외)→PASS. `.../outbox/OutboxStoreAdapter.java:84-110` 매핑 실패 row는 DEAD·lease 해제 후 배치에서 제외(legacy로 낮추지 않으므로 fail-closed 유지) | +| E-8a | 완료 | 실제 PG `countByStatusLeavesPublishedRowsUncounted` FAIL(`{PENDING=1, PUBLISHED=1}`)→PASS. `countGroupedByStatus`에 `where e.status <> 'PUBLISHED'`(`.../outbox/OutboxEventJpaRepository.java`), fake `InMemoryOutboxStore.countByStatus` 동일, 포트 문서 갱신, `OutboxMetrics`는 PUBLISHED 시리즈를 내보내지 않음(0 고정 시리즈 방지). lifecycle PG 테스트의 PUBLISHED 카운트 단언 3곳은 row 상태 직접 조회로 교체 | +| E-8b | 완료 | `OutboxReaperTest` 3건 FAIL(컴파일: `deletePublishedBatch` 없음)→PASS. native `DELETE … WHERE event_id IN (SELECT … LIMIT n)`(ctid 대신 PG·H2 공통 SQL)를 repository 메서드 `@Transactional`로 배치마다 커밋, 덜 찬 배치에서 종료: `.../outbox/OutboxEventJpaRepository.java:19-35`, `.../outbox/OutboxReaper.java`(배치 1,000, `ponytail:` 주석). 실제 PG `reaperDeletesOldPublishedRowsOutsideAnyCallerTransaction`, H2 `theReaperBatchDeleteRunsOnH2AndStopsAtItsLimit` PASS | +| S6-#3b | 완료 | 행동 보존 정리(FAIL→PASS 대상 아님): `OpenInViewSafetyValidator`(모든 profile 거부)를 정본으로 두고 `JpaDangerousConfigurationGuard`의 OSIV 분기·`OPEN_IN_VIEW_KEY` 삭제(`.../startup/JpaDangerousConfigurationGuard.java`), `JpaPlatformReport`는 validator 상수 사용. `OpenInViewSafetyValidatorTest.openInViewTrueFailsStartupUnderALocalConvenienceProfileToo` 추가(수정 전후 모두 PASS = guard의 local 예외가 죽은 코드였다는 증거). guard 테스트는 ddl-auto만 검사하도록 재작성. 학습 문서 `docs/study/postgresql-jpa-walkthrough.ko.md` 표 갱신 | +| NEW-7a | 완료 | application: `SubmitDurableOperationUseCaseTest.retryUnderTheSameOperationIdAppendsTheOutboxEventOnlyOnce` FAIL(`[false, 2]` ≠ `[true, 1]`)→PASS. 실제 PG 재현: `DurableOperationSubmissionOutboxIntegrationTest.retryUnderTheSameOperationIdLeavesThePublishedOutboxRowAlone` FAIL(`[false, [PENDING]]` — 재시도가 PUBLISHED row를 merge로 PENDING으로 되돌림 = 재발행)→PASS, `aSecondAppendOfTheSameEventIdIsRefusedByThePrimaryKeyInsteadOfOverwritingTheRow` FAIL(예외 없이 덮어씀)→PASS(`PersistenceFailureException` SQLState 23505). 수정: `submitIfAbsent`가 삽입 행 수 반환(`.../operation/DurableOperationJpaRepository.java:52`), `DurableOperationStorePort.submit` → `DurableOperationSubmitResult(operation, created)`(새 파일 `application-core/.../operation/DurableOperationSubmitResult.java`), use case는 `created`일 때만 append(`SubmitDurableOperationUseCase.java:99-104`), `OutboxEventEntity implements Persistable`(`isNew`, `@PostLoad/@PostPersist`). `DurableOperationStoreContract`에 `retryUnderTheSameOperationIdReturnsTheOperationAsNotCreated` 추가 — fake와 PG adapter(`DurableOperationStoreAdapterContractTest`, jpa-contract) 모두 통과 | +| NEW-7b | 완료 | 소유자 결정 15. `adapter:inbound:web` `operation/DurableOperationController`: `POST /operations`(202 + Location, Envelope), `GET /operations/{id}`, `DELETE /operations/{id}`(202). 컨트롤러는 Submit/Get/Cancel 유스케이스만 호출, 인가는 유스케이스 `@RequiresPermission`, owner·tenant 판정은 유스케이스의 `DurableOperationAccessPolicy`(남의 것 = 없는 것 = 404 `OPERATION_NOT_FOUND`). 조립은 `app-bootstrap/.../autoconfigure/operation/DurableOperationConfig`(기존 `OutboxConfig` 패턴, operation store·outbox append·TransactionPort bean이 있을 때만 켜짐, `AutoConfiguration.imports` 등록). 테스트: web slice `DurableOperationControllerTest` 10건, 실제 PG 왕복 `DurableOperationCompositionIntegrationTest` 5건(프록시된 `@RequiresPermission` 403 포함, `integrationTest` lane `requires`에 추가). 새 경로는 인증 필요 경로라 공개 경로 스냅숏은 바뀌지 않음(`verifyPublicPathSnapshot` 통과). `security.yml`에 `operation-submit: operation:submit,operation:cancel`, dev Keycloak realm에 같은 client role 추가. 설계 선택(결정 필요 시 뒤집을 수 있음): id는 서버가 UUID로 발급, 재제출은 payload fingerprint로 dedupe, outbox event type은 `OperationCommand.SUBMITTED_EVENT_TYPE` 하나(클라이언트가 임의 event type을 broker에 싣지 못하게), TTL `OperationCommand.DEFAULT_TIME_TO_LIVE`(1일), tenant는 null(웹 운영 경로에 tenant 해석이 없음) | + +## 제거된 코드 +| 대상 | 경로 | 마지막으로 존재한 커밋 | 이유 | +|---|---|---|---| +| `JpaDangerousConfigurationGuard`의 OSIV 검사 분기와 `OPEN_IN_VIEW_KEY` 상수 | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/startup/JpaDangerousConfigurationGuard.java` | `6d27356e` | S6-#3b. `OpenInViewSafetyValidator`가 모든 profile에서 먼저 거부하므로 local 예외가 도달 불가능한 죽은 코드 | +| `OutboxEventJpaRepository.deletePublishedBefore`(무제한 단일 DELETE) | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/outbox/OutboxEventJpaRepository.java` | `6d27356e` | E-8b. 배치 삭제 `deletePublishedBatch`로 교체 | + +## 새로 발견한 결함 +- P9-new-1: `InboxItemEntity.archive()`가 EXPIRED·DELETED 항목도 ARCHIVED로 바꾼다(`src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/notification/platform/inbox/InboxItemEntity.java` `archive`). terminal 상태를 되돌리는 같은 종류의 결함. 고치지 않음(E-4b 범위 밖). +- P9-new-2: `PostgreSqlInboxCutoffIntegrationTest`가 repository의 SQL이 아니라 테스트 안의 사본을 실행하고 있어 E-4a가 PG lane에서 보이지 않았다. 고침(repository `@Query`를 읽어 실행). +- P9-new-3: 같은 operationId를 다른 요청(다른 scope)으로 재사용하면 fake(`InMemoryDurableOperationStore`)는 조용히 덮어쓰고 PG adapter는 PK 위반으로 실패한다 — fake/adapter 불일치. HTTP 경로는 id를 서버가 발급해 영향 없음. 고치지 않음. +- P9-new-4: `WebMvcRequestContextHolder.store(...)`를 부르는 운영 코드가 없어 `WebRequestContext`를 파라미터로 받는 컨트롤러는 항상 `IllegalStateException`으로 실패한다(`src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/mvc/context/WebMvcRequestContextArgumentResolver.java:40`). operation 컨트롤러는 그래서 `@AuthenticationPrincipal`을 쓴다. 고치지 않음(P10 영역). +- P9-new-5: 웹 운영 경로에 tenant 해석이 없다(`TenantContext.resolved` 호출자 없음). durable operation HTTP는 tenant를 null로 넘긴다. 결함이라기보다 미구현 — 기록만. + +## 커밋·검증 +- 브랜치 `worktree-agent-adbb19427d5d1740b`: `21bcba8d` W1, `3152e50b` W2 +- `:application-core:check` `:adapter:outbound:persistence-jpa:check` `:adapter:inbound:web:check` `:app-bootstrap:check` 통과 (unit: application-core 209, persistence-jpa 490, web 234 + webSecurityBoundaryTest 13, app-bootstrap 454(skip 5, 기존) + systemTest 8) +- 실제 PostgreSQL: jpaPlatformContractTest 217, jpaPlatformMigrationTest 45, jpaPlatformFailureTest 3, jpaPlatformQueryPlanTest 3, jpaPlatformSecurityTest 10, jpaPlatformPoolContractTest 8, postgresqlLegacyOutboxRowLifecycle 10, postgresqlLegacyOutboxAppendTransactional 2, postgresqlLegacyOutboxConcurrentRelay 4, postgresqlMigration 5, postgresqlIdempotency 8 — 실패 0, skip 0 +- `:app-bootstrap:integrationTest` 9/9 (새 `DurableOperationCompositionIntegrationTest` 5 포함) +- `architectureCheck`(architectureTest 180), `verifyPublicPathSnapshot`, `:app-bootstrap:verifyEnvKeys`, `verifyDependencyLocks` 통과 + +## 기타 +- 추가한 migration 버전: `postgresql/V18__outbox_event_unpublished_aggregate_order.sql` (다른 묶음과 번호 충돌 시 오케스트레이터 조정 필요, `applied-migrations.sha256`와 `PostgreSqlMigrationIntegrationTest` 버전 목록도 함께). +- `SpringTransactionPort`는 건드리지 않음. +- 규칙 이탈 1건: W1에서 `TenantAwareRepositoryGuard.java`를 한 번 셸(python heredoc)로 편집했다. 결과는 Read로 확인했고 이후 편집은 전부 Edit/Write 도구로 했다. +- 의존성: `adapter:inbound:web` testImplementation에 `testFixtures(project(':application-core'))` 추가. `resolveAndLockAll --write-locks` 결과 lockfile 변화 없음. diff --git a/docs/reviews/2026-09-25-review-followup-status.md b/docs/reviews/2026-09-25-review-followup-status.md index 08c48982..25192ae9 100644 --- a/docs/reviews/2026-09-25-review-followup-status.md +++ b/docs/reviews/2026-09-25-review-followup-status.md @@ -47,6 +47,18 @@ | 19 | 의존성 checksum 검증 | 추가 안 함 → 보류 | O-5a | | 20 | API surface 검사 단계 | PR(`check`)로 올림 | NEW-13d | +Wave 1–2 구현 중 나온 질문에 대해 받은 7건(2026-09-28): + +| # | 질문 | 결정 | 해당 행 | +|---|---|---|---| +| 21 | 알림 route의 provider profile이 사라진 경우 | 일반 재시도 정책(backoff·최대 횟수) 후 FAILED | P3-new-5 | +| 22 | sample 포스터 업로드 abort·reconcile 경합 | 먼저 끝난 쪽이 이김(이미 게시됐으면 abort는 409) | P2-new-2 | +| 23 | Dynamic Target cross-origin redirect의 호출자 헤더 | 전부 제거, 안전한 헤더만 유지 | P11-new-4 | +| 24 | 멱등성 `complete`가 연결 포화로 UNAVAILABLE | 현재 동작 유지 + 문서화 | P6-new-2 | +| 25 | GraphQL DataLoader 키 실패의 adopter 에러 코드 | 등록된 `ApiErrorCode`만 노출 | P8-new-1 | +| 26 | durable operation HTTP 설계 4개(서버 생성 id, payload 지문으로 재제출 판정, 고정 event type, 1일 보존) | 그대로 승인 | NEW-7b | +| 27 | main build가 plugin으로 부르는 build-logic·build-tools 의존성 잠금 | 잠그지 않음 + 문서화 → 보류 | P13-new-1 | + 기존 원칙에서 바로 따라 나와 에이전트가 정한 것(소유자가 뒤집을 수 있음): - M-2b: Kafka 주소는 `app.messaging.brokers..bootstrap-servers` 하나(AGENTS.md capability 기준 4 "prefix 하나"). @@ -67,30 +79,30 @@ ## 요약 +2026-09-28, Wave 1–2 통합 후. 괄호는 시작 시점(2026-09-25) 값. + | 상태 | 행 수 | |---|---| -| 완료 | 161 | -| 해당 없음 | 106 | -| 남음 | 544 | -| 보류 | 1 | -| 합계 | 812 (중복 병합 16행) | +| 완료 | 370 (161) | +| 해당 없음 | 112 (106) | +| 남음 | 375 (544) | +| 보류 | 2 (1) | +| 합계 | 859 (812 + 후속 발견 47) | | Wave (남음) | 행 수 | |---|---| -| W1 | 55 | -| W2 | 139 | +| W1 | 4 | +| W2 | 17 | | W3 | 196 | -| W4 | 56 | -| W5 | 98 | - - +| W4 | 57 | +| W5 | 101 | ## 1차 A Core · L Composition/sample | ID | 심각도 | 요약 | 상태 | 근거 | Wave | 수정 방향 | |---|---|---|---|---|---|---| -| A-1a | Required | `FailOpenDependencyLogger.logFailure`가 `cause.getMessage()`를 WARN 로그에 그대로 남김(수신자 주소·webhook URL 누출 가능, Javadoc은 "PII cannot reach the log") | 남음 | `src/adapter/outbound/support/src/main/java/dev/caskeleton/adapter/outbound/support/FailOpenDependencyLogger.java:39-47`(`:47` `cause.getMessage()`), Javadoc `:10-11`. 호출자 `src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/core/FailOpenNotificationProvider.java:42` | W1 | `FailOpenDependencyLogger.java:41,47`에서 `getMessage()`를 빼고 `error="{}"`에 예외 클래스 simple name만 남긴다 | -| A-1b | Required | PII 누출 테스트가 메시지 `"connection refused"`로 `@gmail.com` 부재만 확인 → 아무것도 증명 못 함 | 남음 | `src/adapter/outbound/support/src/test/java/dev/caskeleton/adapter/outbound/support/FailOpenDependencyLoggerTest.java:65-72` | W4 | 같은 테스트에서 예외 메시지에 `alice@example.com`, `https://hooks.slack.com/services/...`를 넣고 렌더된 로그에 둘 다 없음을 단언 | +| A-1a | Required | `FailOpenDependencyLogger.logFailure`가 `cause.getMessage()`를 WARN 로그에 그대로 남김(수신자 주소·webhook URL 누출 가능, Javadoc은 "PII cannot reach the log") | 완료 | Wave 1–2 P7 (fcddab7e·Wave 2 커밋): `FailOpenDependencyLoggerTest.failureLogKeepsOnlyTheExceptionTypeAndDropsTheRecipientAndWebhookUrlInItsMessage` FAIL→PASS (FAIL: `error="RuntimeException: 550 rejected alice@example.com via https://hooks.slack.com/services/T000/B000/XXXX"`는 `error="RuntimeException"`를 포함하지 않음). `src/adapter/outbound/support/src/main/java/dev/caskeleton/adapter/outbound/support/FailOpenDependencyLogger.java:40-51` — `error="{}"`에 `getSimpleName()`만 넣음. 커밋 `9a05d686` (W1) | - | `FailOpenDependencyLogger.java:41,47`에서 `getMessage()`를 빼고 `error="{}"`에 예외 클래스 simple name만 남긴다 | +| A-1b | Required | PII 누출 테스트가 메시지 `"connection refused"`로 `@gmail.com` 부재만 확인 → 아무것도 증명 못 함 | 완료 | Wave 1–2 P7 (fcddab7e·Wave 2 커밋): 같은 테스트(`FailOpenDependencyLoggerTest.java:64-79`)가 예외 메시지에 `alice@example.com`·`https://hooks.slack.com/services/...`를 넣고 렌더된 로그에 둘 다 없음을 단언한다. 수정 전 FAIL 확인. 커밋 `9a05d686` | - | 같은 테스트에서 예외 메시지에 `alice@example.com`, `https://hooks.slack.com/services/...`를 넣고 렌더된 로그에 둘 다 없음을 단언 | | A-2a | Required | websocket이 prod 판정을 손으로 재구현(`"prod".equals`, trim/소문자 없음) → `Prod` 프로필에서 prod 안전 검증 건너뜀 | 해당 없음(코드 삭제) | 「제거된 코드」 표 `app.websocket.platform.*` 설정(`WebSocketPlatformSafetyConfiguration`, `WebSocketPlatformStartupValidator` 포함) 행. `git log --diff-filter=D`로 `6d27356e` 삭제 확인, 현재 websocket main에 `getActiveProfiles` 호출 0건 | - | - | | A-2b | Required | `RuntimeProfileSnapshot` Javadoc "repository에서 `getActiveProfiles`를 읽는 유일한 production 타입" 주장이 거짓 | 남음 | `src/adapter/outbound/support/src/main/java/dev/caskeleton/adapter/outbound/support/runtime/RuntimeProfileSnapshot.java:12-13`. 직접 읽는 곳: `src/adapter/inbound/graphql/.../autoconfigure/GraphQlPlatformAutoConfiguration.java:123`, `src/adapter/outbound/fileserver/.../platform/autoconfigure/FileserverSecurityConfiguration.java:81`, `src/adapter/outbound/httpclient/.../autoconfigure/HttpClientProfileAutoConfiguration.java:155-156`, `src/adapter/outbound/objectstorage/.../config/ObjectStorageCapabilityConfig.java:59-61` | W5 | `RuntimeProfileSnapshot.java:12-13` 문장을 "composition root(app-bootstrap)의 reader"로 좁히거나 삭제 | | A-2c | Required | BOOT-002 가드 ArchUnit이 `dev.caskeleton.bootstrap..`만 검사 → 다른 leaf의 새 profile reader·손 판정은 못 잡음 | 남음 | `src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/RuntimeProfileAccessArchitectureTest.java:12-21` (변경 없음, `git diff 208077fd 6d27356e` 0줄) | W3 | 같은 규칙을 `dev.caskeleton..`(messaging·sample 제외)로 넓히고 `getActiveProfiles` 호출 허용 목록을 현재 5곳(`RuntimeProfileSnapshot`, 위 graphql·fileserver·httpclient·objectstorage 클래스)으로 고정 — support에 의존 못 하는 graphql·objectstorage가 있어 snapshot 강제는 불가 | @@ -106,10 +118,10 @@ | A-6c | Required | identifier README 패키지 루트·SSOT 오기, 삭제된 UUID 능력을 설명 | 남음 | `src/adapter/outbound/identifier/README.md:3`(`dev.caskeleton.adapter.identifier`, 실제 `...adapter.outbound.identifier`), `:50`(`src/build.gradle`의 `allowedProjectDependencies`), `:11-12` UUIDv7 식별자 생성(main엔 `HmacUserPrincipalPseudonymizer`만). Spock 절은 삭제됨 | W5 | `identifier/README.md:3`, `:50`을 실제 패키지·`src/config/architecture/modules.json`으로, `:11-12` UUID 문장 삭제 | | A-6d | Required | support README가 "CLAUDE.md 없음", SSOT를 `src/build.gradle`로, 없는 `OutboundHttpDependencyLogger`를 언급 | 남음 | `src/adapter/outbound/support/README.md:7-8`(`src/adapter/outbound/support/CLAUDE.md` 존재), `:24`(`class OutboundHttpDependencyLogger` 0건) | W5 | `support/README.md:7-8`을 modules.json·CLAUDE.md 참조로, `:23-24` 비교 문장 삭제 | | A-6e | Required | shared-contract README가 없는 `RateLimiter`/`RateLimiterFactory`를 패턴 예시로 인용 | 남음 | `src/shared-contract/README.md:436,499`, 같은 인용 `src/shared-contract/src/main/java/dev/caskeleton/shared/concurrency/DomainContextPropagatorFactory.java:8` | W5 | 세 곳의 `RateLimiter*` 비교 문장 삭제 | -| A-7a | Consider | `ValidatedIntegrationEvent`가 `envelopeSha256`과 `envelopeBytes` 일치를 확인하지 않음 — DB 복원 경로가 저장된 해시를 그대로 신뢰 | 남음 | `src/application-core/src/main/java/dev/caskeleton/application/messaging/event/ValidatedIntegrationEvent.java:78-83`(null 검사만), 복원 `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/outbox/OutboxStoreAdapter.java:197-214` | W2 | 생성자에서 `envelopeBytes`의 SHA-256을 계산해 `envelopeSha256`과 다르면 `IllegalArgumentException` | -| A-7b | Consider | `CORRELATION_GRAMMAR`가 `*`라 correlation/causation id 길이 무제한인데 오류 메시지는 "bounded" | 남음 | `ValidatedIntegrationEvent.java:36,54,58-59,159` | W2 | `CORRELATION_GRAMMAR`를 `[A-Za-z0-9][A-Za-z0-9._:-]{0,127}`로 | +| A-7a | Consider | `ValidatedIntegrationEvent`가 `envelopeSha256`과 `envelopeBytes` 일치를 확인하지 않음 — DB 복원 경로가 저장된 해시를 그대로 신뢰 | 완료 | Wave 1–2 P7 (fcddab7e·Wave 2 커밋): `ValidatedIntegrationEventTest.envelopeHashThatIsNotTheSha256OfTheEnvelopeBytesIsRefused` FAIL(`Expecting actual not to be null`)→PASS. DB 복원 경로는 `OutboxStoreAdapterTest.claimBatchRefusesACanonicalRowWhoseStoredEnvelopeHashIsNotItsBytesHash`가 PASS(`invalid canonical outbox metadata…` + 원인 메시지 확인). 코드: `src/application-core/src/main/java/dev/caskeleton/application/messaging/event/ValidatedIntegrationEvent.java:85-89`. 계산은 새로 만든 `Sha256.of(byte[])`(`src/application-core/src/main/java/dev/caskeleton/application/messaging/contract/Sha256.java:21-29`)로 한다. 임의 해시로 이벤트를 만들던 테스트 픽스처 5곳을 `Sha256.of(envelope)`로 바꿨다(application-core 1, messaging 2, persistence-jpa 2). 커밋 `3a39b6b5` (W2) | - | 생성자에서 `envelopeBytes`의 SHA-256을 계산해 `envelopeSha256`과 다르면 `IllegalArgumentException` | +| A-7b | Consider | `CORRELATION_GRAMMAR`가 `*`라 correlation/causation id 길이 무제한인데 오류 메시지는 "bounded" | 완료 | Wave 1–2 P7 (fcddab7e·Wave 2 커밋): `ValidatedIntegrationEventTest.correlationIdLongerThan128CharactersIsRefused`·`causationIdLongerThan128CharactersIsRefused` FAIL→PASS. 경계값 테스트 `correlationIdOf128CharactersIsAccepted` PASS. `ValidatedIntegrationEvent.java:36-37` `{0,127}` — outbox `correlation_id`·`causation_id` varchar(128)과 같다. 커밋 `3a39b6b5` | - | `CORRELATION_GRAMMAR`를 `[A-Za-z0-9][A-Za-z0-9._:-]{0,127}`로 | | A-8a | Consider | v1 `IdempotencyExecutor.runAndComplete`가 완료 기록 실패를 action 실패로 처리 → 재시도 때 action 재실행 | 해당 없음(코드 삭제) | 「제거된 코드」 표 "요청 멱등성 v1 모델 (`IdempotencyExecutor`(v1) …)" 행(D3). 현재 executor는 try가 `action.run()`만 감쌈(`src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyExecutor.java:192-198`) | - | - | -| A-8b | Consider | 정본 executor(구 V2)에서 `preserveUnknown`이 던지면 원래 action 예외를 잃음 | 남음 | `src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyExecutor.java:194-198`, `:210-213` | W2 | 두 곳에서 `preserveUnknown` 호출을 try/catch로 감싸 `failure.addSuppressed(e)` 후 원래 예외를 던진다 | +| A-8b | Consider | 정본 executor(구 V2)에서 `preserveUnknown`이 던지면 원래 action 예외를 잃음 | 완료 | Wave 1–2 P7 (fcddab7e·Wave 2 커밋): `IdempotencyExecutorTest.aStoreFailureWhileRecordingTheActionFailureIsSuppressedUnderIt` 3건(thrown / effect unknown / retryable no effect) FAIL(`IllegalStateException: store unavailable … to refer to the same object`)→PASS. `src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyExecutor.java:197-219,273-289` — `markFailed` 호출 세 곳을 `recordFailure` 하나로 모았다. store 예외는 원래 예외에 `addSuppressed`로 붙는다. 현황표는 `preserveUnknown` 두 곳만 적었지만 `RetryableNoEffect` 경로도 같은 결함이라 함께 고쳤다. 커밋 `3a39b6b5` | - | 두 곳에서 `preserveUnknown` 호출을 try/catch로 감싸 `failure.addSuppressed(e)` 후 원래 예외를 던진다 | | A-9a | Consider | `UuidCodec` 죽은 코드(외부 참조 0, "canonical" 계약도 틀림) | 해당 없음(코드 삭제) | 「제거된 코드」 표 `UuidCodec` 행 | - | - | | A-9b | Consider | application-core 테스트 헬퍼 `CompiledPackageScanner` 참조 0 | 해당 없음(코드 삭제) | 「제거된 코드」 표 "application-core 테스트 헬퍼 `CompiledPackageScanner`" 행(다른 leaf 사본 2개는 사용 중) | - | - | | A-9c | Consider | `@Deprecated(forRemoval)` `FileExportPort` 호출자 0 | 해당 없음(코드 삭제) | 「제거된 코드」 표 "`FilePublicationPort`·`FileExportPort` 계약" 행 | - | - | @@ -126,10 +138,10 @@ | L-5 | Consider | 남은 `StartupSafetyValidator` 검사(multi-instance → lock provider)는 절대 실패할 수 없음 | 해당 없음(코드 삭제) | 「제거된 코드」 표 "`DistributedLockConfig`와 `DistributedLockConfigTest`" 행 — bean이 opt-in persistence-jpa(`DistributedLockPersistenceConfig.java:83-92`)로 옮겨져, JPA 없는 기본 조립에서 `APP_MULTI_INSTANCE_ENABLED=true`면 이 검사만 실패시킴. 테스트 `StartupSafetyValidatorTest.multiInstanceEnabledWithMissingDistributedLockProviderFailsStartup` | - | - | | L-6a | Consider | 관계형 의존 목록이 `DataSourceRequirement`와 `CapabilityDependencyValidator` 두 곳에 있고 fileserver 항목이 어긋남 | 해당 없음(코드 삭제) | 「제거된 코드」 표 "`JpaOffAutoConfigurationImportFilter`, `DataSourceRequirement`" 행과 "bootstrap `activation` 패키지(`CapabilityDependencyValidator` …)" 행. fileserver는 `persistence-fileserver`가 data-jpa를 직접 가져옴 | - | - | | L-6b | Consider | `SecretSourceValidator`가 DB 없는 prod 배포에도 `APP_DATASOURCE_PASSWORD`를 요구 | 완료 | `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/runtime/SecretSourceValidator.java:109-110`(`ca-skeleton.persistence-jpa.enabled` 아닐 때 건너뜀). 테스트 `SecretSourceValidatorTest.prodProfileWithoutRelationalPersistenceDoesNotRequireADatabasePassword`. 커밋 `6d27356e` | - | - | -| L-7a | Consider | actuator chain에 인증 수단(`oauth2ResourceServer`/`httpBasic`)이 없어 `loggers` GET과 `show-details: when-authorized`에 어떤 자격증명으로도 도달 불가 | 남음 | `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/management/security/ManagementSecurityConfig.java:25-42`, `src/app-bootstrap/src/main/resources/config/observability.yml:34,41` | W2 | 지금도 도달 불가라 잃는 동작이 없으므로 `observability.yml:34`에서 `loggers` 노출 제거, `:41`을 `show-details: never`로, `ManagementSecurityConfig.java:37-40` loggers 규칙 삭제 | +| L-7a | Consider | actuator chain에 인증 수단(`oauth2ResourceServer`/`httpBasic`)이 없어 `loggers` GET과 `show-details: when-authorized`에 어떤 자격증명으로도 도달 불가 | 완료 | Wave 1–2 P7 (fcddab7e·Wave 2 커밋): 실제 배포 yml을 읽는 `ManagementActuatorSecurityContractTest.applicationYmlExposureIncludePinsAllowlistExactly`·`applicationYmlPinsShowDetailsNeverAndShutdownDisabled` FAIL→PASS. `ActuatorSecurityHttpTest.loggersEndpointIsNotExposed`(인증된 사용자도 404)·`actuatorLinksChallengeUnauthenticatedCallerWith401`(D3 401 확인 대상을 `/actuator` 링크로 옮김) PASS. 변경: `src/app-bootstrap/src/main/resources/config/observability.yml:36`(`include: health,prometheus,info`), `:44`(`show-details: never`), `ManagementSecurityConfig.java:33-37`(loggers `denyAll` 규칙 삭제). `src/app-bootstrap/README.md` 해당 절도 고쳤다. P10이 바꾼 `observability.yml:151` 줄은 건드리지 않았다. 커밋 `3a39b6b5` | - | 지금도 도달 불가라 잃는 동작이 없으므로 `observability.yml:34`에서 `loggers` 노출 제거, `:41`을 `show-details: never`로, `ManagementSecurityConfig.java:37-40` loggers 규칙 삭제 | | L-7b | Consider | `ActuatorSecurityHttpTest`가 `.with(user("ops"))`로 보안 컨텍스트를 주입해 실제로는 도달 불가능한 200을 단언 | 남음 | `src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/ActuatorSecurityHttpTest.java:99-100`(`loggersReadIsAllowedForAuthenticatedCaller`), `:104-120` | W4 | L-7a 적용 후 `loggersReadIsAllowedForAuthenticatedCaller`·loggers write 테스트를 "loggers 비노출(404)" 단언 하나로 교체 | -| L-8a | Consider | sample 기본값 `flyway.out-of-order: true`(prod가 금지하는 값) | 남음 | `src/sample-portfolio/src/main/resources/application.yml:45` | W2 | `application.yml:45`를 `out-of-order: false` | -| L-8b | Consider | sample 기본값 `ddl-auto: update`가 Flyway 소유 스키마를 덮음(mapping/migration 불일치를 숨김) | 남음 | `src/sample-portfolio/src/main/resources/application.yml:53` | W2 | `application.yml:53`을 `${APP_DATASOURCE_DDL_AUTO:validate}` | +| L-8a | Consider | sample 기본값 `flyway.out-of-order: true`(prod가 금지하는 값) | 완료 | Wave 1–2 P7 (fcddab7e·Wave 2 커밋): `SampleSchemaOwnershipDefaultsTest.sampleDefaultsLeaveTheSchemaToFlyway[spring.flyway.out-of-order]` FAIL(`"true"`)→PASS. `src/sample-portfolio/src/main/resources/application.yml:45` `out-of-order: false`. 커밋 `3a39b6b5` | - | `application.yml:45`를 `out-of-order: false` | +| L-8b | Consider | sample 기본값 `ddl-auto: update`가 Flyway 소유 스키마를 덮음(mapping/migration 불일치를 숨김) | 완료 | Wave 1–2 P7 (fcddab7e·Wave 2 커밋): 같은 테스트 `[spring.jpa.hibernate.ddl-auto]` FAIL(`${APP_DATASOURCE_DDL_AUTO:update}`)→PASS. `application.yml:53` `${APP_DATASOURCE_DDL_AUTO:validate}` — env registry 기본값 `validate`와 같아졌다. env 키 변경은 없다(`verifyEnvKeys` 통과). 커밋 `3a39b6b5` | - | `application.yml:53`을 `${APP_DATASOURCE_DDL_AUTO:validate}` | | L-9 | Nit | `NotificationApplicationCompositionAutoConfiguration`에 `@Bean` 12개, 고아 Javadoc, inline FQN | 완료 | `src/composition/notification-platform/src/main/java/dev/caskeleton/composition/notification/NotificationApplicationCompositionAutoConfiguration.java:14-27`(`@Bean` 0, `@Import` 3개) → `NotificationSubmissionConfiguration`(7), `NotificationDeliveryConfiguration`(5), `NotificationCallbackConfiguration`(2). 커밋 `6d27356e` | - | - | | L-10a | Nit | outbox 설정 주석이 "NO env placeholders", "Bound into OutboxProperties"라 서술(실제 placeholder 있음, binder는 `OutboxSettings`) | 남음 | bootstrap `config/outbox.yml`은 삭제됐으나 주석이 `src/adapter/outbound/persistence-jpa/src/main/resources/config/module-defaults/persistence-jpa.yml:178-179`로 옮겨 살아 있음(placeholder `:188-192`, 바인더 `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/outbox/OutboxSettings.java`) | W5 | `persistence-jpa.yml:178-179`를 "Bound into OutboxSettings (app-bootstrap); enabled/relay-enabled/canonical-transport-enabled만 env"로, `:180`의 떨어진 relay-enabled 주석을 `:189` 위로 | | L-10b | Nit | `config/idempotency.yml`이 없는 `IdempotencyProperties`를 이름으로 가리킴 | 해당 없음(코드 삭제) | 「제거된 코드」 표 "bootstrap 멱등성 조립 (… `config/idempotency.yml`)" 행 | - | - | @@ -162,23 +174,23 @@ | B-2b | Critical | TopicArn allowlist 없음 | 완료 | `src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/provider/ses/SesCallbackAdapter.java:75-78`, 콜백 켜면 필수 `.../platform/autoconfigure/NotificationPlatformSettings.java:349-355`. 테스트 `SesCallbackAdapterTest.aSignedMessageFromAnotherTopicIsRejected`, `NotificationPlatformSettingsTest.sesCallbacksWithoutAnAllowedTopicListFailBinding`. 커밋 `6d27356e` | - | - | | B-2c | Critical | SNS `Timestamp` 미검사(재전송 무기한) | 완료 | `SesCallbackAdapter.java:79-81`·`withinReplayWindow`, `.../platform/autoconfigure/NotificationCallbackProviderConfig.java:93-98`(`callbacks.replay-skew`). 테스트 `SesCallbackAdapterTest.aSignedMessageOlderThanTheReplayWindowIsRejected`. 커밋 `6d27356e` | - | - | | B-2d | Critical | 인증서 캐시 무제한, `computeIfAbsent` 안에서 네트워크 fetch | 완료 | `src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/NotificationCallbackProviderConfig.java:34`(상한 64), `:49-62`(fetch를 map 밖에서). 테스트 `SnsCertificateCacheTest.theCacheForgetsCertificatesOnceItPassesItsBound`·`aCachedCertificateIsNotFetchedAgain`. 커밋 `6d27356e` | - | - | -| B-2e | Critical | 받아온 인증서의 subject 검사 없음 | 남음 | `src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/NotificationCallbackProviderConfig.java:73-78`(`getPublicKey()`만 반환, `getSubjectX500Principal` 참조 0). host가 SNS 리전 host + https로 제한돼 잔여 위험은 낮음 | W1 | `NotificationCallbackProviderConfig`의 fetch에서 subject CN이 `sns.amazonaws.com`인지 확인 후 key 반환, 불일치 인증서 거부 테스트 추가 | -| B-3 | Required | dispatch의 render·profile 실패가 attempt row 전에 터져 영원히 재큐(poison pill) | 남음 | `src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/NotificationDispatchService.java:146-147`(`insertDispatching` `:149-159` 전, catch 없음). 제출 검증은 `.../dispatch/NotificationSubmissionService.java:115` `templates.get`뿐. render 실패 테스트 없음(`NotificationDispatchServiceTest` 메서드 2개) | W2 | `NotificationDispatchService.dispatch`에서 render/profile의 `NotificationException`을 잡아 recipient를 FAILED(`TEMPLATE_FAILURE`)로 전이 후 lease 해제; `NotificationSubmissionService`에서 변수 스키마 검증을 먼저 수행; 재현 테스트 | -| B-4a | Required | 모든 attempt가 완료된 DISPATCHING 행을 recovery가 그대로 둠 → 같은 행만 반복 선택 | 남음 | `src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/LeaseRecoveryService.java:123-139`(`completedAt` 있는 attempt는 건너뜀, 행 상태 불변), `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/notification/platform/RecipientDeliveryJpaRepository.java:184-190`(`ORDER BY lease_until LIMIT`). 해당 테스트 없음 | W2 | `LeaseRecoveryService.recoverOnce`에서 attempt가 전부 완료면 마지막 attempt로 retry policy를 다시 적용해 recipient 상태 확정; `LeaseRecoveryServiceTest`에 케이스 추가 | -| B-4b | Required | reconcile `Unsupported`(SMTP·SES)·`Failed`가 행을 DISPATCHING에 남김 | 남음 | `src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/ReconciliationService.java:77-84`, `:126-133`(metric만 올림) | W2 | `ReconciliationService.reconcile`의 `Unsupported`·`Failed` 분기에서 recipient를 `RECONCILIATION_REQUIRED`로 전이(`inWrite`)해 recovery 대상에서 빼고 운영자에게 보이게 | -| B-5a | Required | recorder가 late-match 콜백 투영 직후 dispatch 시작 시점 snapshot으로 recipient를 덮어씀 | 남음 | `src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/DispatchOutcomeRecorder.java:100-106`(`bindUnmatched`→`project`), `:109-135`(`recipient.deliveryOutcome()`·`evidenceLevel()` 옛 값으로 `save`). `DispatchOutcomeRecorderTest` fake는 projection 저장 no-op | W2 | 투영 뒤 recipient를 다시 읽고 recorder가 소유한 필드만 갱신; fake가 투영을 실제로 반영하는 테스트 | -| B-5b | Required | recorder의 recipient 저장이 lease fencing 없음(포트 계약 위반) | 남음 | `DispatchOutcomeRecorder.java:135` `recipients.save(updated)`; 계약 `.../dispatch/RecipientLeaseStorePort.java:14`("Every operation after the claim is fenced"); `saveHeldBy`는 `.../dispatch/RecipientDeliveryStorePort.java:35`에 이미 있음 | W2 | `record()`에 lease를 넘기고 `saveHeldBy(updated, lease)` 사용, 빈 결과면 lease 상실로 처리 | -| B-6 | Required | 알림 HTTP 응답 "상한"이 body 전체를 읽은 뒤 잘라냄 | 남음 | `src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/provider/http/JdkNotificationHttpGateway.java:136-141`(`ofByteArray()` 후 `copyOf`), 주석 `:72-75`("끝없는 chunked 방지")는 사실과 다름. 초과 응답 테스트 없음. SNS 인증서 fetch도 이 gateway 사용(B-2d) | W1 | `boundedBody`를 `BodySubscribers.ofInputStream()`+`readNBytes(max)`(또는 상한 넘으면 구독 취소)로 교체, 초과 body 테스트 | -| B-7a | Required | admin reconcile에 tenant 검사 없음 | 남음 | `src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/admin/NotificationAdminApplicationService.java:156-182`(`require(RECONCILE)`만; redrive `:105`·suppress `:210`은 `requireTenant` 호출) | W1 | attemptId마다 소유 tenant를 조회해 `authorization.requireTenant` 호출 | -| B-7b | Required | tenant 범위 actor가 전역 provider 상태를 바꿀 수 있음 | 남음 | `NotificationAdminApplicationService.java:287-289`(`require(PROVIDER_CONTROL)`만) | W1 | `setProviderState`에서 `actor.tenantId()`가 있으면 거부 | -| B-7c | Required | admin executor가 provider 호출까지 한 DB write 트랜잭션에 넣음 | 남음 | `src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/admin/AdminOperationExecutor.java:32-42`(claim+operation 한 `inWrite`) → reconcile 루프 `NotificationAdminApplicationService.java:179-182`의 provider 왕복이 한 트랜잭션 안 | W2 | executor는 claim과 결과 저장만 각각 트랜잭션으로, operation 본문(provider 호출)은 트랜잭션 밖에서 | +| B-2e | Critical | 받아온 인증서의 subject 검사 없음 | 완료 | Wave 1–2 P3 (fcddab7e·Wave 2 커밋): `SnsCertificateCacheTest.aCertificateNotIssuedToSnsIsRefused` FAIL(`Expecting actual not to be null` — CN=sns.test.invalid 인증서의 키를 그대로 반환)→PASS. `ntf-adapter/autoconfigure/NotificationCallbackProviderConfig.java:89`(subject가 `CN=sns.amazonaws.com`/`.com.cn`이 아니면 거부), `:80` 유효기간 검사도 추가(P3-new-2) | - | `NotificationCallbackProviderConfig`의 fetch에서 subject CN이 `sns.amazonaws.com`인지 확인 후 key 반환, 불일치 인증서 거부 테스트 추가 | +| B-3 | Required | dispatch의 render·profile 실패가 attempt row 전에 터져 영원히 재큐(poison pill) | 완료 | Wave 1–2 P3 (fcddab7e·Wave 2 커밋): `NotificationDispatchServiceTest.aTemplateThatCannotRenderFailsTheDeliveryInsteadOfLeavingItClaimed` FAIL(`TemplateVariableValidationException: TEMPLATE_VARIABLES_INVALID`가 dispatch 밖으로 새어 lease가 남음)→PASS. `ntf-app/dispatch/NotificationDispatchService.java:147-163`(render·profile의 재시도 불가 `NotificationException` → 수신자 FAILED + `lastFailureCategory`, lease 해제), `:201` `failBeforeAttempt`(fenced `saveHeldBy`). 수정 방향의 "제출 시 변수 스키마 검증"은 하지 않았다: poison pill을 닫는 것은 dispatch 쪽 처리이고(템플릿 내용·엔진 오류도 여기서 걸림), 제출 검증은 `NotificationSubmissionService` 생성자·조립 변경이 필요한 입력 품질 개선이다 | - | `NotificationDispatchService.dispatch`에서 render/profile의 `NotificationException`을 잡아 recipient를 FAILED(`TEMPLATE_FAILURE`)로 전이 후 lease 해제; `NotificationSubmissionService`에서 변수 스키마 검증을 먼저 수행; 재현 테스트 | +| B-4a | Required | 모든 attempt가 완료된 DISPATCHING 행을 recovery가 그대로 둠 → 같은 행만 반복 선택 | 완료 | Wave 1–2 P3 (fcddab7e·Wave 2 커밋): `LeaseRecoveryServiceTest.aDispatchingDeliveryWhoseAttemptsAllCompletedIsRequeued` FAIL(`Expecting actual: [] to contain exactly ... READY_TO_DISPATCH`)→PASS. `ntf-app/dispatch/LeaseRecoveryService.java:123-133`. 수정 방향(recovery에서 retry policy 재적용)보다 작게: recorder가 이미 결과를 수신자 행에 썼고 dispatch의 `RoutingDecisionEngine`이 그 사실(accepted면 stop→COMPLETED, ambiguous면 reconcile)로 다음 단계를 다시 정하므로 READY_TO_DISPATCH로 되돌리면 된다. recovery에 retry policy·profile 의존을 끌어오지 않는다 | - | `LeaseRecoveryService.recoverOnce`에서 attempt가 전부 완료면 마지막 attempt로 retry policy를 다시 적용해 recipient 상태 확정; `LeaseRecoveryServiceTest`에 케이스 추가 | +| B-4b | Required | reconcile `Unsupported`(SMTP·SES)·`Failed`가 행을 DISPATCHING에 남김 | 완료 | Wave 1–2 P3 (fcddab7e·Wave 2 커밋): `ReconciliationServiceTest.anUnsupportedAnswerParksADispatchingDeliveryForAnOperator`, `aFailedAnswerParksADispatchingDeliveryForAnOperator` FAIL(`Expecting actual: [DISPATCHING, Optional[2026-09-20T00:00:00Z]] to contain exactly [RECONCILIATION_REQUIRED, Optional.empty]`)→PASS. `ntf-app/dispatch/ReconciliationService.java:126,132,148`(`parkForOperator`: DISPATCHING인 수신자만 `RECONCILIATION_REQUIRED`·next 없음으로, 이미 끝난 수신자는 그대로 — `anUnsupportedAnswerLeavesAFinishedDeliveryAlone`) | - | `ReconciliationService.reconcile`의 `Unsupported`·`Failed` 분기에서 recipient를 `RECONCILIATION_REQUIRED`로 전이(`inWrite`)해 recovery 대상에서 빼고 운영자에게 보이게 | +| B-5a | Required | recorder가 late-match 콜백 투영 직후 dispatch 시작 시점 snapshot으로 recipient를 덮어씀 | 완료 | Wave 1–2 P3 (fcddab7e·Wave 2 커밋): `DispatchOutcomeRecorderTest.aLateMatchedCallbackProjectionIsNotOverwrittenByTheRecorder` FAIL(컴파일: `record(attempt, recipient, lease, …)` 시그니처 없음 — lease 인자를 요구하는 테스트)→PASS. fake 투영 저장소가 JPA처럼 수신자 행에 DELIVERED/DEVICE_DELIVERED를 올린다. `ntf-app/dispatch/DispatchOutcomeRecorder.java:122`(투영 뒤 수신자를 다시 읽고 recorder 소유 필드만 갱신) | - | 투영 뒤 recipient를 다시 읽고 recorder가 소유한 필드만 갱신; fake가 투영을 실제로 반영하는 테스트 | +| B-5b | Required | recorder의 recipient 저장이 lease fencing 없음(포트 계약 위반) | 완료 | Wave 1–2 P3 (fcddab7e·Wave 2 커밋): `DispatchOutcomeRecorderTest.aRecorderThatLostItsLeaseWritesNothingToTheRecipient` FAIL(컴파일, 위와 같음)→PASS. `DispatchOutcomeRecorder.java:153` `saveHeldBy(updated, lease)`, 호출 `NotificationDispatchService.java:194`. 빈 결과(lease 상실)면 쓰지 않고, 이어지는 next-step 쓰기도 fenced라 no-op | - | `record()`에 lease를 넘기고 `saveHeldBy(updated, lease)` 사용, 빈 결과면 lease 상실로 처리 | +| B-6 | Required | 알림 HTTP 응답 "상한"이 body 전체를 읽은 뒤 잘라냄 | 완료 | Wave 1–2 P3 (fcddab7e·Wave 2 커밋): `JdkNotificationHttpGatewaySecurityTest.aResponseBodyThatNeverEndsIsCutAtTheCapWithoutWaitingForItsEnd` FAIL(`TimeoutException` — 요청 timeout 10초가 지나도 끝나지 않는 body를 끝까지 기다려 JUnit 20초 timeout)→PASS. `ntf-adapter/provider/http/JdkNotificationHttpGateway.java:147-160`(`ofInputStream` + `readNBytes(max)` 후 close, 읽기는 호출 스레드에서 `Supplier`로) | - | `boundedBody`를 `BodySubscribers.ofInputStream()`+`readNBytes(max)`(또는 상한 넘으면 구독 취소)로 교체, 초과 body 테스트 | +| B-7a | Required | admin reconcile에 tenant 검사 없음 | 완료 | Wave 1–2 P3 (fcddab7e·Wave 2 커밋): `NotificationAdminApplicationServiceTest.aTenantScopedOperatorCannotReconcileAnotherTenantsAttempt` FAIL(`Expecting actual not to be null` — 예외 없이 진행)→PASS. `ntf-app/admin/NotificationAdminApplicationService.java:161-168`(attempt마다 소유 tenant 확인, 배치 중 하나라도 남의 것이면 아무것도 안 함). 없는 attemptId는 reconcile이 아무것도 하지 않으므로 검사 생략 | - | attemptId마다 소유 tenant를 조회해 `authorization.requireTenant` 호출 | +| B-7b | Required | tenant 범위 actor가 전역 provider 상태를 바꿀 수 있음 | 완료 | Wave 1–2 P3 (fcddab7e·Wave 2 커밋): `NotificationAdminApplicationServiceTest.aTenantScopedOperatorCannotChangeAGlobalProviderState` FAIL(`Expecting actual not to be null`)→PASS. `ntf-app/admin/AdminAuthorizationGuard.java:58`(`requireGlobal`), 호출 `NotificationAdminApplicationService.java:305` | - | `setProviderState`에서 `actor.tenantId()`가 있으면 거부 | +| B-7c | Required | admin executor가 provider 호출까지 한 DB write 트랜잭션에 넣음 | 완료 | Wave 1–2 P3 (fcddab7e·Wave 2 커밋): `NotificationAdminApplicationServiceTest.reconcileAsksTheProviderWithNoTransactionOpen` FAIL(`Expecting actual: [true] to contain exactly [false]`)→PASS. `ntf-app/admin/AdminOperationExecutor.java:54`(`executeOutsideTransaction`: claim 트랜잭션 → 본문 트랜잭션 없이 → 결과 저장은 본문이 자기 트랜잭션에서), reconcile만 이 경로(`NotificationAdminApplicationService.java:183`). 실패 시 claim을 `FAILED` 결과로 닫음(`AdminOperationExecutorTest.anOperationThatFailsOutsideTheTransactionCompletesItsClaimAsFailed`) — 안 닫으면 같은 id가 영구 IN_PROGRESS. redrive·suppress·provider state는 DB/메모리 작업뿐이라 기존 단일 트랜잭션 유지 | - | executor는 claim과 결과 저장만 각각 트랜잭션으로, operation 본문(provider 호출)은 트랜잭션 밖에서 | | B-7d | Required | tenant 거부를 항상 `SUPPRESS` 권한 부족으로 보고 | 남음 | `src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/admin/AdminAuthorizationGuard.java:42-43` | W5 | `requireTenant` 거부 사유를 tenant 범위 전용 값으로(또는 호출한 연산의 authority를 인자로) | | B-8a | Consider | caller 없는 R1 타입 약 95개 | 해당 없음(코드 삭제) | 「제거된 코드」 표 "Notification R1 타입 96개(`NotificationPort`·`Notification`·`NotificationChannel` 제외)와 테스트 19개" 행. `git ls-files 'src/application-notification/src/main/java/dev/caskeleton/application/notification/*.java'` → 3개만 | - | - | | B-8b | Consider | 조립 0인 Reactor facade와 `reactor-core`·`reactor-test` 의존 | 해당 없음(코드 삭제) | 「제거된 코드」 표 "Notification Reactor facade와 `reactor-core`·`reactor-test`·`spring-web` 의존" 행. `.../notification/platform/reactor` ls-files 0건, `src/adapter/outbound/notification/build.gradle`에 reactor 0건 | - | - | | B-8c | Consider | import 0인 `spring-web` 의존 | 해당 없음(코드 삭제) | 같은 표 행. `src/adapter/outbound/notification/build.gradle`에 `spring-web` 0건 | - | - | | B-8d | Consider | `EmailNotifier`·`SmsNotifier`·`MobilePushNotifier`·`WebPushNotifier`·`ApplicationReceiptServiceImpl` caller 없음 | 해당 없음(코드 삭제) | 「제거된 코드」 표 "notification platform `sms`·`push`·`email`·`webpush` facade와 `ApplicationReceiptServiceImpl`" 행. `git grep` 0건 | - | - | -| B-9a | Consider | SMTP 전송 전 실패(비 email 연락처, reveal 실패, 첨부 open 실패)가 ambiguous로 기록 | 남음 | `src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/provider/smtp/SmtpNotificationProviderAdapter.java:86-93`(`reveal`, `IllegalArgumentException`), `:99`(`EmailAttachments.open`); `src/application-notification/.../dispatch/NotificationDispatchService.java:278-287`(그 외 `RuntimeException`→ambiguous) | W2 | `SmtpNotificationProviderAdapter.send`의 전송 전 단계 실패를 `ProviderCallNotStartedException`으로 변환 | -| B-9b | Consider | notBefore 미도달 시 `next_dispatch_at`을 NULL로 전이 → 다시 claim 안 됨 | 남음 | `src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/DispatchPipeline.java:56-58`(`Blocked(READY_TO_DISPATCH)`) → `NotificationDispatchService.java:137-139`(`transition(..., Optional.empty())`); claim 조건 `src/adapter/outbound/persistence-jpa/.../notification/platform/RecipientClaimSql.java:29`(`next_dispatch_at <= :now`) | W2 | `Blocked`에 재시도 시각(`notBefore`)을 실어 `transition`에 전달 | +| B-9a | Consider | SMTP 전송 전 실패(비 email 연락처, reveal 실패, 첨부 open 실패)가 ambiguous로 기록 | 완료 | Wave 1–2 P3 (fcddab7e·Wave 2 커밋): `SmtpNotificationProviderAdapterTest.aNonEmailContactPointFailsBeforeTheCallStarts` FAIL(`Expecting actual throwable to be an instance of ProviderCallNotStartedException but was IllegalArgumentException`)→PASS. `ntf-adapter/provider/EmailRecipients.java`(reveal 실패·비 email → `ProviderCallNotStartedException(CONTACT_POINT_INVALID, INVALID_RECIPIENT)`), SMTP `SmtpNotificationProviderAdapter.java:86`, SES도 같은 결함이라 함께 `SesNotificationProviderAdapter.java:111`. 첨부 open 실패는 이미 `AttachmentUnavailable/IntegrityException`(preDispatch, ambiguous=false)이라 dispatch가 not-submitted로 처리 — 변경 불필요 | - | `SmtpNotificationProviderAdapter.send`의 전송 전 단계 실패를 `ProviderCallNotStartedException`으로 변환 | +| B-9b | Consider | notBefore 미도달 시 `next_dispatch_at`을 NULL로 전이 → 다시 claim 안 됨 | 완료 | Wave 1–2 P3 (fcddab7e·Wave 2 커밋): `NotificationDispatchServiceTest.aDeliveryBlockedByNotBeforeStaysScheduledForThatTime` FAIL(`Expecting Optional to contain: 2026-09-20T01:00:00Z but was empty`)→PASS. `ntf-app/dispatch/DispatchPipeline.java:60`(`Blocked`에 `notBefore`), `DispatchGuardOutcome.Blocked`에 `nextDispatchAt`, `NotificationDispatchService.java:142` | - | `Blocked`에 재시도 시각(`notBefore`)을 실어 `transition`에 전달 | | B-10a | Consider | adapter README·CLAUDE.md가 구현 전체를 "R0 legacy"로 서술 | 남음 | `src/adapter/outbound/notification/README.md:1-5`, `src/adapter/outbound/notification/CLAUDE.md:18-33` | W5 | R2 platform(SES·SMTP) 기준으로 다시 쓰고 legacy는 `core/`·`email/google`·`slack/webhook` seam만으로 한정 | | B-10b | Consider | `application-notification`에 CLAUDE.md 없음 | 남음 | `src/application-notification/`에 CLAUDE.md 없음(ls). 규칙은 `src/application-core/CLAUDE.md:78-79` 부근에 남아 있음 | W5 | `src/application-notification/CLAUDE.md` 신설, application-core의 notification 절을 옮김 | | B-10c | Consider | CLAUDE.md의 Boot 버전 4.0.0 | 남음 | `src/adapter/outbound/notification/CLAUDE.md:8` vs `src/gradle/libs.versions.toml:84`(`4.0.8`) | W5 | 4.0.8로 고치거나 버전 문구 삭제 | @@ -187,27 +199,27 @@ | C-1a | Critical | tus `Upload-Checksum`을 chunk가 아니라 누적 digest와 비교 | 완료 | `src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/local/LocalAppendEngine.java:64-66`(chunk 전용 digest), `:128-139`; `src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/tus/TusController.java:159,166-173`(기대 checksum을 append로 전달); fake `InMemoryUploadApplicationService.java:82-83`도 chunk 단위. 테스트 `TusProtocolContractTest.chunksCarryingTheirOwnCorrectChecksumAreAllAccepted`. 커밋 `6d27356e` | - | - | | C-1b | Critical | checksum 비교가 offset 커밋 뒤 → 불일치 chunk 저장·offset 전진 | 완료 | `LocalAppendEngine.java:74-80`(rollback 경계 안에서 검증, truncate); `src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/upload/DefaultUploadApplicationService.java:217-222`(append 성공 후에만 `commitOffset`). 테스트 `TusProtocolContractTest.aChunkRejectedForItsChecksumDoesNotAdvanceTheOffset`, `LocalStorageGatewayContractTest.aChunkWhoseChecksumDoesNotMatchIsRejectedAndRolledBackToItsPreAppendLength`. 커밋 `6d27356e` | - | - | | C-1c | Critical | 불일치를 422로 응답(tus는 460) | 완료 | `src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/api/error/FileserverErrorCode.java:47`(`CHECKSUM_MISMATCH(460)`). 테스트 `TusProtocolContractTest.aChunkWhoseChecksumDoesNotMatchAnswersChecksumMismatch`. 커밋 `6d27356e` | - | - | -| C-2a | Required | QUARANTINE 판정도 staging bytes 삭제 예약 | 남음 | `src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/upload/DefaultFinalizeUploadService.java:250-252`(REJECT·QUARANTINE 공통 `FAILED_VERIFICATION_CONTENT` enqueue), javadoc `:220-221`("only REJECT")과 모순 | W1 | `applyNonAcceptVerdict`에서 cleanup enqueue를 REJECT일 때만(QUARANTINE은 quarantine 영역으로 이동 또는 보존) | -| C-2b | Required | staging cleanup이 레코드 상태 재확인 없이 삭제 | 남음 | `src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/cleanup/DefaultCleanupService.java:134-146`(`isReclaimable` `:219-223`은 `cleanContent`에만 적용) | W1 | `cleanStaging`에서 fileId 레코드를 읽어 QUARANTINED면 skip | -| C-3a | Required | `reconcileRecoverable`·`RecoveryQueue`를 소비하는 곳 없음 | 남음 | bean 정의만 `src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/autoconfigure/FileserverMaintenanceServiceConfiguration.java:59-65`; main에서 `reconcileRecoverable` 호출 0(`git grep`); composition의 주기 worker는 `FileserverCleanupWorker`뿐 | W2 | `src/composition/fileserver-platform`에 `FileserverCleanupWorker`와 같은 방식으로 `reconcileRecoverable`을 주기 호출하는 worker 추가 | -| C-3b | Required | content key가 READY 커밋에만 기록 → pre-publish 복구 경로 도달 불가 | 남음 | `DefaultFinalizeUploadService.java:115`(publish) 뒤 `:303-310`(`publishAt(contentKey)`)에서만 key 저장, VERIFYING 전이 `:171-201`에는 key 없음 | W2 | `ContentKey`를 application이 정해 VERIFYING에 먼저 저장(write-ahead)한 뒤 move | -| C-3c | Required | publish의 `AmbiguousCompletionException`이 recovery queue로 안 감 | 남음 | `DefaultFinalizeUploadService.java:115`(try 없음). enqueue는 `commitReady` 실패 경로 `:318-323`뿐 | W2 | `publish` 호출을 감싸 ambiguous면 `recoveryQueue.enqueue`(`inNew`) 후 재던짐 | -| C-3d | Consider | (리뷰 외, `6d27356e` 회귀) 보상·복구용 REQUIRES_NEW 쓰기의 30초 상한 소실 | 남음 | `208077fd`의 `FileserverCompensationTransaction`(BUDGET 30s)을 `transactions.inNew`로 교체: `src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/upload/DefaultUploadApplicationService.java:155`, `DefaultFinalizeUploadService.java:321`; `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/transaction/SpringTransactionPort.java:50-55`(requiresNew template timeout 미설정) | W2 | `SpringTransactionPort`의 `requiresNewTemplate`에 timeout(30s) 설정(`inNew`는 outbox·audit·보상 전용이라 공통 상한으로 충분) | -| C-4a | Required | cancel이 READY 파일에도 staging cleanup만 예약 → 게시된 bytes·quota 영구 잔존 | 남음 | `src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/upload/DefaultUploadApplicationService.java:252-273`(`forStaging`만); `src/adapter/outbound/persistence-fileserver/src/main/java/dev/caskeleton/adapter/outbound/persistence/fileserver/repository/FileTransitionRepository.java:67-68`(`markDeleting`이 READY 허용) | W2 | UPLOADED 이후 cancel은 거부(409)하거나 `DefaultFileLifecycleService.delete`(`:71-104`)의 retire 경로 재사용 | -| C-4b | Required | staging cleanup이 DELETING→DELETED 전이를 안 함 → 취소된 upload 전부 DELETING 고착 | 남음 | `src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/cleanup/DefaultCleanupService.java:134-146`(`discardStaging`+`markDone`만) | W2 | `cleanStaging` 끝에서 레코드 DELETING→DELETED(+quota release)를 같은 트랜잭션으로 | -| C-5a | Required | 만료 upload를 치우는 sweep 없음(`EXPIRED_UPLOAD` 생산자 0) | 남음 | `src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/cleanup/CleanupType.java:10`; main에서 `EXPIRED_UPLOAD` enqueue 0(`git grep`) | W1 | cleanup worker에 `expiresAt` 지난 session을 EXPIRED로 전이하고 `EXPIRED_UPLOAD`를 예약하는 sweep 추가 | -| C-5b | Required | orphan 항목은 삭제 없이 done, orphan scan은 contentRoot만 | 남음 | `DefaultCleanupService.java:154-158`(fileId 없음→`markDone`); `src/application-fileserver/.../admin/DefaultFileserverAdminService.java:118-124`(quarantine로 옮긴 뒤 `forOrphan`); `src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/local/LocalOrphanScanAdapter.java:63,81` | W2 | orphan 항목은 quarantine 경로의 object를 실제 삭제; staging root도 scan | -| C-5c | Required | `Upload-Defer-Length: 1` 수락하지만 길이를 확정할 방법 없음 → 끝나지 않는 upload | 남음 | `src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/tus/TusRequestParser.java:64-66`; PATCH `TusController.java:153-184`는 `Upload-Length`를 읽지 않음 | W1 | 구현 전까지 `TusRequestParser.declaredLength`에서 `Upload-Defer-Length` 거부 | -| C-6 | Required | terminal 세션을 살아 있는 세션으로 취급 | 남음 | `src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/api/metadata/UploadSession.java:32`(`terminal`, main 참조 0); `DefaultUploadApplicationService.java:321-329`(`requireActiveSession`), `:243-249`(`status`); `src/adapter/outbound/persistence-fileserver/src/main/java/dev/caskeleton/adapter/outbound/persistence/fileserver/JpaUploadSessionStore.java:156-159`("lease held by another owner", retryable=true) | W2 | `requireActiveSession`·`status`에서 `terminal()`이면 410(또는 404) | -| C-7a | Required | append마다 prefix 전체를 다시 해시(O(n²) IO) | 남음 | `src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/local/LocalBlockingContentStore.java:386-395`(`reattach`가 매번 새 handle) → `LocalAppendEngine.java:59-62`(`rehashPrefix`) | W2 | uploadId별 상한 있는 digest 캐시(offset 키)를 store에 두고 `reattach`가 재사용 | -| C-7b | Required | finalize가 파일을 두 번 더 읽고 servlet 스레드에서 실행 | 남음 | `LocalBlockingContentStore.java:367-383`(`stagingDigest`), `.../platform/local/ContentPublishVerification.java:33`(`verifyStaged`); `TusController.java:178`(`transferExecutor` 밖) | W2 | `stagingDigest` 결과를 `verifyStaged`에 넘겨 재사용, finalize 호출을 `transferExecutor` 안으로 | -| C-8a | Required | 인가가 역할 등급만 보고 파일 owner가 없음 | 남음 | `src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/security/RoleBasedFileAccessPolicy.java:51-68`(`descriptor` 미사용); `src/application-fileserver/.../api/metadata/FileDescriptor.java:10`(owner 필드 없음); 업로드는 모두 기본 namespace(`TusController.java:107`, `.../controller/FileUploadController.java:185`, `.../draft12/Draft12UploadController.java:87`) | W1 | 결정(2026-09-25): 소유자 검사 추가 — `FileRecord`에 `ownerPrincipalId`(새 migration), 기본 정책이 소유자·tenant 검사 | -| C-8b | Required | `FileOperation.FINALIZE`를 인가하지 않음 | 남음 | main에서 `FileOperation.FINALIZE` 참조 0(테스트 `RoleBasedFileAccessPolicyTest.java:66`뿐); `DefaultFinalizeUploadService.java:97-117`에 authorize 없음; `docs/fileserver/security.md:54`("Every public operation calls the injected FileAccessPolicy") | W1 | `DefaultFinalizeUploadService.finalizeUpload`에서 FINALIZE authorize(또는 enum 값 삭제+문서 정정) | -| C-8c | Required | admin 조회가 READ_METADATA 등급으로 인가 | 남음 | `src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/admin/DefaultFileserverAdminService.java:209-211`(transport `RestrictedPathRule`로 완화됨) | W1 | admin 조회용 ADMIN 등급 operation으로 authorize | -| C-9a | Required | 업로드 동시성 한도 초과를 `QUOTA_EXCEEDED`(413, 재시도 불가)로 응답 | 남음 | `src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/quota/DefaultTransferAdmissionController.java:52-57`; `.../api/error/FileserverErrorCode.java:37` | W2 | scope 한도 초과도 `TRANSFER_ADMISSION_REJECTED`(429, retryable)로 | -| C-9b | Required | 모든 업로드가 기본 namespace 한 scope → 노드당 동시 업로드 4 | 남음 | `src/composition/fileserver-platform/src/main/resources/config/module-defaults/fileserver.yml:73-74`(scope 4 < instance 16); 컨트롤러 3곳 `defaultNamespace()`(C-8a 근거와 같음) | W2 | scope를 principal 기준으로(C-8a 결정과 함께) | +| C-2a | Required | QUARANTINE 판정도 staging bytes 삭제 예약 | 완료 | Wave 1–2 P4 (fcddab7e·Wave 2 커밋): `FinalizeUploadServiceTest.aQuarantineVerdictSchedulesNoCleanupOfTheStagedBytes` FAIL(`Expecting empty but was: [CleanupItem[... FAILED_VERIFICATION_CONTENT ...]]`)→PASS. `src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/upload/DefaultFinalizeUploadService.java:272`(REJECTED일 때만 staging cleanup 예약, QUARANTINE은 세션만 terminal) | - | `applyNonAcceptVerdict`에서 cleanup enqueue를 REJECT일 때만(QUARANTINE은 quarantine 영역으로 이동 또는 보존) | +| C-2b | Required | staging cleanup이 레코드 상태 재확인 없이 삭제 | 완료 | Wave 1–2 P4 (fcddab7e·Wave 2 커밋): `CleanupServiceTest.aStagingItemForAQuarantinedFileLeavesTheStagedBytesInPlace` FAIL(`Expecting value to be true but was false`)→PASS. `.../cleanup/DefaultCleanupService.java:197`(QUARANTINED면 삭제 없이 done) | - | `cleanStaging`에서 fileId 레코드를 읽어 QUARANTINED면 skip | +| C-3a | Required | `reconcileRecoverable`·`RecoveryQueue`를 소비하는 곳 없음 | 완료 | Wave 1–2 P4 (fcddab7e·Wave 2 커밋): `FileserverCleanupWorkerTest.aRunReconcilesTheFilesWhoseOutcomeWasLeftOpen`, `aFailingCleanupBatchStillLetsReconciliationRun` — FAIL은 컴파일 실패(`constructor FileserverCleanupWorker ... cannot be applied`, reconciliation을 받을 방법이 없었음)→PASS. 별도 worker 대신 기존 `FileserverCleanupWorker`가 매 회차 cleanup 뒤 `reconcileRecoverable(maxItems)`를 독립 try로 실행(`src/composition/fileserver-platform/.../FileserverCleanupWorker.java`, `FileserverCleanupConfiguration`). 같은 `cleanup.enabled` 스위치를 쓴다(설정 키 추가 없음). recovery queue는 pending 중복을 갱신만 한다(`JpaRecoveryQueue.enqueue`) | - | `src/composition/fileserver-platform`에 `FileserverCleanupWorker`와 같은 방식으로 `reconcileRecoverable`을 주기 호출하는 worker 추가 | +| C-3b | Required | content key가 READY 커밋에만 기록 → pre-publish 복구 경로 도달 불가 | 완료 | Wave 1–2 P4 (fcddab7e·Wave 2 커밋): `FinalizeUploadServiceTest.theContentKeyIsRecordedBeforeThePublishIsAttempted` FAIL(`Expecting Optional to contain a value but it was empty`)→PASS. `DefaultFinalizeUploadService.java:214`(UPLOADED→VERIFYING 전이에 `FileRecordMutation.intendedContentKey`), `UploadContentGateway.newContentKey()`, `FinalizeContentCommand.contentKey`(기존 4인자 생성자 유지), publisher가 그 key로 게시(`AtomicMoveContentPublisher`, `MetadataPointerContentPublisher`). 부수 조치: 검증은 staged bytes를 읽도록 `VerificationRequest.contentKey=empty`(미게시 key로 읽으면 RETRY 고착), 미게시 key의 content 정리는 quota를 회수하지 않음(`DefaultCleanupService.java:275`, `publishedAt` 있을 때만) | - | `ContentKey`를 application이 정해 VERIFYING에 먼저 저장(write-ahead)한 뒤 move | +| C-3c | Required | publish의 `AmbiguousCompletionException`이 recovery queue로 안 감 | 완료 | Wave 1–2 P4 (fcddab7e·Wave 2 커밋): `FinalizeUploadServiceTest.anAmbiguousPublishIsQueuedForRecovery` FAIL(`... to contain entry PUBLISH_UNCONFIRMED`)→PASS. `DefaultFinalizeUploadService.java:130`(inNew로 recovery 기록 후 재던짐, 기록 실패는 suppressed) | - | `publish` 호출을 감싸 ambiguous면 `recoveryQueue.enqueue`(`inNew`) 후 재던짐 | +| C-3d | Consider | (리뷰 외, `6d27356e` 회귀) 보상·복구용 REQUIRES_NEW 쓰기의 30초 상한 소실 | 완료 | Wave 1–2 P4 (fcddab7e·Wave 2 커밋): NEW-3과 같은 결함. `TransactionPort`에 timeout 옵션이 없어 가장 작은 변경으로 `SpringTransactionPort`의 REQUIRES_NEW template에 30초 설정. `SpringTransactionPortTest.inNewBoundsItsTransactionToThirtySeconds` FAIL(`expected: 30 but was: -1`)→PASS. `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/transaction/SpringTransactionPort.java:62`. 포트 시그니처 변경 없음(구현·fake 수정 불필요). `verifyJpaApiSurface` OK | - | `SpringTransactionPort`의 `requiresNewTemplate`에 timeout(30s) 설정(`inNew`는 outbox·audit·보상 전용이라 공통 상한으로 충분) | +| C-4a | Required | cancel이 READY 파일에도 staging cleanup만 예약 → 게시된 bytes·quota 영구 잔존 | 완료 | Wave 1–2 P4 (fcddab7e·Wave 2 커밋): `UploadApplicationServiceTest.cancellingAPublishedUploadQueuesItsContentForReclamation` FAIL(`[CANCELLED_STAGING] to contain [DELETED_READY_CONTENT]`)→PASS. cancel이 `FileRetirement.retire(record, uploadId)`를 쓴다(`DefaultUploadApplicationService.java:265`): content key가 있으면 content 정리도 예약. 409 거부 대신 retire 재사용을 택함(삭제와 같은 DELETE 인가를 이미 거침) | - | UPLOADED 이후 cancel은 거부(409)하거나 `DefaultFileLifecycleService.delete`(`:71-104`)의 retire 경로 재사용 | +| C-4b | Required | staging cleanup이 DELETING→DELETED 전이를 안 함 → 취소된 upload 전부 DELETING 고착 | 완료 | Wave 1–2 P4 (fcddab7e·Wave 2 커밋): `CleanupServiceTest.aCancelledUploadReachesDeletedOnceItsStagingIsReclaimed` FAIL(`expected: DELETED but was: DELETING`)→PASS. `DefaultCleanupService.java:218`(staging 정리와 같은 트랜잭션에서 content key 없는 DELETING→DELETED). quota release는 넣지 않았다: reservation은 upload에 연결되지 않은 scope 단위 TTL 장부이고 만료로 정리된다(`JpaQuotaCommitGateway` 설계 주석) | - | `cleanStaging` 끝에서 레코드 DELETING→DELETED(+quota release)를 같은 트랜잭션으로 | +| C-5a | Required | 만료 upload를 치우는 sweep 없음(`EXPIRED_UPLOAD` 생산자 0) | 완료 | Wave 1–2 P4 (fcddab7e·Wave 2 커밋): `CleanupServiceTest.anUploadPastItsExpiryIsMovedToExpired` FAIL(`expected: EXPIRED but was: UPLOADING`)→PASS, `theStagedBytesOfAnExpiredUploadAreReclaimed` FAIL(`Expecting value to be false but was true`)→PASS, W2에서 `anUploadThatExpiredBeforeItsFirstAppendIsExpiredToo` FAIL(`expected: EXPIRED but was: CREATED`)→PASS. `DefaultCleanupService.java:125`(batch 시작 시 만료 열린 세션 terminal → CREATED/UPLOADING/FAILED 레코드 EXPIRED + `EXPIRED_UPLOAD` 예약). 반복 조회로 limit가 막히지 않게 `findExpired`는 terminal 세션 제외: `src/adapter/outbound/persistence-fileserver/.../repository/JpaUploadSessionRepository.java:19`, PG `PostgreSqlFileserverMetadataStoreIntegrationTest.aTerminatedExpiredSessionIsNotListedAgain` PASS | - | cleanup worker에 `expiresAt` 지난 session을 EXPIRED로 전이하고 `EXPIRED_UPLOAD`를 예약하는 sweep 추가 | +| C-5b | Required | orphan 항목은 삭제 없이 done, orphan scan은 contentRoot만 | 완료 | Wave 1–2 P4 (fcddab7e·Wave 2 커밋): `CleanupServiceTest.aRetiredOrphanIsPurgedFromQuarantine` FAIL(`Expecting value to be false but was true`)→PASS. `CleanupContentGateway.purgeQuarantined` 추가, `DefaultCleanupService.java:243`, `LocalCleanupContentGateway.java:41`(ledger를 다시 확인하는 `OrphanScanPort.purgeQuarantined`에 위임). staging root scan은 하지 않았다(더 작은 수정): staging 객체는 항상 세션이 있고(세션 commit 뒤에만 생성), 이제 모든 세션 끝(cancel·reject·C-5a 만료, CREATED 포함)이 staging 정리를 예약하므로 scan이 찾을 대상은 대기 중인 정리 항목뿐이다. 예외 한 가지는 P4-new-4 | - | orphan 항목은 quarantine 경로의 object를 실제 삭제; staging root도 scan | +| C-5c | Required | `Upload-Defer-Length: 1` 수락하지만 길이를 확정할 방법 없음 → 끝나지 않는 upload | 완료 | Wave 1–2 P4 (fcddab7e·Wave 2 커밋): `TusProtocolContractTest.aCreateThatDefersItsLengthIsRefusedBecauseTheExtensionIsNotOffered` FAIL(`Status expected:<400> but was:<201>`)→PASS. `src/adapter/inbound/web-fileserver/.../tus/TusRequestParser.java:65`. 기존 `aDeferredLengthUploadIsNeverAutoFinalized`는 이 테스트로 대체 | - | 구현 전까지 `TusRequestParser.declaredLength`에서 `Upload-Defer-Length` 거부 | +| C-6 | Required | terminal 세션을 살아 있는 세션으로 취급 | 완료 | Wave 1–2 P4 (fcddab7e·Wave 2 커밋): `UploadApplicationServiceTest.anAppendToACancelledUploadIsRefusedAsGone` FAIL(`Expecting actual throwable to be an instance of UploadExpiredException`, 실제는 재시도 가능한 lease 충돌)→PASS, `theStatusOfACancelledUploadIsGone` FAIL(`Expecting actual not to be null`)→PASS. `DefaultUploadApplicationService.java:332`(terminal → `UPLOAD_EXPIRED` 410), status도 `requireActiveSession`(`:245`) | - | `requireActiveSession`·`status`에서 `terminal()`이면 410(또는 404) | +| C-7a | Required | append마다 prefix 전체를 다시 해시(O(n²) IO) | 완료 | Wave 1–2 P4 (fcddab7e·Wave 2 커밋): `LocalAppendEngineTest.aReattachedHandleResumesTheRunningDigestInsteadOfRereadingThePrefix` FAIL(`Expecting Optional to contain a value but it was empty`)→PASS, 보호 테스트 `aRolledBackAppendLeavesTheCachedDigestDescribingOnlyTheSurvivingPrefix` PASS. `src/adapter/outbound/fileserver/.../local/LocalBlockingContentStore.java:61,187,437`(uploadId별 LRU 1024, 복사본으로 넣고 꺼냄, 실패·finalize·discard 시 제거), `StreamingDigest.copy()` | - | uploadId별 상한 있는 digest 캐시(offset 키)를 store에 두고 `reattach`가 재사용 | +| C-7b | Required | finalize가 파일을 두 번 더 읽고 servlet 스레드에서 실행 | 완료 | Wave 1–2 P4 (fcddab7e·Wave 2 커밋): `TusProtocolContractTest.theCompletingPatchFinalizesOnTheTransferExecutor` FAIL(`"Test worker" to start with "fs-transfer-"`)→PASS. `TusController.java:180`, draft-12도 동일(`Draft12UploadController.java:151`). 파일 재읽기: C-7a 캐시로 `stagingDigest`가 보통 디스크를 읽지 않으므로 finalize의 전체 읽기는 `verifyStaged` 1회로 줄었다. `stagingDigest` 결과를 `verifyStaged`에 넘겨 그 1회까지 없애는 것은 하지 않았다 — 디스크에서 다시 증명한다는 게시 설계(`ContentPublishVerification` 주석)를 버리게 되고, finalize는 writer lease 없이 실행되기 때문 | - | `stagingDigest` 결과를 `verifyStaged`에 넘겨 재사용, finalize 호출을 `transferExecutor` 안으로 | +| C-8a | Required | 인가가 역할 등급만 보고 파일 owner가 없음 | 완료 | Wave 1–2 P4 (fcddab7e·Wave 2 커밋): 결정 14. `RoleBasedFileAccessPolicyTest.aCallerWithTheSameRolesIsDeniedAFileSomebodyElseOwns`(READ_METADATA·DOWNLOAD·APPEND·FINALIZE·DELETE·COPY·MOVE 7건), `theSamePrincipalInAnotherTenantIsDeniedTheFile`, `aFileWithNoRecordedOwnerIsDeniedToEveryDataPlaneCaller` 모두 FAIL(`Expecting actual not to be null` = 거부 안 됨)→PASS, `theOwnerIsGrantedEveryDataOperationWithoutAnException` PASS. `src/adapter/outbound/fileserver/.../security/RoleBasedFileAccessPolicy.java:74,86`. 모델: `FileOwner`(`.../api/metadata/FileOwner.java`), `FileRecord.owner`/`FileDescriptor.owner`/`FileRecordDraft.owner`, 생성 시 `context.subject().asOwner()`(`DefaultUploadApplicationService`, copy는 복사한 사람). 저장: `V5__fileserver_file_owner.sql`(`owner_principal_id varchar(256)`, `owner_tenant_id varchar(64)`), `FileEntity`·`FileEntityMapper`·`JpaFileMetadataStore.insert`. PG `aNewRecordKeepsTheOwnerItWasCreatedFor` PASS, `UploadApplicationServiceTest.aCreatedFileIsOwnedByTheCallerInItsTenant` PASS. **기존 행(owner NULL) 처리:** data plane에서는 누구에게도 허용하지 않는다(fail closed). 소유자를 추론할 근거가 없고, 역할 모델상 남의 파일에 대한 조치는 감사되는 관리 plane(force-delete·reverify, descriptor 없음)이 담당하기 때문이다. **ADMIN 예외:** 두지 않는다. 기존 역할 모델이 "admin은 write를 상속하지 않는다"이므로 data plane 연산은 admin 역할이어도 소유자 검사를 받는다. **anonymous read**가 켜진 배포는 전 파일 공개를 선택한 것이라 read 등급에서 소유자 검사를 건너뛴다(기존 의미 유지). **tenant:** subject 속성 `tenant`(`FileAccessSubject.TENANT_ATTRIBUTE`)와 비교한다. web 플랫폼은 아직 tenant를 해석하지 않아(`WebRequestContext`를 만드는 곳 없음) 현재는 양쪽 모두 비어 있고, transport가 속성을 채우면 그대로 적용된다. 문서 `docs/fileserver/security.md` 「Authorization」 | - | 결정(2026-09-25): 소유자 검사 추가 — `FileRecord`에 `ownerPrincipalId`(새 migration), 기본 정책이 소유자·tenant 검사 | +| C-8b | Required | `FileOperation.FINALIZE`를 인가하지 않음 | 완료 | Wave 1–2 P4 (fcddab7e·Wave 2 커밋): `FinalizeUploadServiceTest.aCallerTheFinalizeOperationIsDeniedToPublishesNothing` FAIL(`Expecting actual not to be null`)→PASS. `DefaultFinalizeUploadService.java:109`(digest·검증·publish 전에 FINALIZE 인가, 정책은 생성자 주입 — `composition/.../FileserverUploadServiceConfiguration`) | - | `DefaultFinalizeUploadService.finalizeUpload`에서 FINALIZE authorize(또는 enum 값 삭제+문서 정정) | +| C-8c | Required | admin 조회가 READ_METADATA 등급으로 인가 | 완료 | Wave 1–2 P4 (fcddab7e·Wave 2 커밋): `FileserverAdminServiceTest.aCallerDeniedAdminReadsCannotSeeStorageHealth` FAIL(`Expecting actual not to be null`)→PASS. 새 `FileOperation.ADMIN_READ`(admin 등급, `RoleBasedFileAccessPolicy.java:102`), `DefaultFileserverAdminService.java:206`. `RoleBasedFileAccessPolicyTest.adminReadsNeedTheAdminRoleRatherThanTheReadRole` PASS | - | admin 조회용 ADMIN 등급 operation으로 authorize | +| C-9a | Required | 업로드 동시성 한도 초과를 `QUOTA_EXCEEDED`(413, 재시도 불가)로 응답 | 완료 | Wave 1–2 P4 (fcddab7e·Wave 2 커밋): `TransferAdmissionControllerTest.anExhaustedScopeIsARetryableAdmissionRejection` FAIL(`... to be an instance of TransferAdmissionRejectedException`)→PASS. `src/application-fileserver/.../quota/DefaultTransferAdmissionController.java:61` | - | scope 한도 초과도 `TRANSFER_ADMISSION_REJECTED`(429, retryable)로 | +| C-9b | Required | 모든 업로드가 기본 namespace 한 scope → 노드당 동시 업로드 4 | 완료 | Wave 1–2 P4 (fcddab7e·Wave 2 커밋): `UploadApplicationServiceTest.admissionIsCountedPerCallerRatherThanPerNamespace` FAIL(`expected: null but was: QuotaExceededException`)→PASS. `DefaultUploadApplicationService.java:280`(`QuotaScope.ofPrincipal`, create·append). quota 예약은 namespace 그대로. principal 수가 무한하므로 표가 차면 유휴(모든 permit 반환) semaphore를 버린다(`DefaultTransferAdmissionController.java:123`, 조회+획득을 한 lock 안에서): `newCallersStillGetTheirOwnScopeOnceTheTableHasFilledWithIdleOnes` FAIL(`expected: null but was: QuotaEx...`)→PASS. 기존 `scopeSemaphoreRegistryIsBoundedAndOverflowScopesShareConservativeCapacity`는 이 동작과 모순이라 `theScopeRegistryStaysBoundedAsCallersComeAndGo`로 교체. env 설명 갱신(`docs/registries/env-keys.yaml` `..._SCOPE_UPLOAD_PERMITS`, `docs/fileserver/configuration.md`) | - | scope를 principal 기준으로(C-8a 결정과 함께) | | C-10 / S2-#11 | Required | persistence-fileserver의 경쟁 조건 SQL에 leaf 테스트 0 | 남음 | `git ls-files src/adapter/outbound/persistence-fileserver` → `build.gradle`·lockfile·main만; 실 SQL 검증은 `src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/.../readiness/PostgreSqlFileserver*IntegrationTest.java` 3개(다른 leaf)
S2-#11: `persistence-jpa/build.gradle:94-95,157-159`, jpa `postgresqlIntegrationTest/.../readiness/PostgreSqlFileserver*IntegrationTest.java` 3개 + `FileserverJpaTestContext`, `persistence-fileserver/.../JpaFileQuotaService.java:88,93` 테스트용 public, `persistence-fileserver/src`에 test 없음·README/CLAUDE.md 없음 | W4 | persistence-fileserver 자체 strict lane에 acquire-after-terminate, claim-while-leased, stale-token settlement 테스트 추가(PG 테스트 이관)
S2-#11: persistence-fileserver에 자기 IT source set(`testFixtures(project(':adapter:outbound:persistence-jpa'))` 재사용)으로 이동, 짧은 CLAUDE.md 추가 | -| C-11 | Consider | Draft-12 create가 POST body를 버리고 Content-Length를 최종 길이로 사용 | 남음 | `src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/draft12/Draft12UploadController.java:82-99`, `:171-174` | W2 | `declaredLength`를 `Upload-Length` 헤더에서 읽고, POST body가 있으면 append | +| C-11 | Consider | Draft-12 create가 POST body를 버리고 Content-Length를 최종 길이로 사용 | 완료 | Wave 1–2 P4 (fcddab7e·Wave 2 커밋): `Draft12ProtocolTest.aCreationBodyIsStoredAsTheFirstPartOfTheUpload` FAIL(`expected: "abc" but was: ""`)→PASS, `theFinalLengthComesFromUploadLengthRatherThanTheCreationBody` FAIL(`OptionalLong[3] to contain 6L`)→PASS. `Draft12UploadController.java:109,205`(`Upload-Length` 헤더, POST body는 offset 0 append, `Upload-Complete: ?1`이면 finalize). 한계: Content-Length 없는 chunked POST body는 저장하지 않는다 | - | `declaredLength`를 `Upload-Length` 헤더에서 읽고, POST body가 있으면 append | | C-12a | Nit | outbound/fileserver CLAUDE.md가 의존 2개·bootstrap 소유로 서술 | 완료 | `src/adapter/outbound/fileserver/CLAUDE.md:15-27`(modules.json SSOT 참조로 교체, bootstrap 소유 문구 삭제). 커밋 `6d27356e` | - | - | | C-12b | Nit | composition build.gradle 주석이 HTTP는 `adapter:inbound:web`, 테이블은 `persistence-jpa`라고 서술 | 남음 | `src/composition/fileserver-platform/build.gradle:8-10`(실제 의존은 `:26` web-fileserver, `:32` persistence-fileserver) | W5 | 주석을 web-fileserver·persistence-fileserver로 | | C-12c | Nit | (리뷰 이후 새 drift) 같은 CLAUDE.md가 "default off"·Boot 4.0.0 | 남음 | `src/adapter/outbound/fileserver/CLAUDE.md:8`, `:19` vs `src/composition/fileserver-platform/src/main/resources/config/module-defaults/fileserver.yml:22`(`enabled: ...:true`), `src/gradle/libs.versions.toml:84` | W5 | "모듈이 있으면 켜짐, false로만 끔"과 4.0.8로 | @@ -224,31 +236,31 @@ | ID | 심각도 | 요약 | 상태 | 근거 | Wave | 수정 방향 | |---|---|---|---|---|---|---| -| D-1a | Required | staged `abort`가 operation 단계 확인 없이 provider `retire`(실제 삭제)부터 호출 → PUBLISHED면 삭제 후 `terminate`에서 예외, 참조·manifest는 PUBLISHED로 남음 | 남음 | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/kernel/StagedObjectPublicationKernel.java:257-269`, `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/control/ObjectOperationRecord.java:142-148`, `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/filesystem/LocalDevObjectDataStore.java:147-155`. kernel·control은 208077fd 이후 무변경 | W1 | `abort`에서 `loadOperation`을 먼저 하고 `REFERENCE_PUBLISH_IN_PROGRESS`/`PUBLISHED`면 거부, `retire` 전에 ABORT_IN_PROGRESS를 CAS로 기록 | -| D-1b | Required | `authorizeAbort`가 stage·handoff만 보고 operation 단계를 보지 않음 → release 또는 lease 만료 후 publish 단계에서도 abort 허가 | 남음 | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/kernel/ObjectPublicationHandoffService.java:101-113`, `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/control/ObjectPublicationHandoffRecord.java:136-139` | W1 | `ObjectPublicationHandoffService.authorizeAbort`에서 operation을 읽어 `REFERENCE_PUBLISH_IN_PROGRESS` 이후면 거부 | -| D-1c | Required | `finalizePublication`이 handoff를 읽지 않고 `ObjectFinalizeRequest`에 fence·claimant가 없음 → lease 만료 후 늦은 finalize가 abort와 경쟁 | 남음 | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/kernel/StagedObjectPublicationKernel.java:183-237`, `src/application-objectstorage/src/main/java/dev/caskeleton/application/objectstorage/request/ObjectFinalizeRequest.java:11-17` | W1 | `ObjectFinalizeRequest`에 `handoffFence`·`claimant` 추가, finalize가 활성·일치 lease를 요구. sample `ReconcilePosterImageUploadUseCase.java:105-112` 호출부 갱신 | -| D-2a | Required | 이미 release된 handoff에 `release` 재호출 시 "owner/fence is stale" 예외 → sample reconcile이 terminal READY마다 `releaseClaim`을 불러 두 번째 reconcile이 항상 실패 | 남음 | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/control/ObjectPublicationHandoffRecord.java:119-120,165-171`, `src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/application/poster/ReconcilePosterImageUploadUseCase.java:96-97,122-137` | W2 | `ObjectPublicationHandoffRecord.release`: 같은 fence·claimant로 이미 released면 쓰기 없이 REPLAYED, `releaseClaim`이 그 결과를 반환 | -| D-2b | Required | `authorizeAbort` 재호출이 idempotent하지 않음: 첫 호출이 `released=false`로 되돌려 lease가 남아 있으면 예외, 지났으면 새 revision을 쓰고 항상 APPLIED | 남음 | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/control/ObjectPublicationHandoffRecord.java:136-152`, `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/kernel/ObjectPublicationHandoffService.java:101-113` | W2 | 이미 `abortAuthorized`이고 fence가 같으면 쓰기 없이 REPLAYED | -| D-2c | Required | 두 번째 staged `abort`는 `retire`=false로 "could not be retired" 예외 → sample `AbortPosterImageUploadUseCase`(IDEMPOTENT 표시)가 ABORT_AUTHORIZED에서 재호출하면 영구 정지 | 남음 | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/kernel/StagedObjectPublicationKernel.java:257-266`, `src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/application/poster/AbortPosterImageUploadUseCase.java:28,73-75,91-92` | W2 | `abort` 첫 단계에서 operation이 이미 ABORTED면 provider 호출 전 REPLAYED 반환(`DirectMultipartCoordinator.java:322-334` 방식) | -| D-3a | Required | stage: operation을 DATA_UPLOADED로 먼저 올리고 stage 기록은 나중 → 사이 crash 후 재시도가 "not uploadable", 데이터 고아·abort 불가 | 남음 | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/kernel/StagedObjectPublicationKernel.java:91-92,123-139` | W2 | operation 레코드를 단일 기준으로: 재시도에서 DATA_UPLOADED면 stage 기록을 create-or-require-same으로 보충하고 APPLIED/REPLAYED 반환 | -| D-3b | Required | verifyIntegrity: stage CAS 후 operation 전진 → 사이 crash 후 재시도는 REPLAYED로 끝나고 finalize가 "not finalizable" | 남음 | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/kernel/StagedObjectPublicationKernel.java:156-171,206-207` | W2 | `integrityVerified` REPLAYED 경로에서 operation이 INTEGRITY_VERIFIED(SCAN_CLEAN이면 SCAN_PENDING) 미만이면 전진을 마저 수행 | -| D-3c | Required | finalize: REFERENCE_PUBLISH_IN_PROGRESS로 올린 뒤 crash하면 모든 재시도가 "not finalizable" | 남음 | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/kernel/StagedObjectPublicationKernel.java:200-225` | W2 | `REFERENCE_PUBLISH_IN_PROGRESS`도 받아 idempotent `references.publish`를 다시 실행하고 PUBLISHED로 전진 | -| D-3d | Required | scan verdict: stage CAS 후 operation 전진(같은 순서), 재시도는 verdict가 같아 REPLAYED로 끝나 전진 누락 | 남음 | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/config/RoutingObjectScanMaintenanceAdapter.java:82-110` | W2 | REPLAYED여도 operation이 SCAN_PENDING이면 SCAN_CLEAN/QUARANTINED 전이를 마저 수행 | +| D-1a | Required | staged `abort`가 operation 단계 확인 없이 provider `retire`(실제 삭제)부터 호출 → PUBLISHED면 삭제 후 `terminate`에서 예외, 참조·manifest는 PUBLISHED로 남음 | 완료 | Wave 1–2 P2 (fcddab7e·Wave 2 커밋): `StagedObjectPublicationLifecycleTest$Abort.abortIsRejectedWhenTheOperationPublishedAfterAuthorization` FAIL(`Expecting message to be: "published operation cannot be aborted"` — 수정 전엔 데이터를 지운 뒤 terminate에서 다른 예외)→PASS, `…$Abort.rejectedAbortAfterPublicationKeepsThePublishedBytesReadable` FAIL(`ObjectStorageProviderException: local object is absent`)→PASS. `kernel/StagedObjectPublicationKernel.java:299-331`. 수정 방향과 다른 점: 새 상태 `ABORT_IN_PROGRESS`를 만들지 않고 `ABORTED` 자체를 retire 전에 CAS로 기록한다(영속 enum 추가 없음). 같은 fence 역할을 하고, 재시도는 D-2c 경로가 retire를 다시 시도해 crash 창을 메운다 | - | `abort`에서 `loadOperation`을 먼저 하고 `REFERENCE_PUBLISH_IN_PROGRESS`/`PUBLISHED`면 거부, `retire` 전에 ABORT_IN_PROGRESS를 CAS로 기록 | +| D-1b | Required | `authorizeAbort`가 stage·handoff만 보고 operation 단계를 보지 않음 → release 또는 lease 만료 후 publish 단계에서도 abort 허가 | 완료 | Wave 1–2 P2 (fcddab7e·Wave 2 커밋): `…$AuthorizeAbort.authorizeAbortIsRejectedOnceTheReferenceIsPublished` FAIL(`Expecting actual not to be null`)→PASS. `kernel/ObjectPublicationHandoffService.java:101-123` | - | `ObjectPublicationHandoffService.authorizeAbort`에서 operation을 읽어 `REFERENCE_PUBLISH_IN_PROGRESS` 이후면 거부 | +| D-1c | Required | `finalizePublication`이 handoff를 읽지 않고 `ObjectFinalizeRequest`에 fence·claimant가 없음 → lease 만료 후 늦은 finalize가 abort와 경쟁 | 완료 | Wave 1–2 P2 (fcddab7e·Wave 2 커밋): `…$FinalizePublication.finalizeAfterAbortWasAuthorizedIsRejected` FAIL(`Expecting actual not to be null`)→PASS. `ObjectFinalizeRequest`에 `handoffFence`·`claimant` 추가(`application-objectstorage/.../request/ObjectFinalizeRequest.java:15-32`), finalize가 활성·일치 lease 요구(`StagedObjectPublicationKernel.java:247-254`, `control/ObjectPublicationHandoffRecord.java:176` `heldBy`). 이미 PUBLISHED인 replay는 lease를 보지 않는다(release 뒤 reconcile 재호출이 계속 REPLAYED). sample 호출부 `sample-portfolio/.../poster/ReconcilePosterImageUploadUseCase.java:106-114` | - | `ObjectFinalizeRequest`에 `handoffFence`·`claimant` 추가, finalize가 활성·일치 lease를 요구. sample `ReconcilePosterImageUploadUseCase.java:105-112` 호출부 갱신 | +| D-2a | Required | 이미 release된 handoff에 `release` 재호출 시 "owner/fence is stale" 예외 → sample reconcile이 terminal READY마다 `releaseClaim`을 불러 두 번째 reconcile이 항상 실패 | 완료 | Wave 1–2 P2 (fcddab7e·Wave 2 커밋): `…$ReleaseClaim.repeatedReleaseByTheSameClaimantReplays` FAIL(`IllegalStateException: publication handoff owner/fence is stale`)→PASS. `ObjectPublicationHandoffRecord.java:121-126`, `ObjectPublicationHandoffService.java:97,125-137`(바뀐 게 없으면 쓰지 않고 REPLAYED) | - | `ObjectPublicationHandoffRecord.release`: 같은 fence·claimant로 이미 released면 쓰기 없이 REPLAYED, `releaseClaim`이 그 결과를 반환 | +| D-2b | Required | `authorizeAbort` 재호출이 idempotent하지 않음: 첫 호출이 `released=false`로 되돌려 lease가 남아 있으면 예외, 지났으면 새 revision을 쓰고 항상 APPLIED | 완료 | Wave 1–2 P2 (fcddab7e·Wave 2 커밋): `…$AuthorizeAbort.repeatedAuthorizeAbortForTheSameFenceReplays` FAIL(`IllegalStateException: active or stale handoff cannot authorize abort`)→PASS. `ObjectPublicationHandoffRecord.java:142-147` | - | 이미 `abortAuthorized`이고 fence가 같으면 쓰기 없이 REPLAYED | +| D-2c | Required | 두 번째 staged `abort`는 `retire`=false로 "could not be retired" 예외 → sample `AbortPosterImageUploadUseCase`(IDEMPOTENT 표시)가 ABORT_AUTHORIZED에서 재호출하면 영구 정지 | 완료 | Wave 1–2 P2 (fcddab7e·Wave 2 커밋): `…$Abort.repeatedAbortReplays` FAIL(`IllegalStateException: publication terminal transition is invalid`)→PASS. `StagedObjectPublicationKernel.java:317-323`. 수정 방향과 다른 점: provider 호출 전에 바로 REPLAYED를 주지 않고 retire를 한 번 더 시도한 뒤(이미 없으면 정상) REPLAYED — D-1a에서 ABORTED를 retire보다 먼저 기록하므로, 그 사이 crash가 바이트를 고아로 남기지 않게 하려는 것 | - | `abort` 첫 단계에서 operation이 이미 ABORTED면 provider 호출 전 REPLAYED 반환(`DirectMultipartCoordinator.java:322-334` 방식) | +| D-3a | Required | stage: operation을 DATA_UPLOADED로 먼저 올리고 stage 기록은 나중 → 사이 crash 후 재시도가 "not uploadable", 데이터 고아·abort 불가 | 완료 | Wave 1–2 P2 (fcddab7e·Wave 2 커밋): `…$Stage.stageRetriedAfterACrashBeforeTheStageRecordStagesTheObject` FAIL(`IllegalStateException: stage operation is not uploadable`)→PASS. `StagedObjectPublicationKernel.java:84-127`(DATA_UPLOADED면 저장된 객체를 inspect해서 stage 기록을 다시 만들고, 동시 재시도 충돌은 REPLAYED) | - | operation 레코드를 단일 기준으로: 재시도에서 DATA_UPLOADED면 stage 기록을 create-or-require-same으로 보충하고 APPLIED/REPLAYED 반환 | +| D-3b | Required | verifyIntegrity: stage CAS 후 operation 전진 → 사이 crash 후 재시도는 REPLAYED로 끝나고 finalize가 "not finalizable" | 완료 | Wave 1–2 P2 (fcddab7e·Wave 2 커밋): `…$FinalizePublication.finalizeSucceedsWhenVerifyWasRetriedAfterACrashBeforeTheOperationAdvanced` FAIL(`IllegalStateException: staged operation is not finalizable`)→PASS. `StagedObjectPublicationKernel.java:192-229`(REPLAYED 경로도 operation을 INTEGRITY_VERIFIED/SCAN_PENDING까지 전진) | - | `integrityVerified` REPLAYED 경로에서 operation이 INTEGRITY_VERIFIED(SCAN_CLEAN이면 SCAN_PENDING) 미만이면 전진을 마저 수행 | +| D-3c | Required | finalize: REFERENCE_PUBLISH_IN_PROGRESS로 올린 뒤 crash하면 모든 재시도가 "not finalizable" | 완료 | Wave 1–2 P2 (fcddab7e·Wave 2 커밋): `…$FinalizePublication.finalizeRetriedAfterACrashInReferencePublicationPublishes` FAIL(`staged operation is not finalizable`)→PASS. `StagedObjectPublicationKernel.java:262-285` | - | `REFERENCE_PUBLISH_IN_PROGRESS`도 받아 idempotent `references.publish`를 다시 실행하고 PUBLISHED로 전진 | +| D-3d | Required | scan verdict: stage CAS 후 operation 전진(같은 순서), 재시도는 verdict가 같아 REPLAYED로 끝나 전진 누락 | 완료 | Wave 1–2 P2 (fcddab7e·Wave 2 커밋): `…$FinalizePublication.finalizeSucceedsWhenTheCleanVerdictWasRetriedAfterACrash` FAIL(`staged operation is not finalizable`)→PASS. `config/RoutingObjectScanMaintenanceAdapter.java:92-115` | - | REPLAYED여도 operation이 SCAN_PENDING이면 SCAN_CLEAN/QUARANTINED 전이를 마저 수행 | | D-4 | Required | staged kernel·handoff 서비스에 동작 테스트 없음 | 남음 | `src/adapter/outbound/objectstorage/src/test/java/dev/caskeleton/adapter/outbound/objectstorage/kernel/StagedObjectPublicationKernelTest.java:11-23`(`ObjectScanVerdictPolicy`만), `src/adapter/outbound/objectstorage/src/test/java/dev/caskeleton/adapter/outbound/objectstorage/kernel/ObjectPublicationHandoffRaceTest.java:23-24`(takeover 1건), `src/app-bootstrap/src/integrationTest/java/dev/caskeleton/bootstrap/integration/objectstorage/ObjectStorageCompositionIntegrationTest.java:71-86`(legacy put/get), `src/sample-portfolio/src/test/java/dev/caskeleton/sample/portfolio/application/poster/PosterImagePublicationWorkflowTest.java:85-86`(포트 mock) | W4 | local-dev provider로 stage→verify→finalize→release, abort·replay 전 흐름 테스트 + `ObjectControlStore` 래퍼로 두 쓰기 사이 실패 주입(D-1~D-3 회귀 테스트 겸용) | -| D-5 / X1-#8b | Consider | local control store `create`가 `CREATE_NEW` 후 쓰기 → 동시 reserve가 빈/부분 파일을 decode 실패, 쓰기 중 crash면 키 영구 손상 | 남음 | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/filesystem/LocalDevObjectControlStore.java:51-65`
X1-#8b: `objectstorage/.../filesystem/LocalDevObjectControlStore.java:51-65`(비교 대상이던 `LocalPublicationJournal`은 삭제) | W2 | temp 파일에 쓰고 `force` 후 `Files.createLink`로 게시(`LocalDevObjectDataStore.java:55-62`와 같은 방식)
X1-#8b: temp 파일에 다 쓰고 `force` 후 원자적으로 게시해 부분 파일이 보이지 않게 + 동시 create 테스트 | -| D-6a | Consider | legacy filesystem adapter `get`이 크기 제한 없이 `Files.readAllBytes` (L3 closure 기록과 코드 불일치) | 남음 | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/FilesystemObjectStorageAdapter.java:71` | W1 | 읽기 전 `Files.size`를 설정 최대값과 비교해 초과 시 거부 | -| D-6b | Consider | legacy `put`이 `target.toUri()`(서버 절대 경로 `file:///…`)를 반환 → sample이 HTTP 응답 `location`에 노출, sample 기본 설정이 이 backend | 남음 | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/FilesystemObjectStorageAdapter.java:61`, `src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/adapter/inbound/web/mapper/PosterWebMapper.java:35`, `src/sample-portfolio/src/main/resources/application.yml:321-326` | W1 | `FilesystemObjectStorageAdapter.put`이 논리 URI(`objectstorage:` + key)를 반환 | -| D-7a | Consider | direct/multipart 코드 약 3.2k줄이 main 호출자 0(`DirectTransferCoordinator`, `DirectMultipartCoordinator`, `ManagedMultipartCoordinator`, `MultipartOperationResolver`, `S3ObjectOperationResolver`, `ObjectOperationResolutionService`, `ObjectOperationEpochRecord`, `SelectedObjectStorageProviderFactory.{managedMultipart,directTransfer,directMultipart}Provider`, 포트 `DirectObjectUploadPort`·`DirectObjectDownloadGrantPort`·`DirectMultipartUploadPort`) | 남음 | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/{direct,multipart}/`(2,053줄) + S3 direct/multipart 타입(1,160줄), main 참조 0·테스트만(`src/adapter/outbound/objectstorage/src/test/java/dev/caskeleton/adapter/outbound/objectstorage/s3/S3ProviderCompositionTest.java:132,140`). `docs/capability-status.md` 「제거된 코드」 표에 없음 | W3 | D1 규칙(호출자 0 삭제)대로 `direct/`·`multipart/`·S3 direct/multipart provider·`Direct*Port`를 삭제하고 제거 표에 기록 | -| D-7b | Consider | 빈 자리 타입: `RoutingObjectDirectGrantAdapter`(참조 0), 빈 `@Configuration` `ObjectStorageMaintenanceCapabilityConfig` | 남음 | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/config/RoutingObjectDirectGrantAdapter.java:1-10`, `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/config/ObjectStorageMaintenanceCapabilityConfig.java:10`, `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/ObjectStorageAutoConfiguration.java:25` | W3 | 두 타입 삭제, `ObjectStorageAutoConfiguration` import 목록에서 제거 | -| D-7c | Consider | 구현 없는 포트 `ObjectPurgeMaintenancePort` | 남음 | `src/application-objectstorage/src/main/java/dev/caskeleton/application/objectstorage/port/ObjectPurgeMaintenancePort.java` (main 구현 0, 테스트 참조만) | W3 | 포트 삭제 | +| D-5 / X1-#8b | Consider | local control store `create`가 `CREATE_NEW` 후 쓰기 → 동시 reserve가 빈/부분 파일을 decode 실패, 쓰기 중 crash면 키 영구 손상 | 완료 | Wave 1–2 P2 (fcddab7e·Wave 2 커밋): `LocalDevObjectStorageRecoveryTest.aConcurrentReaderNeverSeesAPartiallyCreatedControlRecord` FAIL(`Expecting empty but was: [ObjectControlCorruptionException: control record is corrupt …]`)→PASS. `filesystem/LocalDevObjectControlStore.java:51-78`(temp 파일에 다 쓰고 `force` 후 `Files.createLink`). 동시성 재현이라 수정 전 FAIL은 확률적이다(300회 create/read 중 부분 파일 읽기 발생). 수정 뒤에는 부분 파일이 구조상 보이지 않는다 | - | temp 파일에 쓰고 `force` 후 `Files.createLink`로 게시(`LocalDevObjectDataStore.java:55-62`와 같은 방식)
X1-#8b: temp 파일에 다 쓰고 `force` 후 원자적으로 게시해 부분 파일이 보이지 않게 + 동시 create 테스트 | +| D-6a | Consider | legacy filesystem adapter `get`이 크기 제한 없이 `Files.readAllBytes` (L3 closure 기록과 코드 불일치) | 완료 | Wave 1–2 P2 (fcddab7e·Wave 2 커밋): `FilesystemObjectStorageAdapterTest.getRejectsAStoredObjectLargerThanTheReadCeiling` FAIL(`Expecting actual not to be null`)→PASS, `…putRejectsContentLargerThanTheReadCeiling` FAIL→PASS. `FilesystemObjectStorageAdapter.java:33,57,81`. 수정 방향과 다른 점: "설정 최대값" 대신 고정 상한 16 MiB 상수(`ponytail:` 주석). legacy seam(`@Deprecated(forRemoval=true)`)에는 크기 설정 키가 없고, 삭제 예정 seam에 새 설정 키·env 문서를 늘리지 않으려고 상수로 했다. put도 같은 상한으로 막아 "쓴 것은 항상 다시 읽힌다"를 유지 | - | 읽기 전 `Files.size`를 설정 최대값과 비교해 초과 시 거부 | +| D-6b | Consider | legacy `put`이 `target.toUri()`(서버 절대 경로 `file:///…`)를 반환 → sample이 HTTP 응답 `location`에 노출, sample 기본 설정이 이 backend | 완료 | Wave 1–2 P2 (fcddab7e·Wave 2 커밋): `FilesystemObjectStorageAdapterTest.putReturnsALogicalLocationThatHidesTheServerPath` FAIL(`expected: objectstorage:posters/7/image but was: file:///tmp/junit-…/posters/7/image`)→PASS. `FilesystemObjectStorageAdapter.java:71`(`logicalLocation`). 결함을 굳히던 특성 테스트는 `LegacyObjectStorageBehaviorTest.filesystemReceiptNamesTheKeyInsteadOfTheServerPath`로 바꿈 | - | `FilesystemObjectStorageAdapter.put`이 논리 URI(`objectstorage:` + key)를 반환 | +| D-7a | Consider | direct/multipart 코드 약 3.2k줄이 main 호출자 0(`DirectTransferCoordinator`, `DirectMultipartCoordinator`, `ManagedMultipartCoordinator`, `MultipartOperationResolver`, `S3ObjectOperationResolver`, `ObjectOperationResolutionService`, `ObjectOperationEpochRecord`, `SelectedObjectStorageProviderFactory.{managedMultipart,directTransfer,directMultipart}Provider`, 포트 `DirectObjectUploadPort`·`DirectObjectDownloadGrantPort`·`DirectMultipartUploadPort`) | 완료 | Wave 1–2 P2 (fcddab7e·Wave 2 커밋): D 커밋 `2c7b3d25`(+ 문서 후속 `f8bf7b6d`). `direct/`·`multipart/` 패키지, S3 direct·multipart·presigner·operation resolver, `ObjectOperationResolutionService`·`ObjectOperationEpochRecord`, `Direct*Port` 3개와 그 요청·응답 타입 삭제(main −5,017줄, test −2,221줄). 삭제 전후 `git grep`으로 main 참조 0 확인(남은 언급은 `docs/reviews`·`docs/superpowers`·`docs/evidence`의 과거 기록뿐). 함께 정리: `SelectedObjectStorageProviderFactory`의 `Object` 슬롯 3개·생성자 3개(`config/SelectedObjectStorageProviderFactory.java`), S3 contribution의 presigner/direct/multipart 조립(`s3/S3ObjectStorageProviderContribution.java`), direct/multipart 전용 control record 5종과 codec 분기, `ObjectControlKeyCodec`·`ObjectHandleCodec` 메서드, 상태 enum. `DIRECT_UPLOAD`/`DIRECT_MULTIPART` capability 값은 제거해서, 설정에 남아 있으면 조용히 무시되지 않고 바인딩에서 실패한다. 남은 6개 control record family의 골든 digest는 삭제 전과 같다(`ObjectControlRecordCodecTest.everyRecordFamilyHasAFrozenGoldenEnvelopeDigest` PASS) — 유지되는 레코드의 저장 형식은 바뀌지 않았다. AWS lane `requires`에서 `AwsS3DirectMutationPreconditionsTest` 제거(`src/adapter/outbound/objectstorage/build.gradle:89`), workflow 입력 `run_protected_aws_direct_mutation` 제거(`.github/workflows/object-storage-qualification.yml`) | - | D1 규칙(호출자 0 삭제)대로 `direct/`·`multipart/`·S3 direct/multipart provider·`Direct*Port`를 삭제하고 제거 표에 기록 | +| D-7b | Consider | 빈 자리 타입: `RoutingObjectDirectGrantAdapter`(참조 0), 빈 `@Configuration` `ObjectStorageMaintenanceCapabilityConfig` | 완료 | Wave 1–2 P2 (fcddab7e·Wave 2 커밋): `2c7b3d25`. `RoutingObjectDirectGrantAdapter`, 빈 `ObjectStorageMaintenanceCapabilityConfig` 삭제, `ObjectStorageAutoConfiguration.java:21-25` import 목록에서 제거 | - | 두 타입 삭제, `ObjectStorageAutoConfiguration` import 목록에서 제거 | +| D-7c | Consider | 구현 없는 포트 `ObjectPurgeMaintenancePort` | 완료 | Wave 1–2 P2 (fcddab7e·Wave 2 커밋): `2c7b3d25`. `ObjectPurgeMaintenancePort`와 전용 `ObjectPurgeRequest` 삭제, `ObjectStoragePortContractTest`의 purge 단언을 `scannerAndStagedPublicationAreSeparatePrivilegeSurfaces`로 정리 | - | 포트 삭제 | | D-7d | Consider | S3 contribution이 쓰이지 않는 `S3ManagedMultipartProvider`(항상)와 presigner·direct provider(capability SUPPORTED일 때)를 생성 | 남음 | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/s3/S3ObjectStorageProviderContribution.java:110-158` | W3 | D-7a 삭제와 함께 `SelectedObjectStorageProviderFactory` 인자·생성 코드 제거 | | D-7e | Consider | S3 자격 증명을 `System::getenv`로 해석(`SecretSourcePort` 미사용, httpclient H6와 같은 패턴) | 남음 | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/s3/S3ObjectStorageProviderContribution.java:41` | W3 | `ObjectStorageCapabilityConfig`의 S3 contribution bean이 `SecretSourcePort`(`src/application-core/src/main/java/dev/caskeleton/application/outbound/SecretSourcePort.java`)를 받아 `S3ProviderBinding.SecretResolver`로 넘김 | | D-8a | Consider | managed 경로의 참조 게시(`persistPublishedReference`/`createOrRequireSame`)가 `ObjectReferencePublicationService`와 중복 | 남음 | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/config/RoutingObjectMutationAdapter.java:354-421`, `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/kernel/ObjectReferencePublicationService.java:20-92` | W3 | `RoutingObjectMutationAdapter`가 `ObjectReferencePublicationService.publish`를 호출하고 사본 삭제 | | D-8b | Consider | `objectId`/`sha256Hex` 계산 중복 | 남음 | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/config/RoutingObjectMutationAdapter.java:469-500`, `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/kernel/StagedObjectPublicationKernel.java:389-415` | W3 | `codec` 패키지에 identity helper 하나로 합치고 두 곳이 호출 | | D-8c | Consider | route token 파싱 `split("\\.")[1]`이 두 곳에 복사 | 남음 | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/config/RoutingObjectMutationAdapter.java:504`, `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/config/RoutingObjectReadAdapter.java:103` | W3 | `ObjectReferenceCodec.routeToken(..)` 추가 후 두 곳 교체 | | D-8d | Consider | `clock`을 주입받고도 `Instant.now()`를 12번 호출 | 남음 | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/config/RoutingObjectMutationAdapter.java:60,70`(clock), `:128,152,192,201,212,223,229,283,311,329,341,349`(`Instant.now()`) | W3 | `Instant.now()`를 `clock.instant()`로 교체 | -| D-9 | Consider | `inspect`가 scan 상태를 항상 NOT_REQUIRED로 보고(SCAN_CLEAN destination 포함) | 남음 | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/config/RoutingObjectReadAdapter.java:53` | W2 | destination `policySnapshot().publicationRequirement()`가 SCAN_CLEAN이면 CLEAN으로 보고 | -| D-10 | Nit | capability close가 역순이 아님(`Map.copyOf`는 순서 없음), 하나가 던지면 나머지 close를 건너뜀 | 남음 | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/config/ObjectStorageCapabilityAssembler.java:74,111-118` | W2 | provider를 생성 순서 `List`로 보관, 역순 close를 try/catch + `addSuppressed`로 | +| D-9 | Consider | `inspect`가 scan 상태를 항상 NOT_REQUIRED로 보고(SCAN_CLEAN destination 포함) | 완료 | Wave 1–2 P2 (fcddab7e·Wave 2 커밋): `…$Inspect.scanGatedReferenceReportsItsCleanVerdict` FAIL(`Expecting actual: Optional[NOT_REQUIRED]`)→PASS. `config/RoutingObjectReadAdapter.java:53-58`. 이 보고가 참이 되려면 managed publish의 scan 우회를 막아야 해서 P2-new-1을 함께 고쳤다 | - | destination `policySnapshot().publicationRequirement()`가 SCAN_CLEAN이면 CLEAN으로 보고 | +| D-10 | Nit | capability close가 역순이 아님(`Map.copyOf`는 순서 없음), 하나가 던지면 나머지 close를 건너뜀 | 완료 | Wave 1–2 P2 (fcddab7e·Wave 2 커밋): `ObjectStorageCapabilityAssemblerTest.closeReleasesProvidersInReverseCreationOrderAndKeepsEveryFailure` FAIL(`Expecting message to be: "close failed: a"`)→PASS. `config/ObjectStorageCapabilityAssembler.java:52-82,137-140`(provider를 생성 순서 `List`로 보관, 역순 close, 첫 실패에 나머지 `addSuppressed`; assemble 실패 경로도 같은 helper) | - | provider를 생성 순서 `List`로 보관, 역순 close를 try/catch + `addSuppressed`로 | | D-11a | Nit | leaf CLAUDE.md 허용 의존에서 `application-objectstorage` 누락 | 남음 | `src/adapter/outbound/objectstorage/CLAUDE.md:30` (registry: `application-core`, `shared-contract`, `application-objectstorage`) | W5 | 의존 나열을 지우고 registry 참조 한 줄만 남김 | | D-11b | Nit | CLAUDE.md가 object storage 포트·타입 위치를 `application-core`로 적음 | 남음 | `src/adapter/outbound/objectstorage/CLAUDE.md:17,40` | W5 | `application-objectstorage`로 수정. 같은 절 `:19` "disabled-by-default"도 현재 동작(`ObjectStorageCapabilityConfig`의 `matchIfMissing = true`, 있으면 켜짐)으로 | | D-11c | Nit | CLAUDE.md 기준 버전이 Boot 4.0.0(실제 4.0.8) | 남음 | `src/adapter/outbound/objectstorage/CLAUDE.md:8` | W5 | 버전 문구 삭제 또는 4.0.8 | @@ -259,46 +271,46 @@ | E-1c | Critical | outbox-storage `V1__initialize_or_adopt.sql` 적용 후 수정 | 해당 없음(코드 삭제) | 「제거된 코드」 표 "outbox V2 migration stream `jpa/outbox-storage`(V1·V2) … `applied-migrations.sha256`의 해당 4줄"(D2). `git ls-files '…/db/migration/jpa/outbox*'` 0건 | - | - | | E-1d | Critical | 적용된 migration 해시 고정 테스트 부재 | 완료 | `src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/migration/AppliedMigrationImmutabilityTest.java:29`(`appliedMigrationsKeepTheBytesTheyWereAppliedWith`), `:43`(`everyVersionedMigrationIsPinned`), 커밋 6d27356e | - | - | | E-2a | Critical | 같은 요청 재제출이 unique 위반 후 같은 트랜잭션 재조회 → PostgreSQL 25P02 | 완료 | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/operation/DurableOperationStoreAdapter.java:43-70`(`submitIfAbsent` 후 조회), `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/operation/DurableOperationJpaRepository.java:39-59`(`ON CONFLICT … DO NOTHING`), 테스트 `DurableOperationStoreAdapterContractTest`(postgresqlIntegrationTest) ← `DurableOperationStoreContract.identicalResubmissionInsideOneTransactionReturnsTheFirstOperation`, 커밋 6d27356e | - | - | -| E-2b | Required | (알려진 남은 문제) 같은 operationId 재시도 시 outbox 중복 append: `alreadyAccepted`를 operationId 불일치로만 판단 → 같은 id 재시도는 새 제출로 보고 `outbox.append` 재실행. `OutboxEventEntity`에 `Persistable`/`@Version`이 없어 `repository.save`가 merge로 기존 행을 PENDING·attempt 0으로 덮거나(reaper가 지웠으면 새 행) 재발행 | 남음 | `src/application-core/src/main/java/dev/caskeleton/application/operation/SubmitDurableOperationUseCase.java:99-116`, `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/outbox/OutboxStoreAdapter.java:57-71`. merge 동작은 Spring Data `isNew` 규칙 기준 판단(실행 미확인) | W2 | `DurableOperationStorePort.submit`이 생성/재사용 여부를 돌려주게 하고(`submitIfAbsent` 영향 행 수 1/0) 그 값으로 append 여부 결정. `DurableOperationStoreContract`에 같은 id 재시도 케이스 추가 | -| E-3a | Required | `CanonicalOutboxAppendAdapter.append`에 caller 트랜잭션 확인 없음 → 트랜잭션 밖 호출 시 조용한 dual-write | 남음 | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/outbox/CanonicalOutboxAppendAdapter.java:37` (형제 `OutboxStoreAdapter.java:58`에는 있음) | W2 | `append` 첫 줄에 caller 트랜잭션 guard 추가 | +| E-2b | Required | (알려진 남은 문제) 같은 operationId 재시도 시 outbox 중복 append: `alreadyAccepted`를 operationId 불일치로만 판단 → 같은 id 재시도는 새 제출로 보고 `outbox.append` 재실행. `OutboxEventEntity`에 `Persistable`/`@Version`이 없어 `repository.save`가 merge로 기존 행을 PENDING·attempt 0으로 덮거나(reaper가 지웠으면 새 행) 재발행 | 완료 | Wave 1–2 P9 (fcddab7e·Wave 2 커밋): NEW-7a와 같은 결함·같은 수정. 아래 NEW-7a 행 참고 | - | `DurableOperationStorePort.submit`이 생성/재사용 여부를 돌려주게 하고(`submitIfAbsent` 영향 행 수 1/0) 그 값으로 append 여부 결정. `DurableOperationStoreContract`에 같은 id 재시도 케이스 추가 | +| E-3a | Required | `CanonicalOutboxAppendAdapter.append`에 caller 트랜잭션 확인 없음 → 트랜잭션 밖 호출 시 조용한 dual-write | 완료 | Wave 1–2 P9 (fcddab7e·Wave 2 커밋): `CanonicalOutboxAppendAdapterTest.appendOutsideACallerTransactionIsRefusedBeforeAnyWrite` FAIL("Expecting actual not to be null")→PASS. `.../outbox/CanonicalOutboxAppendAdapter.java:40-44` 첫 줄에 caller 트랜잭션 guard(형제 `OutboxStoreAdapter`와 같은 메시지) | - | `append` 첫 줄에 caller 트랜잭션 guard 추가 | | E-3b | Required | caller 트랜잭션 guard가 세 클래스에 복사됨 | 남음 | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/outbox/OutboxStoreAdapter.java:130-135`, `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/operation/DurableOperationStoreAdapter.java:169-174`, `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/liveevent/JpaLiveEventReplayAdapter.java:163-168` | W3 | `persistence/transaction` 패키지에 공용 helper 하나를 두고 세 곳 + E-3a가 호출 | | E-3c | Required | ownership 테스트가 canonical append adapter를 검사하지 않음 | 남음 | `src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/transaction/PersistenceTransactionOwnershipTest.java:25-47`(DurableOperation·LiveEvent만) | W4 | `PersistenceTransactionOwnershipTest`에 `CanonicalOutboxAppendAdapter`의 트랜잭션 없는 호출 거부 케이스 추가 | -| E-4a | Required | `markAllRead` 서브쿼리가 `read_at IS NULL`만 보고 state를 거르지 않음 → 읽지 않고 보관한 ARCHIVED 항목이 READ로 되살아남 | 남음 | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/notification/platform/inbox/InboxItemJpaRepository.java:83-104` | W2 | 서브쿼리에 `AND state NOT IN ('ARCHIVED','EXPIRED','DELETED')` 추가 | -| E-4b | Required | 엔티티 `markRead`/`markSeen`이 ARCHIVED·terminal 상태를 막지 않음 | 남음 | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/notification/platform/inbox/InboxItemEntity.java:107-127` | W2 | `markSeen`/`markRead`에서 `archivedAt != null`·terminal이면 false 반환 | +| E-4a | Required | `markAllRead` 서브쿼리가 `read_at IS NULL`만 보고 state를 거르지 않음 → 읽지 않고 보관한 ARCHIVED 항목이 READ로 되살아남 | 완료 | Wave 1–2 P9 (fcddab7e·Wave 2 커밋): 실제 PG `PostgreSqlInboxCutoffIntegrationTest.markAllReadLeavesAnUnreadArchivedItemArchived` FAIL(`[2, READ]` ≠ `[1, ARCHIVED]`)→PASS. 서브쿼리에 `AND state NOT IN ('ARCHIVED','EXPIRED','DELETED')`: `.../notification/platform/inbox/InboxItemJpaRepository.java:91-93`. 이 테스트 클래스는 SQL 사본을 실행하고 있어서(결함이 안 보였던 이유) repository `@Query` 값을 읽어 실행하도록 바꿈 | - | 서브쿼리에 `AND state NOT IN ('ARCHIVED','EXPIRED','DELETED')` 추가 | +| E-4b | Required | 엔티티 `markRead`/`markSeen`이 ARCHIVED·terminal 상태를 막지 않음 | 완료 | Wave 1–2 P9 (fcddab7e·Wave 2 커밋): `InboxItemEntityTest.markReadLeavesAnItemThatLeftTheInboxWhereItIs` / `markSeen...` (ARCHIVED·EXPIRED·DELETED 각 3건) FAIL(`[true, READ]`/`[true, SEEN]`)→PASS. `.../inbox/InboxItemEntity.java` `leftTheInbox()` 가드 | - | `markSeen`/`markRead`에서 `archivedAt != null`·terminal이면 false 반환 | | E-4c | Required | inbox 통합 테스트가 운영 쿼리를 복사한 SQL 문자열을 실행하고 enum에 없는 `'UNREAD'`를 씀. `JpaNotificationInbox`/`InboxItemJpaRepository` 실행 테스트 없음 | 남음 | `src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlInboxCutoffIntegrationTest.java:86-104,117` | W4 | 테스트가 실제 `InboxItemJpaRepository.markAllRead`를 호출하고 ARCHIVED 항목 유지 케이스 추가 | -| E-5a | Required | FIFO gate가 `occurred_at <`만 봐서 같은 `occurred_at` 이벤트는 함께 claim, 순서 미정 | 남음 | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/postgresql/PostgreSqlOutboxClaimRepository.java:15-29`(H2 `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/h2/H2OutboxClaimRepository.java`도 같은 SQL), 특성화 테스트 `PostgreSqlLegacyOutboxRowLifecycleIntegrationTest.equalTimestampRowsAreClaimedTogetherLegacyFifoLimitationCharacterization` | W2 | canonical row(`contract_id IS NOT NULL`)는 `(aggregate_sequence, event_index)`로 head 판정·정렬. 인덱스는 새 migration `V18`로 추가(+ `applied-migrations.sha256`) | -| E-5b | Required | gate가 `tenant_scope`·`aggregate_type`을 안 봐 다른 tenant/type의 같은 `aggregate_id` DEAD row가 서로 영구 차단 | 남음 | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/postgresql/PostgreSqlOutboxClaimRepository.java:20-25` | W2 | canonical row의 gate 키를 `(tenant_scope, aggregate_type, aggregate_id)`로(E-5a와 같은 SQL 변경, PostgreSQL·H2 두 곳) | +| E-5a | Required | FIFO gate가 `occurred_at <`만 봐서 같은 `occurred_at` 이벤트는 함께 claim, 순서 미정 | 완료 | Wave 1–2 P9 (fcddab7e·Wave 2 커밋): 실제 PG `PostgreSqlOutboxClaimAndMaintenanceIntegrationTest.canonicalEventsSharingAnOccurredAtAreClaimedOneAtATimeInAggregateOrder` FAIL(3건 동시 claim)→PASS, H2 `H2ClaimSqlTest.claimsCanonicalEventsSharingAnOccurredAtOneAtATimeInAggregateOrder` PASS. canonical 쌍은 `(aggregate_sequence, event_index)`로 head 판정·정렬: `.../postgresql/PostgreSqlOutboxClaimRepository.java:25-50`, `.../h2/H2OutboxClaimRepository.java:26-47`. 인덱스 새 migration `V18__outbox_event_unpublished_aggregate_order.sql` + `applied-migrations.sha256` 1줄, `PostgreSqlMigrationIntegrationTest` 버전 목록에 18 추가. legacy row가 낀 쌍은 기존 `occurred_at` 비교 유지(`equalTimestampRowsAreClaimedTogetherLegacyFifoLimitationCharacterization` 그대로 통과) | - | canonical row(`contract_id IS NOT NULL`)는 `(aggregate_sequence, event_index)`로 head 판정·정렬. 인덱스는 새 migration `V18`로 추가(+ `applied-migrations.sha256`) | +| E-5b | Required | gate가 `tenant_scope`·`aggregate_type`을 안 봐 다른 tenant/type의 같은 `aggregate_id` DEAD row가 서로 영구 차단 | 완료 | Wave 1–2 P9 (fcddab7e·Wave 2 커밋): 실제 PG `aDeadCanonicalRowOfAnotherTenantOrTypeDoesNotBlockTheSameAggregateId` FAIL(`[]`)→PASS. E-5a와 같은 SQL 변경(canonical 쌍은 tenant_scope·aggregate_type까지 같아야 같은 aggregate) | - | canonical row의 gate 키를 `(tenant_scope, aggregate_type, aggregate_id)`로(E-5a와 같은 SQL 변경, PostgreSQL·H2 두 곳) | | E-5c | Required | README가 "한 배치에 aggregate 당 최대 한 row"라고 적음(같은 `occurred_at`이면 거짓) | 남음 | `src/adapter/outbound/persistence-jpa/README.md:248-249` | W5 | E-5a 수정 후 README를 실제 보장에 맞춤 | | E-6a | Required | H10 tenant 규칙이 필드 이름 `tenantId`로만 판정("Structural" Javadoc과 반대) → `tenant`, `tenantScope` 엔티티 누락 | 남음 | `src/adapter/outbound/persistence-jpa/src/testFixtures/java/dev/caskeleton/adapter/outbound/persistence/testkit/arch/TenantScopedRepositoryPredicate.java:12-19,49` | W4 | `tenant*` 필드 전부(또는 marker annotation)로 판정 | | E-6b | Required | tenant 컬럼을 가진 세 리포지토리가 `JpaRepository`를 상속해 범위 없는 `findAll`/`deleteAll` 노출 | 남음 | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/operation/DurableOperationJpaRepository.java:25-26`, `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/idempotency/IdempotencyRecordJpaRepository.java:12-13`, `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/outbox/OutboxEventJpaRepository.java:16` | W3 | 세 리포지토리를 `Repository` marker + 쓰는 메서드만 선언으로 축소 | -| E-7 | Consider | 잘못된 canonical row 하나가 `claimBatch` 매핑에서 예외 → claim 트랜잭션 전체 롤백 → 매 주기 같은 row 재선택으로 relay 정지 | 남음 | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/outbox/OutboxStoreAdapter.java:79-94,161-193` | W2 | 매핑 실패 row는 DEAD로 전이하고 배치의 나머지는 계속 | -| E-8a | Consider | outbox 지표 쿼리가 매 poll(PT5S)마다 테이블 전체를 status별로 셈(7일치 PUBLISHED 포함) | 남음 | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/outbox/OutboxEventJpaRepository.java:54-56`, 호출 `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/outbox/OutboxMetrics.java:89` ← `OutboxRelayScheduler.java:36,49` | W2 | `countGroupedByStatus`에 `where e.status <> 'PUBLISHED'` | -| E-8b | Consider | `OutboxReaper`가 PUBLISHED 삭제를 한도 없는 단일 트랜잭션 DELETE로 실행 | 남음 | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/outbox/OutboxEventJpaRepository.java:21-23`, `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/outbox/OutboxReaper.java:40-42` | W2 | native `DELETE … WHERE ctid IN (SELECT … LIMIT n)`를 0건 될 때까지 배치별 트랜잭션으로 반복 | +| E-7 | Consider | 잘못된 canonical row 하나가 `claimBatch` 매핑에서 예외 → claim 트랜잭션 전체 롤백 → 매 주기 같은 row 재선택으로 relay 정지 | 완료 | Wave 1–2 P9 (fcddab7e·Wave 2 커밋): `OutboxStoreAdapterTest.claimBatchMovesAnUnreadableRowToDeadAndClaimsTheRestOfTheBatch` FAIL(IllegalStateException partial canonical)→PASS, 실제 PG `anUnreadableCanonicalRowDoesNotStopTheRestOfTheBatchFromBeingClaimed`·`anUnreadableCanonicalRowIsMovedToDeadByTheClaim` FAIL(projection mismatch 예외)→PASS. `.../outbox/OutboxStoreAdapter.java:84-110` 매핑 실패 row는 DEAD·lease 해제 후 배치에서 제외(legacy로 낮추지 않으므로 fail-closed 유지) | - | 매핑 실패 row는 DEAD로 전이하고 배치의 나머지는 계속 | +| E-8a | Consider | outbox 지표 쿼리가 매 poll(PT5S)마다 테이블 전체를 status별로 셈(7일치 PUBLISHED 포함) | 완료 | Wave 1–2 P9 (fcddab7e·Wave 2 커밋): 실제 PG `countByStatusLeavesPublishedRowsUncounted` FAIL(`{PENDING=1, PUBLISHED=1}`)→PASS. `countGroupedByStatus`에 `where e.status <> 'PUBLISHED'`(`.../outbox/OutboxEventJpaRepository.java`), fake `InMemoryOutboxStore.countByStatus` 동일, 포트 문서 갱신, `OutboxMetrics`는 PUBLISHED 시리즈를 내보내지 않음(0 고정 시리즈 방지). lifecycle PG 테스트의 PUBLISHED 카운트 단언 3곳은 row 상태 직접 조회로 교체 | - | `countGroupedByStatus`에 `where e.status <> 'PUBLISHED'` | +| E-8b | Consider | `OutboxReaper`가 PUBLISHED 삭제를 한도 없는 단일 트랜잭션 DELETE로 실행 | 완료 | Wave 1–2 P9 (fcddab7e·Wave 2 커밋): `OutboxReaperTest` 3건 FAIL(컴파일: `deletePublishedBatch` 없음)→PASS. native `DELETE … WHERE event_id IN (SELECT … LIMIT n)`(ctid 대신 PG·H2 공통 SQL)를 repository 메서드 `@Transactional`로 배치마다 커밋, 덜 찬 배치에서 종료: `.../outbox/OutboxEventJpaRepository.java:19-35`, `.../outbox/OutboxReaper.java`(배치 1,000, `ponytail:` 주석). 실제 PG `reaperDeletesOldPublishedRowsOutsideAnyCallerTransaction`, H2 `theReaperBatchDeleteRunsOnH2AndStopsAtItsLimit` PASS | - | native `DELETE … WHERE ctid IN (SELECT … LIMIT n)`를 0건 될 때까지 배치별 트랜잭션으로 반복 | | E-9 | Consider | `JpaObservabilityAutoConfiguration` 미사용 코드 | 해당 없음(코드 삭제) | 「제거된 코드」 표 "JPA 두 번째 트랜잭션·재시도 엔진 19종 … `JpaObservabilityAutoConfiguration`". `git grep JpaObservabilityAutoConfiguration -- src` 0건 | - | - | -| E-10a | Consider | experimental tenant guard의 "audited" admin scope가 reason을 ThreadLocal에만 두고 기록하지 않음 | 남음 | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/experimental/tenant/TenantAwareRepositoryGuard.java:14-15,36-53` (production 호출자 0, 테스트만) | W1 | 생성자에 audit sink(`Consumer` 등)를 받아 scope 열 때 기록, 또는 "audited" 문구 삭제 | +| E-10a | Consider | experimental tenant guard의 "audited" admin scope가 reason을 ThreadLocal에만 두고 기록하지 않음 | 완료 | Wave 1–2 P9 (fcddab7e·Wave 2 커밋): `TenantAwareRepositoryGuardTest.openingAnAdminScopeRecordsItsReasonInTheAuditSink` FAIL(컴파일: "constructor TenantAwareRepositoryGuard ... cannot be applied", audit sink 없음)→PASS, `anAuditSinkThatFailsLeavesNoAdminScopeOpen` PASS. 생성자가 `Consumer` audit sink를 받고 scope를 열기 전에 사유를 기록: `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/experimental/tenant/TenantAwareRepositoryGuard.java:31,56`. PG `TenantColumnIsolationTest`(jpa-contract) 통과 | - | 생성자에 audit sink(`Consumer` 등)를 받아 scope 열 때 기록, 또는 "audited" 문구 삭제 | | E-10b | Consider | public 생성자라 experimental 진입 게이트(`enabledBy`) 목록에서 빠짐 | 해당 없음(코드 삭제) | 「제거된 코드」 표 "`backend.jpa.experimental.*` 플래그 8개(`ExperimentalFeature`, `ExperimentalFeatureGate`, … `enabledBy(..)` 팩토리)와 `ExperimentalEntryConsentTest`" — 게이트 자체 삭제, 진입점은 public 생성자가 정본 | - | - | -| E-10c | Consider | `releaseConnection`이 search_path reset 실패 시에도 tenant schema가 걸린 커넥션을 pool에 반환 | 남음 | `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/experimental/schema/SchemaMultiTenantConnectionProvider.java:50-57` | W1 | reset 실패 시 `connection.abort(Runnable::run)`(또는 unwrap 후 evict)로 pool 복귀를 막고 예외 전파 | +| E-10c | Consider | `releaseConnection`이 search_path reset 실패 시에도 tenant schema가 걸린 커넥션을 pool에 반환 | 완료 | Wave 1–2 P9 (fcddab7e·Wave 2 커밋): `SchemaMultiTenantConnectionProviderTest.aFailedResetAbortsTheConnectionSoThePoolCannotLendItOutWithTheTenantSchema` FAIL("WantedButNotInvoked: connection.abort")→PASS, `aFailedResetReachesTheCaller` PASS. reset 실패 시 `abort(Runnable::run)` 후 close, 예외 전파: `.../experimental/schema/SchemaMultiTenantConnectionProvider.java:60-74`. Hikari는 abort된 커넥션을 close 때 evict한다(javap로 `ProxyConnection`이 abort를 가로채지 않음 확인) | - | reset 실패 시 `connection.abort(Runnable::run)`(또는 unwrap 후 evict)로 pool 복귀를 막고 예외 전파 | | E-11 / X1-#7d | 권고 | readiness card 외부 prerequisite가 없는 card(`messaging-cdc-dispatch.v1`)를 가리킴 | 해당 없음(코드 삭제) | 가리키던 card `jpa-outbox-cdc-retention-v1`이 「제거된 코드」 표 "readiness card `jpa-outbox-storage-v2`, `jpa-outbox-polling-delivery-v2`, `jpa-outbox-cdc-retention-v1`"로 삭제. `src/config/jpa/readiness-cards.yaml`에 `messaging`/`external` 0건
X1-#7d: 해당 카드 `jpa-outbox-cdc-retention-v1` 삭제(`docs/capability-status.md:179`), `grep messaging-cdc-dispatch src/config` → 0 | - | - | | E-12 | Nit | JPA CLAUDE.md 벤더 SQLState 표에 `55P03 → DB_LOCK_TIMEOUT` 누락 | 남음 | `src/adapter/outbound/persistence-jpa/CLAUDE.md:264-270` vs `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/postgresql/PostgreSqlSqlStateErrorMapping.java:16` | W5 | 표에 `55P03` 행 추가 | -| F-1a | Required | `PolicyAwareMongoQueryBuilder.whereEquals`(및 `whereAtLeast`/`whereBefore`)가 `Object` 값을 그대로 `Criteria.is/gte/lt`에 넣음 → `Map`/`Document`(`{"$ne":null}`)가 연산자로 해석돼 operator allowlist·regex 정책 우회 | 남음 | `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/query/PolicyAwareMongoQueryBuilder.java:43-61` | W1 | 공용 `requireScalar(value)`(Map/Bson/Document 거부, EQ는 Collection도 거부)를 만들어 builder에서 호출 + `Map.of("$ne", …)` 회귀 테스트 | -| F-1b | Required | `AtomicFilter.id`/`andEquals`/`toQuery`가 값 타입 검사 없이 `.is(value)` → `AtomicFilter.id(Map.of("$gt",""))`로 단일 문서 보장 붕괴 | 남음 | `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/imperative/atomic/AtomicFilter.java:38-53,66-74` | W1 | compact constructor에서 모든 값에 F-1a의 `requireScalar` 적용 | -| F-1c | Required | Javadoc이 operator injection을 "compile-time impossibility"라고 주장 | 남음 | `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/query/PolicyAwareMongoQueryBuilder.java:16-19` | W5 | F-1a 후 "런타임 스칼라 검사로 막는다"로 수정 | +| F-1a | Required | `PolicyAwareMongoQueryBuilder.whereEquals`(및 `whereAtLeast`/`whereBefore`)가 `Object` 값을 그대로 `Criteria.is/gte/lt`에 넣음 → `Map`/`Document`(`{"$ne":null}`)가 연산자로 해석돼 operator allowlist·regex 정책 우회 | 완료 | Wave 1–2 P12 (fcddab7e·Wave 2 커밋): `PolicyAwareMongoQueryBuilderTest.anOperatorShapedEqualityValueIsRefused`·`anOperatorShapedLowerBoundIsRefused`·`anOperatorShapedUpperBoundIsRefused`(각 6값: `Map.of("$ne","")`, `Document("$ne",null)`, `BsonDocument("$gt")`, `JsonObject("{$regex}")`, `Pattern`, `BsonRegularExpression`), `anEqualityValueThatIsACollectionIsRefusedInFavourOfWhereIn`, `aRegexHiddenInAMembershipListIsRefused` FAIL(`AssertionError: Expecting actual not to be null`, 23건)→PASS. 공용 검사 `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/query/MongoOperator.java:96`(`requireScalar`), 호출 `query/PolicyAwareMongoQueryBuilder.java:45,52,59,71`. 수정 방향과 차이: 새 공개 타입 `MongoQueryValues`는 API surface 한도(271, `-PraiseMongoApiSurfaceCeiling` 필요)에 걸려 기존 공개 enum `MongoOperator`의 인스턴스 메서드로 둠(surface 불변). `Pattern`·`BsonRegularExpression`도 거부(값 자리 정규식이 regex 정책 우회), `whereIn` 원소에도 적용. | - | 공용 `requireScalar(value)`(Map/Bson/Document 거부, EQ는 Collection도 거부)를 만들어 builder에서 호출 + `Map.of("$ne", …)` 회귀 테스트 | +| F-1b | Required | `AtomicFilter.id`/`andEquals`/`toQuery`가 값 타입 검사 없이 `.is(value)` → `AtomicFilter.id(Map.of("$gt",""))`로 단일 문서 보장 붕괴 | 완료 | Wave 1–2 P12 (fcddab7e·Wave 2 커밋): `MongoAtomicOperationsTemplateTest.anOperatorDocumentAsTheIdentifierIsRefused`(`AtomicFilter.id(Map.of("$gt",""))`), `anOperatorDocumentAsAnExpectedStateIsRefused`, `anOperatorDocumentPassedToTheConstructorIsRefused` FAIL(`AssertionError` at `MongoAtomicOperationsTemplateTest.java:42`)→PASS. `imperative/atomic/AtomicFilter.java:36`(compact constructor에서 `MongoOperator.EQ::requireScalar`). 패키지 edge `imperative -> query`를 `MongoModuleBoundaryTest` matrix에 추가(DAG 유지). | - | compact constructor에서 모든 값에 F-1a의 `requireScalar` 적용 | +| F-1c | Required | Javadoc이 operator injection을 "compile-time impossibility"라고 주장 | 완료 | Wave 1–2 P12: F-1a·F-1b 수정 때 같은 파일 Javadoc 정정 | - | F-1a 후 "런타임 스칼라 검사로 막는다"로 수정 | | F-1d | Required | security lane이 "injection" 검증을 표방하지만 injection 케이스 없음 | 남음 | `src/adapter/outbound/persistence-mongo/build.gradle:183`, `src/adapter/outbound/persistence-mongo/src/mongoIntegrationTest/java/dev/caskeleton/adapter/outbound/mongo/security/MongoSecurityIntegrationLaneTest.java`(`$ne`/`$gt`/inject 0건) | W4 | lane에 operator-document 값 거부 케이스 추가 또는 설명에서 "injection" 삭제 | -| F-2a | Required | 여러 profile일 때 startup validator가 `active-profile`을 무시하고 모든 profile의 topology를 관측값과 비교 → REPLICA_SET+STANDALONE 조합이면 기동 항상 실패 | 남음 | `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/autoconfigure/MongoStartupValidator.java:65-88`, `active-profile`은 `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/client/MongoProfileClientSettingsAutoConfiguration.java:53-54`에서 raw `getProperty`로만 읽음 | W2 | `activeProfile`을 `MongoPlatformSettings`에 한 번 바인딩하고 validator는 그 profile만 검사 + 두 profile 테스트 | -| F-2b | Required | health가 `anyMatch(profile.topology() != observed)` → 다른 profile 때문에 readiness 영구 DOWN | 남음 | `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/autoconfigure/MongoPlatformHealthIndicator.java:57-58,86-89` | W2 | F-2a의 바인딩된 active profile 하나만 비교 | +| F-2a | Required | 여러 profile일 때 startup validator가 `active-profile`을 무시하고 모든 profile의 topology를 관측값과 비교 → REPLICA_SET+STANDALONE 조합이면 기동 항상 실패 | 완료 | Wave 1–2 P12 (fcddab7e·Wave 2 커밋): `MongoStartupValidatorTest.anInactiveProfileWithAnotherTopologyDoesNotFailStartup`(primary=REPLICA_SET 활성, local=STANDALONE) FAIL(`MongoOperationRejectedException: profile 'local' declares topology STANDALONE but is connected to REPLICA_SET`)→PASS, `MongoPlatformPropertiesTest.aProfileSetWhoseActiveNameMatchesNoneOfItsProfilesIsRefused`. `activeProfile`을 `MongoPlatformSettings` 첫 component로 한 번 바인딩(`autoconfigure/MongoPlatformSettings.java:34,74,83`), validator는 활성 profile만 비교(`autoconfigure/MongoStartupValidator.java:67`), customizer의 raw `getProperty` 제거(`client/MongoProfileClientSettingsAutoConfiguration.java:63,90`). 설정 키가 `ca-skeleton.persistence-mongo.active-profile` → `ca-skeleton.persistence-mongo.platform.active-profile`로 이동(`src/main/resources/config/mongo.yml:14`, EPP `MongoDefaultsEnvironmentPostProcessor.java:47`). env 키 `APP_PERSISTENCE_MONGO_ACTIVE_PROFILE`는 그대로라 `env-keys.yaml`·`.env.example` 변경 없음. | - | `activeProfile`을 `MongoPlatformSettings`에 한 번 바인딩하고 validator는 그 profile만 검사 + 두 profile 테스트 | +| F-2b | Required | health가 `anyMatch(profile.topology() != observed)` → 다른 profile 때문에 readiness 영구 DOWN | 완료 | Wave 1–2 P12 (fcddab7e·Wave 2 커밋): `MongoStartupValidatorTest.anInactiveProfileWithAnotherTopologyDoesNotMakeTheInstanceUnready` FAIL(`Expecting value to be true but was false`)→PASS. `autoconfigure/MongoPlatformHealthIndicator.java:89`(활성 profile 하나만 비교), health detail에 `activeProfile` 추가(`:83`). | - | F-2a의 바인딩된 active profile 하나만 비교 | | F-3a | Required | change-stream pipeline이 같은 `clusterTime` 트랜잭션 이벤트를 버림 | 해당 없음(코드 삭제) | 「제거된 코드」 표 "Mongo change stream(`changestream/**`)과 change-stream→messaging bridge(`advanced/bridge/`)". `git ls-files` 에 `changestream` 0건 | - | - | | F-3b | Required | consumer가 `fullDocument`만 넘겨 delete 이벤트가 `{}` | 해당 없음(코드 삭제) | 위와 같은 행(`ReactiveMongoChangeStreamConsumer` 삭제) | - | - | | F-3c | Required | BUSY/PARKED 뒤 다음 이벤트 checkpoint가 건너뛴 이벤트를 넘김 | 해당 없음(코드 삭제) | 위와 같은 행(`MongoChangeStreamRunner` 삭제) | - | - | | F-3d | Required | `MongoResumeCheckpoint.belongsTo()` 호출자 없음, cluster 검사 미실행 | 해당 없음(코드 삭제) | 위와 같은 행. 남은 `MongoResumeException`·`MongoTopologyRequirement.changeStreams()`는 어휘만 남은 것으로 이 결함과 무관 | - | - | -| F-4a | Required | bulk 경로가 raw `getQueryObject()`/`getUpdateObject()`로 `UpdateOneModel`을 만들어 `@Field` 이름·custom conversion 미적용(atomic 경로는 `operations.updateFirst(…, documentType, …)`) | 남음 | `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/imperative/bulk/MongoBulkExecutor.java:76-78`, 비교 `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/imperative/atomic/MongoAtomicOperationsTemplate.java:139` | W2 | `documentType`을 받아 `QueryMapper`/`UpdateMapper`로 매핑(또는 `MongoOperations.bulkOps(…)` 사용) + `@Field`·비String 값 테스트 | -| F-4b | Required | bulk 크기 추정이 매핑 전 `toJson()`을 호출해 codec 없는 값(`DomainDocumentId`, `BigInteger`)에서 실패 | 남음 | `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/imperative/bulk/MongoBulkWritePlan.java:68-69` | W2 | F-4a의 매핑 결과로 크기 추정 | -| F-5a | Required | CSFLE `schemaMap` 키가 `db.coll`이 아니라 bare collection → 드라이버가 매칭하지 못해 자동 암호화 안 됨 | 남음 | `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/advanced/encryption/csfle/MongoCsfleClientFactory.java:40-41` | W1 | namespace(`database.collection`)로 키 지정 | -| F-5b | Required | `profile.fields()`를 읽지 않고 호출자가 준 JSON을 그대로 schema로 씀 | 남음 | `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/advanced/encryption/csfle/MongoCsfleClientFactory.java:32-47`, `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/advanced/encryption/csfle/MongoCsfleProfile.java:18-22` | W1 | `fields()`로 schema를 생성하고 `encryptedFieldsMapJson` 인자 제거 | -| F-5c | Required | `keyVaultCredential`을 `keyVaultMongoClientSettings`로 넘기지 않음(프로필 Javadoc의 별도 자격 증명 약속 위반) | 남음 | `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/advanced/encryption/csfle/MongoCsfleClientFactory.java:43-47`, `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/advanced/encryption/csfle/MongoCsfleProfile.java:11-12,21` | W1 | 별도 credential로 `keyVaultMongoClientSettings` 설정 | +| F-4a | Required | bulk 경로가 raw `getQueryObject()`/`getUpdateObject()`로 `UpdateOneModel`을 만들어 `@Field` 이름·custom conversion 미적용(atomic 경로는 `operations.updateFirst(…, documentType, …)`) | 완료 | Wave 1–2 P12 (fcddab7e·Wave 2 커밋): 실제 Mongo lane `MongoBulkMappingLaneTest.aBulkUpdateWritesTheFieldUnderItsMappedName`(`mongoReplicaSetTest`) FAIL(`expected {_id=o-1, st=PAID} but was {_id=o-1, st=NEW, status=PAID}`)→PASS. `MongoBulkExecutor.execute(context, documentType, plan)`로 시그니처 변경, `QueryMapper`/`UpdateMapper`로 entity 매핑(`imperative/bulk/MongoBulkExecutor.java:68,130`). `bulkOps(...)`는 CSOT `withTimeout`을 잃어서 쓰지 않음. | - | `documentType`을 받아 `QueryMapper`/`UpdateMapper`로 매핑(또는 `MongoOperations.bulkOps(…)` 사용) + `@Field`·비String 값 테스트 | +| F-4b | Required | bulk 크기 추정이 매핑 전 `toJson()`을 호출해 codec 없는 값(`DomainDocumentId`, `BigInteger`)에서 실패 | 완료 | Wave 1–2 P12 (fcddab7e·Wave 2 커밋): 실제 Mongo lane `MongoBulkMappingLaneTest.aBulkUpdateCarriesValuesThatNeedAConverter`(`DomainDocumentId` id + `BigInteger` 값, `findById`로 왕복) FAIL(`CodecConfigurationException: Can't find a codec for ... DomainDocumentId`)→PASS. 크기 한도를 plan 생성자에서 executor로 옮겨 매핑된 문서를 collection codec으로 `RawBsonDocument` 인코딩한 실제 byte로 판정(`MongoBulkExecutor.java:150`), `MongoBulkWritePlan.estimatedEncodedBytes` 삭제. 한도 회귀 테스트는 `MongoBulkOutcomeTest.aPlanOverTheByteCeilingIsRefused`(hermetic, `mappedWrites` 직접 호출)로 이동. | - | F-4a의 매핑 결과로 크기 추정 | +| F-5a | Required | CSFLE `schemaMap` 키가 `db.coll`이 아니라 bare collection → 드라이버가 매칭하지 못해 자동 암호화 안 됨 | 완료 | Wave 1–2 P12 (fcddab7e·Wave 2 커밋): `MongoCsfleClientFactoryTest.theSchemaIsKeyedByTheCollectionNamespace` — 재현 FAIL(`Expecting all elements of ["customers"] to match`)→PASS. `MongoCsfleProfile`에 `database` component 추가, `namespace()` = `database.collection`(`advanced/encryption/csfle/MongoCsfleProfile.java:23,67`), `MongoCsfleClientFactory.java:76`. | - | namespace(`database.collection`)로 키 지정 | +| F-5b | Required | `profile.fields()`를 읽지 않고 호출자가 준 JSON을 그대로 schema로 씀 | 완료 | Wave 1–2 P12 (fcddab7e·Wave 2 커밋): `MongoCsfleClientFactoryTest.theSchemaIsGeneratedFromTheFieldPolicies`(중첩 경로 `contact.email` → 중첩 `properties`, Random/Deterministic 알고리즘, keyId UUID) 재현 FAIL(`Expecting actual "{}" to contain "ssn"`)→PASS, `anAliasWithoutADataKeyIdIsRefused`, `aFieldInsideAnEncryptedParentIsRefused`. `encryptedFieldsMapJson` 인자 제거, 대신 `Map dataKeyIds`(alias→data key id: 자동 암호화 schema는 alias가 아니라 key id를 받으므로 호출자가 key vault에서 해석) — `MongoCsfleClientFactory.java:55,91`. Deterministic 필드는 `bsonType: string` 고정(`ponytail:` 주석, 비문자열 equality 필드가 생기면 정책에 타입 추가). | - | `fields()`로 schema를 생성하고 `encryptedFieldsMapJson` 인자 제거 | +| F-5c | Required | `keyVaultCredential`을 `keyVaultMongoClientSettings`로 넘기지 않음(프로필 Javadoc의 별도 자격 증명 약속 위반) | 완료 | Wave 1–2 P12 (fcddab7e·Wave 2 커밋): `MongoCsfleClientFactoryTest.theKeyVaultConnectsWithItsOwnCredential` 재현 FAIL(`Expecting actual not to be null` — `getKeyVaultMongoClientSettings()`)→PASS. 생성자가 `MongoCredentialResolver`를 받아 `profile.keyVaultCredential()`로 key vault `MongoClientSettings`를 만든다(`MongoCsfleClientFactory.java:40,64-73`). 실제 암호화 lane은 불가: 자동 암호화는 `mongocryptd` 또는 `crypt_shared`(MongoDB Enterprise 배포물)가 필요하고 lane이 쓰는 community `mongo:8.0` 이미지에는 없다. driver 쪽 `org.mongodb:mongodb-crypt`도 이 leaf 의존성에 없다(새 의존성·네트워크 다운로드 필요). 그래서 driver에 넘기는 `AutoEncryptionSettings`를 설정 단위 테스트로 검증함. F-5d(W4, 단위 테스트 추가)도 이 테스트로 사실상 충족. | - | 별도 credential로 `keyVaultMongoClientSettings` 설정 | | F-5d | Required | CSFLE factory에 테스트·호출자 없음(README가 "테스트 없는 진입점"으로 명시) | 남음 | `src/adapter/outbound/persistence-mongo/README.md:159-162` | W4 | 생성된 `AutoEncryptionSettings`(namespace 키, schema, key-vault 설정) 단위 테스트 추가 | | F-6 | Required | 공유 컬렉션 tenancy 강제 지점(`TenantScopedMongoOperations`) 구현·호출자 없음, 문서는 강제된다고 약속 | 완료 | 인터페이스 삭제(「제거된 코드」 표 "`MongoDataKeyResolver`, `MongoTenantDatabaseResolver`, `TenantScopedMongoOperations`"), 문서를 "adopter repository가 injector를 모든 경로에서 호출, facade 없음"으로 수정(`docs/mongodb/advanced/multi-tenancy.md:15-17`), 커밋 6d27356e | - | - | | F-7 | Consider | reactive cursor가 row마다 두 번 직렬화 | 해당 없음(코드 삭제) | 「제거된 코드」 표 "Mongo reactive 경로(`reactive/**` …)". `MongoReactiveCursorPublisher` 0건 | - | - | -| F-8 | Consider | migration lock이 모든 쓰기 오류를 "경쟁에서 짐"으로 삼킴 | 남음 | `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/migration/MongoCollectionMigrationLock.java:112-114` | W2 | `lostTheRace.getError().getCode() == 11000`일 때만 `Optional.empty()`, 그 외 재던짐 | +| F-8 | Consider | migration lock이 모든 쓰기 오류를 "경쟁에서 짐"으로 삼킴 | 완료 | Wave 1–2 P12 (fcddab7e·Wave 2 커밋): 실제 Mongo lane `MongoMigrationLaneTest.aLeaseWriteThatFailsForAnotherReasonIsRaisedRatherThanReportedAsALostRace`(validator로 insert를 121 실패시킴) FAIL(`Expecting actual not to be null`)→PASS. `migration/MongoCollectionMigrationLock.java:116`. 수정 방향(`code == 11000`)보다 조금 넓게 `ErrorCategory.DUPLICATE_KEY`(11000·11001·12582, driver 정의)로 판정 — 같은 패키지 `MongoCollectionMigrationLedger.java:160`과 같은 기준. | - | `lostTheRace.getError().getCode() == 11000`일 때만 `Optional.empty()`, 그 외 재던짐 | | F-9a | Nit | `MongoPlatformAutoConfiguration`에 inline FQN 약 38줄(leaf CLAUDE.md 금지 규칙 위반) | 남음 | `src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/autoconfigure/MongoPlatformAutoConfiguration.java:41,65,72,132-134` 외, 규칙 `src/adapter/outbound/persistence-mongo/CLAUDE.md:69` | W5 | FQN을 import로 교체 | | F-9b | Nit | 고아 Javadoc(`:192-198`) | 해당 없음(코드 삭제) | 고아 Javadoc이 있던 `ReactiveExecution` 블록이 reactive 경로와 함께 삭제(「제거된 코드」 표 reactive 행). 현재 파일에 연속·고아 Javadoc 0건 | - | - | | F-9c | Nit | CLAUDE.md가 조립 방식을 `implementation(project(...))`로 적음(실제 `runtimeOnly`) | 완료 | `src/adapter/outbound/persistence-mongo/CLAUDE.md:52-53`(`runtimeOnly project(':adapter:outbound:persistence-mongo')`), `src/app-bootstrap/build.gradle:146`, 커밋 6d27356e | - | - | @@ -318,12 +330,12 @@ | ID | 심각도 | 요약 | 상태 | 근거 | Wave | 수정 방향 | |---|---|---|---|---|---|---| | G-1a | Critical | SCRIPT lane 한도(기본 8)가 연결 수가 아니라 동시 lease 수라 정상 Redis에서도 9번째 동시 호출부터 거부 | 완료 | `src/adapter/outbound/redis-runtime/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/lettuce/connection/RedisRuntimeOwner.java:145-166`(lane별 fair `Semaphore`, `acquireTimeout`까지 대기 후 거부), `src/adapter/outbound/redis-runtime/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/config/RedisSdkAutoConfiguration.java:234,241`. 테스트 `RedisScriptLaneAdmissionTest.callersBeyondTheScriptLaneLimitWaitForAReturnedConnectionInsteadOfBeingRefused`, `aCallerStillWaitingWhenTheAcquireTimeoutRunsOutIsRefusedAsNotSent`. 커밋 `6d27356e` | - | - | -| G-1b | Critical | Redis에 보내지 않은 lane 거부(`RedisCommandRejectedException`, not-sent)를 idempotency·lease adapter가 `Indeterminate`로 보고 | 남음 | `src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/idempotency/RedisIdempotencyStoreAdapter.java:129-131`(외 243-248, 299-304, 331-336, 474-479), `src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/lease/RedisDistributedLeaseAdapter.java:167-172`(외 225-227, 341-346, 372-375). `LeaseAcquireOutcome.Unavailable`·`IdempotencyClaimOutcome.Unavailable`는 있지만 쓰지 않음 | W2 | 두 adapter에 `RedisEdgeRateLimitAdapter.java:123-132`과 같은 `catch (RedisOperationException)` + `metadata().ambiguousExecution()` 분기를 넣어 not-sent는 `Unavailable`로 반환하고, 포화된 owner로 거부를 재현하는 테스트 추가 | -| G-1c | Critical | `redisRequired` health probe가 업무와 같은 REGULAR lane에서 lease를 빌려, lane 포화가 `acquireTimeout`을 넘으면 Redis 정상이어도 DOWN | 남음 | `src/adapter/outbound/redis-runtime/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/config/RedisHealthContributor.java:51,61-64`(borrow 거부도 `unreachable`). 대기 후 거부로 바뀌어 순간 포화는 완화됨 | W2 | `RedisHealthContributor.probe()`에서 borrow 거부(`RedisCommandRejectedException`)를 `unreachable`이 아닌 `saturated`(UP 유지)로 분리하거나 lane 한도 밖 전용 probe 연결 사용 | -| G-2a | Required | fixed-window/sliding-counter hash가 `windowStart-2w` 필드 하나만 지우고 매 허용마다 `PEXPIRE` 갱신 → 필드·key 무한 증가(M4 회귀) | 남음 | `src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/ratelimit/RateLimitScripts.java:57-59,88-90`. 주석 `:39-40`("refreshed per hit이 아니다")은 여전히 코드와 반대 | W2 | `FIXED_WINDOW`는 `start`/`count` 두 필드 덮어쓰기, `SLIDING_COUNTER`는 `start`/`cur`/`prev` 회전으로 바꾸고 `:39-40` 주석 수정 | +| G-1b | Critical | Redis에 보내지 않은 lane 거부(`RedisCommandRejectedException`, not-sent)를 idempotency·lease adapter가 `Indeterminate`로 보고 | 완료 | Wave 1–2 P6 (fcddab7e·Wave 2 커밋): NEW-5c와 같은 수정(아래) | - | 두 adapter에 `RedisEdgeRateLimitAdapter.java:123-132`과 같은 `catch (RedisOperationException)` + `metadata().ambiguousExecution()` 분기를 넣어 not-sent는 `Unavailable`로 반환하고, 포화된 owner로 거부를 재현하는 테스트 추가 | +| G-1c | Critical | `redisRequired` health probe가 업무와 같은 REGULAR lane에서 lease를 빌려, lane 포화가 `acquireTimeout`을 넘으면 Redis 정상이어도 DOWN | 완료 | Wave 1–2 P6 (fcddab7e·Wave 2 커밋): `redis-runtime/.../config/RedisHealthContributor.java:108`: borrow 거부(`RedisCommandRejectedException`)는 owner가 OPEN이면 `saturated`(reachable=true, UP), 아니면 `shutting-down`. `RedisHealthContributorTest.aSaturatedLaneIsLoadNotAnOutage` FAIL(`[false, "unreachable"]` ≠ `[true, "saturated"]`)→PASS. 트레이드오프(Redis가 멈춰 lane이 계속 가득 차면 saturated로 보임)는 클래스 javadoc에 기록 — 해당 요청은 timeout 후 fail-closed | - | `RedisHealthContributor.probe()`에서 borrow 거부(`RedisCommandRejectedException`)를 `unreachable`이 아닌 `saturated`(UP 유지)로 분리하거나 lane 한도 밖 전용 probe 연결 사용 | +| G-2a | Required | fixed-window/sliding-counter hash가 `windowStart-2w` 필드 하나만 지우고 매 허용마다 `PEXPIRE` 갱신 → 필드·key 무한 증가(M4 회귀) | 완료 | Wave 1–2 P6 (fcddab7e·Wave 2 커밋): `RateLimitScripts.java:55`(fixed-window `start`/`count` 두 필드 덮어쓰기), `:90`(sliding-counter `start`/`cur`/`prev` 회전), `:36-44` 주석을 실제 동작(히트마다 PEXPIRE, 상태 크기 고정)으로 수정. in-memory fake(`redis-runtime` testFixtures `InMemoryRedisCommandGateway` fixedWindow/slidingCounter)도 같은 레이아웃으로. 실제 Redis `LiveRedisSemanticPortsTest.windowCounterStateDoesNotGrowAcrossSkippedWindows`[FIXED_WINDOW, SLIDING_COUNTER] FAIL(`expected: 1L but was: 4L`)→PASS. 배포 시 기존 per-window 필드 키는 카운터가 한 번 리셋되고 옛 필드는 늘지 않은 채 TTL로 사라짐 | - | `FIXED_WINDOW`는 `start`/`count` 두 필드 덮어쓰기, `SLIDING_COUNTER`는 `start`/`cur`/`prev` 회전으로 바꾸고 `:39-40` 주석 수정 | | G-2b | Required | in-memory fake가 rate-limit 스크립트의 `HDEL`/`PEXPIRE`를 흉내내지 않아 hash 증가가 테스트되지 않음 | 남음 | `src/adapter/outbound/redis-runtime/src/testFixtures/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/lettuce/operations/InMemoryRedisCommandGateway.java:1717-1753`(필드 put만). cache-redis 테스트에 HLEN 단언 0건 | W4 | fake `fixedWindow`/`slidingCounter`를 G-2a의 새 필드 모델에 맞추고, `LiveRedisSemanticPortsTest`에 여러 window 뒤 HLEN ≤ 3 단언 추가 | -| G-3a | Required | lease replay(status 2)가 서버 잔여 `PTTL`을 버리고 재시도 시점부터 전체 TTL을 다시 부여 | 남음 | `src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/lease/RedisDistributedLeaseAdapter.java:157-161` → `handle()` `:231-239`가 `localValidityOf(request.leaseTtl())` 사용 (`inspect()` `:213`만 `observedValidityOf`) | W2 | status 2 분기에서 `observedValidityOf(reply.remainingMillis())`로 handle 생성 | -| G-3b | Required | TTL ≤ drift 검사가 Redis 호출 뒤에 있어, 서버는 lease를 잡았는데 IAE가 catch돼 `Indeterminate` 반환 | 남음 | `src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/lease/RedisDistributedLeaseAdapter.java:114-127`(검사), `:145-156`(먼저 스크립트 실행), `:167-172`(IAE를 `Exception`으로 잡음) | W2 | `tryAcquire`·`renew`에서 `localValidityOf(leaseTtl)`을 `owner.borrow` 전에 호출 | +| G-3a | Required | lease replay(status 2)가 서버 잔여 `PTTL`을 버리고 재시도 시점부터 전체 TTL을 다시 부여 | 완료 | Wave 1–2 P6 (fcddab7e·Wave 2 커밋): `RedisDistributedLeaseAdapter.java:169`: status 2 replay handle은 `observedValidityOf(reply.remainingMillis())`. `RedisDistributedLeaseAdapterTest.aReplayedAcquireKeepsOnlyTheServersRemainingTtl` FAIL(`30S to be less than or equal to 10S`)→PASS. 소유자 결정 8대로 lease 포트 유지 | - | status 2 분기에서 `observedValidityOf(reply.remainingMillis())`로 handle 생성 | +| G-3b | Required | TTL ≤ drift 검사가 Redis 호출 뒤에 있어, 서버는 lease를 잡았는데 IAE가 catch돼 `Indeterminate` 반환 | 완료 | Wave 1–2 P6 (fcddab7e·Wave 2 커밋): `RedisDistributedLeaseAdapter.java:148`(tryAcquire), `:341`(renew): `localValidityOf`를 `owner.borrow` 전에 호출, IAE는 호출자에게 전파. `aTtlWithinTheDriftBudgetIsRejectedBeforeReachingRedis`·`aRenewTtlWithinTheDriftBudgetIsRejectedBeforeReachingRedis`(FAIL `Expecting actual not to be null`→PASS), `aTtlWithinTheDriftBudgetLeavesTheResourceFree`(FAIL: `Owned[...]` to be an instance of `Absent`→PASS) | - | `tryAcquire`·`renew`에서 `localValidityOf(leaseTtl)`을 `owner.borrow` 전에 호출 | | G-4a | Required | `capacity.maximum-in-flight-bytes`·`capacity.maximum-reply-bytes`가 바인딩만 되고 적용 안 됨 | 해당 없음(코드 삭제) | `docs/capability-status.md` 「제거된 코드」 `app.redis.limits.*`… 행(174). `RedisSdkSettings`에 getter 없음, env-keys에 `APP_REDIS_CAPACITY_MAXIMUM_*_BYTES` 없음 | - | - | | G-4b | Required | `limits.*` 11개(`maxKeyBytes`~`offlineQueueCommands`·`maxBitmapOffset`)가 적용 안 되고 SDK는 하드코딩 `RedisOperationLimits.defaults()` 사용 | 해당 없음(코드 삭제) | 같은 표 행 174. `src/adapter/outbound/redis-sdk/README.md` "Configuration that is code, not settings" 절이 한도를 코드로 준다고 명시 | - | - | | G-4c | Required | `timeout.collection`·`timeout.admin` 미적용 | 해당 없음(코드 삭제) | 같은 표 행 174. 현재 `Timeouts`는 `fast`·`script`·`batch`만 있고 모두 참조됨(`RedisTopologyClientFactory.java:310`, `RedisCapabilityConfig.java:78`, `RedisSdkAutoConfiguration.java:259`) | - | - | @@ -347,10 +359,10 @@ | G-7d | Consider | runtime과 sdk가 같은 패키지 `…cache.redis.sdk.*`를 공유 | 남음 | redis-runtime main 전 파일이 `dev.caskeleton.adapter.outbound.cache.redis.sdk.*`(예: `.../sdk/lettuce/connection/RedisRuntimeOwner.java:1`) | W3 | redis-runtime 패키지를 `dev.caskeleton.adapter.outbound.cache.redis.runtime.*`로 이동 | | G-7e | Consider | runtime `RedisCorrectnessRoles`가 소비자 selector 값(session·idempotency·rate-limit·lease)을 하드코딩 | 남음 | `src/adapter/outbound/redis-runtime/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/config/RedisCorrectnessRoles.java:32-37` | W3 | selector 목록을 소비자인 cache-redis(`RedisCapabilitySettings`)로 옮기고 runtime은 "required 여부"만 받도록 변경 | | G-8 | Consider | EVALSHA+NOSCRIPT 재로드 헬퍼가 4벌 복사, `CacheScripts`만 메시지 `startsWith("NOSCRIPT")` 폴백 | 남음 | `src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/cache/CacheScripts.java:41-87`, `ratelimit/RateLimitScripts.java:209-263`, `lease/LeaseScripts.java:106-160`, `idempotency/IdempotencyScripts.java:213-271` | W3 | cache-redis에 `RegisteredLuaScript`(digest 캐시·NOSCRIPT 판별·재로드 1회) 하나를 두고 네 클래스가 사용 | -| G-9a | Consider | 장애 WARN이 capability·operation·type 조합마다 JVM 수명 동안 한 번뿐(`WARNED` 비우지 않음) | 남음 | `src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/RedisSemanticFailureLogger.java:19,26` | W2 | `WARNED`를 key별 마지막 WARN 시각 맵으로 바꿔 시간 창(예: 1분)마다 다시 WARN | -| G-9b | Consider | `failureType`이 대부분 wrapper(`ExecutionException`) 이름 | 남음 | 같은 파일 `:24`. 호출부는 `.get()`에서 잡은 예외를 그대로 넘김(`RedisDistributedLeaseAdapter.java:167-168` 등) | W2 | `report()`에서 `ExecutionException`·`CompletionException` cause를 풀고 기록 | -| G-10a | Consider | SCRIPT ACL probe가 `return {1}`이라 스크립트 내부 명령(`TIME`/`HSET`/`PEXPIRE`/`DEL`) 권한 부족을 기동 때 못 잡음 | 남음 | `src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/capability/RedisSemanticScriptAclProbe.java:20`. 실제로 `infra/redis-sdk/acl/application-advanced.acl:1`에 `+time`이 없어 `LiveRedisSemanticPortsTest`가 첫 요청에서 실패(알려진 lane 실패) | W2 | probe 스크립트를 probeKey에 `TIME`·`HSET`·`PEXPIRE`·`HGET`·`DEL`을 실제 실행하는 것으로 교체하고, 테스트 ACL에 `+time` 추가 | -| G-10b | Consider | `redisRequired`가 REGULAR lane만 probe → ADVANCED 자격 증명이 깨져도 readiness UP | 남음 | `src/adapter/outbound/redis-runtime/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/config/RedisHealthContributor.java:51`, `RedisSdkAutoConfiguration.java:259,287` | W2 | script capability가 선택되면 required contributor가 SCRIPT lane에서 등록 스크립트 EVALSHA로 probe | +| G-9a | Consider | 장애 WARN이 capability·operation·type 조합마다 JVM 수명 동안 한 번뿐(`WARNED` 비우지 않음) | 완료 | Wave 1–2 P6 (fcddab7e·Wave 2 커밋): `RedisSemanticFailureLogger.java:28,58`: once-per-JVM `Set` → key별 마지막 WARN 시각 맵, `WARN_INTERVAL`(1분)마다 다시 WARN. 테스트용 package-private `report(..., nowNanos)`. `RedisSemanticFailureLoggerTest.aContinuingFailureWarnsAgainOnceTheWindowHasPassed` FAIL(`Expected size: 2 but was: 1`)→PASS | - | `WARNED`를 key별 마지막 WARN 시각 맵으로 바꿔 시간 창(예: 1분)마다 다시 WARN | +| G-9b | Consider | `failureType`이 대부분 wrapper(`ExecutionException`) 이름 | 완료 | Wave 1–2 P6 (fcddab7e·Wave 2 커밋): `RedisSemanticFailureLogger.java:39`: `ExecutionException`/`CompletionException` cause를 풀어 기록. `aWrappedFailureIsReportedByItsCause` FAIL(`expected "IllegalStateException" but was "ExecutionException"`)→PASS | - | `report()`에서 `ExecutionException`·`CompletionException` cause를 풀고 기록 | +| G-10a | Consider | SCRIPT ACL probe가 `return {1}`이라 스크립트 내부 명령(`TIME`/`HSET`/`PEXPIRE`/`DEL`) 권한 부족을 기동 때 못 잡음 | 완료 | Wave 1–2 P6 (fcddab7e·Wave 2 커밋): `RedisSemanticScriptAclProbe.java:29-38`: probe key에서 `TIME`→`HSET`→`PEXPIRE`→`HGET`→`DEL`을 실행하고 읽은 값이 쓴 값과 같을 때만 `{1}`. `anAccountDeniedACommandTheScriptsCallFailsStartup`[HSET/PEXPIRE/HGET/DEL] FAIL→PASS. 실제 Redis standalone·cluster에서 `LiveRedisSemanticScriptAclProbeTest` 2건 PASS. 테스트 ACL `+time`은 NEW-5a(W1)에서 추가 | - | probe 스크립트를 probeKey에 `TIME`·`HSET`·`PEXPIRE`·`HGET`·`DEL`을 실제 실행하는 것으로 교체하고, 테스트 ACL에 `+time` 추가 | +| G-10b | Consider | `redisRequired`가 REGULAR lane만 probe → ADVANCED 자격 증명이 깨져도 readiness UP | 완료 | Wave 1–2 P6 (fcddab7e·Wave 2 커밋): `RedisCorrectnessRoles.java:71` `anyScriptRoleSelected`(idempotency/rate-limit/lease), `RedisSdkAutoConfiguration.java:296`: 스크립트 role이 선택되면 `redisRequired`가 SCRIPT lane에서 `SCRIPT LOAD`+`EVALSHA`(`return 1`, key `:probe:{health}:script`)도 확인(`RedisHealthContributor.java:92`). 실제 Redis `LiveRedisCompositionTest.aBrokenAdvancedAccountTakesRequiredRedisDown` FAIL(`expected: DOWN but was: UP`)→PASS, `aWorkingAdvancedAccountKeepsRequiredRedisUp` PASS. 단위 `RedisHealthContributorTest.aScriptLaneItsAccountCannotRunIsUnreachable` PASS | - | script capability가 선택되면 required contributor가 SCRIPT lane에서 등록 스크립트 EVALSHA로 probe | | G-11a | Consider | application executor를 adapter leaf에서 조립하고 provider마다 lease·codec 적용이 다름 | 완료 | `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/idempotency/IdempotencyProviderSelectionConfig.java:32-55`(`IdempotencySettings` 하나로 한 번 조립), `src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/capability/RedisIdempotencyConfig.java:31-35`(store만 제공). 「제거된 코드」 행 228. 테스트 `IdempotencyProviderCompositionTest.redisComposesOneExecutorOverTheRedisStoreAlone`. 커밋 `6d27356e` | - | - | | G-11b | Consider | 소유자 결정: 멱등성 executor 조립을 별도 `composition:*` 모듈로 이동 — 아직 app-bootstrap에 있고 sample이 두 번째 executor를 조립 | 남음 | `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/idempotency/IdempotencyProviderSelectionConfig.java:28-55`, `src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/bootstrap/idempotency/SampleIdempotencyConfig.java:39`. `src/composition/`에는 fileserver·notification만 있음 | W3 | `composition:idempotency` leaf를 `modules.json`에 등록하고 `IdempotencyProviderSelectionConfig`·`IdempotencySettings`를 옮긴 뒤 app-bootstrap·sample이 그 leaf를 쓰게 하고 `SampleIdempotencyConfig` 삭제 | | G-12a | Nit | `app-bootstrap/CLAUDE.md`가 없는 `autoconfigure/redis/RedisCapabilityConfig`·`RedisKeys`를 가리킴 | 완료 | `src/app-bootstrap/CLAUDE.md:92,102`가 `cache-redis`의 `capability/RedisCapabilityConfig`·`capability/RedisKeys`를 가리킴(두 파일 존재). 커밋 `6d27356e` | - | - | @@ -360,22 +372,22 @@ | G-12e | Nit | redis-runtime `RedisSdkSettings`가 바인딩하는 `app.redis.*` env key의 `owner_module`이 cache-redis | 남음 | `docs/registries/env-keys.yaml:2130,2162,2299` 등 23개(`capacity.maximum-in-flight-commands`, `capacity.reject-when-disconnected`, `lifecycle.*`, `tls.*`, `sentinel.*`, `authentication.*`, `cluster.*`, `pubsub.*`)가 `adapter-outbound-cache-redis`. `capacity.maximum-script-connections`(`:2146`)만 runtime으로 고쳐짐 | W5 | 해당 23개 행 `owner_module`을 `adapter-outbound-redis-runtime`으로 변경(`app.redis.enabled`는 cache-redis 기본 설정이 소유하므로 유지) | | H-1a | Critical | canonical bridge `@ConditionalOnBean(EncodedMessagePublisher)`가 platform auto-config보다 먼저 평가됨 | 완료 | `src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/autoconfigure/MessagingBridgeRootAutoConfiguration.java:35-36`(`afterName = "...MessagingPlatformRootAutoConfiguration"`). 테스트 `MessagingPlatformBridgeAutoConfigurationTest.bridgeIsAssembledAfterThePlatformRootThatProvidesThePublisher`, 실제 starter 조립 `KafkaCapabilityActivationTest.presentModuleIsOnAndPublishesThroughKafka`. 커밋 `6d27356e` | - | - | | H-1b | Critical | 빈 `producer-id`가 `@ConditionalOnProperty`를 통과해 `new ProducerId("")`로 기동 실패 | 완료 | 같은 파일 `:71,81-91`(`ProducerIdConfigured`: `StringUtils.hasText`). 테스트 `MessagingPlatformBridgeAutoConfigurationTest.blankProducerIdLeavesTheBridgeOutWithoutFailingStartup`("", " "). 커밋 `6d27356e` | - | - | -| H-2 | Required | Dynamic Target이 `trace-propagation=false`여도 `traceparent`·`X-Correlation-Id`를 외부 호스트로 보냄 | 남음 | `src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/dynamic/DefaultDynamicTargetGateway.java:154`(무조건 `PlatformHeaderPropagation.apply`). `tracePropagation`은 바인딩(`DynamicTargetAutoConfiguration.java:46`)만 되고 main에서 읽지 않음. 문서 `docs/httpclient/configuration-reference.md:179` "Off by default" | W1 | `prepare()`에 policy를 넘겨 `if (policy.tracePropagation())`일 때만 적용하고, 헤더 부재 테스트 추가 | -| H-3a | Required | Dynamic redirect가 303에서 method만 GET으로 바꾸고 body는 유지 | 남음 | `src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/dynamic/DefaultDynamicTargetGateway.java:98,134`, `src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/api/operation/HttpOperation.java:91-101`(`withMethod`가 body 유지) | W1 | 303 hop에서 `EmptyBody`로 교체(`BlockingRedirectCoordinator`와 같은 처리) | -| H-3b | Required | Dynamic redirect가 307/308에서 `BODY_NOT_REPLAYABLE` 검사 없이 body 재전송 | 남음 | 같은 파일 `:121-136`(`RedirectEvaluator` 미사용) | W1 | hop마다 `RedirectEvaluator.evaluate`를 호출해 재전송 불가 body면 거부 | -| H-3c | Required | Dynamic redirect가 cross-origin hop에서 호출자 헤더(`X-Api-Key` 등 `HeaderPolicy` 허용 헤더)를 그대로 전달 | 남음 | 같은 파일 `:95-98`(매 hop `operation` 헤더 재사용, `SensitiveHeaderStripper` 미사용) | W1 | origin이 바뀌면 `SensitiveHeaderStripper.stripForCrossOrigin`으로 헤더 정리 후 다음 hop 준비 | +| H-2 | Required | Dynamic Target이 `trace-propagation=false`여도 `traceparent`·`X-Correlation-Id`를 외부 호스트로 보냄 | 완료 | Wave 1–2 P11 (fcddab7e·Wave 2 커밋): `DefaultDynamicTargetGatewayTest.traceHeadersStayOffTheWireWhenThePolicyDisablesPropagation` FAIL(`Expecting actual: [true, true] to contain exactly [false, false]`)→PASS, 켜진 경우 `traceHeadersAreSentWhenThePolicyEnablesPropagation` PASS. `HC/dynamic/DefaultDynamicTargetGateway.java:186` | - | `prepare()`에 policy를 넘겨 `if (policy.tracePropagation())`일 때만 적용하고, 헤더 부재 테스트 추가 | +| H-3a | Required | Dynamic redirect가 303에서 method만 GET으로 바꾸고 body는 유지 | 완료 | Wave 1–2 P11 (fcddab7e·Wave 2 커밋): `DefaultDynamicTargetGatewayTest.seeOtherHopSendsAGetWithoutTheOriginalBody` FAIL(`["GET", "{"name":"grace"}"]` ≠ `["GET", ""]`)→PASS. `HC/dynamic/DefaultDynamicTargetGateway.java:155` | - | 303 hop에서 `EmptyBody`로 교체(`BlockingRedirectCoordinator`와 같은 처리) | +| H-3b | Required | Dynamic redirect가 307/308에서 `BODY_NOT_REPLAYABLE` 검사 없이 body 재전송 | 완료 | Wave 1–2 P11 (fcddab7e·Wave 2 커밋): `DefaultDynamicTargetGatewayTest.temporaryRedirectWithAOneShotBodyIsRejectedAsNotReplayable` FAIL(`Expecting actual not to be null` — 예외 없이 재전송)→PASS. hop마다 `RedirectEvaluator` 판정 `HC/dynamic/DefaultDynamicTargetGateway.java:133-150`(거부 `:147`, 메트릭 outcome=거부 코드) | - | hop마다 `RedirectEvaluator.evaluate`를 호출해 재전송 불가 body면 거부 | +| H-3c | Required | Dynamic redirect가 cross-origin hop에서 호출자 헤더(`X-Api-Key` 등 `HeaderPolicy` 허용 헤더)를 그대로 전달 | 완료 | Wave 1–2 P11 (fcddab7e·Wave 2 커밋): `DefaultDynamicTargetGatewayTest.crossOriginHopDropsTheCallerSuppliedApiKey` FAIL(`[true, true]` ≠ `[true, false]`)→PASS. `HC/dynamic/DefaultDynamicTargetGateway.java:162`. 수정 방향대로 `SensitiveHeaderStripper` 표준 이름만 제거함 — 관례 밖 이름의 호출자 헤더는 P11-new-4 | - | origin이 바뀌면 `SensitiveHeaderStripper.stripForCrossOrigin`으로 헤더 정리 후 다음 hop 준비 | | H-3d | Required | `DefaultDynamicTargetGateway.exchange`를 호출하는 테스트 0건 | 남음 | httpclient 전체에서 `DefaultDynamicTargetGateway` 참조는 main 2파일(`DefaultDynamicTargetGateway.java`, `DynamicTargetAutoConfiguration.java`)뿐 | W4 | httpclient `src/test`에 redirect 계약 테스트(303 body 제거, 307 1회, cross-origin 헤더 제거, trace off) 추가 | -| H-4a | Required | 허용된 API-key 헤더 `X-Client-Key`가 cross-origin redirect에서 제거되지 않음 | 남음 | `src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/security/SensitiveHeaderStripper.java:23,31-33`(`x-api-key`·`api-key`만), `src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/restclient/BlockingExecutionSupport.java:90`(`standard()` 사용), `src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/autoconfigure/HttpClientAuthenticationAutoConfiguration.java:34-35` | W1 | `BlockingRedirectCoordinator`의 cross-origin 처리에서 실제 해석된 `RequestCredentials.headers().keySet()`도 함께 제거 | +| H-4a | Required | 허용된 API-key 헤더 `X-Client-Key`가 cross-origin redirect에서 제거되지 않음 | 완료 | Wave 1–2 P11 (fcddab7e·Wave 2 커밋): `BlockingRedirectCoordinatorTest.crossOriginHopDropsTheProfileCredentialHeader` FAIL(`[true, true]` ≠ `[true, false]`)→PASS. `HC/restclient/BlockingAttemptExecutor.java:187`(붙인 자격증명 헤더 이름을 stripper에 추가), `HC/security/SensitiveHeaderStripper.java:61`(`alsoStripping`, `withAdditional`은 이것에 위임 — H-4b(W3) 삭제 대상은 그대로). 참고: 기동 검증이 API key + `allowCrossOrigin`을 이미 거부하므로 방어 계층 수정 | - | `BlockingRedirectCoordinator`의 cross-origin 처리에서 실제 해석된 `RequestCredentials.headers().keySet()`도 함께 제거 | | H-4b | Required | `SensitiveHeaderStripper.withAdditional` main 호출자 0 | 남음 | `src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/security/SensitiveHeaderStripper.java:47-55` | W3 | H-4a 적용 후 `withAdditional` 삭제 | -| H-5a | Required | reactive 경로가 실패 단계를 기록하지 않아 전송 후 실패도 `VALIDATION`(NOT_SENT)으로 분류 → 호출자가 실행된 POST를 재전송 | 남음 | `src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/webclient/ReactiveAttemptExecutor.java:166-167`(`baseMetadata.stage()`), webclient 패키지에 `AttemptProgressTracker` 0건. D4는 httpclient reactive를 건드리지 않음(`HttpServiceClientAutoConfiguration.java:52-54`가 계속 조립) | W2 | `exchangeToMono` 안에서 요청 전송 뒤 `REQUEST_BODY`, 응답 수신 시 `RESPONSE_HEADERS`/`RESPONSE_BODY`를 기록해 classifier에 넘김 | -| H-5b | Required | `DataBufferLimitException`(응답 크기 초과)이 어디서도 매핑되지 않아 NOT_SENT/connect 실패로 보고 | 남음 | `src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/webclient/WebClientResponseMapper.java:33`, `reactor/ReactorFailureClassifier.java:106-108`(fallback `notSent(UNKNOWN)`) | W2 | `WebClientResponseMapper`에서 `DataBufferLimitException`을 `HttpResponseTooLargeException`으로 변환 | -| H-5c | Required | 모르는 transport 실패가 mapper `default`에서 `HttpConnectException`이 됨 | 남음 | `src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/restclient/StableBlockingExceptionMapper.java:37` | W2 | `default`를 전용 unknown 예외 타입으로 바꾸고 blocking·reactive 둘 다 테스트 | -| H-6a | Required | OAuth2 토큰 네트워크 조회가 `ConcurrentHashMap.compute` 안에서 실행돼 같은 bin 호출자가 모니터에서 대기(N번째 ≈ N×10s) | 남음 | `src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/auth/OAuth2CredentialProvider.java:61-67` | W2 | `cache.get` + 만료 검사 → lock 밖에서 `tokenLoader.load(key)` → `cache.put`(single-flight는 loader가 이미 보장) | -| H-6b | Required | timeout 난 호출자가 공유 future를 `cancel(true)` → 뒤늦은 합류자는 raw `CancellationException`, pool 스레드는 인터럽트 안 됨 | 남음 | `src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/auth/SingleFlightTokenLoader.java:79-83,104`(`CancellationException` catch 없음) | W2 | 호출자 timeout에서는 cancel하지 않고 `inFlight`에서만 제거, `CancellationException`을 `HttpAuthenticationException`으로 변환 | +| H-5a | Required | reactive 경로가 실패 단계를 기록하지 않아 전송 후 실패도 `VALIDATION`(NOT_SENT)으로 분류 → 호출자가 실행된 POST를 재전송 | 해당 없음(코드 삭제) | Wave 1–2 P11 (fcddab7e·Wave 2 커밋): D `06764fcb`에서 `webclient/ReactiveAttemptExecutor` 삭제. blocking은 단계 기록함: `HC/restclient/BlockingAttemptExecutor.java:233,238`(`tracker.enter(REQUEST_BODY/RESPONSE_HEADERS)`)이 classifier로 전달 | - | `exchangeToMono` 안에서 요청 전송 뒤 `REQUEST_BODY`, 응답 수신 시 `RESPONSE_HEADERS`/`RESPONSE_BODY`를 기록해 classifier에 넘김 | +| H-5b | Required | `DataBufferLimitException`(응답 크기 초과)이 어디서도 매핑되지 않아 NOT_SENT/connect 실패로 보고 | 해당 없음(코드 삭제) | Wave 1–2 P11 (fcddab7e·Wave 2 커밋): D `06764fcb`에서 `WebClientResponseMapper`·`ReactorFailureClassifier` 삭제. blocking은 크기 초과를 `HC/restclient/ResponseSizeLimiter.java:42,50`에서 `HttpResponseTooLargeException`으로 던지고 `BlockingAttemptExecutor.java:303`이 `RESPONSE_TOO_LARGE`로 분류 | - | `WebClientResponseMapper`에서 `DataBufferLimitException`을 `HttpResponseTooLargeException`으로 변환 | +| H-5c | Required | 모르는 transport 실패가 mapper `default`에서 `HttpConnectException`이 됨 | 완료 | Wave 1–2 P11 (fcddab7e·Wave 2 커밋): blocking 결함(`StableBlockingExceptionMapper`)이라 W2에서 수정. `StableBlockingExceptionMapperTest.unknownTransportFailureIsNotReportedAsAConnectFailure` FAIL(`expected HttpUnknownTransportException but was HttpConnectException`)→PASS. `HC/restclient/StableBlockingExceptionMapper.java:40`, 새 타입 `HC/api/error/HttpUnknownTransportException.java`. reactive 쪽 테스트는 코드 삭제로 없음 | - | `default`를 전용 unknown 예외 타입으로 바꾸고 blocking·reactive 둘 다 테스트 | +| H-6a | Required | OAuth2 토큰 네트워크 조회가 `ConcurrentHashMap.compute` 안에서 실행돼 같은 bin 호출자가 모니터에서 대기(N번째 ≈ N×10s) | 완료 | Wave 1–2 P11 (fcddab7e·Wave 2 커밋): `OAuth2CredentialProviderTest.aSlowRefreshDoesNotHoldUpAnotherRegistrationThatSharesItsBin` FAIL(`java.util.concurrent.TimeoutException` — 같은 bin의 다른 registration이 느린 refresh 뒤에서 대기)→PASS. `HC/auth/OAuth2CredentialProvider.java:65-69`(`cache.get` → lock 밖 `tokenLoader.load` → `cache.put`) | - | `cache.get` + 만료 검사 → lock 밖에서 `tokenLoader.load(key)` → `cache.put`(single-flight는 loader가 이미 보장) | +| H-6b | Required | timeout 난 호출자가 공유 future를 `cancel(true)` → 뒤늦은 합류자는 raw `CancellationException`, pool 스레드는 인터럽트 안 됨 | 완료 | Wave 1–2 P11 (fcddab7e·Wave 2 커밋): `SingleFlightTokenLoaderTest.aCallerThatJoinedLaterStillGetsTheTokenAfterAnEarlierCallerTimedOut` FAIL(`ExecutionException: CancellationException`)→PASS. timeout·interrupt 분기에서 `cancel(true)` 제거 `HC/auth/SingleFlightTokenLoader.java:81`, `CancellationException`→`HttpAuthenticationException` `:113` | - | 호출자 timeout에서는 cancel하지 않고 `inFlight`에서만 제거, `CancellationException`을 `HttpAuthenticationException`으로 변환 | | H-7a | Consider | `categoryOf`가 `getSimpleName()` 문자열 switch로 blocking·reactive에 중복 | 남음 | `src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/restclient/BlockingAttemptExecutor.java:291-312`, `webclient/ReactiveAttemptExecutor.java:182-200` | W3 | `HttpClientException`에 `FailureCategory category()`를 두고 각 하위 예외가 구현, 두 switch 삭제 | -| H-7b | Consider | reactive `categoryOf`에 CircuitOpen·RateLimitRejected·BulkheadRejected가 없어 telemetry가 `UNKNOWN` | 남음 | `ReactiveAttemptExecutor.java:182-200`(3개 누락), 같은 예외를 `resilience/ReactiveAttemptResiliencePipeline.java:57-70`이 던짐 | W2 | H-7a로 해결. 별도로 하면 reactive switch에 세 case 추가 | -| H-8 | Consider | bridge `prepare`가 모든 `RuntimeException`을 cause 없이 `REJECTED_BEFORE_SEND`로 바꿈 | 남음 | `src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapter.java:60-64` | W2 | catch를 `IllegalArgumentException`으로 좁히고 cause를 `OutboxRelayFailureReport`(또는 거부 예외)로 전달 | -| H-9 | Consider | Kafka seam이 `InterruptedException`을 삼켜 종료 중에도 relay가 항목당 최대 30s 계속 처리 | 남음 | `src/adapter/outbound/messaging-kafka/src/main/java/dev/caskeleton/adapter/outbound/messaging/kafka/KafkaSenderAutoConfiguration.java:98-110`(`.get()`의 인터럽트가 `throws Exception`으로 나감), `src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/outbox/OutboxMessagePublishAdapter.java:94`(→ AMBIGUOUS), `.../core/OutboundMessagePublisher.java:36`(로그 후 무시) | W2 | `kafkaSender` 람다에서 `InterruptedException`을 잡아 `Thread.currentThread().interrupt()` 후 재던지기, `OutboundMessagePublisher`는 interrupt 상태를 보존 | +| H-7b | Consider | reactive `categoryOf`에 CircuitOpen·RateLimitRejected·BulkheadRejected가 없어 telemetry가 `UNKNOWN` | 해당 없음(코드 삭제) | Wave 1–2 P11 (fcddab7e·Wave 2 커밋): D `06764fcb`에서 `ReactiveAttemptExecutor` 삭제. blocking `categoryOf`에는 세 case 있음 `HC/restclient/BlockingAttemptExecutor.java:308-310` | - | H-7a로 해결. 별도로 하면 reactive switch에 세 case 추가 | +| H-8 | Consider | bridge `prepare`가 모든 `RuntimeException`을 cause 없이 `REJECTED_BEFORE_SEND`로 바꿈 | 완료 | Wave 1–2 P11 (fcddab7e·Wave 2 커밋): `PlatformIntegrationEventPublishAdapterTest.aFailureOtherThanAnIncompatibleValueIsNotTurnedIntoARefusal` FAIL(`Expecting actual not to be null` — NPE가 REJECTED_BEFORE_SEND로 바뀜)→PASS. catch를 `IllegalArgumentException`으로 좁힘 `MSG/platformbridge/PlatformIntegrationEventPublishAdapter.java:62`; 나머지 예외는 전파되어 relay가 실제 원인 타입으로 재시도·보고. 수정 방향 중 "cause를 거부 결과에 싣기"는 하지 않음: 포트가 `OutboxPublishOutcome` enum만 돌려줘 원인을 실을 자리가 없고, 실으려면 application-core 포트·relay 변경(계층 밖)이 필요. 로그로 남기는 것도 예외 메시지를 운영 로그에 쓰지 않는 규칙(`Slf4jOutboxRelayFailureReportAdapter`)과 충돌 | - | catch를 `IllegalArgumentException`으로 좁히고 cause를 `OutboxRelayFailureReport`(또는 거부 예외)로 전달 | +| H-9 | Consider | Kafka seam이 `InterruptedException`을 삼켜 종료 중에도 relay가 항목당 최대 30s 계속 처리 | 완료 | Wave 1–2 P11 (fcddab7e·Wave 2 커밋): `KafkaSenderInterruptionTest.anInterruptedAcknowledgementWaitRethrowsWithTheInterruptFlagRestored` FAIL(`[InterruptedException, false]`)→PASS, `OutboundMessagePublisherTest.anInterruptedSendIsSwallowedWithTheInterruptFlagKept`·`OutboxMessagePublishAdapterTest$FailClosedPath.anInterruptedSendKeepsTheRelayThreadInterrupted` FAIL(`Expecting value to be true but was false`)→PASS. `src/adapter/outbound/messaging-kafka/src/main/java/dev/caskeleton/adapter/outbound/messaging/kafka/KafkaSenderAutoConfiguration.java:115`, `MSG/core/OutboundMessagePublisher.java:41`, `MSG/outbox/OutboxMessagePublishAdapter.java:100`(삼키는 지점 두 곳 모두 복원) | - | `kafkaSender` 람다에서 `InterruptedException`을 잡아 `Thread.currentThread().interrupt()` 후 재던지기, `OutboundMessagePublisher`는 interrupt 상태를 보존 | | H-10a | Nit | `src/README.md`가 HTTP client 활성화를 `ca-skeleton.capabilities.http-client`·`OutboundHttpSettings.bindLegacy`로 설명(실제 `app.httpclient.enabled`, `OutboundHttpSettings`는 main에 없음) | 남음 | `src/README.md:331-361`. 같은 파일 `:266` 표는 올바름 | W5 | `:331-361` 절을 `app.httpclient.enabled`/`APP_HTTPCLIENT_ENABLED`와 `runtimeOnly` 한 줄 기준으로 다시 쓰고 legacy 문단 삭제 | | H-10b | Nit | Kafka javadoc이 "프로젝트가 `KafkaSender`를 제공해야 한다"고 적음(leaf가 직접 제공) | 남음 | `src/adapter/outbound/messaging-kafka/src/main/java/dev/caskeleton/adapter/outbound/messaging/kafka/KafkaSender.java:6-8`, `KafkaAdapterConfig.java:14`. 실제 `KafkaSenderAutoConfiguration.java:95-110`이 제공 | W5 | 두 javadoc을 "이 leaf가 `kafkaSeamProducer` 위 기본 `KafkaSender`를 제공하고 서비스가 bean으로 대체 가능"으로 수정 | | H-10c | Nit | `KafkaAdapterSettings.addresses()` 호출자 0 | 남음 | `src/adapter/outbound/messaging-kafka/src/main/java/dev/caskeleton/adapter/outbound/messaging/kafka/KafkaAdapterSettings.java:41-45` | W5 | 메서드 삭제(파싱 검증은 `BrokerAddress`로 유지) | @@ -398,23 +410,23 @@ | I-1c | Critical | `WebRequestContext` argument resolver는 등록되지만 `store` 호출이 0이라 선언한 컨트롤러는 항상 예외(500) | 남음 | 등록 `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/mvc/autoconfigure/WebMvcPlatformAutoConfiguration.java:64-74`, `WebMvcRequestContextHolder.store`(`.../mvc/context/WebMvcRequestContextHolder.java:34`) 호출처 main·test 0, `WebMvcRequestContextArgumentResolver.java:40`이 `require` → `IllegalStateException`. `WebRequestContext` 소비자 0 | W3 | 소비자가 없으므로 `core/WebRequestContext`·`mvc/context/*`·`webMvcRequestContextConfigurer` bean을 삭제(쓰려면 `WebMvcRequestIdFilter`에서 `store` 호출) | | I-1d | Critical | `WebResourceNotVisibleException`이 기본 envelope 계약에서 catch-all 500 | 해당 없음(코드 삭제) | `208077fd`에만 `web/error/WebResourceNotVisibleException.java` 존재, HEAD grep 0. 제거 표 「WebProblem 어휘」「durable operation HTTP 투영」 | - | - | | I-1e | Critical | 실서버 IT가 `OperationFixtureController`로 합성 context를 넣어 결함을 못 잡음 | 해당 없음(코드 삭제) | 제거 표 「WebProblem·budget·throttle·operation fixture와 lane」(`testkit/operation/`). HEAD에 `OperationFixtureController` 없음 | - | - | -| I-2a | Required | 인증 없는 알림 콜백이 `@RequestBody byte[]`로 본문 전체를 읽은 뒤 크기 검사 | 남음 | `src/adapter/inbound/web-notification/src/main/java/dev/caskeleton/adapter/inbound/web/notification/platform/callback/NotificationCallbackMvcController.java:78-85`, 같은 경로 `CallbackMvcSecurityConfiguration.java:35` `permitAll` | W1 | 컨트롤러가 `HttpServletRequest`만 받아 `getContentLengthLong() > maxBodyBytes`면 413, 본문은 `getInputStream().readNBytes(maxBodyBytes + 1)`로 읽고 초과 시 413 | -| I-2b | Required | 운영 servlet 앱 전체에 요청 본문 크기·JSON 깊이 상한이 없음 | 남음 | budget 필터 삭제 후 대체 없음: `src/adapter/inbound/web/src/main`·`src/app-bootstrap/src/main/resources`에 본문 상한/`StreamReadConstraints` 설정 grep 0. `docs/web/repository-adaptation.md:147-151`이 "application column 미적용"이라 기재 | W1 | web leaf에 Content-Length 초과 413 + 스트림 상한 필터 하나(또는 `JsonMapperBuilderCustomizer`로 `StreamReadConstraints.maxDocumentLength/maxNestingDepth`)를 두고 Envelope `PAYLOAD_TOO_LARGE`로 응답 | +| I-2a | Required | 인증 없는 알림 콜백이 `@RequestBody byte[]`로 본문 전체를 읽은 뒤 크기 검사 | 완료 | Wave 1–2 P10 (fcddab7e·Wave 2 커밋): `NotificationCallbackMvcControllerTest.aDeclaredOversizeBodyIsRefusedWithoutReadingIt`, `anUndeclaredOversizeBodyIsRefusedAfterReadingOneByteOverTheCeiling` FAIL(컴파일: `method callback … cannot be applied to given types` — `@RequestBody byte[]` 시그니처)→PASS. 컨트롤러가 `HttpServletRequest`만 받아 Content-Length 초과면 읽지 않고 413, 아니면 `readNBytes(max+1)`(`src/adapter/inbound/web-notification/src/main/java/dev/caskeleton/adapter/inbound/web/notification/platform/callback/NotificationCallbackMvcController.java:85,91`) | - | 컨트롤러가 `HttpServletRequest`만 받아 `getContentLengthLong() > maxBodyBytes`면 413, 본문은 `getInputStream().readNBytes(maxBodyBytes + 1)`로 읽고 초과 시 413 | +| I-2b | Required | 운영 servlet 앱 전체에 요청 본문 크기·JSON 깊이 상한이 없음 | 완료 | Wave 1–2 P10 (fcddab7e·Wave 2 커밋): `RequestBodyBoundaryTest.jsonBodyOverTheCeilingIsRejectedAsPayloadTooLarge` FAIL(`Response status expected:<413> but was:<200>`)→PASS, `jsonBodyWithinTheCeilingReachesTheController` PASS. 새 `JsonBodyLimitFilter`(`src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/mvc/filter/JsonBodyLimitFilter.java:33`): JSON 본문만(multipart·form·tus·콜백은 각자 상한), 선언 Content-Length 초과는 읽기 전에, chunked/거짓 길이는 스트림 계수로 `MaxUploadSizeExceededException` → 기존 핸들러 413 `PAYLOAD_TOO_LARGE` Envelope. Jackson이 bean 속성 안에서 이 예외를 감싸는 경우도 413(`GlobalExceptionHandler.java:281`), `GlobalExceptionHandlerTest.unreadableBodyCausedByTheSizeCeilingIsPayloadTooLarge` FAIL(`expected: 413 CONTENT_TOO_LARGE but was: 400 BAD_REQUEST`)→PASS, `JsonBodyLimitFilterTest` 2건. 상한은 `backend.web.mvc.max-json-body-size`(기본 1MB, `WebMvcPlatformSettings.java:31`). JSON 깊이는 Jackson 3.1 기본 `StreamReadConstraints`(maxNestingDepth 500, maxNumberLength 1000)가 Boot가 만든 mapper에 이미 적용되어 있어 따로 두지 않음(`MapperBuilder`에 factory 제약을 바꾸는 API가 없어 customizer로는 설정 불가). 문서·문자열 길이는 본문 상한이 막음 | - | web leaf에 Content-Length 초과 413 + 스트림 상한 필터 하나(또는 `JsonMapperBuilderCustomizer`로 `StreamReadConstraints.maxDocumentLength/maxNestingDepth`)를 두고 Envelope `PAYLOAD_TOO_LARGE`로 응답 | | I-2c | Required | 콜백 크기 테스트가 배열을 직접 넘겨 컨버터 버퍼링 경로를 검증 안 함 | 남음 | `src/adapter/inbound/web-notification/src/test/java/dev/caskeleton/adapter/inbound/web/notification/platform/callback/NotificationCallbackMvcControllerTest.java:118-124`(`aBodyOverTheTransportCeilingIsRefusedBeforeIngress`) | W4 | MockMvc/실서버로 큰 본문(및 Content-Length 없는 chunked)을 보내 413과 ingress 미호출을 단언 | | I-2d | Required | `backend.web.budgets.enabled=true`면 없는 `BudgetProblemMapper` 빈을 찾아 기동 실패 | 해당 없음(코드 삭제) | 제거 표 「요청 budget 필터 (`WebMvcBudgetFilter`, `BudgetProblemMapper`)」. `WebMvcBudgetExceptionHandler`·`backend.web.budgets` grep 0 | - | - | | I-2e | Required | 문서가 본문 크기·JSON 깊이를 "Application, always"가 막는다고 기재 | 완료 | `docs/web/repository-adaptation.md:147-151` "Removed 2026-09-25 … no longer enforces the application column" 배너. 커밋 `6d27356e` | - | - | | I-3a | Required | Envelope 계약에서 override 안 된 Spring MVC 예외(필수 파라미터·헤더·part 누락 등)가 `application/problem+json`으로 새어 나감 | 남음 | `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/error/GlobalExceptionHandler.java:52`(RESEH 상속, `handleExceptionInternal` override 없음), `.../envelope/EnvelopeBodyAdvice.java:44-46`(비 JSON은 감싸지 않음). 실경로: `src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/adapter/inbound/web/controller/PosterImagePublicationController.java:58`(필수 `Idempotency-Key`), `LegacyPosterImageController.java:36`(필수 part) | W3 | 소유자 결정(Envelope 통일)대로 `GlobalExceptionHandler`에서 `handleExceptionInternal` 하나를 override해 status → `OperationalError` 매핑 후 `ErrorResponseFactory.body` 반환 | -| I-3b | Required | `@Valid` 클래스 레벨 제약 위반이 `details: []`로 나감 | 남음 | `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/error/GlobalExceptionHandler.java:262-265`(`getFieldErrors()`만) | W2 | `getGlobalErrors()`도 `ClientSafeValidationDetails`로 변환해 details에 합침 | +| I-3b | Required | `@Valid` 클래스 레벨 제약 위반이 `details: []`로 나감 | 완료 | Wave 1–2 P10 (fcddab7e·Wave 2 커밋): 커밋 `5c08d3be`(W2). `GlobalExceptionHandlerTest.classLevelConstraintViolationIsReportedAgainstTheRequest` FAIL(`expected: [{code=INVALID, field=request, message=Invalid value}] but was: []`)→PASS. `getAllErrors()`(`GlobalExceptionHandler.java:263`), `ClientSafeValidationDetails.from(ObjectError)`가 global error를 `field=request`로(`ClientSafeValidationDetails.java:56`) | - | `getGlobalErrors()`도 `ClientSafeValidationDetails`로 변환해 details에 합침 | | I-3c | Required | 필수 파라미터/헤더 누락·`HandlerMethodValidationException` 등의 에러 형식 테스트 0건 | 남음 | web·bootstrap·sample 테스트에 `MissingServletRequestParameter`/`MissingRequestHeader`/`HandlerMethodValidation` grep 0 | W4 | web slice 테스트로 필수 파라미터·헤더 누락 시 Envelope 400(`application/json`)을 단언 | -| I-4a | Required | `RequestLoggingFilter`가 Spring Security 뒤에서 돌아 401/403 응답 meta id가 null, 접근 로그 누락 | 남음 | `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/filter/RequestLoggingFilter.java:37`(`@Order` 없음 → LOWEST), MDC는 `:65-71`에서만 채움, `.../auth/AuthErrorResponseWriter.java:46,69`가 MDC 기반 meta 사용. 순서 테스트 `src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/runtime/OperationalContractRuntimeTest.java:100-122`는 세 필터끼리만 비교, `src/adapter/inbound/web/src/testFixtures/java/dev/caskeleton/webtestkit/PipelineOrderFixtureApplication.java:46`은 `WebAdapterAutoConfiguration`을 제외 | W2 | MDC(request/correlation/trace id) 채우기를 `WebMvcRequestIdFilter`(HIGHEST+10)로 옮기고 `OperationalContractRuntimeTest`에 "request-id 필터 order < `springSecurityFilterChain` order" 단언 추가 | -| I-4b | Required | trace id를 두 필터가 따로 생성해 서로 불일치 | 남음 | `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/filter/RequestLoggingFilter.java:69`(자체 traceparent 생성) vs `.../mvc/filter/WebMvcRequestIdFilter.java:122`(`WebTraceId` 생성, 요청 속성 `:80`) | W2 | `RequestLoggingFilter`는 `WebMvcRequestIdFilter.traceId(request)`만 읽고 생성하지 않음 | -| I-5a | Required | `FORWARDED_HEADERS_TRUSTED` 레이트리밋 키가 XFF 맨 왼쪽 값을 peer 검증 없이 사용 → 비인증 레이트리밋 우회 | 남음 | `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/ratelimit/ForwardedHeaderClientIpResolver.java:15`, 테스트가 이 동작을 고정 `src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/ratelimit/RateLimitKeyResolverTest.java:79-86` | W1 | 이 모드를 삭제하고 `server.forward-headers-strategy=native` + `server.tomcat.remoteip.internal-proxies`로 `getRemoteAddr()`를 쓰는 `REMOTE_ADDR_ONLY` 하나로(운영 정본은 `forward-headers-strategy`라는 W3-2b 결정과 일치) | +| I-4a | Required | `RequestLoggingFilter`가 Spring Security 뒤에서 돌아 401/403 응답 meta id가 null, 접근 로그 누락 | 완료 | Wave 1–2 P10 (fcddab7e·Wave 2 커밋): request/correlation/trace/span id 발급·MDC·응답 헤더를 `WebMvcRequestIdFilter`(HIGHEST+10, Security 앞) 한 곳으로 이동(`src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/mvc/filter/WebMvcRequestIdFilter.java:95,103`), ERROR/ASYNC 재디스패치에 같은 값 복원. `SecurityModeWebContractTest.anUnauthenticatedRejectionCarriesTheAssignedRequestIdInItsMeta`(실제 JWT security 체인이 쓴 401 Envelope의 `meta.requestId` = `X-Request-Id`) FAIL(`expected: "13499754-…" but was: null`)→PASS. `WebMvcRequestIdFilterTest.assignedIdentifiersAreOnMdcDuringTheChainAndMatchWhatTheResponseCarries`·`inboundCorrelationIdLosesLineBreaksBeforeReachingMdc` FAIL(`No value present` / `expected "fooFAKE LOG" but was null`)→PASS, `mdcIsClearedWhenTheRequestLeavesTheFilter`·`anErrorRedispatchRestoresTheSameIdentifiersOnMdc` PASS. 순서: `OperationalContractRuntimeTest.requestIdFilterIsRegisteredAheadOfSpringSecurity`(`src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/runtime/OperationalContractRuntimeTest.java:135`, 슬라이스에 `SecurityFilterAutoConfiguration`을 넣어 실제 `springSecurityFilterChain` 등록과 비교) PASS. fixture 문제: `PipelineOrderFixtureApplication`은 의미 순서·async 1회 관측만 증명한다고 주석에 적고 실제 순서는 위 두 테스트가 맡음. `RequestLoggingFilter`는 principal을 읽으려고 보안 체인 안쪽에 남음 → 체인이 거절한 요청의 접근 로그 줄은 없고 entry point/access-denied handler의 `security failure` 로그(이제 request_id 포함)가 대신함 | - | MDC(request/correlation/trace id) 채우기를 `WebMvcRequestIdFilter`(HIGHEST+10)로 옮기고 `OperationalContractRuntimeTest`에 "request-id 필터 order < `springSecurityFilterChain` order" 단언 추가 | +| I-4b | Required | trace id를 두 필터가 따로 생성해 서로 불일치 | 완료 | Wave 1–2 P10 (fcddab7e·Wave 2 커밋): trace는 `WebMvcRequestIdFilter`만 만든다(`TraceParent.parse` 또는 새 root, WebTraceId·MDC·응답 `traceparent`가 같은 값). `RequestLoggingFilterTest.assignsNoIdentifierOrTraceOfItsOwn` FAIL(`Expecting [X-Request-Id, X-Correlation-Id, traceparent] not to contain …`)→PASS, `WebMvcRequestIdFilterTest.responseTraceparentCarriesTheTraceIdTheFilterAssigned`·`validInboundTraceparentIsAdoptedWithItsSpanAndEchoed` FAIL(`NullPointerException` — 헤더 없음)→PASS. `RequestLoggingFilter`의 id/trace 생성 코드 삭제(`src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/filter/RequestLoggingFilter.java`), 옮겨진 테스트는 `WebMvcRequestIdFilterTest`로 | - | `RequestLoggingFilter`는 `WebMvcRequestIdFilter.traceId(request)`만 읽고 생성하지 않음 | +| I-5a | Required | `FORWARDED_HEADERS_TRUSTED` 레이트리밋 키가 XFF 맨 왼쪽 값을 peer 검증 없이 사용 → 비인증 레이트리밋 우회 | 완료 | Wave 1–2 P10 (fcddab7e·Wave 2 커밋): 커밋 `983cc832`(W1). 결정대로 `FORWARDED_HEADERS_TRUSTED` 모드 삭제. 비인증 키는 `getRemoteAddr()` 하나(`src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/ratelimit/RateLimitKeyResolver.java:45`). `RateLimitWebConfigTest.spoofedForwardedForDoesNotChangeTheUnauthenticatedKey`(Review Focus 3: 옛 `client-ip-mode=forwarded-headers-trusted`를 남긴 배포에서 위조 XFF 두 개를 보내도 키가 peer 주소 하나) FAIL(`Expecting actual ["9:CLIENT_IP\|12:198.51.100.1\|…", "…198.51.100.2…"] to contain exactly ["9:CLIENT_IP\|11:203.0.113.7\|…" ×2]`)→PASS. `server.forward-headers-strategy=framework`면 rate limit 켤 때 기동 거부(`RateLimitWebConfig.java:38`), `RateLimitWebConfigTest.frameworkForwardHeadersStrategyIsRefusedWhileRateLimiting` FAIL(`context started successfully`)→PASS. env 키 `APP_RATE_LIMIT_CLIENT_IP_MODE`·설정 키 `app.rate-limit.client-ip-mode` 삭제(`env-keys.yaml`, `.env.example`, `cache-redis.yml`, sample `application.yml`, README 2곳). `APP_SERVER_FORWARD_HEADERS_STRATEGY` allowed_values `[none, native]`, `.env.example` 값 `framework`→`native`, `server.yml` 주석에 `native` + `server.tomcat.remoteip.internal-proxies` 명시 | - | 이 모드를 삭제하고 `server.forward-headers-strategy=native` + `server.tomcat.remoteip.internal-proxies`로 `getRemoteAddr()`를 쓰는 `REMOTE_ADDR_ONLY` 하나로(운영 정본은 `forward-headers-strategy`라는 W3-2b 결정과 일치) | | I-5b | Required | forwarded 헤더 신뢰 판단이 여러 곳에 흩어짐 | 남음 | `TrustedProxyPolicy`·reactive 콜백은 삭제됐으나 3곳 남음: `src/app-bootstrap/src/main/resources/config/server.yml:11`(`forward-headers-strategy`), `src/adapter/inbound/web-notification/src/main/java/dev/caskeleton/adapter/inbound/web/notification/platform/callback/ExternalRequestUrlResolver.java:31-53`(정확 문자열 집합), I-5a resolver(검증 없음) | W3 | `ExternalRequestUrlResolver`의 forwarded 파싱과 I-5a 모드를 지우고 Tomcat RemoteIpValve(`forward-headers-strategy=native`)가 고친 `getScheme/getServerName/getRemoteAddr`만 사용 | -| I-6a | Required | category 생략 시 컨트롤러가 `"transactional"`을 넣어 marketing suppression이 적용되지 않음(HARD-STOP 4 후보) | 남음 | `src/adapter/inbound/web-notification/src/main/java/dev/caskeleton/adapter/inbound/web/notification/platform/submission/NotificationSubmissionController.java:51-52,88-90` | W2 | 결정(2026-09-25): category 필수 — 생략하면 400, 판정은 유스케이스로 이동 | +| I-6a | Required | category 생략 시 컨트롤러가 `"transactional"`을 넣어 marketing suppression이 적용되지 않음(HARD-STOP 4 후보) | 완료 | Wave 1–2 P10 (fcddab7e·Wave 2 커밋): 결정 13. 컨트롤러의 `DEFAULT_CATEGORY="transactional"` 삭제, `request.category()`를 그대로 넘김(`NotificationSubmissionController.java:87`). 판정은 `AcceptNotificationCommand`(application-notification, `AcceptNotificationCommand.java:70`)가 → `IllegalArgumentException` → 400 `BAD_PARAMETER`. `NotificationSubmissionControllerTest.submissionWithoutCategoryIsRejectedBeforeTheUseCaseRuns` FAIL(`[500, 1]` — 유스케이스가 transactional로 호출됨)→PASS(`[400, 0]`), `AcceptNotificationApplicationUseCaseTest.anAcceptanceWithoutCategoryIsRefusedRatherThanDefaulted` PASS(소유자 명시) | - | 결정(2026-09-25): category 필수 — 생략하면 400, 판정은 유스케이스로 이동 | | I-6b | Required | 템플릿 버전 기본값 `1`, locale 기본값 `Locale.getDefault()`(호스트 JVM)를 컨트롤러가 결정 | 남음 | `.../submission/NotificationSubmissionController.java:48-49,82-84,121-123`, `.../submission/NotificationTemplateController.java:75`(경로 prefix는 I-6a와 같음) | W3 | 세 값을 command에서 `Optional`로 받고 기본값은 알림 유스케이스가 설정값으로 적용 | | I-7 | Required | `wire-type-manifest.yaml`이 런타임에 없는 wire 계약(`LONG: INTEGER_STRING`, `BIG_DECIMAL: DECIMAL_STRING`)을 공개 | 남음 | 기본 web의 bean은 삭제(`WebMvcPlatformAutoConfiguration` 3 bean)됐지만 opt-in leaf로 옮겨져 남음: `src/adapter/inbound/web-advanced/src/main/resources/META-INF/web/wire-type-manifest.yaml:3-9,25-30`, `.../web-advanced/src/main/java/dev/caskeleton/adapter/inbound/web/advanced/contract/WebWireTypeManifest.java`. 적용하는 Jackson 설정 없음 | W5 | 소비자 0이므로 yaml과 `advanced/contract/` 4개 타입·테스트를 삭제하고 web-advanced README.md:45 행 정리 | | I-8a | Consider | 운영 소비자 없는 라이브러리 코드가 기본 web leaf에 있고 운영 경로와 중복 | 완료 | 기본 web leaf 패키지는 `auth·authz·conditional·config·controller·core·envelope·error·filter·http·mvc·observability·pagination·ratelimit·settings`만(`security/cache/openapi/idempotency` 없음). 라이브러리는 opt-in `src/adapter/inbound/web-advanced`(README.md:45 목록), 중복 세대는 삭제(제거 표 「forwarded header 라이브러리」「CORS/CSRF 프로필」「cache 정책 카탈로그」「JSON mapper factory」「OpenAPI customizer」). D1 결정, 커밋 `6d27356e` | - | - | -| I-8b | Consider | 더 엄격한 CORS 규칙(`WebCorsPolicyValidator`)을 `CorsSettings`에 합치지 않고 삭제만 함 → 기동 시 origin 형식 검증 없음 | 남음 | `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/settings/CorsSettings.java:24-53`(빈 목록·`*`+credentials만 검사, 기본 allowedHeaders `*` `:48-49`), 사용처 `.../auth/SecurityConfig.java:151-154`. 옛 규칙은 `git show 208077fd:.../security/WebCorsPolicyValidator.java`(정확 origin·소문자·와일드카드·credentials+`*` 헤더 거부) | W1 | `CorsSettings` compact constructor에 옛 validator 규칙(origin = scheme://host[:port] 소문자·경로 없음·와일드카드 없음, credentials면 헤더 `*` 거부) 추가 + 거부 테스트 | +| I-8b | Consider | 더 엄격한 CORS 규칙(`WebCorsPolicyValidator`)을 `CorsSettings`에 합치지 않고 삭제만 함 → 기동 시 origin 형식 검증 없음 | 완료 | Wave 1–2 P10 (fcddab7e·Wave 2 커밋): NEW-10b와 같은 수정. `CorsSettingsTest.originThatIsNotExactlySchemeHostPortFailsWithTheEnvKeyName`(10개 입력) FAIL(`Expecting actual not to be null` — 예외 없음)→PASS, `exactOriginWithPortIsAccepted` PASS. `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/settings/CorsSettings.java:44,64`. 옛 validator 규칙 중 둘은 넣지 않음: "소문자만"(Spring `CorsConfiguration.checkOrigin`이 대소문자 무시 비교), "credentials면 allowedHeaders `*` 거부"(Spring은 `*`를 요청 헤더 목록으로 되돌려 주므로 credentials와 함께 동작한다 — 넣으면 지금 동작하는 기본값(`*`)을 깨뜨림) | - | `CorsSettings` compact constructor에 옛 validator 규칙(origin = scheme://host[:port] 소문자·경로 없음·와일드카드 없음, credentials면 헤더 `*` 거부) 추가 + 거부 테스트 | | I-8c | Consider | `observability/WebAuditPublisher` 참조 0 | 해당 없음(코드 삭제) | 제거 표 「2세대 관측 (`WebAccessLog*`, `WebAudit*` …)」, HEAD grep 0 | - | - | | I-8d | Consider | `RateLimitInterceptor.disabled(...)`가 M2 이후 dead | 남음 | `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/ratelimit/RateLimitInterceptor.java:48`, 호출은 `src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/ratelimit/RateLimitInterceptorTest.java:137`뿐 | W3 | `disabled` 팩토리와 그 테스트 삭제 | | I-8e | Consider | `cursor/CursorCodec.withDevKey()` 키 하드코딩 | 해당 없음(코드 삭제) | 제거 표 「서명 커서 코덱 (`CursorCodec`, `CursorException`)」, HEAD grep 0 | - | - | @@ -423,17 +435,17 @@ | I-9c | Consider | reactive problem 핸들러가 `spring.mvc.*`로 켜짐 | 해당 없음(코드 삭제) | 제거 표 「web WebFlux 플랫폼」(D4) | - | - | | I-9d | Consider | reactive 스택엔 envelope 핸들러가 없어 스위치 off면 Boot 기본 에러 JSON | 해당 없음(코드 삭제) | 제거 표 「web WebFlux 플랫폼」「알림 콜백 WebFlux 핸들러」(D4) | - | - | | J-1 | Critical | 인가 단계가 fragment를 예산 없이 지수적으로 전개(cost 단계 이전) | 완료 | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlDocumentAuthorizationHandler.java:118-155`(fragment 1회 전개 + 방문 예산), `.../cost/GraphQlDocumentShapeAnalyzer.java:221-227`(같음). 테스트 `GraphQlDocumentAuthorizationHandlerTest.exponentialFragmentFanOutIsAuthorizedWithinTheTimeBound`(`doublingFragments(40)`). 커밋 `6d27356e` | - | - | -| J-2 | Required | `__typename`을 introspection으로 취급해 introspection off에서 Apollo/urql 쿼리 전부 거부 | 남음 | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/cost/GraphQlDocumentShapeAnalyzer.java:41,212`(`startsWith("__")`), 기본 off `src/adapter/inbound/graphql/src/main/resources/config/graphql.yml:19`. `__typename` 허용 테스트 없음 | W2 | `__schema`/`__type`만 막고 systemTest에 introspection off + `{ _health __typename }` 성공 추가 | -| J-3a | Required | 마스킹된 실패가 어디에도 로그되지 않음(executionId가 가리키는 기록 없음) | 남음 | graphql main에 `LoggerFactory/getLogger/System.Logger` 0 파일. 마스킹 분기 `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/error/GraphQlExceptionResolver.java:55`, 요청 단계 `.../runtime/GraphQlPlatformWebInterceptor.java:94-95,161-165`, `.../runtime/GraphQlPlatformInstrumentation.java:84-88` | W2 | 마스킹 분기(unknown → `INTERNAL_ERROR`)에서 executionId와 예외를 ERROR로 한 번 로그 | +| J-2 | Required | `__typename`을 introspection으로 취급해 introspection off에서 Apollo/urql 쿼리 전부 거부 | 완료 | Wave 1–2 P8 (fcddab7e·Wave 2 커밋): `cost/GraphQlFragmentReachabilityTest.typenameIsNotTreatedAsIntrospection`(3건) FAIL(`selectsIntrospection`이 true) → PASS, systemTest `runtime/GraphQlPlatformExecutionPathTest.typenameIsAnsweredWhenTheClientProfileForbidsIntrospection`(introspection 금지 profile + `{ _health __typename }`) FAIL(`GRAPHQL_DOCUMENT_SHAPE_REJECTED`/`INTROSPECTION` 에러) → PASS. `__schema`/`__type`만 차단. `.../cost/GraphQlDocumentShapeAnalyzer.java:50,221`. 커밋 `aa5f4d90` | - | `__schema`/`__type`만 막고 systemTest에 introspection off + `{ _health __typename }` 성공 추가 | +| J-3a | Required | 마스킹된 실패가 어디에도 로그되지 않음(executionId가 가리키는 기록 없음) | 완료 | Wave 1–2 P8 (fcddab7e·Wave 2 커밋): `error/GraphQlExceptionResolverTest.aMaskedFailureIsLoggedOnceAtErrorWithItsExecutionId` FAIL(`Expected size: 1 but was: 0`) → PASS. 마스킹 분기에서 `graphql failure masked as INTERNAL_ERROR (executionId=…)` + 예외를 ERROR 한 번. 모든 경로가 이 분기를 거치게 된 것은 S5-#6a 수정 덕분. `.../error/GraphQlExceptionResolver.java:61`. 커밋 `aa5f4d90` | - | 마스킹 분기(unknown → `INTERNAL_ERROR`)에서 executionId와 예외를 ERROR로 한 번 로그 | | J-3b | Required | Javadoc이 "detail은 로그에 남는다"고 주장 | 남음 | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlWireErrorMapper.java:30-32`, `.../runtime/GraphQlPlatformRejectionMapper.java:26-29` | W5 | J-3a 로그 추가와 함께 문구를 실제 로그 위치에 맞춤 | -| J-4a | Required | DataLoader `GraphQlBatchTimeoutException`·`GraphQlMissingKeyException` CODE를 mapper가 몰라 `INTERNAL_ERROR`로 나감 | 남음 | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlPlatformRejectionMapper.java:54-121`에 두 타입 없음. 카탈로그 테스트는 "modelled-only"(`src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/error/GraphQlErrorCodeCatalogTest.java:52-55`)인데 `src/adapter/inbound/graphql/CLAUDE.md:161`은 DataLoader `wired` | W2 | `mapKnown`에 두 예외 매핑 추가(batch timeout은 `REQUEST_TIMEOUT`, missing key는 전용 code)하고 `platformCodes()`·카탈로그 테스트 갱신 | -| J-4b | Required | blocking bridge 포화가 Reactor `Schedulers.fromExecutor`를 거쳐 `RejectedExecutionException`으로 감싸여 `INTERNAL_ERROR` + 거부마다 ERROR 로그 | 남음 | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlBatchLoaderRegistrar.java:121-125`, `.../runtime/GraphQlBlockingBridge.java:78-85`; mapper에 `GraphQlBlockingBridgeFullException` 없음 | W2 | Reactor scheduler 대신 `Mono.fromFuture(CompletableFuture.supplyAsync(..., bridge executor))`로 거부를 `Mono.error`로 받고, cause chain에서 bridge-full을 찾아 `DEPENDENCY_UNAVAILABLE`로 매핑 | +| J-4a | Required | DataLoader `GraphQlBatchTimeoutException`·`GraphQlMissingKeyException` CODE를 mapper가 몰라 `INTERNAL_ERROR`로 나감 | 완료 | Wave 1–2 P8 (fcddab7e·Wave 2 커밋): `runtime/GraphQlWireErrorMapperTest.dataLoaderFailuresKeepAPlatformCode`(2건) FAIL(`["INTERNAL_ERROR","INTERNAL"]`) → PASS. batch timeout → `REQUEST_TIMEOUT`/TIMEOUT, missing key → 새 platform code `GRAPHQL_BATCH_KEY_MISSING`/BUSINESS. `.../runtime/GraphQlPlatformRejectionMapper.java:106,113`, `.../error/GraphQlErrorCode.java:48,72`, `GraphQlErrorCodeCatalogTest` 갱신. Spring GraphQL `ExceptionResolversExceptionHandler`가 `CompletionException`을 벗겨 넘기는 것 확인(2.0.5 소스). 커밋 `aa5f4d90` | - | `mapKnown`에 두 예외 매핑 추가(batch timeout은 `REQUEST_TIMEOUT`, missing key는 전용 code)하고 `platformCodes()`·카탈로그 테스트 갱신 | +| J-4b | Required | blocking bridge 포화가 Reactor `Schedulers.fromExecutor`를 거쳐 `RejectedExecutionException`으로 감싸여 `INTERNAL_ERROR` + 거부마다 ERROR 로그 | 해당 없음(코드 삭제) | Wave 1–2 P8 (fcddab7e·Wave 2 커밋): bridge 포화 경로(`GraphQlBlockingBridge`·`Schedulers.fromExecutor`)는 event loop 전용이라 D4(servlet 단일)에 맞춰 삭제. 남은 경로는 호출 스레드 inline(`Mono.fromCallable`)이라 예외가 그대로 mapper에 도달(J-4a 매핑 적용). 삭제 커밋 `6390bf89` | - | Reactor scheduler 대신 `Mono.fromFuture(CompletableFuture.supplyAsync(..., bridge executor))`로 거부를 `Mono.error`로 받고, cause chain에서 bridge-full을 찾아 `DEPENDENCY_UNAVAILABLE`로 매핑 | | J-4c | Required | DataLoader 실패 테스트가 `getErrors().isNotEmpty()`만 단언 | 남음 | `src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlBatchLoaderRegistrationTest.java:137,150,166,202` | W4 | 각 실패의 wire `extensions.code`/`category`를 단언 | | J-5 / X1-#2d | Required | stable extensions allowlist가 아무도 처리하지 않는 `idempotencyKey`를 허용 | 완료 | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/http/GraphQlExtensionsPolicy.java:40-42`(`stableDefaults()` → `none()`), 테스트 `GraphQlRequestEnvelopeValidatorTest.stableDefaultsRejectAnIdempotencyKeyExtensionAsUnregistered`. 제거 표 「GraphQL mutation 멱등성」. 커밋 `6d27356e`
X1-#2d: `GraphQlExtensionsPolicy.java:29` 기본 allowlist `Set.of()`, mutation 멱등성 타입 삭제(`docs/capability-status.md:231`), 커밋 `6d27356e` | - | - | | J-6 | Required | `GraphQlClientPolicy.persistedOperationOnly`가 아무 동작도 안 함(fail-open) | 해당 없음(코드 삭제) | 제거 표 「`GraphQlClientPolicy`의 `persistedOperationOnly`·`maxResponseNodes`·`maxResponseBytes`」, graphql src grep 0 | - | - | | J-7 | Consider | preparsed 캐시가 조회마다 전역 lock 아래 전체 항목을 순회 | 남음 | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/execution/BoundedPreparsedDocumentProvider.java:167-177`(끝까지 순회). 맵은 이미 access-order(`:57`) | W3 | `expireIdle`에서 첫 미만료 항목을 만나면 `break`(access-order라 뒤는 모두 더 최근) | -| J-8 | Consider | 인가 root 타입 이름을 `"Query/Mutation/Subscription"` 리터럴로 고정 → root 이름을 바꾸면 규칙 미적용(allow 규칙 fail-open) | 남음 | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlDocumentAuthorizationHandler.java:74-84` | W1 | `context.schema().getQueryType()/getMutationType()/getSubscriptionType()`의 이름 사용 | -| J-9a | Consider | body-cap 필터 스트리밍 경로에서 `BodyTooLargeException`이 감싸이면 413 대신 500 가능 | 남음 | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/runtime/servlet/GraphQlRequestBodyLimitFilter.java:85-91`(예외 타입 직접 catch), `:205`(RuntimeException). 미확인: 실제 wrapping 여부는 실행해 봐야 함 | W2 | catch를 `Exception`으로 넓혀 cause chain에서 `BodyTooLargeException`을 찾으면 413 | +| J-8 | Consider | 인가 root 타입 이름을 `"Query/Mutation/Subscription"` 리터럴로 고정 → root 이름을 바꾸면 규칙 미적용(allow 규칙 fail-open) | 완료 | Wave 1–2 P8 (fcddab7e·Wave 2 커밋): `runtime/GraphQlDocumentAuthorizationHandlerTest.aProtectedFieldOnARenamedRootTypeIsStillDenied`(query·mutation 2건), `aContextWithoutASchemaIsRefusedInsteadOfGuessingRootNames` FAIL(`Expecting actual not to be null` — 거부 없이 통과) → PASS. root 이름을 `context.schema().getQueryType()/getMutationType()/getSubscriptionType()`에서 읽고, schema나 해당 root가 없으면 `IllegalStateException`(→ INTERNAL_ERROR, fail-closed). `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlDocumentAuthorizationHandler.java:68,87`. 커밋 `0392d8c9` | - | `context.schema().getQueryType()/getMutationType()/getSubscriptionType()`의 이름 사용 | +| J-9a | Consider | body-cap 필터 스트리밍 경로에서 `BodyTooLargeException`이 감싸이면 413 대신 500 가능 | 완료 | Wave 1–2 P8 (fcddab7e·Wave 2 커밋): 재현됨. systemTest `runtime/GraphQlPlatformExecutionPathTest.aChunkedBodyOverTheRawCapIsRefusedWith413`(Content-Length 없는 chunked 200KB 본문) FAIL(`expected: 413 but was: 500`) → PASS. 원인: `FrameworkServlet`(spring-webmvc 7.0.9 `FrameworkServlet.java:1006-1008`)이 decoder 안에서 던진 unchecked `BodyTooLargeException`을 `ServletException("Request processing failed")`으로 감쌈. `IOException/ServletException/RuntimeException`을 잡아 cause chain(최대 16단계)에서 찾으면 413, 아니면 그대로 rethrow. `.../runtime/servlet/GraphQlRequestBodyLimitFilter.java:85,98`. 커밋 `aa5f4d90` | - | catch를 `Exception`으로 넓혀 cause chain에서 `BodyTooLargeException`을 찾으면 413 | | J-9b | Consider | body-cap 필터의 chunked(Content-Length 없음) 경로 테스트 없음 | 남음 | graphql test·systemTest에 `chunked`/`Transfer-Encoding`/`BodyTooLarge` grep 0 | W4 | systemTest에 Content-Length 없는 chunked 초과 본문 → 413 케이스 추가 | | J-10a | Consider | `advanced/**` 134파일 도달 불가 | 해당 없음(코드 삭제) | 제거 표 「graphql `advanced/**` 전체」 | - | - | | J-10b | Consider | `compat`·`release`·`moduleboundary`(테스트 데이터가 운영 jar에) 도달 불가 | 해당 없음(코드 삭제) | 제거 표 「graphql 스키마 호환성 비교기 `compat/`」「graphql 릴리스 게이트 `release/`」「graphql 모듈 경계 모델 `moduleboundary/`」 | - | - | @@ -444,7 +456,7 @@ | J-10g | Consider | `schema/` 19개 중 16개 도달 불가 | 해당 없음(코드 삭제) | 제거 표 「schema gate·병렬 조립기 … 14개」. 남은 `schema/` 3개(`GraphQlScalar*`)는 자동 설정에서 도달 | - | - | | J-11a | Consider | CLAUDE.md가 Accept negotiation을 `wired`로 표기(`GraphQlMediaTypes` 도달 불가) | 해당 없음(코드 삭제) | 제거 표 「병렬 HTTP 전송 모델(… `GraphQlMediaTypes`, `GraphQlAcceptHeader` …)」, CLAUDE.md 등급 표에서 행 제거됨 | - | - | | J-11b | Consider | README/CLAUDE가 없는 `GraphqlExceptionResolver`와 "비-carrier는 null 반환 → Spring 기본 처리"를 설명(실제는 전부 마스킹) | 남음 | `src/adapter/inbound/graphql/README.md:64-79`, `src/adapter/inbound/graphql/CLAUDE.md:52,125` | W5 | 현재 구조(`GraphQlDataFetcherExceptionResolver` → `GraphQlWireErrorMapper`, unknown은 마스킹)로 해당 절 재작성 | -| J-12 / X2-P2-6b | Consider | prod가 익명 principal resolver로 기동한 뒤 모든 요청을 `AUTHENTICATION_REQUIRED`로 거부 | 남음 | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/autoconfigure/GraphQlPlatformAutoConfiguration.java:266-270`(기본 `anonymous()`), 같은 파일 `:296-309`는 authz policy만 prod에서 요구
X2-P2-6b: `AuthorizationPrincipal.java:13` tenant 없음, GraphQL 기본 resolver `GraphQlPrincipalResolver.anonymous()`(`GraphQlPlatformAutoConfiguration.java:269`), gRPC `GrpcAuthenticationPolicy.java:16` boolean, 가명은 `GraphQlIdentityFingerprinter`와 `UserPrincipalPseudonymizerPort`로 갈림 | W2 | `graphQlPrincipalResolver` 기본 bean도 `properties.production()`이면 `GraphQlPlatformConfigurationException`
X2-P2-6b: `AuthorizationPrincipal`에 tenant 추가해 모든 inbound가 생성, GraphQL에 Spring Security `Authentication` → principal 기본 resolver, 가명은 `UserPrincipalPseudonymizerPort` 하나로 | +| J-12 / X2-P2-6b | Consider | prod가 익명 principal resolver로 기동한 뒤 모든 요청을 `AUTHENTICATION_REQUIRED`로 거부 | 남음 | Wave 1–2 P8 (fcddab7e·Wave 2 커밋): `autoconfigure/GraphQlDeploymentModeContractTest.aProductionModeRefusesTheAnonymousPrincipalResolver`(PRODUCTION_INTERNAL·PUBLIC) FAIL(`to have failed but context started successfully`) → PASS, `aProductionModeWithAnExplicitPolicyAndResolverStarts` PASS. 기본 `graphQlPrincipalResolver` bean이 production이면 `GraphQlPlatformConfigurationException`(mode 없으면 REQUIRED_MESSAGE). `.../autoconfigure/GraphQlPlatformAutoConfiguration.java:243`. 커밋 `aa5f4d90`
J-12 부분은 완료(production에서 principal resolver가 없으면 기동 거부). X2-P2-6b 나머지(`AuthorizationPrincipal` tenant, gRPC 인증 정책, 가명 포트 통일)는 Wave 3 3-D | W3 | `graphQlPrincipalResolver` 기본 bean도 `properties.production()`이면 `GraphQlPlatformConfigurationException`
X2-P2-6b: `AuthorizationPrincipal`에 tenant 추가해 모든 inbound가 생성, GraphQL에 Spring Security `Authentication` → principal 기본 resolver, 가명은 `UserPrincipalPseudonymizerPort` 하나로 | | K-1 | Required | `HandshakeAdmissionPipeline`이 bearer/cookie 헤더 존재만으로 통과, 모든 사용자가 한 actor | 해당 없음(코드 삭제) | 제거 표 「platform catalog·정책 패키지 … `handshake` …」(K#1 명시). 현재 websocket main에 `handshake/` 없음 | - | - | | K-2a | Required | servlet 런타임에서 frame/fragment 상한(`FragmentAssembler`)이 동작하지 않음 | 해당 없음(코드 삭제) | 제거 표 「`inbound/FragmentAssembler`, … `maxFrameBytes`·`maxFragments` …」(K#2 명시) | - | - | | K-2b | Required | 실제 수신 상한이 Tomcat 기본 8 KiB이고 설정한 `maxMessageBytes`와 무관 | 완료 | handler가 whole message의 크기를 직접 검사 `src/adapter/inbound/websocket/src/main/java/dev/caskeleton/adapter/inbound/websocket/servlet/PlatformWebSocketHandler.java:79-86`, 컨테이너 버퍼를 `maxMessageBytes`와 맞추는 조립 예·설명 `src/adapter/inbound/websocket/README.md:108-124`. 커밋 `6d27356e` | - | - | @@ -453,13 +465,13 @@ | K-4 | Required | `SerializedOutboundWriter.drain()` 경쟁으로 메시지가 남겨짐 | 완료 | `src/adapter/inbound/websocket/src/main/java/dev/caskeleton/adapter/inbound/websocket/outbound/SerializedOutboundWriter.java:111-122`(unlock 후 `hasQueued()` 재확인 루프), 테스트 `SerializedOutboundWriterTest.nothingIsStrandedWhenBusy`(수동 drain 제거). 커밋 `6d27356e` | - | - | | K-5a | Required | `PlatformWebSocketHandler.stop()`이 웹 서버 종료 뒤 실행돼 1001을 못 보냄 | 완료 | `src/adapter/inbound/websocket/src/main/java/dev/caskeleton/adapter/inbound/websocket/servlet/PlatformWebSocketHandler.java:155-161`(`SmartLifecycle.DEFAULT_PHASE`), 테스트 `PlatformWebSocketHandlerTest.stopRunsBeforeTheWebServerGracefulShutdown`. 커밋 `6d27356e` | - | - | | K-5b | Required | 종료 IT가 context를 닫지 않고 `stop()`을 직접 호출 | 남음 | `src/adapter/inbound/websocket/src/systemTest/java/dev/caskeleton/adapter/inbound/websocket/runtime/TomcatWebSocketAbuseIT.java:71`(`handler.stop()`) | W4 | `shutdownClosesLiveConnections`에서 application context를 `close()`해 Spring lifecycle 순서로 1001을 받는지 단언 | -| K-6 | Required | gRPC 예외 인터셉터가 정상 close 뒤 `onComplete`·늦은 `onCancel`을 삼켜 스트리밍 정리 hook이 안 돎 | 남음 | `src/adapter/inbound/grpc/src/main/java/dev/caskeleton/adapter/inbound/grpc/GrpcExceptionHandlingInterceptor.java:67-80`(모든 콜백이 `closed`면 return), `:95`(OK close에도 `closed=true`). `GrpcExceptionHandlingInterceptorTest`에 onComplete/onCancel 테스트 없음 | W2 | `onComplete`/`onCancel`은 gate 없이 try/catch만으로 위임, gate는 `onMessage`/`onHalfClose`/`onReady`에만; `setOnCloseHandler`가 실행되는 wire 테스트 추가 | +| K-6 | Required | gRPC 예외 인터셉터가 정상 close 뒤 `onComplete`·늦은 `onCancel`을 삼켜 스트리밍 정리 hook이 안 돎 | 완료 | Wave 1–2 P5 (fcddab7e·Wave 2 커밋): `GrpcP1BoundaryWireTest.aSuccessfullyCompletedCallStillRunsTheServiceOnCloseHandler`(실제 Netty, `setOnCloseHandler`) FAIL(`Expecting value to be true but was false`)→PASS, `GrpcExceptionHandlingInterceptorTest.aCancelAfterTheCallClosedStillReachesTheServiceListener` FAIL→PASS. gate는 onMessage/onHalfClose/onReady에만, onCancel/onComplete는 try/catch만 `src/adapter/inbound/grpc/src/main/java/dev/caskeleton/adapter/inbound/grpc/GrpcExceptionHandlingInterceptor.java:70,79`. 커밋 `a498ad84` | - | `onComplete`/`onCancel`은 gate 없이 try/catch만으로 위임, gate는 `onMessage`/`onHalfClose`/`onReady`에만; `setOnCloseHandler`가 실행되는 wire 테스트 추가 | | K-7 | Required | `WebSocketSessionRegistry` register/deregister 경쟁으로 actor당 상한 초과 | 해당 없음(코드 삭제) | 제거 표 「platform catalog·정책 패키지 … `session` …」(K#7 명시) | - | - | | K-8 | Consider | conflation 교체가 연결당 상한을 건너뛰고 손실을 `CONFLATED`로 보고 | 완료 | `src/adapter/inbound/websocket/src/main/java/dev/caskeleton/adapter/inbound/websocket/outbound/OutboundQueue.java:192-210`(로컬·전역 둘 다 검사, 실패 시 `DROPPED`), 테스트 `OutboundQueueTest.conflationThatDoesNotFitTheConnectionBoundIsReportedAsDropped`. 커밋 `6d27356e` | - | - | | K-9 | Consider | `WebSocketCorrelationRegistry.countFor`가 노드 전체 in-flight를 요청마다 순회 | 해당 없음(코드 삭제) | 제거 표 「platform catalog·정책 패키지 … `handler` …」, 현재 websocket main에 `handler/` 없음 | - | - | | K-10a | Consider | gRPC 인증 정책이 yes/no만 반환해 식별자를 `Context`로 넘기지 못함 | 남음 | `src/adapter/inbound/grpc/src/main/java/dev/caskeleton/adapter/inbound/grpc/GrpcAuthenticationPolicy.java:16`(`boolean isAuthenticated(Metadata)`) | W3 | `Optional authenticate(Metadata)`로 바꾸고 인터셉터가 `Context.Key`에 담아 `Contexts.interceptCall` | -| K-10b | Consider | gRPC 인증 정책 예외를 로그 없이 삼킴 | 남음 | `src/adapter/inbound/grpc/src/main/java/dev/caskeleton/adapter/inbound/grpc/GrpcAuthenticationInterceptor.java:35-41`(`catch (RuntimeException ignored)`) | W2 | 예외 타입·메서드명만 WARN 로그(자격 증명 제외) 후 UNAUTHENTICATED | -| K-11a | Consider | live STOMP inbound/outbound 채널 executor queue가 무제한(`Integer.MAX_VALUE`) | 남음 | `src/adapter/inbound/websocket/src/main/java/dev/caskeleton/adapter/inbound/websocket/stomp/WebSocketConfig.java:66-69`(interceptor만 등록, `taskExecutor().queueCapacity` 없음), `configureClientOutboundChannel` 없음 | W1 | `registration.taskExecutor().corePoolSize/maxPoolSize/queueCapacity(n)`을 inbound·outbound 둘 다 설정(`WebSocketSettings`에서 값) | +| K-10b | Consider | gRPC 인증 정책 예외를 로그 없이 삼킴 | 완료 | Wave 1–2 P5 (fcddab7e·Wave 2 커밋): `GrpcAuthenticationInterceptorTest.aThrowingPolicyIsLoggedWithItsTypeAndMethodButNotItsMessage` FAIL(출력 `""`)→PASS. 예외 타입·메서드만 WARN, 메시지(자격 증명 가능)는 남기지 않음 `src/adapter/inbound/grpc/src/main/java/dev/caskeleton/adapter/inbound/grpc/GrpcAuthenticationInterceptor.java:44`. 커밋 `a498ad84` | - | 예외 타입·메서드명만 WARN 로그(자격 증명 제외) 후 UNAUTHENTICATED | +| K-11a | Consider | live STOMP inbound/outbound 채널 executor queue가 무제한(`Integer.MAX_VALUE`) | 완료 | Wave 1–2 P5 (fcddab7e·Wave 2 커밋): `WebSocketAutoConfigurationTest.clientChannelExecutorsAreBoundedByTheConfiguredQueueCapacity` FAIL(`[(2147483647, false), (2147483647, false)]` ≠ `[(64, true), (64, true)]`)→PASS. inbound·outbound 둘 다 스레드 CPU×2 고정(core=max), 큐 `app.websocket.channel-queue-capacity`(기본 10000, `@Positive`) `src/adapter/inbound/websocket/src/main/java/dev/caskeleton/adapter/inbound/websocket/stomp/WebSocketConfig.java:74,83`, `.../stomp/WebSocketSettings.java:32`. 새 env 키 `APP_WEBSOCKET_CHANNEL_QUEUE_CAPACITY`(`docs/registries/env-keys.yaml`, `src/.env.example`), `verifyEnvKeys` 통과. 커밋 `b39d3de0` | - | `registration.taskExecutor().corePoolSize/maxPoolSize/queueCapacity(n)`을 inbound·outbound 둘 다 설정(`WebSocketSettings`에서 값) | | K-11b | Consider | 동기 `@EventListener` 브로드캐스트가 구독자 수만큼 발행 스레드에서 fan-out | 남음 | `src/adapter/inbound/websocket/src/main/java/dev/caskeleton/adapter/inbound/websocket/stomp/LiveEventStompBroadcaster.java:57-87` | W3 | best-effort(R1) 문서 기준이면 브로커 채널에 executor를 두거나(`configureMessageBroker`의 `brokerChannel` taskExecutor) 리스너를 비동기로 | | K-12a | Nit | `moduleboundary/WebSocketStableModule` `HANDSHAKE` Javadoc 중복 | 해당 없음(코드 삭제) | 제거 표 「websocket main의 검증용 코드(`moduleboundary`, `evidence`, `release`)」 | - | - | | K-12b | Nit | websocket `CLAUDE.md`가 Boot 4.0.0 표기 | 완료 | `src/adapter/inbound/websocket/CLAUDE.md:8` "Spring Boot 4.0.8"(`208077fd`은 4.0.0). 커밋 `6d27356e` | - | - | @@ -476,61 +488,61 @@ |---|---|---|---|---|---|---| | M-1 | Critical | outbox relay·DLQ·retry-topic이 이미 인코딩된 payload를 다시 인코딩해 전부 REJECTED (= Critical #7) | 완료 | `src/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisher.java:307-311` (`EncodedMessage` payload는 codec을 거치지 않고 content type만 확인). 테스트 `DefaultMessagePublisherTest.aDeadLetterPublishedThroughThisPublisherReachesTheTransportWithTheOriginalBytes`, `OutboxRelayTest.aRowRelayedThroughTheRealPublisherIsMarkedPublished`·`aRowRelayedThroughTheRealPublisherReachesTheTransportWithItsStoredBytes`(실제 `DefaultMessagePublisher` 사용). 커밋 `6d27356e` | - | - | | M-2a | Critical | `KafkaSecurityConfigurer`를 producer에 적용하지 않아 TLS/SASL 설정이 있어도 PLAINTEXT·무인증으로 연결 (= Critical #8) | 완료 | `src/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaMessagingAutoConfiguration.java:176,187-236` (security profile을 configurer로 병합, profile·CredentialProvider가 없으면 기동 실패). 테스트 `KafkaProducerSecurityTest.aTlsBrokerWithScramCredentialsConfiguresTheProducerForSaslSsl`·`aBrokerDeclaringTlsWithoutASecurityEntryFailsStartup`·`aSecurityEntryWithoutACredentialProviderFailsStartup`. 커밋 `6d27356e` | - | - | -| M-2b | Critical | producer는 `spring.kafka.bootstrap-servers`만 읽고, 필수로 검증하는 `app.messaging.brokers..bootstrap-servers`는 쓰지 않음(주소를 두 곳에 적어야 함) | 남음 | `src/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaMessagingAutoConfiguration.java:155-165` vs `src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationCompiler.java:97-99` | W2 | 결정(2026-09-25): capability 설정 prefix는 하나(AGENTS.md 기준 4) → producer가 `app.messaging.brokers..bootstrap-servers`를 읽고 `spring.kafka.bootstrap-servers` 의존 제거 | -| M-2c | Critical | broker별 `access.publishable` ACL이 compile만 되고 publish 판정에는 쓰이지 않음 | 남음 | `src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationCompiler.java:235-238`에서 만든 정책을 아무도 안 씀. 판정은 `src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingCoreAutoConfiguration.java:414-419` (`DeclaredDestinationAccess.of(destinations.all())`) | W1 | `messagingDestinationAccess` bean이 선언 destination 집합과 compile된 `BrokerSecurityProfile`의 `publishable`을 교집합으로 쓰게 바꾸고, 허용 목록 밖 publish가 REJECTED인 테스트 추가 | -| M-2d | Critical | SASL JAAS username에 credential 참조 id가 들어감 | 남음 | `src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaSecurityConfigurer.java:148-151`. 새 테스트가 결함을 고정함: `src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaProducerSecurityTest.java:84-94` (`username="kafka-producer"` = credential id) | W1 | `CredentialRuntime`(또는 provider 응답)에 username을 넣고 JAAS는 그 값을 쓰게 바꿈. 테스트 기대값도 provider가 준 username으로 교체 | -| M-2e | Critical | truststore/keystore 설정 키가 없음. `MutualTls`는 `SSL` + `sasl.mechanism=NONE`만 넣고 keystore를 안 넣음 → 사설 CA·mTLS broker 연결 불가 | 남음 | `src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaSecurityConfigurer.java:85-90,109`. `git grep -i "truststore\|keystore" -- 'src/messaging/*/src/main'` 0건 | W1 | `BrokerSecuritySettings`에 truststore/keystore(경로·유형·비밀번호 credential id) 추가 후 `ssl.truststore.*`/`ssl.keystore.*` 설정. 지원 전까지 `MutualTls`는 기동 거부 | -| M-2f | Critical | credential rotation이 producer에 반영 안 됨(기동 때 JAAS 문자열 1회 생성) | 남음 | `src/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaMessagingAutoConfiguration.java:234-235` (`Instant.now()`로 1회 configure), `:246-250` (generation 1 고정). `src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaSecurityConfigurer.java:17-20` javadoc은 rotation이 된다고 적음 | W1 | rotation 시 producer를 새로 만들고 transport generation을 올리는 경로 추가. 당장 안 하면 javadoc을 정정하고 만료 임박 credential은 기동/주기 검사에서 경고 | -| M-3 | Required | handler timeout 때 `cancel(true)`가 실행 중 handler를 멈추지 않는데 permit을 바로 반환 → 같은 offset 중복 처리 (H6 회귀) | 남음 | `src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrar.java:316-319` (`!cancel(true) && !isDone()` 분기 도달 불가). 테스트 `src/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrarTest.java:157,201`은 `isCancelled()`만 확인 | W2 | timeout이면 항상 `handler.whenComplete(...)`에서 permit·work count를 반환. 테스트는 "첫 handler가 끝나기 전 같은 offset 재dispatch 없음"을 단언 | -| M-4a | Required | admission 거부(`MessageTooLarge`/`Backpressure`)가 `try` 밖에서 동기 예외로 던져짐 | 남음 | `src/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisher.java:227` | W2 | `admission.admit`을 `try` 안으로 옮겨 크기 초과는 REJECTED(retryable=false), backpressure는 REJECTED(retryable=true)로 반환 | -| M-4b | Required | relay에 row별 catch가 없고 CLAIM이 `attempts`를 올리지 않음 → poison row가 매 lease 재claim, 같은 batch 나머지도 lease 만료까지 묶임 | 남음 | `src/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/OutboxRelay.java:166-168,223-227` (`toEnvelope`·`publish` 예외가 `runOnce` 밖으로), `src/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/JdbcOutboxRepository.java:113-135` (attempts 미증가), `src/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/OutboxEnvelopeFactory.java:71` (예약 header row에서 throw) | W2 | `runOnce` 루프에 row별 try/catch → `markFailed(lease, code)`. 테스트: 예약 header row는 FAILED, 같은 batch 나머지 row는 PUBLISHED | -| M-4c | Required | 실패한 relay pass를 로그 없이 삼키고 `failedPasses()`를 읽는 곳이 없음 | 남음 | `src/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/OutboxRelayWorker.java:184-189`, `:155` (main 호출 0) | W2 | catch에서 원인 포함 WARN 로그, `failedPasses`를 meter로 노출 | -| M-5a | Required | publish가 deadline 적용 전 caller thread를 최대 약 65초 막음(InFlightLimiter 5초 + `max.block.ms` 기본 60초) | 남음 | `src/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisher.java:227-233`, `src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingCoreAutoConfiguration.java:436-437`, `src/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaMessagingAutoConfiguration.java:162-177` (`MAX_BLOCK_MS` 없음) | W2 | `producerConfig`에 `max.block.ms`를 기본 publish timeout 이하로 설정, limiter 대기도 남은 budget 안으로 제한 | -| M-5b | Required | reactive facade가 blocking publish를 subscriber thread에서 실행 | 남음 | `src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/DefaultReactiveMessagePublisher.java:37` | W2 | `Mono.fromCompletionStage(...)` 뒤에 `.subscribeOn(Schedulers.boundedElastic())` | -| M-6 | Required | outbox/inbox cleanup job이 제한 없는 단일 DELETE (MSG-006 §6 불완전) | 남음 | `src/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/OutboxCleanupJob.java:50`, `src/messaging/messaging-inbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/inbox/InboxCleanupJob.java:56` (1-인자 purge), `InboxCleanupJob.java:21` `DEFAULT_BATCH_SIZE` 미사용. bounded 버전 `JdbcOutboxRepository.java:485`, `JdbcInboxRepository.java:141`은 main 호출 0 | W2 | 두 job이 `(cutoff, batchSize)` 버전을 삭제 수 < batch가 될 때까지 반복 호출. port의 1-인자 메서드(`src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/OutboxRepository.java:103`, `InboxRepository.java:45`) 삭제 | -| M-7 | Required | consumer poison message가 지연 없이 무한 재시도(partition 영구 정지) | 남음 | `src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrar.java:115` (기본 quarantine `unavailable()`), `:607-609` (`enqueueRequeue(Duration.ZERO)`), `src/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultDeliveryProcessor.java:70-97` (시도 한도 없음) | W2 | requeue에 `BackoffCalculator` 지연, 시도 한도 초과 시 DLQ/park. production에서 quarantine이 `unavailable()`이면 기동 거부 | +| M-2b | Critical | producer는 `spring.kafka.bootstrap-servers`만 읽고, 필수로 검증하는 `app.messaging.brokers..bootstrap-servers`는 쓰지 않음(주소를 두 곳에 적어야 함) | 완료 | Wave 1–2 P1 (fcddab7e·Wave 2 커밋): NEW-4c와 같은 결함. 결정대로 `spring.kafka.bootstrap-servers` 의존 제거(NEW-4c의 "spring.kafka fallback + 불일치 시 실패" 추천은 이 결정으로 대체). `KafkaProducerConfigTest.theProducerConnectsToTheBrokerEntryAddressesNotToSpringKafka`·`aBrokerWithoutAnEntryFailsStartupNamingTheKey` FAIL(broker 항목이 있어도 spring.kafka가 없으면 기동 실패 / spring.kafka만으로 기동) → PASS. producer는 type=kafka인 `app.messaging.brokers.` 항목 정확히 하나에서 만든다(`src/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaMessagingAutoConfiguration.java:150-205`). 모듈 기본값이 `APP_MESSAGING_KAFKA_BROKERS`를 `app.messaging.brokers.kafka.bootstrap-servers`로 연결(`src/adapter/outbound/messaging-kafka/src/main/resources/config/module-defaults/messaging.yml`), `KafkaCapabilityActivationTest` 2건 PASS. 함께 수정: `docs/registries/env-keys.yaml`(APP_MESSAGING_KAFKA_BROKERS 주석), `src/README.md`, `src/adapter/outbound/messaging-kafka/README.md`, compose 계약(`src/config/runtime/compose-profile-contracts.json`에서 `SPRING_KAFKA_BOOTSTRAP_SERVERS` 3곳 삭제, `scripts/verify-compose-profile-contracts.sh` 18 lane 일치), `docs/messaging/configuration-reference.md`. env 키 이름은 바뀌지 않음(`.env.example` 변경 없음) | - | 결정(2026-09-25): capability 설정 prefix는 하나(AGENTS.md 기준 4) → producer가 `app.messaging.brokers..bootstrap-servers`를 읽고 `spring.kafka.bootstrap-servers` 의존 제거 | +| M-2c | Critical | broker별 `access.publishable` ACL이 compile만 되고 publish 판정에는 쓰이지 않음 | 완료 | Wave 1–2 P1 (fcddab7e·Wave 2 커밋): `BrokerAccessListTest.aDeclaredDestinationTheSecurityEntryDoesNotListIsRejectedAsForbidden` FAIL("Expecting Optional[PUBLISH_PREPARATION_FAILED] to contain PUBLISH_FORBIDDEN" — 목록 밖 destination이 접근 검사를 통과) → PASS. `messagingDestinationAccess`가 선언 destination 중 해당 broker security 항목의 `access.publishable`에 있는 것만 허용: `src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingCoreAutoConfiguration.java:422`. security 항목이 없는 broker는 기존대로 선언 destination 전부. 빈 목록이면 publish 불가(문서화: `docs/messaging/configuration-reference.md` 보안 절, `docs/messaging/security.md` ACL 절) | - | `messagingDestinationAccess` bean이 선언 destination 집합과 compile된 `BrokerSecurityProfile`의 `publishable`을 교집합으로 쓰게 바꾸고, 허용 목록 밖 publish가 REJECTED인 테스트 추가 | +| M-2d | Critical | SASL JAAS username에 credential 참조 id가 들어감 | 완료 | Wave 1–2 P1 (fcddab7e·Wave 2 커밋): `KafkaProducerSecurityTest.theProducerAuthenticatesAsTheUsernameTheProviderReturnsNotAsTheCredentialId` FAIL(JAAS가 `username="kafka-producer"`=credential id, `password=` 고정, callback handler 없음) → PASS. `CredentialProvider.username(credentialId)` 추가(`src/messaging/messaging-security/src/main/java/dev/caskeleton/messaging/security/CredentialProvider.java:43`), `CredentialRuntime.username()`, SASL 사용자 이름이 없으면 기동 실패 `SASL_USERNAME_MISSING`(`KafkaSecurityConfigurerTest.aSaslCredentialWhoseProviderNamesNoUserIsRefused`). 실제 lane: `MessagingSecuredBrokerQualificationTest.aPublishIsConfirmedByAPrivateCaBrokerThatRequiresSaslAsTheProviderUser` PASS, 확인용으로 provider 사용자 이름을 틀리게 바꾸면 REJECTED(broker가 SASL을 실제로 검사함) | - | `CredentialRuntime`(또는 provider 응답)에 username을 넣고 JAAS는 그 값을 쓰게 바꿈. 테스트 기대값도 provider가 준 username으로 교체 | +| M-2e | Critical | truststore/keystore 설정 키가 없음. `MutualTls`는 `SSL` + `sasl.mechanism=NONE`만 넣고 keystore를 안 넣음 → 사설 CA·mTLS broker 연결 불가 | 완료 | Wave 1–2 P1 (fcddab7e·Wave 2 커밋): NEW-4b와 같은 결함, 한 번 수정. `KafkaProducerSecurityTest.aPrivateCaTrustStoreReachesTheProducer`·`mutualTlsPresentsTheProducerKeyStoreUnlockedByItsCredential`·`mutualTlsOnABrokerWithoutTlsFailsStartup` FAIL("trust-store.location binds nothing") → PASS, `mutualTlsWithoutAKeyStoreFailsStartupNamingTheKey` PASS, `KafkaSecurityConfigurerTest.aTrustStoreOnABrokerWithoutTlsIsRefused` PASS. 설정: `app.messaging.security..trust-store.{location,type,password-credential-id}`, `.key-store.{location,type}`(`BrokerSecuritySettings.java`), 모델 `BrokerTrustStore`(신규), `BrokerCredentialProfile.MutualTls(credentialId, keyStoreLocation, keyStoreType)`(`BrokerCredentialProfile.java:58`), Kafka 설정 `ssl.truststore.*`/`ssl.keystore.*`(`KafkaSecurityConfigurer.java:102,129`). key-store 없는 MUTUAL_TLS·TLS 꺼진 MUTUAL_TLS·TLS 꺼진 trust-store는 기동 실패(평문 fallback 없음, `MessagingConfigurationCompiler.java:276`, `KafkaSecurityConfigurer.java:190`). 실제 lane: 테스트 시점에 keytool로 만든 사설 CA로 서명된 broker 두 개 — SASL_SSL, `ssl.client.auth=required` SSL — 로 publish CONFIRMED(`MessagingSecuredBrokerQualificationTest` 2건). trust-store 생략은 JVM 기본 trust store(공인 CA broker용, 문서화) | - | `BrokerSecuritySettings`에 truststore/keystore(경로·유형·비밀번호 credential id) 추가 후 `ssl.truststore.*`/`ssl.keystore.*` 설정. 지원 전까지 `MutualTls`는 기동 거부 | +| M-2f | Critical | credential rotation이 producer에 반영 안 됨(기동 때 JAAS 문자열 1회 생성) | 완료 | Wave 1–2 P1 (fcddab7e·Wave 2 커밋): NEW-4d와 같은 결함, NEW-4d 방향(`sasl.client.callback.handler.class`) 채택. `KafkaProducerSecurityTest.aRotatedPasswordReachesTheNextAuthenticationWithoutRebuildingTheProducer` FAIL(callback handler 없음, 비밀번호가 JAAS 문자열에 고정) → PASS. JAAS는 login module 이름만(`... required;`), `KafkaCredentialCallbackHandler`가 인증마다 `CredentialRuntimeRegistry`에서 사용자 이름·비밀번호를 읽음(`src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaCredentialCallbackHandler.java:62`, `KafkaSecurityConfigurer.java:156`). producer를 바꾸지 않으므로 transport generation 1 유지 — 주석 정정(`KafkaMessagingAutoConfiguration.java:277`), Javadoc 정정(`KafkaSecurityConfigurer.java:15-30`), `docs/messaging/security.md` Rotation 절. 한계(문서화): registry는 provider가 만료 시각을 줄 때만 다시 가져옴, key/trust store 비밀번호는 client 재생성(재기동) 필요 | - | rotation 시 producer를 새로 만들고 transport generation을 올리는 경로 추가. 당장 안 하면 javadoc을 정정하고 만료 임박 credential은 기동/주기 검사에서 경고 | +| M-3 | Required | handler timeout 때 `cancel(true)`가 실행 중 handler를 멈추지 않는데 permit을 바로 반환 → 같은 offset 중복 처리 (H6 회귀) | 완료 | Wave 1–2 P1 (fcddab7e·Wave 2 커밋): `KafkaConsumerRegistrarTest.aTimedOutHandlerStillRunningIsNotDispatchedASecondTime` FAIL("Expected size: 1 but was: 2" — 첫 handler가 도는 중 같은 offset 재dispatch) → PASS, `aTimedOutHandlerIsRedeliveredOnceItFinishesWithoutSettling` PASS. timeout이면 `cancel` 없이 `handler.whenComplete`에서 requeue와 permit·work count 반환(`src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrar.java:374-395`). 방향보다 한 단계 더: requeue도 완료 시점으로 미룸(maxInFlight>1에서도 같은 offset 동시 실행 없음). 결함을 고정하던 기존 테스트 `handlerTimeoutCancelsTheOutstandingHandlerBeforeThePartitionPermitIsReleased`(cancel 여부 단언) 삭제 | - | timeout이면 항상 `handler.whenComplete(...)`에서 permit·work count를 반환. 테스트는 "첫 handler가 끝나기 전 같은 offset 재dispatch 없음"을 단언 | +| M-4a | Required | admission 거부(`MessageTooLarge`/`Backpressure`)가 `try` 밖에서 동기 예외로 던져짐 | 완료 | Wave 1–2 P1 (fcddab7e·Wave 2 커밋): `DefaultMessagePublisherTest.anOversizedPayloadIsRejectedAsNotRetryableInsteadOfThrown` FAIL(`MessageTooLargeException` 동기 throw) → PASS, `aSaturatedPermitPoolRejectsAsRetryableWithinTheCallersDeadline` FAIL(5초 안에 끝나지 않음) → PASS. admission을 try 안으로, 크기 초과 REJECTED retryable=false, backpressure REJECTED retryable=true(`src/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisher.java:226-236,333`) | - | `admission.admit`을 `try` 안으로 옮겨 크기 초과는 REJECTED(retryable=false), backpressure는 REJECTED(retryable=true)로 반환 | +| M-4b | Required | relay에 row별 catch가 없고 CLAIM이 `attempts`를 올리지 않음 → poison row가 매 lease 재claim, 같은 batch 나머지도 lease 만료까지 묶임 | 완료 | Wave 1–2 P1 (fcddab7e·Wave 2 커밋): `OutboxRelayTest.aRowThatCannotBecomeAnEnvelopeFailsWhileTheRestOfItsBatchPublishes` FAIL(예약 header row의 예외가 `runOnce` 밖으로) → PASS(`[FAILED, PUBLISHED]`), `aPublisherThatThrowsLeavesTheRowAmbiguousRatherThanStrandingTheBatch` FAIL → PASS. envelope 변환 실패는 `markFailed`, publisher 예외는 결과 불명이라 AMBIGUOUS(같은 id로 재시도, attempt 예산 적용)(`src/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/OutboxRelay.java:176-190,254`). CLAIM 시 attempts 증가는 하지 않음: row 단위 처리로 poison row 무한 재claim이 사라짐. relay 프로세스가 row 처리 중 죽는 경우는 lease 만료 재claim으로 남음 | - | `runOnce` 루프에 row별 try/catch → `markFailed(lease, code)`. 테스트: 예약 header row는 FAILED, 같은 batch 나머지 row는 PUBLISHED | +| M-4c | Required | 실패한 relay pass를 로그 없이 삼키고 `failedPasses()`를 읽는 곳이 없음 | 완료 | Wave 1–2 P1 (fcddab7e·Wave 2 커밋): `MessagingOutboxRelayLifecycleTest.aRelayPassThatFailsIsCountedOnTheMeterRegistry` FAIL(`MeterNotFoundException 'messaging.outbox.relay.failed.passes'`) → PASS. `FunctionCounter messaging.outbox.relay.failed.passes`(`src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingReliabilityAutoConfiguration.java:124`), 원인 포함 WARNING 로그(`System.Logger`, `OutboxRelayWorker.java:193`). 로그 자체는 자동 테스트 없음. `OutboxRelayWorkerTest.aFailedPassDoesNotEndTheLoop`는 pass 실패를 DB 장애(repository 예외)로 재현하도록 변경(publisher 예외는 이제 row에서 처리됨) | - | catch에서 원인 포함 WARN 로그, `failedPasses`를 meter로 노출 | +| M-5a | Required | publish가 deadline 적용 전 caller thread를 최대 약 65초 막음(InFlightLimiter 5초 + `max.block.ms` 기본 60초) | 완료 | Wave 1–2 P1 (fcddab7e·Wave 2 커밋): `KafkaProducerConfigTest.theProducerStopsWaitingForMetadataWithinTheDefaultPublishDeadline` FAIL → PASS(`max.block.ms` = `PublishOptions.defaults().timeout()` 5s, `KafkaMessagingAutoConfiguration.java:186`), permit 대기를 남은 budget으로 제한(`InFlightLimiter.java:63`, `MessagingAdmissionController.java:91`, `DefaultMessagePublisher.java:232`), 테스트 `DefaultMessagePublisherTest.aSaturatedPermitPoolRejectsAsRetryableWithinTheCallersDeadline` | - | `producerConfig`에 `max.block.ms`를 기본 publish timeout 이하로 설정, limiter 대기도 남은 budget 안으로 제한 | +| M-5b | Required | reactive facade가 blocking publish를 subscriber thread에서 실행 | 완료 | Wave 1–2 P1 (fcddab7e·Wave 2 커밋): `ReactiveFacadeTest.theBlockingPublishRunsOffTheSubscribingThread` FAIL("Expected not same: Thread[#1,Test worker]") → PASS. `.subscribeOn(Schedulers.boundedElastic())`(`src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/DefaultReactiveMessagePublisher.java:41`) | - | `Mono.fromCompletionStage(...)` 뒤에 `.subscribeOn(Schedulers.boundedElastic())` | +| M-6 | Required | outbox/inbox cleanup job이 제한 없는 단일 DELETE (MSG-006 §6 불완전) | 완료 | Wave 1–2 P1 (fcddab7e·Wave 2 커밋): `OutboxOperationsTest`·`InboxOperationsTest.cleanupAsksForBoundedBatchesAndStopsAtTheFirstShortOne` FAIL("Expecting [] to contain exactly [1000, ...]") → PASS. 두 job이 `(cutoff, 1000)`을 짧은 batch가 나올 때까지 반복(`OutboxCleanupJob.java:53`, `InboxCleanupJob.java:56`), port의 1-인자 purge와 JDBC 구현 삭제(`OutboxRepository`, `InboxRepository`, `JdbcOutboxRepository`, `JdbcInboxRepository`). PG lane `OutboxPostgresIT.retentionRemovesOnlyPublishedRows`·`InboxPostgresIT.retentionRemovesOldRows` bounded 호출로 PASS | - | 두 job이 `(cutoff, batchSize)` 버전을 삭제 수 < batch가 될 때까지 반복 호출. port의 1-인자 메서드(`src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/OutboxRepository.java:103`, `InboxRepository.java:45`) 삭제 | +| M-7 | Required | consumer poison message가 지연 없이 무한 재시도(partition 영구 정지) | 완료 | Wave 1–2 P1 (fcddab7e·Wave 2 커밋): `KafkaConsumerRegistrarTest.aFailedHandlerWaitsOutItsBackoffBeforeThePartitionIsReadAgain` FAIL(즉시 resume) → PASS, `aHandlerThatSpendsItsAttemptBudgetIsQuarantinedAndCommittedPast` FAIL("Expecting Optional to contain 11L but was empty") → PASS, `aProductionDestinationWithoutAQuarantineIsRefused` FAIL(거부 없음) → PASS. offset별 실패 횟수, `BackoffCalculator` 지연(최소 1초), `retry.maxAttempts` 도달 시 quarantine 후 commit, quarantine 없으면 backoff로 계속 재시도, production destination에 quarantine이 없으면 생성자에서 `KAFKA_QUARANTINE_REQUIRED`(`KafkaConsumerRegistrar.java:185,695`), `KafkaQuarantinePublisher.unavailable()`을 단일 인스턴스로. 재시도 시각은 주입 가능한 `InstantSource`. 참고: consumer는 아직 starter가 조립하지 않음(결정 10, Wave 3) | - | requeue에 `BackoffCalculator` 지연, 시도 한도 초과 시 DLQ/park. production에서 quarantine이 `unavailable()`이면 기동 거부 | | M-8a | Consider | 옛 prefix `backend.messaging` 테스트 fixture yml 2개가 남아 있음(어떤 테스트도 로드 안 함) | 남음 | `src/messaging/messaging-spring-boot-starter/src/test/resources/application-valid.yml:2-3`, `src/messaging/messaging-spring-boot-starter/src/test/resources/application-invalid-ordering.yml:7-8`. `git grep "application-valid\|invalid-ordering" -- src/messaging` 0건 | W5 | 두 파일 삭제 | | M-8b | Consider | kafka-share·stream-bridge 오류 메시지가 거부되는 옛 prefix를 안내, `app.messaging.experimental.*`는 바인딩만 | 해당 없음(코드 삭제) | 「제거된 코드」 표의 `messaging-kafka-share-experimental` leaf, `messaging-spring-cloud-stream-bridge` leaf, `MessagingSettings.Experimental`·`Bridge` 행 | - | - | | M-9 | Consider | 구현·사용처 없는 messaging API 타입 7개 (known-open L7/L8) | 남음 | `src/messaging/messaging-core-api/src/main/java/dev/caskeleton/messaging/api/delivery/BatchMessageHandler.java`, `.../api/destination/CapabilityRegistry.java`, `.../api/publish/DelayedMessagePublisher.java`, `.../api/settlement/ManualMessageHandler.java`, `.../api/delivery/PauseResumeController.java`, `.../api/delivery/ProcessingGuarantee.java`, `src/messaging/messaging-transport-spi/src/main/java/dev/caskeleton/messaging/transport/MessagingLifecycle.java` (main 참조 0, `git grep`로 확인) | W3 | 7개 파일 삭제 | | M-10 | Consider | Rabbit publish sequence 예약이 원자적이지 않음 | 해당 없음(코드 삭제) | 「제거된 코드」 표의 `messaging-rabbit` leaf 행 | - | - | -| M-11 | Consider | outbox CLAIM이 `ordering_key`를 무시해 같은 key의 뒤 row가 먼저 나갈 수 있음 | 남음 | `src/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/JdbcOutboxRepository.java:113-128` (`ORDER BY created_at` + `SKIP LOCKED`) | W2 | ordered destination을 outbox로 내보내는 조합을 기동 때 거부(최소 수정). 순서 보장이 필요하면 같은 key의 더 오래된 미완료 row가 있을 때 claim에서 제외 | +| M-11 | Consider | outbox CLAIM이 `ordering_key`를 무시해 같은 key의 뒤 row가 먼저 나갈 수 있음 | 완료 | Wave 1–2 P1 (fcddab7e·Wave 2 커밋): `OutboxPostgresIT.aNewerRowWaitsWhileAnOlderRowWithTheSameOrderingKeyIsUnfinished`(실제 PostgreSQL) — 새 조건을 끈 SQL로 FAIL(같은 key의 뒤 row까지 3건 claim) → PASS. 최소 수정(기동 거부) 대신 claim 제외를 택함: relay는 기동 때 어떤 destination이 outbox로 나가는지 알 수 없다. CLAIM에 "같은 destination·ordering_key의 더 오래된 PENDING/AMBIGUOUS/IN_FLIGHT row가 없을 것" 조건과 `(created_at, message_id)` 순서(`src/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/JdbcOutboxRepository.java:113-140`), 새 migration `V1005__messaging_outbox_ordering_key_index.sql`(messaging 예약 대역, `md5(ordering_key)` partial index). `twoRelaysClaimingConcurrently...` fixture는 서로 다른 key로 변경. `leaseBatch`(main 호출자 없음)에는 적용 안 함 | - | ordered destination을 outbox로 내보내는 조합을 기동 때 거부(최소 수정). 순서 보장이 필요하면 같은 key의 더 오래된 미완료 row가 있을 때 claim에서 제외 | | N-1 | Critical | FAILED_TERMINAL 뒤 재시도가 claim 없이 PROCEED (= Critical #15) | 완료 | `src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/idempotency/GrpcIdempotencyInterceptor.java:109-117` (`reclaimFailed` 성공 시에만 PROCEED), `src/grpc/grpc-core-api/src/main/java/dev/caskeleton/grpc/api/ledger/GrpcOperationLedger.java:53`, `src/grpc/grpc-operation-ledger-jpa/src/main/java/dev/caskeleton/grpc/ledger/JpaGrpcOperationLedger.java:92-96`. 공통 계약 `src/grpc/grpc-core-api/src/testFixtures/java/dev/caskeleton/grpc/api/ledger/GrpcOperationLedgerContract.java` (`aFailedClaimIsReclaimedByARetryOfTheSameRequest`, `aFailedClaimCannotBeCommittedWithoutBeingReclaimed`)을 fake(`InMemoryOperationLedgerContractTest`)와 JPA(`JpaGrpcOperationLedgerContractIT`)가 상속. 커밋 `6d27356e` | - | - | -| N-2 | Required | `GrpcDeadlineBudget`이 생성 시점 Duration만 들고 있어 시간이 지나도 만료되지 않음 | 남음 | `src/grpc/grpc-core-api/src/main/java/dev/caskeleton/grpc/api/deadline/GrpcDeadlineBudget.java:13,82-83` | W2 | 절대 시각(`long deadlineNanos` + 주입 `LongSupplier`)을 저장하고 `remaining(now)`/`expired(now)`로 변경, 시간 경과 테스트 추가 | -| N-3 | Required | starter `environment` 기본값 LOCAL → 설정 누락 시 TLS·reflection 검사 전부 꺼짐 | 남음 | `src/grpc/grpc-spring-boot-starter/src/main/java/dev/caskeleton/grpc/boot/GrpcPlatformProperties.java:26`, `src/grpc/grpc-spring-boot-starter/src/main/java/dev/caskeleton/grpc/boot/GrpcPlatformStartupValidator.java:87` | W1 | 기본값 제거, `enabled=true`인데 environment가 없으면 startup violation. 누락 케이스 테스트 추가 | -| N-4 | Required | resolver service config의 retry/hedging을 검증하지 않고, 정상 `retryThrottling.maxTokens`는 `token` 부분일치로 거부 | 남음 | `src/grpc-advanced/grpc-advanced-resilience/src/main/java/dev/caskeleton/grpc/advanced/discovery/GrpcResolverSafetyPolicy.java:56-65,86-91` | W1 | JSON 파싱 + top-level 키 allowlist, `retryPolicy`/`hedgingPolicy`는 `GrpcMethodPolicyCatalog`로 검증하거나 거부, credential 정규식 삭제 | -| N-5a | Required | `GrpcAdmissionController.tryAdmit` check-then-act → 동시 호출 수만큼 bound 초과 | 남음 | `src/grpc/grpc-server/src/main/java/dev/caskeleton/grpc/server/GrpcAdmissionController.java:52-55` | W2 | `synchronized` 또는 `updateAndGet` CAS로 확인과 증가를 하나로, 동시성 테스트 추가 | -| N-5b | Required | `GrpcCredentialRotationManager` get/set 경합 → `completeDrain`이 새 generation을 되돌리거나 역방향 rotation 통과 | 남음 | `src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/security/GrpcCredentialRotationManager.java:89-103,119-120` | W2 | `state.updateAndGet`/`compareAndSet` 루프로 교체, 동시 rotate·completeDrain 테스트 | -| N-5c | Required | `GrpcChannelRuntimeRegistry.rotate` get/set 경합으로 replacement가 drain 목록에서 빠져 누수, synchronizedList를 락 없이 순회 | 남음 | `src/grpc/grpc-client/src/main/java/dev/caskeleton/grpc/client/GrpcChannelRuntimeRegistry.java:91-107,127-129` | W2 | `holder.compareAndSet` 또는 profile 단위 `synchronized`, `retireQuiescent`·`draining`은 리스트 락 안에서 순회 | -| N-5d | Required | `GrpcServiceHealthRegistry`에서 `draining` 확인과 `put(SERVING)` 사이에 drain 시작 → drain 후 SERVING 복귀 | 남음 | `src/grpc/grpc-admin/src/main/java/dev/caskeleton/grpc/admin/GrpcServiceHealthRegistry.java:50-53` vs `:85` | W2 | `markServing`/`markNotServing`/`beginDraining`을 같은 락으로 묶기 | -| N-5e | Required | `GrpcStreamAdmission`이 global bound 검사 전에 `computeIfAbsent` → 포화 시 거부된 caller마다 count 0 엔트리 영구 잔류 (M1(b) 미완) | 남음 | `src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/streaming/GrpcStreamAdmission.java:43-47` | W2 | global 검사를 `computeIfAbsent` 앞으로 옮김 | -| N-6a | Required | `GrpcSerializedStreamWriter`의 `LongSupplier` sizer가 실제 payload 크기를 모름 (H3 잔여) | 남음 | `src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/streaming/GrpcSerializedStreamWriter.java:30,48` | W2 | `ToLongFunction`로 바꿔 메시지마다 크기 계산 | -| N-6b | Required | writer가 `PAUSE`를 `ACCEPTED`로 반환해 백프레셔 신호 소실 | 남음 | `src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/streaming/GrpcSerializedStreamWriter.java:100-102` | W2 | `ACCEPTED_PAUSE` 결과를 추가해 PAUSE를 호출자에게 전달 | -| N-6c | Required | `flush()`가 `isReady`와 무관하게 큐 전체 전송 | 남음 | `src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/streaming/GrpcSerializedStreamWriter.java:126-138` | W2 | `flush(BooleanSupplier ready)`로 바꿔 ready가 false면 중단 | -| N-7 | Consider | `GrpcContextBinder.wrap`이 io.grpc `Context`(취소·deadline)를 스레드 경계에서 버림 | 남음 | `src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/context/GrpcContextBinder.java:86-98` (SNAPSHOT 값만 캡처) | W2 | `Context.current()`를 캡처해 `captured.wrap(...)` 안에서 `runWith` 실행 | -| N-8a | Consider | envoy 참조 설정의 `DownstreamTlsContext`에 인증서가 없음 | 남음 | `src/grpc-advanced/grpc-advanced-compat/src/main/resources/envoy/envoy.yaml:50-53` | W2 | 인증서 경로 placeholder를 넣고 `envoy --mode validate` 통과 확인 | -| N-8b | Consider | CORS header 목록이 실제 gRPC trailer와 다름(`expose_headers`에 `error-code,error-category`, 실제는 `error-reason`·`error-execution-id`·`completion-outcome`, `grpc-status-details-bin` 없음. `allow_headers`에 `x-user-agent`·`grpc-timeout` 없음) | 남음 | `src/grpc-advanced/grpc-advanced-compat/src/main/resources/envoy/envoy.yaml:37-38` vs `src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/error/GrpcErrorMapper.java:31-39` | W2 | header 목록을 정정하고 `GrpcErrorMapper` 상수와 envoy.yaml을 대조하는 테스트 추가 | -| N-8c | Consider | route `timeout: 30s`가 server stream을 30초에 끊음 | 남음 | `src/grpc-advanced/grpc-advanced-compat/src/main/resources/envoy/envoy.yaml:32` | W2 | stream route는 `timeout: 0s` + `grpc_timeout_header_max: 0s` | +| N-2 | Required | `GrpcDeadlineBudget`이 생성 시점 Duration만 들고 있어 시간이 지나도 만료되지 않음 | 완료 | Wave 1–2 P5 (fcddab7e·Wave 2 커밋): `GrpcDeadlineBudgetTest.aBudgetRunsOutAsTimePassesAfterItWasCreated` FAIL(`Expecting value to be true but was false`, sleep 판)→PASS(주입 시계 판), `aDownstreamDerivedLaterGetsOnlyWhatIsLeftThen` 추가. 단조 시계의 절대 deadline + 주입 `LongSupplier` `src/grpc/grpc-core-api/src/main/java/dev/caskeleton/grpc/api/deadline/GrpcDeadlineBudget.java:44,93`. 방향과 다른 점: `remaining(now)` 대신 시계를 주입해 호출부 시그니처를 유지. budget이 살아 있게 되면서 두 번 읽기 경합이 생기는 곳을 한 번 읽기로 고침 `src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/resilience/GrpcRetryCoordinator.java:82`, `.../GrpcWaitForReadyValidator.java:39`. 커밋 `a498ad84` | - | 절대 시각(`long deadlineNanos` + 주입 `LongSupplier`)을 저장하고 `remaining(now)`/`expired(now)`로 변경, 시간 경과 테스트 추가 | +| N-3 | Required | starter `environment` 기본값 LOCAL → 설정 누락 시 TLS·reflection 검사 전부 꺼짐 | 완료 | Wave 1–2 P5 (fcddab7e·Wave 2 커밋): `GrpcPlatformAutoConfigurationContextTest.enabledPlatformWithoutAnEnvironmentRefusesToStartInsteadOfAssumingLocal` FAIL(`Expecting actual not to be null` — LOCAL 가정으로 기동 성공)→PASS. 기본값 제거 `src/grpc/grpc-spring-boot-starter/src/main/java/dev/caskeleton/grpc/boot/GrpcPlatformProperties.java:30`, 미설정 violation `.../GrpcPlatformStartupValidator.java:80`. 검증 전 생성되는 reflection 정책 bean은 environment가 없으면 PROD 바닥(비활성)으로 만든다 `.../GrpcPlatformAutoConfiguration.java`(reflection bean). 커밋 `b39d3de0` | - | 기본값 제거, `enabled=true`인데 environment가 없으면 startup violation. 누락 케이스 테스트 추가 | +| N-4 | Required | resolver service config의 retry/hedging을 검증하지 않고, 정상 `retryThrottling.maxTokens`는 `token` 부분일치로 거부 | 완료 | Wave 1–2 P5 (fcddab7e·Wave 2 커밋): `GrpcResolverSafetyPolicyTest.aServiceConfigWithRetryThrottlingIsAccepted` FAIL(`credential-shaped field` 위반)→PASS, `aServiceConfigThatTurnsOnRetriesIsRefused` FAIL(`Expected size: 1 but was: 0`)→PASS. 수정 방향과 다른 점: 이 leaf 클래스패스에 JSON 파서가 없고 새로 들이지 않기로 한 leaf라서, service config를 gRPC가 쓰는 파싱된 `Map`로 받게 바꿨다(`NameResolver.Helper.parseServiceConfig`와 같은 형태) `src/grpc-advanced/grpc-advanced-resilience/src/main/java/dev/caskeleton/grpc/advanced/discovery/GrpcResolverUpdate.java:17`. top-level 필드 allowlist `.../GrpcResolverSafetyPolicy.java:25,68`, `methodConfig`의 `retryPolicy`·`hedgingPolicy`는 거부(resolver는 catalog를 모르므로 검증 대신 거부) `:89`, `token` 부분일치 정규식 삭제. 커밋 `b39d3de0` | - | JSON 파싱 + top-level 키 allowlist, `retryPolicy`/`hedgingPolicy`는 `GrpcMethodPolicyCatalog`로 검증하거나 거부, credential 정규식 삭제 | +| N-5a | Required | `GrpcAdmissionController.tryAdmit` check-then-act → 동시 호출 수만큼 bound 초과 | 완료 | Wave 1–2 P5 (fcddab7e·Wave 2 커밋): `GrpcAdmissionControllerTest.racingCallersNeverGetPastTheConcurrencyAndQueueBounds` FAIL(`expected: 2 but was: 4`)→PASS. 두 카운터를 한 락으로(`tryAdmit`·`promoteFromQueue`·`release` 모두 check-then-act였음) `src/grpc/grpc-server/src/main/java/dev/caskeleton/grpc/server/GrpcAdmissionController.java:52`. 커밋 `a498ad84` | - | `synchronized` 또는 `updateAndGet` CAS로 확인과 증가를 하나로, 동시성 테스트 추가 | +| N-5b | Required | `GrpcCredentialRotationManager` get/set 경합 → `completeDrain`이 새 generation을 되돌리거나 역방향 rotation 통과 | 완료 | Wave 1–2 P5 (fcddab7e·Wave 2 커밋): `GrpcCredentialRotationManagerTest.racingRotationsNeverLeaveAnOlderGenerationCurrent` FAIL(`expected: 4L but was: 3L`)→PASS, `aDrainCompletedDuringARotationNeverRevertsTheNewGeneration` FAIL(`expected: 3L but was: 2L`)→PASS. CAS 루프 `src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/security/GrpcCredentialRotationManager.java:108`, `completeDrain`은 `updateAndGet` `:126`. 커밋 `a498ad84` | - | `state.updateAndGet`/`compareAndSet` 루프로 교체, 동시 rotate·completeDrain 테스트 | +| N-5c | Required | `GrpcChannelRuntimeRegistry.rotate` get/set 경합으로 replacement가 drain 목록에서 빠져 누수, synchronizedList를 락 없이 순회 | 완료 | Wave 1–2 P5 (fcddab7e·Wave 2 커밋): `GrpcChannelRuntimeRegistryTest.racingRotationsDrainEveryReplacedRuntimeAndKeepTheNewestCurrent` FAIL(`"2 draining [1, 1]"`, `"3 draining [1, 1]"` 발생)→PASS. install/rotate/draining/retireQuiescent를 registry 락 하나로, drain 목록은 락 안의 `HashMap`/`ArrayList` `src/grpc/grpc-client/src/main/java/dev/caskeleton/grpc/client/GrpcChannelRuntimeRegistry.java:86`. 커밋 `a498ad84` | - | `holder.compareAndSet` 또는 profile 단위 `synchronized`, `retireQuiescent`·`draining`은 리스트 락 안에서 순회 | +| N-5d | Required | `GrpcServiceHealthRegistry`에서 `draining` 확인과 `put(SERVING)` 사이에 drain 시작 → drain 후 SERVING 복귀 | 완료 | Wave 1–2 P5 (fcddab7e·Wave 2 커밋): `GrpcServiceHealthRegistryTest.aServiceMarkedServingWhileDrainBeginsNeverReturnsTheInstanceToServing` FAIL(`[DRAINING/DRAINING, DRAINING/UNKNOWN, SERVING/SERVING]`)→PASS. 쓰기 메서드 전부 같은 락 `src/grpc/grpc-admin/src/main/java/dev/caskeleton/grpc/admin/GrpcServiceHealthRegistry.java:50,86`. 커밋 `a498ad84` | - | `markServing`/`markNotServing`/`beginDraining`을 같은 락으로 묶기 | +| N-5e | Required | `GrpcStreamAdmission`이 global bound 검사 전에 `computeIfAbsent` → 포화 시 거부된 caller마다 count 0 엔트리 영구 잔류 (M1(b) 미완) | 완료 | Wave 1–2 P5 (fcddab7e·Wave 2 커밋): `GrpcStreamAdmissionConcurrencyTest.aCallerRefusedByTheGlobalBoundLeavesNoTrackedEntry` FAIL(`expected: 1 but was: 2`)→PASS. global 검사를 `computeIfAbsent` 앞으로 `src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/streaming/GrpcStreamAdmission.java:42`. 커밋 `a498ad84` | - | global 검사를 `computeIfAbsent` 앞으로 옮김 | +| N-6a | Required | `GrpcSerializedStreamWriter`의 `LongSupplier` sizer가 실제 payload 크기를 모름 (H3 잔여) | 완료 | Wave 1–2 P5 (fcddab7e·Wave 2 커밋): `GrpcSerializedStreamWriterTest.theByteBoundCountsEachPayloadsOwnSize` RED(테스트 컴파일 실패 — `LongSupplier`는 payload를 받지 못함)→PASS. `ToLongFunction` `src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/streaming/GrpcSerializedStreamWriter.java:74`. 커밋 `a498ad84` | - | `ToLongFunction`로 바꿔 메시지마다 크기 계산 | +| N-6b | Required | writer가 `PAUSE`를 `ACCEPTED`로 반환해 백프레셔 신호 소실 | 완료 | Wave 1–2 P5 (fcddab7e·Wave 2 커밋): `GrpcSerializedStreamWriterTest.aWriteWhileTheTransportIsNotReadyTellsTheProducerToPause` RED(컴파일 실패 — 결과 값 없음)→PASS. `GrpcStreamWriteResult.ACCEPTED_PAUSE`(queued=true) `.../GrpcSerializedStreamWriter.java:103`. 커밋 `a498ad84` | - | `ACCEPTED_PAUSE` 결과를 추가해 PAUSE를 호출자에게 전달 | +| N-6c | Required | `flush()`가 `isReady`와 무관하게 큐 전체 전송 | 완료 | Wave 1–2 P5 (fcddab7e·Wave 2 커밋): `GrpcSerializedStreamWriterTest.flushStopsWhenTheTransportStopsBeingReady` RED(컴파일 실패 — readiness 인자 없음)→PASS. `flush(BooleanSupplier)`가 메시지마다 ready 확인, 남은 바이트 정확히 차감 `.../GrpcSerializedStreamWriter.java:133`. 커밋 `a498ad84` | - | `flush(BooleanSupplier ready)`로 바꿔 ready가 false면 중단 | +| N-7 | Consider | `GrpcContextBinder.wrap`이 io.grpc `Context`(취소·deadline)를 스레드 경계에서 버림 | 완료 | Wave 1–2 P5 (fcddab7e·Wave 2 커밋): `GrpcContextBinderTest.wrappedWorkSeesTheSubmittingCallsCancellationOnAnotherThread` FAIL(`Expecting AtomicBoolean(false) to have value: true`)→PASS. `Context.current()` 전체를 캡처해 `captured.wrap(work)` `src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/context/GrpcContextBinder.java:97`. 커밋 `a498ad84` | - | `Context.current()`를 캡처해 `captured.wrap(...)` 안에서 `runWith` 실행 | +| N-8a | Consider | envoy 참조 설정의 `DownstreamTlsContext`에 인증서가 없음 | 완료 | Wave 1–2 P5 (fcddab7e·Wave 2 커밋): 실제 Envoy v1.31 `--mode validate`: 수정 전 `No TLS certificates found for server context`, 수정 후 `configuration ... OK`(임시 자체서명 인증서를 placeholder 경로에 마운트). `GrpcWebCompatibilityTest.theReferenceProxyTerminatesTlsWithACertificate` FAIL→PASS. `src/grpc-advanced/grpc-advanced-compat/src/main/resources/envoy/envoy.yaml:62`. 커밋 `a498ad84` | - | 인증서 경로 placeholder를 넣고 `envoy --mode validate` 통과 확인 | +| N-8b | Consider | CORS header 목록이 실제 gRPC trailer와 다름(`expose_headers`에 `error-code,error-category`, 실제는 `error-reason`·`error-execution-id`·`completion-outcome`, `grpc-status-details-bin` 없음. `allow_headers`에 `x-user-agent`·`grpc-timeout` 없음) | 완료 | Wave 1–2 P5 (fcddab7e·Wave 2 커밋): `GrpcWebCompatibilityTest.theReferenceProxyExposesEveryTrailerThePlatformSends`(`GrpcErrorMapper`·`GrpcValidationInterceptor` 상수와 대조) FAIL(`error-code,error-category`만 있음)→PASS, `theReferenceProxyLetsTheBrowserSendItsDeadlineAndClientHeaders` FAIL→PASS. `envoy.yaml:41,43` | - | header 목록을 정정하고 `GrpcErrorMapper` 상수와 envoy.yaml을 대조하는 테스트 추가 | +| N-8c | Consider | route `timeout: 30s`가 server stream을 30초에 끊음 | 완료 | Wave 1–2 P5 (fcddab7e·Wave 2 커밋): `GrpcWebCompatibilityTest.theReferenceRouteLeavesStreamLengthToTheCallersDeadline` FAIL→PASS. route `timeout: 0s` + `max_stream_duration.grpc_timeout_header_max: 0s` `envoy.yaml:34,36`(Envoy validate 통과) | - | stream route는 `timeout: 0s` + `grpc_timeout_header_max: 0s` | | N-8d | Consider | 참조 설정이 main resources라 jar에 포함, 테스트는 부분 문자열만 확인 | 남음 | `src/grpc-advanced/grpc-advanced-compat/src/main/resources/envoy/envoy.yaml` | W3 | test resources 또는 docs로 이동 | | N-9a | Consider | starter의 `grpc-proto-contract`·`grpc-codegen` 의존이 main에서 안 쓰임 | 남음 | `src/grpc/grpc-spring-boot-starter/build.gradle:21-22` (starter main의 `grpc.contract`·`grpc.codegen` import 0) | W3 | 두 줄과 registry edge 삭제 | -| N-9b | Consider | `requireValid(..., Set.of())`로 advanced 격리 검사가 항상 통과 | 남음 | `src/grpc/grpc-spring-boot-starter/src/main/java/dev/caskeleton/grpc/boot/GrpcPlatformAutoConfiguration.java:129-133`, `src/grpc/grpc-spring-boot-starter/src/main/java/dev/caskeleton/grpc/boot/GrpcPlatformStartupValidator.java:58,175` | W3 | 파라미터와 `validateAdvancedIsolation` 삭제(격리는 Gradle 방향 게이트가 담당) | -| N-9c | Consider | 문서가 `GrpcStableBuildInvariant`가 runtime에 강제한다고 적지만 호출하는 `requireStableStarterIsClean`의 main 호출자 0 | 남음 | `src/grpc/CLAUDE.md:70`, `src/grpc-advanced/CLAUDE.md:19`, `src/grpc-advanced/grpc-advanced-bootstrap/src/main/java/dev/caskeleton/grpc/advanced/bootstrap/GrpcAdvancedModuleGuard.java:75` (테스트에서만 호출) | W5 | 두 CLAUDE.md에서 "runtime에 강제" 문구 삭제(또는 guard와 함께 삭제) | +| N-9b | Consider | `requireValid(..., Set.of())`로 advanced 격리 검사가 항상 통과 | 해당 없음(코드 삭제) | Wave 1–2 P5 (fcddab7e·Wave 2 커밋): P5 목록 밖이지만 D 삭제로 함께 닫힘: `validateAdvancedIsolation`과 `stableModuleDependencies` 파라미터 삭제(`GrpcStableBuildInvariant` 삭제에 따른 것). 커밋 `9b296c7c` | - | 파라미터와 `validateAdvancedIsolation` 삭제(격리는 Gradle 방향 게이트가 담당) | +| N-9c | Consider | 문서가 `GrpcStableBuildInvariant`가 runtime에 강제한다고 적지만 호출하는 `requireStableStarterIsClean`의 main 호출자 0 | 완료 | Wave 1–2 P5 (fcddab7e·Wave 2 커밋): P5 목록 밖이지만 D에서 함께 닫힘: runtime 강제를 적던 문장을 build-time만으로 정정 `src/grpc/CLAUDE.md`(Stable 범위 절), `src/grpc-advanced/CLAUDE.md:18-19`. 커밋 `9b296c7c` | - | 두 CLAUDE.md에서 "runtime에 강제" 문구 삭제(또는 guard와 함께 삭제) | | N-10a | Consider | 같은 한계값(1 MiB/8192)이 여러 곳에 따로 정의되고 정합 검사 없음(server profile bean의 리터럴 복사 포함) | 남음 | `src/grpc/grpc-server/src/main/java/dev/caskeleton/grpc/server/GrpcServerProfile.java:70-71`, `src/grpc/grpc-spring-boot-starter/src/main/java/dev/caskeleton/grpc/boot/GrpcPlatformAutoConfiguration.java:59-60`, `src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/policy/GrpcMessageSizeProfile.java:43`, `src/grpc/grpc-client/src/main/java/dev/caskeleton/grpc/client/GrpcNamedChannelProfile.java:80-81,95-96`, `src/grpc/grpc-core-api/src/main/java/dev/caskeleton/grpc/api/context/GrpcMetadataBudget.java:33` | W3 | 상수를 `GrpcTransportLimits` 한 곳으로, starter bean은 `GrpcServerProfile` 팩토리 재사용, validator에 "method profile ≤ server profile" | | N-10b | Consider | `GrpcStreamProfile`은 테스트에서만 쓰이고 `GrpcFlowControlPolicy`의 256/8MiB를 복제 | 남음 | `src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/streaming/GrpcStreamProfile.java:40,45` (참조는 `GrpcStreamEnvelopeTest`뿐), `src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/streaming/GrpcFlowControlPolicy.java:43` | W3 | `GrpcStreamProfile`과 그 테스트 참조 삭제 | -| N-11a | Consider | ledger claim에서 insert 0행 + 조회 실패를 소유 획득으로 처리 | 남음 | `src/grpc/grpc-operation-ledger-jpa/src/main/java/dev/caskeleton/grpc/ledger/JpaGrpcOperationLedger.java:46-53` (`findById` 빈 결과 → `Optional.empty()` = 소유) | W2 | 0행인데 조회도 비면 `IllegalStateException` | -| N-11b | Consider | `callerFingerprint` 길이 제한이 없어 storageKey가 `VARCHAR(512)`를 넘을 수 있음 | 남음 | `src/grpc/grpc-core-api/src/main/java/dev/caskeleton/grpc/api/ledger/GrpcOperationIdentity.java:21,36-37`, `src/grpc/grpc-operation-ledger-jpa/src/main/resources/db/migration/grpc/V001__create_grpc_operation_ledger.sql:12` | W2 | fingerprint ≤256자 검증 또는 storage key를 해시로 고정 길이화 | +| N-11a | Consider | ledger claim에서 insert 0행 + 조회 실패를 소유 획득으로 처리 | 완료 | Wave 1–2 P5 (fcddab7e·Wave 2 커밋): `GrpcOperationLedgerRepositoryTest.aConflictWhoseRowVanishedBeforeTheReadIsNotTakenAsOwnership` FAIL(`Expecting actual not to be null`)→PASS. 0행 + 조회 실패면 `IllegalStateException` `src/grpc/grpc-operation-ledger-jpa/src/main/java/dev/caskeleton/grpc/ledger/JpaGrpcOperationLedger.java:58`. PG lane(`integrationCheck`) 18건 통과. 커밋 `a498ad84` | - | 0행인데 조회도 비면 `IllegalStateException` | +| N-11b | Consider | `callerFingerprint` 길이 제한이 없어 storageKey가 `VARCHAR(512)`를 넘을 수 있음 | 완료 | Wave 1–2 P5 (fcddab7e·Wave 2 커밋): 리뷰의 "`sha256:` 형식 검증 안 거침"은 틀림(`GrpcOperationIdentity.java:29`가 검사) — 길이만 고침. `GrpcOperationIdentityTest.aCallerFingerprintWiderThanItsLedgerColumnIsRefused`·`anIdentityWhoseStorageKeyWouldNotFitTheLedgerIsRefused` FAIL(`Expecting actual not to be null`)→PASS. V001 컬럼 폭(caller 256, method 256, hash 80, storage key 512)으로 compact constructor에서 거부 `src/grpc/grpc-core-api/src/main/java/dev/caskeleton/grpc/api/ledger/GrpcOperationIdentity.java:24,40`. migration 변경 없음. 커밋 `a498ad84` | - | fingerprint ≤256자 검증 또는 storage key를 해시로 고정 길이화 | | N-12a | Nit | `GrpcClientMessageDeduplicator`가 "constant space"라지만 outcome이 세션 내내 누적, `endSession`이 O(N) `removeIf` | 남음 | `src/grpc-advanced/grpc-advanced-streaming/src/main/java/dev/caskeleton/grpc/advanced/streaming/GrpcClientMessageDeduplicator.java:13,110-112` | W5 | outcome을 세션별 map으로 나눠 `endSession`은 한 번에 제거, javadoc 정정 | | N-12b | Nit | `ReactiveGrpcClient.serverStream`은 List를 Flux로 감싸기만 함 | 남음 | `src/grpc-advanced/grpc-advanced-compat/src/main/java/dev/caskeleton/grpc/advanced/reactor/ReactiveGrpcClient.java:50` | W5 | 메서드 삭제 | | O-1 | Critical | root plugin 적용 시 compose overlay가 없으면 설정 단계에서 빌드 전체 실패 (= Critical #1) | 완료 | `src/build-logic/src/main/java/dev/caskeleton/buildlogic/bootstrap/DeveloperBootstrapPlugin.java:79-88` (overlay 확인이 task `doFirst`로 이동). 테스트 `DeveloperBootstrapPluginFunctionalTest.configurationDoesNotRequireComposeFiles`. 커밋 `6d27356e` | - | - | | O-2 / BUILD-계획-B1 / BUILD-바로할것-3 | Critical | `redis-sdk` CI job이 항상 실패하고 `release-gate`가 그 성공을 요구 (= Critical #2) | 완료 | `.github/workflows/ci-quality-gates.yml:74-100` (release-gate needs에 redis-sdk·`REDIS_RESULT` 없음), `_reusable-gradle.yml` 삭제됨. 커밋 `6d27356e`
BUILD-계획-B1: `_reusable-gradle.yml` 삭제(`6d27356e`), 모든 job이 `./.github/actions/setup-gradle-java` 사용
BUILD-바로할것-3: `ci-quality-gates.yml`에 redis-sdk job·release-gate needs 없음(`208077fd` 기준 `:109,225,240`에서 제거) | - | - | -| O-3a | Required | `verifyNoIgnoredSourcePackages`가 `src/main/java`·`src/test/java`만 검사(testFixtures·integrationTest·systemTest·architectureTest 미검사, sample 제외) | 남음 | `src/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/ArchitecturePlugin.java:193-205` | W2 | 각 project의 모든 source set `java.srcDirs`를 수집 | -| O-3b | Required | git 오류(exit 128, 실행 파일 없음)면 검사가 통과(fail-open) | 남음 | `src/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/VerifyNoIgnoredSourcePackagesTask.java:70-80` (exit code 미확인), `:117-119` (`IOException` → null → 통과) | W2 | 저장소에 `.git`이 있는데 git이 0/1 외 코드로 끝나거나 실행 불가면 `GradleException` | -| O-3c | Required | optional-platforms의 `ci`가 이 검사를 돌리지 않아 gRPC 소스 미검사 | 남음 | `src/optional-platforms/build.gradle:33-38` | W2 | optional build `ci`에 같은 검사 연결 | +| O-3a | Required | `verifyNoIgnoredSourcePackages`가 `src/main/java`·`src/test/java`만 검사(testFixtures·integrationTest·systemTest·architectureTest 미검사, sample 제외) | 완료 | Wave 1–2 P13 (fcddab7e·Wave 2 커밋): `VerifyNoIgnoredSourcePackagesFunctionalTest.sourceInAnIgnoredPackageOfAnAuxiliarySourceSetFailsTheGate` FAIL(`UnexpectedBuildSuccess` — integrationTest source set 미검사)→PASS, `...sourceInAnIgnoredPackageOfTheSamplePortfolioFailsTheGate` FAIL(`found no Java sources at all; the gate would pass vacuously.` — sample 제외)→PASS. 수정: `src/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/ArchitecturePlugin.java:196-215` — 모든 project의 모든 `SourceSet.java.srcDirs`를 모으고 build 디렉터리 아래(생성 코드)만 뺀다. sample도 포함. 실제 저장소: main build 4784개 Java 소스 검사(이전 main/test·sample 제외 약 4117개), optional-platforms 341개, 둘 다 OK. | - | 각 project의 모든 source set `java.srcDirs`를 수집 | +| O-3b | Required | git 오류(exit 128, 실행 파일 없음)면 검사가 통과(fail-open) | 완료 | Wave 1–2 P13 (fcddab7e·Wave 2 커밋): `VerifyNoIgnoredSourcePackagesFunctionalTest.gitFailingInsideACheckoutFailsTheGateInsteadOfPassing` FAIL(`UnexpectedBuildSuccess` — 깨진 `.git`에서 git exit 128인데 통과)→PASS. 수정: `VerifyNoIgnoredSourcePackagesTask.java:70,102-150` — checkout 여부를 git 출력이 아니라 상위 디렉터리의 `.git` 존재로 판단(`checkoutRoot`), checkout 안에서 `git check-ignore`가 실행 불가(`IOException`)거나 exit가 0/1이 아니면 `GradleException`. `.git`이 없는 소스 묶음만 기존처럼 이름 규칙만 적용. `rev-parse` 호출과 `GitCommandResult` 삭제. | - | 저장소에 `.git`이 있는데 git이 0/1 외 코드로 끝나거나 실행 불가면 `GradleException` | +| O-3c | Required | optional-platforms의 `ci`가 이 검사를 돌리지 않아 gRPC 소스 미검사 | 완료 | Wave 1–2 P13 (fcddab7e·Wave 2 커밋): `src/optional-platforms/build.gradle:38-40` — `ci`가 `verifyCleanArchitectureDependencies` 대신 `architectureCheck`(방향 + purity + `verifyNoIgnoredSourcePackages`)에 의존. 재현: `./gradlew -p optional-platforms ci --dry-run`에서 `verifyNoIgnoredSourcePackages` 0회 → 수정 후 포함. `./gradlew -p optional-platforms ci` BUILD SUCCESSFUL, `verifyNoIgnoredSourcePackages: OK — 341 Java sources`. | - | optional build `ci`에 같은 검사 연결 | | O-3d | Required | 이 검사의 테스트가 0개 | 남음 | `git grep -l IgnoredSource -- src/build-logic/src/test src/app-bootstrap/src src/build-tools/src/test` 0건 | W4 | TestKit 케이스: integrationTest source set에 ignore 대상 패키지 → 실패, git 실패 → 실패 | | O-4a | Required | app-bootstrap `test`가 선언 안 된 저장소 파일(runbook, `.env.example`)을 읽어 UP-TO-DATE 거짓 통과 | 완료 | `src/app-bootstrap/build.gradle:276-294` (`docs/**`, `*.example`, `.env*` 등을 `repositoryContractInputs`로 RELATIVE 선언). 커밋 `6d27356e` | - | - | | O-4b | Required | messaging adapter test가 schema 파일을 sysprop으로 읽으면서 입력 미선언 | 완료 | `src/adapter/outbound/messaging/build.gradle:45-48` (`inputs.file(config/messaging/evidence/build-evidence-manifest-v1.schema.json)`). 커밋 `6d27356e` | - | - | | O-4c | Required | CI에서 커밋마다 jar manifest version이 바뀌어 test·SpotBugs cache가 항상 miss | 남음 | `src/build-logic/src/main/java/dev/caskeleton/buildlogic/release/ReleaseProvenancePlugin.java:29` (`GITHUB_SHA`), `src/build-logic/src/main/java/dev/caskeleton/buildlogic/java/JavaConventionsPlugin.java:65` (`Implementation-Version`), normalization 설정 0건 | W3 | 입력 선언이 끝났으므로(O-4a/b) `JavaConventionsPlugin`에 `normalization.runtimeClasspath.metaInf.ignoreAttribute("Implementation-Version")` 추가 | | O-5a | Consider | 의존성 artifact checksum 검증(`verification-metadata.xml`)이 없음 | 보류 | `src/gradle/`에 `verification-metadata.xml` 없음 | - | 보류: lockfile로 버전은 고정됨, 의존성 갱신마다 metadata 재생성 부담을 지지 않음. 승인자: 저장소 소유자(2026-09-25) | -| O-5b | Consider | included build(build-logic/build-tools)의 plugin 의존성이 lock 없이 `gradlePluginPortal`에서 받아짐 | 남음 | `src/build-logic/settings.gradle:6-10`, build-logic·build-tools에 `gradle.lockfile`·`dependencyLocking` 없음 | W1 | `src/build-logic/build.gradle`에 `dependencyLocking { lockAllConfigurations() }` + lockfile 커밋(build-tools는 비울 예정이면 생략) | +| O-5b | Consider | included build(build-logic/build-tools)의 plugin 의존성이 lock 없이 `gradlePluginPortal`에서 받아짐 | 완료 | Wave 1–2 P13 (fcddab7e·Wave 2 커밋): W1 `50cb2d9e`. `src/build-logic/build.gradle:9-12`, `src/build-tools/build.gradle:10-13`에 `dependencyLocking { lockAllConfigurations(); lockMode = STRICT }`. lockfile 커밋: `src/build-logic/gradle.lockfile`, `src/build-tools/gradle.lockfile`(+ `--write-locks`가 만든 `settings-gradle.lockfile` 2개, main build와 같은 형태). 재생성: `./gradlew -p build-logic dependencies --write-locks`(build-tools도 같음). 재현(FAIL): lockfile의 `spotless-plugin-gradle:8.6.0`을 `8.5.0`으로 바꾸고 `./gradlew -p build-logic compileJava` → `:compileJava FAILED ... Dependency version enforced by Dependency Locking`. 복원 후 `-p build-logic test` 80/80, `-p build-tools test` 35/35 통과. 범위 한계는 P13-new-1 참고. | - | `src/build-logic/build.gradle`에 `dependencyLocking { lockAllConfigurations() }` + lockfile 커밋(build-tools는 비울 예정이면 생략) | | O-6 | Consider | 프로젝트 좌표 `dev.caskeleton:messaging-kafka` 중복(adapter vs vendored) | 완료 | `src/adapter/outbound/messaging-kafka/build.gradle:14-23` (`group = 'dev.caskeleton.adapter'`, `archivesName = 'adapter-outbound-messaging-kafka'`). 커밋 `6d27356e` | - | - | | O-7 / BUILD-중복-1 / BUILD-바로할것-1 | Consider | runtime membership 검사가 방향 게이트와 중복 | 완료 | `ca.runtime-membership` 삭제: `src/build-logic/README.md:41`, `git ls-files src/build-logic \| grep RuntimeMembership` 0건. 커밋 `6d27356e`
BUILD-중복-1: `ca.runtime-membership` id·코드 grep 0건(`src/build-logic/build.gradle`), 삭제 표 `src/build-logic/README.md:41`. 컴파일러·방향 task·ArchUnit은 리뷰대로 유지
BUILD-바로할것-1: id·클래스 grep 0건, `src/build.gradle`에 적용 없음 | - | - | | O-8 / BUILD-중복-2 / BUILD-바로할것-6 | Consider | "지정 테스트가 실행됐고 skip 없음" 검사 구현이 5개 | 남음 | 4개(`ca.strict-qualification`, `ca.conditional-transport-qualification`, `ca.graphql-platform`, `ca.evidence`)는 삭제되고 `strictTestLanes` + `RequiredTestExecution`으로 합쳐짐(`src/build-logic/README.md:42-44`). 남은 1개: `src/build-tools/src/main/java/dev/caskeleton/buildtools/junit/JUnitEvidenceReader.java` (사용처 `src/build-tools/src/main/java/dev/caskeleton/buildtools/jpa/JpaEvidenceTestResultLocator.java`뿐)
BUILD-중복-2: 3개 남음: `StrictLaneExecutionTracker`(정본), `RedisTopologyExecutionTracker`(`src/build-logic/src/main/java/dev/caskeleton/buildlogic/redis/RedisTopologyLanePlugin.java:81`, 소유자 결정으로 유지), `JUnitEvidenceReader`(`src/build-tools/src/main/java/dev/caskeleton/buildtools/junit/`, `JpaEvidenceTestResultLocator`가 사용). RejectSkippedTestsListener·JUnitEvidence·MongoJUnitXml은 grep 0건
BUILD-바로할것-6: `MongoJUnitXml` 삭제. `JUnitEvidenceReader`는 JPA evidence 전용으로 남음(`src/build-tools/src/main/java/dev/caskeleton/buildtools/junit/JUnitEvidenceReader.java`) | W3 | 소유자 결정대로 JPA evidence manifest(`ca.jpa-evidence`, `ca.jpa-qualification`)를 leaf 테스트로 옮길 때 `buildtools/junit/` 패키지를 함께 삭제
BUILD-중복-2: JPA evidence를 폐기할 때 `junit` 패키지(138+76줄)도 같이 삭제
BUILD-바로할것-6: BUILD-O3-2와 같이 삭제 | @@ -608,7 +620,7 @@ | TEST-F-1 | Required | fake가 실제 adapter와 같은 계약으로 묶여 있지 않음 | 남음 | 공통 추상 계약이 있는 포트: DurableOperationStore, GrpcOperationLedger, WorkLogRepository, OutboxLeaseFencing(fake·adapter 양쪽이 상속). 없는 포트: Redis, tus, DeliveryProjection, MessagePublisher, IdempotencyStore, ObjectControlStore(TEST-FAKE 행) | W4 | TEST-FAKE 행마다 계약 추가 | | TEST-F-2a | Required | `claimsAreDeterministicallyOrdered`가 순서를 확인하지 않음 | 남음 | `src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/platform/PostgreSqlWorkClaimContractTest.java:78-86` `isNotEmpty()`만 | W4 | 두 번 claim해 기대 순서를 `containsExactly`로 단언 | | TEST-F-2b | Required | `batchCreatePersistsEveryItemAtomically`가 원자성을 증명하지 못함 | 완료 | 이름과 단언을 맞춤: `src/sample-portfolio/src/test/java/dev/caskeleton/sample/portfolio/application/worklog/WorkLogUseCasesTest.java:258-264` `savesAllItemsInOneWriteTransaction`이 `tx.committed()`를 단언 | - | - | -| TEST-F-2c | Required | PII가 없다는 단언이 항상 통과함 | 남음 | 예외 메시지에 원래 PII가 없음: `src/adapter/outbound/notification/src/test/java/dev/caskeleton/adapter/outbound/notification/core/RoutingNotifierTest.java:131`("provider-failure")→`:174`, `src/adapter/outbound/support/src/test/java/dev/caskeleton/adapter/outbound/support/FailOpenDependencyLoggerTest.java:69`("connection refused")→`:72` | W1 | 예외 메시지에 실제 PII를 넣고, 로그에서 빠지는지 단언 | +| TEST-F-2c | Required | PII가 없다는 단언이 항상 통과함 | 완료 | Wave 1–2 P7 (fcddab7e·Wave 2 커밋): `RoutingNotifierTest.failingProvider`가 `"POST " + WEBHOOK_URL + " rejected " + n.recipient()`를 던진다(`RoutingNotifierTest.java:54,134`). `failOpenProviderLogsFailureWithProviderIdAndNoPii`·`piiNeverReachesLogOnSendFailure`가 수신자(`alice@example.com`)와 webhook URL이 로그에 없음을 단언한다. 수정 전 둘 다 FAIL(`not to contain: "alice@example.com"`) → PASS. `FailOpenDependencyLoggerTest` 쪽은 A-1b. 같은 결함이 있던 `NotificationAdapterTest.failingProvider`도 수신자를 메시지에 넣게 고쳤다(`NotificationAdapterTest.java:80`, 두 테스트 FAIL→PASS). 커밋 `9a05d686` | - | 예외 메시지에 실제 PII를 넣고, 로그에서 빠지는지 단언 | | TEST-F-2d | Required | "…BeforeIngress" 테스트가 converter 경로를 건너뜀 | 남음 | `src/adapter/inbound/web-notification/src/test/java/dev/caskeleton/adapter/inbound/web/notification/platform/callback/NotificationCallbackMvcControllerTest.java:118-126` 컨트롤러를 직접 호출 | W4 | MockMvc로 HTTP 경로를 거쳐 크기 제한을 단언 | | TEST-F-2e | Required | SLO 버킷 대신 `isNotEmpty()`만 확인 | 남음 | `src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/metrics/MetricsContractConfigTest.java:57-70` | W4 | 기대 SLO 경계값 목록을 `containsExactly`로 단언 | | TEST-F-2f | Required | `assertThat(context).isNotNull()` | 남음 | `SampleApplicationContextTest`는 고쳐짐(`:50-81` 구체 단언). `src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/autoconfigure/tracing/TracingActivationContextTest.java:80-83`은 남음 | W4 | 빈 endpoint로 기동한 뒤 exporter·bean 상태를 단언 | @@ -668,7 +680,7 @@ | X1-지도-caller 트랜잭션 guard | 권고 | 9벌 복사 → persistence-jpa helper 1개 (= E-3) | 남음 | persistence-jpa 복사본 4벌 + guard 없는 곳 10개(세부 X1-#4) | W3 | X1-#4 | | X1-지도-Backoff 계산식 | 권고 | 10개, "full jitter" 뜻 3가지 → shared-contract `Backoff` | 남음 | 앱 쪽 3개 남음(`OutboxBackoffPolicy.java:63-68`, `ExponentialFullJitterBackoff.java:78`, `RetryBackoff.java:42`), JPA 2개 삭제 | W3 | X1-#9 | | X1-지도-Rate limit | 권고 | web 전용 병렬 타입 세트 삭제 (= I-8 일부) | 완료 | `WebRateLimiter`·web `RateLimitDecision`·`RateLimitFailurePolicy`·`WebMvcThrottleFilter` 삭제(`docs/capability-status.md:99`); 남은 경로 `RateLimitWebConfig.java:22` → `EdgeRateLimitTransportBridge` → shared `EdgeRateLimitPort`, 커밋 `6d27356e` | - | - | -| X1-지도-Admission / in-flight | 권고 | 유지하되 gRPC check-then-increment는 `Semaphore`로 (= N-5) | 남음 | web admission 삭제(`docs/capability-status.md:101`). `grpc/grpc-server/.../GrpcAdmissionController.java:51-60` `get() < max` 후 `incrementAndGet()` 그대로 | W2 | X1-#10a | +| X1-지도-Admission / in-flight | 권고 | 유지하되 gRPC check-then-increment는 `Semaphore`로 (= N-5) | 완료 | Wave 1–2 P5 (fcddab7e·Wave 2 커밋): N-5a와 같은 수정. `Semaphore` 대신 한 락: in-flight와 queued 두 카운터를 한 결정에서 함께 봐야 해서 semaphore 두 개로는 원자적으로 안 된다. `GrpcAdmissionController.java:52`, `GrpcAdmissionControllerTest` | - | X1-#10a | | X1-지도-Kafka producer | 권고 | legacy seam·platform 2개, 둘 다 TLS/SASL 없음 → outbox 정리에 포함 | 남음 | platform producer는 Wave 1(1-4)에서 보안 적용. legacy `KafkaSenderAutoConfiguration.java:60-80` `kafkaSeamProducer`에 `security.protocol`·SASL·SSL 설정 없음 | W1 | X1-#1f | | X1-지도-파일 control plane / canonical JSON | 권고 | 소비자 0인 `FilePublicationPort` plane 삭제, parser 3개 → 1개 | 완료 | publication R1/R2 31개·`FilePublicationPort`·`FileExportPort` 삭제(`docs/capability-status.md:76-77`), 남은 직접 파서 `objectstorage/control/CanonicalJsonReader.java` 1개, 커밋 `6d27356e` | - | - | | X1-지도-readiness / evidence / API-surface / moduleboundary | 권고 | 카드 스키마·검증기·API-surface gate·moduleboundary 여러 벌 → 하나로 | 남음 | moduleboundary main 3벌 삭제, API-surface는 `ca.api-surface` 하나. 남은 것: 카드 스키마 3개·검증기 3곳, JPA evidence plugin(build-tools `jpa/` 48파일) | W3 | 결정(2026-09-25): O3 — JPA readiness·evidence는 persistence-jpa 테스트로(manifest 폐기), messaging 카드 검증은 messaging leaf로 | @@ -676,7 +688,7 @@ | X1-#1a | Required | Outbox V2 삭제 + v1 claim에 owner+token fencing 이식 | 완료 | `persistence-jpa/.../db/migration/postgresql/V17__outbox_event_lease_fencing.sql`, `OutboxStoreAdapter.java:102-123`(markPublished·markFailed·markDead가 `lease.owner()`·`lease.token()` 조건부 UPDATE), V2 코드·`jpa/outbox-storage`·`jpa/outbox-polling` 삭제(`docs/capability-status.md:175-179`), 커밋 `6d27356e` | - | - | | X1-#1b | Required | append 포트를 `OutboxAppendPort` 하나로, legacy는 cutover 후 삭제 | 남음 | `OutboxAppendPort` main 소비자 0(구현 `CanonicalOutboxAppendAdapter`뿐). `LegacyOutboxAppendPort` 소비자 4곳: `SubmitDurableOperationUseCase.java:56`, sample `PosterEventPublisher.java:25`·`PosterImagePublicationEventPublisher.java:12`·`CreateWorkLogUseCase.java:42`. canonical 경로는 `IntegrationEventEncoderPort` 구현이 필요한데 템플릿은 주지 않음(`src/messaging/CLAUDE.md:83-89`, main 구현 0) | W3 | 결정(2026-09-25): canonical 통일(S1-#2b와 같은 작업) | | X1-#1c | Required | `CanonicalOutboxAppendAdapter`에 caller 트랜잭션 guard 없음 (= E-3) | 남음 | `CanonicalOutboxAppendAdapter.java:36-75` `append`가 트랜잭션 확인 없이 `repository.save` | W3 | X1-#4 helper를 `append` 첫 줄에서 호출(1곳) + 트랜잭션 없이 부르면 거부되는 테스트 | -| X1-#1d | Required | canonical 이벤트가 v1 claim을 타며 aggregate 순서·tenant 범위를 잃음 (= E-5) | 남음 | `PostgreSqlOutboxClaimRepository.java:15-29` FIFO gate가 `aggregate_id`·`occurred_at`만 사용, `tenant_scope`·`aggregate_sequence`·`event_index` 미사용 | W2 | X1-#1b에서 canonical 경로를 남기면: canonical row(`contract_id IS NOT NULL`) gate를 `(tenant_scope, aggregate_type, aggregate_id)` + `(aggregate_sequence, event_index)` 순서로, `H2OutboxClaimRepository`도 동일 | +| X1-#1d | Required | canonical 이벤트가 v1 claim을 타며 aggregate 순서·tenant 범위를 잃음 (= E-5) | 완료 | Wave 1–2 P9 (fcddab7e·Wave 2 커밋): E-5a·E-5b와 같은 변경 — canonical row claim 순서를 tenant·type·id + sequence·index로(PostgreSQL·H2 SQL), migration V18 index | - | X1-#1b에서 canonical 경로를 남기면: canonical row(`contract_id IS NOT NULL`) gate를 `(tenant_scope, aggregate_type, aggregate_id)` + `(aggregate_sequence, event_index)` 순서로, `H2OutboxClaimRepository`도 동일 | | X1-#1f | Required | legacy Kafka producer에 TLS/SASL 없음 (Critical #8 = M-2와 같은 문제) | 남음 | `adapter/outbound/messaging-kafka/.../KafkaSenderAutoConfiguration.java:60-80` producer config에 bootstrap·serializer·acks·timeout만 | W1 | `KafkaAdapterSettings`에 security 블록(protocol·SASL·truststore) 추가 후 `kafkaSeamProducer` config에 반영, 또는 X1-#1b 결정으로 seam 자체 삭제 | | X1-#1g | Required | `src/messaging/CLAUDE.md`에 "앱은 `messaging_outbox`를 쓰지 않는다" 명시 | 남음 | `grep -n messaging_outbox src/messaging/CLAUDE.md` → 0건 | W5 | `src/messaging/CLAUDE.md` MSG-015 절(:60-89)에 한 줄 추가 | | X1-#1h | Required | fencing 시나리오를 contract kit로 fake·실제 adapter 양쪽에서 실행 | 완료 | testFixtures `OutboxLeaseFencingContract`를 `InMemoryOutboxStoreLeaseFencingContractTest.java:9`와 `PostgreSqlLegacyOutboxConcurrentRelayIntegrationTest.java:45`가 상속, 커밋 `6d27356e` | - | - | @@ -695,21 +707,21 @@ | X1-#6b | Required | lock과 lease 중 하나만 남김 | 남음 | `DistributedLockPort`(구현 `LockRegistryDistributedLockAdapter`, 참조는 `StartupSafetyValidator.java:51` 존재 검사뿐), `DistributedLeasePort`(구현 `RedisDistributedLeaseAdapter`, 소비자 0). `CacheRefreshCoordinationPort`는 삭제(`docs/capability-status.md:152`). `LeaseAttempt`·`IdempotencyClaimAttempt` 같은 구조 그대로 | W4 | 결정(2026-09-25): lock·lease 둘 다 유지(S1-#3b와 같은 작업) | | X1-#6c | Required | app-core inbox 삭제로 `IdempotencyOwner`·`InboxOwner` 중복 record 해소 | 해당 없음(코드 삭제) | `application/inbox/` 삭제(`docs/capability-status.md:155`) | - | - | | X1-#6d | Required | `ClaimFencingContract` kit를 application-core testFixtures에 두고 row lease store마다 실행 | 남음 | outbox 전용 `OutboxLeaseFencingContract`만 있음. durable operation(`claimNext`·`heartbeat`), notification `JpaRecipientLeaseStore`는 공통 fencing kit 없음 | W4 | `OutboxLeaseFencingContract`의 "밀려난 쪽 종결 쓰기는 0건" 시나리오를 범용 `ClaimFencingContract`로 올리고 durable operation·recipient lease store 2곳에 상속 추가 | -| X1-#6e | Required | notification `recipients.save`가 lease 확인 없이 씀 (= B-5) | 남음 | `application-notification/.../dispatch/DispatchOutcomeRecorder.java:135` `recipients.save(updated)` | W2 | projection 뒤 recipient를 다시 읽고 recorder 소유 필드만 `saveHeldBy(lease)`로 기록 + late-match 회귀 테스트 | +| X1-#6e | Required | notification `recipients.save`가 lease 확인 없이 씀 (= B-5) | 완료 | Wave 1–2 P3 (fcddab7e·Wave 2 커밋): B-5a·B-5b와 같은 결함. 같은 수정·테스트(`DispatchOutcomeRecorder.java:122,153`) | - | projection 뒤 recipient를 다시 읽고 recorder 소유 필드만 `saveHeldBy(lease)`로 기록 + late-match 회귀 테스트 | | X1-#6f | 권고 | shared-contract `OperationalRecordStorePort`(CAS 저장 포트) 사용처 0 — 리뷰 권고 "미사용분 삭제" 적용 대상 | 남음 | `shared-contract/.../opstore/OperationalRecordStorePort.java:19`, 같은 패키지 `OperationalRecord`·`OperationalRecordConflictException` 포함 구현·호출·테스트·문서 참조 0(`git grep -w OperationalRecordStorePort` → 자기 파일뿐) | W3 | `shared-contract/src/main/java/dev/caskeleton/shared/opstore/` 3개 삭제, `docs/capability-status.md` 제거 표에 한 줄 | | X1-#7a | Required | readiness 카드 스키마 3개·검증기 3개, family별 evidence plugin | 남음 | 카드: `src/config/jpa/readiness-cards.yaml`(kebab JSON), `src/config/messaging/readiness-cards.yaml`(camelCase), `docs/registries/object-storage-readiness.yaml`(snake_case). 검증기: build-tools `JpaReadinessRegistryValidator.java`, app-bootstrap `MessagingCapabilityRegistryContractTest.java`, objectstorage `ObjectStorageReadinessRegistryTest.java`. messaging·notification·mongo evidence plugin은 leaf 테스트로 이동, JPA evidence는 build-tools `jpa/` 48파일에 남음(계획서 진행 기록 Wave 5 "남은 설계 결정") | W3 | 결정(2026-09-25): O3 방향(X1-지도-readiness와 같은 작업) | | X1-#7b | Required | API-surface gate 3개 → `ca.api-surface` 하나 | 완료 | notification·persistence-jpa·persistence-mongo·graphql 모두 `id 'ca.api-surface'`(`adapter/outbound/notification/build.gradle:4`, `persistence-jpa/build.gradle:7`), `ca.notification-api-surface`·`verifyJpaAdopterApiSurface` 삭제. JPA adopter import 검사는 leaf 테스트 `JpaAdopterApiSurfaceTest`, 커밋 `6d27356e` | - | - | | X1-#7c | Required | web·graphql·websocket main의 moduleboundary 3벌 → ArchUnit | 완료 | 3벌 삭제(`docs/capability-status.md:80,93,113`), graphql 규칙 2개는 `GraphQlTransportBoundaryArchitectureTest.java`로, 커밋 `6d27356e` | - | - | | X1-#8a | Consider | 소비자 0인 `FilePublicationPort` plane 삭제, parser 3→1, 경계 결정 문서화 | 완료 | `docs/capability-status.md:76-77`, fileserver `FileserverControlRecordCodec`·`LocalPublicationJournalCodec` 삭제, 남은 파서 `CanonicalJsonReader.java` 1개, `docs/storage-capability-boundary.md` "Decision rule" 절, 커밋 `6d27356e` | - | - | | X1-#9 | Consider | Backoff 계산식 10개, "full jitter" 뜻 3가지 → shared-contract `Backoff` | 남음 | JPA `BackoffCalculator`·`TransactionRetryBackoff`, httpclient `BackoffStrategy` 삭제. 앱 쪽 3개: `OutboxBackoffPolicy.java:63-68`(이름은 full jitter인데 `base·2ⁿ + U(0,base)`, 상한 없음), `ExponentialFullJitterBackoff.java:78`(`U(0,capped]`), notification `RetryBackoff.java:42`. mongo·messaging·grpc는 자체 유지 대상 | W3 | shared-contract에 `Backoff(base, max, Jitter)`(stdlib만) 추가, 사용처 2곳(`OutboxBackoffPolicy`, `ExponentialFullJitterBackoff`) 교체; notification은 application-notification→shared-contract edge를 registry에 추가할 때만 | -| X1-#10a | FYI | `GrpcAdmissionController` check-then-increment → `Semaphore.tryAcquire` (= N-5) | 남음 | `grpc/grpc-server/.../GrpcAdmissionController.java:51-60` | W2 | `inFlight`·`queued`를 `Semaphore` 또는 `updateAndGet` CAS로, 동시 호출 수 > 한도 테스트 1개(optional build) | +| X1-#10a | FYI | `GrpcAdmissionController` check-then-increment → `Semaphore.tryAcquire` (= N-5) | 완료 | Wave 1–2 P5 (fcddab7e·Wave 2 커밋): 위와 같음(동시 호출 수 > 한도 테스트 `GrpcAdmissionControllerTest.racingCallersNeverGetPastTheConcurrencyAndQueueBounds`, optional build) | - | `inFlight`·`queued`를 `Semaphore` 또는 `updateAndGet` CAS로, 동시 호출 수 > 한도 테스트 1개(optional build) | | X1-#10b | FYI | SHA-256 헬퍼 65벌, notification `MessageDigestPort`는 과한 추상화 → 흡수 | 남음 | `application-notification/.../dispatch/MessageDigestPort.java` + `Sha256MessageDigestAdapter.java` 그대로. 헬퍼 수는 X2-P1-5 | W3 | X2-P1-5와 같이. `MessageDigestPort`는 application-notification이 shared-contract edge를 가져야 흡수 가능 → edge 추가 후 포트·adapter 2개 삭제 | -| X2-P1-1a | Required | S3 시크릿이 `System::getenv` 고정 → `SecretSourcePort` bridge | 남음 | `objectstorage/.../s3/S3ObjectStorageProviderContribution.java:41` 기본 생성자가 `System::getenv` | W1 | S3 contribution에 `SecretSourcePort`를 주입해 `secretSource::resolve`(Redis `RedisCapabilityConfig.java:66-67` 방식), `System::getenv` 기본값 제거 | -| X2-P1-1b | Required | Mongo credential bridge 없음(기본 `unconfigured()`) | 남음 | `persistence-mongo/.../security/MongoCredentialResolver.java:31`; persistence-mongo 밖 `MongoCredentialResolver` bean 0; persistence-mongo는 registry edge 0이라 `SecretSourcePort`를 못 봄 | W1 | modules.json에 persistence-mongo→application-core edge 추가 후 Mongo auto-config에 `MongoCredentialResolver` bridge bean 1개(`secretSource::resolve`) | +| X2-P1-1a | Required | S3 시크릿이 `System::getenv` 고정 → `SecretSourcePort` bridge | 완료 | Wave 1–2 P2 (fcddab7e·Wave 2 커밋): `S3ProviderCompositionTest.capabilityConfigResolvesS3CredentialsThroughTheSecretSourcePort` FAIL(`IllegalArgumentException: S3 provider binding is invalid: credential environment references did not resolve completely`)→PASS. `s3/S3ObjectStorageProviderContribution.java:33`(공개 생성자가 `SecretSourcePort`를 받고 `System::getenv` 제거), `config/ObjectStorageCapabilityConfig.java:47-51`(`ObjectProvider`를 자격 증명을 실제로 풀 때 조회 — secret backend 없는 local-only 조립도 기동됨). 새 설정·env 키 없음 | - | S3 contribution에 `SecretSourcePort`를 주입해 `secretSource::resolve`(Redis `RedisCapabilityConfig.java:66-67` 방식), `System::getenv` 기본값 제거 | +| X2-P1-1b | Required | Mongo credential bridge 없음(기본 `unconfigured()`) | 완료 | Wave 1–2 P12 (fcddab7e·Wave 2 커밋): `MongoProfileClientSettingsAutoConfigurationTest.aTypedProfileResolvesItsUriThroughTheApplicationSecretSource` FAIL(`IllegalStateException: MongoDB typed profiles are configured but no MongoCredentialResolver bean is available`)→PASS, `aSecretSourceWithoutTheReferencedKeyFailsClosed`. `src/config/architecture/modules.json:81-86`(`adapter-outbound-persistence-mongo` → `application-core`), `src/adapter/outbound/persistence-mongo/build.gradle:32`(`implementation project(':application-core')`), bridge bean `client/MongoProfileClientSettingsAutoConfiguration.java:57`(`@ConditionalOnBean(SecretSourcePort)`·`@ConditionalOnMissingBean(MongoCredentialResolver)`, `MongoCredentialResolver.fromSecretSource(secretSource::resolve)`), `security/MongoCredentialResolver.java:42`(key = `secret:///`의 ``, Redis·httpclient와 같은 규칙). `MongoRegistryPermissionParityTest`(app-bootstrap) PASS. 이유는 W1 커밋 메시지에 적음. | - | modules.json에 persistence-mongo→application-core edge 추가 후 Mongo auto-config에 `MongoCredentialResolver` bridge bean 1개(`secretSource::resolve`) | | X2-P1-2a | Required | websocket prod 판정 직접 구현(`Prod`·공백 미인식) (= A-2) | 해당 없음(코드 삭제) | `WebSocketPlatformSafetyConfiguration`·`app.websocket.platform.*` 삭제(`docs/capability-status.md:186`), websocket main에 `"prod"` 문자열 0 | - | - | | X2-P1-2b | Required | httpclient `profile/RuntimeEnvironment`가 정본과 이름이 같음(Nit) | 남음 | `adapter/outbound/httpclient/.../profile/RuntimeEnvironment.java` (httpclient 안 참조 파일 4개 + 정본 import 1개) | W5 | `HttpClientHardening` 등으로 개명, 참조 4파일 수정 | | X2-P1-3a | Required(문서) | capability settings 규칙(strict 바인딩 + compact constructor)을 root 문서에 | 완료 | `AGENTS.md:216` capability 완료 기준 4, 커밋 `6d27356e` | - | - | -| X2-P1-3b | Required | gRPC adapter strict prefix `ca-skeleton.grpc`가 벤더 `ca-skeleton.grpc.platform`과 겹침 | 남음 | `adapter/inbound/grpc/.../GrpcServerSettings.java:17`(`ignoreUnknownFields = false`, `platform` 필드 없음) vs `grpc-spring-boot-starter/.../GrpcPlatformProperties.java:19`. 미확인: 두 스택 동시 기동 실패는 실행 안 함 | W2 | adapter prefix를 `ca-skeleton.grpc.server` 등으로 분리(설정 키·env key·README 갱신) | +| X2-P1-3b | Required | gRPC adapter strict prefix `ca-skeleton.grpc`가 벤더 `ca-skeleton.grpc.platform`과 겹침 | 완료 | Wave 1–2 P5 (fcddab7e·Wave 2 커밋): `GrpcSafeActivationTest.theVendorPlatformNamespaceBesideTheAdapterDoesNotFailItsStrictBinding` FAIL(`UnboundConfigurationPropertiesException: The elements [ca-skeleton.grpc.platform.enabled] were left unbound`)→PASS. 어댑터 prefix `ca-skeleton.grpc` → `ca-skeleton.grpc.server` `src/adapter/inbound/grpc/src/main/java/dev/caskeleton/adapter/inbound/grpc/GrpcServerSettings.java:17`, `GrpcServerConfig.java`. 어댑터 키는 env-keys registry에 행이 없었다(추가·수정 없음). 갱신: `src/adapter/inbound/grpc/{CLAUDE,README}.md`, `src/README.md:269`(env `CA_SKELETON_GRPC_SERVER_ALLOW_INSECURE_LOCAL`). **오케스트레이터 할 일:** `docs/capability-status.md:42`의 `ca-skeleton.grpc.enabled`·`ca-skeleton.grpc.allow-insecure-local`을 `.server.` 경로로. Wave 3-B(`app.*`)에서도 `app.grpc.server`처럼 벤더 prefix와 형제로 둬야 같은 충돌이 다시 안 생긴다. 커밋 `a498ad84` | - | adapter prefix를 `ca-skeleton.grpc.server` 등으로 분리(설정 키·env key·README 갱신) | | X2-P1-3c | Required | 오타 키 거부가 일부 capability에만 적용 | 남음 | strict 바인딩 4곳(fileserver·httpclient `StrictSettingsBinder`, `GrpcServerSettings.java:17`, `GrpcPlatformProperties.java:19`) / main `@ConfigurationProperties` 54파일(`git grep -l "@ConfigurationProperties" -- 'src/**/src/main/java/**'`) | W3 | `AGENTS.md:216` 기준대로 capability 모듈(cache-redis, persistence-jpa, persistence-mongo, messaging, notification, objectstorage, graphql, websocket) settings를 `StrictSettingsBinder`로 바인딩 | | X2-P1-4a | Consider | web `cursor/CursorCodec`(dev key 하드코딩) 삭제 | 완료 | `docs/capability-status.md:94`, `HmacWebCursorCodec`도 삭제(`:97`), 커밋 `6d27356e` | - | - | | X2-P1-4b | Consider | 서명 계층 하나(inbound에서 서명, persistence는 typed keyset), 남으면 공용 서명 헬퍼 | 남음 | HMAC codec 7 → 4: graphql `HmacGraphQlCursorCodec`, persistence-jpa `SignedJsonCursorCodec`, persistence-mongo `MongoKeysetCursorCodec`, 벤더 `GrpcResumeTokenCodec`. 앱 쪽 3개 모두 production 생성 0(라이브러리 API) | W3 | 결정(2026-09-25): Wave 3 라이브러리 유지 결정을 따름 — 서명 codec 유지, shared-contract에 sign/verify 헬퍼 하나로 중복 제거 | @@ -730,7 +742,7 @@ | X2-P2-5 | Consider | correlation이 HTTP 밖으로 안 이어짐, `MdcKeys`가 web에 갇힘 | 남음 | `adapter/inbound/web/.../observability/MdcKeys.java`(사용 5파일, web-fileserver 포함), `MDC.put`은 `RequestLoggingFilter.java:65-71,147`뿐, `CorrelationIdPort` 구현은 `MdcCorrelationIdPortAdapter` 1개, GraphQL은 `GraphQlPlatformWebInterceptor.java:157` Spring request id | W3 | `MdcKeys`를 shared-contract로(원본 `docs/registries/mdc-keys.yaml`), 사용 5파일 import 변경; websocket STOMP·gRPC interceptor에 MDC 채우는 코드, GraphQL은 `WebRequestId` 사용 | | X2-P2-6a | Required | 같은 이름 `TenantContext` 2개, 허용 문법이 다름 | 남음 | web `core/TenantContext.java:20` `[A-Za-z0-9][A-Za-z0-9_.-]{0,63}` vs graphql `context/TenantContext.java:17,30`(비어있지 않고 128자 이하). 그 밖에 persistence-jpa `experimental/tenant/TenantId`, application-notification `TenantId` | W3 | application-core에 tenant id 값 타입 1개(web 문법) 두고 web·graphql `TenantContext` 2곳이 감쌈, notification·jpa `TenantId`도 같은 타입으로 맞춤 | | X2-P2-7a | Required | 연결 안 된 두 번째 rate-limit stack 삭제 (= I-8 일부) | 완료 | `WebRateLimiter`·`WebMvcThrottleFilter`·`ThrottleProblemWriter` 삭제(`docs/capability-status.md:99-100`), WebFlux throttle은 WebFlux와 함께 삭제(`:88`), 커밋 `6d27356e` | - | - | -| X2-P2-7b | Required | client IP 신뢰 규칙이 두 갈래 (= I-5) | 남음 | `web/ratelimit/ForwardedHeaderClientIpResolver.java:11-16` trusted proxy 확인 없이 XFF 첫 hop vs `web-notification/.../ExternalRequestUrlResolver.java:31` trusted proxy일 때만 | W1 | `ForwardedHeaderClientIpResolver`도 `remoteAddr`가 trusted proxy일 때만 XFF 사용(아니면 `remoteAddr`), 규칙은 `ExternalRequestUrlResolver`와 같은 설정 하나로 | +| X2-P2-7b | Required | client IP 신뢰 규칙이 두 갈래 (= I-5) | 완료 | Wave 1–2 P10 (fcddab7e·Wave 2 커밋): I-5a와 같은 결함. client IP 해석 경로가 `getRemoteAddr()` 하나만 남음(XFF를 직접 읽는 main 코드 grep 0건, `ForwardedHeaderClientIpResolver` 삭제). 남은 `web-notification/.../ExternalRequestUrlResolver`는 client IP가 아니라 URL(proto/host) 해석이고 이미 trusted proxy일 때만 읽는다. 그 forwarded 파싱 삭제·설정 통합은 현황표 I-5b(W3)가 소유해서 이번에 건드리지 않음 | - | `ForwardedHeaderClientIpResolver`도 `remoteAddr`가 trusted proxy일 때만 XFF 사용(아니면 `remoteAddr`), 규칙은 `ExternalRequestUrlResolver`와 같은 설정 하나로 | | X2-P2-8 | Consider | Origin 검증기 3개, env key 3개 기본값 다름 | 해당 없음(코드 삭제) | web `WebCorsPolicyValidator` 삭제(`docs/capability-status.md:206`), websocket platform origin 정책·`APP_WEBSOCKET_PLATFORM_*` 삭제(`:186`); 남은 검증은 `WebSocketSettings.java:25`(+`@AssertTrue`) 1개 | - | - | | X2-P2-9a | FYI | 크기 제한 위반 코드 이름이 전송마다 다름 | 남음 | web `PAYLOAD_TOO_LARGE`(`GlobalExceptionHandler.java:342`), graphql `REQUEST_TOO_LARGE`(`GraphQlHttpOutcome.java:32`)·`GRAPHQL_DOCUMENT_SHAPE_REJECTED`, fileserver `FILE_TOO_LARGE`(`FileserverErrorCode.java:36`) | W3 | P2-1 정리 때 body 크기 초과는 `PAYLOAD_TOO_LARGE` 하나로(graphql 1곳), 문서 모양 거부·파일 크기는 별도 코드 유지 | | X2-P2-9b | FYI | STOMP가 모든 실패를 `WEBSOCKET_REQUEST_REJECTED` 하나로 → carrier 코드 소실 | 남음 | `SafeStompSubProtocolErrorHandler.java:12,21-27` | W3 | 원인이 `ApiErrorCarrier`면 그 `code()`를 `error-code` 헤더에(메시지는 고정 유지), 나머지는 현재 값 | @@ -756,7 +768,7 @@ | S1-#3a | Required | 호출자 없는 cache executor 20종·`LeaseWatchdog`·`TransactionCompletionResolver`·inbox·filepublication·`EphemeralFanoutPort` | 해당 없음(코드 삭제) | 「제거된 코드」 application-core cache 20종, `LeaseWatchdog`, `TransactionCompletionResolver`, same-store inbox, `FilePublicationPort`, `EphemeralFanoutPort` 행 | - | - | | S1-#3b | Required | `lease/*` 399줄: Redis 구현만 있고 use case 호출자 0 (= X1-#6) | 남음 | `application-core/.../lease/`(13파일 399줄) 참조는 `cache-redis/.../lease/RedisDistributedLeaseAdapter.java`·`RedisLeaseConfig.java`뿐. JDBC `DistributedLockPort`도 비즈니스 소비자 0. cache-redis README가 lease를 제공 capability로 명시 | W4 | 결정(2026-09-25): lock·lease 둘 다 capability로 유지 — 포트별 추상 계약 테스트를 fake와 어댑터가 함께 통과 | | S1-#4 | Required | `NotificationDispatchService` 생성자 15개, record 필드별 재조립·실패 분류가 한 클래스에 (B-5 구조 원인) | 남음 | `application-notification/.../dispatch/NotificationDispatchService.java:72`(인자 15개), `:208`·`:485` record 재조립, `:255-288` catch 분기, `:475`·`:513` 종료 상태 두 번 계산. `DispatchOutcomeRecorder.java:67,110` 재조립 2곳 | W3 | `DeliveryAttemptRecord.completed(result, at)`·`RecipientDeliveryRecord.advancedRoute(now)` 전이 메서드 추가, catch 분기는 `ProviderOutcomeClassifier` 정적 메서드로 분리 | -| S1-#5 | Required | fileserver retire 절차 3곳 복사, admin `forceDelete`는 content 없는 레코드를 DELETING에 남김 (C-4 관련) | 남음 | `application-fileserver/.../admin/DefaultFileserverAdminService.java:160-175`(contentKey 없을 때 DELETED 전이 없음) vs `lifecycle/DefaultFileLifecycleService.java:87-100`(있음), `upload/DefaultUploadApplicationService.java:258-269` | W2 | `retire(FileRecord)` 하나로 합치고 content 없으면 DELETING→DELETED 전이를 세 호출부 모두에 적용 | +| S1-#5 | Required | fileserver retire 절차 3곳 복사, admin `forceDelete`는 content 없는 레코드를 DELETING에 남김 (C-4 관련) | 완료 | Wave 1–2 P4 (fcddab7e·Wave 2 커밋): `FileserverAdminServiceTest.forceDeletingAFileThatWasNeverPublishedRetiresItCompletely` FAIL(`expected: DELETED but was: DELETING`)→PASS. 세 호출부가 `src/application-fileserver/.../cleanup/FileRetirement.java:40` 하나를 쓴다: `DefaultFileLifecycleService.java:84`, `DefaultFileserverAdminService.java:167`, `DefaultUploadApplicationService.java:265`. `cleanup` 패키지에 둔 이유: 세 호출 패키지가 이미 cleanup을 의존하고 cleanup은 그들을 의존하지 않아 새 패키지 순환이 생기지 않는다 | - | `retire(FileRecord)` 하나로 합치고 content 없으면 DELETING→DELETED 전이를 세 호출부 모두에 적용 | | S1-#6a | Required | fileserver 단일 구현 인터페이스 6개(fake 없음) | 남음 | `CleanupService`, `WriterLeaseCoordinator`, `FileLifecycleService`, `TransferAdmissionController`, `FileReconciliationService`, `FileStateMachine` 모두 구현 1개(`Default*`) | W3 | 인터페이스 6개 삭제, `Default*`를 인터페이스 이름으로 개명 | | S1-#6b | Required | fileserver 인바운드가 use-case 계약 밖(capability gate 미적용) | 남음 | `application-fileserver/src/main/java`에서 `@UseCaseCapability`/`CommandUseCase`/`QueryUseCase` 0건(notification 14파일) | W3 | transport가 부르는 연산을 `*UseCase` + `@UseCaseCapability`로 선언 | | S1-#7 | Consider | 에러 코드마다 예외 서브클래스, 타입 분기는 몇 개뿐 | 남음 | fileserver `api/error/` 예외 23개 그대로(`FileNotFoundException`·`FileAlreadyExistsException`·`InvalidPathException` JDK 이름 충돌 유지). notification은 throw 0인 12개만 삭제(「제거된 코드」 행), 12개 남음 | W3 | base를 구체 클래스 + `of(code, …)`, 서브클래스는 catch로 타입 분기하는 5개만 남김 | @@ -784,7 +796,7 @@ | S1-lead-3 | 권고 | 멱등성 executor 조립 위치 (= G-11) | 남음 | adapter 조립은 사라졌으나(`RedisIdempotencyConfig.java:51` store만) 조립이 `app-bootstrap/.../idempotency/IdempotencyProviderSelectionConfig.java:48`에 있음. 소유자 결정은 별도 `composition:*` 모듈 | W3 | `IdempotencyProviderSelectionConfig`·`IdempotencySettings`를 새 `composition:idempotency`(가칭) 모듈로 이동, registry 등록 | | S1-lead-4 | 권고 | `Local*Gateway`가 `LocalBlockingContentStore`로 넘기기만 | 남음 | `adapter/outbound/fileserver/.../platform/local/` gateway 6개 385줄, 이 중 `LocalDownloadContentGateway`(26줄)·`LocalCleanupContentGateway`·`LocalZeroCopyDownloadGateway`는 위임만 | W3 | 위임만 하는 3개는 `LocalBlockingContentStore`가 해당 gateway 인터페이스를 직접 구현, 로직 있는 Copy/Upload는 유지 | | S1-lead-5 | 권고 | persistence-jpa `SpringPolicyTransactionPort` 정리 | 해당 없음(코드 삭제) | 「제거된 코드」 `SpringPolicyTransactionPort`… 행 | - | - | -| S1-lead-6 | 권고 | fileserver 전이 규칙이 Java와 SQL 두 곳 | 남음 | `application-fileserver/.../api/DefaultFileStateMachine.java:14` vs `adapter/outbound/persistence-fileserver/.../repository/FileTransitionRepository.java:63-68`(DELETING 진입 가능 상태를 SQL 문자열로 하드코딩) | W2 | SQL의 허용 상태 목록을 `FileState` 전이표에서 파라미터로 넘기거나, 두 목록이 같은지 단언하는 테스트 추가 | +| S1-lead-6 | 권고 | fileserver 전이 규칙이 Java와 SQL 두 곳 | 완료 | Wave 1–2 P4 (fcddab7e·Wave 2 커밋): SQL의 허용 상태 문자열을 없애고 `JpaFileMetadataStore`가 전이표(`FileStateMachine.canTransition(s, DELETING)`)에서 목록을 만들어 파라미터로 넘긴다: `src/adapter/outbound/persistence-fileserver/.../repository/FileTransitionRepository.java:73`, `JpaFileMetadataStore.java:56`. 동작이 바뀐 게 아니라 중복 제거라 FAIL 재현 대상이 없음. PG `aRecordInAStateWithNoDeletingEdgeIsNotMarkedDeleting`(VERIFYING 거부)·기존 `logicalDeleteMovesTheRecordOutOfPublicReadability` PASS | - | SQL의 허용 상태 목록을 `FileState` 전이표에서 파라미터로 넘기거나, 두 목록이 같은지 단언하는 테스트 추가 | | S2-#1a | Required | JPA `notification/crypto` 505줄 테스트 전용 사본 | 해당 없음(코드 삭제) | 「제거된 코드」 "JPA notification crypto 6종과 테스트" 행 | - | - | | S2-#1b | Required | persistence-jpa가 notification persistence를 품음(jpa→application-notification edge) | 남음 | `adapter/outbound/persistence-jpa/build.gradle:38` `implementation project(':application-notification')`, `persistence/notification/**` 6,573줄, `PersistenceJpaConfig.java:40-80` 19개 패키지 목록 ×2, `:88` `OPT_IN_NOTIFICATION_PACKAGE`, `PersistenceEntityScanCoverageTest.java:46`. 계획 W4가 추출을 적었으나 registry에 `persistence-notification` 없음 | W3 | `persistence-fileserver/build.gradle` 방식으로 `adapter:outbound:persistence-notification` leaf 추출, 목록 2개·상수·coverage 테스트 삭제 | | S2-#2a | Required | Mongo: 바인딩 안 되는 `advanced.*.enabled`, 구현 없는 인터페이스 10개, reactive·change stream | 해당 없음(코드 삭제) | 「제거된 코드」 Mongo advanced 바인딩·search/vector·time series·GridFS·`MongoDataKeyResolver` 등·reactive·change stream 행. 인터페이스 9개 grep 0, `MongoTenantMigrationCheckpointStore`는 구현 생김(`MongoTenantMigrationCoordinator.java:96`) | - | - | @@ -814,12 +826,12 @@ | S2-lead-4 | 권고 | persistence 실패 예외 계층 3벌 | 남음 | jpa `api/error/JpaPersistenceException.java:14`(RuntimeException 상속, 21개, 라이브러리 `PostgreSqlExceptionTranslator` 결과), mongo `api/error` 24개, shared `shared-contract/.../error/PersistenceFailureException.java`(web·grpc가 매핑) | W3 | `JpaPersistenceException`이 `PersistenceFailureException`을 상속해 inbound가 한 계층만 매핑(mongo는 edge 없어 유지) | | S2-lead-5 | 권고 | sample이 `PostgreSqlPersistenceConfig`의 claim repository bean을 재선언 | 완료 | `sample-portfolio/.../bootstrap/persistence/SamplePostgreSqlPersistenceConfig.java:28-48`은 sample Flyway 전략만 선언, claim repository bean 없음 | - | - | | S2-lead-6 | 권고 | JPA 조립이 leaf와 bootstrap에 나뉨 | 완료 | 「제거된 코드」 `JpaPlatformAutoConfiguration`·`JpaPlatformRuntimeAutoConfiguration` 행, 조립은 `persistence-jpa/src/main/resources/META-INF/spring/...AutoConfiguration.imports`(3개)에만, `app-bootstrap/.../autoconfigure/`에 jpa 없음 | - | - | -| S3-#1 | Required | httpclient blocking/reactive 병렬 스택이 이미 갈라짐 (= H-5, H-7) | 남음 | D4는 inbound WebFlux만 삭제. httpclient `webclient/`·`reactor/`·`service/Reactive*` 그대로, `build.gradle:30-37` webflux·reactor 의존. 401 refresh는 blocking만(`restclient/DefaultGenericHttpGateway.java:212-225`), `webclient/ReactiveAttemptExecutor.java:155-172` `false` 고정, `ReactiveClientRuntime.java:39`가 `BlockingExecutionSupport` 사용 | W3 | 결정(2026-09-25): D4를 outbound에도 적용 — httpclient reactive(WebClient·Reactor Netty) 스택과 webflux·reactor 의존 삭제 | -| S3-#2a | Required | reactive streaming 요청이 admission·deadline·credential 없이 나감 | 남음 | `adapter/outbound/httpclient/.../webclient/ReactiveStreamingGateway.java:50-107`(prepared header만 전송, credential·admission·deadline 호출 없음) vs `restclient/BlockingStreamingGateway.java`(고쳐짐) | W2 | S3-#1에서 reactive를 지우면 함께 삭제, 유지하면 blocking과 같은 credential·admission·deadline 단계 적용 + 동작 테스트 | +| S3-#1 | Required | httpclient blocking/reactive 병렬 스택이 이미 갈라짐 (= H-5, H-7) | 완료 | Wave 1–2 P11 (fcddab7e·Wave 2 커밋): D 커밋 `06764fcb`에서 reactive 스택(WebClient·Reactor Netty)과 webflux·reactor·reactor-netty·reactor-test·blockhound 의존 삭제. blocking(RestClient) 경로 하나만 남음. `clients[N].api` 설정 키·`ClientApiType`·`TransportType.REACTOR_NETTY` 삭제, env-fields.yaml 행 삭제, lockfile 재생성(httpclient·app-bootstrap). Jetty HTTP/3 실험 transport는 reactive SPI에 묶여 있어 blocking SPI(`JettyClientHttpRequestFactory`)로 옮김(자동 조립 안 됨은 그대로) `HC/http3/JettyHttp3TransportProvider.java:49` | - | 결정(2026-09-25): D4를 outbound에도 적용 — httpclient reactive(WebClient·Reactor Netty) 스택과 webflux·reactor 의존 삭제 | +| S3-#2a | Required | reactive streaming 요청이 admission·deadline·credential 없이 나감 | 해당 없음(코드 삭제) | Wave 1–2 P11 (fcddab7e·Wave 2 커밋): D `06764fcb`에서 `webclient/ReactiveStreamingGateway` 삭제. blocking 스트리밍은 deadline·credential·admission 적용 `HC/restclient/BlockingStreamingGateway.java:69,82,106` | - | S3-#1에서 reactive를 지우면 함께 삭제, 유지하면 blocking과 같은 credential·admission·deadline 단계 적용 + 동작 테스트 | | S3-#2b | Required | 진입점 6개가 호출 파이프라인을 각자 조립 | 남음 | `CallSetup` 등 공통 조립 없음(grep 0), `DefaultDynamicTargetGateway`·`DefaultReactiveSseGateway`·`BlockingStreamingGateway`·`ReactiveStreamingGateway`가 각자 조립 | W3 | `CallSetup.prepare(lease, operation)`이 metadata/prepared/deadline/admission/credentials 반환, 진입점은 전송만 다르게 | | S3-#3a | Required | 118개 메서드 `RedisCommandGateway`, runtime이 SDK 개념에 역의존 (= G-7) | 남음 | `redis-runtime/.../lettuce/operations/RedisCommandGateway.java`(1,227줄, 메서드 118), `:1107-1134` `sendApprovedRaw/sendAdminDiagnostic/sendExtension`, `lettuce/connection/RedisConnectionKind.java:25-33` BLOCKING·TRANSACTION·PUBSUB lane, `:64` `forCommand(RedisCommandDescriptor)` | W3 | runtime 계약은 semantic adapter가 쓰는 8개(`SemanticRedisCommands`)로, 나머지는 redis-sdk 확장 인터페이스로 이동(redis-sdk 유지 결정 반영), lane은 REGULAR·SCRIPT만 | | S3-#3b | Required | runtime이 `Sdk` 이름·`...redis.sdk` 패키지를 쓰고 redis-sdk와 split package | 남음 | `redis-runtime/.../sdk/config/RedisSdkSettings.java`(670줄), `RedisSdkAutoConfiguration.java`, redis-runtime·redis-sdk 공유 패키지 9개 | W3 | `RedisRuntimeSettings`로 개명, runtime 패키지를 `...redis.runtime.*`로, SDK 전용 설정 섹션은 redis-sdk로 | -| S3-#4a | Required | cache-redis에서 "안 보냄/보냈는지 모름" 구분을 rate-limit만 함 | 남음 | `ambiguousExecution()` 사용은 `cache-redis/.../ratelimit/RedisEdgeRateLimitAdapter.java:130`뿐, 멱등성·lease·cache는 lane 거절도 `Indeterminate`(계획 진행 기록 Wave 1 "남은 것"에도 기재) | W2 | 멱등성·lease·cache의 실패 분류에 `metadata().ambiguousExecution()`로 NOT_SENT/AMBIGUOUS 구분 추가 | +| S3-#4a | Required | cache-redis에서 "안 보냄/보냈는지 모름" 구분을 rate-limit만 함 | 완료 | Wave 1–2 P6 (fcddab7e·Wave 2 커밋): 멱등성·lease는 NEW-5c 수정. cache는 현황표 근거("lane 거절도 Indeterminate")가 사실과 다름: cache는 이미 lane 거절을 `DEGRADED_UNAVAILABLE`(=안 보냄)로 돌려준다. 빠진 쪽은 반대 방향이었다 — 보낸 뒤 응답을 잃은 쓰기도 `DEGRADED_UNAVAILABLE`였다. `RedisCacheRegionAdapter.java:241,294,314,328`에 `sent` 플래그를 두어 쓰기 명령을 보낸 뒤의 실패는 `INDETERMINATE`, 그 전(lane 거절·연결·generation 조회)은 `DEGRADED_UNAVAILABLE`. 테스트 `RedisCacheRegionAdapterTest.aWriteWhoseReplyWasLostIsIndeterminate`/`anInvalidationWhoseReplyWasLostIsIndeterminate`/`aRegionInvalidationWhoseReplyWasLostIsIndeterminate` FAIL(`expected: INDETERMINATE but was: DEGRADED_UNAVAILABLE`)→PASS, 가드 `aWriteThatFailedBeforeItsSetWasSentDegrades` PASS | - | 멱등성·lease·cache의 실패 분류에 `metadata().ambiguousExecution()`로 NOT_SENT/AMBIGUOUS 구분 추가 | | S3-#4b | Required | "lease 빌림 → `.get(timeout)` → 예외 처리" 틀 복사, Lua 응답 디코더 3벌 | 남음 | `catch (InterruptedException` 16곳(멱등성 6·lease 4·cache 4·rate-limit 1·probe 1), 디코더 `idempotency/IdempotencyScripts.java:273`, `lease/LeaseScripts.java:162`, `ratelimit/RateLimitScripts.java:280` | W3 | `SemanticRedisCall.run(...)` 공통 틀 + 응답 디코딩을 등록 스크립트 쪽 한 곳으로 | | S3-#5 | Consider | `RedisIdempotencyStoreAdapter.transition` 인자 14~15개, 상태 문자열 switch 반복 | 남음 | `cache-redis/.../idempotency/RedisIdempotencyStoreAdapter.java:164-180`(`transition` 호출 14개 인자), `:137-157` 등 문자열 switch | W3 | `IdempotencyScripts.Reply`에서 `enum ScriptStatus`로 한 번 파싱, 호출부는 `Map` | | S3-#6 | Consider | 대체 불가능한 확장 지점(`HttpClientTagPolicy` bean) | 남음 | `httpclient/.../autoconfigure/HttpClientObservationAutoConfiguration.java:23-27` bean 소비처 0, `restclient/BlockingExecutionSupport.java:77`이 `HttpClientTagPolicy.standard()`를 다시 생성, `observation/HttpClientTagPolicy.java:32` private 생성자라 override 자체 불가 | W3 | bean 삭제, `BlockingExecutionSupport`는 `ExecutionSupport`로 개명 | @@ -832,7 +844,7 @@ | S3-#12a | Nit | `CacheKeys`가 가변 generation 상태 보유, `KeyDigest`가 설정 패키지에 | 남음 | `cache-redis/.../cache/RedisCacheRegionAdapter.java:375,430`(`CacheKeys.observeGeneration`), `capability/RedisKeys.java:37` `KeyDigest` | W5 | `RegionGeneration` 분리, `KeyDigest`를 keyspace 패키지로 옮기고 `RedisNamespace.prefix()` 사용 | | S3-#12b | Nit | cache-redis CLAUDE.md의 "legacy cache router"는 존재하지 않음 | 남음 | `adapter/outbound/cache-redis/CLAUDE.md:22` | W5 | 해당 줄 삭제 | | S3-#13a | Nit | Jackson 2 사용 main 파일은 하나인데 주석은 "two files" | 남음 | `httpclient/build.gradle:67` vs Jackson 2 import는 `restclient/RemoteProblemDecoder.java`뿐 | W5 | `RemoteProblemDecoder`를 Jackson 3로 옮기고 `jackson-databind`(2) 의존 삭제 | -| S3-#13b | Nit | draining·retry 소진을 `HttpRateLimitRejectedException`으로 던짐(텔레메트리 카테고리 오기) | 남음 | `httpclient/.../restclient/DefaultGenericHttpGateway.java:182,280`, `webclient/DefaultReactiveHttpGateway.java:265,351` | W2 | draining·retry 소진 전용 예외(또는 카테고리)로 분리 | +| S3-#13b | Nit | draining·retry 소진을 `HttpRateLimitRejectedException`으로 던짐(텔레메트리 카테고리 오기) | 완료 | Wave 1–2 P11 (fcddab7e·Wave 2 커밋): `DefaultGenericHttpGatewayTest.anExhaustedRetryBudgetIsReportedAsItsOwnFailureNotARateLimit`·`aRetryRefusedByADrainingRuntimeIsReportedAsItsOwnFailureNotARateLimit` FAIL(`expected HttpRetryBudgetExhaustedException/HttpRuntimeDrainingException but was HttpRateLimitRejectedException`)→PASS. `HC/restclient/DefaultGenericHttpGateway.java:183,281`, 새 타입 `HC/api/error/HttpRetryBudgetExhaustedException.java`·`HttpRuntimeDrainingException.java`, `docs/httpclient/operations.md` 예외 표 갱신. 두 경로는 재시도 판정과 다음 attempt 사이의 경합에서만 도달하므로 테스트는 `TestGateways.forProfile(profile, transport, eligibility)`로 판정기를 주입해 재현 | - | draining·retry 소진 전용 예외(또는 카테고리)로 분리 | | S3-#13c | Nit | Redis health indicator 둘이 DOWN 값만 다름 | 남음 | `redis-runtime/.../sdk/config/RedisSdkAutoConfiguration.java:257`(DEGRADED)·`:285`(DOWN) | W5 | 상태 값만 인자로 받는 indicator 하나로 | | S3-lead-1 | 권고 | `RedisSecretSource` + `System.getenv` 기본값 vs `SecretSourcePort` (= X2 P1-1) | 완료 | 문제 아님: redis-runtime은 의존 edge가 없어 자체 SPI(`RedisSdkAutoConfiguration.java:168-171,334`)를 두고, cache-redis가 `SecretSourcePort`로 bridge(`cache-redis/.../capability/RedisCapabilityConfig.java:66`). X2 P1-1이 이 구조를 모범 사례로 판정 | - | - | | S3-lead-2 | 권고 | `HttpClientEnvironmentKeys`(리플렉션 env 이름 역산) vs `StrictSettingsBinder` (= X2 P1-3) | 남음 | `httpclient/.../autoconfigure/HttpClientEnvironmentKeys.java`(179줄, `RecordComponent` 순회), `HttpClientPlatformSettingsBinder.java:27`만 사용. 다른 capability는 env 오타 검사 없음 | W3 | env 이름 역산 검사를 support `StrictSettingsBinder` 옵션으로 옮겨 모든 capability가 같은 방식으로 오타 env를 거부 | @@ -859,10 +871,10 @@ |---|---|---|---|---|---|---| | S4-#1 | Required | fileserver 루트 publication 제품군(R1+R2, 31파일 8.7k줄) 호출처 없음 (= X1-8) | 완료 | `src/adapter/outbound/fileserver/src/main/java/.../fileserver/` 아래 `platform/`만 남음(main 5,626줄). `FilePublicationPort`·`FileExportPort`·`FileserverActivationValidator`·`app.file-export.*` grep 0건. 「제거된 코드」 표 76–78행, 커밋 `6d27356e` | - | - | | S4-#2 | Required | messaging R1 compiler/encoder 체인·realtime fanout 미연결 | 완료 | `src/adapter/outbound/messaging` main 13파일 765줄(`core`·`outbox`·`platformbridge`·`autoconfigure`만). NetworkNT는 `build.gradle`에 `testImplementation`만. `JsonSchemaIntegrationEventEncoder`·`CompiledMessagingDescriptor`·`MessagingDurableFanoutAdapter` grep 0건. 「제거된 코드」 표 119–122행과 `realtime/` 행, `6d27356e` | - | - | -| S4-#3a | Required | notification 미조립 provider 5종(APNs·FCM·Twilio·WebPush·Webhook) | 남음 | `notification/…/platform/provider/{apns,fcm,twilio,webpush,webhook}` 재측정 2,750줄(327+526+681+863+353). 자기 패키지 밖 main 참조 0건. assembler는 `SesProviderRuntimeAssembler.java:28`, `SmtpProviderRuntimeAssembler.java:48` 두 개뿐. `ProviderType.java:22-41`에 7종이 남아 있고, 켜면 `NotificationProviderAssembly.java:144`에서 기동 실패. 계획서 W4 표는 "미조립 provider 5종 삭제"라고 했지만 코드도 「제거된 코드」 표 행도 없음 | W3 | 5개 패키지 삭제. `ProviderType`에서 APNS·FCM·TWILIO·WEB_PUSH·WEBHOOK 제거. `docs/notification/configuration-reference.md:69,106-114` 표 정리. 「제거된 코드」 표에 행 추가 | -| S4-#3b | Required | SES callback은 조립되는데 projector 없음 → 모든 callback 이벤트가 `NO_PROJECTOR`로 실패 처리 | 남음 | main에 `ProviderEventProjector` bean이 0개임. `NotificationPlatformRegistriesConfig.java:36-40`는 빈 `List`로 registry를 만듦. `NotificationProviderAssembly.java:175`가 모은 `AssembledPlatform.projectors`를 읽는 곳 0건. 그래서 `ProviderEventProjectionService.java:80-82`가 `markFailed(…, "NO_PROJECTOR")` 처리. `SesDeliveryProjector`·`SesSuppressionUpdater` main 참조 0건인데 `SesProviderCallbackAssembler.java:13`은 조립됨 | W2 | SES callback assembler가 `SesDeliveryProjector`를 `AssembledProvider`에 싣고, registry는 `AssembledPlatform.projectors()`로 만든다. suppression을 적용하려면 `SesSuppressionUpdater`도 연결. SES callback이 bounce를 반영하는지 통합 테스트 1개 추가 | +| S4-#3a | Required | notification 미조립 provider 5종(APNs·FCM·Twilio·WebPush·Webhook) | 완료 | Wave 1–2 P3 (fcddab7e·Wave 2 커밋): D 커밋 `38d31b98`. `provider/{apns,fcm,twilio,webpush,webhook}` main·test 삭제, `SesSuppressionUpdater` 삭제. `ProviderType`은 SES·SMTP만(`ntf-adapter/autoconfigure/ProviderType.java:26-30`). 5종만 쓰던 설정 필드 `topic`·`vapid-public-key`·`callback-signing-secret-ref` 삭제(`NotificationPlatformSettings.java` Provider), `SecretPurpose.VAPID_SIGNING`·`vapid-signing-key`·env 키 2개(`APP_NOTIFICATION_PLATFORM_VAPID_SIGNING_KEY`, `_KEY_ID`)를 `notification.yml`·`.env.example`·`env-keys.yaml`·`secrets-classification.yaml`·`scripts/run-compose-runtime-smoke.sh`에서 삭제. 문서: `docs/notification/{configuration-reference,support-matrix,module-mapping,provider-runbooks}.md`, `composition/notification-platform/README.md`. 새 테스트 `NotificationPlatformSettingsTest.aRemovedProviderTypeFailsStartupAsUnknown`(5종 → "unknown provider type"). API surface 416→379 재승인. `verifyEnvKeys` OK | - | 5개 패키지 삭제. `ProviderType`에서 APNS·FCM·TWILIO·WEB_PUSH·WEBHOOK 제거. `docs/notification/configuration-reference.md:69,106-114` 표 정리. 「제거된 코드」 표에 행 추가 | +| S4-#3b | Required | SES callback은 조립되는데 projector 없음 → 모든 callback 이벤트가 `NO_PROJECTOR`로 실패 처리 | 완료 | Wave 1–2 P3 (fcddab7e·Wave 2 커밋): `NotificationProviderAssemblyTest.anSesHardBounceIsProjectedRatherThanFailedForWantOfAProjector` FAIL(컴파일: `providerEventProjectorRegistry(AssembledPlatform, List)` 없음 — registry가 빈 bean 목록으로만 만들어지던 구조)→PASS(hard bounce → `DeliveryOutcome.BOUNCED`). 빈 슬롯 유지·연결: `ProviderCallbackAssembler.projector()` 추가, SES는 `SesDeliveryProjector`(`SesProviderCallbackAssembler.java:34`), assembly가 콜백을 만들 때 projector를 `AssembledPlatform.projectors`에 넣음(`NotificationProviderAssembly.java:134`, INGEST_ONLY 포함), registry는 `platform.projectors()` + 선언된 bean(`NotificationPlatformRegistriesConfig.java:46`). `SesSuppressionUpdater`는 소유자 승인 삭제(D)라 연결하지 않았다 — suppression은 `ProviderEventProjectionService`의 `NotificationSideEffectPort` 경로가 이미 처리 | - | SES callback assembler가 `SesDeliveryProjector`를 `AssembledProvider`에 싣고, registry는 `AssembledPlatform.projectors()`로 만든다. suppression을 적용하려면 `SesSuppressionUpdater`도 연결. SES callback이 bounce를 반영하는지 통합 테스트 1개 추가 | | S4-#3c | Required | reconciliation 슬롯·자격증명 회전 경로에 production 입력 없음 | 남음 | `TwilioReconciliationCapability`·`ProviderRuntimeRotator` main 참조 0건. `RuntimeDrainCoordinator`·`CredentialProbe`는 `ProviderRuntimeRotator`만 참조하고 `CredentialProbe` 구현체는 0개. `NotificationPlatformProviderConfig.java:148`이 항상 빈 `reconciliations`로 gateway를 만듦. 두 assembler 모두 `AssembledProvider.dispatchOnly`(`SesProviderRuntimeAssembler.java:98`, `SmtpProviderRuntimeAssembler.java:112`) | W3 | `ProviderRuntimeRotator`·`RuntimeDrainCoordinator`·`CredentialProbe` 삭제. reconciliation 슬롯은 #3a와 함께 지우거나, 남길 경우 README에 "SES/SMTP는 reconciliation 없음" 한 줄 | -| S4-#4a | Required | SMTP capability 값이 두 곳에서 다름 | 남음 | `SmtpProviderRuntimeAssembler.java:126,138-152`: 자기 사본 `25L*1024*1024`(26,214,400), `Duration.ofHours(24)`. `SmtpNotificationProviderAdapter.java:75-76`: 25,000,000, `Duration.ofDays(1)`. SES는 `adapter.capabilities()`를 씀(`SesProviderRuntimeAssembler.java:95`) | W2 | assembler의 `capabilities()` 사본을 지우고 `adapter.capabilities()`를 쓴다. 값 하나로 확정 | +| S4-#4a | Required | SMTP capability 값이 두 곳에서 다름 | 완료 | Wave 1–2 P7 (fcddab7e·Wave 2 커밋): `SmtpProviderRuntimeAssemblerTest.theAssembledProfileDeclaresTheAdaptersOwnCapabilities` FAIL(`maxPayloadBytes=26214400` vs `25000000`)→PASS. assembler에 있던 capability 사본 `capabilities()`를 지우고, snapshot이 SES처럼 `adapter.capabilities()`를 쓴다: `src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/SmtpProviderRuntimeAssembler.java:108,115-134`. 값은 어댑터 쪽(25,000,000 B, 1일) 하나로 정했다. P3가 바꾼 테스트 `profile()` 줄은 건드리지 않았다. 커밋 `3a39b6b5` | - | assembler의 `capabilities()` 사본을 지우고 `adapter.capabilities()`를 쓴다. 값 하나로 확정 | | S4-#4b | Required | `ProviderCapabilities` 위치 인자 11개를 8곳에서 `new` | 남음 | `application-notification/…/provider/ProviderCapabilities.java:12-23`(boolean 8개 + int·long·Duration). main에서 `new ProviderCapabilities(` 8곳(SMTP assembler, SMTP·SES·APNs·FCM·Twilio·WebPush·Webhook adapter). #3a를 하면 3곳이 남음 | W3 | #3a 이후 `ProviderCapabilities.dispatchOnly(maxPayloadBytes, maxTtl)` 같은 named factory 하나 추가 | | S4-#5 | Required | `LocalPersistentControlPlane`(1,470줄)이 7가지 일을 함 | 해당 없음(코드 삭제) | S4-#1과 함께 삭제. `LocalPersistentControlPlane` grep 0건. 「제거된 코드」 표 76행 | - | - | | S4-#6 | Required | "attested root 아래 private shard" 구현 3벌 | 해당 없음(코드 삭제) | `LocalPersistentControlPlane`·`LocalPersistentPayloadOperations`·`LocalPersistentRootAttestor`·`LocalPublicationJournal`·`LocalFilePublicationAdapter` 모두 grep 0건. 남은 `forceDirectory`는 `platform/local/ContentPublishVerification.java:106` 하나. 「제거된 코드」 표 76행 | - | - | @@ -874,7 +886,7 @@ | S4-#11b | Consider | objectstorage 패키지 위치 불명확(port 구현이 `config/`에, managed publish가 router inline) (≈ D-7, D-8) | 남음 | `config/`에 `Routing{Mutation,Read,ScanMaintenance,DirectGrant}Adapter`. `RoutingObjectMutationAdapter.java` 523줄은 `208077fd` 이후 변경 없음. `RoutingObjectDirectGrantAdapter.java:7-9`는 private 생성자만 있는 빈 클래스 | W3 | `Routing*Adapter`를 `routing/`로 옮기고, managed publish 부분을 `kernel/`로 추출. 빈 `RoutingObjectDirectGrantAdapter` 삭제 | | S4-#12 | Consider | `SelectedObjectStorageProviderFactory`가 type-unsafe service locator (≈ D-7) | 남음 | `config/SelectedObjectStorageProviderFactory.java:14-16`에 `Object` 슬롯 3개, `:20-53`에 생성자 4개, `:71-89`에 `Class.cast`. 슬롯 getter 호출은 test(`S3ProviderCompositionTest.java:132,140`)뿐. direct(1,735줄)·multipart(318줄) 패키지는 남아 있음 | W3 | direct/multipart 슬롯 제거 후 `record ProviderInstance(ObjectStorageProvider, ObjectControlStore, Runnable close)`로 교체. direct/multipart 삭제(1차 D-7)와 같이 진행 | | S4-#13 | Consider | provider 1개인데 fileserver R2 routing 계층 | 해당 없음(코드 삭제) | `RoutingFilePublicationAdapter`·`FilePublicationProvider`·`LocalPersistentPublicationProvider` grep 0건. 「제거된 코드」 표 76행 | - | - | -| S4-#14a | Consider | `ProviderRuntime`의 무조건 덮어쓰기가 운영자 결정·인증 실패를 지움 | 남음 | `ProviderRuntime.java:127-132`의 `markAuthenticationFailed`가 무조건 `set`해서 DISABLED·DRAINING을 덮어씀. 반대로 `markDraining`·`markDisabled`(`:221-245`)는 AUTHENTICATION_FAILED를 덮어씀. 그래서 AUTH_FAILED→DISABLED→`resumeHealthy`(`:205`)→HEALTHY 순서로 "인증 실패는 resume 불가" 규칙이 우회됨 | W2 | 전이 규칙을 한 곳에 둔다. AUTH_FAILED는 rotation으로만 벗어나고, DISABLED/DRAINING은 인증 실패로 덮이지 않게. 두 순서에 대한 테스트 추가 | +| S4-#14a | Consider | `ProviderRuntime`의 무조건 덮어쓰기가 운영자 결정·인증 실패를 지움 | 완료 | Wave 1–2 P7 (fcddab7e·Wave 2 커밋): `ProviderRuntimeStateTest.anOperatorStateDoesNotLetResumeClearAnAuthenticationFailure`(DISABLED·DRAINING) FAIL→PASS. `aLateAuthenticationFailureDoesNotOverwriteAnOperatorState`(DISABLED·DRAINING) FAIL(`expected DISABLED but was AUTHENTICATION_FAILED`)→PASS. 전이 규칙은 `ProviderRuntime.moveTo` 한 곳에 있다(`src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/dispatch/ProviderRuntime.java:229-255`). AUTH_FAILED는 rotation(새 runtime)으로만 벗어나고, DISABLED/DRAINING은 인증 실패로 덮이지 않는다. `markAuthenticationFailed`가 이제 적용 여부를 boolean으로 돌려준다. `RegistryProviderRuntimeControl.java:36`은 그 값을 그대로 반환한다(전에는 항상 true). notification API surface(type 목록)는 바뀌지 않았다(`verifyNotificationApiSurface` 통과). 커밋 `3a39b6b5` | - | 전이 규칙을 한 곳에 둔다. AUTH_FAILED는 rotation으로만 벗어나고, DISABLED/DRAINING은 인증 실패로 덮이지 않게. 두 순서에 대한 테스트 추가 | | S4-#14b | Consider | 상태 전이 규칙이 7개 메서드에 흩어짐 | 남음 | `ProviderRuntime.java:127-245`에 `mark*`/`resumeHealthy` 7개가 각자 `updateAndGet` 조건을 가짐. `RegistryProviderRuntimeControl.java:30` switch | W3 | `EnumMap>` 전이표 + `transition(target, reason)` 하나로 (#14a와 같이) | | S4-#15 | Consider | Settings가 모든 provider 필드를 한 record에 담음 | 남음 | `NotificationPlatformSettings.java:211-223`의 `Provider`가 `topic`·`vapidPublicKey`·`callbackSigningSecretRef`를 가짐(APNs·WebPush·Twilio 전용). `:288`은 `switch (resolved.name())` 문자열 분기. `:229-258`은 테스트 호환용 11-인자 오버로드 | W3 | #3a와 함께 미조립 provider 필드·분기 삭제, enum switch로 바꾸고 11-인자 오버로드 삭제 | | S4-#16a | Nit | notification·fileserver 이력 서술 주석 | 남음 | 예: `ProviderType.java:10-15`, `:85`("used to bind successfully"), `NotificationProviderAssembly.java:30`, `MapProviderCallbackAdapterRegistry.java:10-11`(BOOT-017). grep 근사로 notification 37줄, fileserver 12줄 | W5 | 주석을 현재 동작만 설명하도록 줄이고, 이력은 commit/ADR로 | @@ -900,7 +912,7 @@ | S5-#4e | Required | 로깅 `RequestLoggingFilter` vs `WebAccessLog*`/`WebAudit*` (= I-8) | 완료 | `web/observability/`에 `WebAccessLog*`·`WebAudit*` 없음. 표 95행 | - | - | | S5-#4f | Required | 동시 실행 제한 semaphore 3벌 (= I-8) | 완료 | `SemaphoreAdmissionController`(admission)·`BlockingBridgeBudget` 삭제(표 101행, blocking bridge 행). 남은 건 opt-in `web-advanced/…/virtualthread/VirtualThreadAdmissionGuard.java` 하나 | - | - | | S5-#5 | Required | Retry-After 초 계산 3벌, 결과가 다름 | 해당 없음(코드 삭제) | `ThrottleProblemWriter`·`OperationHttpController`·`ReactiveOperationHttpController` 삭제. Duration→초 계산은 `RateLimitInterceptor.java:107-111`(올림) 하나만 남음 | - | - | -| S5-#6a | Required | GraphQL 요청 단계 에러가 `GraphQlWireErrorMapper`를 거치지 않음 → adopter `ApiErrorCarrier`가 요청 단계에서 `INTERNAL_ERROR`로 바뀜 | 남음 | `graphql/…/runtime/GraphQlPlatformWebInterceptor.java:165`, `GraphQlPlatformInstrumentation.java:88`이 `GraphQlPlatformRejectionMapper.map`을 직접 호출. `GraphQlWireErrorMapper.java:23-28` Javadoc도 이 차이를 인정 | W2 | 두 호출부가 `GraphQlWireErrorMapper`의 `map(Throwable, ctx)` 하나(플랫폼 거부 → `ApiErrorCarrier` → application mapping 순서)를 쓰게 한다. principal resolver가 `ApiErrorCarrier`를 던지는 테스트 추가 | +| S5-#6a | Required | GraphQL 요청 단계 에러가 `GraphQlWireErrorMapper`를 거치지 않음 → adopter `ApiErrorCarrier`가 요청 단계에서 `INTERNAL_ERROR`로 바뀜 | 완료 | Wave 1–2 P8 (fcddab7e·Wave 2 커밋): `runtime/GraphQlRequestStageErrorMappingTest.anApiErrorCarrierFromThePrincipalResolverKeepsItsCode`, `anApiErrorCarrierFromAPipelineStageKeepsItsCode` FAIL(`expected "TENANT_SUSPENDED" but was "INTERNAL_ERROR"`) → PASS. 두 테스트 모두 auto-configuration이 만든 bean으로 돌려 "세 곳이 mapper bean을 받는다"를 검증. `GraphQlWireErrorMapper.map(Throwable, ctx)`(플랫폼 거부 → ApiErrorCarrier → application 매핑) + `toGraphQlError`(carrier는 category로 classification) 하나로 interceptor·instrumentation·field resolver가 모두 이것을 씀. `.../runtime/GraphQlWireErrorMapper.java:61,79`, `GraphQlPlatformWebInterceptor.java:168`, `GraphQlPlatformInstrumentation.java:89`, `GraphQlDataFetcherExceptionResolver`, 주입 `GraphQlPlatformAutoConfiguration.java:357,413`. 호출자가 없어진 `GraphQlPlatformRejectionMapper.map` 삭제. 커밋 `aa5f4d90` | - | 두 호출부가 `GraphQlWireErrorMapper`의 `map(Throwable, ctx)` 하나(플랫폼 거부 → `ApiErrorCarrier` → application mapping 순서)를 쓰게 한다. principal resolver가 `ApiErrorCarrier`를 던지는 테스트 추가 | | S5-#6b | Required | 호출처 0인 `mapRequestRejection`과 참조 0인 error 클래스 | 완료 | `mapRequestRejection`·`GraphQlRequestErrorMapper`·`GraphQlSubscriptionExceptionResolver`·`GraphQlNullabilityContract` grep 0건. 표 "`GraphQlWireErrorMapper.mapRequestRejection`" 행과 `error/` 행 | - | - | | S5-#6c | Required | Category switch 3개와 client 문구 중복 | 남음 | `GraphQlWireErrorMapper.java:94`(category), `:104`(clientMessage), `GraphQlWireErrors.java:56`. "요청한 리소스를 찾을 수 없습니다." 3곳(`GraphQlWireErrorMapper.java:108`, `GraphQlPlatformRejectionMapper.java:69`, `security/GraphQlAuthorizationInterceptor.java:50`) | W3 | `EnumMap` 표 하나로 switch 3개를 대체하고 문구 상수를 한 곳에 둔다 | | S5-#6d | Required | 플랫폼 예외 `instanceof` 사슬 9개, 실제 매퍼가 `runtime/`에 있음 | 남음 | `GraphQlPlatformRejectionMapper.java:55-114`에 instanceof 9개. `GraphQlWireErrorMapper`·`GraphQlPlatformRejectionMapper`·`GraphQlWireErrors`가 `runtime/`에 있음(`error/`에는 타입만) | W3 | 플랫폼 예외가 code·category·message 인터페이스를 구현하게 해 instanceof 사슬을 없애고, 매퍼 3개를 `error/`로 옮긴다 | @@ -920,7 +932,7 @@ | S5-#14e | Nit | `GraphQlPlatformWebInterceptor` 생성자 인자 9개 | 남음 | `GraphQlPlatformWebInterceptor.java:66-75`. anonymous 관련 3개(`anonymousProfile`, `anonymousTenant`, `anonymousProfileProtected`) | W5 | anonymous 3값을 record 하나로 묶는다 | | S5-lead-1 | 권고 | client 에러 문구 언어가 전송마다 다름(web 영어, graphql 한국어) (= X2-P2-1) | 남음 | web `error/ClientSafeErrorMessages.java:44-50` 영어, graphql `GraphQlWireErrorMapper.java:104-113` 한국어. gRPC `GrpcStatusMapper.java:33`은 status만 매핑(문구 없음). status/분류 매핑은 전송마다 달라서 공유할 수 없음 | W3 | 결정(2026-09-25): client 에러 문구는 한국어 — `Category`별 문구 표 하나를 shared-contract에 두고 모든 전송이 사용 | | S5-lead-2 | 권고 | moduleboundary 세 번째 사본(websocket) | 해당 없음(코드 삭제) | `WebSocketStableModule`·`WebSocketBuildModel` 0건. 표 80행 | - | - | -| S5-lead-3 | 권고 | request/tenant context 타입이 전송마다 따로 있음 (= X2-P2-6) | 남음 | 이름이 같은 `TenantContext` 두 개의 모양·검증이 다름. web `core/TenantContext.java:17,20`은 `(String tenantId)`, `[A-Za-z0-9][A-Za-z0-9_.-]{0,63}`. graphql `context/TenantContext.java:15,17,30`은 `(value, source)`, 비어 있지 않고 128자 이하면 모두 허용. 같은 tenant가 한 전송은 통과하고 다른 전송은 거부됨 | W2 | tenant 값 타입 하나(검증 규칙 하나)를 application-core/shared-contract에 두고, 두 전송 context가 그것을 담게 한다 | +| S5-lead-3 | 권고 | request/tenant context 타입이 전송마다 따로 있음 (= X2-P2-6) | 남음 | 이름이 같은 `TenantContext` 두 개의 모양·검증이 다름. web `core/TenantContext.java:17,20`은 `(String tenantId)`, `[A-Za-z0-9][A-Za-z0-9_.-]{0,63}`. graphql `context/TenantContext.java:15,17,30`은 `(value, source)`, 비어 있지 않고 128자 이하면 모두 허용. 같은 tenant가 한 전송은 통과하고 다른 전송은 거부됨
Wave 1–2 P8: 미완 — 이유: 공통 tenant 값 타입(shared-contract/application-core)을 만들고 web·graphql(그리고 messaging·persistence·notification의 tenant 타입)이 담게 하는 일은 계획서 Wave 3 3-D 「tenant 값 타입」 공통 작업이고 web은 P10 범위. 이번에는 증상만 막음: GraphQL `TenantContext` 검증을 web과 같은 문법 `[A-Za-z0-9][A-Za-z0-9_.-]{0,63}`으로 맞춰 "한 전송만 통과하는 tenant"를 없앰. `context/GraphQlRequestContextTest.aTenantTheWebTransportRefusesIsRefusedHereToo`(4건) FAIL(`Expecting actual not to be null`) → PASS. `.../context/TenantContext.java:38`. 커밋 `aa5f4d90` | W2 | tenant 값 타입 하나(검증 규칙 하나)를 application-core/shared-contract에 두고, 두 전송 context가 그것을 담게 한다 | | S5-lead-4 | 권고 | release/promotion gate가 websocket/grpc에도 반복되는지 | 남음 | web·graphql·websocket gate는 삭제(표 80·114·115행, web Advanced release 행). grpc에 남음: `grpc/grpc-testkit/…/release/GrpcStableReleaseGate.java`, `grpc-advanced/grpc-advanced-bootstrap/…/release/GrpcAdvancedPromotionGate.java`. 둘 다 main 참조 0건(test만) | W3 | 두 gate와 테스트를 삭제하거나 test source set으로 옮긴다(S6/S7 grpc 항목과 같이) | | S5-lead-5 | 권고 | bulkhead: graphql·fileserver·httpclient가 겹치는지 | 해당 없음(코드 삭제) | 겹치던 web `BlockingBridgeBudget`·`SemaphoreAdmissionController`는 삭제. 남은 3개는 방식이 다름: `GraphQlBlockingBridge.java:45-57`(bounded `ThreadPoolExecutor`+AbortPolicy), `BlockingTransferExecutor.java:26`(Spring `ThreadPoolTaskExecutor`), `BlockingAttemptBulkhead.java:39`(`Semaphore`). 각 100줄 이하 | - | - | @@ -941,11 +953,11 @@ | S6-#1b | Required | websocket main의 gate·moduleboundary·evidence·release, 거짓 주석 `WebSocketAdvancedCapability` | 해당 없음(코드 삭제) | `CS:80`, `CS:185` | - | - | | S6-#1c | Required | 조립되지 않는 websocket 플랫폼 라이브러리 약 9.7k줄 | 완료 | main 12,954 → 1,557줄(`stomp/` 491, `servlet`·`outbound`·`budget`·`core`·`protocol` 1,066). 나머지 패키지 삭제(`CS:185,187`). 남긴 라이브러리는 Wave 3 결정대로 README에 라이브러리 API로 명시(`src/adapter/inbound/websocket/README.md:6-13,56`), `6d27356e` | - | - | | S6-#2a | Required | capability 의존 규칙이 6곳(CDV, DSR, `RedisActivationValidator`, ORBRV, `MasterSwitch`, endpoint)에 흩어짐 (= L-6) | 해당 없음(코드 삭제) | `CS:237`(DSR), `CS:241`(ORBRV), `CS:248`(`MasterSwitch`), `CS:249`(CDV·endpoint), `CS:252`(RAV). capability 의존은 build 줄로 표현(`src/app-bootstrap/build.gradle:139-153`) | - | - | -| S6-#2b | Required | `ca-skeleton.outbox.relay-enabled` 없을 때 기본값 해석이 여전히 갈림 | 남음 | 모듈 yml `false`(`src/adapter/outbound/persistence-jpa/src/main/resources/config/module-defaults/persistence-jpa.yml:189`) vs `matchIfMissing = true`(`BS/autoconfigure/outbox/OutboxConfig.java:69-72`) vs null이면 `true`(`BS/autoconfigure/outbox/OutboxSettings.java:34-36`). yml이 항상 먼저 채워 실제 동작은 false | W2 | relay 조립을 `composition:*` 모듈로 옮길 때(소유자 결정) 기본값을 `false` 하나로: `matchIfMissing` 삭제, `OutboxSettings` null 기본값을 `false`로 | +| S6-#2b | Required | `ca-skeleton.outbox.relay-enabled` 없을 때 기본값 해석이 여전히 갈림 | 완료 | Wave 1–2 P1 (fcddab7e·Wave 2 커밋): 기본값 불일치만 수정(조립 위치 이동은 X1-#1i, Wave 3 3-C). `OutboxSettingsTest.bindsAllSixDefaultsWhenFieldsAreNull` FAIL("Expecting value to be false but was true") → PASS, `OutboxConfigTest.withoutTheRelayKeyTheRelaySchedulerIsNotAssembled` FAIL(scheduler 조립됨) → PASS. `matchIfMissing` 삭제(`src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/outbox/OutboxConfig.java:69`), null 기본값 false(`OutboxSettings.java:37`), `src/app-bootstrap/README.md` 문구 | - | relay 조립을 `composition:*` 모듈로 옮길 때(소유자 결정) 기본값을 `false` 하나로: `matchIfMissing` 삭제, `OutboxSettings` null 기본값을 `false`로 | | S6-#2c | Required | Redis 역할 표 2벌, bootstrap이 Redis 역할별 prod secret 규칙을 앎 | 남음 | `RedisCorrectnessRoles.java:32-37`(redis-runtime) vs `BS/runtime/SecretSourceValidator.java:137-158`(prefix 분기) + 모듈 키 사본 `REDIS_ENABLED_PROPERTY`(`:31`), secret 목록 `:38-48` | W3 | Redis secret 요구 판정을 cache-redis 모듈로 옮기고 `RedisCorrectnessRoles` 표에서 파생; `SecretSourceValidator`는 모듈이 기여한 필요 secret 목록만 검사 | | S6-#2d | Required | `capabilities.idempotency.provider` 기본값이 `disabled`/`jdbc`로 갈림 | 완료 | 모두 `disabled`: `BS/runtime/SecretSourceValidator.java:151`, `BS/autoconfigure/idempotency/IdempotencyProviderSelectionConfig.java:34`, `SP/bootstrap/idempotency/SampleIdempotencyConfig.java:34`; `jdbc` 값 main 0건, `6d27356e` | - | - | | S6-#3a | Required | startup validator가 3 lifecycle·여러 패키지에 흩어짐, `StartupRule` 목록 없음 | 남음 | 19 → 16개: bootstrap 7(`BS/runtime/*Validator` 5, `OutboxCanonicalTransportRequirementValidator`, `TracingSamplingEnvironmentPostProcessor`), persistence-jpa 8(`JS/*Validator` 7, `JpaActivationEnvironmentPostProcessor`), cache-redis 1(`RedisReadinessGroupPostProcessor`). EPP 4, `InitializingBean` 1, `SmartInitializingSingleton` 11. `StartupRule` 타입 없음 | W3 | 모듈마다 `StartupRule { List violations(Environment) }` 목록 + runner 1개; bean이 필요한 검사만 bean으로 | -| S6-#3b | Required | OSIV 검사 2벌, 뒤 검사의 local 예외는 죽은 코드 | 남음 | `JS/OpenInViewSafetyValidator.java:26-38`(모든 profile 거부) vs `JS/JpaDangerousConfigurationGuard.java:51-52`(local-convenience 허용). 둘 다 무조건 등록(`JS/JpaStartupAutoConfiguration.java:71-74,117-127`) | W2 | 하나로: local 예외를 정책으로 쓸지 정해 `OpenInViewSafetyValidator`를 삭제하거나 guard의 OSIV 분기를 삭제 | +| S6-#3b | Required | OSIV 검사 2벌, 뒤 검사의 local 예외는 죽은 코드 | 완료 | Wave 1–2 P9 (fcddab7e·Wave 2 커밋): 행동 보존 정리(FAIL→PASS 대상 아님): `OpenInViewSafetyValidator`(모든 profile 거부)를 정본으로 두고 `JpaDangerousConfigurationGuard`의 OSIV 분기·`OPEN_IN_VIEW_KEY` 삭제(`.../startup/JpaDangerousConfigurationGuard.java`), `JpaPlatformReport`는 validator 상수 사용. `OpenInViewSafetyValidatorTest.openInViewTrueFailsStartupUnderALocalConvenienceProfileToo` 추가(수정 전후 모두 PASS = guard의 local 예외가 죽은 코드였다는 증거). guard 테스트는 ddl-auto만 검사하도록 재작성. 학습 문서 `docs/study/postgresql-jpa-walkthrough.ko.md` 표 갱신 | - | 하나로: local 예외를 정책으로 쓸지 정해 `OpenInViewSafetyValidator`를 삭제하거나 guard의 OSIV 분기를 삭제 | | S6-#3c | Required | ddl-auto 검사 2벌 | 남음 | `JS/JpaSchemaSafetyValidator.java:28-50`(prod) vs `JS/JpaDangerousConfigurationGuard.java:62-65`(non-local, prod 포함) | W3 | guard 한 곳으로 합치고 `JpaSchemaSafetyValidator` 삭제 | | S6-#3d | Required | `isProdActive()` 5곳 복사 | 남음 | `JS/FlywayProdSafetyValidator.java:57`, `JS/JpaSchemaSafetyValidator.java:51`, `JS/PersistenceVendorProdSafetyValidator.java:81`, `JS/PostgreSqlTransportSecurityValidator.java:86`, `BS/runtime/SecretSourceValidator.java:175`. 본문은 모두 `RuntimeProfileSnapshot.isProduction()` 1줄 위임 | W3 | 1줄 wrapper 삭제하고 호출부에서 직접 호출(S6-#3a와 함께) | | S6-#3e | Required | vocabulary 패키지 `runtime/startup/`에 guard 3개 | 완료 | bootstrap `BS/runtime/startup/`에는 `StartupFailureExceptionReporter`만. 어휘는 `SST/`, Flyway·RequiredEnvironment 검사는 `JS/`로 이동, `6d27356e` | - | - | @@ -953,7 +965,7 @@ | S6-#4 | Required | root가 넓게 scan한 뒤 다른 leaf 패키지를 regex로 제외 | 완료 | `BS/CaSkeletonApplication.java` 전체가 `@SpringBootApplication` + bootstrap 패키지 5개 `@ConfigurationPropertiesScan`. regex 삭제(`CS:250`), web은 자기 imports로 공개(`src/adapter/inbound/web/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports:1`), `6d27356e` | - | - | | S6-#5 | Required | fileserver가 build에서 빠졌는데 스위치·설정이 root에 남음 | 완료 | `dependencyPolicy` 없음, 한 줄 선택(`src/app-bootstrap/build.gradle:152`), 설정은 모듈 소유(`CS:37`, `CS:234`), `MasterSwitch.FILESERVER*` 삭제(`CS:78`), composition 자체 imports(`src/composition/fileserver-platform/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`), `6d27356e` | - | - | | S6-#6a | Required | 멱등성 설정 binder 3개·yml 2개, PG provider 하드코딩 (= X1-#2) | 완료 | settings record 하나 `IdempotencySettings`(`BS/autoconfigure/idempotency/IdempotencySettings.java:24-34`, prefix `ca-skeleton.capabilities.idempotency`), `config/idempotency.yml`·`IdempotencyProviderSettings`·`PostgreSqlIdempotencyProviderConfig` 삭제(`CS:228`), `APP_IDEMPOTENCY_TTL` 한 키(`src/app-bootstrap/src/main/resources/config/capabilities.yml:14`) | - | - | -| S6-#6b | Required | `APP_RATE_LIMIT_DEFAULT_POLICY_ID`가 두 키에 바인딩 | 남음 | `src/adapter/outbound/cache-redis/src/main/resources/config/module-defaults/cache-redis.yml:18`(`app.rate-limit.default-policy-id`)와 `:65`(`ca-skeleton.capabilities.rate-limit.default-policy-id`) | W2 | 읽는 쪽 하나만 남기고 다른 키 삭제(sample의 `ca-skeleton.rate-limit.*`는 1차 L-11) | +| S6-#6b | Required | `APP_RATE_LIMIT_DEFAULT_POLICY_ID`가 두 키에 바인딩 | 완료 | Wave 1–2 P6 (fcddab7e·Wave 2 커밋): 두 키 모두 읽히고 있었다(web `EdgeRateLimitTransportSettings`가 `app.rate-limit.*`, cache-redis `RedisRateLimitConfig`가 `ca-skeleton.capabilities.rate-limit.default-policy-id`). 소유자 결정 16(`app.*` 통일)에 맞춰 `app.rate-limit.default-policy-id` 하나만 남김: `cache-redis.yml:65` 줄과 `RedisCapabilitySettings.RateLimit.defaultPolicyId` 삭제, `RedisRateLimitConfig.java:34,60`이 `app.rate-limit.default-policy-id`로 검증. env 키 `APP_RATE_LIMIT_DEFAULT_POLICY_ID`는 그대로(`env-keys.yaml`·`.env.example` 변경 없음). `RedisCapabilityCompositionTest.aDefaultPolicyTheLimiterDoesNotHaveIsRefusedAtStartup` FAIL(`Expecting actual not to be null`)→PASS | - | 읽는 쪽 하나만 남기고 다른 키 삭제(sample의 `ca-skeleton.rate-limit.*`는 1차 L-11) | | S6-#7 | Required | sample이 bootstrap 인프라를 복사, 이미 갈라짐 | 남음 | `SP/bootstrap/{tracing,idempotency,settings,logging,metrics,context,management}` 525줄. `SampleTracingSampleRateResolver.java:23` `"staging" -> 0.10`, `SampleIdempotencyConfig.java:15` "stand-in", `SamplePseudonymizationConfig.java:12` "Sample-local copy" | W3 | 소유자 결정대로 멱등성 executor·outbox relay 조립을 `composition:*` 모듈로 옮겨 두 root가 함께 쓰고, tracing·logging·metrics·context·management는 공용 library leaf로(registry edge 추가), staging 분기 삭제 | | S6-#8 | Required | sample root가 다른 leaf 패키지를 넓게 scan | 남음 | `SP/SamplePortfolioApplication.java:31-60`: `@ComponentScan`·`@ConfigurationPropertiesScan`에 `adapter.inbound.web`, `adapter.outbound.identifier`, `adapter.outbound.objectstorage`, `application`, `domain`, `shared`. JPA만 auto-config로 바뀜 | W3 | scan을 `dev.caskeleton.sample`로 좁히고 web·identifier·objectstorage는 각 leaf auto-config로 받기(보안 설정 2개는 exclude/property로 끔) | | S6-#9 | Required | sample `application.yml` 중 읽는 코드 없는 블록 | 남음 | 326줄 중 약 101줄: `src/sample-portfolio/src/main/resources/application.yml:150-177`(capabilities.cache), `:180-181`(bootstrap), `:210-226`(logging), `:255-279`(app.cache.redis), `:280-283`(messaging), `:284-288`(notification), `:289-308`(outbound.http). sample classpath에 해당 binder 없음(`src/sample-portfolio/build.gradle:48-83`) | W5 | 해당 블록 삭제 | @@ -963,7 +975,7 @@ | S6-#10d | Consider | `WorkLogSortField`(domain)가 HTTP 이름과 persistence 이름을 같이 앎 | 남음 | `SP/domain/worklog/WorkLogSortField.java:11-23`(`property` 하나로 `fromRequest` 매칭) | W3 | 요청 이름 매핑은 web mapper로, persistence 이름은 persistence mapper로; domain enum은 논리 필드만 | | S6-#10e | Consider | sample `CLAUDE.md` 경로 틀림, WorkLog만 설명 | 남음 | `src/sample-portfolio/CLAUDE.md:17-22`: `adapter/web`, `adapter/persistence`, `adapter/identifier`(실제 `adapter/inbound/web`, `adapter/outbound/persistence`, `adapter/outbound/identifier`) | W5 | 경로 수정, poster-image 슬라이스 한 줄 추가 | | S6-#11a | Consider | 컨트롤러 `toId()` 4벌, sort 파싱 2벌 | 남음 | `toId`: `WorkLogController.java:239`, `PosterController.java:161`, `LegacyPosterImageController.java:49`, `PosterImagePublicationController.java:110`; sort: `WorkLogController.java:99-113`, `PosterController.java:91-105` (모두 `SP/adapter/inbound/web/controller/`) | W3 | web 어댑터 helper 하나(id 파싱, `SortParam` + enum `fromRequest` 공통 처리) | -| S6-#11b | Consider | If-Match를 컨트롤러가 update 전에 get use case로 읽어 비교(트랜잭션 밖) | 남음 | `SP/adapter/inbound/web/controller/WorkLogController.java:162,209-218`; `SP/application/command/UpdateWorkLogCommand.java`에 `expectedVersion` 없음 | W2 | `UpdateWorkLogCommand.expectedVersion` 추가, 비교를 update use case 트랜잭션 안으로 | +| S6-#11b | Consider | If-Match를 컨트롤러가 update 전에 get use case로 읽어 비교(트랜잭션 밖) | 완료 | Wave 1–2 P10 (fcddab7e·Wave 2 커밋): `UpdateWorkLogCommand.expectedVersion`(`OptionalLong`, `sample-portfolio/.../application/command/UpdateWorkLogCommand.java:25`), 비교는 `UpdateWorkLogUseCase` 쓰기 트랜잭션 안(`UpdateWorkLogUseCase.java:43`, 불일치 → 새 `WorkLogVersionMismatchException` → `DomainExceptionHandler`가 412 `PRECONDITION_FAILED`). 컨트롤러는 헤더만 해석(`WorkLogController.java:211`). `WorkLogControllerWireTest.patchWithIfMatchDoesNotReadTheWorkLogOutsideTheUpdate` FAIL(`NoInteractionsWanted … GetWorkLogUseCase`)→PASS, `WorkLogUseCasesTest.staleExpectedVersionIsRefusedInsideTheUpdate`·`currentExpectedVersionAppliesTheUpdate`, `patchHandsTheIfMatchVersionToTheUpdateUseCase`, `patchWithStaleIfMatchReturns412`(유스케이스 예외 경로로 변경) PASS. 동작 변화: 여러 태그를 나열한 `If-Match`(예: `W/"1", W/"2"`)는 이제 읽지 않고 412(`patchWithAListIfMatchIsRefusedAs412`) — 이 리소스는 validator 하나만 내보냄 | - | `UpdateWorkLogCommand.expectedVersion` 추가, 비교를 update use case 트랜잭션 안으로 | | S6-#11c | Consider | sample 테스트가 `TransactionPort` fake를 각자 작성 (= X1-#3 일부) | 완료 | application-core testFixtures `DirectTransactionPort`(`src/application-core/src/testFixtures/java/dev/caskeleton/application/transaction/testkit/DirectTransactionPort.java`), sample 테스트의 인라인 fake 0건, `6d27356e` | - | - | | S6-#12 | Consider | JPA 정책 클래스 겸용, 주입처 없는 bean, 테스트만 쓰는 플래그 | 완료 | `JpaPlatformAutoConfiguration` 삭제·`JpaStartupAutoConfiguration`으로 합침(`CS:238`), `app.jpa-platform.addons-enabled` 삭제(`CS:193`), `jpaDataSourceProfileValidator`가 `jpaResolvedDataSourceCheck`에 주입됨(`JS/JpaStartupAutoConfiguration.java:100,109-110`), `6d27356e` | - | - | | S6-#13 | Consider | 역할 없는 startup 예외 subclass 4개 | 남음 | `SST/{MigrationFailed,ProfileMismatch,RequiredAdapterDisabled,StartupValidation}Exception.java` — bootstrap에서 support로 옮기기만 했고 본문은 `StartupErrorCode`를 부모에 넘기기만 | W3 | `StartupFailureException` 하나 + 테스트는 `errorCode()` 단언; 생성은 `StartupFailures` factory만 | @@ -980,7 +992,7 @@ | S6-G3 | 권고 | capability 하나 켜는 표면이 큼(outbox 스위치 5개, yml 19개) | 완료 | bootstrap yml 19개 1,388줄 → 9개 655줄. Outbox+relay = build 줄 2개 + `APP_OUTBOX_ENABLED`·`APP_OUTBOX_RELAY_ENABLED`(`CS:35`), 검증 클래스 1개(`OutboxCanonicalTransportRequirementValidator`); Redis 연결 env는 `src/adapter/outbound/cache-redis/README.md:50`에 문서화 | - | - | | S6-lead-1 | 권고 | gRPC 서버 스택 2개, 둘 다 조립 안 됨 (= X1-#10) | 완료 | `adapter:inbound:grpc`는 자기 imports(`GrpcServerConfig`)로 한 줄 선택(`CS:42`), 플랫폼 `grpc:*`는 별도 build `src/optional-platforms`(`CS:41`). 두 스택 공존은 X1-#10에서 의도로 수용 | - | - | | S6-lead-2 | 권고 | 인라인 `TransactionPort` fake가 저장소 전체에 (= X1-#3) | 남음 | 인라인 fake 24 → 10개 파일: application-core 4(`TransactionPortTest` 포함), application-notification 4, `application-fileserver/.../testkit/DirectTransactions.java`, `composition/fileserver-platform/.../FileserverAssemblyFixture.java`. `DirectTransactionPort` 사용 12개 파일 | W4 | 계약 자체를 검증하는 `TransactionPortTest` 외 9개를 `DirectTransactionPort`로 교체 | -| S6-lead-3 | 권고 | 복사용 예제 `CreateWorkLogUseCase`가 `LegacyOutboxAppendPort` 사용 (= X1-#1 append 포트) | 남음 | `SP/application/worklog/CreateWorkLogUseCase.java:7`; canonical `OutboxAppendPort`(`src/application-core/src/main/java/dev/caskeleton/application/outbox/OutboxAppendPort.java:13`) 존재, legacy 포트 Javadoc은 "cutover 창 동안만"(`LegacyOutboxAppendPort.java:3-9`) | W2 | 예제를 `OutboxAppendPort` + `ValidatedIntegrationEvent`로 옮기고 MSG-015 cutover 후 legacy 포트 삭제 | +| S6-lead-3 | 권고 | 복사용 예제 `CreateWorkLogUseCase`가 `LegacyOutboxAppendPort` 사용 (= X1-#1 append 포트) | 남음 | `SP/application/worklog/CreateWorkLogUseCase.java:7`; canonical `OutboxAppendPort`(`src/application-core/src/main/java/dev/caskeleton/application/outbox/OutboxAppendPort.java:13`) 존재, legacy 포트 Javadoc은 "cutover 창 동안만"(`LegacyOutboxAppendPort.java:3-9`)
Wave 1–2 P1: 미완 — 이유: sample을 `OutboxAppendPort`로 옮기려면 `ValidatedIntegrationEvent`를 만들 encoder가 있어야 하는데 템플릿에 없다(`IntegrationEventEncoderPort` 구현 0). 결정 7(템플릿 JSON encoder 제공 + legacy 포트 삭제)이 Wave 3 3-C 작업. sample의 legacy 포트 사용처 3곳(`CreateWorkLogUseCase`, `PosterEventPublisher`, `PosterImagePublicationEventPublisher`) | W2 | 예제를 `OutboxAppendPort` + `ValidatedIntegrationEvent`로 옮기고 MSG-015 cutover 후 legacy 포트 삭제 | | S6-lead-4 | 권고 | `CS` WIRED=yes vs `dependencyPolicy` 모순, `MasterSwitch`가 없는 capability 나열 | 해당 없음(코드 삭제) | `dependencyPolicy`·`MasterSwitch` 삭제(`CS:248`), WIRED 정의를 "선택하면 조립됨"으로 재정의(`CS:11`, `CS:37`) | - | - | | S6-lead-5 | 권고 | `DefaultUploadApplicationService` 생성자 14개 | 남음 | `src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/upload/DefaultUploadApplicationService.java` 생성자 인자 14개, 조립 `FileserverUploadServiceConfiguration.java:88` | W3 | 정책 3개(access·filename·upload)와 저장소 2개를 record로 묶거나 업로드 단계별 서비스로 분해 | | S7-#1a | Required | 선택 불가·SDK 없는 messaging leaf(experimental 4, rabbit 2)와 Debezium | 해당 없음(코드 삭제) | `CS:124-130` | - | - | @@ -988,7 +1000,7 @@ | S7-#1c | Required | starter가 쓰지 않는 cloudevents·claim-check edge, 바인딩만 되는 `Experimental`·`Bridge` 설정 | 완료 | `CS:131`, `CS:133`; `src/messaging/messaging-spring-boot-starter/build.gradle:20-37`에 두 leaf 없음, `6d27356e` | - | - | | S7-#2 | Required | consume 계약 3개, 조립 0 | 남음 | `MessageHandler.java:14`(main 참조 0), `DefaultDeliveryProcessor.java:40-47`(참조 0), `IdempotentMessageHandler.java:21`; `KafkaConsumerRegistrar`(645줄)·`KafkaBatchConsumerRegistrar`(146줄) main 참조 0, 자동 조립 transport는 발행 전용(`KafkaMessagingTransport.java:89` `KAFKA_CONSUMER_NOT_CONFIGURED`) | W3 | 결정(2026-09-25): Kafka 소비 지원 — `MessageHandler` 하나, starter-kafka가 handler bean이 있으면 consumer 조립, 실제 Kafka lane 테스트 | | S7-#3 | Required | grpc 18 leaf를 9 leaf로 | 남음 | `MJ`에 grpc leaf 18개 그대로. io.grpc import main 파일은 `grpc-policy` 4 + `grpc-server` 1(+testkit 6); `src/grpc/grpc-client/build.gradle:12-13` io.grpc api인데 import 0; 미사용 edge `src/grpc/grpc-codegen/build.gradle:13`, `src/grpc-advanced/grpc-advanced-edition/build.gradle:9-11` | W3 | policy+server+client+discovery+admin → `grpc-runtime`, proto-contract+codegen → `grpc-contract`, advanced 5개 → `grpc-advanced`, 미사용 edge 삭제 | -| S7-#4 | Required | gate·guard·catalog 같은 governance를 운영 코드로 (≈ N-9) | 남음 | 전부 존재: `GrpcStableModuleCatalog.java`(79), `GrpcStableBuildInvariant.java`(53), 상수 반환 gate 7종(`GrpcKotlinCompatibilityGate`, `GrpcWebCompatibilityGate`, `GrpcServletStartupValidator`, `GrpcEdition2026Guard`, `GrpcEdition2024Gate`, `GrpcResolverSafetyPolicy`의 상수 메서드, `GrpcXdsStartupGuard`), `GrpcRawApiImportRule`(108)·`GrpcApplicationBoundaryRules`(92), `GrpcAdvancedInfrastructureTestkit`(87). `git diff 208077fd 6d27356e --stat -- src/grpc*`은 Wave 1 1-10 파일만 | W3 | 상수 gate·catalog·invariant·testkit 삭제, import 규칙은 ArchUnit 테스트로 | +| S7-#4 | Required | gate·guard·catalog 같은 governance를 운영 코드로 (≈ N-9) | 완료 | Wave 1–2 P5 (fcddab7e·Wave 2 커밋): 삭제 커밋 `9b296c7c`(P5 D). 상수 gate·guard·catalog·invariant·testkit·문자열 ArchUnit 흉내 삭제(아래 「제거된 코드」). 전부 main 호출자 0이었다. `GrpcRawApiImportRule`·`GrpcApplicationBoundaryRules`는 자기 테스트의 합성 입력만 검사하고 저장소 코드를 검사하지 않아서 테스트로 옮기지 않고 삭제했다(inbound→outbound 규칙은 app-bootstrap ArchUnit `INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS`가 이미 검사). `GrpcResolverSafetyPolicy`는 상수 메서드 2개만 삭제. starter의 항상 통과하던 advanced 격리 검사도 함께 제거 `src/grpc/grpc-spring-boot-starter/src/main/java/dev/caskeleton/grpc/boot/GrpcPlatformStartupValidator.java:41`. 문서 갱신: `src/grpc/CLAUDE.md`, `src/grpc-advanced/CLAUDE.md`, `docs/runbooks/grpc-advanced-capabilities.md`, `docs/compatibility/grpc-advanced-support-matrix.md` | - | 상수 gate·catalog·invariant·testkit 삭제, import 규칙은 ArchUnit 테스트로 | | S7-#5a | Required | `messaging-outbox-jdbc-postgresql`의 Debezium 4개 | 해당 없음(코드 삭제) | `CS:130` | - | - | | S7-#5b | Required | 한 leaf가 relay 로직·PG repository·admin journal을 함께 가짐 | 남음 | `src/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/`: relay 7클래스 877줄, `JdbcOutboxRepository` 721줄, `JdbcAdminOperationJournal` 326줄; Spring JDBC import 파일 2개. inbox는 6개 중 5개가 stdlib | W3 | `messaging-reliability`(stdlib relay·inbox 로직) + `messaging-reliability-jdbc-postgresql`(Jdbc 3종)으로 재분할 | | S7-#6a | Required | `PublishResult` 7인자 생성자 직접 호출 | 남음 | 11파일 28회 → 5파일 8회(`KafkaMessagingTransport` 1, `KafkaPublishFailureClassifier` 2, `KafkaPublishMapper` 1, `DefaultMessagePublisher` 2, `MS/PublishResults.java` 2). `PublishResult.java:30`에 정적 factory 없음 | W3 | `PublishResult.rejected/ambiguous/confirmed` 정적 factory 추가 후 8곳 교체 | @@ -1011,7 +1023,7 @@ | S7-#16c | Nit | `KafkaConsumerRegistrar.dispatch` 긴 메서드 | 남음 | `KafkaConsumerRegistrar.java:264-354`(약 90줄) | W5 | S7-#2 결정 후: 유지면 분해, 삭제면 소멸 | | S7-lead-1 | 권고 | outbox relay 3개 (= X1-#1) | 완료 | V2 relay 삭제(`CS:175`), 앱 relay는 `PublishPendingOutboxEventsUseCase` 하나(`BS/autoconfigure/outbox/OutboxConfig.java:86`). messaging `OutboxRelay`는 vendored 제품 기능으로 `@ConditionalOnBean(OutboxRepository)`(`MS/MessagingReliabilityAutoConfiguration.java:81`)이고 main에 `JdbcOutboxRepository` 생성 0이라 앱 조립에 들어오지 않음, `6d27356e` | - | - | | S7-lead-2 | 권고 | 멱등성 저장소 3개(앱, grpc ledger, messaging inbox) (= X1-#2) | 남음 | 셋 다 존재. messaging inbox는 소비자 dedup이고 family 규칙상 앱 계약 사용 불가(`CLAUDE.md:65`); grpc ledger도 앱 edge 없음(`MJ:606`, allowed `grpc-core-api`만) → 분리는 구조상 의도. 그러나 root `CLAUDE.md:59-67` family 표에 `grpc:*`·`grpc-advanced:*` 행이 없어 이 예외가 문서에 없음 | W5 | family 표에 gRPC 플랫폼을 messaging과 같은 vendored 예외(자체 ledger, optional build)로 한 줄 추가 | -| S7-lead-3 | 권고 | Kafka producer 경로 2개 (= X1 표 Kafka producer) | 남음 | R0 `LegacyKafkaMessagingRootAutoConfiguration`·`KafkaSender`·`KafkaSenderAutoConfiguration`(`src/adapter/outbound/messaging-kafka/src/main/java/dev/caskeleton/adapter/outbound/messaging/kafka/`) vs 플랫폼 `KafkaMessagingTransport`; `CS:32` "legacy `KafkaSender` seam and the vendored platform" | W2 | MSG-015 cutover(S6-lead-3과 함께) 후 R0 `KafkaSender` 경로 삭제 | +| S7-lead-3 | 권고 | Kafka producer 경로 2개 (= X1 표 Kafka producer) | 남음 | R0 `LegacyKafkaMessagingRootAutoConfiguration`·`KafkaSender`·`KafkaSenderAutoConfiguration`(`src/adapter/outbound/messaging-kafka/src/main/java/dev/caskeleton/adapter/outbound/messaging/kafka/`) vs 플랫폼 `KafkaMessagingTransport`; `CS:32` "legacy `KafkaSender` seam and the vendored platform"
Wave 1–2 P1: 미완 — 이유: = X1 표 Kafka producer(legacy `KafkaSender` R0 경로). 결정 7로 Wave 3 3-C에서 경로째 삭제. 이번 묶음 지시대로 legacy seam은 손대지 않음 | W2 | MSG-015 cutover(S6-lead-3과 함께) 후 R0 `KafkaSender` 경로 삭제 | | S7-lead-4 | 권고 | lease/claimBatch 구현 여러 벌 (= X1-#6) | 남음 | persistence-jpa 안에 owner+token lease 2벌: outbox(`OutboxStoreAdapter.java:79-90`, `OutboxEventJpaRepository.java:34,47`)와 알림(`RecipientDeliveryJpaRepository.java:85-175`, `JpaRecipientLeaseStore`). outbox는 계약 kit `OutboxLeaseFencingContract`(application-core testFixtures)가 있으나 `RecipientLeaseStorePort`는 PG 통합 테스트 1개뿐. messaging `OutboxRepository.claimBatch`는 vendored라 별개 | W4 | SQL은 테이블별 유지(X1-#6), application-notification testFixtures에 `RecipientLeaseFencingContract`를 만들어 fake와 JPA store가 함께 상속 | | S7-lead-5 | 권고 | messaging 기본 off 처리 두 곳(sentinel vs starter switch) | 해당 없음(코드 삭제) | `DisabledMessagingSentinelAutoConfiguration` 삭제(`CS:240`), 끄는 키는 모듈 `app.messaging.enabled` 하나(`CS:32`) | - | - | @@ -1029,30 +1041,30 @@ | ID | 심각도 | 요약 | 상태 | 근거 | Wave | 수정 방향 | |---|---|---|---|---|---|---| -| NEW-1a | Consider | compose smoke가 lane이 실제로 켠 기능·DB 벤더를 확인하지 않는다. `expectedSwitchesOn`·`expectedPersistenceVendor`를 읽는 코드가 없다(스크립트·정적 검사기 모두). | 남음 | `scripts/run-compose-runtime-smoke.sh:414-427`은 `/actuator/health`만 폴링한다. 예전 버전은 `/actuator/adapteractivation`의 `switches`·`persistenceVendor`를 비교했는데, 그 endpoint(`AdapterActivationEndpoint`·`AdapterActivationReport`·`MasterSwitchEnvironmentPostProcessor`)가 6d27356e에서 삭제됐다(`git diff 208077fd 6d27356e -- scripts/run-compose-runtime-smoke.sh`). `scripts/verify-compose-profile-contracts.sh:43-56`도 이 두 필드를 읽지 않는다. 필드 값은 아직 유효한 property 키다: `ca-skeleton.persistence-jpa.enabled`(`PersistenceJpaAutoConfiguration.java:17`), `app.messaging.enabled`(`MessagingPlatformRootAutoConfiguration.java:23`), `backend.graphql.enabled`(`GraphQlRootAutoConfiguration.java:12`) 등 8개 모두 main 코드에 있다. 하지만 이제 이 키를 "앱이 보고한 값"으로 노출하는 곳이 없어서 필드는 읽히지 않는 문서다. `src/config/runtime/compose-profile-contracts.json:741`의 `$activationComment`는 "Redis·fileserver·httpclient는 app-bootstrap에 포함"이라고 적혀 있는데, capability 포장 이후로는 틀린 설명이다. actuator 노출 목록은 `health,prometheus,info,loggers`다(`src/app-bootstrap/src/main/resources/config/observability.yml:34`). | W2 | 결정(2026-09-25): smoke가 lane이 켠 capability·DB 벤더를 health component(또는 info)로 확인, 계약 필드를 그 값에 맞춰 재정의 | +| NEW-1a | Consider | compose smoke가 lane이 실제로 켠 기능·DB 벤더를 확인하지 않는다. `expectedSwitchesOn`·`expectedPersistenceVendor`를 읽는 코드가 없다(스크립트·정적 검사기 모두). | 완료 | Wave 1–2 P13 (fcddab7e·Wave 2 커밋): 방식: Spring Boot `management.info.env.enabled=true`(`src/app-bootstrap/src/main/resources/config/observability.yml:86-94`, `info.*` 트리만 노출, env 전체 아님)와, 각 capability 모듈이 자기 설정 파일에 `info.capabilities..enabled: ${<스위치 키>:}`을 싣는다. JPA는 `vendor: ${ca-skeleton.persistence.vendor:postgresql}`도 싣는다(vendor=postgresql이면 `JpaDataSourceProfileValidator`가 실제 DB가 PostgreSQL인지 기동 때 확인하므로 선택자=실제 DB). Java 코드 추가 없음, capability 모듈 8개의 yml만 추가: `persistence-jpa.yml`, `persistence-mongo/config/mongo.yml`, `messaging-kafka/.../messaging.yml`, `notification-platform/.../notification.yml`, `graphql/config/graphql.yml`, `cache-redis.yml`, `fileserver-platform/.../fileserver.yml`, `httpclient.yml`. 계약 재정의: `expectedSwitchesOn`(property 키) → `expectedCapabilitiesOn`(info 이름), 최상위 `capabilities` 카탈로그(8개) 추가, `$activationComment`/`$vendorComment` 갱신(`src/config/runtime/compose-profile-contracts.json:741-752`). smoke: `scripts/run-compose-runtime-smoke.sh:434-468` — health 응답 뒤 `/actuator/info`를 받아 ①보고된 capability 이름 집합 = 카탈로그(모듈 누락·info 꺼짐 검출, all-off lane이 빈 목록끼리 비교하는 헛검사가 안 되게) ②enabled=true 집합 = `expectedCapabilitiesOn` ③JPA가 켜졌으면 `vendor`, 아니면 `none` = `expectedPersistenceVendor`. 정적 검사 `scripts/verify-compose-profile-contracts.sh:133-146`(check 6): 카탈로그 밖 이름, JPA 켜짐/꺼짐과 맞지 않는 vendor를 거부. 실제 실행(Docker, qualification 이미지): 재현 — off-local이 persistence-jpa를 기대하도록 바꾼 계약에서 HEAD의 smoke는 `all 1 blocking lanes passed`(결함), 새 smoke는 `off-local: the application reports [] on, the contract expects [persistence-jpa]`로 FAIL. 실제 계약: `--lane off-local` passed(8개 모두 `enabled:"false"`), `--lane local-jpa` passed(`persistence-jpa {enabled:"true",vendor:"postgresql"}`), `--lane off-prod` passed. `--lane local-redis`는 info 검사(`redis enabled:"true"`)를 통과한 뒤 기존 3c 기동 로그 검사에서 실패(P13-new-2). 정적 검사: 실제 계약 18 lane 전부 match, 깨진 사본(카탈로그 밖 이름·JPA 켜짐+vendor none)은 두 lane FAIL. 한계: objectstorage·websocket·gRPC는 모든 lane에서 꺼지고 info에 보고하지 않는다(예전 activation endpoint도 보고하지 않던 셋). `ConfigurationNamespaceContractTest`의 허용 root에 프레임워크 namespace `info` 추가(`app-bootstrap/src/test/.../ConfigurationNamespaceContractTest.java:57-74`). | - | 결정(2026-09-25): smoke가 lane이 켠 capability·DB 벤더를 health component(또는 info)로 확인, 계약 필드를 그 값에 맞춰 재정의 | | NEW-1b | Required | 새 CI 잡이 GitHub에서 한 번도 돌지 않았다. 18개 lane을 실제로 돌린 증거가 없다. | 남음 | 브랜치에 upstream이 없고(`git status -sb` → `## refactor/review-followup`), `6d27356e`를 포함한 원격 브랜치도 없다(`git branch -r --contains` 결과 비어 있음). 새로 추가된 잡은 `.github/workflows/build-logic.yml:30-41`(included build 테스트), `.github/workflows/integration-main.yml:64`(`main-check`), `:85`(`configuration-cache`), `:130`(`jpa-candidate-evidence`)이다. compose 잡은 `integration-main.yml:374-387`에 있고 `push: main`·nightly·dispatch에서만 돈다(`:33-40`). 계약 lane은 18개다(`jq '.lanes\|length'`). lane은 `COMPOSITION=qualification` 이미지로 돈다(`run-compose-runtime-smoke.sh:34`, `src/Dockerfile:70-77`). | W4 | 로컬에서 돌리려면 docker, docker compose 2.24.4 이상(`compose-profile-contracts.json`의 `minimumComposeVersion`), jq, openssl(TLS lane의 인증서 생성, `:183-211`)이 필요하다. 명령은 `bash scripts/run-compose-runtime-smoke.sh --matrix src/config/runtime/compose-profile-contracts.json`이고, 이미지는 스크립트가 `docker compose build app`으로 만든다(`:366`). 스크립트의 도구 사전 검사(`:75-77`)에 `openssl`을 추가한다. 브랜치를 push해서 `workflow_dispatch`로 `integration-main`·`build-logic`을 한 번 돌리고 그 결과를 증거로 남긴다. | | NEW-2a | Consider | outbox relay 조립이 app-bootstrap에 있다. | 남음 | `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/outbox/OutboxConfig.java:44-120`. 조건: `@AutoConfiguration(afterName=PersistenceJpaAutoConfiguration, MessagingBridgeRootAutoConfiguration)`, `@ConditionalOnProperty(ca-skeleton.outbox.enabled=true)`, `@ConditionalOnBean(OutboxStorePort)`, `@EnableScheduling`. 빈: `outboxCanonicalTransportRequirementValidator`, `outboxRelayScheduler`(`relay-enabled` 기본 true + `@ConditionalOnBean(OutboxMessagePublishPort)`), `outboxRandomGenerator`, `outboxLeaderElection`, `outboxMetrics`. 같은 패키지에 `OutboxSettings`·`OutboxMetrics`·`OutboxRelayScheduler`·`OutboxLeaderElectionToken`·`OutboxCanonicalTransportRequirementValidator`가 있다. 등록은 `src/app-bootstrap/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports:2`. persistence-jpa로 옮기지 못하는 이유는 `AdapterBoundaryArchitectureTest.java:207-227` 때문이다. 이 규칙은 `adapter.outbound.persistence..` 패키지가 `*UseCase`를 참조하는 것을 막는데, `OutboxConfig`는 `PublishPendingOutboxEventsUseCase`를 직접 만든다(:85). | W3 | 새 leaf `:composition:outbox-relay`(패키지 `dev.caskeleton.composition.outbox`)를 만들고 위 6개 클래스와 테스트(`OutboxConfigTest`·`OutboxSettingsTest`·`OutboxRelaySchedulerLoggingTest`·`OutboxCanonicalTransport*Test`)를 옮긴다. 자세한 내용은 아래 메모. | | NEW-2b | Consider | 멱등성 executor 조립이 app-bootstrap에 있고, sample이 검증 없는 복사본을 따로 가진다. | 남음 | `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/idempotency/IdempotencyProviderSelectionConfig.java:28-56`: `@AutoConfiguration`, 빈은 `idempotencyExecutor` 하나다(`@ConditionalOnExpression(provider != disabled)`). store가 정확히 1개가 아니면 기동 실패한다(:39-47). 설정은 `IdempotencySettings.java:24-67`에 있고 lease·TTL 상한과 codec·revision을 검증한다. sample 복사본 `src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/bootstrap/idempotency/SampleIdempotencyConfig.java:21-47`과의 차이는 셋이다. ① `Binder`로 직접 읽어서 상한·양수 검증이 없다(:38-45). ② store를 1개로 가정한다(`IdempotencyStorePort store` 직접 주입). ③ `Clock` 빈과 `@EnableScheduling`을 함께 들고 있다(:22,:27-30). | W3 | 새 leaf `:composition:idempotency`로 `IdempotencyProviderSelectionConfig`·`IdempotencySettings`와 테스트(`IdempotencyProviderCompositionTest`·`IdempotencySettingsTest`)를 옮긴다. sample은 `runtimeOnly project(':composition:idempotency')`를 쓰고 `SampleIdempotencyConfig`에서는 executor 빈을 지운다(Clock·scheduling만 남긴다). modules.json의 `sample-portfolio.allowed_dependencies`에 `composition-idempotency`를 추가한다. | -| NEW-3 | Required | fileserver 보상 트랜잭션의 30초 타임아웃이 사라졌다. 지금은 `inNew` 경로 전체에 타임아웃이 없다. | 남음 | 예전 코드는 `git show 208077fd:src/application-fileserver/.../upload/FileserverCompensationTransaction.java:16`에 `BUDGET = Duration.ofSeconds(30)`을 두고 `:27` `MAINTENANCE_NEW` 정책으로 `SpringPolicyTransactionPort`에 넘겼다. 그 포트가 `definition.setTimeout(...)`을 걸었다(208077fd `SpringPolicyTransactionPort.java:184`, 상한 `persistence.yml` `transaction-timeout: 30s`). 지금은 `src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/upload/DefaultUploadApplicationService.java:155`와 `DefaultFinalizeUploadService.java:321`이 `transactions.inNew(...)`를 그대로 호출한다. `TransactionPort.java:23-78`에는 timeout 옵션이 없다. `SpringTransactionPort.java:83-93` `template()`은 `setTimeout`을 호출하지 않는다. `spring.transaction.default-timeout`도 어디에도 없다(grep 0건). | W2 | 가장 작은 변경은 `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/transaction/SpringTransactionPort.java`의 `requiresNewTemplate`에 `setTimeout(30)`을 거는 것이다(상수 1개). 이러면 보상·outbox·audit용 REQUIRES_NEW의 옛 동작이 돌아온다. 전 트랜잭션에 상한을 원하면 대신 `persistence-jpa.yml` module-defaults에 `spring.transaction.default-timeout: 30s`를 둔다. 테스트는 `SpringTransactionPort` 단위 테스트에서 inNew template의 timeout 값을 단언한다. | +| NEW-3 | Required | fileserver 보상 트랜잭션의 30초 타임아웃이 사라졌다. 지금은 `inNew` 경로 전체에 타임아웃이 없다. | 완료 | Wave 1–2 P4 (fcddab7e·Wave 2 커밋): C-3d와 같은 수정·테스트. `SpringTransactionPort.java:62` | - | 가장 작은 변경은 `src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/transaction/SpringTransactionPort.java`의 `requiresNewTemplate`에 `setTimeout(30)`을 거는 것이다(상수 1개). 이러면 보상·outbox·audit용 REQUIRES_NEW의 옛 동작이 돌아온다. 전 트랜잭션에 상한을 원하면 대신 `persistence-jpa.yml` module-defaults에 `spring.transaction.default-timeout: 30s`를 둔다. 테스트는 `SpringTransactionPort` 단위 테스트에서 inNew template의 timeout 값을 단언한다. | | NEW-4a | Required | Kafka legacy seam producer에 보안 설정이 전혀 없다(항상 PLAINTEXT). | 남음 | `src/adapter/outbound/messaging-kafka/src/main/java/dev/caskeleton/adapter/outbound/messaging/kafka/KafkaSenderAutoConfiguration.java:62-80`: bootstrap·serializer·acks·timeout만 넣는다. `security.protocol`·SASL·SSL 키가 없다. messaging-kafka 모듈을 고르면 `LegacyKafkaMessagingRootAutoConfiguration`(imports 1행)로 항상 켜진다. 반면 platform producer는 `KafkaSecurityConfigurer`를 적용한다(`KafkaMessagingAutoConfiguration.java:234-235`). | W1 | seam producer도 같은 보안 profile을 쓰게 한다. `KafkaMessagingAutoConfiguration.producerSecurity(...)`를 재사용 가능한 static으로 빼거나 `KafkaSecurityConfigurer` 결과를 주입받아 `config.putAll(...)`한다. 보안 profile이 없고 broker가 TLS·auth를 요구하면 기동을 실패시킨다(platform 쪽 `:200-211`과 같은 규칙). 장기적으로는 seam을 platform transport로 합쳐 producer를 하나로 줄인다. | -| NEW-4b | Required | Kafka TLS 자료(truststore/keystore) 설정 키가 없다. `MUTUAL_TLS`를 설정 값으로는 받지만 실제로 동작하지 않는다. | 남음 | `src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaSecurityConfigurer.java:85-90`은 TLS일 때 `ssl.enabled.protocols`·`ssl.endpoint.identification.algorithm`만 넣는다. `:109` `MutualTls`는 `sasl.mechanism=NONE`만 넣고 `ssl.keystore.*`는 넣지 않는다. 그래서 `security.protocol=SSL`인데 client 인증서가 없는 상태가 되어 연결할 때 실패한다. `src/messaging` main에서 `truststore\|keystore` grep 결과는 0건이다. 설정 컴파일러는 `MUTUAL_TLS`를 받는다(`MessagingConfigurationCompiler.java:258`). 동작하지 않는 옵션을 받는 것은 완료 기준 3 위반이다. | W1 | `BrokerSettings`(messaging-spring-boot-starter)에 `trust-store-location/password/type`, `key-store-location/password/type`을 추가하거나 Spring Boot SSL bundle 이름(`ssl-bundle`)을 받는다. `KafkaSecurityConfigurer`가 `ssl.truststore.*`·`ssl.keystore.*`(또는 PEM `ssl.*.certificates`)를 채운다. keystore가 없는 `MUTUAL_TLS`는 컴파일 단계에서 거부한다. 구현하지 않을 거면 `MessagingConfigurationCompiler.java:258`에서 `MUTUAL_TLS`를 뺀다. | -| NEW-4c | Consider | platform producer가 broker 주소를 `spring.kafka.bootstrap-servers`에서만 읽고, 선언된 broker의 `bootstrap-servers`는 검증만 한 뒤 쓰지 않는다. | 남음 | `src/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaMessagingAutoConfiguration.java:155-165`는 `environment.getProperty("spring.kafka.bootstrap-servers")`만 읽는다. `MessagingConfigurationCompiler.java:97-99`는 `app.messaging.brokers..bootstrap-servers`가 비어 있으면 거부하지만, producer는 그 값을 쓰지 않는다. 두 경로를 이어 주는 것은 module-defaults 한 줄뿐이다: `src/adapter/outbound/messaging-kafka/src/main/resources/config/module-defaults/messaging.yml:17,23`에서 둘 다 `${APP_MESSAGING_KAFKA_BROKERS:}`. | W2 | 주소 출처를 하나로 정한다. 추천은 compiled broker(`CompiledMessagingConfiguration`의 kafka broker `bootstrapServers()`)를 쓰고, 없을 때만 `spring.kafka.bootstrap-servers`로 fallback하는 것이다. 둘 다 있는데 값이 다르면 기동을 실패시킨다. 테스트는 `producerConfig(...)`에 두 값을 다르게 주고 결과를 단언한다. | -| NEW-4d | Required | credential rotation이 Kafka producer에 반영되지 않는다. | 남음 | `KafkaMessagingAutoConfiguration.java:140-146`: producer를 기동 때 한 번 만든다. `:234-235`: `Instant.now()` 시점의 credential로 JAAS 문자열을 고정한다. `:250`: transport generation이 `1L`로 고정이다. `KafkaSecurityConfigurer.java:17-21` Javadoc은 "rotation을 가능하게 한다"고 적혀 있지만, 회전 뒤 producer를 다시 만드는 코드가 없다(`messaging-kafka` main에서 rotate grep 0건). 회전 소스는 `MessagingCoreAutoConfiguration.java:184`(runtime registry)다. | W1 | Kafka 방식으로 해결한다. `sasl.client.callback.handler.class`에 `CredentialRuntimeRegistry`를 조회하는 handler를 넣고 JAAS에는 username만 둔다. 이러면 재인증(broker `connections.max.reauth.ms`) 때마다 새 비밀번호를 쓴다. 다른 방법은 registry의 generation 변화에 맞춰 producer를 교체하고 transport generation을 올리는 것이다. Javadoc(:17-21)은 실제 동작에 맞춘다. | -| NEW-5a | Required | Redis ACL 템플릿의 script 계정에 `TIME` 권한이 없다. rate-limit·멱등성 script가 NOPERM으로 실패한다(실제 lane 실패 4건의 주원인). | 남음 | `infra/redis-sdk/acl/application-advanced.acl:1`, `infra/redis-sdk/acl/all-accounts.acl:3`: `-@all` 뒤에 `+time`이 없다(`TIME`은 `@read`·`@write`에 속하지 않는다). script 안에서 `redis.call('TIME')`을 쓰는 곳은 `RateLimitScripts.java:48,76,108`, `IdempotencyScripts.java:41,127`이다. `infra/redis-sdk/acl/README.md`는 `all-accounts.acl`을 "deployment가 로드하는 파일"이라고 적고 있어서, 운영 템플릿도 같이 깨져 있다. 기동 probe도 이 문제를 잡지 못한다. `RedisSemanticScriptAclProbe.java:20`은 `return {1}`만 실행한다. | W1 | 두 ACL 파일의 advanced 계정에 `+time`을 추가한다. `admin-readonly.acl:1`에는 이미 `+time`이 있다. probe script를 `redis.call('TIME')`을 실제로 수행하는 스크립트로 바꿔서 권한이 없으면 기동 때 실패하게 한다. 검증은 `redis-sdk-topology.yml` standalone lane에서 `LiveRedisSemanticPortsTest`로 한다. | -| NEW-5b | Consider | `LiveRedisSemanticPortsTest`의 token-bucket 테스트가 +1h 시계 때문에 항상 거부 결과를 받는다(테스트 버그). | 남음 | `src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/LiveRedisSemanticPortsTest.java:230`: adapter 시계가 `Clock.offset(systemUTC, +1h)`다. `:252`: 요청 deadline은 `Instant.now().plusSeconds(5)`다. `RedisEdgeRateLimitAdapter.java:99-106`은 `callerDeadline`이 adapter 시각보다 앞이면 `Unavailable(ADMISSION_REJECTED)`를 돌려준다. 그런데 테스트는 `Evaluated`를 기대한다(:236-238). 원인 추정: "Redis TIME을 쓴다"를 보이려고 넣은 offset이 deadline 검사와 충돌했다. | W4 | `:230`을 `Clock.systemUTC()`로 되돌린다. skew 검증은 이미 `idempotencyLeaseExpiryUsesRedisTimeAcrossSkewedCallers`(:317-)가 한다. offset을 꼭 유지하려면 `request()`가 같은 clock으로 deadline을 만들게 한다. | -| NEW-5c | Required | 멱등성·lease adapter가 "보내기 전 거부"(script lane 없음, lane 포화)도 `Indeterminate`로 분류한다. | 남음 | `src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/idempotency/RedisIdempotencyStoreAdapter.java:109-131`, `lease/RedisDistributedLeaseAdapter.java:145-172`(acquire), `:197-227`(inspect), `:316-346`(renew), `:352-375`(release): `catch (Exception)` 하나로 모두 `Indeterminate`를 돌려준다. 거부는 `RedisRuntimeOwner.borrow`가 `RedisCommandRejectedException`(`RedisOperationException`의 하위 클래스)으로 던진다(`RedisRuntimeOwner.java:136-160`). rate-limit adapter는 이미 이 둘을 구분한다(`RedisEdgeRateLimitAdapter.java:123-132`, `metadata().ambiguousExecution()`). 포트에는 결정적 실패 variant가 있다: `IdempotencyClaimOutcome.Unavailable`(:71), `LeaseAcquireOutcome.Unavailable(LeaseUnavailableCategory.UNAVAILABLE_BEFORE_SEND)`(:34). | W2 | 두 adapter에 `catch (RedisOperationException failure)`를 `catch (Exception)` 앞에 추가한다. `!failure.metadata().ambiguousExecution()`이면 `Unavailable`(lease는 `UNAVAILABLE_BEFORE_SEND`)을 돌려주고, 나머지만 `Indeterminate`로 둔다. 모양은 rate-limit과 같다. 테스트는 script lane이 없는 `runtime(false)`로 claim/acquire를 호출하고 `Unavailable`을 단언한다. | -| NEW-6 | Nit | `S3AsyncResponseBodyBridgeTest`가 벽시계 예산 5초에 의존해 부하가 걸리면 실패할 수 있다. | 남음 | `src/adapter/outbound/objectstorage/src/test/java/dev/caskeleton/adapter/outbound/objectstorage/s3/S3AsyncResponseBodyBridgeTest.java:45,101`: `CallBudget.fromNow(Duration.ofSeconds(5))`을 테스트 시작 시점에 만든다. `:80,119,127`: `result.get(5, SECONDS)`. bridge는 50ms마다 poll하면서 예산 만료를 `System.nanoTime()`으로 확인한다(`S3AsyncResponseBodyBridge.java:231,261-262`). 두 번째 테스트는 예산 하나(`read`)를 bridge 2개가 차례로 나눠 쓴다(:94-128). 큐 용량 2(chunk 1 + END)는 경합 원인이 아니다(`:164`). 미확인: 실패 로그가 없어서 실제 실패 지점은 확정하지 못했다. | W4 | 예산과 `get` timeout을 30초로 올린다(실패 경로 테스트는 즉시 끝나므로 느려지지 않는다). 두 번째 테스트는 bridge마다 새 `ReadOperation`(새 예산)을 만든다. | -| NEW-7a | Required | durable operation을 같은 operationId로 재시도하면 outbox append가 다시 실행된다. | 남음 | `src/application-core/src/main/java/dev/caskeleton/application/operation/SubmitDurableOperationUseCase.java:100`: `alreadyAccepted = !operation.operationId().equals(command.operationId())`. 같은 id로 재시도하면 store가 기존 행을 돌려주고(`DurableOperationStoreAdapter.java:49-` `submitIfAbsent` 후 조회), id가 같아서 `alreadyAccepted=false`가 되어 `:107` append가 다시 돈다. `eventId=operationId`이고 `outbox_event` PK가 `event_id`다(`V3__outbox_event.sql:14`). `OutboxStoreAdapter.java:71`은 `repository.save(entity)`인데 `OutboxEventEntity.java:20-22`에 `@Version`도 `Persistable`도 없다. 그래서 (추정, Spring Data `isNew` 기본 규칙) merge로 기존 행을 PENDING·attempt 0으로 덮어써서 다시 발행할 수 있다. 기존 테스트는 다른 id로 재제출하는 경우만 본다(`SubmitDurableOperationUseCaseTest.java:92-105`). | W2 | `DurableOperationJpaRepository.submitIfAbsent`(:51)의 반환형을 `int`(삽입 행 수)로 바꾼다. `DurableOperationStorePort.submit`은 `created` 여부를 돌려주게 하고(예: `DurableOperationSubmitResult(operation, created)`), use case는 `created`일 때만 append한다. `OutboxEventEntity`는 `Persistable`(`isNew=true`)을 구현해서 중복 append가 PK 위반으로 드러나게 한다. 테스트: 같은 id로 두 번 submit → `outbox.appended` 1건, `alreadyAccepted=true`. | -| NEW-7b | Consider | `Submit/Get/CancelDurableOperationUseCase`를 쓰는 HTTP 어댑터와 운영 조립이 없다. | 남음 | 이 use case들을 참조하는 main 코드는 `application-core` 자신뿐이다(grep: `new SubmitDurableOperationUseCase` 등 test 밖 0건). 저장소만 `@Repository`로 있다(`DurableOperationStoreAdapter.java:28`). 인바운드 어댑터와 bean 조립이 없다. | W2 | 결정(2026-09-25): HTTP 어댑터 추가 — `POST /operations`(202)·`GET`·`DELETE /operations/{id}`, JPA 조립에 use case bean | -| NEW-8a | Required | 알림 reconcile이 `Unsupported`면 attempt·수신자 상태를 바꾸지 않는다. 행이 영구히 남고 매 recovery 주기마다 다시 조회된다. | 남음 | `src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/ReconciliationService.java:77-84`(gateway 미지원)과 `:126-129`(gateway가 Unsupported 반환)는 metric만 올린다. `:72-74`(snapshot 없음)도 같다. | W2 | `Unsupported`일 때 수신자를 운영자가 확인하는 종단 상태로 옮긴다. 예: `RECONCILIATION_REQUIRED`에 `nextCheckAt=null`, 또는 전용 `MANUAL_REVIEW` 상태. `ambiguousAttemptExists=true`를 유지하고 lease를 해제한다. 전이는 `recipients.transition(...)`을 `transactions.inWrite`로 감싸 `StillUnknown` 분기(:119-125)와 같은 모양으로 한다. | -| NEW-8b | Required | attempt가 모두 완료된 수신자가 `DISPATCHING`에 남는다(1차 리뷰 B-4). | 남음 | `DispatchOutcomeRecorder.java:118-121`: 모호하지 않은 결과면 수신자를 `DISPATCHING`으로 저장한다(callback 대기). `LeaseRecoveryService.java:113`: `expiredDispatching`로 다시 조회한다. `:123-138`: attempt가 모두 `completedAt` 있음이면 아무것도 하지 않는다. 결과적으로 같은 행이 매 batch를 차지해서 다른 행의 복구를 굶길 수 있다. | W2 | `LeaseRecoveryService.recoverOnce`에서 attempt가 모두 완료인 경우를 명시적으로 처리한다. callback 대기 기한(`staleAfter`)이 지났으면 마지막 attempt로 `reconciliation.reconcile(...)`을 호출하고, 그래도 확정이 안 되면 NEW-8a의 종단 상태로 전이한다. 테스트는 attempt가 모두 완료된 DISPATCHING 행 1개로 `recoverOnce`를 두 번 부르고 상태가 바뀌는지 단언한다. | -| NEW-9a | Required | GraphQL 요청 단계 에러가 `GraphQlWireErrorMapper`를 거치지 않는다. adopter의 `ApiErrorCarrier`가 요청 단계에서는 `INTERNAL_ERROR`로 나간다. | 남음 | `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlPlatformWebInterceptor.java:161-168`(`reject`, 호출은 `:95`)과 `GraphQlPlatformInstrumentation.java:81-88`이 `GraphQlPlatformRejectionMapper.map`(:41)을 직접 호출한다. 이 mapper는 platform 예외 9종만 instanceof로 매핑한다(:54-121). 필드 단계만 `GraphQlWireErrorMapper.mapFieldFailure`(:60)를 거친다(`GraphQlDataFetcherExceptionResolver.java:22-44`). 원 지적은 `docs/reviews/2026-09-24-src-maintainability-review.md:912-915`. | W2 | `GraphQlWireErrorMapper`에 `map(Throwable, GraphQlErrorContext)` 진입점 하나를 둔다. platform rejection을 먼저 보고, 그다음 application mapping(`ApiErrorCarrier`), 마지막에 internal로 처리한다. interceptor·instrumentation·field resolver 세 곳이 모두 이 mapper bean을 받는다(`GraphQlPlatformAutoConfiguration.java:388-396`에서 주입). category switch 3개(`GraphQlWireErrorMapper.java:94`, `GraphQlWireErrors.java:56`, `clientMessage`)는 `EnumMap` 표 하나로 합친다. | +| NEW-4b | Required | Kafka TLS 자료(truststore/keystore) 설정 키가 없다. `MUTUAL_TLS`를 설정 값으로는 받지만 실제로 동작하지 않는다. | 완료 | Wave 1–2 P1 (fcddab7e·Wave 2 커밋): M-2e 행과 같은 수정·테스트 | - | `BrokerSettings`(messaging-spring-boot-starter)에 `trust-store-location/password/type`, `key-store-location/password/type`을 추가하거나 Spring Boot SSL bundle 이름(`ssl-bundle`)을 받는다. `KafkaSecurityConfigurer`가 `ssl.truststore.*`·`ssl.keystore.*`(또는 PEM `ssl.*.certificates`)를 채운다. keystore가 없는 `MUTUAL_TLS`는 컴파일 단계에서 거부한다. 구현하지 않을 거면 `MessagingConfigurationCompiler.java:258`에서 `MUTUAL_TLS`를 뺀다. | +| NEW-4c | Consider | platform producer가 broker 주소를 `spring.kafka.bootstrap-servers`에서만 읽고, 선언된 broker의 `bootstrap-servers`는 검증만 한 뒤 쓰지 않는다. | 완료 | Wave 1–2 P1 (fcddab7e·Wave 2 커밋): M-2b 행과 같은 수정·테스트 | - | 주소 출처를 하나로 정한다. 추천은 compiled broker(`CompiledMessagingConfiguration`의 kafka broker `bootstrapServers()`)를 쓰고, 없을 때만 `spring.kafka.bootstrap-servers`로 fallback하는 것이다. 둘 다 있는데 값이 다르면 기동을 실패시킨다. 테스트는 `producerConfig(...)`에 두 값을 다르게 주고 결과를 단언한다. | +| NEW-4d | Required | credential rotation이 Kafka producer에 반영되지 않는다. | 완료 | Wave 1–2 P1 (fcddab7e·Wave 2 커밋): M-2f 행과 같은 수정·테스트 | - | Kafka 방식으로 해결한다. `sasl.client.callback.handler.class`에 `CredentialRuntimeRegistry`를 조회하는 handler를 넣고 JAAS에는 username만 둔다. 이러면 재인증(broker `connections.max.reauth.ms`) 때마다 새 비밀번호를 쓴다. 다른 방법은 registry의 generation 변화에 맞춰 producer를 교체하고 transport generation을 올리는 것이다. Javadoc(:17-21)은 실제 동작에 맞춘다. | +| NEW-5a | Required | Redis ACL 템플릿의 script 계정에 `TIME` 권한이 없다. rate-limit·멱등성 script가 NOPERM으로 실패한다(실제 lane 실패 4건의 주원인). | 완료 | Wave 1–2 P6 (fcddab7e·Wave 2 커밋): W1 `22f28a3e`. `infra/redis-sdk/acl/application-advanced.acl:1`, `infra/redis-sdk/acl/all-accounts.acl:3`에 `+time` 추가(`admin-readonly`는 이미 있음). probe가 `redis.call('TIME')`을 실제 실행: `cache-redis/.../capability/RedisSemanticScriptAclProbe.java:29-38`. 단위 `RedisSemanticScriptAclProbeTest.anAccountDeniedACommandTheScriptsCallFailsStartup[TIME]` FAIL(`Expecting actual not to be null`)→PASS. 실제 Redis `LiveRedisSemanticScriptAclProbeTest.theAdvancedAccountPassesTheStartupProbe`: 새 probe + 옛 ACL에서 FAIL(`ERR ACL failure in script: User ca-skeleton-application-advanced has no permissions to run the 'time' command`) → ACL 수정 후 PASS. 이 클래스를 `cache-redis/build.gradle` `redisTopologyLane` standalone·cluster 필수 클래스에 등록. `infra/redis-sdk/acl/README.md`에 `+time` 이유 기록 | - | 두 ACL 파일의 advanced 계정에 `+time`을 추가한다. `admin-readonly.acl:1`에는 이미 `+time`이 있다. probe script를 `redis.call('TIME')`을 실제로 수행하는 스크립트로 바꿔서 권한이 없으면 기동 때 실패하게 한다. 검증은 `redis-sdk-topology.yml` standalone lane에서 `LiveRedisSemanticPortsTest`로 한다. | +| NEW-5b | Consider | `LiveRedisSemanticPortsTest`의 token-bucket 테스트가 +1h 시계 때문에 항상 거부 결과를 받는다(테스트 버그). | 완료 | Wave 1–2 P6 (fcddab7e·Wave 2 커밋): `LiveRedisSemanticPortsTest.java:193`: token-bucket adapter 시계 `Clock.offset(+1h)` → `Clock.systemUTC()`. `tokenBucketWithNonDivisibleRefillUsesIntegerExpiry` FAIL(W1 후에도 `AssertionError at :194`)→PASS. 기존 실패 4건(`theIdempotencyStoreClaimsOnceUnderTheAdvancedAccount`, `idempotencyLeaseExpiryUsesRedisTimeAcrossSkewedCallers`, `theRateLimiterEnforcesUnderTheAdvancedAccount`, `tokenBucketWithNonDivisibleRefillUsesIntegerExpiry`) 모두 PASS: 앞의 3건은 NEW-5a ACL, 마지막은 NEW-5b | - | `:230`을 `Clock.systemUTC()`로 되돌린다. skew 검증은 이미 `idempotencyLeaseExpiryUsesRedisTimeAcrossSkewedCallers`(:317-)가 한다. offset을 꼭 유지하려면 `request()`가 같은 clock으로 deadline을 만들게 한다. | +| NEW-5c | Required | 멱등성·lease adapter가 "보내기 전 거부"(script lane 없음, lane 포화)도 `Indeterminate`로 분류한다. | 완료 | Wave 1–2 P6 (fcddab7e·Wave 2 커밋): 멱등성 `RedisIdempotencyStoreAdapter.java:132,258,319,356,505`, lease `RedisDistributedLeaseAdapter.java:175,239,368,409`에 `catch (RedisOperationException)` + `!metadata().ambiguousExecution()` → `Unavailable`/`UNAVAILABLE`(lease는 `UNAVAILABLE_BEFORE_SEND`, renew/release는 handle을 ACTIVE로 유지). 테스트: `RedisIdempotencyStoreAdapterTest.aSaturatedScriptLaneRefusesTheClaimAsUnavailable`(FAIL `Indeterminate[...] to be an instance of Unavailable`→PASS), `aSaturatedScriptLaneRefusesOwnerTransitionsAsUnavailable`[markExecutionStarted/renew/complete/markFailed/releaseBeforeExecution](FAIL `expected: UNAVAILABLE but was: INDETERMINATE`→PASS), `RedisDistributedLeaseAdapterTest.aSaturatedScriptLaneRefusesAcquireBeforeSend`/`aSaturatedScriptLaneRefusesInspectBeforeSend`/`aRenewRefusedBeforeSendLeavesTheHandleActive`/`aReleaseRefusedBeforeSendLeavesTheHandleActive`(FAIL `expected: Unavailable[category=UNAVAILABLE_BEFORE_SEND] but was: Indeterminate`→PASS). 현황표 수정 방향의 테스트 제안(`runtime(false)`)은 틀렸다: 그 경우 EVALSHA가 서버까지 가서 NOPERM으로 거부되므로 not-sent가 아니다. 대신 SCRIPT lane을 포화시킨 owner(`RedisRuntimeOwner.borrow`가 `RedisCommandRejectedException`)로 재현했다. openLane 실패 같은 타입 없는 예외는 기존대로 Indeterminate(기존 `anUnreachableRedisIsIndeterminate` 유지) | - | 두 adapter에 `catch (RedisOperationException failure)`를 `catch (Exception)` 앞에 추가한다. `!failure.metadata().ambiguousExecution()`이면 `Unavailable`(lease는 `UNAVAILABLE_BEFORE_SEND`)을 돌려주고, 나머지만 `Indeterminate`로 둔다. 모양은 rate-limit과 같다. 테스트는 script lane이 없는 `runtime(false)`로 claim/acquire를 호출하고 `Unavailable`을 단언한다. | +| NEW-6 | Nit | `S3AsyncResponseBodyBridgeTest`가 벽시계 예산 5초에 의존해 부하가 걸리면 실패할 수 있다. | 완료 | Wave 1–2 P2 (fcddab7e·Wave 2 커밋): 결정적 FAIL 재현은 못 했다(부하 의존 간헐 실패, 실패 로그 없음). 원인인 벽시계 예산을 없앴다: 예산 `CallBudget.fromNow(365일)`, `get` 타임아웃은 1분 hang guard로만, bridge마다 새 `ReadOperation`, truncated/oversized 두 테스트로 분리. `adapter/outbound/objectstorage/src/test/.../s3/S3AsyncResponseBodyBridgeTest.java` 3/3 PASS | - | 예산과 `get` timeout을 30초로 올린다(실패 경로 테스트는 즉시 끝나므로 느려지지 않는다). 두 번째 테스트는 bridge마다 새 `ReadOperation`(새 예산)을 만든다. | +| NEW-7a | Required | durable operation을 같은 operationId로 재시도하면 outbox append가 다시 실행된다. | 완료 | Wave 1–2 P9 (fcddab7e·Wave 2 커밋): application: `SubmitDurableOperationUseCaseTest.retryUnderTheSameOperationIdAppendsTheOutboxEventOnlyOnce` FAIL(`[false, 2]` ≠ `[true, 1]`)→PASS. 실제 PG 재현: `DurableOperationSubmissionOutboxIntegrationTest.retryUnderTheSameOperationIdLeavesThePublishedOutboxRowAlone` FAIL(`[false, [PENDING]]` — 재시도가 PUBLISHED row를 merge로 PENDING으로 되돌림 = 재발행)→PASS, `aSecondAppendOfTheSameEventIdIsRefusedByThePrimaryKeyInsteadOfOverwritingTheRow` FAIL(예외 없이 덮어씀)→PASS(`PersistenceFailureException` SQLState 23505). 수정: `submitIfAbsent`가 삽입 행 수 반환(`.../operation/DurableOperationJpaRepository.java:52`), `DurableOperationStorePort.submit` → `DurableOperationSubmitResult(operation, created)`(새 파일 `application-core/.../operation/DurableOperationSubmitResult.java`), use case는 `created`일 때만 append(`SubmitDurableOperationUseCase.java:99-104`), `OutboxEventEntity implements Persistable`(`isNew`, `@PostLoad/@PostPersist`). `DurableOperationStoreContract`에 `retryUnderTheSameOperationIdReturnsTheOperationAsNotCreated` 추가 — fake와 PG adapter(`DurableOperationStoreAdapterContractTest`, jpa-contract) 모두 통과 | - | `DurableOperationJpaRepository.submitIfAbsent`(:51)의 반환형을 `int`(삽입 행 수)로 바꾼다. `DurableOperationStorePort.submit`은 `created` 여부를 돌려주게 하고(예: `DurableOperationSubmitResult(operation, created)`), use case는 `created`일 때만 append한다. `OutboxEventEntity`는 `Persistable`(`isNew=true`)을 구현해서 중복 append가 PK 위반으로 드러나게 한다. 테스트: 같은 id로 두 번 submit → `outbox.appended` 1건, `alreadyAccepted=true`. | +| NEW-7b | Consider | `Submit/Get/CancelDurableOperationUseCase`를 쓰는 HTTP 어댑터와 운영 조립이 없다. | 완료 | Wave 1–2 P9 (fcddab7e·Wave 2 커밋): 소유자 결정 15. `adapter:inbound:web` `operation/DurableOperationController`: `POST /operations`(202 + Location, Envelope), `GET /operations/{id}`, `DELETE /operations/{id}`(202). 컨트롤러는 Submit/Get/Cancel 유스케이스만 호출, 인가는 유스케이스 `@RequiresPermission`, owner·tenant 판정은 유스케이스의 `DurableOperationAccessPolicy`(남의 것 = 없는 것 = 404 `OPERATION_NOT_FOUND`). 조립은 `app-bootstrap/.../autoconfigure/operation/DurableOperationConfig`(기존 `OutboxConfig` 패턴, operation store·outbox append·TransactionPort bean이 있을 때만 켜짐, `AutoConfiguration.imports` 등록). 테스트: web slice `DurableOperationControllerTest` 10건, 실제 PG 왕복 `DurableOperationCompositionIntegrationTest` 5건(프록시된 `@RequiresPermission` 403 포함, `integrationTest` lane `requires`에 추가). 새 경로는 인증 필요 경로라 공개 경로 스냅숏은 바뀌지 않음(`verifyPublicPathSnapshot` 통과). `security.yml`에 `operation-submit: operation:submit,operation:cancel`, dev Keycloak realm에 같은 client role 추가. 설계 선택(결정 필요 시 뒤집을 수 있음): id는 서버가 UUID로 발급, 재제출은 payload fingerprint로 dedupe, outbox event type은 `OperationCommand.SUBMITTED_EVENT_TYPE` 하나(클라이언트가 임의 event type을 broker에 싣지 못하게), TTL `OperationCommand.DEFAULT_TIME_TO_LIVE`(1일), tenant는 null(웹 운영 경로에 tenant 해석이 없음) | - | 결정(2026-09-25): HTTP 어댑터 추가 — `POST /operations`(202)·`GET`·`DELETE /operations/{id}`, JPA 조립에 use case bean | +| NEW-8a | Required | 알림 reconcile이 `Unsupported`면 attempt·수신자 상태를 바꾸지 않는다. 행이 영구히 남고 매 recovery 주기마다 다시 조회된다. | 완료 | Wave 1–2 P3 (fcddab7e·Wave 2 커밋): B-4b와 같은 결함. 같은 수정·테스트(`ReconciliationService.java:148`). 수정 방향대로 `ambiguousAttemptExists`·attempt는 건드리지 않아 redrive는 계속 duplicate-risk 승인을 요구 | - | `Unsupported`일 때 수신자를 운영자가 확인하는 종단 상태로 옮긴다. 예: `RECONCILIATION_REQUIRED`에 `nextCheckAt=null`, 또는 전용 `MANUAL_REVIEW` 상태. `ambiguousAttemptExists=true`를 유지하고 lease를 해제한다. 전이는 `recipients.transition(...)`을 `transactions.inWrite`로 감싸 `StillUnknown` 분기(:119-125)와 같은 모양으로 한다. | +| NEW-8b | Required | attempt가 모두 완료된 수신자가 `DISPATCHING`에 남는다(1차 리뷰 B-4). | 완료 | Wave 1–2 P3 (fcddab7e·Wave 2 커밋): B-4a와 같은 결함. 같은 수정·테스트(`LeaseRecoveryService.java:123`). 방향의 "staleAfter 지나면 reconcile 호출" 대신 requeue: 모든 attempt가 완료라 provider에 물을 것이 없고, dispatch 라우팅이 기록된 결과로 다음 단계를 정한다. `expiredDispatching`이 이미 staleAfter로 거른다 | - | `LeaseRecoveryService.recoverOnce`에서 attempt가 모두 완료인 경우를 명시적으로 처리한다. callback 대기 기한(`staleAfter`)이 지났으면 마지막 attempt로 `reconciliation.reconcile(...)`을 호출하고, 그래도 확정이 안 되면 NEW-8a의 종단 상태로 전이한다. 테스트는 attempt가 모두 완료된 DISPATCHING 행 1개로 `recoverOnce`를 두 번 부르고 상태가 바뀌는지 단언한다. | +| NEW-9a | Required | GraphQL 요청 단계 에러가 `GraphQlWireErrorMapper`를 거치지 않는다. adopter의 `ApiErrorCarrier`가 요청 단계에서는 `INTERNAL_ERROR`로 나간다. | 완료 | Wave 1–2 P8 (fcddab7e·Wave 2 커밋): S5-#6a와 같은 결함, 같은 수정·같은 테스트. 수정 방향 중 category switch 3개(`GraphQlWireErrorMapper.category`·`clientMessage`, `GraphQlWireErrors.classificationOf`)를 EnumMap 표 하나로 합치는 일은 지시대로 하지 않음 — Wave 3 3-A(Category별 한국어 문구 표를 shared-contract에)에서 `clientMessage`가 그 표로 대체되므로 그때 함께. 커밋 `aa5f4d90` | - | `GraphQlWireErrorMapper`에 `map(Throwable, GraphQlErrorContext)` 진입점 하나를 둔다. platform rejection을 먼저 보고, 그다음 application mapping(`ApiErrorCarrier`), 마지막에 internal로 처리한다. interceptor·instrumentation·field resolver 세 곳이 모두 이 mapper bean을 받는다(`GraphQlPlatformAutoConfiguration.java:388-396`에서 주입). category switch 3개(`GraphQlWireErrorMapper.java:94`, `GraphQlWireErrors.java:56`, `clientMessage`)는 `EnumMap` 표 하나로 합친다. | | NEW-9b | Nit | `shared-contract`의 `OperationalRecordStorePort` 패키지는 사용처가 0이다. | 남음 | `src/shared-contract/src/main/java/dev/caskeleton/shared/opstore/`(3개 파일). 이 패키지 밖에서 `shared.opstore`를 참조하는 곳은 main·test 모두 0건이다. 유일한 소비자였던 graphql `advanced/**`는 삭제됐다(`docs/capability-status.md:211`). | W3 | `shared/opstore/` 3개 파일을 삭제한다. `src/shared-contract/CLAUDE.md` 책임 목록에 있으면 그 줄도 지운다. `docs/study/graphql-walkthrough.ko.md:125,2064,2133`의 언급은 NEW-14에서 함께 고친다. | -| NEW-10a | Consider | web 운영 경로에 JSON 중복 키 거부가 없다. | 남음 | `src/app-bootstrap/src/main/resources/application.yml:64-80`에는 `fail-on-unknown/null-for-primitives/ignored-properties`만 있다. 중복 키 감지는 web·bootstrap main 어디에도 없다(`STRICT_DUPLICATE_DETECTION` grep 0건). web-advanced에도 없다. JSON mapper factory(`WebObjectMapperFactory`·`BoundedJsonFactory`)는 web-advanced로 옮긴 뒤 삭제됐다(`docs/capability-status.md:208`). | W1 | `adapter:inbound:web`에 `JsonMapperBuilderCustomizer` 빈 하나를 두고 `StreamReadFeature.STRICT_DUPLICATE_DETECTION`을 켠다(Jackson 3, `tools.jackson.core`). 위치는 `WebAdapterAutoConfiguration` import 목록이다. contract test는 `{"a":1,"a":2}` → 400을 단언한다. | -| NEW-10b | Consider | CORS origin의 형식을 기동 때 검증하지 않는다(scheme/host/port 형태, path·trailing slash·`null` origin). | 남음 | `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/settings/CorsSettings.java:24-53`은 "enabled면 비어 있지 않음"과 "`*`+credentials 금지" 두 가지만 검사한다. 예전 `WebCorsPolicyValidator`는 web-advanced로 옮긴 뒤 삭제됐다(`docs/capability-status.md:206`). | W1 | `CorsSettings` compact constructor에 origin마다 `URI` 파싱을 추가한다. `http`·`https` scheme과 host가 있어야 하고, path·query·fragment·trailing `/`와 `"null"`은 금지한다. `*`는 credentials가 없을 때만 허용한다. 실패하면 env 키 이름을 담은 메시지로 기동을 실패시킨다(기존 메시지 형식을 따른다). | -| NEW-10c | Required | 신뢰하지 않는 forwarded 헤더를 거부하는 장치가 없다. rate-limit의 `FORWARDED_HEADERS_TRUSTED`는 XFF의 맨 왼쪽 값(클라이언트가 조작 가능)을 쓴다. | 남음 | `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/ratelimit/ForwardedHeaderClientIpResolver.java:10-17`은 `split(",")[0]`을 쓰고 remoteAddr가 proxy인지 확인하지 않는다. `server.forward-headers-strategy` 기본값은 `none`(`src/app-bootstrap/src/main/resources/config/server.yml:11`)이지만, `framework`로 바꾸면 모든 요청의 헤더를 신뢰한다. 예전 `ForwardedHeaderSanitizer`·`TrustedProxyPolicy`는 web-advanced로 옮긴 뒤 삭제됐다(`docs/capability-status.md:204`). | W1 | `EdgeRateLimitTransportSettings`에 `trusted-proxies`(CIDR 목록)를 추가한다. resolver는 remoteAddr가 trusted일 때만 XFF를 오른쪽에서부터 읽어 첫 번째 untrusted 주소를 쓰고, 아니면 remoteAddr를 쓴다. `FORWARDED_HEADERS_TRUSTED`인데 `trusted-proxies`가 비어 있으면 기동을 거부한다. `server.yml` 주석에는 `native` + `server.tomcat.remoteip.internal-proxies`를 명시하라고 적는다. | +| NEW-10a | Consider | web 운영 경로에 JSON 중복 키 거부가 없다. | 완료 | Wave 1–2 P10 (fcddab7e·Wave 2 커밋): `RequestBodyBoundaryTest.duplicateJsonKeyIsRejectedAsValidationFailure`(`{"role":"user","role":"admin"}` → 400 `VALIDATION_FAILED`) FAIL(`Status expected:<400> but was:<200>`)→PASS. `JsonMapperBuilderCustomizer`로 `StreamReadFeature.STRICT_DUPLICATE_DETECTION`(`src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/mvc/autoconfigure/WebMvcPlatformAutoConfiguration.java:84`). 위치는 현황표의 `WebAdapterAutoConfiguration` 대신 같은 leaf의 `WebMvcPlatformAutoConfiguration`(요청 경계 필터와 같이 servlet 앱 조건·`backend.web.mvc.enabled`에 묶이고, 테스트가 무거운 security 조립 없이 이 루트 하나로 검증됨) | - | `adapter:inbound:web`에 `JsonMapperBuilderCustomizer` 빈 하나를 두고 `StreamReadFeature.STRICT_DUPLICATE_DETECTION`을 켠다(Jackson 3, `tools.jackson.core`). 위치는 `WebAdapterAutoConfiguration` import 목록이다. contract test는 `{"a":1,"a":2}` → 400을 단언한다. | +| NEW-10b | Consider | CORS origin의 형식을 기동 때 검증하지 않는다(scheme/host/port 형태, path·trailing slash·`null` origin). | 완료 | Wave 1–2 P10 (fcddab7e·Wave 2 커밋): `CorsSettings` compact constructor가 origin마다 `URI` 파싱: `http`/`https`, host 필수, path(끝 `/` 포함)·query·fragment·user info·와일드카드 호스트·`"null"` 거부, `*`는 기존대로 credentials 없을 때만. 메시지에 `APP_SECURITY_CORS_ORIGINS (ca-skeleton.cors.allowed-origins)`. 테스트는 I-8b 행 | - | `CorsSettings` compact constructor에 origin마다 `URI` 파싱을 추가한다. `http`·`https` scheme과 host가 있어야 하고, path·query·fragment·trailing `/`와 `"null"`은 금지한다. `*`는 credentials가 없을 때만 허용한다. 실패하면 env 키 이름을 담은 메시지로 기동을 실패시킨다(기존 메시지 형식을 따른다). | +| NEW-10c | Required | 신뢰하지 않는 forwarded 헤더를 거부하는 장치가 없다. rate-limit의 `FORWARDED_HEADERS_TRUSTED`는 XFF의 맨 왼쪽 값(클라이언트가 조작 가능)을 쓴다. | 완료 | Wave 1–2 P10 (fcddab7e·Wave 2 커밋): I-5a와 같은 수정(같은 커밋·테스트). 현황표 수정 방향(`trusted-proxies` CIDR 설정 추가)은 오케스트레이터 결정(모드 삭제 + native/internal-proxies)으로 대체. `.env.example`이 `framework`(모든 peer의 XFF를 믿음)를 기본으로 권하던 것도 이 행의 원인이라 `native`로 바꾸고 `framework`는 rate limit 기동 거부로 막음 | - | `EdgeRateLimitTransportSettings`에 `trusted-proxies`(CIDR 목록)를 추가한다. resolver는 remoteAddr가 trusted일 때만 XFF를 오른쪽에서부터 읽어 첫 번째 untrusted 주소를 쓰고, 아니면 remoteAddr를 쓴다. `FORWARDED_HEADERS_TRUSTED`인데 `trusted-proxies`가 비어 있으면 기동을 거부한다. `server.yml` 주석에는 `native` + `server.tomcat.remoteip.internal-proxies`를 명시하라고 적는다. | | NEW-10d | Nit | web fixture 앱 2개와 sample이 `WebAdapterAutoConfiguration` 전체를 제외한다. sample webSystemTest 4곳은 문자열 이름으로 제외한다. | 남음 | 클래스로 제외: `src/adapter/inbound/web/src/testFixtures/java/dev/caskeleton/webtestkit/ContractFixtureApplication.java:38`, `PipelineOrderFixtureApplication.java:46`, `src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/SamplePortfolioApplication.java:30,49`. 문자열로 제외: `OpenApiDriftContractTest.java:172`, `OpenApiSnapshotTest.java:103`, `DateHeaderContractTest.java:69`, `VirtualThreadMdcE2ETest.java:152`(모두 `src/sample-portfolio/src/webSystemTest/...`). 제외하는 이유는 production security chain을 빼기 위해서다(`ContractFixtureApplication.java:27-30`). | W3 | `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/mvc/autoconfigure/WebAdapterAutoConfiguration.java`의 `@Import` 목록을 `WebAdapterAutoConfiguration`(core)과 `WebSecurityAutoConfiguration`(`JwtDecoderConfig`·`SecurityConfig`·`MethodSecurityConfig`·`RedisSessionWebConfig`·`JwtToAuthenticatedPrincipalConverter`·`AuthorizationAdapter`)으로 나눈다. fixture·sample은 security root만 클래스로 제외하고, sample은 `dev.caskeleton.adapter.inbound.web` component scan(`SamplePortfolioApplication.java:31-40`)을 지운다. 문자열 제외는 클래스 참조로 바꾼다. | -| NEW-11 | Consider | fileserver를 JPA 줄 없이 고르면 Boot 관계형 자동 설정이 켜지고, 원인을 알기 어려운 오류로 기동에 실패한다. | 남음 | `src/adapter/outbound/persistence-fileserver/build.gradle`이 `implementation 'org.springframework.boot:spring-boot-starter-data-jpa'`를 가져서 runtime classpath에 Hibernate·Hikari가 들어온다. `src/composition/fileserver-platform/build.gradle`은 persistence-jpa를 의존하지 않는다. JPA를 끄는 쪽(`JpaActivationEnvironmentPostProcessor`)은 persistence-jpa에 있어서 이 경우 존재하지 않는다. 결과 추정: URL도 embedded DB도 없으면 `DataSourceAutoConfiguration`이 "Failed to configure a DataSource"로 실패한다. URL을 주면 `TransactionPort` 빈이 없어서 `FileserverUploadServiceConfiguration.java:86,116`·`FileserverMaintenanceServiceConfiguration.java:43`에서 NoSuchBean으로 실패한다. Flyway 핵심 stream과 `capability_schema_registry`도 없다(`FileserverSchemaActivation.java:22-30`). "JPA 필요"는 문서에만 있다(`src/README.md:270`, `src/composition/fileserver-platform/README.md:27`). notification도 같은 구조다(`docs/capability-status.md:36`). | W2 | 결정(2026-09-25): 한 줄 원칙 — fileserver·notification composition이 persistence-jpa를 `runtimeOnly`로 함께 가져옴 | +| NEW-11 | Consider | fileserver를 JPA 줄 없이 고르면 Boot 관계형 자동 설정이 켜지고, 원인을 알기 어려운 오류로 기동에 실패한다. | 완료 | Wave 1–2 P4 (fcddab7e·Wave 2 커밋): `src/composition/fileserver-platform/build.gradle`에 `runtimeOnly project(':adapter:outbound:persistence-jpa')`, `src/config/architecture/modules.json` edge 추가, README 갱신(`src/composition/fileserver-platform/README.md` 저장소 줄, `src/README.md:270` 표). `architectureCheck`·`verifyDependencyLocks` 통과. JPA 줄 없이 fileserver만 고른 조립의 기동 테스트는 추가하지 않았다: 모든 테스트 classpath(app-bootstrap integrationTest 포함)에 persistence-jpa가 이미 있어 "없는 조립"을 만들 수 없다. 대신 조립 lane `:app-bootstrap:integrationTest`(fileserver PG 왕복 포함 4건) 통과 | - | 결정(2026-09-25): 한 줄 원칙 — fileserver·notification composition이 persistence-jpa를 `runtimeOnly`로 함께 가져옴 | | NEW-12 | Nit | `bootstrap.autoconfigure` 패키지가 component scan 범위 안에 있다. | 남음 | `src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/CaSkeletonApplication.java:19`: `@SpringBootApplication`이 `dev.caskeleton.bootstrap..` 전체를 scan한다. 지금 `autoconfigure/` 아래 4개 root는 imports에 있어서 Boot의 `AutoConfigurationExcludeFilter`가 걸러낸다. 그 외 stereotype은 `@ConfigurationProperties` record 3개뿐이다(grep: `@Configuration`·`@Component` 0건). 지금 당장 문제는 없고, 나중에 root가 아닌 `@Configuration`을 추가하면 조건 없이 등록되는 잠재 위험이다. | W3 | NEW-2 이동 뒤에 남는 `common`·`tracing` root를 scan 밖 패키지(예: `dev.caskeleton.autoconfigure.bootstrap`)로 옮긴다. 옮기지 않을 거면 architectureTest에 "`bootstrap.autoconfigure..`의 `@Configuration`은 `@AutoConfiguration`이어야 한다" 규칙을 추가한다. | | NEW-13a | Consider | `verifyEnvKeys`는 bootstrap에 유지하기로 결정됐는데, 문서는 아직 "옮기지 않은 검사"라고 적고 있다. | 남음 | 태스크는 `src/app-bootstrap/build.gradle:5`(`ca.config-contract`), 루트 `src/build.gradle:78`(`configContractCheck`)에 있다. 구현은 `src/build-tools/src/main/java/dev/caskeleton/buildtools/config/`(6개 파일)에 있다. 문구는 `CLAUDE.md:32`, `AGENTS.md:68`에 있다. | W3 | JPA evidence를 삭제하면(NEW-13b) build-tools에는 `ca.config-contract` 하나만 남는다. 그 plugin을 `src/build-logic/`으로 옮기고 `src/settings.gradle:6` `includeBuild('build-tools')`와 `build-logic.yml`의 build-tools 단계를 지운다. `CLAUDE.md:32`·`AGENTS.md:68`은 "verifyEnvKeys = app-bootstrap 유지"로 고친다. | | NEW-13b | Consider | JPA evidence manifest(`ca.jpa-evidence`, `ca.jpa-qualification`)를 폐기하고 leaf 테스트로 옮기기로 결정됐다. 아직 코드에 남아 있다. | 남음 | plugin: `src/build-tools/build.gradle:18-27`, 구현은 `src/build-tools/src/main/java/dev/caskeleton/buildtools/jpa/`(45개 파일, 2,701줄). 적용 위치: `src/build.gradle:20`, `src/adapter/outbound/persistence-jpa/build.gradle:5,141-178,216,261-264`. 입력: `src/config/jpa/readiness-cards.yaml`, `src/config/jpa/release-registry.json`. CI: `.github/workflows/jpa-r2-evidence.yml` 전체, `integration-main.yml:130-143`(`jpa-candidate-evidence`), `jpa-release.yml:121-122`. 다른 사용처: `MessagingCapabilityRegistryContractTest.java:128,140,225`가 `readiness-cards.yaml`을 읽고, `JpaReleaseManifest.java:46`(persistence-jpa testFixtures)가 `release-registry.json`을 읽는다. | W3 | build-tools의 `jpa/` 패키지와 두 plugin id를 삭제한다. evidence가 확인하던 사실(마이그레이션 순서, PG 버전 매트릭스, lane 존재)은 persistence-jpa `postgresqlIntegrationTest`의 JUnit 테스트로 옮긴다. yaml·json 입력과 `jpa-r2-evidence.yml`, integration-main의 `jpa-candidate-evidence` 잡, jpa-release의 두 태스크를 지운다. `MessagingCapabilityRegistryContractTest`에서 readiness-cards 의존을 뺀다. | @@ -1097,3 +1109,56 @@ - 208077fd와 HEAD 사이에 삭제된 클래스만 셌다. 그 전에 삭제됐거나 처음부터 구현되지 않은 이름은 세지 않았으므로 실제 불일치는 더 많다. - 모듈 이름 언급은 세지 않았다. +## 후속 작업 중 발견한 결함 (2026-09-25 ~ 09-28) + +Wave 1–2 구현 묶음(`P1`–`P13`)이 작업 중 찾은 결함과 통합 검증에서 드러난 문제. 상세는 각 묶음 결과 파일 「새로 발견한 결함」 절. + +| ID | 심각도 | 요약 | 상태 | 근거 | Wave | 수정 방향 | +|---|---|---|---|---|---|---| +| P1-new-1 | 발견 | `src/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaMessagingAutoConfiguration.java` — broker 항목의 `acks`, `enable-idempotence`, `max-in-flight-requests-per-connection`, `del… | 완료 | Wave 1–2 P1 (fcddab7e·Wave 2 커밋): 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P1.md` | - | - | +| P1-new-2 | 발견 | `src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrar.java` — in-flight 천장·drain·pool 거부로 pause한 partition을 다시 resume하는 코드가 없음. ordered partition은 한 poll에 두 record를 받으면 첫 record 뒤 영구 정지… | 완료 | Wave 1–2 P1 (fcddab7e·Wave 2 커밋): 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P1.md` | - | - | +| P1-new-3 | 발견 | 같은 파일 — requeue 재개 시각을 `Instant.now()`로, poll은 호출자가 준 `now`로 비교해 두 시계가 섞임(테스트에서 재시도가 영원히 안 풀리거나 즉시 풀림). `InstantSource` 하나로 통일(M-7 수정에 포함) | 완료 | Wave 1–2 P1 (fcddab7e·Wave 2 커밋): 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P1.md` | - | - | +| P2-new-1 | 발견 | managed `publish`가 SCAN_CLEAN destination에서 scan 없이 게시한다 — `RoutingObjectMutationAdapter.publish`가 INTEGRITY_VERIFIED에서 곧바로 REFERENCE_PUBLISH_IN_PROGRESS로 가고 `requirePolicy`는 요구 수준이 같은지만 봤다. 이제 scan-gated destination이면 거부한다(`confi… | 완료 | Wave 1–2 P2 (fcddab7e·Wave 2 커밋): 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P2.md` | - | - | +| P2-new-2 | 발견 | sample abort와 reconcile의 경합에서 intent가 멈춘다 — `AbortPosterImageUploadUseCase`(`sample-portfolio/.../poster/AbortPosterImageUploadUseCase.java:63-81,91`)는 DB에 ABORT_AUTHORIZED를 먼저 커밋한 뒤 저장소에 `authorizeAbort`를 부른다. 그 사이 reconcile이 fin… | 남음 | 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P2.md` | W2 | 결정 22: 먼저 끝난 쪽이 이긴다 — 이미 게시됐으면 abort는 409, 게시된 객체를 붙인다 | +| P2-new-3 | 발견 | S3 managed provider `retire`가 항상 UNSUPPORTED를 던진다(`s3/S3ManagedObjectProvider.java:121-125`). S3 profile은 `CONDITIONAL_RETIREMENT`를 주장할 수 있어 destination 컴파일은 통과한다. D-1a 순서에서 S3 abort는 ABORTED를 기록한 뒤 retire에서 실패한다(바이트 잔존, 재시도도 같은 실… | 남음 | 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P2.md` | W2 | S3 `retire` 구현 또는 S3 profile이 `CONDITIONAL_RETIREMENT`를 주장하지 못하게 | +| P3-new-1 | 발견 | `ntf-app/admin/AdminAuthorizationGuard.java` `requireTenant`가 어떤 작업이든 거부 시 `AdminAccessDeniedException(SUPPRESS)`를 던졌다 — redrive·reconcile 거부가 SUPPRESS 권한 부족으로 보고됨. 실제 권한을 인자로 받게 고침(`:41`). | 완료 | Wave 1–2 P3 (fcddab7e·Wave 2 커밋): 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P3.md` | - | - | +| P3-new-2 | 발견 | SNS 서명 인증서의 유효기간을 확인하지 않았다(`NotificationCallbackProviderConfig.java:80` `checkValidity()` 추가, B-2e와 함께). | 완료 | Wave 1–2 P3 (fcddab7e·Wave 2 커밋): 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P3.md` | - | - | +| P3-new-3 | 발견 | JDK HttpClient의 요청 timeout은 응답 body 읽기를 덮지 않는다. B-6 재현 테스트의 FAIL이 증거다(요청 timeout 10초가 지나도 body 대기가 끝나지 않아 JUnit 20초 timeout). 상한 전까지 body를 조금씩 흘리는 provider(또는 SNS 인증서 host)는 dispatch 스레드를 무기한 잡을 수 있다. 위치 `ntf-adapter/provider/http… | 남음 | 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P3.md` | W2 | 응답 body 읽기에 별도 deadline | +| P3-new-4 | 발견 | SES adapter도 B-9a와 같은 결함(비 email 연락처·reveal 실패가 ambiguous로 기록). 공용 `EmailRecipients`로 SMTP와 함께 고침. | 완료 | Wave 1–2 P3 (fcddab7e·Wave 2 커밋): 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P3.md` | - | - | +| P3-new-5 | 발견 | 라우트의 profile runtime이 사라진 경우 `gateway.profile()`이 `IllegalStateException`(`ntf-adapter/dispatch/ProviderRuntimeRegistry.java:50`)을 던져 B-3과 같은 경로(attempt row 전, lease 미해제 → requeue 반복)를 탄다. 설정 drift라 "고쳐질 때까지 재시도"로 볼 수도 있어 FAILED로 … | 남음 | 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P3.md` | W2 | 결정 21: 일반 재시도 정책(backoff·최대 횟수) 적용 후 FAILED + 사유 코드 | +| P3-new-6 | 발견 | dispatch의 guard `Blocked` 전이와 routing stop 전이(`ntf-app/dispatch/NotificationDispatchService.java:138-142`, `applyRoutingStop`)는 lease fencing 없는 `transition`을 쓴다(B-5b와 같은 계열). provider 호출 전 짧은 구간이라 위험은 낮다. | 남음 | 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P3.md` | W2 | guard `Blocked`·routing stop 전이를 lease fencing 있는 전이로 | +| P4-new-1 | 발견 | fileserver migration(`src/adapter/outbound/persistence-fileserver/src/main/resources/db/migration/jpa/fileserver/V1..V5`)은 불변성 테스트가 없다. `AppliedMigrationImmutabilityTest`는 persistence-jpa의 `src/main/resources/db/migration`만 읽는다(`s… | 남음 | 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P4.md` | W4 | fileserver migration에도 적용 파일 해시 고정 테스트 | +| P4-new-2 | 발견 | 재조정이 READY를 복원할 때 quota를 commit하지 않는다. `src/application-fileserver/.../recovery/DefaultFileReconciliationService.java` `reconcilePrePublishWithKey`는 VERIFYING→READY 전이만 하고 `QuotaCommitGateway.commit`이 없다. C-3a·C-3b로 이 경로가 실제로 실행되므… | 남음 | 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P4.md` | W2 | 재조정 READY 복원 때 quota commit | +| P4-new-3 | 발견 | `DefaultFinalizeUploadService.advanceToVerifying`의 CREATED 분기가 CREATED→UPLOADED를 시도하지만 전이표에는 CREATED→UPLOADING뿐이라 `IllegalStateException`이 난다(`.../upload/DefaultFinalizeUploadService.java` `advanceToVerifying` 첫 if). | 남음 | 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P4.md` | W2 | CREATED 분기 전이를 전이표에 맞게 | +| P4-new-4 | 발견 | lifecycle delete(`DefaultFileLifecycleService.delete`)로 진행 중 upload(UPLOADING)를 지우면 레코드는 DELETED가 되지만 세션은 ACTIVE로 남고 staging 정리가 예약되지 않는다. 이후 만료 sweep도 레코드가 DELETED라 staging을 예약하지 않아 staged bytes가 남는다. `FileRetirement`에 upload를 찾는… | 남음 | 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P4.md` | W2 | 진행 중 upload 삭제 시 세션 종료·staging 정리 예약 | +| P5-new-1 | 발견 | `src/grpc-advanced/grpc-advanced-compat/src/main/resources/envoy/envoy.yaml:37`(virtual host `cors`): Envoy v1.31 validate가 `VirtualHost.cors`를 deprecated("will be removed soon")로 경고한다. per-filter `typed_per_filter_config`의 `CorsP… | 남음 | 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P5.md` | W5 | envoy CORS를 per-filter 설정으로 | +| P5-new-2 | 발견 | `src/grpc/grpc-core-api/src/main/java/dev/caskeleton/grpc/core/GrpcMethodName.java`: `parse`는 전체 이름을 256자로 제한하지만 생성자는 service·method를 각각 256자로만 제한해 canonical이 최대 513자가 된다. ledger 쪽은 N-11b에서 막았지만 타입 자체의 두 경로가 다르다. 안 고침. | 남음 | 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P5.md` | W2 | `GrpcMethodName` 두 생성 경로의 길이 제한 통일 | +| P5-new-3 | 발견 | `src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/security/GrpcCredentialRotationManager.java:125` `completeDrain()`이 인자 없이 "지금 draining인 것"을 지워서, 그 사이 새 rotation이 시작한 drain(방금 교체된 세대)을 일찍 끝낼 수 있다. 경합 자체(현재 세대 되돌림)는 N-5b로 고쳤… | 남음 | 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P5.md` | W2 | `completeDrain`이 대상 rotation을 인자로 받게 | +| P5-new-4 | 발견 | `src/grpc-advanced/grpc-advanced-{resilience,compat,edition,streaming}/build.gradle`: `api project(':grpc-advanced:grpc-advanced-bootstrap')`를 main이 쓰지 않는다(resilience는 `GrpcXdsStartupGuard` 삭제로 새로 0, 나머지 셋은 원래 0). build 줄과 registr… | 남음 | 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P5.md` | W3 | 쓰지 않는 bootstrap 의존 제거 | +| P6-new-1 | 발견 | `src/adapter/outbound/cache-redis/README.md` 「Useful focused checks」가 `./gradlew :app-bootstrap:test --tests '*RedisSemanticScriptAclProbeTest'`를 안내했지만 그 테스트는 cache-redis leaf에 있다. `:adapter:outbound:cache-redis:test`로 수정. 같은 READ… | 완료 | Wave 1–2 P6 (fcddab7e·Wave 2 커밋): 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P6.md` | - | - | +| P6-new-2 | 발견 | `IdempotencyExecutor`(application-core)는 `complete`가 `UNAVAILABLE`이면 곧바로 `IdempotencyUnavailableException`을 던진다(`IdempotencyExecutor.java:228`). 이번 수정으로 SCRIPT lane 포화 시 complete가 `INDETERMINATE`(재조정 경로) 대신 `UNAVAILABLE`을 받으므로, 효과… | 남음 | 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P6.md` | W5 | 결정 24: 현재 동작 유지, README·Javadoc에 복구 경로 명시 | +| P7-new-1 | 발견 | `src/adapter/outbound/notification/src/test/java/dev/caskeleton/adapter/outbound/notification/core/NotificationAdapterTest.java:65-82`: `RoutingNotifierTest`와 같은, 절대 실패하지 않는 PII 단언이 있었다(`"provider-failure"`). 고쳤다(W1 `9a05d686`). | 완료 | Wave 1–2 P7 (fcddab7e·Wave 2 커밋): 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P7.md` | - | - | +| P7-new-2 | 발견 | `IdempotencyExecutor`의 `RetryableNoEffect` 경로도 `markFailed`가 예외를 던지면 원래 action 예외를 잃었다. A-8b와 함께 고쳤다(W2 `3a39b6b5`). | 완료 | Wave 1–2 P7 (fcddab7e·Wave 2 커밋): 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P7.md` | - | - | +| P7-new-3 | 발견 | `src/sample-portfolio/src/main/resources/db/sample-migration/V2__work_log.sql:26-27`의 주석은 "local dev relies on ddl-auto=update"라고 적혀 있다. 실제로는 `SamplePostgreSqlPersistenceConfig.sampleMigrationStrategy`가 sample schema를 migrate한다. 이… | 남음 | 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P7.md` | W5 | 적용된 migration은 못 바꾸므로 sample README에 실제 경로 명시 | +| P7-new-4 | 발견 | L-7a로 `show-details: never`가 되면 `show-components`도 따라서 never가 된다. 그러면 `/actuator/health` 응답에 component가 나오지 않는다. P13 `NEW-1a`(compose smoke가 켜진 capability를 확인)는 health component 대신 `info` 경로를 써야 한다. | 완료 | Wave 1–2 P7 (fcddab7e·Wave 2 커밋): 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P7.md` | - | - | +| P8-new-1 | 발견 | `GraphQlBatchLoadException`(per-key 실패, adopter가 준 `errorCode`)을 mapper가 모른다 → `INTERNAL_ERROR`로 가려지고 adopter code가 사라짐. `src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/dataloader/GraphQlBatchResu… | 남음 | 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P8.md` | W3 | 결정 25: 등록된 `ApiErrorCode`만 노출(3-A와 함께) | +| P8-new-2 | 발견 | instrumentation 이 platform context 없이 온 요청(= interceptor 미배선 설정 오류)을 `INTERNAL_ERROR`+`PLATFORM_CONTEXT`로 거부하지만 로그를 남기지 않아, 잘못 조립된 배포가 모든 요청을 조용히 실패시킨다. `.../runtime/GraphQlPlatformInstrumentation.java:65-70`. | 남음 | 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P8.md` | W2 | platform context 없는 요청 거부 시 WARN 로그 | +| P8-new-3 | 발견 | graphql `CLAUDE.md` 「Error mapping」 절이 없는 클래스 `GraphqlExceptionResolver`와 "비-carrier 예외는 null 반환"을 설명하고 있었음. 현재 경로(한 mapper, 마스킹+로그)로 고침. 커밋 `aa5f4d90`. | 완료 | Wave 1–2 P8 (fcddab7e·Wave 2 커밋): 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P8.md` | - | - | +| P8-new-4 | 발견 | 이번 D 삭제 대상(`GraphQlRuntimeTransport`, `GraphQlExecutionProfile`, `GraphQlBlockingBridge`)을 설명하는 학습 문서가 남아 있음 — `docs/study/graphql-walkthrough.ko.md:157,461,871,1078`(결정 6 대상), `docs/graphql-superpowers-package/`. | 남음 | 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P8.md` | W5 | 학습 문서 갱신(결정 6) | +| P9-new-1 | 발견 | `InboxItemEntity.archive()`가 EXPIRED·DELETED 항목도 ARCHIVED로 바꾼다(`src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/notification/platform/inbox/InboxItemEntity.java` `archive`). terminal … | 남음 | 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P9.md` | W2 | `archive()`가 EXPIRED·DELETED를 거부 | +| P9-new-2 | 발견 | `PostgreSqlInboxCutoffIntegrationTest`가 repository의 SQL이 아니라 테스트 안의 사본을 실행하고 있어 E-4a가 PG lane에서 보이지 않았다. 고침(repository `@Query`를 읽어 실행). | 완료 | Wave 1–2 P9 (fcddab7e·Wave 2 커밋): 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P9.md` | - | - | +| P9-new-3 | 발견 | 같은 operationId를 다른 요청(다른 scope)으로 재사용하면 fake(`InMemoryDurableOperationStore`)는 조용히 덮어쓰고 PG adapter는 PK 위반으로 실패한다 — fake/adapter 불일치. HTTP 경로는 id를 서버가 발급해 영향 없음. 고치지 않음. | 남음 | 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P9.md` | W4 | durable operation store 계약 테스트에 id 재사용 경우 추가, fake를 adapter와 맞춤 | +| P9-new-4 | 발견 | `WebMvcRequestContextHolder.store(...)`를 부르는 운영 코드가 없어 `WebRequestContext`를 파라미터로 받는 컨트롤러는 항상 `IllegalStateException`으로 실패한다(`src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/mvc/context/WebMvcRequestContex… | 남음 | 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P9.md` | W2 | 운영 경로에서 `WebRequestContext`를 채우거나 파라미터 사용처 제거 | +| P9-new-5 | 발견 | 웹 운영 경로에 tenant 해석이 없다(`TenantContext.resolved` 호출자 없음). durable operation HTTP는 tenant를 null로 넘긴다. 결함이라기보다 미구현 — 기록만. | 남음 | 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P9.md` | W3 | tenant 해석(3-D tenant 값 타입과 함께) | +| P10-new-1 | 발견 | `src/.env.example:25`가 `APP_SERVER_FORWARD_HEADERS_STRATEGY=framework`를 권했다. `framework`는 Spring `ForwardedHeaderFilter`가 모든 peer의 `X-Forwarded-For`를 믿어 `getRemoteAddr()` 자체를 호출자가 고르게 하므로, rate-limit 모드와 상관없이 비인증 키를 우회할 수 있었다. `na… | 완료 | Wave 1–2 P10 (fcddab7e·Wave 2 커밋): 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P10.md` | - | - | +| P10-new-2 | 발견 | `WebMvcRequestIdFilter`의 traceparent 정규식은 all-zero trace id 등을 받아들였고 `RequestLoggingFilter`의 `TraceParent.parse`는 거부해서, 같은 요청에서 두 필터가 다른 trace id를 가질 수 있었다(I-4b의 한 원인). 이제 `TraceParent.parse` 하나만 쓴다. | 완료 | Wave 1–2 P10 (fcddab7e·Wave 2 커밋): 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P10.md` | - | - | +| P10-new-3 | 발견 | 옛 콜백 컨트롤러의 `@RequestBody byte[]`는 form POST(`application/x-www-form-urlencoded`, query string 없음)에서 Spring 7 `ServletServerHttpRequest.getBody()`가 요청 파라미터로 다시 만든 본문을 준다(`getBodyFromServletRequestParameters`, spring-web 7.0.9 bytec… | 완료 | Wave 1–2 P10 (fcddab7e·Wave 2 커밋): 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P10.md` | - | - | +| P11-new-1 | 발견 | `app.httpclient.clients[N].timeout.streaming-idle`(`APP_HTTPCLIENT_CLIENTS_N_TIMEOUT_STREAMING_IDLE`)은 바인딩만 되고 main 코드 어디서도 읽지 않음(reactive 삭제 전에도 그랬음). `HC/profile/TimeoutSettings.java:25`, `docs/httpclient/configuration-reference… | 남음 | 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P11.md` | W3 | 읽지 않는 `timeout.streaming-idle` 키·env 키 삭제 | +| P11-new-2 | 발견 | `scripts/verify-httpclient-docs.py:22`가 없는 경로 `src/app-bootstrap/.../autoconfigure/httpclient/HttpClientStartupValidator.java`를 읽어 `FileNotFoundError`로 실패함. 경로를 `.../httpclient/autoconfigure`로 바꿔 돌리면 `rotation-drain-timeout`이 `doc… | 남음 | 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P11.md` | W5 | `scripts/verify-httpclient-docs.py` 경로 수정, `rotation-drain-timeout` 문서 추가 | +| P11-new-3 | 발견 | `httpClientFailureInjectionTest`의 `FailureInjectionContractTest.disabledProxyFailsBeforeARequestCanBeSent`가 이 머신에서 실패(`expected: NOT_SENT but was: SENT_NO_RESPONSE`). Docker userland proxy(`docker-proxy` 동작 중)가 꺼진 Toxiproxy 리스너의 p… | 남음 | 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P11.md` | W4 | Docker userland proxy에 의존하지 않는 방식으로 lane 수정(기준 커밋에서도 실패 — 기존 결함) | +| P11-new-4 | 발견 | Dynamic Target cross-origin hop은 `SensitiveHeaderStripper` 표준 이름(`authorization`·`cookie`·`x-api-key`·`api-key` 등)만 제거하므로, 호출자가 `HeaderPolicy`로 넘긴 관례 밖 이름의 자격증명 헤더(예: `X-Client-Key`)는 다음 origin으로 따라감 `HC/dynamic/DefaultDynamicTarg… | 남음 | 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P11.md` | W1 | 결정 23: cross-origin hop에서 호출자 헤더 전부 제거, 안전한 헤더만 유지 | +| P12-new-1 | 발견 | bulk 경로가 `access.rawOperations().getCollection(...)`의 raw collection에 `bulkWrite`를 해서, `MongoConsistencyBinder`가 profile별 template에 `setWriteConcern`으로 건 write concern이 적용되지 않는다(Spring `MongoTemplate.getCollection`은 template write… | 남음 | 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P12.md` | W2 | bulk 경로에 profile write concern 적용 | +| P13-new-1 | 발견 | included build lock은 build-logic·build-tools 자신의 configuration(compile/test)만 잠근다. main build가 plugin을 쓸 때의 settings·root buildscript classpath는 main build에서 따로 해석되고 잠기지 않는다. 증거: `./gradlew buildEnvironment`에서 `project :build-tool… | 보류 | 사유: 잠그면 Spring Boot plugin을 올릴 때마다 lock 갱신 필요, included build 자체는 잠갔다. 승인자: 저장소 소유자(2026-09-28, 결정 27) | - | - | +| P13-new-2 | 발견 | `local-redis` lane은 기동 로그 무음 검사(스크립트 3c)를 통과할 수 없다. lane 자신이 주는 `APP_REDIS_AUTHENTICATION_ANONYMOUS_ACCESS_ACCEPTED=true`와 advanced credential 미설정 때문에 `RedisSdkAutoConfiguration`이 기동 중 WARN 2줄(`Redis is running without credentials… | 남음 | 결과 파일 `docs/reviews/2026-09-25-review-followup-results/P13.md` | W4 | `local-redis` lane 설정 또는 smoke 무음 검사 기준 정리(NEW-1b와 함께) | +| NEW-15 | 발견 | gRPC proto 조직 이름이 템플릿 이름이 아니라 `hyeonworks`로 고정 — `GrpcProtoStyleManifest.caSkeleton()` `organization`, 기본 proto 패키지 `hyeonworks.grpc.common.v1`, `GrpcCodegenManifest`, 테스트 38개 파일. 재사용 체크리스트에도 없음 | 남음 | `src/grpc/grpc-proto-contract/src/main/java/dev/caskeleton/grpc/contract/GrpcProtoStyleManifest.java:62`, `src/grpc/grpc-proto-contract/src/main/resources/proto/hyeonworks/`, `src/grpc/grpc-codegen/.../GrpcCodegenManifest.java:63` | W3 | 결정 18(protobuf 플러그인 전환)과 함께 `caskeleton`으로 바꾸고 `AGENTS.md` 재사용 체크리스트에 한 줄 | +| NEW-16 | 발견 | `integrationCheck`가 로컬에서 통과할 수 없는 lane을 묶음 — Redis topology 3개는 `-Predis.topology.mode` 없이 fail-closed, AWS 보호 lane은 보호 자격 증명 env가 없으면 실패. 그래서 집계 태스크가 항상 실패 | 남음 | Wave 1·2 검증 로그: `redisTopologyTest was selected with redis.topology.mode='unset'`, `AwsS3QualificationPreconditionsTest` | W3 | 매개변수·자격 증명이 필요한 lane은 `integrationCheck`에서 빼고 전용 워크플로에서만(또는 입력이 있을 때만 포함) | diff --git a/docs/reviews/2026-09-28-review-followup-resume-prompt.md b/docs/reviews/2026-09-28-review-followup-resume-prompt.md new file mode 100644 index 00000000..c5d720d2 --- /dev/null +++ b/docs/reviews/2026-09-28-review-followup-resume-prompt.md @@ -0,0 +1,79 @@ +# 재개 프롬프트 — 리뷰 후속 Wave 3–5 (desktop에서 이어 하기) + +> 사용법: desktop에서 이 저장소(`/home/donghyeon/workspace/chat-gpt-container/codebase/clean-architecture-backend-template`, 브랜치 `refactor/review-followup`)를 연 Claude Code 세션에 +> `docs/reviews/2026-09-28-review-followup-resume-prompt.md 를 읽고 그대로 진행하자` 한 줄로 시작한다. + +--- + +## 프롬프트 본문 + +### 0. 지금까지 (2026-09-25 ~ 09-28, 노트북에서 진행) + +- 입력: 1차 리뷰 `docs/reviews/2026-09-24-src-module-code-review.md`(그룹 A–O), 2차 리뷰 `docs/reviews/2026-09-24-src-maintainability-review.md`(BUILD·TEST·X1·X2·S1–S7). 원래 지시는 `docs/reviews/2026-09-25-review-followup-prompt.md`. +- 현황표 `docs/reviews/2026-09-25-review-followup-status.md`: 두 리뷰의 모든 항목을 행으로 만들고 현재 코드 기준으로 판정했다. 지금 859행(리뷰 812 + 작업 중 새로 찾은 결함 47) 중 **완료 370 · 해당 없음 112 · 보류 2 · 남음 375**(W1 4 · W2 17 · W3 196 · W4 57 · W5 101). +- 계획 `docs/superpowers/plans/2026-09-25-review-followup.md`: Wave 1(보안·데이터)·Wave 2(정합성)는 끝났다. 13개 작업 묶음(P1–P13)을 worktree 에이전트로 병렬 구현하고 main 작업 트리에 합쳐 전체 게이트로 검증했다. 기록은 맨 아래 「진행 기록」. +- 묶음별 결과(행 결과·제거된 코드·새 결함): `docs/reviews/2026-09-25-review-followup-results/P*.md`. +- 에이전트 공통 지시·스크립트: `docs/superpowers/plans/2026-09-25-review-followup-tools/`(`agent-brief.md`, `apply_results.py` = 결과 파일로 현황표 갱신, `by_area.py` = 남은 행을 영역·Wave별로 나열. 둘 다 저장소 루트에서 실행). +- **소유자 결정 27건**이 현황표 「소유자 결정」 절에 있다. 전부 따른다. 다시 묻지 않는다. 특히: 에러 응답은 Envelope 하나 + client 문구 한국어(Draft-12 offset 문서만 프로토콜 예외), outbox는 canonical(`OutboxAppendPort`)로 통일하고 legacy 포트·legacy Kafka seam 삭제, outbox relay·멱등성 executor 조립은 별도 `composition:*` 모듈, 설정 prefix는 `app.*`, SES는 AWS SDK(sesv2), gRPC `.proto`는 protobuf Gradle 플러그인 + Buf(CI), Kafka 소비 지원(`MessageHandler` 하나), `@DisplayName`은 한국어, 삭제된 코드를 설명하는 학습 문서는 현재 코드에 맞게 갱신. + +### 1. 목표 + +현황표의 남은 행 375개를 전부 `완료` / `해당 없음` / `보류(사유·승인자)`로 닫는다. 완료 조건은 원래 지시 8절과 같다: 모든 행이 닫히고, 계획서 「진행 기록」에 Wave별 검증 결과가 있고, 검증 명령이 작업 브랜치에서 전부 통과(기존 환경 의존 실패는 사유와 함께 기록). + +### 2. 먼저 읽을 것 + +1. `AGENTS.md`(HARD-STOP 7개, capability 모듈 규칙, 테스트 작성 규칙 6개 — 단 `@DisplayName`은 한국어), `CLAUDE.md` +2. 현황표의 「소유자 결정」 절과 「후속 작업 중 발견한 결함」 절 +3. 계획서 전체(특히 「Global Constraints」, 「실행 방식」, 「Wave 3/4/5」 개요, 「진행 기록」) +4. `docs/superpowers/plans/2026-09-25-review-followup-tools/agent-brief.md` + +### 3. 할 일 (순서) + +0. **환경 확인:** `git pull` 뒤 `git log --oneline -3`으로 이 문서를 추가한 커밋이 HEAD인지 본다. `nproc`, `free -g`, `docker ps`로 자원을 보고 동시 에이전트 수를 정한다(노트북은 여유 메모리 5GB라 3개였다). `cd src && ./gradlew check --continue`로 기준선을 확인한다. +1. **남은 W1·W2 먼저 (Wave 2.5):** `python3 docs/superpowers/plans/2026-09-25-review-followup-tools/by_area.py --list W1 <영역>`·`--list W2 <영역>`으로 나열. W1 4행 중 3행(`X1-지도-Kafka producer`, `X1-#1f`, `NEW-4a`)은 legacy Kafka seam 삭제(아래 3-C)로 닫히니 3-C에서 처리. `P11-new-4`(결정 23)와 W2 17행(대부분 `P*-new-*`)은 영역별 묶음으로. +2. **Wave 3 — 구조 (196행):** 계획서 「Wave 3」에 상세 Task를 먼저 추가한다(rolling-wave). 여러 leaf를 한 번에 바꾸는 공통 작업은 **순차**로: + - 3-A 에러 어휘: Envelope 하나, `ApiErrorCode` 하나, shared 예외 `ApiErrorCarrier`, `Category`별 한국어 문구 표(shared-contract), IAE는 모든 전송 400, GraphQL은 등록된 코드만 노출(결정 25). + - 3-B 설정 prefix `app.*`(gRPC 어댑터는 벤더 설정과 나란히 `app.grpc.server`처럼 — 부모 prefix를 쓰면 기동 실패가 다시 생긴다, P5 메모). + - 3-C outbox canonical 통일(JSON encoder 제공, sample 3곳 + durable operation 이전) + legacy 포트·legacy Kafka seam 삭제 + outbox relay·멱등성 executor를 `composition:*` 모듈로(NEW-2) + sample `SampleIdempotencyConfig` 복사본 제거. + - 3-D 공통 유틸(`Sha256`, `Backoff`, traceparent 파싱, 서명 헬퍼), tenant 값 타입과 운영 web 경로의 tenant 해석(P9-new-5, X2-P2-6b), caller 트랜잭션 guard 하나. + 그다음 영역별 묶음: Kafka 소비(결정 10), SES → AWS SDK(결정 17), gRPC protobuf 플러그인 + Buf(결정 18, 이때 proto 조직 이름 `hyeonworks` → `caskeleton`, NEW-15), `persistence-notification` leaf 추출, sample이 web leaf를 통째로 scan하는 구조 정리(NEW-10d), `integrationCheck` 구성 정리(NEW-16), SRP 분해·구현 1개 인터페이스 정리·이름 규칙, 빌드 게이트 이동(JPA evidence manifest 폐기, API surface → PR `check`). +3. **Wave 4 — 테스트 규칙 (57행):** `AGENTS.md` 규칙 2를 한국어로, 포트별 추상 계약 테스트(lock·lease 포함), 약한 단언, 계층별 모범 모듈, 18개 compose lane 실제 실행(NEW-1b). +4. **Wave 5 — 문서 (101행):** W5 행 전부 + 학습 문서(`docs/study/*.ko.md`, `docs/*-superpowers-package/`)를 현재 코드 기준으로 갱신(결정 6). 마지막에 현황표 요약 수치를 다시 센다. + +### 4. 실행 방식 (지난 Wave에서 검증된 방법) + +- 묶음 하나 = 구현 에이전트 하나, `isolation: worktree`. 프롬프트는 짧게: "공통 지시 `docs/superpowers/plans/2026-09-25-review-followup-tools/agent-brief.md`를 읽고 따른다 + 묶음 ID 목록 + 묶음별 주의사항 + 결과 파일 절대 경로(`<원본 작업 트리>/docs/reviews/2026-09-25-review-followup-results/-P<번호>.md`) + 원본 작업 트리 경로". +- 에이전트는 자기 worktree 브랜치에 `D`→`W` 순서로 커밋한다. 오케스트레이터는 `git cherry-pick -n <해시>`로 main 작업 트리에 모은다. **충돌·실패는 멈추고 해결한다.** 끝난 worktree는 깨끗한지 확인 후 `git worktree remove`(브랜치는 남김). 잠겨 있으면 살아 있는 프로세스가 없는지 보고 `git worktree unlock`. +- **묶음끼리의 의미 충돌을 예상한다.** 각 묶음이 자기 worktree에서 통과해도 합치면 깨진 사례가 이번에 3건 있었다: (1) 한 묶음이 저장값 검증을 추가 → 다른 묶음 테스트 fixture의 가짜 hash가 거부됨, (2) 새 `@RestController`를 sample의 component scan이 주워 감, (3) 같은 테스트를 두 묶음이 다른 기대값으로 고침. 그래서 **합친 뒤 전체 게이트를 반드시 돌린다.** +- `docs/capability-status.md`, 현황표, 계획서, lockfile은 에이전트가 아니라 오케스트레이터가 고친다(결과 파일의 「제거된 코드」 행은 `docs/capability-status.md` 표 끝에 붙인다 — `CapabilityStatusDocumentTest`가 이 파일을 읽으니 Gradle이 도는 중에는 고치지 않는다). +- 에이전트가 셸 heredoc으로 파일을 쓰다 멈춘 적이 있다. 파일은 파일 도구로. 긴 Gradle에는 `timeout`. 같은 작업 트리에서 Gradle은 동시에 하나. +- migration: 적용됐을 수 있는 versioned migration은 수정 금지, 새 버전 + `src/adapter/outbound/persistence-jpa/src/test/resources/db/applied-migrations.sha256`. 현재 최신: persistence-jpa `V18`, fileserver `V5`, messaging `V1005`. + +### 5. Wave 종료 검증 + +```bash +cd src +./gradlew check --continue +./gradlew ci verifyDependencyLocks --warning-mode=fail +./gradlew mainCheck --continue +./gradlew architectureCheck verifyPublicPathSnapshot :app-bootstrap:verifyEnvKeys configContractCheck +./gradlew :app-bootstrap:integrationTest :sample-portfolio:integrationTest :sample-portfolio:systemTest +./gradlew integrationCheck --continue +./gradlew -p build-logic test && ./gradlew -p build-tools test && ./gradlew -p optional-platforms ci +./gradlew :app-bootstrap:qualificationBootJar +# Redis topology lane (integrationCheck에서는 모드가 없어 실패한다 — NEW-16): +# REDIS_VERSION=7.4 docker compose -f ../infra/redis-sdk/standalone/compose.yml up -d --wait +# ./gradlew :adapter:outbound:redis-runtime:redisTopologyTest :adapter:outbound:redis-sdk:redisTopologyTest \ +# :adapter:outbound:cache-redis:redisTopologyTest --continue \ +# -Predis.topology.host=localhost -Predis.topology.port=6379 -Predis.topology.mode=standalone +# docker compose -f ../infra/redis-sdk/standalone/compose.yml down -v +``` + +`integrationCheck`의 기존 실패(이번 작업 전에도 실패, 고치는 것은 NEW-16·P11-new-3 행): Redis topology 3개(모드 인자 없음), `httpClientFailureInjectionTest.disabledProxyFailsBeforeARequestCanBeSent`(Docker userland proxy 의존), `objectStorageAwsQualificationTest`(보호 자격 증명 env 필요). 이 셋 말고 새 실패가 나오면 멈추고 원인을 찾는다. 로컬 SpotBugs가 "missing analysis class … .jar.jar"로 실패하던 문제는 `QualityConventionsPlugin`에서 고쳤다. + +### 6. 커밋·보고 + +- 브랜치 `refactor/review-followup`에 Wave마다 커밋(소유자 결정 1). `main` 병합과 push는 사용자가 요청할 때만. +- 커밋 메시지 끝: `Co-Authored-By: Claude Opus 5.5 (1M context) ` +- 보고는 짧게: 변경 / 확인(실행한 명령과 결과 수치) / 남은 문제. Wave마다 Slack `#clean-architecture-전체`(channel_id `C0BCN9H9ABH`)에 작업 브리핑(`:memo: *[작업] …*` 템플릿, 둘째 줄에 `repo`·`branch`·시각). +- 사용자는 작은 증분마다 확인받는 것보다 검증까지 끝낸 큰 덩어리를 선호한다. 진짜로 사용자 몫인 결정만 묻는다(여러 개면 한 번에 모아서, 기본값 추천과 함께). 사용량 한도가 있으니 에이전트는 묶음을 크게 잡아 수를 줄인다(지난번 구현 에이전트는 묶음당 약 36만~72만 토큰). diff --git a/docs/study/postgresql-jpa-walkthrough.ko.md b/docs/study/postgresql-jpa-walkthrough.ko.md index 0ab67edf..1dc5aa3f 100644 --- a/docs/study/postgresql-jpa-walkthrough.ko.md +++ b/docs/study/postgresql-jpa-walkthrough.ko.md @@ -2762,7 +2762,8 @@ scan 대상 6개: `audit`, `failure`, `idempotency`, `lock`, `outbox`, `transact | 가드 | 하는 일 | |---|---| -| `JpaDangerousConfigurationGuard` | `spring.jpa.open-in-view=true` (local convenience 프로필 외), 스키마 변경 `ddl-auto` 거부 | +| `JpaDangerousConfigurationGuard` | 스키마 변경 `ddl-auto` 거부 (local convenience 프로필 외) | +| `OpenInViewSafetyValidator` | `spring.jpa.open-in-view=true` 거부 — local 포함 모든 프로필 (guard에 있던 local 예외는 이 검사 때문에 도달할 수 없어 2026-09-25 삭제) | | `JpaDataSourceProfileValidator` | resolved `DataSource`를 열어서 product/version 확인 | | `PostgreSqlVersionPolicy` | PostgreSQL 16/17/18만 허용 | | `PersistenceVendorProdSafetyValidator` | prod에서 H2 거부 | diff --git a/docs/superpowers/plans/2026-09-25-review-followup-tools/agent-brief.md b/docs/superpowers/plans/2026-09-25-review-followup-tools/agent-brief.md new file mode 100644 index 00000000..175fba54 --- /dev/null +++ b/docs/superpowers/plans/2026-09-25-review-followup-tools/agent-brief.md @@ -0,0 +1,47 @@ +# 구현 에이전트 공통 지시 (리뷰 후속) + +당신은 구현 에이전트다. 프롬프트가 지정한 묶음(`P<번호>`)을 끝까지 구현·검증·커밋한다. + +## 작업 환경 +- 당신의 현재 작업 디렉터리는 이 저장소(Java 21 + Spring Boot 4.0.8 Gradle 멀티모듈 Clean Architecture 템플릿)의 **격리된 git worktree**다. `git rev-parse --show-toplevel`로 루트를 확인하고, 모든 편집·Gradle 실행은 이 worktree 안에서만 한다. 원본 작업 트리(오케스트레이터가 프롬프트에 적은 경로)는 절대 건드리지 않는다(읽기도 worktree 쪽 파일로). +- Gradle: `cd src && timeout 2400 ./gradlew :check --max-workers=2 --console=plain`. 이 worktree에서 Gradle은 한 번에 하나만. 다른 에이전트 2개가 동시에 돌고 있어 메모리가 빠듯하다(`--max-workers=2` 필수). Docker는 사용 가능(Testcontainers lane). +- 파일은 Read/Edit/Write 도구로 쓴다. 셸 heredoc·`echo >`로 소스 파일을 쓰지 않는다. + +## 먼저 읽을 것 +1. `AGENTS.md` — HARD-STOP 7개, 「부가 기능(capability) 모듈 규칙」, 「테스트 전략」의 테스트 작성 규칙 6개. **단 `@DisplayName` 언어는 한국어**(소유자 결정, AGENTS.md 문구는 나중 Wave에서 고침). +2. `CLAUDE.md`, 작업할 leaf의 가장 가까운 `src/**/CLAUDE.md`, leaf 경로·gradle_path·허용 edge는 `src/config/architecture/modules.json`. +3. 계획 `docs/superpowers/plans/2026-09-25-review-followup.md`의 「Global Constraints」, 「실행 방식」, 그리고 당신 묶음 절. +4. 현황표 `docs/reviews/2026-09-25-review-followup-status.md`에서 당신 ID들의 행(`grep -n '^| ' …`). 「수정 방향」 열이 행별 수정 지시이고 「근거」 열에 현재 `file:line`이 있다. 소유자 결정 20건은 현황표 「소유자 결정」 절. 배경이 더 필요하면 원 리뷰 `docs/reviews/2026-09-24-src-module-code-review.md`(1차, 그룹 A–O), `docs/reviews/2026-09-24-src-maintainability-review.md`(2차, BUILD/TEST/X1/X2/S1–S7)를 본다. + +## 규칙 +- 순서: D(결정된 삭제, 있으면) → 커밋 → W1 → 커밋 → W2 → 커밋. 커밋 메시지 `review-followup P<번호> : <한국어 요약>` + 빈 줄 + `Co-Authored-By: Claude Opus 5.5 (1M context) `. 당신 worktree 브랜치에서만 커밋하고 push하지 않는다. 다른 브랜치를 건드리지 않는다. +- 결함 수정은 TDD: 재현 테스트를 먼저 쓰고 실행해 FAIL을 확인(실패 메시지 한 줄을 결과 파일에 기록)한 뒤 고치고 PASS를 확인한다. 테스트 규칙 6개를 따른다(이름은 lowerCamelCase 행동 문장, 본문 3문장 이상이면 `// given // when // then`, `// when` 하나, 예외는 `catchThrowable`로 분리해 타입+메시지 단언, 포트 대역은 fake). fake가 결함을 숨기는 포트면 추상 계약 테스트로 fake와 어댑터를 함께 돌린다. DB·브로커 동작은 실제 벤더 lane으로 확인한다. +- 현황표의 수정 방향이 코드를 읽어 보니 틀렸으면, 더 작고 올바른 수정을 하고 결과 파일 근거에 이유를 적는다. 소유자 결정이 필요한 새 질문이 생기면 추측하지 말고 `보류`(사유: 결정 필요 …)로 둔다. +- DB 스키마가 바뀌면 이미 적용됐을 수 있는 migration은 수정하지 말고 새 버전을 추가한 뒤 `src/adapter/outbound/persistence-jpa/src/test/resources/db/applied-migrations.sha256`에 한 줄 추가한다(`AppliedMigrationImmutabilityTest`). 다른 묶음도 새 migration을 추가할 수 있으니, 버전 번호 충돌은 통합 때 오케스트레이터가 조정한다(결과 파일에 추가한 버전을 적는다). +- 모듈 edge는 `modules.json` 밖으로 만들지 않는다. 꼭 필요하면 registry에 추가하고 이유를 커밋 메시지에 적는다. 설정 키·env 키를 바꾸면 `docs/registries/env-keys.yaml`과 `src/.env.example`도 고치고 `./gradlew :app-bootstrap:verifyEnvKeys`를 돌린다. 공개 타입이 바뀌어 API surface 검사가 실패하면 해당 `update*ApiSurface -Papprove*` 태스크로 재승인한다(notification은 `-PapproveNotificationApiSurfaceChange`). 공개 HTTP 경로가 바뀌면 `verifyPublicPathSnapshot`의 승인 절차(build 파일에서 확인)를 따른다. 의존성이 바뀌면 `./gradlew :resolveAndLockAll --write-locks`. +- **고치지 말 파일:** `docs/capability-status.md`, 현황표, 계획서. 대신 결과 파일에 적는다. +- 끝나기 전 검증: 건드린 모든 leaf의 `check`, 묶음에 적힌 실제 벤더 lane, `./gradlew architectureCheck --max-workers=2`, env/의존성 변경 시 `:app-bootstrap:verifyEnvKeys`·`verifyDependencyLocks`. 실패를 남긴 채 끝내지 않는다. 못 고친 것은 그대로 보고한다. `git status`가 깨끗해야 한다(전부 커밋). + +## 결과 파일 +`docs/reviews/2026-09-25-review-followup-results/-P<번호>.md`(원본 작업 트리 쪽 절대 경로는 오케스트레이터가 프롬프트에 적는다) 에 Write 도구로 아래 세 절을 쓴다: + +``` +## 행 결과 +| ID | 결과 | 근거 | +|---|---|---| +(당신 묶음의 모든 ID 한 행씩. 결과는 `완료` / `해당 없음(코드 삭제)` / `보류` / `남음`. 완료면 테스트 클래스·메서드 이름과 FAIL→PASS, 현재 `file:line`. 해당 없음이면 삭제 커밋. 보류면 사유와 "승인자: 저장소 소유자 결정 필요". 남음이면 이유.) + +## 제거된 코드 +| 대상 | 경로 | 마지막으로 존재한 커밋 | 이유 | +|---|---|---|---| +(삭제한 것마다 한 행. 마지막으로 존재한 커밋은 `6d27356e`.) + +## 새로 발견한 결함 +(현황표에 없는 결함만. ID `P<번호>-new-1`…, 위치와 한 줄 설명. 고쳤으면 그렇다고.) +``` + +## 최종 응답 (짧게) +- worktree 경로와 브랜치 이름, 커밋 목록(해시 + 메시지) +- 행 결과 집계(완료/해당 없음/보류/남음 수) +- 실행한 검증 명령과 결과(통과/실패 수치) +- 남은 문제 diff --git a/docs/superpowers/plans/2026-09-25-review-followup-tools/apply_results.py b/docs/superpowers/plans/2026-09-25-review-followup-tools/apply_results.py new file mode 100644 index 00000000..623fc935 --- /dev/null +++ b/docs/superpowers/plans/2026-09-25-review-followup-tools/apply_results.py @@ -0,0 +1,87 @@ +"""Run from the repository root. +Apply package result files to the status document. + +Usage: python3 apply_results.py results/P1.md [results/P2.md ...] +Updates 상태·근거 of each listed ID; `남음` results keep the row open with the reason appended. +Prints IDs it could not find and a new status summary. Refuses unknown result values. +""" +import re +import sys +from collections import Counter +from pathlib import Path + +STATUS = Path("docs/reviews/2026-09-25-review-followup-status.md") +SPLIT = re.compile(r"(?{wave} {package}: 미완 — {evidence}" + else: + cells[3] = result + cells[4] = f"{wave} {package} ({commit}): {evidence}" + if not result.startswith("보류"): + cells[5] = "-" + lines[i] = "| " + " | ".join(cells) + " |" + STATUS.write_text("\n".join(lines) + "\n", encoding="utf-8") + missing = sorted(set(updates) - seen) + if missing: + print("NOT FOUND:", ", ".join(missing)) + counts = Counter() + for line in lines: + cells = [c.strip() for c in SPLIT.split(line)[1:-1]] + if len(cells) == 7 and cells[0] != "ID": + for key in RESULTS: + if cells[3].startswith(key): + counts[key] += 1 + print(dict(counts)) + + +if __name__ == "__main__": + main() diff --git a/docs/superpowers/plans/2026-09-25-review-followup-tools/by_area.py b/docs/superpowers/plans/2026-09-25-review-followup-tools/by_area.py new file mode 100644 index 00000000..a24998b5 --- /dev/null +++ b/docs/superpowers/plans/2026-09-25-review-followup-tools/by_area.py @@ -0,0 +1,92 @@ +"""Run from the repository root. +Assign open status rows to work areas. Usage: python3 by_area.py [--list WAVE AREA] [--ids WAVE AREA]""" +import re +import sys +from collections import Counter, defaultdict +from pathlib import Path + +STATUS = Path("docs/reviews/2026-09-25-review-followup-status.md") +SPLIT = re.compile(r"(?`로 가져온다. +현황표: 859행(812 + 후속 발견 47) 중 완료 370 · 해당 없음 112 · 보류 2 · 남음 375(W1 4 · W2 17 · W3 196 · W4 57 · W5 101). 묶음별 결과 파일은 `docs/reviews/2026-09-25-review-followup-results/P*.md`, 에이전트 지시·스크립트는 `docs/superpowers/plans/2026-09-25-review-followup-tools/`. -| 묶음 | 브랜치 | D·W1 커밋 (main에 적용됨) | W2 커밋 (Wave 2에서 적용) | 행 결과 | -|---|---|---|---|---| -| P1 messaging | `worktree-agent-ac82c0859f4fb76da` | `3ecef978` | `2ae3c960` | 완료 18, 남음 2(Wave 3 3-C) | -| P2 object storage | `worktree-agent-a0383097e74acaf1e` | `2c7b3d25` `69ca6565` `f8bf7b6d` | `11eac0c7` | 완료 20 | -| P3 notification | `worktree-agent-a9bbc66a423c4d1fa` | `38d31b98` `12adea6e` | `6db6214c` | 완료 17, 남음 1(X2-P2-7b → P10에서 완료) | -| P4 file server | `worktree-agent-a4be05fc0e42cb70c` | `433bacdb` | `ed2c0929` | 완료 24 | -| P5 realtime·gRPC | `worktree-agent-ab8fb70ea2e85b04c` | `9b296c7c` `b39d3de0` | `a498ad84` | 완료 24(+N-9c 완료, N-9b 해당 없음) | -| P6 Redis | `worktree-agent-a6ab0657d876ae6b9` | `22f28a3e` | `5761314d` | 완료 14 | -| P7 core·bootstrap | `worktree-agent-a50ffe5361b9ddd73` | `9a05d686` | `3a39b6b5` | 완료 11, 남음 1(X1-#1d = P9 E-5) | -| P8 GraphQL | `worktree-agent-ab74dd57027acdc42` | `6390bf89` `0392d8c9` | `aa5f4d90` | 완료 8, 해당 없음 1, 남음 2(Wave 3 3-D) | -| P9 JPA·durable op | `worktree-agent-adbb19427d5d1740b` | `21bcba8d` | `3152e50b` | 완료 14 | -| P10 web | `worktree-agent-afae86287ba980dfb` | `983cc832` | `5c08d3be` | 완료 13 | -| P11 httpclient | `worktree-agent-afdf5842812e13046` | `06764fcb` `c44030e8` | `52511391` | 완료 12, 해당 없음 4 | -| P12 Mongo | `worktree-agent-aa2a445bdd99d8bd7` | `ceddd6d1` | `3dc06bba` | 완료 11(+F-1c W5 사실상 해결) | -| P13 build/CI | `worktree-agent-a93a684bfe0982466` | `50cb2d9e` | `6b1cddc6` | 완료 5 | - -13개 묶음 전부 끝남. 모든 `D`·`W1` 커밋이 main 작업 트리에 적용돼 있다(충돌 0, 커밋 전). - -재개 순서: - -1. (완료) 13개 묶음의 `D`·`W1` 커밋 적용. -2. migration 버전 충돌 확인: P9가 persistence-jpa `V18`, P4가 fileserver `V5`, P1이 messaging `V1005`를 추가했다. -3. lockfile 재생성(`resolveAndLockAll --write-locks`) → Wave 종료 검증 전체 → `apply_results.py --only-waves W1` → 「제거된 코드」 표에 결과 파일 행 추가 → 커밋 `review-followup Wave 1` → Slack 브리핑. -4. W2 커밋 적용 → 같은 검증 → 커밋 `review-followup Wave 2`. -5. 새로 발견한 결함(`P*-new-*`)을 현황표 행으로 추가하고 Wave 3 이후에 배정. - -소유자에게 물을 것(모아 둔 것): -- P3-new-5: 알림 profile runtime이 사라진 경우 무한 재시도할지, FAILED로 닫을지. -- P2-new-2: sample poster 업로드에서 abort와 reconcile이 경합하면 게시된 객체가 붙지 않은 채 남는다. 어떻게 정리할지. -- P11-new-4: Dynamic Target이 cross-origin redirect될 때 호출자가 넣은 관례 밖 헤더(`X-Client-Key` 등)도 전부 버릴지. -- P6-new-2: 멱등성 `complete`가 연결 풀 포화로 `UNAVAILABLE`이면 executor가 재시도할지, 복구 경로에 맡길지. -- P8: DataLoader 키 실패 때 adopter가 준 에러 code를 client에 그대로 내보낼지. -- P9: durable operation 설계 선택 4개(서버 생성 id, payload fingerprint로 재제출 판정, 고정 outbox event type, 보존 1일) 승인 여부. -- P13-new-1: build-logic·build-tools를 main build가 plugin으로 불러올 때의 의존성도 잠글지(잠그면 Spring Boot plugin을 올릴 때마다 lock 갱신 필요). +작업 환경 이동(2026-09-28): 노트북 부하로 이후 작업은 desktop(`ssh desktop`, `/home/donghyeon/workspace/chat-gpt-container/codebase/clean-architecture-backend-template`)에서 이어 한다. 재개 프롬프트: `docs/reviews/2026-09-28-review-followup-resume-prompt.md`. diff --git a/docs/web/repository-adaptation.md b/docs/web/repository-adaptation.md index 4def4709..42f3402b 100644 --- a/docs/web/repository-adaptation.md +++ b/docs/web/repository-adaptation.md @@ -132,8 +132,17 @@ for idempotency, where `IdempotencyStorePort` lives in `application-core` and The split is not only a registry workaround; it puts each half where its invariants belong. A problem document is an HTTP concept and has no business being persisted, so the stored failure is a -code plus a safe message. An HTTP surface for operations, if one is added again, maps it onto the -`Envelope` error contract. +code plus a safe message. + +The HTTP surface was added back on 2026-09-25 (owner decision 15) as a thin transport over the +application use cases: `adapter:inbound:web` `operation/DurableOperationController` — +`POST /operations` (202 + `Location`), `GET /operations/{id}`, `DELETE /operations/{id}` (202), +answers in the `Envelope` contract, and a caller's operation that is not theirs is the same 404 +(`OPERATION_NOT_FOUND`) as one that does not exist. The controller and the three use cases are +assembled by `app-bootstrap` `autoconfigure/operation/DurableOperationConfig`, which turns on only +when the operation store and the outbox append port exist (the JPA module with +`ca-skeleton.outbox.enabled=true`). Submit and cancel need `operation:submit` / `operation:cancel` +(`security.yml` grants both to the `operation-submit` role). The state machine is enforced three times on purpose: in `DurableOperation`'s constructor, in the `CHECK` constraints of `V11__durable_operation.sql`, and in the `WHERE` clause of every statement diff --git a/infra/keycloak/realms/ca-skeleton-realm.json b/infra/keycloak/realms/ca-skeleton-realm.json index f0c62bf9..1e00633b 100644 --- a/infra/keycloak/realms/ca-skeleton-realm.json +++ b/infra/keycloak/realms/ca-skeleton-realm.json @@ -26,6 +26,12 @@ "description": "Publish a notification template version. Separate from submit: publishing changes what every future submission renders.", "composite": false, "clientRole": true + }, + { + "name": "operation-submit", + "description": "Submit a durable operation and cancel one's own.", + "composite": false, + "clientRole": true } ] } @@ -96,7 +102,8 @@ "ca-skeleton-api": [ "graphql-query", "notification-submit", - "notification-template-publish" + "notification-template-publish", + "operation-submit" ] } } diff --git a/scripts/run-compose-runtime-smoke.sh b/scripts/run-compose-runtime-smoke.sh index c4083a99..3b32fdcc 100755 --- a/scripts/run-compose-runtime-smoke.sh +++ b/scripts/run-compose-runtime-smoke.sh @@ -8,7 +8,9 @@ # and a stale directory cannot be mistaken for this run's; # 2. the static contract, then `config`, then `create` — a stack that cannot render has no partial # failure mode, and finding that out after `up` costs a teardown; -# 3. `up --wait` for long-running services only, then the application's own health answer; +# 3. `up --wait` for long-running services only, then the application's own health answer and +# its /actuator/info report of which capabilities are on and which database vendor it resolved, +# compared with the lane's expectedCapabilitiesOn and expectedPersistenceVendor; # 4. every one-shot the lane declares, each of which must exit zero — a missing or skipped # required client is a lane failure, not a lane that had nothing to check; # 5. sanitized evidence; @@ -413,18 +415,57 @@ run_lane() { management_port="${management_port:-9001}" # Poll rather than trust `up --wait`. Not every overlay defines a healthcheck — the dev one does # not — and where there is none `--wait` returns as soon as the container is created. - local attempt + local attempt answered="" for attempt in $(seq 1 60); do if docker compose -p "${PROJECT}" "${LANE_ARGS[@]}" exec -T app \ wget -qO- "http://localhost:${management_port}/actuator/health" \ >"${LANE_EVIDENCE}/health.json" 2>/dev/null \ && [[ -s "${LANE_EVIDENCE}/health.json" ]]; then - return 0 + answered=yes + break fi sleep 5 done - echo "${id}: the application never answered /actuator/health on port ${management_port}" >&2 - return 1 + if [[ -z "${answered}" ]]; then + echo "${id}: the application never answered /actuator/health on port ${management_port}" >&2 + return 1 + fi + + # Which capabilities the application turned on, and the relational vendor it resolved. Without + # this a lane called local-jpa that ran with JPA off would render the right services, start + # cleanly, and prove nothing. Each capability module ships info.capabilities. beside its + # switch (management.info.env), so the application must name every capability the contract + # catalogues — true or false — and a name that is missing is a module that is missing. + if ! docker compose -p "${PROJECT}" "${LANE_ARGS[@]}" exec -T app \ + wget -qO- "http://localhost:${management_port}/actuator/info" \ + >"${LANE_EVIDENCE}/info.json" 2>/dev/null \ + || ! jq -e 'type == "object"' "${LANE_EVIDENCE}/info.json" >/dev/null 2>&1; then + echo "${id}: the application did not answer /actuator/info with a JSON object" >&2 + return 1 + fi + local catalogued reported + catalogued="$(jq -r '.capabilities | sort | join(",")' "${CONTRACTS}")" + reported="$(jq -r '.capabilities // {} | keys | sort | join(",")' "${LANE_EVIDENCE}/info.json")" + if [[ "${catalogued}" != "${reported}" ]]; then + echo "${id}: the application reports capabilities [${reported}], the contract catalogues [${catalogued}]" >&2 + return 1 + fi + local expected_on actual_on + expected_on="$(jq -r '.expectedCapabilitiesOn | sort | join(",")' <<<"${lane_json}")" + actual_on="$(jq -r '[.capabilities | to_entries[] | select((.value.enabled | tostring) == "true") | .key] | sort | join(",")' \ + "${LANE_EVIDENCE}/info.json")" + if [[ "${expected_on}" != "${actual_on}" ]]; then + echo "${id}: the application reports [${actual_on}] on, the contract expects [${expected_on}]" >&2 + return 1 + fi + local expected_vendor actual_vendor + expected_vendor="$(jq -r '.expectedPersistenceVendor' <<<"${lane_json}")" + actual_vendor="$(jq -r '.capabilities["persistence-jpa"] | if (.enabled | tostring) == "true" then .vendor else "none" end' \ + "${LANE_EVIDENCE}/info.json")" + if [[ "${expected_vendor}" != "${actual_vendor}" ]]; then + echo "${id}: the application resolved vendor '${actual_vendor}', the contract expects '${expected_vendor}'" >&2 + return 1 + fi } await_application_report || return 1 @@ -449,6 +490,7 @@ run_lane() { fi redact_in_place "${LANE_EVIDENCE}/notification-smoke-phase1.log" cp "${LANE_EVIDENCE}/health.json" "${LANE_EVIDENCE}/health-phase1.json" + cp "${LANE_EVIDENCE}/info.json" "${LANE_EVIDENCE}/info-phase1.json" # The application only. The database and its volume stay up, which is the whole point. echo "-- ${id}: restarting the application into the second phase" diff --git a/scripts/verify-compose-profile-contracts.sh b/scripts/verify-compose-profile-contracts.sh index 9697d99b..7eac5c3d 100755 --- a/scripts/verify-compose-profile-contracts.sh +++ b/scripts/verify-compose-profile-contracts.sh @@ -1,7 +1,7 @@ #!/usr/bin/env bash # The static half of the Compose contract: every lane renders, and renders exactly what it claims. # -# Five things are checked, and each exists because assuming it cost something: +# Six things are checked, and each exists because assuming it cost something: # # 1. the Compose version, because `!override` is what stops the dev overlay's tmpfs merging with # the base's and colliding with a bind mount, and it needs 2.24.4; @@ -14,7 +14,10 @@ # distinct"; # 5. the service-role partition, because a service the lane renders and files under no role is # started by nothing and checked by nothing, and a one-shot filed as a --wait target hangs the -# lane for its full timeout on a container that was built to exit. +# lane for its full timeout on a container that was built to exit; +# 6. the expected application report (expectedCapabilitiesOn, expectedPersistenceVendor) names +# only catalogued capabilities and a vendor that agrees with persistence-jpa, because an +# expectation the application cannot report fails every run of the lane. # # Static only. Nothing starts here; scripts/run-compose-runtime-smoke.sh owns that. set -euo pipefail @@ -127,10 +130,25 @@ for index in $(seq 0 $((lane_count - 1))); do | select(length > 0) | join(",")' "${CONTRACTS}")" [[ -n "${uncatalogued}" ]] && fail "${id}: [${uncatalogued}] are run with \`run --rm\` but are in neither top-level catalogue" + # 6. what the lane expects the application to report is something it can report. The wrapper + # compares expectedCapabilitiesOn with the names under info.capabilities whose enabled is true, and + # the whole reported set with the top-level `capabilities` catalogue; a name outside the catalogue + # can never match. The vendor is reported only while persistence-jpa is on, so a vendor expected + # with JPA off, or none expected with it on, is a contract that fails every run. + expectation="$(jq -r --argjson lane "${lane}" ' + ( ($lane.expectedCapabilitiesOn // []) - (.capabilities // []) ) as $unknown + | ( ($lane.expectedCapabilitiesOn // []) | index("persistence-jpa") != null ) as $jpa + | [ (if ($unknown | length) > 0 then "uncatalogued=[\($unknown | join(","))]" else empty end), + (if $jpa == ($lane.expectedPersistenceVendor == "none") + then "vendor \($lane.expectedPersistenceVendor) with persistence-jpa \(if $jpa then "on" else "off" end)" + else empty end) ] + | join(" ")' "${CONTRACTS}")" + [[ -n "${expectation}" ]] && fail "${id}: the expected application report is unreachable — ${expectation}" + [[ ${FAILURES} -eq 0 ]] && echo "${id}: ${expected} @ ${runtime}" done -# 6. the Keycloak realm artifact deserializes into Keycloak's own representation. +# 7. the Keycloak realm artifact deserializes into Keycloak's own representation. # # Keycloak rejects unknown fields rather than ignoring them, so one annotation key anywhere in the # tree fails the whole import, the container exits 1, and every lane that needs an identity provider diff --git a/src/README.md b/src/README.md index d2d73486..2b8ffbe7 100644 --- a/src/README.md +++ b/src/README.md @@ -266,8 +266,8 @@ Kafka 없이 기동합니다. 나머지 기능은 `app-bootstrap/build.gradle` | 외부 HTTP 호출 | `runtimeOnly project(':adapter:outbound:httpclient')` | client 하나 이상: `APP_HTTPCLIENT_CLIENTS_0_*` (`docs/httpclient/env-fields.yaml`) | `APP_HTTPCLIENT_ENABLED` | | 객체 저장소 (S3/로컬) | `runtimeOnly project(':adapter:outbound:objectstorage')` | 전용 env 없음. `app.object-storage.*`의 provider·destination을 `application-*.yml`에 적음 | `app.object-storage.enabled` | | WebSocket (STOMP push) | `runtimeOnly project(':adapter:inbound:websocket')` | 없음(기본값으로 동작). origin은 `APP_WEBSOCKET_ALLOWED_ORIGINS` | `APP_WEBSOCKET_ENABLED` | -| gRPC 서버 | `runtimeOnly project(':adapter:inbound:grpc')` | `CA_SKELETON_GRPC_ALLOW_INSECURE_LOCAL=true` (지금 받는 listener가 loopback plaintext뿐) | `ca-skeleton.grpc.enabled` | -| 파일 서버 (JPA 줄도 필요) | `runtimeOnly project(':composition:fileserver-platform')` | `APP_FILESERVER_PLATFORM_STORAGE_ROOT`, `APP_FILESERVER_PLATFORM_OBSERVABILITY_FINGERPRINT_KEY`, 그리고 `FileAccessPolicy` bean 또는 `APP_FILESERVER_PLATFORM_SECURITY_ACCESS_POLICY=role-based` | `APP_FILESERVER_PLATFORM_ENABLED` | +| gRPC 서버 | `runtimeOnly project(':adapter:inbound:grpc')` | `CA_SKELETON_GRPC_SERVER_ALLOW_INSECURE_LOCAL=true` (지금 받는 listener가 loopback plaintext뿐) | `ca-skeleton.grpc.server.enabled` | +| 파일 서버 (JPA를 함께 가져옴) | `runtimeOnly project(':composition:fileserver-platform')` | `APP_FILESERVER_PLATFORM_STORAGE_ROOT`, `APP_FILESERVER_PLATFORM_OBSERVABILITY_FINGERPRINT_KEY`, 그리고 `FileAccessPolicy` bean 또는 `APP_FILESERVER_PLATFORM_SECURITY_ACCESS_POLICY=role-based` | `APP_FILESERVER_PLATFORM_ENABLED` | | 알림 (SMTP/SES, JPA 줄도 필요) | `runtimeOnly project(':composition:notification-platform')` | 키 8종과 각 `_ID`(`APP_NOTIFICATION_PLATFORM_*_KEY`, `*_KEY_ID`), 쓰는 provider 설정(`APP_NOTIFICATION_PLATFORM_SMTP_*` 또는 `_SES_*`) | `APP_NOTIFICATION_PLATFORM_ENABLED` | 전체 목록과 타입·기본값은 `docs/registries/env-keys.yaml`, 각 모듈이 제공하는 것은 그 모듈 README의 @@ -323,7 +323,8 @@ Kafka·Redis는 위 "기능 추가 = 한 줄 + env" 표의 한 줄로 고릅니 broker)라 보통 비워 두지 않습니다. 빈 값을 주면 기동이 거부되면서 이 키 이름을 지목합니다. 이 키를 비워도 메시징이 꺼지지는 않습니다 — 끄는 것은 `APP_MESSAGING_ENABLED=false`입니다. - **`APP_MESSAGING_KAFKA_BROKERS`** — `host:port` CSV. Kafka 모듈을 고르면 필수. legacy seam과 - messaging platform의 Kafka transport(`spring.kafka.bootstrap-servers`)가 같은 값을 씁니다. + messaging platform의 Kafka transport(`app.messaging.brokers.kafka.bootstrap-servers`)가 같은 값을 + 씁니다. `spring.kafka.bootstrap-servers`는 읽지 않습니다. - **`APP_NOTIFICATION_SLACK_WEBHOOK_ENABLED`** — Slack webhook R0 provider enable flag. notification 플랫폼이 켜졌을 때 어떤 provider를 쓸지 고르는 값입니다. - **`APP_NOTIFICATION_GOOGLE_EMAIL_ENABLED`** — Google Email R0 provider enable flag. 위와 같습니다. @@ -405,7 +406,7 @@ ca-skeleton: - **`OTEL_EXPORTER_OTLP_ENDPOINT`** — OTLP exporter endpoint. 빈 값 = exporter off(스켈레톤에서 OTel SEAM 미활성). 값이 있으면 유효한 URL 이어야 하며 기동 시 `TracingProperties` 가 검증합니다. - **`APP_TRACING_ENABLED`** — `false` 면 tracing seam 은 꺼지지만, `meta.traceId` 는 - `RequestLoggingFilter` 가 W3C `traceparent` 로 여전히 생성합니다(D4 disabled-fallback 보장). + `WebMvcRequestIdFilter` 가 W3C `traceparent` 로 여전히 생성합니다(D4 disabled-fallback 보장). - **`APP_TRACING_SAMPLE_RATE`** — per-profile 기본값을 덮어쓰는 샘플 비율. [0.0, 1.0] float. - per-profile 기본값(D6): prod = `0.01`, staging = `0.10`, dev/local = `1.0`. - **결정 — 빈 값으로 두는 이유(D-1 ISSUE-1 fix).** 빈 값이어야 per-profile resolver 의 기본값이 diff --git a/src/adapter/inbound/graphql/CLAUDE.md b/src/adapter/inbound/graphql/CLAUDE.md index 7c9e22f7..c14cd514 100644 --- a/src/adapter/inbound/graphql/CLAUDE.md +++ b/src/adapter/inbound/graphql/CLAUDE.md @@ -117,9 +117,11 @@ application/platform namespace split. ## Error mapping (`Category → ErrorType`) -feature 는 `ApiErrorCarrier` 를 구현한 예외(자신의 `ApiErrorCode` 를 실어)를 던지면 -`GraphqlExceptionResolver` 가 `GraphQLError`(ErrorType + `extensions{code, category}`)로 매핑한다. -비-`ApiErrorCarrier` 예외는 `null` 반환 → 다른 resolver / Spring 기본 처리. 표는 [README.md](README.md). +모든 client 에러는 `runtime/GraphQlWireErrorMapper` 하나를 거친다 — 전송 interceptor, 실행 전 +pipeline(instrumentation), data fetcher resolver 세 곳이 같은 bean 을 받는다. 순서는 플랫폼 거부 +(`GraphQlPlatformRejectionMapper.mapKnown`) → `ApiErrorCarrier`(자기 `ApiErrorCode`) → 등록된 +application 매핑(`GraphQlExceptionResolver`). 어디에도 안 걸린 예외는 `INTERNAL_ERROR` 로 가려지고, +같은 executionId 로 ERROR 로그 한 줄이 남는다. 표는 [README.md](README.md). ## 향후 adopter 의 feature 기여 방법 @@ -169,9 +171,6 @@ health 스키마만 소유한다. replay 등)는 바인딩되지 않는 feature flag gate 뒤의 모델뿐이어서 2026-09-25 에 삭제했다 (`docs/capability-status.md` 제거 표). 다시 필요하면 Spring GraphQL/graphql-java SPI 를 구현하는 형태로 새로 만든다. -- 요청 단계 거부(`GraphQlPlatformWebInterceptor`, `GraphQlPlatformInstrumentation`)는 - `GraphQlWireErrorMapper` 를 거치지 않고 `GraphQlPlatformRejectionMapper.map` 을 직접 부른다. - 그래서 요청 단계의 `ApiErrorCarrier` 는 `INTERNAL_ERROR` 가 된다(리뷰 S5 #6, 미해결). ## Test diff --git a/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/autoconfigure/GraphQlPlatformAutoConfiguration.java b/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/autoconfigure/GraphQlPlatformAutoConfiguration.java index 2afcfa98..3efed6c7 100644 --- a/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/autoconfigure/GraphQlPlatformAutoConfiguration.java +++ b/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/autoconfigure/GraphQlPlatformAutoConfiguration.java @@ -229,13 +229,30 @@ public class GraphQlPlatformAutoConfiguration { /** * How a request is authenticated. * - *

Anonymous by default, because authentication belongs to the composition root. This is not a - * permissive default in itself: what an anonymous caller may do is decided by the authorization - * policy and the client profile, both of which are checked on every request. + *

Anonymous by default in a development mode, because authentication belongs to the + * composition root. What an anonymous caller may do is decided by the authorization policy and + * the client profile, both of which are checked on every request. + * + *

A production mode refuses anonymous callers outright, so the anonymous default there started + * an endpoint that answered every request with {@code AUTHENTICATION_REQUIRED}. That is the same + * missing composition decision as a missing authorization policy, and it fails the same way: at + * startup, by name. */ @Bean @ConditionalOnMissingBean - public GraphQlPrincipalResolver graphQlPrincipalResolver() { + public GraphQlPrincipalResolver graphQlPrincipalResolver(GraphQlPlatformSettings properties) { + if (properties.deploymentMode() == null) { + throw new GraphQlPlatformConfigurationException( + List.of(GraphQlDeploymentMode.REQUIRED_MESSAGE)); + } + if (properties.production()) { + throw new GraphQlPlatformConfigurationException( + List.of( + "backend.graphql.deployment-mode=" + + properties.deploymentMode() + + " requires an explicit GraphQlPrincipalResolver bean; production refuses " + + "anonymous callers, so the anonymous default would reject every request")); + } return GraphQlPrincipalResolver.anonymous(); } @@ -336,8 +353,9 @@ public class GraphQlPlatformAutoConfiguration { */ @Bean @ConditionalOnMissingBean(GraphQlPlatformInstrumentation.class) - public Instrumentation graphQlPlatformInstrumentation(GraphQlExecutionChain chain) { - return new GraphQlPlatformInstrumentation(chain); + public Instrumentation graphQlPlatformInstrumentation( + GraphQlExecutionChain chain, GraphQlWireErrorMapper errors) { + return new GraphQlPlatformInstrumentation(chain, errors); } /** @@ -391,7 +409,8 @@ public class GraphQlPlatformAutoConfiguration { GraphQlJsonStructurePolicy structurePolicy, GraphQlExtensionsPolicy extensionsPolicy, GraphQlPlatformSettings properties, - Clock graphQlPlatformClock) { + Clock graphQlPlatformClock, + GraphQlWireErrorMapper errors) { return new GraphQlPlatformWebInterceptor( principalResolver, contextFactory, @@ -401,7 +420,8 @@ public class GraphQlPlatformAutoConfiguration { new GraphQlClientProfile(DEFAULT_ANONYMOUS_PROFILE), TenantContext.system(DEFAULT_ANONYMOUS_TENANT), properties.production(), - graphQlPlatformClock); + graphQlPlatformClock, + errors); } /** The approved scalar set; the wiring configurer refuses to wire anything absent from it. */ diff --git a/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/context/TenantContext.java b/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/context/TenantContext.java index 7471079a..8a7a87a6 100644 --- a/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/context/TenantContext.java +++ b/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/context/TenantContext.java @@ -1,5 +1,7 @@ package dev.caskeleton.adapter.inbound.graphql.context; +import java.util.regex.Pattern; + /** * The tenant a request executes in, together with where that decision came from. * @@ -14,7 +16,13 @@ package dev.caskeleton.adapter.inbound.graphql.context; */ public record TenantContext(String value, TenantSource source) { - private static final int MAXIMUM_LENGTH = 128; + /** + * The web transport's tenant grammar ({@code adapter.inbound.web.core.TenantContext}). + * + *

Duplicated on purpose until the shared tenant value type exists (review S5-lead-3, Wave 3): + * while the two transports disagreed, the same tenant passed one and was refused by the other. + */ + private static final Pattern GRAMMAR = Pattern.compile("[A-Za-z0-9][A-Za-z0-9_.-]{0,63}"); /** Trusted inputs a tenant may be derived from. */ public enum TenantSource { @@ -27,8 +35,8 @@ public record TenantContext(String value, TenantSource source) { } public TenantContext { - if (value == null || value.isBlank() || value.length() > MAXIMUM_LENGTH) { - throw new IllegalArgumentException("tenant identity is required and bounded"); + if (value == null || !GRAMMAR.matcher(value).matches()) { + throw new IllegalArgumentException("tenant identity must match " + GRAMMAR.pattern()); } if (source == null) { throw new IllegalArgumentException("tenant source is required"); diff --git a/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/cost/GraphQlDocumentShapeAnalyzer.java b/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/cost/GraphQlDocumentShapeAnalyzer.java index cbed063b..768d33ef 100644 --- a/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/cost/GraphQlDocumentShapeAnalyzer.java +++ b/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/cost/GraphQlDocumentShapeAnalyzer.java @@ -37,9 +37,18 @@ import java.util.Set; */ public final class GraphQlDocumentShapeAnalyzer { - /** Prefix that marks an introspection field. */ + /** Prefix that marks a meta field ({@code __schema}, {@code __type}, {@code __typename}). */ public static final String INTROSPECTION_FIELD_PREFIX = "__"; + /** + * The meta fields that disclose the schema. + * + *

{@code __typename} is not one of them: it names the type of an object the caller already + * received, and Apollo and urql add it to every selection set. Gating it with the schema fields + * refused every query those clients send once introspection was off. + */ + private static final Set SCHEMA_DISCLOSING_FIELDS = Set.of("__schema", "__type"); + private final int maximumVisitedNodes; /** Creates an analyzer with the default traversal budget. */ @@ -209,7 +218,7 @@ public final class GraphQlDocumentShapeAnalyzer { counters.visit(maximumVisitedNodes); if (selection instanceof Field field) { - if (field.getName().startsWith(INTROSPECTION_FIELD_PREFIX) + if (SCHEMA_DISCLOSING_FIELDS.contains(field.getName()) || selectsIntrospection(field.getSelectionSet(), fragments, expanded, counters)) { return true; } diff --git a/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/error/GraphQlErrorCode.java b/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/error/GraphQlErrorCode.java index dea9c001..49c8fa89 100644 --- a/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/error/GraphQlErrorCode.java +++ b/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/error/GraphQlErrorCode.java @@ -44,6 +44,9 @@ public record GraphQlErrorCode(String value) { /** Stable operation-name rejection. */ public static final String GRAPHQL_OPERATION_NAME_REQUIRED = "GRAPHQL_OPERATION_NAME_REQUIRED"; + /** A DataLoader key declared always resolvable had no row. */ + public static final String GRAPHQL_BATCH_KEY_MISSING = "GRAPHQL_BATCH_KEY_MISSING"; + private static final Set LEGACY_UNPREFIXED_PLATFORM_CODES = Set.of( INTERNAL_ERROR, @@ -65,7 +68,8 @@ public record GraphQlErrorCode(String value) { DEPENDENCY_UNAVAILABLE, GRAPHQL_DOCUMENT_SHAPE_REJECTED, GRAPHQL_COMPLEXITY_EXCEEDED, - GRAPHQL_OPERATION_NAME_REQUIRED); + GRAPHQL_OPERATION_NAME_REQUIRED, + GRAPHQL_BATCH_KEY_MISSING); private static final Pattern PATTERN = Pattern.compile("[A-Z][A-Z0-9_]{2,63}"); diff --git a/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/error/GraphQlExceptionResolver.java b/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/error/GraphQlExceptionResolver.java index e4b1a4a9..c457ea08 100644 --- a/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/error/GraphQlExceptionResolver.java +++ b/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/error/GraphQlExceptionResolver.java @@ -2,6 +2,8 @@ package dev.caskeleton.adapter.inbound.graphql.error; import java.util.LinkedHashMap; import java.util.Map; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; /** * Maps a resolver failure onto the wire (design §16, Stable plan Task 25). @@ -16,6 +18,8 @@ import java.util.Map; */ public final class GraphQlExceptionResolver { + private static final Logger LOG = LoggerFactory.getLogger(GraphQlExceptionResolver.class); + private final Map, Mapping> mappings; private GraphQlExceptionResolver(Map, Mapping> mappings) { @@ -52,6 +56,13 @@ public final class GraphQlExceptionResolver { context); } } + // The client gets an opaque error and this execution id; the log line under the same id is the + // only place the cause survives. Without it the id pointed at nothing. + LOG.error( + "graphql failure masked as {} (executionId={})", + GraphQlErrorCode.INTERNAL_ERROR, + context.executionId(), + failure); return GraphQlInternalErrorMasker.mask(context); } diff --git a/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlDataFetcherExceptionResolver.java b/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlDataFetcherExceptionResolver.java index d875ed2f..a29a1b08 100644 --- a/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlDataFetcherExceptionResolver.java +++ b/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlDataFetcherExceptionResolver.java @@ -1,7 +1,6 @@ package dev.caskeleton.adapter.inbound.graphql.runtime; import dev.caskeleton.adapter.inbound.graphql.error.GraphQlErrorContext; -import dev.caskeleton.adapter.inbound.graphql.error.GraphQlWireError; import graphql.GraphQLError; import graphql.schema.DataFetchingEnvironment; import java.util.List; @@ -34,14 +33,7 @@ public final class GraphQlDataFetcherExceptionResolver extends DataFetcherExcept @Override protected GraphQLError resolveToSingleError(Throwable failure, DataFetchingEnvironment env) { - GraphQlWireError wireError = mapper.mapFieldFailure(failure, errorContext(env)); - // A carrier still knows its operational category, which is finer than the six wire categories. - // Classifying from it keeps `NOT_FOUND` distinguishable from any other business outcome. - if (failure instanceof dev.caskeleton.shared.error.ApiErrorCarrier carrier) { - return GraphQlWireErrors.toGraphQlError( - wireError, GraphQlWireErrors.classificationOf(carrier.errorCode().category())); - } - return GraphQlWireErrors.toGraphQlError(wireError); + return mapper.toGraphQlError(failure, errorContext(env)); } /** diff --git a/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlPlatformInstrumentation.java b/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlPlatformInstrumentation.java index 57b80b6c..f7b28340 100644 --- a/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlPlatformInstrumentation.java +++ b/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlPlatformInstrumentation.java @@ -33,14 +33,18 @@ public final class GraphQlPlatformInstrumentation extends SimplePerformantInstru public static final String MISSING_CONTEXT_CONSTRAINT = "PLATFORM_CONTEXT"; private final GraphQlExecutionChain chain; + private final GraphQlWireErrorMapper errors; /** * Creates the instrumentation. * * @param chain the executable policy chain + * @param errors the mapper every client-visible error goes through */ - public GraphQlPlatformInstrumentation(GraphQlExecutionChain chain) { + public GraphQlPlatformInstrumentation( + GraphQlExecutionChain chain, GraphQlWireErrorMapper errors) { this.chain = Objects.requireNonNull(chain, "execution chain is required"); + this.errors = Objects.requireNonNull(errors, "wire error mapper is required"); } /** The pipeline this instrumentation enforces, derived from the chain. */ @@ -82,10 +86,7 @@ public final class GraphQlPlatformInstrumentation extends SimplePerformantInstru GraphQlExecutionContext.starting( request, requestContext, execution.getGraphQLSchema(), execution.getDocument())); } catch (RuntimeException rejection) { - throw new AbortExecutionException( - List.of( - GraphQlWireErrors.toGraphQlError( - GraphQlPlatformRejectionMapper.map(rejection, errorContext)))); + throw new AbortExecutionException(List.of(errors.toGraphQlError(rejection, errorContext))); } // Publish the context the pipeline actually settled on. The transport could only build a diff --git a/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlPlatformRejectionMapper.java b/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlPlatformRejectionMapper.java index 4b661ad9..61f3ffc6 100644 --- a/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlPlatformRejectionMapper.java +++ b/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlPlatformRejectionMapper.java @@ -2,6 +2,8 @@ package dev.caskeleton.adapter.inbound.graphql.runtime; import dev.caskeleton.adapter.inbound.graphql.cost.GraphQlComplexityRejectedException; import dev.caskeleton.adapter.inbound.graphql.cost.GraphQlStructuralLimitException; +import dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlBatchTimeoutException; +import dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlMissingKeyException; import dev.caskeleton.adapter.inbound.graphql.error.GraphQlErrorCategory; import dev.caskeleton.adapter.inbound.graphql.error.GraphQlErrorCode; import dev.caskeleton.adapter.inbound.graphql.error.GraphQlErrorContext; @@ -23,26 +25,13 @@ import dev.caskeleton.adapter.inbound.graphql.security.GraphQlTenantIsolationExc * code, a bounded category and no internal detail. Doing that per stage would produce as many error * vocabularies as there are stages, and the one that forgot would leak an exception message. * - *

An unrecognised exception maps to the opaque internal error rather than to its own message. - * That is the fail-closed direction: a new rejection type that nobody mapped shows up as {@code - * INTERNAL_ERROR} in the client's response and in full in the logs, instead of publishing whatever - * the exception happened to say. + *

This is the platform's catalogue only. {@link GraphQlWireErrorMapper} consults it first and + * falls back to the application's mappings, which mask and log anything unrecognised. */ public final class GraphQlPlatformRejectionMapper { private GraphQlPlatformRejectionMapper() {} - /** - * Maps a rejection thrown by a pipeline stage. - * - * @param failure the exception a handler threw - * @param context correlation identity for the response - */ - public static GraphQlWireError map(Throwable failure, GraphQlErrorContext context) { - GraphQlWireError known = mapKnown(failure, context); - return known != null ? known : GraphQlWireError.internal(context.executionId()); - } - /** * Maps a rejection this platform raised, or {@code null} when it did not raise it. * @@ -111,13 +100,25 @@ public final class GraphQlPlatformRejectionMapper { GraphQlErrorCategory.REQUEST, context); } - if (failure instanceof GraphQlRequestCancelledException) { + // A batch that ran out of budget is the request running out of budget, one level down: the + // client can retry the same request and should be told so, not handed an opaque failure. + if (failure instanceof GraphQlRequestCancelledException + || failure instanceof GraphQlBatchTimeoutException) { return GraphQlWireError.of( "요청 처리 시간이 초과되었습니다.", GraphQlErrorCode.platform(GraphQlErrorCode.REQUEST_TIMEOUT), GraphQlErrorCategory.TIMEOUT, context); } + if (failure instanceof GraphQlMissingKeyException) { + // The loader declared this relation always resolvable and it did not resolve. The key is an + // object identifier, so the message names neither it nor the loader. + return GraphQlWireError.of( + "요청한 리소스를 찾을 수 없습니다.", + GraphQlErrorCode.platform(GraphQlMissingKeyException.CODE), + GraphQlErrorCategory.BUSINESS, + context); + } return null; } diff --git a/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlPlatformWebInterceptor.java b/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlPlatformWebInterceptor.java index 0d046fa3..16924b6a 100644 --- a/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlPlatformWebInterceptor.java +++ b/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlPlatformWebInterceptor.java @@ -5,7 +5,6 @@ import dev.caskeleton.adapter.inbound.graphql.context.GraphQlDeadline; import dev.caskeleton.adapter.inbound.graphql.context.GraphQlRequestContext; import dev.caskeleton.adapter.inbound.graphql.context.TenantContext; import dev.caskeleton.adapter.inbound.graphql.error.GraphQlErrorContext; -import dev.caskeleton.adapter.inbound.graphql.error.GraphQlWireError; import dev.caskeleton.adapter.inbound.graphql.http.GraphQlExtensionsPolicy; import dev.caskeleton.adapter.inbound.graphql.http.GraphQlJsonStructurePolicy; import dev.caskeleton.adapter.inbound.graphql.http.GraphQlRequestSize; @@ -51,6 +50,7 @@ public final class GraphQlPlatformWebInterceptor implements WebGraphQlIntercepto private final TenantContext anonymousTenant; private final boolean anonymousProfileProtected; private final Clock clock; + private final GraphQlWireErrorMapper errors; /** * Creates the interceptor. @@ -62,6 +62,7 @@ public final class GraphQlPlatformWebInterceptor implements WebGraphQlIntercepto * @param anonymousTenant tenant used when no credential is present * @param anonymousProfileProtected whether an anonymous request is refused outright * @param clock clock used for the request deadline + * @param errors the mapper every client-visible error goes through */ public GraphQlPlatformWebInterceptor( GraphQlPrincipalResolver principalResolver, @@ -72,7 +73,8 @@ public final class GraphQlPlatformWebInterceptor implements WebGraphQlIntercepto GraphQlClientProfile anonymousProfile, TenantContext anonymousTenant, boolean anonymousProfileProtected, - Clock clock) { + Clock clock, + GraphQlWireErrorMapper errors) { this.principalResolver = Objects.requireNonNull(principalResolver, "principal resolver"); this.contextFactory = Objects.requireNonNull(contextFactory, "context factory is required"); this.policy = Objects.requireNonNull(policy, "client policy is required"); @@ -83,6 +85,7 @@ public final class GraphQlPlatformWebInterceptor implements WebGraphQlIntercepto this.anonymousTenant = Objects.requireNonNull(anonymousTenant, "anonymous tenant"); this.anonymousProfileProtected = anonymousProfileProtected; this.clock = Objects.requireNonNull(clock, "clock is required"); + this.errors = Objects.requireNonNull(errors, "wire error mapper is required"); } @Override @@ -160,12 +163,9 @@ public final class GraphQlPlatformWebInterceptor implements WebGraphQlIntercepto private WebGraphQlResponse reject(WebGraphQlRequest request, RuntimeException rejection) { ExecutionInput input = request.toExecutionInput(); - String executionId = traceId(request); - GraphQlWireError wireError = - GraphQlPlatformRejectionMapper.map(rejection, GraphQlErrorContext.of(executionId)); ExecutionResult result = ExecutionResult.newExecutionResult() - .addError(GraphQlWireErrors.toGraphQlError(wireError)) + .addError(errors.toGraphQlError(rejection, GraphQlErrorContext.of(traceId(request)))) .build(); ExecutionGraphQlResponse response = new DefaultExecutionGraphQlResponse(input, result); return new WebGraphQlResponse(response); diff --git a/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlWireErrorMapper.java b/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlWireErrorMapper.java index 8b4eb089..4a8b6055 100644 --- a/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlWireErrorMapper.java +++ b/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlWireErrorMapper.java @@ -8,6 +8,7 @@ import dev.caskeleton.adapter.inbound.graphql.error.GraphQlWireError; import dev.caskeleton.shared.error.ApiErrorCarrier; import dev.caskeleton.shared.error.ApiErrorCode; import dev.caskeleton.shared.error.Category; +import graphql.GraphQLError; import java.util.Objects; /** @@ -20,16 +21,15 @@ import java.util.Objects; * the failure happened to take — and the two resolver classes differed only in the case of one * letter, so importing the wrong one compiled. * - *

Field-level failures route through here. Request-stage rejections do not yet: {@code - * GraphQlPlatformWebInterceptor} and {@code GraphQlPlatformInstrumentation} call {@link - * GraphQlPlatformRejectionMapper#map} directly, so an {@link ApiErrorCarrier} thrown before - * execution (for example by an adopter's {@code GraphQlPrincipalResolver}) becomes {@code - * INTERNAL_ERROR} there while the same exception from a resolver keeps its code. Both paths share - * the platform catalogue in {@link GraphQlPlatformRejectionMapper#mapKnown}. + *

Every stage routes through here: the transport interceptor, the pre-execution pipeline and the + * data-fetcher resolver all receive this bean. While the first two called the platform catalogue + * directly, an {@link ApiErrorCarrier} thrown before execution (for example by an adopter's {@code + * GraphQlPrincipalResolver}) became {@code INTERNAL_ERROR} while the same exception from a resolver + * kept its code. * *

An unrecognised failure never contributes its own message. That is the fail-closed direction: * a new exception type nobody mapped becomes an opaque internal error with a correlation id, and - * the detail stays in the logs. + * the detail goes to the log under that id ({@link GraphQlExceptionResolver}). */ public final class GraphQlWireErrorMapper { @@ -51,25 +51,40 @@ public final class GraphQlWireErrorMapper { } /** - * Maps a failure thrown by a data fetcher. + * Maps a failure from any stage: platform rejection first, then {@link ApiErrorCarrier}, then the + * registered application mappings, which mask anything they do not recognise. * *

Platform rejections are consulted first: an authorization denial raised from inside a * resolver means the same thing to a client as one raised before execution, and giving it a * different code because of where it was thrown would be an implementation detail on the wire. */ - public GraphQlWireError mapFieldFailure(Throwable failure, GraphQlErrorContext context) { + public GraphQlWireError map(Throwable failure, GraphQlErrorContext context) { GraphQlWireError platform = GraphQlPlatformRejectionMapper.mapKnown(failure, context); - return platform != null ? platform : mapCommon(failure, context); - } - - private GraphQlWireError mapCommon(Throwable failure, GraphQlErrorContext context) { + if (platform != null) { + return platform; + } if (failure instanceof ApiErrorCarrier carrier) { return fromApiError(carrier.errorCode(), context); } - // The registered application mappings, which mask anything they do not recognise. return applicationMappings.resolve(failure, context); } + /** + * Maps a failure and renders it as the engine's error type. + * + *

A carrier still knows its operational category, which is finer than the six wire categories. + * Classifying from it keeps {@code NOT_FOUND} distinguishable from any other business outcome, + * and does so the same way whichever stage threw. + */ + public GraphQLError toGraphQlError(Throwable failure, GraphQlErrorContext context) { + GraphQlWireError wireError = map(failure, context); + if (failure instanceof ApiErrorCarrier carrier) { + return GraphQlWireErrors.toGraphQlError( + wireError, GraphQlWireErrors.classificationOf(carrier.errorCode().category())); + } + return GraphQlWireErrors.toGraphQlError(wireError); + } + /** * Maps the shared operational error code onto the GraphQL wire vocabulary. * diff --git a/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/runtime/servlet/GraphQlRequestBodyLimitFilter.java b/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/runtime/servlet/GraphQlRequestBodyLimitFilter.java index fec1cfb7..de87f5a9 100644 --- a/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/runtime/servlet/GraphQlRequestBodyLimitFilter.java +++ b/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/runtime/servlet/GraphQlRequestBodyLimitFilter.java @@ -82,13 +82,30 @@ public final class GraphQlRequestBodyLimitFilter implements Filter { try { chain.doFilter(new BoundedBodyRequest(httpRequest, maxBodyBytes), response); - } catch (BodyTooLargeException tooLarge) { + } catch (IOException | ServletException | RuntimeException failure) { + // The overflow is thrown inside the decoder, and it does not come back as itself: Spring's + // FrameworkServlet wraps an unchecked handler failure in a ServletException, which a catch of + // the exact type let through as a 500. + if (!causedByOverflow(failure)) { + throw failure; + } if (!httpResponse.isCommitted()) { reject(httpResponse); } } } + private static boolean causedByOverflow(Throwable failure) { + // Bounded, because a cause chain can loop and this runs on every failed request. + int depth = 0; + for (Throwable cause = failure; cause != null && depth++ < 16; cause = cause.getCause()) { + if (cause instanceof BodyTooLargeException) { + return true; + } + } + return false; + } + private boolean guards(HttpServletRequest request) { String path = request.getRequestURI(); return path != null && path.equals(request.getContextPath() + graphQlPath); diff --git a/src/adapter/inbound/graphql/src/main/resources/config/graphql.yml b/src/adapter/inbound/graphql/src/main/resources/config/graphql.yml index c100982b..f40b5a94 100644 --- a/src/adapter/inbound/graphql/src/main/resources/config/graphql.yml +++ b/src/adapter/inbound/graphql/src/main/resources/config/graphql.yml @@ -22,3 +22,11 @@ backend: preparsed-cache-entries: ${APP_GRAPHQL_PREPARSED_CACHE_ENTRIES:1000} preparsed-cache-weight: ${APP_GRAPHQL_PREPARSED_CACHE_WEIGHT:10000000} preparsed-cache-expire-after-access: ${APP_GRAPHQL_PREPARSED_CACHE_EXPIRE_AFTER_ACCESS:30m} + +# /actuator/info 에 싣는 이 모듈의 상태(management.info.env). compose smoke 가 lane 이 실제로 켠 +# capability 를 이 값으로 확인한다. 위 스위치를 해석한 값이고, 기본값은 GraphQlRootAutoConfiguration 의 +# matchIfMissing 과 같다. +info: + capabilities: + graphql: + enabled: ${backend.graphql.enabled:true} diff --git a/src/adapter/inbound/graphql/src/systemTest/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlPlatformExecutionPathTest.java b/src/adapter/inbound/graphql/src/systemTest/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlPlatformExecutionPathTest.java index 759ea8ae..e6221dbd 100644 --- a/src/adapter/inbound/graphql/src/systemTest/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlPlatformExecutionPathTest.java +++ b/src/adapter/inbound/graphql/src/systemTest/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlPlatformExecutionPathTest.java @@ -10,11 +10,17 @@ import dev.caskeleton.adapter.inbound.graphql.context.GraphQlRequestContext; import dev.caskeleton.adapter.inbound.graphql.execution.BoundedPreparsedDocumentProvider; import dev.caskeleton.adapter.inbound.graphql.policy.GraphQlClientPolicy; import dev.caskeleton.adapter.inbound.graphql.security.GraphQlAuthorizationPolicy; +import java.io.ByteArrayInputStream; import java.net.URI; +import java.net.http.HttpClient; +import java.net.http.HttpRequest; +import java.net.http.HttpResponse; +import java.nio.charset.StandardCharsets; import java.time.Instant; import java.util.concurrent.atomic.AtomicInteger; import java.util.concurrent.atomic.AtomicReference; import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.SpringBootConfiguration; @@ -153,6 +159,17 @@ class GraphQlPlatformExecutionPathTest { assertThat(response.getBody()).contains("INTROSPECTION"); } + @Test + @DisplayName("introspection 을 막은 profile 에서도 Apollo·urql 이 붙이는 __typename 은 통과한다") + void typenameIsAnsweredWhenTheClientProfileForbidsIntrospection() { + // when + ResponseEntity response = post("{ _health __typename }"); + + // then + assertThat(response.getBody()) + .isEqualTo("{\"data\":{\"_health\":\"UP\",\"__typename\":\"Query\"}}"); + } + @Test void introspectionHiddenBehindANamedFragmentIsStillRejected() { ResponseEntity response = @@ -241,6 +258,31 @@ class GraphQlPlatformExecutionPathTest { assertThat(RESOLVER_INVOCATIONS).as("an oversize body must never reach a resolver").hasValue(0); } + @Test + @DisplayName("Content-Length 없이 chunked 로 보낸 상한 초과 본문도 decoder 안에서 413 으로 거부된다") + void aChunkedBodyOverTheRawCapIsRefusedWith413() throws Exception { + // given + byte[] body = + ("{\"query\":\"{ platformStamp }\",\"padding\":\"" + "x".repeat(200_000) + "\"}") + .getBytes(StandardCharsets.UTF_8); + // An input-stream publisher has no length, so the request goes out chunked and only the + // counting stream — not the Content-Length check — can refuse it. + HttpRequest request = + HttpRequest.newBuilder(URI.create("http://localhost:" + port + "/graphql")) + .header("Content-Type", "application/json") + .POST(HttpRequest.BodyPublishers.ofInputStream(() -> new ByteArrayInputStream(body))) + .build(); + + // when + HttpResponse response; + try (HttpClient client = HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build()) { + response = client.send(request, HttpResponse.BodyHandlers.ofString()); + } + + // then + assertThat(response.statusCode()).isEqualTo(413); + } + @Test void theSecondIdenticalDocumentIsServedFromThePlatformParseCache() { long hitsBefore = preparsedCache.metrics().hits(); diff --git a/src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/autoconfigure/GraphQlDeploymentModeContractTest.java b/src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/autoconfigure/GraphQlDeploymentModeContractTest.java index ae6d2b8e..a6236eb0 100644 --- a/src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/autoconfigure/GraphQlDeploymentModeContractTest.java +++ b/src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/autoconfigure/GraphQlDeploymentModeContractTest.java @@ -4,12 +4,14 @@ import static org.assertj.core.api.Assertions.assertThat; import static org.assertj.core.api.Assertions.catchThrowable; import dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlPlatformWebInterceptor; +import dev.caskeleton.adapter.inbound.graphql.runtime.GraphQlPrincipalResolver; import dev.caskeleton.adapter.inbound.graphql.security.GraphQlAuthorizationPolicy; import dev.caskeleton.shared.runtime.RuntimeEnvironment; import java.util.Arrays; import java.util.LinkedHashMap; import java.util.List; import java.util.Map; +import java.util.Optional; import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; import org.junit.jupiter.params.ParameterizedTest; @@ -224,6 +226,34 @@ class GraphQlDeploymentModeContractTest { .hasMessageContaining("requires an explicit GraphQlAuthorizationPolicy")); } + @ParameterizedTest + @ValueSource(strings = {"PRODUCTION_INTERNAL", "PRODUCTION_PUBLIC"}) + @DisplayName("production 은 익명 principal resolver 로 떠서 모든 요청을 거부하는 대신 기동을 거부한다") + void aProductionModeRefusesTheAnonymousPrincipalResolver(String mode) { + runner + .withPropertyValues("backend.graphql.deployment-mode=" + mode) + .withBean( + GraphQlAuthorizationPolicy.class, () -> GraphQlAuthorizationPolicy.builder().build()) + .run( + context -> + assertThat(context) + .hasFailed() + .getFailure() + .rootCause() + .hasMessageContaining("requires an explicit GraphQlPrincipalResolver")); + } + + @Test + @DisplayName("production 은 인가 정책과 principal resolver 를 둘 다 주면 기동한다") + void aProductionModeWithAnExplicitPolicyAndResolverStarts() { + runner + .withPropertyValues("backend.graphql.deployment-mode=PRODUCTION_INTERNAL") + .withBean( + GraphQlAuthorizationPolicy.class, () -> GraphQlAuthorizationPolicy.builder().build()) + .withBean(GraphQlPrincipalResolver.class, () -> request -> Optional.empty()) + .run(context -> assertThat(context).hasNotFailed()); + } + @Test @DisplayName("the mode reaches the interceptor that decides what an anonymous caller may do") void theModeReachesTheRequestPath() { diff --git a/src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/context/GraphQlRequestContextTest.java b/src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/context/GraphQlRequestContextTest.java index 3eea1e12..803648fb 100644 --- a/src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/context/GraphQlRequestContextTest.java +++ b/src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/context/GraphQlRequestContextTest.java @@ -2,6 +2,7 @@ package dev.caskeleton.adapter.inbound.graphql.context; import static org.assertj.core.api.Assertions.assertThat; import static org.assertj.core.api.Assertions.assertThatThrownBy; +import static org.assertj.core.api.Assertions.catchThrowable; import dev.caskeleton.adapter.inbound.graphql.api.GraphQlClientProfile; import dev.caskeleton.adapter.inbound.graphql.api.GraphQlOperationId; @@ -10,7 +11,11 @@ import java.time.Duration; import java.time.Instant; import java.time.ZoneOffset; import java.util.Locale; +import java.util.stream.Stream; +import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.MethodSource; /** Immutable request context and layered deadline contract (Stable plan Task 3). */ class GraphQlRequestContextTest { @@ -47,6 +52,23 @@ class GraphQlRequestContextTest { TenantContext.TenantSource.SYSTEM); } + static Stream tenantsTheWebTransportRefuses() { + return Stream.of("tenant a", "tenant/a", "-tenant", "a".repeat(65)); + } + + @ParameterizedTest + @MethodSource("tenantsTheWebTransportRefuses") + @DisplayName("web 전송이 거부하는 tenant 는 GraphQL 도 거부한다 — 한 전송만 통과하는 tenant 가 없다") + void aTenantTheWebTransportRefusesIsRefusedHereToo(String tenant) { + // when + Throwable thrown = catchThrowable(() -> TenantContext.fromAuthenticatedCredential(tenant)); + + // then + assertThat(thrown) + .isInstanceOf(IllegalArgumentException.class) + .hasMessage("tenant identity must match [A-Za-z0-9][A-Za-z0-9_.-]{0,63}"); + } + @Test void actorAndTenantExposePartitionTokensInsteadOfRawIdentifiers() { ActorRef actor = ActorRef.authenticated("user-42"); diff --git a/src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/cost/GraphQlFragmentReachabilityTest.java b/src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/cost/GraphQlFragmentReachabilityTest.java index 922d25c3..167cf1b6 100644 --- a/src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/cost/GraphQlFragmentReachabilityTest.java +++ b/src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/cost/GraphQlFragmentReachabilityTest.java @@ -8,7 +8,10 @@ import graphql.language.Definition; import graphql.language.Document; import graphql.language.OperationDefinition; import graphql.parser.Parser; +import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.ValueSource; /** * The gate has to see what the request can reach, not what it wrote inline. @@ -47,6 +50,25 @@ class GraphQlFragmentReachabilityTest { assertThat(analyzer.selectsIntrospection(document)).isTrue(); } + @ParameterizedTest + @ValueSource( + strings = { + "{ _health __typename }", + "query Q { node { __typename id } }", + "query Q { ...N } fragment N on Query { node { __typename } }" + }) + @DisplayName("__typename 은 introspection 이 아니라서 introspection 을 끈 client 도 쓸 수 있다") + void typenameIsNotTreatedAsIntrospection(String query) { + // given + Document document = Parser.parse(query); + + // when + boolean selectsIntrospection = analyzer.selectsIntrospection(document); + + // then + assertThat(selectsIntrospection).isFalse(); + } + @Test void aFragmentCycleTerminatesRatherThanRecursingForever() { Document document = diff --git a/src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/error/GraphQlErrorCodeCatalogTest.java b/src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/error/GraphQlErrorCodeCatalogTest.java index d0623af3..a9d3c1d4 100644 --- a/src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/error/GraphQlErrorCodeCatalogTest.java +++ b/src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/error/GraphQlErrorCodeCatalogTest.java @@ -6,6 +6,7 @@ import static org.assertj.core.api.Assertions.assertThatThrownBy; import dev.caskeleton.adapter.inbound.graphql.cost.GraphQlComplexityRejectedException; import dev.caskeleton.adapter.inbound.graphql.cost.GraphQlStructuralLimitException; import dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlBatchTimeoutException; +import dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlMissingKeyException; import dev.caskeleton.adapter.inbound.graphql.execution.GraphQlAnonymousOperationException; import dev.caskeleton.adapter.inbound.graphql.pagination.GraphQlCursorException; import java.util.Set; @@ -26,8 +27,11 @@ class GraphQlErrorCodeCatalogTest { GraphQlErrorCode.DEPENDENCY_UNAVAILABLE, GraphQlErrorCode.GRAPHQL_DOCUMENT_SHAPE_REJECTED, GraphQlErrorCode.GRAPHQL_COMPLEXITY_EXCEEDED, - GraphQlErrorCode.GRAPHQL_OPERATION_NAME_REQUIRED); + GraphQlErrorCode.GRAPHQL_OPERATION_NAME_REQUIRED, + GraphQlErrorCode.GRAPHQL_BATCH_KEY_MISSING); + assertThat(GraphQlMissingKeyException.CODE) + .isEqualTo(GraphQlErrorCode.GRAPHQL_BATCH_KEY_MISSING); assertThat(GraphQlStructuralLimitException.CODE) .isEqualTo(GraphQlErrorCode.GRAPHQL_DOCUMENT_SHAPE_REJECTED); assertThat(GraphQlComplexityRejectedException.CODE) @@ -48,6 +52,8 @@ class GraphQlErrorCodeCatalogTest { .isTrue()); } + // A batch timeout is wired, but it reaches the wire as REQUEST_TIMEOUT: its own code names the + // loader-level cause for logs, not a separate thing a client should branch on. @Test void modelledOnlyCapabilityCodesDoNotPretendToBeShippedWireCodes() { assertThat(GraphQlErrorCode.platformCodes()) diff --git a/src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/error/GraphQlExceptionResolverTest.java b/src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/error/GraphQlExceptionResolverTest.java index fab11570..4600dd68 100644 --- a/src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/error/GraphQlExceptionResolverTest.java +++ b/src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/error/GraphQlExceptionResolverTest.java @@ -3,7 +3,13 @@ package dev.caskeleton.adapter.inbound.graphql.error; import static org.assertj.core.api.Assertions.assertThat; import static org.assertj.core.api.Assertions.assertThatThrownBy; +import ch.qos.logback.classic.Level; +import ch.qos.logback.classic.Logger; +import ch.qos.logback.classic.spi.ILoggingEvent; +import ch.qos.logback.core.read.ListAppender; +import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; +import org.slf4j.LoggerFactory; /** Exception resolution, masking and partial data (Stable plan Task 25). */ class GraphQlExceptionResolverTest { @@ -30,6 +36,37 @@ class GraphQlExceptionResolverTest { .containsEntry("code", GraphQlErrorCode.INTERNAL_ERROR); } + @Test + @DisplayName("가려진 실패는 client 가 받은 executionId 와 예외로 ERROR 로그 한 줄을 남긴다") + void aMaskedFailureIsLoggedOnceAtErrorWithItsExecutionId() { + // given + Logger logger = (Logger) LoggerFactory.getLogger(GraphQlExceptionResolver.class); + ListAppender appender = new ListAppender<>(); + appender.start(); + logger.addAppender(appender); + + // when + try { + GraphQlExceptionResolver.defaults() + .resolve(new IllegalStateException("pool exhausted"), GraphQlErrorContext.of("exec-9")); + } finally { + logger.detachAppender(appender); + appender.stop(); + } + + // then + assertThat(appender.list) + .singleElement() + .extracting( + ILoggingEvent::getLevel, + ILoggingEvent::getFormattedMessage, + event -> event.getThrowableProxy().getClassName()) + .containsExactly( + Level.ERROR, + "graphql failure masked as INTERNAL_ERROR (executionId=exec-9)", + IllegalStateException.class.getName()); + } + @Test void deliberatelyModelledFailuresKeepTheirCodeAndCategory() { GraphQlExceptionResolver resolver = diff --git a/src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlRequestStageErrorMappingTest.java b/src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlRequestStageErrorMappingTest.java new file mode 100644 index 00000000..9e84e133 --- /dev/null +++ b/src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlRequestStageErrorMappingTest.java @@ -0,0 +1,186 @@ +package dev.caskeleton.adapter.inbound.graphql.runtime; + +import static org.assertj.core.api.Assertions.assertThat; + +import dev.caskeleton.adapter.inbound.graphql.autoconfigure.GraphQlRootAutoConfiguration; +import dev.caskeleton.adapter.inbound.graphql.context.GraphQlRequestContext; +import dev.caskeleton.adapter.inbound.graphql.execution.GraphQlExecutionStage; +import dev.caskeleton.adapter.inbound.graphql.testkit.GraphQlRequestContexts; +import dev.caskeleton.shared.error.ApiErrorCarrier; +import dev.caskeleton.shared.error.ApiErrorCode; +import dev.caskeleton.shared.error.Category; +import graphql.ExecutionInput; +import graphql.ExecutionResult; +import graphql.GraphQL; +import graphql.schema.idl.SchemaParser; +import graphql.schema.idl.UnExecutableSchemaGenerator; +import java.net.URI; +import java.util.List; +import java.util.Locale; +import java.util.Map; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.springframework.boot.autoconfigure.AutoConfigurations; +import org.springframework.boot.test.context.runner.ApplicationContextRunner; +import org.springframework.graphql.server.WebGraphQlInterceptor; +import org.springframework.graphql.server.WebGraphQlRequest; +import org.springframework.graphql.server.WebGraphQlResponse; +import org.springframework.graphql.support.DefaultGraphQlRequest; +import org.springframework.http.HttpHeaders; +import org.springframework.util.LinkedMultiValueMap; +import reactor.core.publisher.Mono; + +/** + * A failure raised before execution meets the same mapper as one raised by a resolver. + * + *

The request stage — the transport interceptor and the pre-execution pipeline — used to map + * through the platform's own catalogue only, so an adopter's {@link ApiErrorCarrier} thrown there + * became {@code INTERNAL_ERROR} while the same exception from a resolver kept its code. Both cases + * go through the auto-configured beans, because "every path receives the mapper bean" is the + * property under test. + */ +class GraphQlRequestStageErrorMappingTest { + + private final ApplicationContextRunner runner = + new ApplicationContextRunner() + .withConfiguration(AutoConfigurations.of(GraphQlRootAutoConfiguration.class)) + .withPropertyValues( + "backend.graphql.enabled=true", "backend.graphql.deployment-mode=LOCAL"); + + @Test + @DisplayName("principal resolver 가 던진 ApiErrorCarrier 는 요청 단계에서도 자기 code 로 나간다") + void anApiErrorCarrierFromThePrincipalResolverKeepsItsCode() { + runner + .withBean( + GraphQlPrincipalResolver.class, + () -> + request -> { + throw new TenantSuspendedException(); + }) + .run( + context -> { + // given + WebGraphQlInterceptor interceptor = + context.getBean(GraphQlPlatformWebInterceptor.class); + + // when + WebGraphQlResponse response = + interceptor + .intercept( + request("{ _health }"), + next -> Mono.error(new AssertionError("a rejected request ran"))) + .block(); + + // then + assertThat(response.getErrors()) + .singleElement() + .extracting(error -> error.getExtensions().get("code")) + .isEqualTo("TENANT_SUSPENDED"); + }); + } + + @Test + @DisplayName("실행 전 pipeline 단계가 던진 ApiErrorCarrier 도 자기 code 로 나간다") + void anApiErrorCarrierFromAPipelineStageKeepsItsCode() { + runner + .withBean( + GraphQlExecutionChain.class, + () -> + new GraphQlExecutionChain( + List.of( + new Stage(GraphQlExecutionStage.PARSE_VALIDATE, false), + new Stage(GraphQlExecutionStage.AUTHORIZATION, true), + new Stage(GraphQlExecutionStage.COST, false)))) + .run( + context -> { + // given + GraphQL graphQl = + GraphQL.newGraphQL( + UnExecutableSchemaGenerator.makeUnExecutableSchema( + new SchemaParser().parse("type Query { _health: String }"))) + .instrumentation(context.getBean(GraphQlPlatformInstrumentation.class)) + .build(); + ExecutionInput input = + ExecutionInput.newExecutionInput("{ _health }") + .graphQLContext( + Map.of( + GraphQlRequestContext.CONTEXT_KEY, + GraphQlRequestContexts.testContext("tenant-a"))) + .build(); + + // when + ExecutionResult result = graphQl.execute(input); + + // then + assertThat(result.getErrors()) + .singleElement() + .extracting(error -> error.getExtensions().get("code")) + .isEqualTo("TENANT_SUSPENDED"); + }); + } + + private static WebGraphQlRequest request(String document) { + return new WebGraphQlRequest( + URI.create("http://localhost/graphql"), + new HttpHeaders(), + new LinkedMultiValueMap<>(), + null, + Map.of(), + new DefaultGraphQlRequest(document), + "request-1", + Locale.ROOT); + } + + /** A pipeline stage that passes the state through, or rejects with an adopter's carrier. */ + private record Stage(GraphQlExecutionStage stage, boolean rejects) + implements GraphQlExecutionHandler { + + @Override + public GraphQlExecutionContext handle(GraphQlExecutionContext context) { + if (rejects) { + throw new TenantSuspendedException(); + } + return context; + } + } + + /** An adopter's modelled failure, carrying its own stable code. */ + private static final class TenantSuspendedException extends RuntimeException + implements ApiErrorCarrier { + + private static final long serialVersionUID = 1L; + + TenantSuspendedException() { + super("tenant t-1 suspended by billing"); + } + + @Override + public ApiErrorCode errorCode() { + return AdopterErrorCode.TENANT_SUSPENDED; + } + } + + private enum AdopterErrorCode implements ApiErrorCode { + TENANT_SUSPENDED; + + @Override + public String code() { + return name(); + } + + @Override + public Category category() { + return Category.AUTHZ; + } + + @Override + public int httpStatus() { + return 403; + } + + @Override + public boolean retryable() { + return false; + } + } +} diff --git a/src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlWireErrorMapperTest.java b/src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlWireErrorMapperTest.java new file mode 100644 index 00000000..a7353304 --- /dev/null +++ b/src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlWireErrorMapperTest.java @@ -0,0 +1,40 @@ +package dev.caskeleton.adapter.inbound.graphql.runtime; + +import static org.assertj.core.api.Assertions.assertThat; + +import dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlBatchTimeoutException; +import dev.caskeleton.adapter.inbound.graphql.dataloader.GraphQlMissingKeyException; +import dev.caskeleton.adapter.inbound.graphql.error.GraphQlErrorContext; +import dev.caskeleton.adapter.inbound.graphql.error.GraphQlWireError; +import java.util.stream.Stream; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.Arguments; +import org.junit.jupiter.params.provider.MethodSource; + +class GraphQlWireErrorMapperTest { + + static Stream dataLoaderFailures() { + return Stream.of( + Arguments.of( + new GraphQlBatchTimeoutException("customer-by-id"), "REQUEST_TIMEOUT", "TIMEOUT"), + Arguments.of(new GraphQlMissingKeyException(), "GRAPHQL_BATCH_KEY_MISSING", "BUSINESS")); + } + + @ParameterizedTest + @MethodSource("dataLoaderFailures") + @DisplayName("DataLoader 의 timeout·missing key 는 INTERNAL_ERROR 로 가려지지 않고 플랫폼 code 로 나간다") + void dataLoaderFailuresKeepAPlatformCode( + RuntimeException failure, String expectedCode, String expectedCategory) { + // given + GraphQlWireErrorMapper mapper = GraphQlWireErrorMapper.masking(); + + // when + GraphQlWireError error = mapper.map(failure, GraphQlErrorContext.test()); + + // then + assertThat(error.extensions()) + .extracting(extensions -> extensions.get("code"), extensions -> extensions.get("category")) + .containsExactly(expectedCode, expectedCategory); + } +} diff --git a/src/adapter/inbound/grpc/CLAUDE.md b/src/adapter/inbound/grpc/CLAUDE.md index fecafa09..a563b9c0 100644 --- a/src/adapter/inbound/grpc/CLAUDE.md +++ b/src/adapter/inbound/grpc/CLAUDE.md @@ -38,10 +38,12 @@ Package root: `dev.caskeleton.adapter.inbound.grpc`. - 프로덕션 feature RPC 를 스켈레톤에 두는 것 — health/reflection 표면만 (web 의 `HealthcheckController` 와 동일 원칙). -## Config knobs (`ca-skeleton.grpc.*`) +## Config knobs (`ca-skeleton.grpc.server.*`) 타입드 `@ConfigurationProperties` 만 두고, 값은 composition-root `application.yml` 에 산다 -(모듈별 `yml` 없음). +(모듈별 `yml` 없음). prefix가 `ca-skeleton.grpc`가 아니라 `.server`까지인 이유: 바인딩이 +`ignoreUnknownFields = false`라서, 부모 prefix를 쓰면 벤더 starter의 `ca-skeleton.grpc.platform.*` +키가 들어오는 순간 기동이 실패한다(`GrpcSafeActivationTest`). | key | default | 의미 | |---|---|---| @@ -81,7 +83,8 @@ credential path and a separately qualified non-loopback bind. 때는 `.proto`/generated stub/`BindableService`를 해당 feature가 소유하고, 서비스 빈과 정확히 한 개의 caller-supplied `GrpcAuthenticationPolicy` 빈을 함께 제공한다. 정책이 없거나 여러 개면 listener 시작이 실패한다. 정책이 `false`를 반환하거나 예외를 던진 요청은 feature handler에 닿지 -않고 안정적인 `UNAUTHENTICATED` status/code/category로 종료된다. +않고 안정적인 `UNAUTHENTICATED` status/code/category로 종료된다. 정책 예외는 예외 타입과 메서드 +이름만 WARN으로 남긴다(메시지는 자격 증명을 담을 수 있어 남기지 않는다). ## P1 증거와 한계 diff --git a/src/adapter/inbound/grpc/README.md b/src/adapter/inbound/grpc/README.md index 07ed6de9..5671af83 100644 --- a/src/adapter/inbound/grpc/README.md +++ b/src/adapter/inbound/grpc/README.md @@ -22,10 +22,10 @@ ``` 이 줄을 지우면 서버, 포트, 설정 바인딩이 모두 함께 빠진다. -- 켜기와 끄기: 모듈이 있으면 켜진다. `ca-skeleton.grpc.enabled=false`로만 끈다. +- 켜기와 끄기: 모듈이 있으면 켜진다. `ca-skeleton.grpc.server.enabled=false`로만 끈다. - 필요한 설정: 전용 `APP_*` env 키는 registry에 없다. 켜진 상태에서 지금 구현이 받는 listener는 - loopback plaintext뿐이라 `ca-skeleton.grpc.allow-insecure-local=true`(env - `CA_SKELETON_GRPC_ALLOW_INSECURE_LOCAL=true`)를 명시해야 기동한다. 선택: `ca-skeleton.grpc.port` + loopback plaintext뿐이라 `ca-skeleton.grpc.server.allow-insecure-local=true`(env + `CA_SKELETON_GRPC_SERVER_ALLOW_INSECURE_LOCAL=true`)를 명시해야 기동한다. 선택: `ca-skeleton.grpc.server.port` (기본 9090), `.bind-address`(기본 127.0.0.1), `.reflection-enabled`, `.shutdown-grace-seconds`. ## 왜 self-managed Netty 인가 diff --git a/src/adapter/inbound/grpc/src/main/java/dev/caskeleton/adapter/inbound/grpc/GrpcAuthenticationInterceptor.java b/src/adapter/inbound/grpc/src/main/java/dev/caskeleton/adapter/inbound/grpc/GrpcAuthenticationInterceptor.java index d167e2f1..25552ec9 100644 --- a/src/adapter/inbound/grpc/src/main/java/dev/caskeleton/adapter/inbound/grpc/GrpcAuthenticationInterceptor.java +++ b/src/adapter/inbound/grpc/src/main/java/dev/caskeleton/adapter/inbound/grpc/GrpcAuthenticationInterceptor.java @@ -6,10 +6,14 @@ import io.grpc.ServerCall; import io.grpc.ServerCallHandler; import io.grpc.ServerInterceptor; import io.grpc.Status; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; /** Applies the caller-supplied authentication policy before a feature RPC can reach its handler. */ final class GrpcAuthenticationInterceptor implements ServerInterceptor { + private static final Logger log = LoggerFactory.getLogger(GrpcAuthenticationInterceptor.class); + private final GrpcAuthenticationPolicy authenticationPolicy; private final GrpcStatusMapper statusMapper; @@ -22,7 +26,7 @@ final class GrpcAuthenticationInterceptor implements ServerInterceptor { @Override public ServerCall.Listener interceptCall( ServerCall call, Metadata headers, ServerCallHandler next) { - if (isAuthenticated(headers)) { + if (isAuthenticated(headers, call.getMethodDescriptor().getFullMethodName())) { return next.startCall(call, headers); } @@ -32,10 +36,15 @@ final class GrpcAuthenticationInterceptor implements ServerInterceptor { return new ServerCall.Listener<>() {}; } - private boolean isAuthenticated(Metadata headers) { + private boolean isAuthenticated(Metadata headers, String method) { try { return authenticationPolicy.isAuthenticated(headers); - } catch (RuntimeException ignored) { + } catch (RuntimeException failure) { + // Type and method only: the message of a failing credential check may echo the credential. + log.warn( + "gRPC authentication policy threw {} for {}; the call is rejected as UNAUTHENTICATED", + failure.getClass().getName(), + method); return false; } } diff --git a/src/adapter/inbound/grpc/src/main/java/dev/caskeleton/adapter/inbound/grpc/GrpcExceptionHandlingInterceptor.java b/src/adapter/inbound/grpc/src/main/java/dev/caskeleton/adapter/inbound/grpc/GrpcExceptionHandlingInterceptor.java index 559d1f50..1f31bdb1 100644 --- a/src/adapter/inbound/grpc/src/main/java/dev/caskeleton/adapter/inbound/grpc/GrpcExceptionHandlingInterceptor.java +++ b/src/adapter/inbound/grpc/src/main/java/dev/caskeleton/adapter/inbound/grpc/GrpcExceptionHandlingInterceptor.java @@ -51,19 +51,21 @@ public class GrpcExceptionHandlingInterceptor implements ServerInterceptor { return new SimpleForwardingServerCallListener<>(delegate) { @Override public void onMessage(REQT message) { - runGuarded(() -> super.onMessage(message)); + runWhileOpen(() -> super.onMessage(message)); } @Override public void onHalfClose() { - runGuarded(super::onHalfClose); + runWhileOpen(super::onHalfClose); } @Override public void onReady() { - runGuarded(super::onReady); + runWhileOpen(super::onReady); } + // onCancel/onComplete arrive after close by design; they run the service's cancel and close + // handlers, so they are never skipped. @Override public void onCancel() { runGuarded(super::onCancel); @@ -74,10 +76,13 @@ public class GrpcExceptionHandlingInterceptor implements ServerInterceptor { runGuarded(super::onComplete); } - private void runGuarded(Runnable action) { - if (closed.get()) { - return; + private void runWhileOpen(Runnable action) { + if (!closed.get()) { + runGuarded(action); } + } + + private void runGuarded(Runnable action) { try { action.run(); } catch (RuntimeException e) { diff --git a/src/adapter/inbound/grpc/src/main/java/dev/caskeleton/adapter/inbound/grpc/GrpcServerConfig.java b/src/adapter/inbound/grpc/src/main/java/dev/caskeleton/adapter/inbound/grpc/GrpcServerConfig.java index 9e421352..a8fe2663 100644 --- a/src/adapter/inbound/grpc/src/main/java/dev/caskeleton/adapter/inbound/grpc/GrpcServerConfig.java +++ b/src/adapter/inbound/grpc/src/main/java/dev/caskeleton/adapter/inbound/grpc/GrpcServerConfig.java @@ -11,8 +11,8 @@ import org.springframework.context.annotation.Bean; /** * Wires the gRPC transport machinery. Registered through this module's own {@code * AutoConfiguration.imports}: on when the module is present, off with {@code - * ca-skeleton.grpc.enabled=false}. The plaintext listener still refuses to start unless {@code - * ca-skeleton.grpc.allow-insecure-local=true} is explicit. + * ca-skeleton.grpc.server.enabled=false}. The plaintext listener still refuses to start unless + * {@code ca-skeleton.grpc.server.allow-insecure-local=true} is explicit. * *

All collaborators are plain objects composed here, mirroring the clean DI style used across * the skeleton. A feature service is exposed only when its {@link BindableService} bean carries @@ -20,7 +20,7 @@ import org.springframework.context.annotation.Bean; */ @AutoConfiguration @ConditionalOnProperty( - prefix = "ca-skeleton.grpc", + prefix = "ca-skeleton.grpc.server", name = "enabled", havingValue = "true", matchIfMissing = true) diff --git a/src/adapter/inbound/grpc/src/main/java/dev/caskeleton/adapter/inbound/grpc/GrpcServerSettings.java b/src/adapter/inbound/grpc/src/main/java/dev/caskeleton/adapter/inbound/grpc/GrpcServerSettings.java index d1ad8fc0..5d3f1ef2 100644 --- a/src/adapter/inbound/grpc/src/main/java/dev/caskeleton/adapter/inbound/grpc/GrpcServerSettings.java +++ b/src/adapter/inbound/grpc/src/main/java/dev/caskeleton/adapter/inbound/grpc/GrpcServerSettings.java @@ -10,11 +10,11 @@ import org.springframework.boot.context.properties.ConfigurationProperties; import org.springframework.validation.annotation.Validated; /** - * gRPC server settings bound from {@code ca-skeleton.grpc.*}. Typed configuration only (no + * gRPC server settings bound from {@code ca-skeleton.grpc.server.*}. Typed configuration only (no * per-module {@code yml}); values live in the composition-root {@code application.yml}, matching * the ca-skeleton config convention. See README for the self-managed-Netty rationale. */ -@ConfigurationProperties(prefix = "ca-skeleton.grpc", ignoreUnknownFields = false) +@ConfigurationProperties(prefix = "ca-skeleton.grpc.server", ignoreUnknownFields = false) @Validated public class GrpcServerSettings { diff --git a/src/adapter/inbound/grpc/src/test/java/dev/caskeleton/adapter/inbound/grpc/GrpcAuthenticationInterceptorTest.java b/src/adapter/inbound/grpc/src/test/java/dev/caskeleton/adapter/inbound/grpc/GrpcAuthenticationInterceptorTest.java new file mode 100644 index 00000000..971f9a9a --- /dev/null +++ b/src/adapter/inbound/grpc/src/test/java/dev/caskeleton/adapter/inbound/grpc/GrpcAuthenticationInterceptorTest.java @@ -0,0 +1,83 @@ +package dev.caskeleton.adapter.inbound.grpc; + +import static org.assertj.core.api.Assertions.assertThat; + +import io.grpc.Metadata; +import io.grpc.MethodDescriptor; +import io.grpc.ServerCall; +import io.grpc.Status; +import java.io.InputStream; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; +import org.springframework.boot.test.system.CapturedOutput; +import org.springframework.boot.test.system.OutputCaptureExtension; + +@ExtendWith(OutputCaptureExtension.class) +class GrpcAuthenticationInterceptorTest { + + private static final String CREDENTIAL_SENTINEL = "credential-secret-sentinel"; + + @Test + void aThrowingPolicyIsLoggedWithItsTypeAndMethodButNotItsMessage(CapturedOutput output) { + // given + GrpcAuthenticationInterceptor interceptor = + new GrpcAuthenticationInterceptor( + metadata -> { + throw new IllegalStateException(CREDENTIAL_SENTINEL); + }, + new GrpcStatusMapper()); + + // when + interceptor.interceptCall( + new MethodCall(), new Metadata(), (call, headers) -> new ServerCall.Listener<>() {}); + + // then + assertThat(output.getAll()) + .contains("IllegalStateException", "test.auth.Feature/Check") + .doesNotContain(CREDENTIAL_SENTINEL); + } + + /** A server call that only knows its method; the interceptor closes it as unauthenticated. */ + private static final class MethodCall extends ServerCall { + + private static final MethodDescriptor.Marshaller UNUSED = + new MethodDescriptor.Marshaller<>() { + @Override + public InputStream stream(String value) { + throw new UnsupportedOperationException(); + } + + @Override + public String parse(InputStream stream) { + throw new UnsupportedOperationException(); + } + }; + + @Override + public void request(int numMessages) {} + + @Override + public void sendHeaders(Metadata headers) {} + + @Override + public void sendMessage(String message) {} + + @Override + public void close(Status status, Metadata trailers) {} + + @Override + public boolean isCancelled() { + return false; + } + + @Override + public MethodDescriptor getMethodDescriptor() { + return MethodDescriptor.newBuilder() + .setType(MethodDescriptor.MethodType.UNARY) + .setFullMethodName("test.auth.Feature/Check") + .setRequestMarshaller(UNUSED) + .setResponseMarshaller(UNUSED) + .build(); + } + } +} diff --git a/src/adapter/inbound/grpc/src/test/java/dev/caskeleton/adapter/inbound/grpc/GrpcExceptionHandlingInterceptorTest.java b/src/adapter/inbound/grpc/src/test/java/dev/caskeleton/adapter/inbound/grpc/GrpcExceptionHandlingInterceptorTest.java index a38d902a..24508878 100644 --- a/src/adapter/inbound/grpc/src/test/java/dev/caskeleton/adapter/inbound/grpc/GrpcExceptionHandlingInterceptorTest.java +++ b/src/adapter/inbound/grpc/src/test/java/dev/caskeleton/adapter/inbound/grpc/GrpcExceptionHandlingInterceptorTest.java @@ -11,6 +11,7 @@ import io.grpc.MethodDescriptor; import io.grpc.ServerCall; import io.grpc.ServerCallHandler; import io.grpc.Status; +import java.util.concurrent.atomic.AtomicBoolean; import org.junit.jupiter.api.Test; /** @@ -66,6 +67,30 @@ class GrpcExceptionHandlingInterceptorTest { assertThat(call.trailers.get(GrpcStatusMapper.CATEGORY_KEY)).isEqualTo("INTERNAL"); } + @Test + void aCancelAfterTheCallClosedStillReachesTheServiceListener() { + // given + AtomicBoolean cancelled = new AtomicBoolean(); + ServerCallHandler handler = + (serverCall, headers) -> { + serverCall.close(Status.OK, new Metadata()); + return new ServerCall.Listener<>() { + @Override + public void onCancel() { + cancelled.set(true); + } + }; + }; + ServerCall.Listener listener = + interceptor.interceptCall(new CapturingServerCall(), new Metadata(), handler); + + // when + listener.onCancel(); + + // then + assertThat(cancelled).isTrue(); + } + private CapturingServerCall closeAfterThrowing(RuntimeException thrown) { CapturingServerCall call = new CapturingServerCall(); ServerCallHandler handler = diff --git a/src/adapter/inbound/grpc/src/test/java/dev/caskeleton/adapter/inbound/grpc/GrpcP1BoundaryWireTest.java b/src/adapter/inbound/grpc/src/test/java/dev/caskeleton/adapter/inbound/grpc/GrpcP1BoundaryWireTest.java index 583a79ca..100311e5 100644 --- a/src/adapter/inbound/grpc/src/test/java/dev/caskeleton/adapter/inbound/grpc/GrpcP1BoundaryWireTest.java +++ b/src/adapter/inbound/grpc/src/test/java/dev/caskeleton/adapter/inbound/grpc/GrpcP1BoundaryWireTest.java @@ -22,6 +22,7 @@ import io.grpc.reflection.v1.ServerReflectionRequest; import io.grpc.reflection.v1.ServerReflectionResponse; import io.grpc.stub.ClientCalls; import io.grpc.stub.MetadataUtils; +import io.grpc.stub.ServerCallStreamObserver; import io.grpc.stub.ServerCalls; import io.grpc.stub.StreamObserver; import java.io.ByteArrayInputStream; @@ -55,16 +56,19 @@ class GrpcP1BoundaryWireTest { unaryMethod("HandlerThrow"); private static final MethodDescriptor LISTENER_THROW_METHOD = unaryMethod("ListenerThrow"); + private static final MethodDescriptor CLOSE_HANDLER_METHOD = + unaryMethod("CloseHandler"); + private static final CountDownLatch CLOSE_HANDLER_RAN = new CountDownLatch(1); private final ApplicationContextRunner contextRunner = new ApplicationContextRunner() .withUserConfiguration(GrpcServerConfig.class, FeatureConfiguration.class) .withPropertyValues( - "ca-skeleton.grpc.enabled=true", - "ca-skeleton.grpc.port=0", - "ca-skeleton.grpc.bind-address=127.0.0.1", - "ca-skeleton.grpc.allow-insecure-local=true", - "ca-skeleton.grpc.reflection-enabled=false"); + "ca-skeleton.grpc.server.enabled=true", + "ca-skeleton.grpc.server.port=0", + "ca-skeleton.grpc.server.bind-address=127.0.0.1", + "ca-skeleton.grpc.server.allow-insecure-local=true", + "ca-skeleton.grpc.server.reflection-enabled=false"); @Test void missingAuthenticationMetadataIsRejectedWithAStableContract() { @@ -172,6 +176,27 @@ class GrpcP1BoundaryWireTest { RAW_STATUS_SENTINEL)); } + @Test + void aSuccessfullyCompletedCallStillRunsTheServiceOnCloseHandler() { + withChannel( + channel -> { + // when + unary(authenticated(channel), CLOSE_HANDLER_METHOD, "ok"); + + // then + assertThat(await(CLOSE_HANDLER_RAN)).isTrue(); + }); + } + + private static boolean await(CountDownLatch latch) { + try { + return latch.await(5, TimeUnit.SECONDS); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + throw new IllegalStateException("interrupted while waiting for the close handler", e); + } + } + private void withChannel(Consumer assertion) { contextRunner.run( context -> { @@ -312,6 +337,15 @@ class GrpcP1BoundaryWireTest { observer.onNext("authorized-" + request); observer.onCompleted(); })) + .addMethod( + CLOSE_HANDLER_METHOD, + ServerCalls.asyncUnaryCall( + (String request, StreamObserver observer) -> { + ((ServerCallStreamObserver) observer) + .setOnCloseHandler(CLOSE_HANDLER_RAN::countDown); + observer.onNext(request); + observer.onCompleted(); + })) .addMethod( HANDLER_THROW_METHOD, (ServerCallHandler) diff --git a/src/adapter/inbound/grpc/src/test/java/dev/caskeleton/adapter/inbound/grpc/GrpcSafeActivationTest.java b/src/adapter/inbound/grpc/src/test/java/dev/caskeleton/adapter/inbound/grpc/GrpcSafeActivationTest.java index e46857f5..00133ef0 100644 --- a/src/adapter/inbound/grpc/src/test/java/dev/caskeleton/adapter/inbound/grpc/GrpcSafeActivationTest.java +++ b/src/adapter/inbound/grpc/src/test/java/dev/caskeleton/adapter/inbound/grpc/GrpcSafeActivationTest.java @@ -42,14 +42,15 @@ class GrpcSafeActivationTest { @Test void presentWithoutTheSwitchIsOnAndStillRefusesAnImplicitPlaintextListener() { contextRunner - .withPropertyValues("ca-skeleton.grpc.port=0") + .withPropertyValues("ca-skeleton.grpc.server.port=0") .run(context -> assertRootCauseContains(context.getStartupFailure(), "insecure")); } @Test void switchedOffCreatesNoGrpcRuntimeBeansOrListener() { contextRunner - .withPropertyValues("ca-skeleton.grpc.enabled=false", "ca-skeleton.grpc.port=0") + .withPropertyValues( + "ca-skeleton.grpc.server.enabled=false", "ca-skeleton.grpc.server.port=0") .run( context -> { assertThat(context).doesNotHaveBean(GrpcServerSettings.class); @@ -62,7 +63,8 @@ class GrpcSafeActivationTest { @Test void enabledTransportRequiresAnExplicitLocalInsecureOverride() { contextRunner - .withPropertyValues("ca-skeleton.grpc.enabled=true", "ca-skeleton.grpc.port=0") + .withPropertyValues( + "ca-skeleton.grpc.server.enabled=true", "ca-skeleton.grpc.server.port=0") .run(context -> assertRootCauseContains(context.getStartupFailure(), "insecure")); } @@ -70,10 +72,10 @@ class GrpcSafeActivationTest { void insecureTransportRejectsANonLoopbackBindAddress() { contextRunner .withPropertyValues( - "ca-skeleton.grpc.enabled=true", - "ca-skeleton.grpc.port=0", - "ca-skeleton.grpc.bind-address=0.0.0.0", - "ca-skeleton.grpc.allow-insecure-local=true") + "ca-skeleton.grpc.server.enabled=true", + "ca-skeleton.grpc.server.port=0", + "ca-skeleton.grpc.server.bind-address=0.0.0.0", + "ca-skeleton.grpc.server.allow-insecure-local=true") .run(context -> assertRootCauseContains(context.getStartupFailure(), "loopback")); } @@ -81,10 +83,10 @@ class GrpcSafeActivationTest { void enabledTransportRejectsAPortOutsideTheTcpRange() { contextRunner .withPropertyValues( - "ca-skeleton.grpc.enabled=true", - "ca-skeleton.grpc.port=65536", - "ca-skeleton.grpc.bind-address=127.0.0.1", - "ca-skeleton.grpc.allow-insecure-local=true") + "ca-skeleton.grpc.server.enabled=true", + "ca-skeleton.grpc.server.port=65536", + "ca-skeleton.grpc.server.bind-address=127.0.0.1", + "ca-skeleton.grpc.server.allow-insecure-local=true") .run(context -> assertRootCauseContains(context.getStartupFailure(), "port")); } @@ -92,11 +94,11 @@ class GrpcSafeActivationTest { void enabledTransportRejectsANegativeShutdownGrace() { contextRunner .withPropertyValues( - "ca-skeleton.grpc.enabled=true", - "ca-skeleton.grpc.port=0", - "ca-skeleton.grpc.bind-address=127.0.0.1", - "ca-skeleton.grpc.allow-insecure-local=true", - "ca-skeleton.grpc.shutdown-grace-seconds=-1") + "ca-skeleton.grpc.server.enabled=true", + "ca-skeleton.grpc.server.port=0", + "ca-skeleton.grpc.server.bind-address=127.0.0.1", + "ca-skeleton.grpc.server.allow-insecure-local=true", + "ca-skeleton.grpc.server.shutdown-grace-seconds=-1") .run( context -> assertRootCauseContains(context.getStartupFailure(), "shutdownGraceSeconds")); @@ -107,13 +109,23 @@ class GrpcSafeActivationTest { contextRunner .withUserConfiguration(FeatureServiceConfiguration.class) .withPropertyValues( - "ca-skeleton.grpc.enabled=true", - "ca-skeleton.grpc.port=0", - "ca-skeleton.grpc.bind-address=127.0.0.1", - "ca-skeleton.grpc.allow-insecure-local=true") + "ca-skeleton.grpc.server.enabled=true", + "ca-skeleton.grpc.server.port=0", + "ca-skeleton.grpc.server.bind-address=127.0.0.1", + "ca-skeleton.grpc.server.allow-insecure-local=true") .run(context -> assertRootCauseContains(context.getStartupFailure(), "authentication")); } + @Test + void theVendorPlatformNamespaceBesideTheAdapterDoesNotFailItsStrictBinding() { + contextRunner + .withPropertyValues( + "ca-skeleton.grpc.server.port=0", + "ca-skeleton.grpc.server.allow-insecure-local=true", + "ca-skeleton.grpc.platform.enabled=true") + .run(context -> assertThat(context).hasNotFailed()); + } + private static void assertRootCauseContains(Throwable failure, String expected) { assertThat(failure).isNotNull(); Throwable rootCause = failure; diff --git a/src/adapter/inbound/grpc/src/test/java/dev/caskeleton/adapter/inbound/grpc/GrpcServerRunnerBootTest.java b/src/adapter/inbound/grpc/src/test/java/dev/caskeleton/adapter/inbound/grpc/GrpcServerRunnerBootTest.java index be5b5a4a..2286033a 100644 --- a/src/adapter/inbound/grpc/src/test/java/dev/caskeleton/adapter/inbound/grpc/GrpcServerRunnerBootTest.java +++ b/src/adapter/inbound/grpc/src/test/java/dev/caskeleton/adapter/inbound/grpc/GrpcServerRunnerBootTest.java @@ -27,10 +27,10 @@ import org.springframework.context.annotation.Configuration; /** * Boots the skeleton gRPC machinery in a real Spring context on an ephemeral port ({@code - * ca-skeleton.grpc.port=0}) with ZERO feature services and proves it stands up a working surface: - * the {@link GrpcServerRunner} SmartLifecycle starts, the standard {@code grpc.health.v1} health - * service reports SERVING, and v1 server reflection lists the built-in services. A real Netty - * channel exercises the wire, so this is a genuine transport smoke test, not a wiring mock. + * ca-skeleton.grpc.server.port=0}) with ZERO feature services and proves it stands up a working + * surface: the {@link GrpcServerRunner} SmartLifecycle starts, the standard {@code grpc.health.v1} + * health service reports SERVING, and v1 server reflection lists the built-in services. A real + * Netty channel exercises the wire, so this is a genuine transport smoke test, not a wiring mock. */ class GrpcServerRunnerBootTest { @@ -38,11 +38,11 @@ class GrpcServerRunnerBootTest { new ApplicationContextRunner() .withUserConfiguration(GrpcServerConfig.class) .withPropertyValues( - "ca-skeleton.grpc.enabled=true", - "ca-skeleton.grpc.port=0", - "ca-skeleton.grpc.bind-address=127.0.0.1", - "ca-skeleton.grpc.allow-insecure-local=true", - "ca-skeleton.grpc.reflection-enabled=true"); + "ca-skeleton.grpc.server.enabled=true", + "ca-skeleton.grpc.server.port=0", + "ca-skeleton.grpc.server.bind-address=127.0.0.1", + "ca-skeleton.grpc.server.allow-insecure-local=true", + "ca-skeleton.grpc.server.reflection-enabled=true"); @Test void skeletonServerStartsAndServesHealthAndReflectionWithNoFeatures() { diff --git a/src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/draft12/Draft12Headers.java b/src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/draft12/Draft12Headers.java index 0f041ffd..69d28711 100644 --- a/src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/draft12/Draft12Headers.java +++ b/src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/draft12/Draft12Headers.java @@ -10,6 +10,7 @@ package dev.caskeleton.adapter.inbound.web.fileserver.draft12; public final class Draft12Headers { public static final String UPLOAD_OFFSET = "Upload-Offset"; + public static final String UPLOAD_LENGTH = "Upload-Length"; public static final String UPLOAD_COMPLETE = "Upload-Complete"; public static final String UPLOAD_LIMIT = "Upload-Limit"; diff --git a/src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/draft12/Draft12UploadController.java b/src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/draft12/Draft12UploadController.java index 3499794b..8921e1e1 100644 --- a/src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/draft12/Draft12UploadController.java +++ b/src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/draft12/Draft12UploadController.java @@ -79,8 +79,19 @@ public class Draft12UploadController { this.clock = clock; } + /** + * Creates the upload and stores the creation request's body as its first part. + * + *

The body is part of the representation, not a preamble: the draft lets a client send all or + * some of the bytes with the creation request, so dropping them loses data the client will not + * resend. For the same reason the body's length is never the upload's length — that is {@code + * Upload-Length}, when the client knows it. + */ + // The channel wraps the servlet request body, which the container owns; see append. + @SuppressWarnings("resource") @PostMapping(DRAFT_PATH) - public ResponseEntity create(HttpServletRequest request) { + public ResponseEntity create(HttpServletRequest request) throws IOException { + RequestContext context = contextFactory.current(); UploadSessionView created = uploadService.create( new CreateUploadRequest( @@ -91,10 +102,28 @@ public class Draft12UploadController { Optional.empty(), UploadMode.EXPERIMENTAL_RESUMABLE, clock.instant().plus(draftProperties.uploadTtl())), - contextFactory.current()); + context); + long offset = 0; + long bodyLength = request.getContentLengthLong(); + if (bodyLength > 0) { + InputStream body = request.getInputStream(); + offset = + transferExecutor + .call( + () -> + uploadService.append( + created.uploadId(), 0, Channels.newChannel(body), bodyLength, context)) + .committedOffset(); + } + if (isComplete(request)) { + transferExecutor.call( + () -> + finalizeService.finalizeUpload( + created.uploadId(), FinalizeUploadRequest.synchronousWithoutDigest(), context)); + } return ResponseEntity.created(URI.create(DRAFT_PATH + "/" + created.uploadId().canonicalText())) - .header(Draft12Headers.UPLOAD_OFFSET, "0") + .header(Draft12Headers.UPLOAD_OFFSET, String.valueOf(offset)) .header(Draft12Headers.UPLOAD_LIMIT, "max-size=" + draftProperties.maxSize()) .build(); } @@ -119,7 +148,10 @@ public class Draft12UploadController { uploadService.append( id, expectedOffset, Channels.newChannel(body), declared, context)); if (complete) { - finalizeService.finalizeUpload(id, FinalizeUploadRequest.synchronousWithoutDigest(), context); + transferExecutor.call( + () -> + finalizeService.finalizeUpload( + id, FinalizeUploadRequest.synchronousWithoutDigest(), context)); } return ResponseEntity.noContent() .header(Draft12Headers.UPLOAD_OFFSET, String.valueOf(appended.committedOffset())) @@ -168,9 +200,21 @@ public class Draft12UploadController { } } + /** {@code Upload-Length} when the client declared it; otherwise unknown until completion. */ private static OptionalLong declaredLength(HttpServletRequest request) { - long length = request.getContentLengthLong(); - return length < 0 ? OptionalLong.empty() : OptionalLong.of(length); + String header = request.getHeader(Draft12Headers.UPLOAD_LENGTH); + if (header == null || header.isBlank()) { + return OptionalLong.empty(); + } + try { + long length = Long.parseLong(header.trim()); + if (length < 0) { + throw new NumberFormatException("negative"); + } + return OptionalLong.of(length); + } catch (NumberFormatException malformed) { + throw MalformedRequestException.of("Upload-Length is not a non-negative integer"); + } } private static String filename(HttpServletRequest request) { diff --git a/src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/tus/TusController.java b/src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/tus/TusController.java index 3f828295..a4f89688 100644 --- a/src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/tus/TusController.java +++ b/src/adapter/inbound/web-fileserver/src/main/java/dev/caskeleton/adapter/inbound/web/fileserver/tus/TusController.java @@ -175,7 +175,12 @@ public class TusController { UploadSessionView session = uploadService.status(id, context); if (isComplete(session, appended)) { - finalizeService.finalizeUpload(id, FinalizeUploadRequest.synchronousWithoutDigest(), context); + // Finalize reads the whole object back and moves it: transfer work, bounded by the same + // executor as the append rather than holding a servlet thread for it. + transferExecutor.call( + () -> + finalizeService.finalizeUpload( + id, FinalizeUploadRequest.synchronousWithoutDigest(), context)); } return ResponseEntity.noContent() .header(TusHeaders.RESUMABLE, tusProperties.version()) diff --git a/src/adapter/inbound/web-fileserver/src/test/java/dev/caskeleton/adapter/inbound/web/fileserver/draft12/Draft12ProtocolTest.java b/src/adapter/inbound/web-fileserver/src/test/java/dev/caskeleton/adapter/inbound/web/fileserver/draft12/Draft12ProtocolTest.java index 4c564fc8..03096cbb 100644 --- a/src/adapter/inbound/web-fileserver/src/test/java/dev/caskeleton/adapter/inbound/web/fileserver/draft12/Draft12ProtocolTest.java +++ b/src/adapter/inbound/web-fileserver/src/test/java/dev/caskeleton/adapter/inbound/web/fileserver/draft12/Draft12ProtocolTest.java @@ -53,6 +53,46 @@ class Draft12ProtocolTest { .andExpect(header().string(Draft12Headers.UPLOAD_LIMIT, "max-size=" + DRAFT.maxSize())); } + /** A creation request carries the first part of the representation; dropping it loses bytes. */ + @Test + void aCreationBodyIsStoredAsTheFirstPartOfTheUpload() throws Exception { + // when + String location = + mvc.perform( + post("/v1/experimental/draft12/uploads") + .header(Draft12Headers.UPLOAD_LENGTH, "6") + .contentType("application/octet-stream") + .content("abc")) + .andReturn() + .getResponse() + .getHeader("Location"); + + // then + assertThat(uploads.content(uploadIdOf(location))).isEqualTo("abc"); + } + + /** The body's own length is the size of one part, never the size of the whole upload. */ + @Test + void theFinalLengthComesFromUploadLengthRatherThanTheCreationBody() throws Exception { + // when + String location = + mvc.perform( + post("/v1/experimental/draft12/uploads") + .header(Draft12Headers.UPLOAD_LENGTH, "6") + .contentType("application/octet-stream") + .content("abc")) + .andReturn() + .getResponse() + .getHeader("Location"); + + // then + assertThat( + uploads + .status(uploadIdOf(location), FileserverWebFixtures.requestContext()) + .expectedLength()) + .hasValue(6); + } + @Test void anAppendAdvancesTheOffsetAndReportsIncompleteness() throws Exception { String location = create(); diff --git a/src/adapter/inbound/web-fileserver/src/test/java/dev/caskeleton/adapter/inbound/web/fileserver/testkit/RecordingFinalizeService.java b/src/adapter/inbound/web-fileserver/src/test/java/dev/caskeleton/adapter/inbound/web/fileserver/testkit/RecordingFinalizeService.java index d54bfb03..65459595 100644 --- a/src/adapter/inbound/web-fileserver/src/test/java/dev/caskeleton/adapter/inbound/web/fileserver/testkit/RecordingFinalizeService.java +++ b/src/adapter/inbound/web-fileserver/src/test/java/dev/caskeleton/adapter/inbound/web/fileserver/testkit/RecordingFinalizeService.java @@ -10,20 +10,26 @@ import dev.caskeleton.application.fileserver.api.security.RequestContext; import dev.caskeleton.application.fileserver.upload.FileView; import dev.caskeleton.application.fileserver.upload.FinalizeUploadRequest; import dev.caskeleton.application.fileserver.upload.FinalizeUploadService; -import java.util.ArrayList; import java.util.List; import java.util.Optional; import java.util.UUID; +import java.util.concurrent.CopyOnWriteArrayList; /** Records which uploads a protocol adapter decided to finalize. */ public final class RecordingFinalizeService implements FinalizeUploadService { - private final List finalized = new ArrayList<>(); + private final List finalized = new CopyOnWriteArrayList<>(); + private final List threads = new CopyOnWriteArrayList<>(); public List finalized() { return List.copyOf(finalized); } + /** Names of the threads each finalize ran on. */ + public List threads() { + return List.copyOf(threads); + } + @Override public FileView finalizeUpload( UploadSession session, FinalizeUploadRequest request, RequestContext context) { @@ -34,6 +40,7 @@ public final class RecordingFinalizeService implements FinalizeUploadService { public FileView finalizeUpload( UploadId uploadId, FinalizeUploadRequest request, RequestContext context) { finalized.add(uploadId); + threads.add(Thread.currentThread().getName()); return FileView.of( new FileDescriptor( FileId.of(UUID.randomUUID()), diff --git a/src/adapter/inbound/web-fileserver/src/test/java/dev/caskeleton/adapter/inbound/web/fileserver/tus/TusProtocolContractTest.java b/src/adapter/inbound/web-fileserver/src/test/java/dev/caskeleton/adapter/inbound/web/fileserver/tus/TusProtocolContractTest.java index c36f0c8b..58de03eb 100644 --- a/src/adapter/inbound/web-fileserver/src/test/java/dev/caskeleton/adapter/inbound/web/fileserver/tus/TusProtocolContractTest.java +++ b/src/adapter/inbound/web-fileserver/src/test/java/dev/caskeleton/adapter/inbound/web/fileserver/tus/TusProtocolContractTest.java @@ -145,6 +145,19 @@ class TusProtocolContractTest { created.andExpect(status().isBadRequest()); } + /** Finalize rereads and moves the whole object; that is transfer work, not servlet work. */ + @Test + void theCompletingPatchFinalizesOnTheTransferExecutor() throws Exception { + // given + String location = create(3); + + // when + appendAt(location, 0, "abc"); + + // then + assertThat(finalizeService.threads()).singleElement().asString().startsWith("fs-transfer-"); + } + @Test void chunksCarryingTheirOwnCorrectChecksumAreAllAccepted() throws Exception { // given diff --git a/src/adapter/inbound/web-notification/src/main/java/dev/caskeleton/adapter/inbound/web/notification/platform/submission/NotificationSubmissionController.java b/src/adapter/inbound/web-notification/src/main/java/dev/caskeleton/adapter/inbound/web/notification/platform/submission/NotificationSubmissionController.java index f984c7c2..8fa88076 100644 --- a/src/adapter/inbound/web-notification/src/main/java/dev/caskeleton/adapter/inbound/web/notification/platform/submission/NotificationSubmissionController.java +++ b/src/adapter/inbound/web-notification/src/main/java/dev/caskeleton/adapter/inbound/web/notification/platform/submission/NotificationSubmissionController.java @@ -48,9 +48,6 @@ public class NotificationSubmissionController { /** What a caller gets when it names no version; the first published version of a template. */ private static final long DEFAULT_TEMPLATE_VERSION = 1L; - /** What a caller gets when it names no category. */ - private static final String DEFAULT_CATEGORY = "transactional"; - private final AcceptNotificationUseCase accept; /** @@ -85,9 +82,9 @@ public class NotificationSubmissionController { locale(request.locale()), NotificationVariableCoercion.coerceAll(request.variables()), Optional.ofNullable(request.idempotencyKey()).filter(key -> !key.isBlank()), - request.category() == null || request.category().isBlank() - ? DEFAULT_CATEGORY - : request.category()); + // Passed as sent. Category decides marketing suppression, so the application refuses a + // missing one (400) rather than this transport choosing "transactional" for the caller. + request.category()); return ResponseEntity.status(HttpStatus.ACCEPTED) .body( diff --git a/src/adapter/inbound/web-notification/src/main/java/dev/caskeleton/adapter/inbound/web/notification/platform/submission/SubmitNotificationHttpRequest.java b/src/adapter/inbound/web-notification/src/main/java/dev/caskeleton/adapter/inbound/web/notification/platform/submission/SubmitNotificationHttpRequest.java index cfd8ea2b..ce5cbcba 100644 --- a/src/adapter/inbound/web-notification/src/main/java/dev/caskeleton/adapter/inbound/web/notification/platform/submission/SubmitNotificationHttpRequest.java +++ b/src/adapter/inbound/web-notification/src/main/java/dev/caskeleton/adapter/inbound/web/notification/platform/submission/SubmitNotificationHttpRequest.java @@ -25,7 +25,8 @@ import java.util.Map; * @param locale the BCP 47 language tag to render in; the platform default when omitted * @param variables template variables, as JSON scalars, lists and objects * @param idempotencyKey the caller's key; derived from the request when omitted - * @param category the routing and reporting category; {@code transactional} when omitted + * @param category the routing and reporting category; required — the application refuses a + * submission without one (400) instead of guessing, since it decides marketing suppression */ public record SubmitNotificationHttpRequest( @NotBlank @Size(max = 200) String recipientRef, diff --git a/src/adapter/inbound/web-notification/src/test/java/dev/caskeleton/adapter/inbound/web/notification/platform/submission/NotificationSubmissionControllerTest.java b/src/adapter/inbound/web-notification/src/test/java/dev/caskeleton/adapter/inbound/web/notification/platform/submission/NotificationSubmissionControllerTest.java new file mode 100644 index 00000000..2270c921 --- /dev/null +++ b/src/adapter/inbound/web-notification/src/test/java/dev/caskeleton/adapter/inbound/web/notification/platform/submission/NotificationSubmissionControllerTest.java @@ -0,0 +1,50 @@ +package dev.caskeleton.adapter.inbound.web.notification.platform.submission; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post; + +import dev.caskeleton.adapter.inbound.web.error.GlobalExceptionHandler; +import dev.caskeleton.application.notification.platform.port.in.AcceptNotificationCommand; +import dev.caskeleton.shared.tracing.SpanErrorRecorder; +import java.util.ArrayList; +import java.util.List; +import org.junit.jupiter.api.Test; +import org.springframework.http.MediaType; +import org.springframework.test.web.servlet.MockMvc; +import org.springframework.test.web.servlet.setup.MockMvcBuilders; + +class NotificationSubmissionControllerTest { + + private final List accepted = new ArrayList<>(); + + private final MockMvc mvc = + MockMvcBuilders.standaloneSetup( + new NotificationSubmissionController( + command -> { + accepted.add(command); + throw new IllegalStateException("the probe stops after recording"); + })) + .setControllerAdvice(new GlobalExceptionHandler(SpanErrorRecorder.NOOP)) + .build(); + + @Test + void submissionWithoutCategoryIsRejectedBeforeTheUseCaseRuns() throws Exception { + // given + String withoutCategory = + "{\"recipientRef\":\"r-1\",\"channel\":\"EMAIL\",\"address\":\"a@example.com\"," + + "\"template\":\"welcome\"}"; + + // when + int status = + mvc.perform( + post("/notifications") + .contentType(MediaType.APPLICATION_JSON) + .content(withoutCategory)) + .andReturn() + .getResponse() + .getStatus(); + + // then + assertThat(List.of(status, accepted.size())).containsExactly(400, 0); + } +} diff --git a/src/adapter/inbound/web/README.md b/src/adapter/inbound/web/README.md index 10fed0b0..c8b20f47 100644 --- a/src/adapter/inbound/web/README.md +++ b/src/adapter/inbound/web/README.md @@ -242,10 +242,16 @@ commit-aware response wrapper 계약을 구현한다. 또한 이 모듈은 HTML - 단일 소유권: Spring Security 기본 `Cache-Control` 은 `SecurityConfig` 에서 비활성화 → 실행 앱에서 이 필터가 헤더 단일 소유자. 독립 MockMvc(보안 체인 없음)에서도 이 필터가 유일 writer. -### RequestLoggingFilter +### WebMvcRequestIdFilter / RequestLoggingFilter +- **id 는 한 곳에서 만든다.** request/correlation/trace/span id 발급, MDC 기록, 응답 헤더(`X-Request-Id`, + `X-Correlation-Id`, `traceparent`)는 `WebMvcRequestIdFilter`(HIGHEST+10, Spring Security 앞)가 한다. 그래서 + 보안 체인이 쓰는 401/403 Envelope 의 `meta` 도 id 를 가진다. `RequestLoggingFilter` 는 id 를 만들지 않고 + 접근 로그 한 줄과 `user_principal` 만 담당한다(principal 을 읽으려고 보안 체인 안쪽에서 돈다). 보안 체인이 + 거절한 요청의 로그는 entry point / access-denied handler 가 남긴다. 아래 traceparent 규칙은 + `WebMvcRequestIdFilter` 의 것이다. - **MDC 키 정책(D11/D19).** `MdcKeys` 의 snake_case 키 사용. -- **인바운드 id 헤더(D14/D15).** `X-Request-Id` / `X-Correlation-Id` 는 사용 전 sanitize(CR/LF + control 제거) - 및 길이 제한. 부재/공백은 서버 생성. +- **인바운드 id 헤더(D14/D15).** `X-Request-Id` 는 기본적으로 받지 않고 서버가 만든다(신뢰 설정 시 안전 문자만). + `X-Correlation-Id` 는 사용 전 sanitize(CR/LF + control 제거) 및 길이 제한. 부재/공백은 서버 생성. - **W3C `traceparent`(D5/D7/D4).** 유효한 인바운드 traceparent 가 있으면 채택해 그 `traceId`→MDC `trace_id`, `spanId`→`span_id`. 부재/공백/무효면 fresh ROOT traceparent 생성(32-hex traceId, 16-hex spanId, sampled=false)하여 MDC `trace_id` 가 **항상** 의미 있는 W3C id 이고 절대 null 이 아니게 한다(D4: 추적 비활성 @@ -373,7 +379,7 @@ commit-aware response wrapper 계약을 구현한다. 또한 이 모듈은 HTML 변환 단일 지점은 `ResponseMetaFactory`. ### MdcCorrelationIdPortAdapter -- `RequestLoggingFilter`가 무해화하고 MDC `correlation_id`에 넣은 값을 application-core의 +- `WebMvcRequestIdFilter`가 무해화하고 MDC `correlation_id`에 넣은 값을 application-core의 `CorrelationIdPort`로 투영한다. - absent/blank는 `Optional.empty()`로 반환한다. application/sample 계층은 SLF4J/MDC를 직접 참조하지 않고 event-id fallback 정책만 소유한다. diff --git a/src/adapter/inbound/web/build.gradle b/src/adapter/inbound/web/build.gradle index 0a1cac61..05f46346 100644 --- a/src/adapter/inbound/web/build.gradle +++ b/src/adapter/inbound/web/build.gradle @@ -36,6 +36,9 @@ dependencies { // owned by feature-contract-verification-test-suite (planned). implementation libs.springdoc.openapi.starter.webmvc.api testImplementation 'org.springframework.security:spring-security-test' + // The operation controller's contract test drives the real use cases over the port owners' + // fakes (operation store, outbox, transaction port). + testImplementation testFixtures(project(':application-core')) } tasks.named('test') { diff --git a/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/error/ClientSafeValidationDetails.java b/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/error/ClientSafeValidationDetails.java index 9507703d..c1f9c761 100644 --- a/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/error/ClientSafeValidationDetails.java +++ b/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/error/ClientSafeValidationDetails.java @@ -7,6 +7,7 @@ import java.util.ArrayList; import java.util.List; import java.util.Map; import org.springframework.validation.FieldError; +import org.springframework.validation.ObjectError; /** * Builds bounded validation details without reflecting rejected values or interpolated messages. @@ -49,8 +50,13 @@ final class ClientSafeValidationDetails { return detail(normalize(violation.getPropertyPath()), rule); } - static Map from(FieldError fieldError) { - return detail(normalize(fieldError.getField()), ruleFor(fieldError.getCode())); + /** + * A field error names its field; a class-level (global) error is reported against the request. + */ + static Map from(ObjectError error) { + String field = + error instanceof FieldError fieldError ? normalize(fieldError.getField()) : "request"; + return detail(field, ruleFor(error.getCode())); } private static Map detail(String field, Rule rule) { diff --git a/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/error/GlobalExceptionHandler.java b/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/error/GlobalExceptionHandler.java index fd5f4101..77210730 100644 --- a/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/error/GlobalExceptionHandler.java +++ b/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/error/GlobalExceptionHandler.java @@ -260,7 +260,7 @@ public class GlobalExceptionHandler extends ResponseEntityExceptionHandler { HttpStatusCode status, WebRequest request) { List> fields = - ex.getBindingResult().getFieldErrors().stream() + ex.getBindingResult().getAllErrors().stream() .map(ClientSafeValidationDetails::from) .toList(); return new ResponseEntity<>( diff --git a/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/filter/RequestLoggingFilter.java b/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/filter/RequestLoggingFilter.java index 2591ee2d..e904d7ca 100644 --- a/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/filter/RequestLoggingFilter.java +++ b/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/filter/RequestLoggingFilter.java @@ -1,17 +1,13 @@ package dev.caskeleton.adapter.inbound.web.filter; import dev.caskeleton.adapter.inbound.web.auth.AuthenticatedPrincipal; -import dev.caskeleton.adapter.inbound.web.core.WebRequestId; -import dev.caskeleton.adapter.inbound.web.observability.HeaderSanitizer; import dev.caskeleton.adapter.inbound.web.observability.MdcKeys; import dev.caskeleton.application.observability.UserPrincipalPseudonymizerPort; -import dev.caskeleton.shared.tracing.TraceParent; import jakarta.servlet.FilterChain; import jakarta.servlet.ServletException; import jakarta.servlet.http.HttpServletRequest; import jakarta.servlet.http.HttpServletResponse; import java.io.IOException; -import java.util.UUID; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.slf4j.MDC; @@ -22,28 +18,21 @@ import org.springframework.web.filter.OncePerRequestFilter; import org.springframework.web.servlet.HandlerMapping; /** - * Logs one structured line per HTTP request and threads the correlation ids onto MDC using the - * snake_case keys of {@link MdcKeys}. The request id is assigned by the transport's request-id - * filter and stored as a {@link WebRequestId}; this filter never makes a second trust decision from - * {@code X-Request-Id}. Inbound {@code X-Correlation-Id} is sanitized and length-capped before use; - * absent/blank values are server-generated. A valid inbound W3C {@code traceparent} is adopted onto - * MDC ({@code trace_id} / {@code span_id}), otherwise a fresh ROOT traceparent is generated; the - * resolved value is set on the response header. {@code user_principal} is pseudonymized via {@link - * UserPrincipalPseudonymizerPort} before being placed on MDC. + * Logs one structured line per HTTP request. The correlation ids on MDC ({@code request_id}, {@code + * correlation_id}, {@code trace_id}, {@code span_id}) are the ones the request-id filter assigned + * before Spring Security ran; this filter neither makes nor replaces any of them. {@code + * user_principal} is pseudonymized via {@link UserPrincipalPseudonymizerPort} before being placed + * on MDC. * - *

See README for the design rationale, including the fork landmine around the generated {@code - * trace_id} when a real tracer is later wired in. + *

It runs inside the security chain on purpose: the authenticated principal is readable only + * there. A request the chain rejects is logged by the entry point / access-denied handler instead. + * See README for the design rationale. */ @Component public class RequestLoggingFilter extends OncePerRequestFilter { private static final Logger log = LoggerFactory.getLogger(RequestLoggingFilter.class); - private static final String HEADER_REQUEST_ID = "X-Request-Id"; - private static final String HEADER_CORRELATION_ID = "X-Correlation-Id"; - private static final String HEADER_TRACEPARENT = "traceparent"; - private static final int MAX_ID_LENGTH = 200; - private final UserPrincipalPseudonymizerPort pseudonymizer; public RequestLoggingFilter(UserPrincipalPseudonymizerPort pseudonymizer) { @@ -54,23 +43,6 @@ public class RequestLoggingFilter extends OncePerRequestFilter { protected void doFilterInternal( HttpServletRequest req, HttpServletResponse res, FilterChain chain) throws ServletException, IOException { - - Object assignedRequestId = req.getAttribute(WebRequestId.REQUEST_ATTRIBUTE); - String requestId = - assignedRequestId instanceof WebRequestId id ? id.value() : UUID.randomUUID().toString(); - String correlationId = resolveOrGenerate(req.getHeader(HEADER_CORRELATION_ID)); - res.setHeader(HEADER_REQUEST_ID, requestId); - res.setHeader(HEADER_CORRELATION_ID, correlationId); - - MDC.put(MdcKeys.REQUEST_ID, requestId); - MDC.put(MdcKeys.CORRELATION_ID, correlationId); - - // W3C traceparent: adopt inbound if valid, otherwise generate a fresh ROOT. - TraceParent traceParent = resolveOrGenerateTraceParent(req.getHeader(HEADER_TRACEPARENT)); - MDC.put(MdcKeys.TRACE_ID, traceParent.traceId()); - MDC.put(MdcKeys.SPAN_ID, traceParent.spanId()); - res.setHeader(HEADER_TRACEPARENT, traceParent.toHeader()); - long start = System.nanoTime(); try { chain.doFilter(req, res); @@ -83,48 +55,10 @@ public class RequestLoggingFilter extends OncePerRequestFilter { resolveUriTemplate(req), res.getStatus(), durationMs); - MDC.remove(MdcKeys.REQUEST_ID); - MDC.remove(MdcKeys.CORRELATION_ID); - MDC.remove(MdcKeys.TRACE_ID); - MDC.remove(MdcKeys.SPAN_ID); MDC.remove(MdcKeys.USER_PRINCIPAL); } } - /** Sanitize an inbound id header; generate a fresh one when absent/blank. */ - private static String resolveOrGenerate(String inbound) { - String clean = HeaderSanitizer.sanitize(inbound, MAX_ID_LENGTH); - return (clean == null || clean.isBlank()) ? UUID.randomUUID().toString() : clean; - } - - /** - * Resolves a W3C {@code traceparent} for this request: adopts a present, valid inbound header - * unchanged, otherwise generates a fresh ROOT traceparent (32-hex {@code traceId}, 16-hex {@code - * spanId}, {@code sampled=false}). - */ - private static TraceParent resolveOrGenerateTraceParent(String header) { - return TraceParent.parse(header) - .orElseGet( - () -> { - String traceId = freshHex32(); - String spanId = freshHex16(); - return TraceParent.of(traceId, spanId, false); - }); - } - - /** Returns a 32-char lowercase hex string from a random UUID (dashes stripped). */ - private static String freshHex32() { - return UUID.randomUUID().toString().replace("-", ""); - } - - /** - * Returns a 16-char lowercase hex span id (64 random bits), derived from a fresh UUID's - * least-significant bits and zero-padded. See README for the design rationale. - */ - private static String freshHex16() { - return String.format("%016x", UUID.randomUUID().getLeastSignificantBits()); - } - /** * Returns the low-cardinality matched route template ({@code BEST_MATCHING_PATTERN_ATTRIBUTE}), * falling back to the raw request URI for unmatched requests (e.g. 404s). diff --git a/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/mvc/filter/WebMvcRequestIdFilter.java b/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/mvc/filter/WebMvcRequestIdFilter.java index 16ecfcc4..b74dd321 100644 --- a/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/mvc/filter/WebMvcRequestIdFilter.java +++ b/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/mvc/filter/WebMvcRequestIdFilter.java @@ -2,14 +2,19 @@ package dev.caskeleton.adapter.inbound.web.mvc.filter; import dev.caskeleton.adapter.inbound.web.core.WebRequestId; import dev.caskeleton.adapter.inbound.web.core.WebTraceId; +import dev.caskeleton.adapter.inbound.web.observability.HeaderSanitizer; +import dev.caskeleton.adapter.inbound.web.observability.MdcKeys; +import dev.caskeleton.shared.tracing.TraceParent; import jakarta.servlet.FilterChain; import jakarta.servlet.ServletException; import jakarta.servlet.http.HttpServletRequest; import jakarta.servlet.http.HttpServletResponse; import java.io.IOException; +import java.util.Map; import java.util.Optional; import java.util.UUID; import java.util.regex.Pattern; +import org.slf4j.MDC; import org.springframework.core.Ordered; import org.springframework.web.filter.OncePerRequestFilter; @@ -27,6 +32,11 @@ import org.springframework.web.filter.OncePerRequestFilter; * *

The trace id is different: propagating an inbound {@code traceparent} is the entire point of * distributed tracing, so it is honoured when it parses, and replaced when it does not. + * + *

This is the one place the identifiers are made. It puts them on MDC and on the response before + * anything else runs — Spring Security included, so a {@code 401}/{@code 403} written inside the + * security chain carries the same {@code meta} ids as any other response — and the access log + * ({@code RequestLoggingFilter}) only reads them. */ public final class WebMvcRequestIdFilter extends OncePerRequestFilter implements Ordered { @@ -39,15 +49,19 @@ public final class WebMvcRequestIdFilter extends OncePerRequestFilter implements /** The header a client may propose a request id in. */ public static final String REQUEST_ID_HEADER = "X-Request-Id"; + /** The header a caller correlates its own requests by; sanitized, never trusted as an id. */ + public static final String CORRELATION_ID_HEADER = "X-Correlation-Id"; + /** The W3C trace context header. */ public static final String TRACEPARENT_HEADER = "traceparent"; + /** The MDC entries of a request, kept so an ERROR or ASYNC redispatch restores the same ones. */ + private static final String MDC_ATTRIBUTE = WebMvcRequestIdFilter.class.getName() + ".mdc"; + /** Printable, bounded, no separators a log parser would act on. */ private static final Pattern SAFE_IDENTIFIER = Pattern.compile("[A-Za-z0-9._-]{1,128}"); - /** {@code version-traceid-spanid-flags}; only the trace id is taken. */ - private static final Pattern TRACEPARENT = - Pattern.compile("[0-9a-f]{2}-([0-9a-f]{32})-[0-9a-f]{16}-[0-9a-f]{2}"); + private static final int MAX_CORRELATION_ID_LENGTH = 200; private final boolean trustInboundRequestId; private final int order; @@ -73,16 +87,38 @@ public final class WebMvcRequestIdFilter extends OncePerRequestFilter implements protected void doFilterInternal( HttpServletRequest request, HttpServletResponse response, FilterChain chain) throws IOException, ServletException { - if (request.getAttribute(REQUEST_ID_ATTRIBUTE) == null) { - WebRequestId requestId = resolveRequestId(request); - WebTraceId traceId = resolveTraceId(request); - request.setAttribute(REQUEST_ID_ATTRIBUTE, requestId); - request.setAttribute(TRACE_ID_ATTRIBUTE, traceId); - // Echoed so a client can quote it in a support ticket. Safe to publish: it names a log entry - // rather than a person, and it is this platform's value, not the caller's. - response.setHeader(REQUEST_ID_HEADER, requestId.value()); + @SuppressWarnings("unchecked") + Map mdc = (Map) request.getAttribute(MDC_ATTRIBUTE); + if (mdc == null) { + mdc = assign(request, response); } - chain.doFilter(request, response); + mdc.forEach(MDC::put); + try { + chain.doFilter(request, response); + } finally { + mdc.keySet().forEach(MDC::remove); + } + } + + private Map assign(HttpServletRequest request, HttpServletResponse response) { + WebRequestId requestId = resolveRequestId(request); + TraceParent trace = resolveTrace(request); + String correlationId = resolveCorrelationId(request); + request.setAttribute(REQUEST_ID_ATTRIBUTE, requestId); + request.setAttribute(TRACE_ID_ATTRIBUTE, new WebTraceId(trace.traceId())); + // Echoed so a client can quote them in a support ticket. Safe to publish: they name a log + // entry rather than a person, and they are this platform's values, not the caller's. + response.setHeader(REQUEST_ID_HEADER, requestId.value()); + response.setHeader(CORRELATION_ID_HEADER, correlationId); + response.setHeader(TRACEPARENT_HEADER, trace.toHeader()); + Map mdc = + Map.of( + MdcKeys.REQUEST_ID, requestId.value(), + MdcKeys.CORRELATION_ID, correlationId, + MdcKeys.TRACE_ID, trace.traceId(), + MdcKeys.SPAN_ID, trace.spanId()); + request.setAttribute(MDC_ATTRIBUTE, mdc); + return mdc; } @Override @@ -109,17 +145,23 @@ public final class WebMvcRequestIdFilter extends OncePerRequestFilter implements .orElseGet(() -> new WebRequestId(UUID.randomUUID().toString())); } - private WebTraceId resolveTraceId(HttpServletRequest request) { - String traceparent = request.getHeader(TRACEPARENT_HEADER); - if (traceparent != null) { - var matcher = TRACEPARENT.matcher(traceparent.trim()); - if (matcher.matches()) { - return new WebTraceId(matcher.group(1)); - } - } + private static TraceParent resolveTrace(HttpServletRequest request) { // A malformed traceparent is replaced rather than rejected: refusing the request would let an // upstream misconfiguration take an API down, and the platform still needs a correlation id. - return new WebTraceId(UUID.randomUUID().toString().replace("-", "")); + return TraceParent.parse(request.getHeader(TRACEPARENT_HEADER)) + .orElseGet( + () -> + TraceParent.of( + UUID.randomUUID().toString().replace("-", ""), + String.format("%016x", UUID.randomUUID().getLeastSignificantBits()), + false)); + } + + private static String resolveCorrelationId(HttpServletRequest request) { + String clean = + HeaderSanitizer.sanitize( + request.getHeader(CORRELATION_ID_HEADER), MAX_CORRELATION_ID_LENGTH); + return clean == null || clean.isBlank() ? UUID.randomUUID().toString() : clean; } private static Optional sanitized(String candidate) { diff --git a/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/operation/DurableOperationController.java b/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/operation/DurableOperationController.java new file mode 100644 index 00000000..5e1ddeb1 --- /dev/null +++ b/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/operation/DurableOperationController.java @@ -0,0 +1,158 @@ +package dev.caskeleton.adapter.inbound.web.operation; + +import dev.caskeleton.adapter.inbound.web.auth.AuthenticatedPrincipal; +import dev.caskeleton.adapter.inbound.web.error.ErrorResponseFactory; +import dev.caskeleton.adapter.inbound.web.observability.ResponseMetaFactory; +import dev.caskeleton.application.idempotency.RequestFingerprint; +import dev.caskeleton.application.operation.CancelDurableOperationCommand; +import dev.caskeleton.application.operation.CancelDurableOperationUseCase; +import dev.caskeleton.application.operation.DurableOperationId; +import dev.caskeleton.application.operation.GetDurableOperationQuery; +import dev.caskeleton.application.operation.GetDurableOperationUseCase; +import dev.caskeleton.application.operation.OperationAcceptance; +import dev.caskeleton.application.operation.OperationCommand; +import dev.caskeleton.application.operation.SubmitDurableOperationUseCase; +import dev.caskeleton.shared.response.Envelope; +import jakarta.validation.Valid; +import java.net.URI; +import java.nio.charset.StandardCharsets; +import java.util.Objects; +import java.util.UUID; +import org.springframework.http.HttpStatus; +import org.springframework.http.ResponseEntity; +import org.springframework.security.authentication.AuthenticationCredentialsNotFoundException; +import org.springframework.security.core.annotation.AuthenticationPrincipal; +import org.springframework.web.bind.annotation.DeleteMapping; +import org.springframework.web.bind.annotation.GetMapping; +import org.springframework.web.bind.annotation.PathVariable; +import org.springframework.web.bind.annotation.PostMapping; +import org.springframework.web.bind.annotation.RequestBody; +import org.springframework.web.bind.annotation.RequestMapping; +import org.springframework.web.bind.annotation.RestController; +import org.springframework.web.servlet.support.ServletUriComponentsBuilder; + +/** + * Durable operations over HTTP: submit, poll, cancel. + * + *

A transport only. Who may submit or cancel is the use cases' {@code @RequiresPermission}; who + * may see an operation is their owner and tenant check, which answers "absent" for someone else's + * operation exactly as for one that does not exist — so both are the same 404 here. Registered by + * the composition that assembles those use cases, which exists only when a store is selected. + * + *

No tenant is passed: nothing on this transport resolves one yet, and an operation submitted + * without a tenant is visible only to calls made without one. + */ +@RestController +@RequestMapping("/operations") +public class DurableOperationController { + + private final SubmitDurableOperationUseCase submit; + private final GetDurableOperationUseCase get; + private final CancelDurableOperationUseCase cancel; + + /** + * A controller over the three operation use cases. + * + * @param submit accepts work + * @param get reads one operation + * @param cancel requests cancellation + */ + public DurableOperationController( + SubmitDurableOperationUseCase submit, + GetDurableOperationUseCase get, + CancelDurableOperationUseCase cancel) { + this.submit = Objects.requireNonNull(submit, "submit"); + this.get = Objects.requireNonNull(get, "get"); + this.cancel = Objects.requireNonNull(cancel, "cancel"); + } + + /** + * Accepts an operation. + * + *

{@code 202} with the operation's {@code Location}. The id is minted here; a resubmission of + * the same work by the same caller is recognised by its payload fingerprint and answered with the + * operation that already exists, {@code alreadyAccepted} true and the same {@code Location}. + */ + @PostMapping + public ResponseEntity> submit( + @Valid @RequestBody SubmitOperationHttpRequest request, + @AuthenticationPrincipal AuthenticatedPrincipal principal) { + String payload = request.payload().toString(); + OperationAcceptance acceptance = + submit.submit( + new OperationCommand( + new DurableOperationId(UUID.randomUUID().toString()), + request.operationName(), + principalId(principal), + null, + RequestFingerprint.ofSha256(payload.getBytes(StandardCharsets.UTF_8)), + payload, + OperationCommand.SUBMITTED_EVENT_TYPE, + OperationCommand.DEFAULT_TIME_TO_LIVE)); + URI location = + ServletUriComponentsBuilder.fromCurrentRequestUri() + .path("/{operationId}") + .buildAndExpand(acceptance.operationId().value()) + .toUri(); + return ResponseEntity.accepted() + .location(location) + .body( + Envelope.ok( + OperationAcceptedHttpResponse.from(acceptance), ResponseMetaFactory.fromMdc())); + } + + /** Reads one operation; {@code 404} when it does not exist or is not the caller's. */ + @GetMapping("/{operationId}") + public ResponseEntity> get( + @PathVariable String operationId, @AuthenticationPrincipal AuthenticatedPrincipal principal) { + return get.handle( + new GetDurableOperationQuery( + new DurableOperationId(operationId), principalId(principal), null)) + .>>map( + operation -> + ResponseEntity.ok( + Envelope.ok( + OperationHttpResponse.from(operation), ResponseMetaFactory.fromMdc()))) + .orElseGet(DurableOperationController::notFound); + } + + /** + * Requests cancellation; {@code 404} when the operation does not exist or is not the caller's. + * + *

{@code 202}, not {@code 204}: a worker mid-flight may still finish. {@code canceled} says + * whether this call moved it to CANCELED; a repeat, or a cancel of finished work, is {@code + * false} rather than an error. + */ + @DeleteMapping("/{operationId}") + public ResponseEntity> cancel( + @PathVariable String operationId, @AuthenticationPrincipal AuthenticatedPrincipal principal) { + DurableOperationId id = new DurableOperationId(operationId); + return cancel + .handle(new CancelDurableOperationCommand(id, principalId(principal), null)) + .>>map( + canceled -> + ResponseEntity.accepted() + .location(ServletUriComponentsBuilder.fromCurrentRequestUri().build().toUri()) + .body( + Envelope.ok( + new OperationCanceledHttpResponse(id.value(), canceled), + ResponseMetaFactory.fromMdc()))) + .orElseGet(DurableOperationController::notFound); + } + + // Unreachable through the shipped security chain, which authenticates every non-public path; + // a request that reaches here without our principal is refused rather than treated as anonymous. + private static String principalId(AuthenticatedPrincipal principal) { + if (principal == null || principal.idpUserId() == null || principal.idpUserId().isBlank()) { + throw new AuthenticationCredentialsNotFoundException("no authenticated principal"); + } + return principal.idpUserId(); + } + + private static ResponseEntity> notFound() { + return ResponseEntity.status(HttpStatus.NOT_FOUND) + .body( + ErrorResponseFactory.body( + OperationErrorCode.OPERATION_NOT_FOUND, "Operation was not found", null)); + } +} diff --git a/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/operation/OperationAcceptedHttpResponse.java b/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/operation/OperationAcceptedHttpResponse.java new file mode 100644 index 00000000..46435956 --- /dev/null +++ b/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/operation/OperationAcceptedHttpResponse.java @@ -0,0 +1,20 @@ +package dev.caskeleton.adapter.inbound.web.operation; + +import dev.caskeleton.application.operation.OperationAcceptance; +import java.time.Instant; + +/** + * The receipt for a submission. + * + * @param operationId the identity to poll + * @param acceptedAt when the operation was first accepted + * @param alreadyAccepted whether an identical earlier submission had already created it + */ +public record OperationAcceptedHttpResponse( + String operationId, Instant acceptedAt, boolean alreadyAccepted) { + + static OperationAcceptedHttpResponse from(OperationAcceptance acceptance) { + return new OperationAcceptedHttpResponse( + acceptance.operationId().value(), acceptance.acceptedAt(), acceptance.alreadyAccepted()); + } +} diff --git a/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/operation/OperationCanceledHttpResponse.java b/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/operation/OperationCanceledHttpResponse.java new file mode 100644 index 00000000..4e9ac0d6 --- /dev/null +++ b/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/operation/OperationCanceledHttpResponse.java @@ -0,0 +1,9 @@ +package dev.caskeleton.adapter.inbound.web.operation; + +/** + * The answer to a cancel request. + * + * @param operationId the operation asked about + * @param canceled whether this request moved it to CANCELED + */ +public record OperationCanceledHttpResponse(String operationId, boolean canceled) {} diff --git a/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/operation/OperationErrorCode.java b/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/operation/OperationErrorCode.java new file mode 100644 index 00000000..1ce07cb7 --- /dev/null +++ b/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/operation/OperationErrorCode.java @@ -0,0 +1,31 @@ +package dev.caskeleton.adapter.inbound.web.operation; + +import dev.caskeleton.shared.error.ApiErrorCode; +import dev.caskeleton.shared.error.Category; + +/** The operation endpoint's own error code, beside the skeleton-wide {@code OperationalError}. */ +enum OperationErrorCode implements ApiErrorCode { + + /** The operation does not exist, or belongs to another caller; the two are not told apart. */ + OPERATION_NOT_FOUND; + + @Override + public String code() { + return name(); + } + + @Override + public Category category() { + return Category.NOT_FOUND; + } + + @Override + public int httpStatus() { + return 404; + } + + @Override + public boolean retryable() { + return false; + } +} diff --git a/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/operation/OperationHttpResponse.java b/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/operation/OperationHttpResponse.java new file mode 100644 index 00000000..1fa0755c --- /dev/null +++ b/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/operation/OperationHttpResponse.java @@ -0,0 +1,77 @@ +package dev.caskeleton.adapter.inbound.web.operation; + +import dev.caskeleton.application.operation.DurableOperation; +import java.time.Instant; + +/** + * One operation as a poller sees it. + * + *

The lease and the submitted payload are left out: which worker holds the operation is not the + * caller's business, and the payload is what the caller sent. + * + * @param operationId the identity + * @param operationName what work this is + * @param state where in the lifecycle it is + * @param submittedAt when it was accepted + * @param startedAt when a worker first picked it up, or null + * @param completedAt when it reached a terminal state, or null + * @param progress how far it has got, or null + * @param resultReference where a successful result can be read, or null + * @param failure why it failed, or null + * @param expiresAt when this record stops being available + */ +public record OperationHttpResponse( + String operationId, + String operationName, + String state, + Instant submittedAt, + Instant startedAt, + Instant completedAt, + Progress progress, + String resultReference, + Failure failure, + Instant expiresAt) { + + /** + * Progress of a running operation. + * + * @param completedUnits work finished so far + * @param totalUnits work expected in total, or null when unknown + * @param phase the current stage, or null + */ + public record Progress(long completedUnits, Long totalUnits, String phase) {} + + /** + * Why an operation failed. + * + * @param code the stable failure code + * @param detail a message safe to publish + * @param retryable whether resubmitting the same work could succeed + */ + public record Failure(String code, String detail, boolean retryable) {} + + static OperationHttpResponse from(DurableOperation operation) { + return new OperationHttpResponse( + operation.operationId().value(), + operation.operationName(), + operation.state().name(), + operation.submittedAt(), + operation.startedAt().orElse(null), + operation.completedAt().orElse(null), + operation + .progress() + .map( + progress -> + new Progress( + progress.completedUnits(), + progress.totalUnits().orElse(null), + progress.phase().orElse(null))) + .orElse(null), + operation.resultReference().orElse(null), + operation + .failure() + .map(failure -> new Failure(failure.code(), failure.detail(), failure.retryable())) + .orElse(null), + operation.expiresAt()); + } +} diff --git a/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/operation/SubmitOperationHttpRequest.java b/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/operation/SubmitOperationHttpRequest.java new file mode 100644 index 00000000..51293070 --- /dev/null +++ b/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/operation/SubmitOperationHttpRequest.java @@ -0,0 +1,18 @@ +package dev.caskeleton.adapter.inbound.web.operation; + +import jakarta.validation.constraints.NotBlank; +import jakarta.validation.constraints.NotNull; +import jakarta.validation.constraints.Pattern; +import jakarta.validation.constraints.Size; +import tools.jackson.databind.JsonNode; + +/** + * A request to run work asynchronously. + * + * @param operationName what work this is, as the worker that runs it names it + * @param payload the request the worker will execute, any JSON value + */ +public record SubmitOperationHttpRequest( + @NotBlank @Size(max = 256) @Pattern(regexp = "[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*") + String operationName, + @NotNull JsonNode payload) {} diff --git a/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/auth/SecurityModeWebContractTest.java b/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/auth/SecurityModeWebContractTest.java index b736fd32..22f8a75e 100644 --- a/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/auth/SecurityModeWebContractTest.java +++ b/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/auth/SecurityModeWebContractTest.java @@ -6,6 +6,8 @@ import static org.springframework.test.web.servlet.request.MockMvcRequestBuilder import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content; import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status; +import com.jayway.jsonpath.JsonPath; +import dev.caskeleton.adapter.inbound.web.mvc.filter.WebMvcRequestIdFilter; import dev.caskeleton.adapter.inbound.web.settings.CorsSettings; import dev.caskeleton.adapter.inbound.web.settings.SecuritySettings; import jakarta.servlet.Filter; @@ -169,6 +171,32 @@ class SecurityModeWebContractTest { }); } + @Test + void anUnauthenticatedRejectionCarriesTheAssignedRequestIdInItsMeta() { + runner + .withPropertyValues( + "ca-skeleton.security.auth-mode=jwt", + "ca-skeleton.security.issuer-uri=https://issuer.example", + "ca-skeleton.cors.enabled=false") + .run( + context -> { + // given: the request-id filter sits in front of Spring Security, as registered + MockMvc mvc = + MockMvcBuilders.standaloneSetup(new ProbeController()) + .addFilters( + new WebMvcRequestIdFilter(), + context.getBean("springSecurityFilterChain", Filter.class)) + .build(); + + // when + var response = mvc.perform(get("/whoami")).andReturn().getResponse(); + + // then + assertThat(JsonPath.read(response.getContentAsString(), "$.meta.requestId")) + .isEqualTo(response.getHeader(WebMvcRequestIdFilter.REQUEST_ID_HEADER)); + }); + } + private static MockMvc mvc(Filter springSecurityFilterChain) { return MockMvcBuilders.standaloneSetup(new ProbeController()) .addFilters(springSecurityFilterChain) diff --git a/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/envelope/EnvelopeMetaIntegrationTest.java b/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/envelope/EnvelopeMetaIntegrationTest.java index 629d85d8..d8352cc3 100644 --- a/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/envelope/EnvelopeMetaIntegrationTest.java +++ b/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/envelope/EnvelopeMetaIntegrationTest.java @@ -5,7 +5,7 @@ import static org.springframework.test.web.servlet.result.MockMvcResultMatchers. import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status; import dev.caskeleton.adapter.inbound.web.error.GlobalExceptionHandler; -import dev.caskeleton.adapter.inbound.web.filter.RequestLoggingFilter; +import dev.caskeleton.adapter.inbound.web.mvc.filter.WebMvcRequestIdFilter; import dev.caskeleton.shared.tracing.SpanErrorRecorder; import java.util.Map; import org.junit.jupiter.api.BeforeEach; @@ -17,7 +17,7 @@ import org.springframework.web.bind.annotation.RestController; /** * End-to-end pin of the foundation envelope contract across the adapter-web chain: {@link - * RequestLoggingFilter} sets the SNAKE_CASE MDC ids, {@link EnvelopeBodyAdvice} (success) and + * WebMvcRequestIdFilter} sets the SNAKE_CASE MDC ids, {@link EnvelopeBodyAdvice} (success) and * {@link GlobalExceptionHandler} (5xx) project them onto a camelCase {@code meta} object. * Standalone MockMvc — no Spring context, so it neither needs the production {@code * application.yml} placeholders nor a security filter chain. @@ -30,7 +30,7 @@ class EnvelopeMetaIntegrationTest { void setUp() { mvc = MockMvcBuilders.standaloneSetup(new Probe()) - .addFilter(new RequestLoggingFilter(rawPrincipal -> rawPrincipal)) + .addFilter(new WebMvcRequestIdFilter()) .setControllerAdvice( new EnvelopeBodyAdvice(), new GlobalExceptionHandler(SpanErrorRecorder.NOOP)) .build(); diff --git a/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/error/GlobalExceptionHandlerTest.java b/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/error/GlobalExceptionHandlerTest.java index b53f5267..8c1a8fa2 100644 --- a/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/error/GlobalExceptionHandlerTest.java +++ b/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/error/GlobalExceptionHandlerTest.java @@ -42,6 +42,7 @@ import org.springframework.security.authentication.BadCredentialsException; import org.springframework.security.oauth2.server.resource.InvalidBearerTokenException; import org.springframework.validation.BeanPropertyBindingResult; import org.springframework.validation.FieldError; +import org.springframework.validation.ObjectError; import org.springframework.web.bind.MethodArgumentNotValidException; import org.springframework.web.context.request.ServletWebRequest; import org.springframework.web.method.annotation.MethodArgumentTypeMismatchException; @@ -198,6 +199,34 @@ class GlobalExceptionHandlerTest { .doesNotContain(secret, "rejectedValue", "rejected interpolated value", "[7]"); } + @Test + void classLevelConstraintViolationIsReportedAgainstTheRequest() { + // given + BeanPropertyBindingResult bindingResult = + new BeanPropertyBindingResult(new Object(), "request"); + bindingResult.addError( + new ObjectError( + "request", + new String[] {"ValidPeriod.request", "ValidPeriod"}, + null, + "end must not precede start")); + MethodArgumentNotValidException exception = + new MethodArgumentNotValidException(validationProbeParameter(), bindingResult); + + // when + ResponseEntity response = + handler.handleMethodArgumentNotValid( + exception, + new HttpHeaders(), + HttpStatus.BAD_REQUEST, + new ServletWebRequest(new MockHttpServletRequest())); + + // then + assertThat(((Envelope) response.getBody()).error().details()) + .isEqualTo( + List.of(Map.of("field", "request", "code", "INVALID", "message", "Invalid value"))); + } + @Test void unreadableBodyCausedByTheSizeCeilingIsPayloadTooLarge() { // given: the parser wraps the ceiling's exception when it fires inside a bean property diff --git a/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/filter/RequestLoggingFilterTest.java b/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/filter/RequestLoggingFilterTest.java index 5b12449f..076d1207 100644 --- a/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/filter/RequestLoggingFilterTest.java +++ b/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/filter/RequestLoggingFilterTest.java @@ -7,8 +7,7 @@ import ch.qos.logback.core.read.ListAppender; import dev.caskeleton.adapter.inbound.web.auth.AuthenticatedPrincipal; import dev.caskeleton.adapter.inbound.web.mvc.filter.WebMvcRequestIdFilter; import dev.caskeleton.adapter.inbound.web.observability.MdcKeys; -import dev.caskeleton.adapter.inbound.web.observability.ResponseMetaFactory; -import jakarta.servlet.FilterChain; +import jakarta.servlet.http.HttpServletRequest; import java.util.List; import java.util.Set; import java.util.concurrent.atomic.AtomicReference; @@ -22,6 +21,9 @@ import org.springframework.security.authentication.TestingAuthenticationToken; import org.springframework.security.core.context.SecurityContextHolder; import org.springframework.web.servlet.HandlerMapping; +/** + * The access log. Identifiers are {@link WebMvcRequestIdFilter}'s; its tests own their assignment. + */ class RequestLoggingFilterTest { private final RequestLoggingFilter filter = new RequestLoggingFilter(raw -> "pseudo-" + raw); @@ -33,79 +35,43 @@ class RequestLoggingFilterTest { } @Test - void generatesSnakeCaseRequestIdAndEchoesHeaderWhenAbsent() throws Exception { - MockHttpServletRequest req = new MockHttpServletRequest("GET", "/x"); + void assignsNoIdentifierOrTraceOfItsOwn() throws Exception { + // given MockHttpServletResponse res = new MockHttpServletResponse(); - AtomicReference seen = new AtomicReference<>(); - FilterChain chain = (rq, rs) -> seen.set(MDC.get(MdcKeys.REQUEST_ID)); - filter.doFilter(req, res, chain); + // when + filter.doFilter(new MockHttpServletRequest("GET", "/x"), res, (rq, rs) -> {}); - assertThat(seen.get()).as("request_id present on MDC during the chain").isNotBlank(); - assertThat(res.getHeader("X-Request-Id")).isEqualTo(seen.get()); - assertThat(MDC.get(MdcKeys.REQUEST_ID)).as("MDC cleared after request").isNull(); + // then + assertThat(res.getHeaderNames()) + .doesNotContain("X-Request-Id", "X-Correlation-Id", "traceparent"); } @Test - void rejectsClientRequestIdByDefaultButHonoursCorrelationId() throws Exception { + void accessLogLineCarriesTheRequestIdTheRequestIdFilterAssigned() throws Exception { + // given MockHttpServletRequest req = new MockHttpServletRequest("GET", "/x"); - req.addHeader("X-Request-Id", "client-req-1"); - req.addHeader("X-Correlation-Id", "client-corr-1"); - MockHttpServletResponse res = new MockHttpServletResponse(); - AtomicReference reqId = new AtomicReference<>(); - AtomicReference corrId = new AtomicReference<>(); - FilterChain chain = - (rq, rs) -> { - reqId.set(MDC.get(MdcKeys.REQUEST_ID)); - corrId.set(MDC.get(MdcKeys.CORRELATION_ID)); - }; - - filter.doFilter(req, res, chain); - - assertThat(reqId.get()).isNotEqualTo("client-req-1"); - assertThat(res.getHeader("X-Request-Id")).isEqualTo(reqId.get()); - assertThat(corrId.get()).isEqualTo("client-corr-1"); - assertThat(res.getHeader("X-Correlation-Id")).isEqualTo("client-corr-1"); - } - - @Test - void usesTheRequestIdAlreadyAssignedByTheMvcRequestIdFilter() throws Exception { - MockHttpServletRequest req = new MockHttpServletRequest("GET", "/x"); - req.addHeader("X-Request-Id", "chosen-by-caller"); - MockHttpServletResponse res = new MockHttpServletResponse(); AtomicReference assigned = new AtomicReference<>(); - AtomicReference logged = new AtomicReference<>(); - WebMvcRequestIdFilter requestIds = new WebMvcRequestIdFilter(); + ListAppender accessLog = attachAppender(); - requestIds.doFilter( - req, - res, - (rq, rs) -> { - assigned.set( - WebMvcRequestIdFilter.requestId((jakarta.servlet.http.HttpServletRequest) rq) - .orElseThrow() - .value()); - filter.doFilter( - rq, rs, (innerRequest, innerResponse) -> logged.set(MDC.get(MdcKeys.REQUEST_ID))); - }); + // when + try { + new WebMvcRequestIdFilter() + .doFilter( + req, + new MockHttpServletResponse(), + (rq, rs) -> { + assigned.set( + WebMvcRequestIdFilter.requestId((HttpServletRequest) rq).orElseThrow().value()); + filter.doFilter(rq, rs, (innerRequest, innerResponse) -> {}); + }); + } finally { + detach(accessLog); + } - assertThat(assigned.get()).isNotEqualTo("chosen-by-caller"); - assertThat(logged.get()).isEqualTo(assigned.get()); - assertThat(res.getHeader("X-Request-Id")).isEqualTo(assigned.get()); - } - - @Test - void sanitizesCrlfInjectionInInboundCorrelationId() throws Exception { - MockHttpServletRequest req = new MockHttpServletRequest("GET", "/x"); - req.addHeader("X-Correlation-Id", "foo\r\nFAKE LOG"); - MockHttpServletResponse res = new MockHttpServletResponse(); - AtomicReference correlationId = new AtomicReference<>(); - FilterChain chain = (rq, rs) -> correlationId.set(MDC.get(MdcKeys.CORRELATION_ID)); - - filter.doFilter(req, res, chain); - - assertThat(correlationId.get()).isEqualTo("fooFAKE LOG"); - assertThat(correlationId.get()).doesNotContain("\r").doesNotContain("\n"); + // then + assertThat(httpRequestEvent(accessLog).getMDCPropertyMap().get(MdcKeys.REQUEST_ID)) + .isEqualTo(assigned.get()); } // DRIFT-3: logs the route template, not the raw concrete path @@ -114,175 +80,19 @@ class RequestLoggingFilterTest { MockHttpServletRequest req = new MockHttpServletRequest("GET", "/v1/worklogs/123"); req.setAttribute(HandlerMapping.BEST_MATCHING_PATTERN_ATTRIBUTE, "/v1/worklogs/{id}"); MockHttpServletResponse res = new MockHttpServletResponse(); - - ch.qos.logback.classic.Logger logger = - (ch.qos.logback.classic.Logger) LoggerFactory.getLogger(RequestLoggingFilter.class); - ListAppender listAppender = new ListAppender<>(); - listAppender.start(); - logger.addAppender(listAppender); + ListAppender listAppender = attachAppender(); try { filter.doFilter(req, res, (rq, rs) -> {}); - List events = listAppender.list; - assertThat(events).isNotEmpty(); - ILoggingEvent event = - events.stream() - .filter(e -> e.getFormattedMessage().contains("http_request")) - .findFirst() - .orElseThrow(() -> new AssertionError("No http_request log event found")); - - String msg = event.getFormattedMessage(); + String msg = httpRequestEvent(listAppender).getFormattedMessage(); assertThat(msg).contains("uri_template=/v1/worklogs/{id}"); assertThat(msg).doesNotContain("uri_template=/v1/worklogs/123"); } finally { - logger.detachAppender(listAppender); + detach(listAppender); } } - // feature-distributed-tracing-contract D5/D7/D4: W3C traceparent handling - - /** - * D5/D7: a valid inbound {@code traceparent} header is adopted — its traceId and spanId are - * placed on MDC and the same traceparent value is echoed on the response. D4: {@link - * ResponseMetaFactory#fromMdc()} returns a non-null traceId. - */ - @Test - void validInboundTraceparentIsAdoptedIntoMdcAndEchoedOnResponse() throws Exception { - String validTraceparent = "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"; - MockHttpServletRequest req = new MockHttpServletRequest("GET", "/x"); - req.addHeader("traceparent", validTraceparent); - MockHttpServletResponse res = new MockHttpServletResponse(); - - AtomicReference capturedTraceId = new AtomicReference<>(); - AtomicReference capturedSpanId = new AtomicReference<>(); - AtomicReference capturedMetaTraceId = new AtomicReference<>(); - FilterChain chain = - (rq, rs) -> { - capturedTraceId.set(MDC.get(MdcKeys.TRACE_ID)); - capturedSpanId.set(MDC.get(MdcKeys.SPAN_ID)); - capturedMetaTraceId.set(ResponseMetaFactory.fromMdc().traceId()); - }; - - filter.doFilter(req, res, chain); - - assertThat(capturedTraceId.get()) - .as("MDC trace_id must be adopted from traceparent traceId") - .isEqualTo("4bf92f3577b34da6a3ce929d0e0e4736"); - assertThat(capturedSpanId.get()) - .as("MDC span_id must be adopted from traceparent spanId") - .isEqualTo("00f067aa0ba902b7"); - assertThat(res.getHeader("traceparent")) - .as("response traceparent must echo the resolved value") - .isEqualTo(validTraceparent); - assertThat(capturedMetaTraceId.get()) - .as("D4: ResponseMetaFactory.fromMdc().traceId() must be non-null when traceparent adopted") - .isEqualTo("4bf92f3577b34da6a3ce929d0e0e4736"); - // MDC must be cleaned up after filter - assertThat(MDC.get(MdcKeys.TRACE_ID)).isNull(); - assertThat(MDC.get(MdcKeys.SPAN_ID)).isNull(); - } - - /** - * D4 / disabled-tracing fallback: when no inbound {@code traceparent} header is present, the - * filter generates a fresh ROOT traceparent — 32-hex traceId (non-null, non-all-zeros), so {@link - * ResponseMetaFactory#fromMdc()} keeps {@code meta.traceId} non-null even when no tracer/exporter - * is wired. - */ - @Test - void absentTraceparentGeneratesFreshW3cRootAndMetaTraceIdIsNonNull() throws Exception { - MockHttpServletRequest req = new MockHttpServletRequest("GET", "/y"); - MockHttpServletResponse res = new MockHttpServletResponse(); - - AtomicReference capturedTraceId = new AtomicReference<>(); - AtomicReference capturedSpanId = new AtomicReference<>(); - AtomicReference capturedMetaTraceId = new AtomicReference<>(); - FilterChain chain = - (rq, rs) -> { - capturedTraceId.set(MDC.get(MdcKeys.TRACE_ID)); - capturedSpanId.set(MDC.get(MdcKeys.SPAN_ID)); - capturedMetaTraceId.set(ResponseMetaFactory.fromMdc().traceId()); - }; - - filter.doFilter(req, res, chain); - - assertThat(capturedTraceId.get()) - .as("generated trace_id must be non-null, 32 hex chars") - .isNotNull() - .hasSize(32) - .matches("[0-9a-f]{32}"); - assertThat(capturedTraceId.get()) - .as("generated trace_id must not be all zeros") - .isNotEqualTo("00000000000000000000000000000000"); - assertThat(capturedSpanId.get()) - .as("generated span_id must be non-null, 16 hex chars") - .isNotNull() - .hasSize(16) - .matches("[0-9a-f]{16}"); - assertThat(res.getHeader("traceparent")) - .as("response traceparent header must be set") - .isNotNull() - .startsWith("00-"); - assertThat(capturedMetaTraceId.get()) - .as("D4: meta.traceId must be non-null even with no tracer (disabled-tracing fallback)") - .isNotNull() - .hasSize(32); - } - - /** - * D4 fallback: an INVALID inbound {@code traceparent} header (malformed) yields the same - * generated-root behavior — traceId is a fresh 32-hex value. - */ - @Test - void invalidTraceparentGeneratesFreshRootTraceId() throws Exception { - MockHttpServletRequest req = new MockHttpServletRequest("GET", "/z"); - req.addHeader("traceparent", "NOT-A-VALID-TRACEPARENT"); - MockHttpServletResponse res = new MockHttpServletResponse(); - - AtomicReference capturedTraceId = new AtomicReference<>(); - FilterChain chain = (rq, rs) -> capturedTraceId.set(MDC.get(MdcKeys.TRACE_ID)); - - filter.doFilter(req, res, chain); - - assertThat(capturedTraceId.get()) - .as("invalid traceparent must yield a fresh generated 32-hex traceId") - .isNotNull() - .hasSize(32) - .matches("[0-9a-f]{32}"); - } - - /** - * §테스트계약: request_id and correlation_id MDC keys are still set regardless of traceparent - * handling, keeping existing observability contracts intact. - */ - @Test - void requestIdAndCorrelationIdMdcStillSetAlongsideTraceparent() throws Exception { - MockHttpServletRequest req = new MockHttpServletRequest("GET", "/w"); - req.addHeader("X-Request-Id", "my-req-id"); - req.addHeader("X-Correlation-Id", "my-corr-id"); - MockHttpServletResponse res = new MockHttpServletResponse(); - - AtomicReference capturedReqId = new AtomicReference<>(); - AtomicReference capturedCorrId = new AtomicReference<>(); - AtomicReference capturedTraceId = new AtomicReference<>(); - FilterChain chain = - (rq, rs) -> { - capturedReqId.set(MDC.get(MdcKeys.REQUEST_ID)); - capturedCorrId.set(MDC.get(MdcKeys.CORRELATION_ID)); - capturedTraceId.set(MDC.get(MdcKeys.TRACE_ID)); - }; - - filter.doFilter(req, res, chain); - - assertThat(capturedReqId.get()).isNotEqualTo("my-req-id"); - assertThat(capturedCorrId.get()).isEqualTo("my-corr-id"); - assertThat(capturedTraceId.get()) - .as("trace_id must be set (W3C generated root since no traceparent header)") - .isNotNull() - .hasSize(32) - .matches("[0-9a-f]{32}"); - } - // DRIFT-6: user_principal on MDC must be pseudonymized, never raw @Test void putsPseudonymizedUserPrincipalOnMdcNotRawId() throws Exception { @@ -294,31 +104,42 @@ class RequestLoggingFilterTest { MockHttpServletRequest req = new MockHttpServletRequest("GET", "/v1/test"); MockHttpServletResponse res = new MockHttpServletResponse(); - - ch.qos.logback.classic.Logger logger = - (ch.qos.logback.classic.Logger) LoggerFactory.getLogger(RequestLoggingFilter.class); - ListAppender listAppender = new ListAppender<>(); - listAppender.start(); - logger.addAppender(listAppender); + ListAppender listAppender = attachAppender(); try { // user_principal is set in the filter's finally block (after chain.doFilter) and is // captured on the http_request log event's MDC snapshot, asserted below. filter.doFilter(req, res, (rq, rs) -> {}); - // Capture the MDC value from the http_request log event (which fires after putUserPrincipal) - List events = listAppender.list; - ILoggingEvent event = - events.stream() - .filter(e -> e.getFormattedMessage().contains("http_request")) - .findFirst() - .orElseThrow(() -> new AssertionError("No http_request log event found")); - - String userPrincipalOnMdc = event.getMDCPropertyMap().get("user_principal"); + String userPrincipalOnMdc = + httpRequestEvent(listAppender).getMDCPropertyMap().get("user_principal"); assertThat(userPrincipalOnMdc).isEqualTo("pseudo-raw-user-1"); assertThat(userPrincipalOnMdc).isNotEqualTo("raw-user-1"); } finally { - logger.detachAppender(listAppender); + detach(listAppender); } } + + private static ListAppender attachAppender() { + ListAppender appender = new ListAppender<>(); + appender.start(); + logger().addAppender(appender); + return appender; + } + + private static void detach(ListAppender appender) { + logger().detachAppender(appender); + } + + private static ch.qos.logback.classic.Logger logger() { + return (ch.qos.logback.classic.Logger) LoggerFactory.getLogger(RequestLoggingFilter.class); + } + + private static ILoggingEvent httpRequestEvent(ListAppender appender) { + List events = appender.list; + return events.stream() + .filter(e -> e.getFormattedMessage().contains("http_request")) + .findFirst() + .orElseThrow(() -> new AssertionError("No http_request log event found")); + } } diff --git a/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/mvc/filter/WebMvcRequestIdFilterTest.java b/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/mvc/filter/WebMvcRequestIdFilterTest.java index 4810257d..b9b21c87 100644 --- a/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/mvc/filter/WebMvcRequestIdFilterTest.java +++ b/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/mvc/filter/WebMvcRequestIdFilterTest.java @@ -2,8 +2,15 @@ package dev.caskeleton.adapter.inbound.web.mvc.filter; import static org.assertj.core.api.Assertions.assertThat; +import dev.caskeleton.adapter.inbound.web.observability.MdcKeys; +import dev.caskeleton.shared.tracing.TraceParent; +import jakarta.servlet.DispatcherType; +import java.util.HashMap; +import java.util.List; +import java.util.Map; import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; +import org.slf4j.MDC; import org.springframework.mock.web.MockFilterChain; import org.springframework.mock.web.MockHttpServletRequest; import org.springframework.mock.web.MockHttpServletResponse; @@ -67,5 +74,120 @@ class WebMvcRequestIdFilterTest { .isPresent(); } + @Test + void assignedIdentifiersAreOnMdcDuringTheChainAndMatchWhatTheResponseCarries() throws Exception { + // given + MockHttpServletRequest request = new MockHttpServletRequest(); + request.addHeader(CORRELATION_ID_HEADER, "corr-1"); + MockHttpServletResponse response = new MockHttpServletResponse(); + Map duringChain = new HashMap<>(); + + // when + new WebMvcRequestIdFilter().doFilter(request, response, (rq, rs) -> duringChain.putAll(mdc())); + + // then + TraceParent echoed = + TraceParent.parse(response.getHeader(WebMvcRequestIdFilter.TRACEPARENT_HEADER)) + .orElseThrow(); + assertThat(duringChain) + .containsExactlyInAnyOrderEntriesOf( + Map.of( + MdcKeys.REQUEST_ID, response.getHeader(WebMvcRequestIdFilter.REQUEST_ID_HEADER), + MdcKeys.CORRELATION_ID, "corr-1", + MdcKeys.TRACE_ID, WebMvcRequestIdFilter.traceId(request).orElseThrow().value(), + MdcKeys.SPAN_ID, echoed.spanId())); + } + + @Test + void responseTraceparentCarriesTheTraceIdTheFilterAssigned() throws Exception { + // given + MockHttpServletRequest request = new MockHttpServletRequest(); + MockHttpServletResponse response = new MockHttpServletResponse(); + + // when + new WebMvcRequestIdFilter().doFilter(request, response, new MockFilterChain()); + + // then + assertThat(response.getHeader(WebMvcRequestIdFilter.TRACEPARENT_HEADER)) + .startsWith("00-" + WebMvcRequestIdFilter.traceId(request).orElseThrow().value() + "-"); + } + + @Test + void validInboundTraceparentIsAdoptedWithItsSpanAndEchoed() throws Exception { + // given + String inbound = "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"; + MockHttpServletRequest request = new MockHttpServletRequest(); + request.addHeader(WebMvcRequestIdFilter.TRACEPARENT_HEADER, inbound); + MockHttpServletResponse response = new MockHttpServletResponse(); + Map duringChain = new HashMap<>(); + + // when + new WebMvcRequestIdFilter().doFilter(request, response, (rq, rs) -> duringChain.putAll(mdc())); + + // then + assertThat( + List.of( + duringChain.get(MdcKeys.TRACE_ID), + duringChain.get(MdcKeys.SPAN_ID), + response.getHeader(WebMvcRequestIdFilter.TRACEPARENT_HEADER))) + .containsExactly("4bf92f3577b34da6a3ce929d0e0e4736", "00f067aa0ba902b7", inbound); + } + + @Test + void inboundCorrelationIdLosesLineBreaksBeforeReachingMdc() throws Exception { + // given + MockHttpServletRequest request = new MockHttpServletRequest(); + request.addHeader(CORRELATION_ID_HEADER, "foo\r\nFAKE LOG"); + Map duringChain = new HashMap<>(); + + // when + new WebMvcRequestIdFilter() + .doFilter(request, new MockHttpServletResponse(), (rq, rs) -> duringChain.putAll(mdc())); + + // then + assertThat(duringChain.get(MdcKeys.CORRELATION_ID)).isEqualTo("fooFAKE LOG"); + } + + @Test + void mdcIsClearedWhenTheRequestLeavesTheFilter() throws Exception { + // when + new WebMvcRequestIdFilter() + .doFilter( + new MockHttpServletRequest(), new MockHttpServletResponse(), new MockFilterChain()); + + // then + assertThat(mdc()).isEmpty(); + } + + @Test + void anErrorRedispatchRestoresTheSameIdentifiersOnMdc() throws Exception { + // given + MockHttpServletRequest request = new MockHttpServletRequest(); + WebMvcRequestIdFilter filter = new WebMvcRequestIdFilter(); + Map firstPass = new HashMap<>(); + filter.doFilter(request, new MockHttpServletResponse(), (rq, rs) -> firstPass.putAll(mdc())); + request.setDispatcherType(DispatcherType.ERROR); + Map errorPass = new HashMap<>(); + + // when + filter.doFilter(request, new MockHttpServletResponse(), (rq, rs) -> errorPass.putAll(mdc())); + + // then + assertThat(errorPass).isEqualTo(firstPass); + } + + private static Map mdc() { + Map copy = new HashMap<>(); + for (String key : + List.of(MdcKeys.REQUEST_ID, MdcKeys.CORRELATION_ID, MdcKeys.TRACE_ID, MdcKeys.SPAN_ID)) { + String value = MDC.get(key); + if (value != null) { + copy.put(key, value); + } + } + return copy; + } + private static final String NEWLINE = "\n"; + private static final String CORRELATION_ID_HEADER = "X-Correlation-Id"; } diff --git a/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/operation/DurableOperationControllerTest.java b/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/operation/DurableOperationControllerTest.java new file mode 100644 index 00000000..a6ddbb4e --- /dev/null +++ b/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/operation/DurableOperationControllerTest.java @@ -0,0 +1,246 @@ +package dev.caskeleton.adapter.inbound.web.operation; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.delete; +import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get; +import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post; +import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.header; +import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath; +import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status; + +import com.jayway.jsonpath.JsonPath; +import dev.caskeleton.adapter.inbound.web.auth.AuthenticatedPrincipal; +import dev.caskeleton.adapter.inbound.web.envelope.EnvelopeBodyAdvice; +import dev.caskeleton.adapter.inbound.web.error.GlobalExceptionHandler; +import dev.caskeleton.application.operation.CancelDurableOperationUseCase; +import dev.caskeleton.application.operation.GetDurableOperationUseCase; +import dev.caskeleton.application.operation.OperationCommand; +import dev.caskeleton.application.operation.SubmitDurableOperationUseCase; +import dev.caskeleton.application.operation.testkit.InMemoryDurableOperationStore; +import dev.caskeleton.application.outbox.testkit.InMemoryOutboxStore; +import dev.caskeleton.application.transaction.testkit.DirectTransactionPort; +import dev.caskeleton.shared.tracing.SpanErrorRecorder; +import java.time.Clock; +import java.time.Instant; +import java.time.ZoneOffset; +import java.util.List; +import java.util.Set; +import org.junit.jupiter.api.AfterEach; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.springframework.http.MediaType; +import org.springframework.security.authentication.TestingAuthenticationToken; +import org.springframework.security.core.context.SecurityContextHolder; +import org.springframework.security.web.method.annotation.AuthenticationPrincipalArgumentResolver; +import org.springframework.test.web.servlet.MockMvc; +import org.springframework.test.web.servlet.MvcResult; +import org.springframework.test.web.servlet.ResultActions; +import org.springframework.test.web.servlet.setup.MockMvcBuilders; + +/** + * The HTTP contract of the operation endpoints over the real use cases and the port owners' fakes. + * + *

Standalone MockMvc: no security filter chain and no method-security proxy, so the permission + * gate on submit and cancel is not exercised here — the composition test in app-bootstrap is where + * the assembled beans are proxied. + */ +class DurableOperationControllerTest { + + private static final String REPORT = + "{\"operationName\":\"reports.generate\",\"payload\":{\"range\":\"2026-08\"}}"; + + private final InMemoryDurableOperationStore operations = new InMemoryDurableOperationStore(); + private final InMemoryOutboxStore outbox = new InMemoryOutboxStore(); + private final DirectTransactionPort transactions = new DirectTransactionPort(); + private final Clock clock = Clock.fixed(Instant.parse("2026-09-25T00:00:00Z"), ZoneOffset.UTC); + + private MockMvc mvc; + + @BeforeEach + void setUp() { + DurableOperationController controller = + new DurableOperationController( + new SubmitDurableOperationUseCase(operations, outbox, transactions, clock), + new GetDurableOperationUseCase(operations, transactions, clock), + new CancelDurableOperationUseCase(operations, transactions, clock)); + mvc = + MockMvcBuilders.standaloneSetup(controller) + .setControllerAdvice( + new GlobalExceptionHandler(SpanErrorRecorder.NOOP), new EnvelopeBodyAdvice()) + .setCustomArgumentResolvers(new AuthenticationPrincipalArgumentResolver()) + .build(); + } + + @AfterEach + void signOut() { + SecurityContextHolder.clearContext(); + } + + @Test + void aSubmissionIsAcceptedWith202AndTheOperationsLocationInAnEnvelope() throws Exception { + // given + signIn("alice"); + + // when + ResultActions response = submit(REPORT); + + // then + String operationId = operationIdOf(response.andReturn()); + response + .andExpect(status().isAccepted()) + .andExpect(header().string("Location", "http://localhost/operations/" + operationId)) + .andExpect(jsonPath("$.success").value(true)) + .andExpect(jsonPath("$.data.alreadyAccepted").value(false)); + } + + @Test + void anIdenticalResubmissionPointsAtTheFirstOperation() throws Exception { + // given + signIn("alice"); + String first = submit(REPORT).andReturn().getResponse().getHeader("Location"); + + // when + MvcResult again = submit(REPORT).andReturn(); + + // then + assertThat( + List.of( + again.getResponse().getHeader("Location"), + JsonPath.read(again.getResponse().getContentAsString(), "$.data.alreadyAccepted"))) + .containsExactly(first, true); + } + + @Test + void aSubmissionAppendsItsOutboxEventUnderTheSubmittedEventTypeNotOneTheCallerChose() + throws Exception { + // given + signIn("alice"); + + // when + submit(REPORT); + + // then + assertThat(outbox.oldestUnpublishedAgeSecondsByEventType(clock.instant())) + .containsOnlyKeys(OperationCommand.SUBMITTED_EVENT_TYPE); + } + + @Test + void theSubmitterReadsTheirOperation() throws Exception { + // given + signIn("alice"); + String operationId = operationIdOf(submit(REPORT).andReturn()); + + // when + ResultActions response = mvc.perform(get("/operations/" + operationId)); + + // then + response + .andExpect(status().isOk()) + .andExpect(jsonPath("$.data.operationId").value(operationId)) + .andExpect(jsonPath("$.data.operationName").value("reports.generate")) + .andExpect(jsonPath("$.data.state").value("PENDING")); + } + + @Test + void anotherCallerReadingTheOperationGetsTheSame404AsForAnUnknownOne() throws Exception { + // given + signIn("alice"); + String operationId = operationIdOf(submit(REPORT).andReturn()); + signIn("bob"); + + // when + ResultActions response = mvc.perform(get("/operations/" + operationId)); + + // then + response + .andExpect(status().isNotFound()) + .andExpect(jsonPath("$.success").value(false)) + .andExpect(jsonPath("$.error.code").value("OPERATION_NOT_FOUND")); + } + + @Test + void anUnknownOperationIs404() throws Exception { + // given + signIn("alice"); + + // when + ResultActions response = mvc.perform(get("/operations/no-such-operation")); + + // then + response + .andExpect(status().isNotFound()) + .andExpect(jsonPath("$.error.code").value("OPERATION_NOT_FOUND")); + } + + @Test + void theSubmitterCancelsTheirOperationWith202() throws Exception { + // given + signIn("alice"); + String operationId = operationIdOf(submit(REPORT).andReturn()); + + // when + ResultActions response = mvc.perform(delete("/operations/" + operationId)); + + // then + response + .andExpect(status().isAccepted()) + .andExpect(header().string("Location", "http://localhost/operations/" + operationId)) + .andExpect(jsonPath("$.data.canceled").value(true)); + } + + @Test + void anotherCallerCancelingTheOperationGets404() throws Exception { + // given + signIn("alice"); + String operationId = operationIdOf(submit(REPORT).andReturn()); + signIn("bob"); + + // when + ResultActions response = mvc.perform(delete("/operations/" + operationId)); + + // then + response + .andExpect(status().isNotFound()) + .andExpect(jsonPath("$.error.code").value("OPERATION_NOT_FOUND")); + } + + @Test + void aSubmissionWithoutAnOperationNameIsAValidationFailure() throws Exception { + // given + signIn("alice"); + + // when + ResultActions response = submit("{\"payload\":{}}"); + + // then + response + .andExpect(status().isBadRequest()) + .andExpect(jsonPath("$.error.code").value("VALIDATION_FAILED")); + } + + @Test + void aRequestWithoutAnAuthenticatedPrincipalIs401() throws Exception { + // when + ResultActions response = submit(REPORT); + + // then + response + .andExpect(status().isUnauthorized()) + .andExpect(jsonPath("$.error.code").value("UNAUTHENTICATED")); + } + + private ResultActions submit(String body) throws Exception { + return mvc.perform(post("/operations").contentType(MediaType.APPLICATION_JSON).content(body)); + } + + private static String operationIdOf(MvcResult result) throws Exception { + return JsonPath.read(result.getResponse().getContentAsString(), "$.data.operationId"); + } + + private static void signIn(String subject) { + SecurityContextHolder.getContext() + .setAuthentication( + new TestingAuthenticationToken( + new AuthenticatedPrincipal(subject, subject + "@example.test", Set.of()), "n/a")); + } +} diff --git a/src/adapter/inbound/web/src/testFixtures/java/dev/caskeleton/webtestkit/PipelineOrderFixtureApplication.java b/src/adapter/inbound/web/src/testFixtures/java/dev/caskeleton/webtestkit/PipelineOrderFixtureApplication.java index e463b655..c412075d 100644 --- a/src/adapter/inbound/web/src/testFixtures/java/dev/caskeleton/webtestkit/PipelineOrderFixtureApplication.java +++ b/src/adapter/inbound/web/src/testFixtures/java/dev/caskeleton/webtestkit/PipelineOrderFixtureApplication.java @@ -42,7 +42,11 @@ import org.springframework.web.servlet.config.annotation.WebMvcConfigurer; // @SpringBootTest(classes = ...), so the package is what keeps it out. @Configuration(proxyBeanMethods = false) // Not the adapter's own root: its security chain and filters would be stages this fixture did not -// declare, and the recorded order would be about them rather than the semantic pipeline. +// declare, and the recorded order would be about them rather than the semantic pipeline. So this +// fixture proves the semantic order and the async single-observation, not where the real filters +// sit: the registered order of the request-id filter against springSecurityFilterChain is asserted +// on the real auto-configuration by app-bootstrap's OperationalContractRuntimeTest, and the +// consequence (a 401 envelope carrying the assigned request id) by SecurityModeWebContractTest. @EnableAutoConfiguration(exclude = WebAdapterAutoConfiguration.class) @Import(PipelineOrderFixtureController.class) public class PipelineOrderFixtureApplication implements WebMvcConfigurer { diff --git a/src/adapter/outbound/cache-redis/README.md b/src/adapter/outbound/cache-redis/README.md index 2f72e69c..4d17f2be 100644 --- a/src/adapter/outbound/cache-redis/README.md +++ b/src/adapter/outbound/cache-redis/README.md @@ -109,12 +109,20 @@ sent. Rate limiting, distributed leases and Redis idempotency execute Lua programs. If any of those roles select Redis, the composition root runs a startup probe on the SCRIPT lane: -1. `SCRIPT LOAD` a mutation-free `return {1}` program; +1. `SCRIPT LOAD` a program that calls the commands the semantic scripts depend on — `TIME`, then + `HSET`/`PEXPIRE`/`HGET`/`DEL` on its own probe key, which it deletes; 2. execute it through `EVALSHA`; -3. require the expected reply. +3. require the expected reply (the value it wrote reads back). -A deployment whose effective Redis account lacks script permissions fails during startup rather -than at the first request. Cache-only deployments do not run this probe. +Redis checks a script's inner commands against the ACL only when they run, so a probe that ran +nothing proved `EVALSHA` and nothing else: an account granted by category (`@read`/`@write`) lacks +`TIME` and failed every rate-limit and idempotency request after a clean start. A deployment whose +effective Redis account lacks script permissions fails during startup rather than at the first +request. Cache-only deployments do not run this probe. + +At runtime, `redisRequired` (redis-runtime) probes the SCRIPT lane too when a script role is +selected, so a broken advanced-account credential makes the pod unready instead of leaving the +regular-lane PING to report UP. ## Cache semantics @@ -217,7 +225,7 @@ Useful focused checks: ```bash ./gradlew :adapter:outbound:cache-redis:check ./gradlew :adapter:outbound:redis-runtime:check -./gradlew :app-bootstrap:test --tests '*RedisSemanticScriptAclProbeTest' +./gradlew :adapter:outbound:cache-redis:test --tests '*RedisSemanticScriptAclProbeTest' ./gradlew :app-bootstrap:verifyEnvKeys ./gradlew architectureCheck ``` diff --git a/src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/RedisSemanticFailureLogger.java b/src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/RedisSemanticFailureLogger.java index 1f6686a7..2d48829b 100644 --- a/src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/RedisSemanticFailureLogger.java +++ b/src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/RedisSemanticFailureLogger.java @@ -1,7 +1,10 @@ package dev.caskeleton.adapter.outbound.cache.redis; -import java.util.Set; +import java.time.Duration; +import java.util.Map; +import java.util.concurrent.CompletionException; import java.util.concurrent.ConcurrentHashMap; +import java.util.concurrent.ExecutionException; import org.slf4j.Logger; import org.slf4j.LoggerFactory; @@ -10,20 +13,32 @@ import org.slf4j.LoggerFactory; * degraded/indeterminate outcomes. * *

Never logs exception messages, Redis keys, values, command arguments or credential material. - * One warning per capability/operation/failure type makes a fail-open/fail-closed transition - * visible without turning a Redis outage into a log-flood outage; repeats stay at debug. + * One warning per capability/operation/failure type per {@link #WARN_INTERVAL} makes a + * fail-open/fail-closed transition visible without turning a Redis outage into a log-flood outage; + * repeats inside the interval stay at debug. Once per JVM was too few: an outage that started an + * hour after the first one was invisible at WARN. */ public final class RedisSemanticFailureLogger { + static final Duration WARN_INTERVAL = Duration.ofMinutes(1); + private static final Logger LOG = LoggerFactory.getLogger(RedisSemanticFailureLogger.class); - private static final Set WARNED = ConcurrentHashMap.newKeySet(); + + // Bounded by the code: capability x operation x the exception types a driver can raise. + private static final Map LAST_WARNED = new ConcurrentHashMap<>(); private RedisSemanticFailureLogger() {} public static void report(String capability, String operation, Throwable failure) { - String failureType = failure.getClass().getSimpleName(); + report(capability, operation, failure, System.nanoTime()); + } + + static void report(String capability, String operation, Throwable failure, long nowNanos) { + // The cause, not the future's wrapper: every failure read through `.get()` is an + // ExecutionException, which says nothing about what went wrong. + String failureType = causeOf(failure).getClass().getSimpleName(); String key = capability + ":" + operation + ":" + failureType; - if (WARNED.add(key)) { + if (claimWarning(key, nowNanos)) { LOG.warn( "Redis semantic operation degraded; capability={} operation={} failureType={}", capability, @@ -37,4 +52,27 @@ public final class RedisSemanticFailureLogger { failureType); } } + + private static boolean claimWarning(String key, long nowNanos) { + boolean[] claimed = {false}; + LAST_WARNED.compute( + key, + (ignored, last) -> { + if (last == null || nowNanos - last >= WARN_INTERVAL.toNanos()) { + claimed[0] = true; + return nowNanos; + } + return last; + }); + return claimed[0]; + } + + private static Throwable causeOf(Throwable failure) { + Throwable current = failure; + while ((current instanceof ExecutionException || current instanceof CompletionException) + && current.getCause() != null) { + current = current.getCause(); + } + return current; + } } diff --git a/src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/cache/RedisCacheRegionAdapter.java b/src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/cache/RedisCacheRegionAdapter.java index 5599318c..d46e2891 100644 --- a/src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/cache/RedisCacheRegionAdapter.java +++ b/src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/cache/RedisCacheRegionAdapter.java @@ -27,8 +27,10 @@ import java.util.function.Function; * *

The only port in this leaf that may degrade rather than fail. A cache exists to make things * faster, so an unreachable cache means slower, not broken — every failure path returns a miss or - * {@code DEGRADED_UNAVAILABLE} and the caller falls back to the source. That licence is specific to - * this port and must never be copied to session, idempotency, rate limit, or lease, where the same + * {@code DEGRADED_UNAVAILABLE} and the caller falls back to the source. A write whose command was + * sent and whose reply was lost says {@code INDETERMINATE} instead, because it may have landed; + * {@code DEGRADED_UNAVAILABLE} is kept for writes that never left. That licence is specific to this + * port and must never be copied to session, idempotency, rate limit, or lease, where the same * behaviour would mean serving without the guarantee the caller asked for. * *

Three things this adapter refuses to treat as an ordinary miss, because each of them means the @@ -221,6 +223,9 @@ public final class RedisCacheRegionAdapter implements CacheRegionPort 0 ? ttl : softTtl; byte[] physicalKey = keys.entryKey(keyDigest.apply(key)); + // Whether the write command itself was handed to the driver. A failure before that point — + // lane refusal, connection, the generation read — wrote nothing. + boolean sent = false; try (RedisLease lease = owner.borrow(RedisConnectionKind.REGULAR)) { resolveGeneration(lease, now); CacheEnvelope envelope = @@ -233,6 +238,7 @@ public final class RedisCacheRegionAdapter implements CacheRegionPort implements CacheRegionPort implements CacheRegionPort implements CacheRegionPort implements CacheRegionPort policiesOf( - RedisCapabilitySettings.RateLimit rateLimit) { + RedisCapabilitySettings.RateLimit rateLimit, String defaultPolicyId) { if (rateLimit.getPolicies().isEmpty()) { // An enabled limiter with no policy would answer every request "unknown policy", which the // port reports as a deployment error on every call rather than once at startup. @@ -72,10 +81,10 @@ class RedisRateLimitConfig { rateLimit .getPolicies() .forEach((id, policy) -> policies.put(id, policyOf(id, policy, rateLimit))); - if (!policies.containsKey(rateLimit.getDefaultPolicyId())) { + if (!policies.containsKey(defaultPolicyId)) { throw new CapabilityStartupValidationException( "the default rate-limit policy '" - + rateLimit.getDefaultPolicyId() + + defaultPolicyId + "' is not among the configured policies " + policies.keySet()); } diff --git a/src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/capability/RedisSemanticScriptAclProbe.java b/src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/capability/RedisSemanticScriptAclProbe.java index 426c877a..7025379e 100644 --- a/src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/capability/RedisSemanticScriptAclProbe.java +++ b/src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/capability/RedisSemanticScriptAclProbe.java @@ -20,14 +20,22 @@ import org.springframework.beans.factory.SmartInitializingSingleton; * nothing about the commands the semantic scripts call. {@code TIME} belongs to no data category * ({@code @read}/{@code @write}), so an account granted by category alone lacked it and every * rate-limit and idempotency request failed with {@code NOPERM} after a clean start. The probe runs - * the commands the scripts depend on. + * the commands the scripts depend on, on the probe key, and cleans up after itself; it answers + * {@code {1}} only when the value it wrote reads back. */ final class RedisSemanticScriptAclProbe implements SmartInitializingSingleton { private static final byte[] PROBE_SCRIPT = """ - redis.call('TIME') - return {1} + local t = redis.call('TIME') + redis.call('HSET', KEYS[1], 'probe', t[1]) + redis.call('PEXPIRE', KEYS[1], 10000) + local stored = redis.call('HGET', KEYS[1], 'probe') + redis.call('DEL', KEYS[1]) + if stored == t[1] then + return {1} + end + return {0} """ .getBytes(StandardCharsets.UTF_8); @@ -79,7 +87,8 @@ final class RedisSemanticScriptAclProbe implements SmartInitializingSingleton { } catch (Exception failure) { throw new CapabilityStartupValidationException( "Redis semantic SCRIPT capability is selected but SCRIPT LOAD/EVALSHA is unavailable " - + "or the account is denied a command the scripts call (TIME); configure the " + + "or the account is denied a command the scripts call (TIME, HSET, PEXPIRE, HGET, " + + "DEL); configure the " + "ADVANCED Redis credential role or grant the effective account the required " + "script permissions", failure); diff --git a/src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/idempotency/RedisIdempotencyStoreAdapter.java b/src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/idempotency/RedisIdempotencyStoreAdapter.java index 0ada2911..52bb09ba 100644 --- a/src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/idempotency/RedisIdempotencyStoreAdapter.java +++ b/src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/idempotency/RedisIdempotencyStoreAdapter.java @@ -2,6 +2,7 @@ package dev.caskeleton.adapter.outbound.cache.redis.idempotency; import dev.caskeleton.adapter.outbound.cache.redis.RedisSemanticFailureLogger; import dev.caskeleton.adapter.outbound.cache.redis.keyspace.CapabilityKeyspace; +import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.error.RedisOperationException; import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisNamespace; import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisConnectionKind; import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisLease; @@ -45,7 +46,9 @@ import java.util.concurrent.TimeUnit; *

Every failure whose outcome is unknown is reported as {@code INDETERMINATE} rather than as a * failure. The difference is the whole point: a caller told "failed" retries and duplicates the * effect, while a caller told "indeterminate" inspects with the same attempt and discovers what - * actually happened. This adapter never converts an ambiguous write into a clean answer. + * actually happened. This adapter never converts an ambiguous write into a clean answer. The + * converse holds too: a refusal the runtime raised before sending anything (a saturated or closing + * script lane) is {@code UNAVAILABLE}, because nothing can have happened. * *

{@code application-core} sees {@link IdempotencyStorePort}. No Redis type, key, or script * digest crosses this boundary. @@ -126,6 +129,13 @@ public final class RedisIdempotencyStoreAdapter implements IdempotencyStorePort } catch (InterruptedException interrupted) { Thread.currentThread().interrupt(); return new IdempotencyClaimOutcome.Indeterminate(request.claimAttempt().operationId()); + } catch (RedisOperationException failure) { + RedisSemanticFailureLogger.report("idempotency", "claim", failure); + // A refusal before the script was sent — a saturated or closing lane — claimed nothing, so + // the caller may treat it as unavailable. Only a call that may have run is indeterminate. + return notSent(failure) + ? new IdempotencyClaimOutcome.Unavailable() + : new IdempotencyClaimOutcome.Indeterminate(request.claimAttempt().operationId()); } catch (Exception failure) { RedisSemanticFailureLogger.report("idempotency", "claim", failure); return new IdempotencyClaimOutcome.Indeterminate(request.claimAttempt().operationId()); @@ -176,6 +186,7 @@ public final class RedisIdempotencyStoreAdapter implements IdempotencyStorePort IdempotencyStartOutcome.NOT_CLAIMED, IdempotencyStartOutcome.OPERATION_CONFLICT, IdempotencyStartOutcome.INDETERMINATE, + IdempotencyStartOutcome.UNAVAILABLE, IdempotencyStartOutcome::carriesOwner); } @@ -198,6 +209,7 @@ public final class RedisIdempotencyStoreAdapter implements IdempotencyStorePort IdempotencyRenewOutcome.NOT_IN_PROGRESS, IdempotencyRenewOutcome.OPERATION_CONFLICT, IdempotencyRenewOutcome.INDETERMINATE, + IdempotencyRenewOutcome.UNAVAILABLE, IdempotencyRenewOutcome::carriesOwner); } @@ -243,6 +255,11 @@ public final class RedisIdempotencyStoreAdapter implements IdempotencyStorePort } catch (InterruptedException interrupted) { Thread.currentThread().interrupt(); return IdempotencyCompleteOutcome.INDETERMINATE; + } catch (RedisOperationException failure) { + RedisSemanticFailureLogger.report("idempotency", "complete", failure); + return notSent(failure) + ? IdempotencyCompleteOutcome.UNAVAILABLE + : IdempotencyCompleteOutcome.INDETERMINATE; } catch (Exception failure) { RedisSemanticFailureLogger.report("idempotency", "complete", failure); // The effect may have been recorded. A caller told INDETERMINATE inspects; one told @@ -299,6 +316,11 @@ public final class RedisIdempotencyStoreAdapter implements IdempotencyStorePort } catch (InterruptedException interrupted) { Thread.currentThread().interrupt(); return IdempotencyFailOutcome.INDETERMINATE; + } catch (RedisOperationException failure) { + RedisSemanticFailureLogger.report("idempotency", "mark-failed", failure); + return notSent(failure) + ? IdempotencyFailOutcome.UNAVAILABLE + : IdempotencyFailOutcome.INDETERMINATE; } catch (Exception failure) { RedisSemanticFailureLogger.report("idempotency", "mark-failed", failure); return IdempotencyFailOutcome.INDETERMINATE; @@ -331,6 +353,11 @@ public final class RedisIdempotencyStoreAdapter implements IdempotencyStorePort } catch (InterruptedException interrupted) { Thread.currentThread().interrupt(); return IdempotencyReleaseOutcome.INDETERMINATE; + } catch (RedisOperationException failure) { + RedisSemanticFailureLogger.report("idempotency", "release-before-execution", failure); + return notSent(failure) + ? IdempotencyReleaseOutcome.UNAVAILABLE + : IdempotencyReleaseOutcome.INDETERMINATE; } catch (Exception failure) { RedisSemanticFailureLogger.report("idempotency", "release-before-execution", failure); return IdempotencyReleaseOutcome.INDETERMINATE; @@ -432,6 +459,7 @@ public final class RedisIdempotencyStoreAdapter implements IdempotencyStorePort O wrongState, O operationConflict, O indeterminate, + O unavailable, java.util.function.Predicate carriesOwner) { try (RedisLease lease = owner.borrow(RedisConnectionKind.SCRIPT)) { IdempotencyScripts.Reply reply = @@ -474,12 +502,21 @@ public final class RedisIdempotencyStoreAdapter implements IdempotencyStorePort } catch (InterruptedException interrupted) { Thread.currentThread().interrupt(); return new IdempotencyMutationResult<>(indeterminate, null, carriesOwner); + } catch (RedisOperationException failure) { + RedisSemanticFailureLogger.report("idempotency", "transition", failure); + return new IdempotencyMutationResult<>( + notSent(failure) ? unavailable : indeterminate, null, carriesOwner); } catch (Exception failure) { RedisSemanticFailureLogger.report("idempotency", "transition", failure); return new IdempotencyMutationResult<>(indeterminate, null, carriesOwner); } } + /** A typed runtime refusal raised before any command existed — nothing reached Redis. */ + private static boolean notSent(RedisOperationException failure) { + return !failure.metadata().ambiguousExecution(); + } + private static IdempotencyOwner ownerOf( IdempotencyClaimRequest request, IdempotencyScripts.Reply reply) { return new IdempotencyOwner( diff --git a/src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/lease/RedisDistributedLeaseAdapter.java b/src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/lease/RedisDistributedLeaseAdapter.java index c67e9b77..2c472527 100644 --- a/src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/lease/RedisDistributedLeaseAdapter.java +++ b/src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/lease/RedisDistributedLeaseAdapter.java @@ -2,6 +2,7 @@ package dev.caskeleton.adapter.outbound.cache.redis.lease; import dev.caskeleton.adapter.outbound.cache.redis.RedisSemanticFailureLogger; import dev.caskeleton.adapter.outbound.cache.redis.keyspace.CapabilityKeyspace; +import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.error.RedisOperationException; import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisNamespace; import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisConnectionKind; import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisLease; @@ -16,6 +17,7 @@ import dev.caskeleton.application.lease.LeaseReleaseOutcome; import dev.caskeleton.application.lease.LeaseRenewOutcome; import dev.caskeleton.application.lease.LeaseRequest; import dev.caskeleton.application.lease.LeaseState; +import dev.caskeleton.application.lease.LeaseUnavailableCategory; import java.security.SecureRandom; import java.time.Clock; import java.time.Duration; @@ -140,6 +142,10 @@ public final class RedisDistributedLeaseAdapter implements DistributedLeasePort @Override public LeaseAcquireOutcome tryAcquire(LeaseRequest request) { Objects.requireNonNull(request, "request must be non-null"); + // Before the round trip: a TTL the drift budget swallows is the caller's argument error, and + // checking it after the script ran left the lease taken on the server while this caller was + // told Indeterminate. + Duration validity = localValidityOf(request.leaseTtl()); String ownership = ownershipOf(request.attempt()); long startedAt = nanoTime.getAsLong(); try (RedisLease lease = owner.borrow(RedisConnectionKind.SCRIPT)) { @@ -153,17 +159,25 @@ public final class RedisDistributedLeaseAdapter implements DistributedLeasePort .toCompletableFuture() .get(commandTimeout.toNanos(), TimeUnit.NANOSECONDS); return switch ((int) reply.status()) { - case 1 -> new LeaseAcquireOutcome.Acquired(handle(request, ownership, startedAt)); + case 1 -> new LeaseAcquireOutcome.Acquired(handle(request, ownership, validity, startedAt)); case 2 -> // The same owner and operation already hold it. This is a retry whose first reply was // lost, not a second acquisition, and answering "contended" would make a caller back - // off from a lease it already owns. - new LeaseAcquireOutcome.ReplayedSameOperation(handle(request, ownership, startedAt)); + // off from a lease it already owns. The server did not re-grant the TTL, so the + // handle gets what is left of it, not a fresh one. + new LeaseAcquireOutcome.ReplayedSameOperation( + handle(request, ownership, observedValidityOf(reply.remainingMillis()), startedAt)); default -> contendedOrConflicting(request, reply); }; } catch (InterruptedException interrupted) { Thread.currentThread().interrupt(); return new LeaseAcquireOutcome.Indeterminate(request.attempt().operationId()); + } catch (RedisOperationException failure) { + RedisSemanticFailureLogger.report("lease", "acquire", failure); + // Refused before anything was sent: nothing can have been taken. + return notSent(failure) + ? new LeaseAcquireOutcome.Unavailable(LeaseUnavailableCategory.UNAVAILABLE_BEFORE_SEND) + : new LeaseAcquireOutcome.Indeterminate(request.attempt().operationId()); } catch (Exception failure) { RedisSemanticFailureLogger.report("lease", "acquire", failure); // An acquire whose outcome is unknown may have taken the lease. Reporting it as a clean @@ -222,19 +236,25 @@ public final class RedisDistributedLeaseAdapter implements DistributedLeasePort } catch (InterruptedException interrupted) { Thread.currentThread().interrupt(); return new LeaseInspectionOutcome.Indeterminate(request.attempt().operationId()); + } catch (RedisOperationException failure) { + RedisSemanticFailureLogger.report("lease", "inspect", failure); + return notSent(failure) + ? new LeaseInspectionOutcome.Unavailable(LeaseUnavailableCategory.UNAVAILABLE_BEFORE_SEND) + : new LeaseInspectionOutcome.Indeterminate(request.attempt().operationId()); } catch (Exception failure) { RedisSemanticFailureLogger.report("lease", "inspect", failure); return new LeaseInspectionOutcome.Indeterminate(request.attempt().operationId()); } } - private RedisLeaseHandle handle(LeaseRequest request, String ownership, long startedAt) { + private RedisLeaseHandle handle( + LeaseRequest request, String ownership, Duration validity, long startedAt) { return new RedisLeaseHandle( request.purpose(), request.resourceDigest(), request.attempt(), ownership, - localValidityOf(request.leaseTtl()), + validity, startedAt); } @@ -242,6 +262,11 @@ public final class RedisDistributedLeaseAdapter implements DistributedLeasePort return attempt.ownerToken() + ":" + attempt.operationId(); } + /** A typed runtime refusal raised before any command existed — nothing reached Redis. */ + private static boolean notSent(RedisOperationException failure) { + return !failure.metadata().ambiguousExecution(); + } + /** A held lease, whose validity is its own to track. */ private final class RedisLeaseHandle implements LeaseHandle { @@ -312,6 +337,8 @@ public final class RedisDistributedLeaseAdapter implements DistributedLeasePort @Override public LeaseRenewOutcome renew(Duration leaseTtl) { Objects.requireNonNull(leaseTtl, "leaseTtl must be non-null"); + // Before the round trip, for the reason tryAcquire gives. + Duration validity = localValidityOf(leaseTtl); long startedAt = nanoTime.getAsLong(); try (RedisLease lease = owner.borrow(RedisConnectionKind.SCRIPT)) { LeaseScripts.Reply reply = @@ -326,7 +353,7 @@ public final class RedisDistributedLeaseAdapter implements DistributedLeasePort if (reply.status() == 1) { // The renewed budget is shortened by the drift allowance for the same reason the first // one was: a renew does not make the two clocks agree. - grantedValidity = localValidityOf(leaseTtl); + grantedValidity = validity; grantedAtNanos = startedAt; return new LeaseRenewOutcome.Renewed(remainingValidity()); } @@ -338,6 +365,16 @@ public final class RedisDistributedLeaseAdapter implements DistributedLeasePort Thread.currentThread().interrupt(); state = LeaseState.UNKNOWN; return new LeaseRenewOutcome.Indeterminate(attempt.operationId()); + } catch (RedisOperationException failure) { + RedisSemanticFailureLogger.report("lease", "renew", failure); + if (notSent(failure)) { + // Nothing reached the server, so the lease is exactly what it was: still held, on the + // budget it already had. + return new LeaseRenewOutcome.Unavailable( + LeaseUnavailableCategory.UNAVAILABLE_BEFORE_SEND); + } + state = LeaseState.UNKNOWN; + return new LeaseRenewOutcome.Indeterminate(attempt.operationId()); } catch (Exception failure) { RedisSemanticFailureLogger.report("lease", "renew", failure); // A renew whose outcome is unknown must not extend the local budget. Leaving the handle in @@ -369,6 +406,14 @@ public final class RedisDistributedLeaseAdapter implements DistributedLeasePort Thread.currentThread().interrupt(); state = LeaseState.UNKNOWN; return new LeaseReleaseOutcome.Indeterminate(attempt.operationId()); + } catch (RedisOperationException failure) { + RedisSemanticFailureLogger.report("lease", "release", failure); + if (notSent(failure)) { + return new LeaseReleaseOutcome.Unavailable( + LeaseUnavailableCategory.UNAVAILABLE_BEFORE_SEND); + } + state = LeaseState.UNKNOWN; + return new LeaseReleaseOutcome.Indeterminate(attempt.operationId()); } catch (Exception failure) { RedisSemanticFailureLogger.report("lease", "release", failure); state = LeaseState.UNKNOWN; diff --git a/src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/ratelimit/RateLimitScripts.java b/src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/ratelimit/RateLimitScripts.java index 6b15f669..8f2901f4 100644 --- a/src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/ratelimit/RateLimitScripts.java +++ b/src/adapter/outbound/cache-redis/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/ratelimit/RateLimitScripts.java @@ -34,10 +34,13 @@ import java.util.concurrent.atomic.AtomicReference; public final class RateLimitScripts { /** - * Fixed window: one counter per window, expiring with it. + * Fixed window: one counter, overwritten when the window turns. * - *

Returns {@code {allowed, remaining, resetAfterMillis}}. The expiry is set from the window - * rather than refreshed per hit, so a subject cannot hold a counter alive indefinitely. + *

Returns {@code {allowed, remaining, resetAfterMillis}}. The state is two fields, {@code + * start} and {@code count}, whatever the traffic: the counter of a window that has ended is + * replaced, not kept. The expiry is refreshed on every allowed hit, which is safe only because + * the state cannot grow — a field per window would have grown for as long as a subject kept the + * key alive. */ private static final String FIXED_WINDOW = """ @@ -49,13 +52,15 @@ public final class RateLimitScripts { local nowMillis = (tonumber(t[1]) * 1000) + math.floor(tonumber(t[2]) / 1000) local windowStart = nowMillis - (nowMillis % windowMillis) local resetAfter = (windowStart + windowMillis) - nowMillis - local bucket = tostring(windowStart) - local current = tonumber(redis.call('HGET', KEYS[1], bucket)) or 0 + local state = redis.call('HMGET', KEYS[1], 'start', 'count') + local current = 0 + if tonumber(state[1]) == windowStart then + current = tonumber(state[2]) or 0 + end if current + cost > limit then return {0, limit - current, resetAfter} end - redis.call('HSET', KEYS[1], bucket, current + cost) - redis.call('HDEL', KEYS[1], tostring(windowStart - (windowMillis * 2))) + redis.call('HSET', KEYS[1], 'start', windowStart, 'count', current + cost) redis.call('PEXPIRE', KEYS[1], stateTtlMillis) return {1, limit - (current + cost), resetAfter} """; @@ -66,6 +71,10 @@ public final class RateLimitScripts { *

Approximate by construction, and the port says so. An exact sliding window needs one sorted * set entry per request, which costs memory proportional to the traffic it is limiting — the * failure mode of an exact limiter is that it becomes the outage. + * + *

The state is three fields, {@code start}, {@code cur} and {@code prev}. When the window + * turns, {@code cur} becomes {@code prev} if the stored window is the one just before, and both + * reset if it is older — so the state never grows with the number of windows a subject touches. */ private static final String SLIDING_COUNTER = """ @@ -78,15 +87,22 @@ public final class RateLimitScripts { local windowStart = nowMillis - (nowMillis % windowMillis) local elapsed = nowMillis - windowStart local resetAfter = windowMillis - elapsed - local current = tonumber(redis.call('HGET', KEYS[1], tostring(windowStart))) or 0 - local previous = tonumber(redis.call('HGET', KEYS[1], tostring(windowStart - windowMillis))) or 0 + local state = redis.call('HMGET', KEYS[1], 'start', 'cur', 'prev') + local storedStart = tonumber(state[1]) + local current = 0 + local previous = 0 + if storedStart == windowStart then + current = tonumber(state[2]) or 0 + previous = tonumber(state[3]) or 0 + elseif storedStart == windowStart - windowMillis then + previous = tonumber(state[2]) or 0 + end local weight = (windowMillis - elapsed) / windowMillis local estimated = current + math.floor(previous * weight) if estimated + cost > limit then return {0, math.max(0, limit - estimated), resetAfter} end - redis.call('HSET', KEYS[1], tostring(windowStart), current + cost) - redis.call('HDEL', KEYS[1], tostring(windowStart - (windowMillis * 2))) + redis.call('HSET', KEYS[1], 'start', windowStart, 'cur', current + cost, 'prev', previous) redis.call('PEXPIRE', KEYS[1], stateTtlMillis) return {1, math.max(0, limit - (estimated + cost)), resetAfter} """; diff --git a/src/adapter/outbound/cache-redis/src/main/resources/config/module-defaults/cache-redis.yml b/src/adapter/outbound/cache-redis/src/main/resources/config/module-defaults/cache-redis.yml index bc9b1593..a06686e7 100644 --- a/src/adapter/outbound/cache-redis/src/main/resources/config/module-defaults/cache-redis.yml +++ b/src/adapter/outbound/cache-redis/src/main/resources/config/module-defaults/cache-redis.yml @@ -60,7 +60,8 @@ ca-skeleton: # disabled | redis. This is the sole outbound provider activation selector. provider: ${APP_RATE_LIMIT_PROVIDER:disabled} failure-policy: ${APP_RATE_LIMIT_FAILURE_POLICY:fail-closed} - default-policy-id: ${APP_RATE_LIMIT_DEFAULT_POLICY_ID:api-default} + # The default policy id is app.rate-limit.default-policy-id above, read by both the HTTP + # boundary and this limiter's startup check. It has no second key here. failure-retry-after: ${APP_RATE_LIMIT_FAILURE_RETRY_AFTER:100ms} key-version: ${APP_RATE_LIMIT_KEY_VERSION:1} command-timeout: ${APP_RATE_LIMIT_REDIS_COMMAND_TIMEOUT:200ms} @@ -75,3 +76,11 @@ ca-skeleton: refill-period: ${APP_RATE_LIMIT_REFILL_PERIOD:1s} maximum-cost: ${APP_RATE_LIMIT_MAXIMUM_COST:10} cleanup-grace: ${APP_RATE_LIMIT_CLEANUP_GRACE:5s} + +# /actuator/info 에 싣는 이 모듈의 상태(management.info.env). compose smoke 가 lane 이 실제로 켠 +# capability 를 이 값으로 확인한다. 위 스위치를 해석한 값이고, 기본값은 RedisCapabilityConfig 의 +# 조건과 같다(matchIfMissing 없음 = false). +info: + capabilities: + redis: + enabled: ${app.redis.enabled:false} diff --git a/src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/LiveRedisSemanticPortsTest.java b/src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/LiveRedisSemanticPortsTest.java index 77f4b082..bf12d04e 100644 --- a/src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/LiveRedisSemanticPortsTest.java +++ b/src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/LiveRedisSemanticPortsTest.java @@ -13,6 +13,8 @@ import dev.caskeleton.adapter.outbound.cache.redis.ratelimit.RedisEdgeRateLimitA import dev.caskeleton.adapter.outbound.cache.redis.sdk.RedisTopologyEndpoint; import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.RedisDeploymentMode; import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisNamespace; +import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisConnectionKind; +import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisLease; import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner; import dev.caskeleton.application.cache.CacheLookup; import dev.caskeleton.application.cache.CacheRecordIntent; @@ -39,10 +41,13 @@ import java.time.Clock; import java.time.Duration; import java.util.Map; import java.util.UUID; +import java.util.concurrent.TimeUnit; import org.junit.jupiter.api.AfterEach; import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Tag; import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.EnumSource; /** * The semantic ports, against a real server, under the real ACL accounts. @@ -182,7 +187,10 @@ class LiveRedisSemanticPortsTest { new RateLimitKeys(NAMESPACE, 1), Map.of(policy.policyId(), policy), new RateLimitScripts(), - Clock.offset(Clock.systemUTC(), Duration.ofHours(1)), + // The system clock: request() builds the deadline from it. An adapter clock an hour + // ahead saw every deadline as spent and refused before reaching Redis. Skewed-clock + // coverage is idempotencyLeaseExpiryUsesRedisTimeAcrossSkewedCallers. + Clock.systemUTC(), Duration.ofSeconds(2), Duration.ofMillis(100)); @@ -195,6 +203,61 @@ class LiveRedisSemanticPortsTest { assertThat(((RateLimitOutcome.Evaluated) outcome).decision().allowed()).isTrue(); } + @ParameterizedTest + @EnumSource( + value = RateLimitAlgorithm.class, + names = {"FIXED_WINDOW", "SLIDING_COUNTER"}) + @DisplayName("창을 건너뛰며 요청해도 subject 하나의 카운터 hash 필드 수가 늘지 않는다") + void windowCounterStateDoesNotGrowAcrossSkippedWindows(RateLimitAlgorithm algorithm) + throws Exception { + // given + Duration window = Duration.ofMillis(100); + RateLimitPolicy policy = + new RateLimitPolicy( + "api-default", + "v1", + algorithm, + algorithm == RateLimitAlgorithm.FIXED_WINDOW + ? new RateParameters.FixedWindow(100, window) + : new RateParameters.SlidingCounter(100, window), + 1, + // A grace far longer than the gaps below, so the key outlives every gap and only the + // script's own bookkeeping can keep its field count down. + Duration.ofSeconds(5), + Duration.ofMillis(250), + RateLimitFailurePolicy.FAIL_CLOSED); + RedisRuntimeOwner runtime = runtime(true); + RedisEdgeRateLimitAdapter limiter = + new RedisEdgeRateLimitAdapter( + runtime, + new RateLimitKeys(NAMESPACE, 1), + Map.of(policy.policyId(), policy), + new RateLimitScripts(), + Clock.systemUTC(), + Duration.ofSeconds(2), + Duration.ofMillis(100)); + String subject = "hv1:" + UUID.randomUUID().toString().replace("-", ""); + byte[] key = new RateLimitKeys(NAMESPACE, 1).counterKey(policy, subject); + limiter.evaluate(request(subject)); + long fieldsAfterFirstHit = fieldCount(runtime, key); + + // when + for (int hit = 0; hit < 3; hit++) { + // More than three windows apart: the old script deleted only the field two windows back. + Thread.sleep(350); + limiter.evaluate(request(subject)); + } + + // then + assertThat(fieldCount(runtime, key)).isEqualTo(fieldsAfterFirstHit); + } + + private static long fieldCount(RedisRuntimeOwner runtime, byte[] key) throws Exception { + try (RedisLease lease = runtime.borrow(RedisConnectionKind.REGULAR)) { + return lease.gateway().hashSize(key).toCompletableFuture().get(2, TimeUnit.SECONDS); + } + } + private RateLimitRequest request(String subject) { return new RateLimitRequest( "api-default", diff --git a/src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/RedisSemanticFailureLoggerTest.java b/src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/RedisSemanticFailureLoggerTest.java new file mode 100644 index 00000000..b3836ed7 --- /dev/null +++ b/src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/RedisSemanticFailureLoggerTest.java @@ -0,0 +1,73 @@ +package dev.caskeleton.adapter.outbound.cache.redis; + +import static org.assertj.core.api.Assertions.assertThat; + +import ch.qos.logback.classic.Level; +import ch.qos.logback.classic.Logger; +import ch.qos.logback.classic.spi.ILoggingEvent; +import ch.qos.logback.core.read.ListAppender; +import java.time.Duration; +import java.util.List; +import java.util.UUID; +import java.util.concurrent.ExecutionException; +import org.junit.jupiter.api.AfterEach; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.slf4j.LoggerFactory; + +class RedisSemanticFailureLoggerTest { + + private final Logger logger = (Logger) LoggerFactory.getLogger(RedisSemanticFailureLogger.class); + + private final ListAppender appender = new ListAppender<>(); + + // The warned-once state is JVM-wide, so each test reports under a capability nobody else uses. + private final String capability = "test-" + UUID.randomUUID(); + + @BeforeEach + void attach() { + appender.start(); + logger.addAppender(appender); + } + + @AfterEach + void detach() { + logger.detachAppender(appender); + } + + private List warnings() { + return appender.list.stream().filter(event -> event.getLevel() == Level.WARN).toList(); + } + + @Test + @DisplayName("같은 장애가 1분 창을 넘겨 계속되면 다시 WARN한다") + void aContinuingFailureWarnsAgainOnceTheWindowHasPassed() { + // given + long start = 0L; + RedisSemanticFailureLogger.report(capability, "claim", new IllegalStateException(), start); + RedisSemanticFailureLogger.report( + capability, "claim", new IllegalStateException(), Duration.ofSeconds(30).toNanos()); + + // when + RedisSemanticFailureLogger.report( + capability, "claim", new IllegalStateException(), Duration.ofSeconds(61).toNanos()); + + // then + assertThat(warnings()).hasSize(2); + } + + @Test + @DisplayName("ExecutionException으로 감싼 장애는 원인 타입으로 기록한다") + void aWrappedFailureIsReportedByItsCause() { + // when + RedisSemanticFailureLogger.report( + capability, "claim", new ExecutionException(new IllegalStateException()), 0L); + + // then + assertThat(warnings()) + .singleElement() + .extracting(event -> event.getArgumentArray()[2]) + .isEqualTo("IllegalStateException"); + } +} diff --git a/src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/cache/RedisCacheRegionAdapterTest.java b/src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/cache/RedisCacheRegionAdapterTest.java index 1dcc18cd..46337e42 100644 --- a/src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/cache/RedisCacheRegionAdapterTest.java +++ b/src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/cache/RedisCacheRegionAdapterTest.java @@ -15,6 +15,7 @@ import dev.caskeleton.application.cache.CacheLookup; import dev.caskeleton.application.cache.CacheRecordIntent; import dev.caskeleton.application.cache.CacheRecordMetadata; import dev.caskeleton.application.cache.CacheRecordOutcome; +import java.lang.reflect.Proxy; import java.nio.charset.StandardCharsets; import java.time.Clock; import java.time.Duration; @@ -22,6 +23,7 @@ import java.time.Instant; import java.time.ZoneOffset; import java.util.EnumMap; import java.util.Map; +import java.util.concurrent.CompletableFuture; import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; @@ -323,6 +325,74 @@ class RedisCacheRegionAdapterTest { .isEqualTo(CacheInvalidationOutcome.DEGRADED_UNAVAILABLE); } + @Test + @DisplayName("보낸 뒤 응답을 잃은 SET은 적용됐을 수 있으므로 INDETERMINATE다") + void aWriteWhoseReplyWasLostIsIndeterminate() { + // given + RedisCacheRegionAdapter cache = cache(T0, new StubClient(losingReplyOf("set"))); + + // when + CacheRecordOutcome outcome = cache.record("order-1", "payload", upsert()); + + // then + assertThat(outcome).isEqualTo(CacheRecordOutcome.INDETERMINATE); + } + + @Test + @DisplayName("SET을 보내기 전 generation 조회가 실패하면 기록은 DEGRADED_UNAVAILABLE이다") + void aWriteThatFailedBeforeItsSetWasSentDegrades() { + // given + RedisCacheRegionAdapter cache = + cache(T0, new StubClient(losingReplyOf("incrementBy"))); + + // when + CacheRecordOutcome outcome = cache.record("order-1", "payload", upsert()); + + // then + assertThat(outcome).isEqualTo(CacheRecordOutcome.DEGRADED_UNAVAILABLE); + } + + @Test + @DisplayName("보낸 뒤 응답을 잃은 invalidate는 지워졌을 수 있으므로 INDETERMINATE다") + void anInvalidationWhoseReplyWasLostIsIndeterminate() { + // given + RedisCacheRegionAdapter cache = + cache(T0, new StubClient(losingReplyOf("getAndDelete"))); + + // when + CacheInvalidationOutcome outcome = cache.invalidate("order-1"); + + // then + assertThat(outcome).isEqualTo(CacheInvalidationOutcome.INDETERMINATE); + } + + @Test + @DisplayName("보낸 뒤 응답을 잃은 region invalidate는 generation이 올라갔을 수 있으므로 INDETERMINATE다") + void aRegionInvalidationWhoseReplyWasLostIsIndeterminate() { + // given + RedisCacheRegionAdapter cache = + cache(T0, new StubClient(losingReplyOf("incrementBy"))); + + // when + CacheInvalidationOutcome outcome = cache.invalidateRegion(); + + // then + assertThat(outcome).isEqualTo(CacheInvalidationOutcome.INDETERMINATE); + } + + /** The in-memory gateway, except that one command's reply is lost after it was sent. */ + private RedisCommandGateway losingReplyOf(String command) { + RedisCommandGateway real = gateway.gateway(); + return (RedisCommandGateway) + Proxy.newProxyInstance( + RedisCommandGateway.class.getClassLoader(), + new Class[] {RedisCommandGateway.class}, + (proxy, method, arguments) -> + method.getName().equals(command) + ? CompletableFuture.failedFuture(new RuntimeException("reply lost")) + : method.invoke(real, arguments)); + } + @Test @DisplayName("a negative entry expires sooner than a value entry") void negativeEntriesExpireSooner() { diff --git a/src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/capability/RedisCapabilityCompositionTest.java b/src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/capability/RedisCapabilityCompositionTest.java index 7b62afc1..47244614 100644 --- a/src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/capability/RedisCapabilityCompositionTest.java +++ b/src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/capability/RedisCapabilityCompositionTest.java @@ -115,6 +115,24 @@ class RedisCapabilityCompositionTest { }); } + @Test + @DisplayName("HTTP 경계가 요청할 기본 정책(app.rate-limit.default-policy-id)이 Redis 정책에 없으면 기동이 실패한다") + void aDefaultPolicyTheLimiterDoesNotHaveIsRefusedAtStartup() { + // given + ApplicationContextRunner limiter = + runner.withPropertyValues( + "ca-skeleton.capabilities.rate-limit.provider=redis", + "app.rate-limit.default-policy-id=missing-policy"); + + // when & then + limiter.run( + context -> + assertThat(context.getStartupFailure()) + .hasStackTraceContaining( + "the default rate-limit policy 'missing-policy' is not among the configured" + + " policies")); + } + @Test @DisplayName("every selected role composes at once, under one namespace") void allRolesComposeTogether() { diff --git a/src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/capability/RedisSemanticScriptAclProbeTest.java b/src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/capability/RedisSemanticScriptAclProbeTest.java index dc365794..aaf5826d 100644 --- a/src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/capability/RedisSemanticScriptAclProbeTest.java +++ b/src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/capability/RedisSemanticScriptAclProbeTest.java @@ -82,7 +82,7 @@ class RedisSemanticScriptAclProbeTest { } @ParameterizedTest - @ValueSource(strings = {"TIME"}) + @ValueSource(strings = {"TIME", "HSET", "PEXPIRE", "HGET", "DEL"}) @DisplayName("스크립트가 부르는 명령 하나라도 계정에 없으면 첫 요청이 아니라 기동에서 실패한다") void anAccountDeniedACommandTheScriptsCallFailsStartup(String command) { // given diff --git a/src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/idempotency/RedisIdempotencyStoreAdapterTest.java b/src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/idempotency/RedisIdempotencyStoreAdapterTest.java index a43df3be..1dcf75b4 100644 --- a/src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/idempotency/RedisIdempotencyStoreAdapterTest.java +++ b/src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/idempotency/RedisIdempotencyStoreAdapterTest.java @@ -19,6 +19,7 @@ import dev.caskeleton.application.idempotency.IdempotencyInspectionOutcome; import dev.caskeleton.application.idempotency.IdempotencyInspectionRequest; import dev.caskeleton.application.idempotency.IdempotencyOwner; import dev.caskeleton.application.idempotency.IdempotencyReleaseOutcome; +import dev.caskeleton.application.idempotency.IdempotencyRenewOutcome; import dev.caskeleton.application.idempotency.IdempotencyScopeDigest; import dev.caskeleton.application.idempotency.IdempotencyStartOutcome; import dev.caskeleton.application.idempotency.RequestFingerprint; @@ -30,8 +31,13 @@ import java.time.Instant; import java.time.ZoneOffset; import java.util.EnumMap; import java.util.Map; +import java.util.stream.Stream; import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Named; import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.Arguments; +import org.junit.jupiter.params.provider.MethodSource; /** * The state machine that keeps a retried request from happening twice. @@ -61,12 +67,28 @@ class RedisIdempotencyStoreAdapterTest { private final RedisIdempotencyStoreAdapter store = store(T0, new StubClient(gateway.gateway())); private RedisIdempotencyStoreAdapter store(Instant now, RedisRuntimeClient client) { + return store(now, owner(client, 4, Duration.ofSeconds(1))); + } + + private static RedisRuntimeOwner owner( + RedisRuntimeClient client, int connectionsPerLane, Duration acquireTimeout) { Map limits = new EnumMap<>(RedisConnectionKind.class); for (RedisConnectionKind kind : RedisConnectionKind.values()) { - limits.put(kind, 4); + limits.put(kind, connectionsPerLane); } + return new RedisRuntimeOwner(client, limits, acquireTimeout, Duration.ofSeconds(1)); + } + + /** + * An owner with one script connection and almost no patience, so holding it saturates the lane. + */ + private RedisRuntimeOwner narrowOwner() { + return owner(new StubClient(gateway.gateway()), 1, Duration.ofMillis(10)); + } + + private RedisIdempotencyStoreAdapter store(Instant now, RedisRuntimeOwner owner) { return new RedisIdempotencyStoreAdapter( - new RedisRuntimeOwner(client, limits, Duration.ofSeconds(1), Duration.ofSeconds(1)), + owner, new RedisIdempotencyStoreAdapter.IdempotencyKeys( new RedisNamespace("prod", "ca-skeleton", "shared"), 1), new IdempotencyScripts(), @@ -282,6 +304,89 @@ class RedisIdempotencyStoreAdapterTest { assertThat(outcome).isInstanceOf(IdempotencyClaimOutcome.Indeterminate.class); } + @Test + @DisplayName("스크립트 lane이 포화돼 보내지도 못한 claim은 Indeterminate가 아니라 Unavailable이다") + void aSaturatedScriptLaneRefusesTheClaimAsUnavailable() { + // given + RedisRuntimeOwner narrow = narrowOwner(); + RedisIdempotencyStoreAdapter saturated = store(T0, narrow); + narrow.borrow(RedisConnectionKind.SCRIPT); + + // when + IdempotencyClaimOutcome outcome = saturated.claim(claim(saturated.newClaimAttempt(OPERATION))); + + // then + assertThat(outcome).isInstanceOf(IdempotencyClaimOutcome.Unavailable.class); + } + + static Stream ownerTransitions() { + return Stream.of( + Arguments.of( + Named.of( + "markExecutionStarted", + (OwnerCall) + (target, owner) -> target.markExecutionStarted(owner, OPERATION).outcome()), + IdempotencyStartOutcome.UNAVAILABLE), + Arguments.of( + Named.of( + "renew", + (OwnerCall) + (target, owner) -> + target.renew(owner, Duration.ofSeconds(30), OPERATION).outcome()), + IdempotencyRenewOutcome.UNAVAILABLE), + Arguments.of( + Named.of( + "complete", + (OwnerCall) + (target, owner) -> + target.complete( + owner, new StoredResponse("{}"), Duration.ofHours(1), OPERATION)), + IdempotencyCompleteOutcome.UNAVAILABLE), + Arguments.of( + Named.of( + "markFailed", + (OwnerCall) + (target, owner) -> + target.markFailed( + owner, + IdempotencyFailureDisposition.NO_EFFECT_RETRYABLE, + Duration.ofHours(1), + OPERATION)), + IdempotencyFailOutcome.UNAVAILABLE), + Arguments.of( + Named.of( + "releaseBeforeExecution", + (OwnerCall) (target, owner) -> target.releaseBeforeExecution(owner, OPERATION)), + IdempotencyReleaseOutcome.UNAVAILABLE)); + } + + @ParameterizedTest(name = "{0}") + @MethodSource("ownerTransitions") + @DisplayName("스크립트 lane이 포화돼 보내지도 못한 owner 전이는 INDETERMINATE가 아니라 UNAVAILABLE이다") + void aSaturatedScriptLaneRefusesOwnerTransitionsAsUnavailable( + OwnerCall call, Object unavailable) { + // given + RedisRuntimeOwner narrow = narrowOwner(); + RedisIdempotencyStoreAdapter saturated = store(T0, narrow); + IdempotencyOwner owner = + ((IdempotencyClaimOutcome.Acquired) + saturated.claim(claim(saturated.newClaimAttempt(OPERATION)))) + .owner(); + narrow.borrow(RedisConnectionKind.SCRIPT); + + // when + Object outcome = call.apply(saturated, owner); + + // then + assertThat(outcome).isEqualTo(unavailable); + } + + /** One owner-checked transition, reduced to its outcome. */ + @FunctionalInterface + interface OwnerCall { + Object apply(RedisIdempotencyStoreAdapter store, IdempotencyOwner owner); + } + private IdempotencyOwner executing() { IdempotencyClaimAttempt attempt = store.newClaimAttempt(OPERATION); IdempotencyOwner owner = diff --git a/src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/lease/RedisDistributedLeaseAdapterTest.java b/src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/lease/RedisDistributedLeaseAdapterTest.java index 8dfafee7..48c7786e 100644 --- a/src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/lease/RedisDistributedLeaseAdapterTest.java +++ b/src/adapter/outbound/cache-redis/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/lease/RedisDistributedLeaseAdapterTest.java @@ -1,6 +1,7 @@ package dev.caskeleton.adapter.outbound.cache.redis.lease; import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.catchThrowable; import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.RedisDeploymentMode; import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisNamespace; @@ -18,11 +19,13 @@ import dev.caskeleton.application.lease.LeaseReleaseOutcome; import dev.caskeleton.application.lease.LeaseRenewOutcome; import dev.caskeleton.application.lease.LeaseRequest; import dev.caskeleton.application.lease.LeaseState; +import dev.caskeleton.application.lease.LeaseUnavailableCategory; import java.time.Clock; import java.time.Duration; import java.time.Instant; import java.time.ZoneOffset; import java.util.EnumMap; +import java.util.List; import java.util.Map; import java.util.concurrent.atomic.AtomicLong; import org.junit.jupiter.api.DisplayName; @@ -64,12 +67,28 @@ class RedisDistributedLeaseAdapterTest { } private RedisDistributedLeaseAdapter adapter(RedisRuntimeClient client, Duration driftBudget) { + return adapter(owner(client, 4, Duration.ofSeconds(1)), driftBudget); + } + + private static RedisRuntimeOwner owner( + RedisRuntimeClient client, int connectionsPerLane, Duration acquireTimeout) { Map limits = new EnumMap<>(RedisConnectionKind.class); for (RedisConnectionKind kind : RedisConnectionKind.values()) { - limits.put(kind, 4); + limits.put(kind, connectionsPerLane); } + return new RedisRuntimeOwner(client, limits, acquireTimeout, Duration.ofSeconds(1)); + } + + /** + * An owner with one script connection and almost no patience, so holding it saturates the lane. + */ + private RedisRuntimeOwner narrowOwner() { + return owner(new StubClient(gateway.gateway()), 1, Duration.ofMillis(10)); + } + + private RedisDistributedLeaseAdapter adapter(RedisRuntimeOwner owner, Duration driftBudget) { return new RedisDistributedLeaseAdapter( - new RedisRuntimeOwner(client, limits, Duration.ofSeconds(1), Duration.ofSeconds(1)), + owner, new RedisDistributedLeaseAdapter.LeaseKeys( new RedisNamespace("prod", "ca-skeleton", "shared"), 1), new LeaseScripts(), @@ -252,6 +271,160 @@ class RedisDistributedLeaseAdapterTest { assertThat(((LeaseAcquireOutcome.Indeterminate) outcome).operationId()).isEqualTo(OPERATION_A); } + @Test + @DisplayName("스크립트 lane이 포화돼 보내지도 못한 acquire는 Indeterminate가 아니라 보내기 전 Unavailable이다") + void aSaturatedScriptLaneRefusesAcquireBeforeSend() { + // given + RedisRuntimeOwner narrow = narrowOwner(); + RedisDistributedLeaseAdapter saturated = adapter(narrow, Duration.ZERO); + narrow.borrow(RedisConnectionKind.SCRIPT); + + // when + LeaseAcquireOutcome outcome = + saturated.tryAcquire(request(saturated.newAttempt(OPERATION_A), Duration.ofSeconds(30))); + + // then + assertThat(outcome) + .isEqualTo( + new LeaseAcquireOutcome.Unavailable(LeaseUnavailableCategory.UNAVAILABLE_BEFORE_SEND)); + } + + @Test + @DisplayName("스크립트 lane이 포화돼 보내지도 못한 inspect는 보내기 전 Unavailable이다") + void aSaturatedScriptLaneRefusesInspectBeforeSend() { + // given + RedisRuntimeOwner narrow = narrowOwner(); + RedisDistributedLeaseAdapter saturated = adapter(narrow, Duration.ZERO); + narrow.borrow(RedisConnectionKind.SCRIPT); + + // when + LeaseInspectionOutcome outcome = + saturated.inspect( + new LeaseInspectionRequest(PURPOSE, RESOURCE, saturated.newAttempt(OPERATION_A))); + + // then + assertThat(outcome) + .isEqualTo( + new LeaseInspectionOutcome.Unavailable( + LeaseUnavailableCategory.UNAVAILABLE_BEFORE_SEND)); + } + + @Test + @DisplayName("보내지도 못한 renew는 Unavailable이고 handle은 ACTIVE로 남는다") + void aRenewRefusedBeforeSendLeavesTheHandleActive() { + // given + RedisRuntimeOwner narrow = narrowOwner(); + RedisDistributedLeaseAdapter leases = adapter(narrow, Duration.ZERO); + LeaseHandle handle = + ((LeaseAcquireOutcome.Acquired) + leases.tryAcquire(request(leases.newAttempt(OPERATION_A), Duration.ofSeconds(30)))) + .handle(); + narrow.borrow(RedisConnectionKind.SCRIPT); + + // when + LeaseRenewOutcome outcome = handle.renew(Duration.ofSeconds(30)); + + // then + assertThat(List.of(outcome, handle.state())) + .containsExactly( + new LeaseRenewOutcome.Unavailable(LeaseUnavailableCategory.UNAVAILABLE_BEFORE_SEND), + LeaseState.ACTIVE); + } + + @Test + @DisplayName("보내지도 못한 release는 Unavailable이고 handle은 ACTIVE로 남는다") + void aReleaseRefusedBeforeSendLeavesTheHandleActive() { + // given + RedisRuntimeOwner narrow = narrowOwner(); + RedisDistributedLeaseAdapter leases = adapter(narrow, Duration.ZERO); + LeaseHandle handle = + ((LeaseAcquireOutcome.Acquired) + leases.tryAcquire(request(leases.newAttempt(OPERATION_A), Duration.ofSeconds(30)))) + .handle(); + narrow.borrow(RedisConnectionKind.SCRIPT); + + // when + LeaseReleaseOutcome outcome = handle.release(); + + // then + assertThat(List.of(outcome, handle.state())) + .containsExactly( + new LeaseReleaseOutcome.Unavailable(LeaseUnavailableCategory.UNAVAILABLE_BEFORE_SEND), + LeaseState.ACTIVE); + } + + @Test + @DisplayName("replay로 돌려받은 handle의 유효 시간은 서버에 남은 TTL을 넘지 않는다") + void aReplayedAcquireKeepsOnlyTheServersRemainingTtl() { + // given + LeaseAttempt attempt = adapter.newAttempt(OPERATION_A); + adapter.tryAcquire(request(attempt, Duration.ofSeconds(30))); + gateway.advance(Duration.ofSeconds(20)); + + // when + LeaseAcquireOutcome replay = adapter.tryAcquire(request(attempt, Duration.ofSeconds(30))); + + // then + assertThat(((LeaseAcquireOutcome.ReplayedSameOperation) replay).handle().remainingValidity()) + .isLessThanOrEqualTo(Duration.ofSeconds(10)); + } + + @Test + @DisplayName("drift 예산 이하 TTL은 Redis에 보내기 전에 인자 오류로 거부된다") + void aTtlWithinTheDriftBudgetIsRejectedBeforeReachingRedis() { + // given + RedisDistributedLeaseAdapter drifted = + adapter(new StubClient(gateway.gateway()), Duration.ofSeconds(2)); + LeaseAttempt attempt = drifted.newAttempt(OPERATION_A); + + // when + Throwable failure = + catchThrowable(() -> drifted.tryAcquire(request(attempt, Duration.ofSeconds(1)))); + + // then + assertThat(failure) + .isInstanceOf(IllegalArgumentException.class) + .hasMessageContaining("is not longer than the configured clock-drift budget"); + } + + @Test + @DisplayName("drift 예산 이하 TTL로 거부된 acquire는 서버에 lease를 남기지 않는다") + void aTtlWithinTheDriftBudgetLeavesTheResourceFree() { + // given + RedisDistributedLeaseAdapter drifted = + adapter(new StubClient(gateway.gateway()), Duration.ofSeconds(2)); + LeaseAttempt attempt = drifted.newAttempt(OPERATION_A); + + // when + Throwable unused = + catchThrowable(() -> drifted.tryAcquire(request(attempt, Duration.ofSeconds(1)))); + + // then + assertThat(adapter.inspect(new LeaseInspectionRequest(PURPOSE, RESOURCE, attempt))) + .isInstanceOf(LeaseInspectionOutcome.Absent.class); + } + + @Test + @DisplayName("drift 예산 이하 TTL의 renew는 Redis에 보내기 전에 인자 오류로 거부된다") + void aRenewTtlWithinTheDriftBudgetIsRejectedBeforeReachingRedis() { + // given + RedisDistributedLeaseAdapter drifted = + adapter(new StubClient(gateway.gateway()), Duration.ofSeconds(2)); + LeaseHandle handle = + ((LeaseAcquireOutcome.Acquired) + drifted.tryAcquire( + request(drifted.newAttempt(OPERATION_A), Duration.ofSeconds(30)))) + .handle(); + + // when + Throwable failure = catchThrowable(() -> handle.renew(Duration.ofSeconds(1))); + + // then + assertThat(failure) + .isInstanceOf(IllegalArgumentException.class) + .hasMessageContaining("is not longer than the configured clock-drift budget"); + } + @Test @DisplayName("owner tokens are unguessable and never repeat") void ownerTokensAreUnguessable() { diff --git a/src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/autoconfigure/FileserverStorageGatewayConfiguration.java b/src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/autoconfigure/FileserverStorageGatewayConfiguration.java index 0cef1a75..3aa7d4ca 100644 --- a/src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/autoconfigure/FileserverStorageGatewayConfiguration.java +++ b/src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/autoconfigure/FileserverStorageGatewayConfiguration.java @@ -7,6 +7,7 @@ import dev.caskeleton.adapter.outbound.fileserver.platform.local.LocalDownloadCo import dev.caskeleton.adapter.outbound.fileserver.platform.local.LocalUploadContentGateway; import dev.caskeleton.adapter.outbound.fileserver.platform.local.LocalUploadStorageGateway; import dev.caskeleton.adapter.outbound.fileserver.platform.local.LocalZeroCopyDownloadGateway; +import dev.caskeleton.application.fileserver.admin.OrphanScanPort; import dev.caskeleton.application.fileserver.api.metadata.FileMetadataStore; import dev.caskeleton.application.fileserver.api.metadata.UploadSessionStore; import dev.caskeleton.application.fileserver.cleanup.CleanupContentGateway; @@ -54,8 +55,9 @@ class FileserverStorageGatewayConfiguration { @Bean @ConditionalOnMissingBean - CleanupContentGateway fileserverCleanupContentGateway(LocalBlockingContentStore store) { - return new LocalCleanupContentGateway(store); + CleanupContentGateway fileserverCleanupContentGateway( + LocalBlockingContentStore store, OrphanScanPort orphans) { + return new LocalCleanupContentGateway(store, orphans); } @Bean diff --git a/src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/local/AtomicMoveContentPublisher.java b/src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/local/AtomicMoveContentPublisher.java index 30c3134d..0689ab61 100644 --- a/src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/local/AtomicMoveContentPublisher.java +++ b/src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/local/AtomicMoveContentPublisher.java @@ -43,7 +43,7 @@ final class AtomicMoveContentPublisher implements ContentPublisher { String digest = verification.verifyStaged(root, staging, command); verification.force(root, staging, command.forceDurable()); - ContentKey contentKey = resolver.newContentKey(); + ContentKey contentKey = command.contentKey().orElseGet(resolver::newContentKey); Path target = resolver.contentPath(contentKey); channels.createParentDirectories(root, target); try { diff --git a/src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/local/LocalBlockingContentStore.java b/src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/local/LocalBlockingContentStore.java index db90db8d..e58edd76 100644 --- a/src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/local/LocalBlockingContentStore.java +++ b/src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/local/LocalBlockingContentStore.java @@ -30,7 +30,10 @@ import java.nio.file.Path; import java.nio.file.attribute.BasicFileAttributes; import java.time.Instant; import java.util.Arrays; +import java.util.Collections; +import java.util.LinkedHashMap; import java.util.Locale; +import java.util.Map; import java.util.Optional; /** @@ -44,6 +47,28 @@ public final class LocalBlockingContentStore implements BlockingContentStore { private static final int BUFFER_POOL_CAPACITY = 64; + /** + * Running digests kept across requests. + * + *

Every append and every finalize reattaches a fresh handle, so a digest kept only on the + * handle died with the request and the next one rehashed the whole prefix from disk — quadratic + * reads over a chunked upload. The store keeps the accumulator between requests instead. Copies + * go in and come out, so a rolled-back append can never poison the kept state, and an entry whose + * offset no longer matches the file is simply not used. + */ + // ponytail: LRU of 1024 uploads per node; beyond that an idle upload rehashes once on its next + // append. Raise it if one node carries more concurrent uploads than that. + private static final int DIGEST_CACHE_CAPACITY = 1024; + + private final Map digests = + Collections.synchronizedMap( + new LinkedHashMap<>(16, 0.75f, true) { + @Override + protected boolean removeEldestEntry(Map.Entry eldest) { + return size() > DIGEST_CACHE_CAPACITY; + } + }); + private final LocalStorageProperties properties; private final DefaultPhysicalPathResolver resolver; private final SafeFileChannelFactory channels; @@ -142,19 +167,32 @@ public final class LocalBlockingContentStore implements BlockingContentStore { Optional expectedChunkSha256, WriteFence fence) { LocalUploadHandle local = UploadHandle.requireOwn(handle, LocalUploadHandle.class); - return appendEngine.append( - properties.root(), - local, - expectedOffset, - source, - contentLength, - expectedChunkSha256, - fence); + AppendResult result; + try { + result = + appendEngine.append( + properties.root(), + local, + expectedOffset, + source, + contentLength, + expectedChunkSha256, + fence); + } catch (RuntimeException failure) { + digests.remove(local.uploadId()); + throw failure; + } + local + .digestAt(result.committedOffset()) + .ifPresent(digest -> digests.put(local.uploadId(), digest.copy())); + return result; } @Override public StoredContent finalizeUpload(UploadHandle handle, FinalizeContentCommand command) { LocalUploadHandle local = UploadHandle.requireOwn(handle, LocalUploadHandle.class); + // The staging object stops being appendable here whatever the outcome. + digests.remove(local.uploadId()); PublishResult result = publisher.publish(local, command); verifyPublishedIdentity(result, command); return new StoredContent( @@ -240,6 +278,7 @@ public final class LocalBlockingContentStore implements BlockingContentStore { /** Removes a staging object; used by cancel and by the cleanup worker. */ public DeleteResult discardStaging(UploadId uploadId) { + digests.remove(uploadId); Path staging = resolver.stagingPath(uploadId); if (!channels.isRegularFile(properties.root(), staging)) { return DeleteResult.alreadyGone(); @@ -390,8 +429,18 @@ public final class LocalBlockingContentStore implements BlockingContentStore { "staging object for the upload no longer exists", FileserverFailureContext.of(FileserverErrorCode.FILE_NOT_FOUND, false)); } - return new LocalUploadHandle( - command.uploadId(), command.namespace(), staging, command.maximumLength()); + LocalUploadHandle handle = + new LocalUploadHandle( + command.uploadId(), command.namespace(), staging, command.maximumLength()); + Optional.ofNullable(digests.get(command.uploadId())) + .map(StreamingDigest::copy) + .ifPresent(handle::rememberDigest); + return handle; + } + + /** A fresh content key in this store's layout, for a caller that records it before publishing. */ + public ContentKey newContentKey() { + return resolver.newContentKey(); } /** True when the active publish strategy relies on an atomic rename. */ diff --git a/src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/local/LocalCleanupContentGateway.java b/src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/local/LocalCleanupContentGateway.java index 64a34565..ca6ab300 100644 --- a/src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/local/LocalCleanupContentGateway.java +++ b/src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/local/LocalCleanupContentGateway.java @@ -1,5 +1,6 @@ package dev.caskeleton.adapter.outbound.fileserver.platform.local; +import dev.caskeleton.application.fileserver.admin.OrphanScanPort; import dev.caskeleton.application.fileserver.api.ContentKey; import dev.caskeleton.application.fileserver.api.UploadId; import dev.caskeleton.application.fileserver.api.content.DeletePrecondition; @@ -16,9 +17,11 @@ import dev.caskeleton.application.fileserver.cleanup.CleanupContentGateway; public final class LocalCleanupContentGateway implements CleanupContentGateway { private final LocalBlockingContentStore store; + private final OrphanScanPort orphans; - public LocalCleanupContentGateway(LocalBlockingContentStore store) { + public LocalCleanupContentGateway(LocalBlockingContentStore store, OrphanScanPort orphans) { this.store = store; + this.orphans = orphans; } @Override @@ -30,4 +33,12 @@ public final class LocalCleanupContentGateway implements CleanupContentGateway { public void discardStaging(UploadId uploadId) { store.discardStaging(uploadId); } + + /** + * The orphan scan owns the quarantine area and re-checks the reference ledger before deleting. + */ + @Override + public boolean purgeQuarantined(ContentKey key) { + return orphans.purgeQuarantined(key); + } } diff --git a/src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/local/LocalUploadContentGateway.java b/src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/local/LocalUploadContentGateway.java index c03b3c4a..49cceda0 100644 --- a/src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/local/LocalUploadContentGateway.java +++ b/src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/local/LocalUploadContentGateway.java @@ -1,5 +1,6 @@ package dev.caskeleton.adapter.outbound.fileserver.platform.local; +import dev.caskeleton.application.fileserver.api.ContentKey; import dev.caskeleton.application.fileserver.api.content.CreateContentCommand; import dev.caskeleton.application.fileserver.api.content.FinalizeContentCommand; import dev.caskeleton.application.fileserver.api.content.StoredContent; @@ -61,6 +62,11 @@ public final class LocalUploadContentGateway implements UploadContentGateway { return store.stagingDigest(handle, committedOffset); } + @Override + public ContentKey newContentKey() { + return store.newContentKey(); + } + @Override public StoredContent finalizeUpload(UploadHandle handle, FinalizeContentCommand command) { return store.finalizeUpload(handle, command); diff --git a/src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/local/MetadataPointerContentPublisher.java b/src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/local/MetadataPointerContentPublisher.java index fff98d70..5c7bf965 100644 --- a/src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/local/MetadataPointerContentPublisher.java +++ b/src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/local/MetadataPointerContentPublisher.java @@ -46,7 +46,7 @@ final class MetadataPointerContentPublisher implements ContentPublisher { Path staging = handle.stagingPath(); String digest = verification.verifyStaged(root, staging, command); - ContentKey contentKey = resolver.newContentKey(); + ContentKey contentKey = command.contentKey().orElseGet(resolver::newContentKey); Path target = resolver.contentPath(contentKey); channels.createParentDirectories(root, target); diff --git a/src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/local/StreamingDigest.java b/src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/local/StreamingDigest.java index d60c3a5d..c66e4523 100644 --- a/src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/local/StreamingDigest.java +++ b/src/adapter/outbound/fileserver/src/main/java/dev/caskeleton/adapter/outbound/fileserver/platform/local/StreamingDigest.java @@ -38,6 +38,11 @@ final class StreamingDigest { return offset; } + /** An independent accumulator at the same offset; updating one never moves the other. */ + StreamingDigest copy() { + return new StreamingDigest(cloneDigest(), offset); + } + /** Hex digest of everything accumulated so far; the accumulator stays usable afterwards. */ String hex() { MessageDigest snapshot = cloneDigest(); diff --git a/src/adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/platform/local/LocalAppendEngineTest.java b/src/adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/platform/local/LocalAppendEngineTest.java index b4541079..18a4649f 100644 --- a/src/adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/platform/local/LocalAppendEngineTest.java +++ b/src/adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/platform/local/LocalAppendEngineTest.java @@ -9,6 +9,7 @@ import static dev.caskeleton.adapter.outbound.fileserver.platform.local.LocalCon import static org.assertj.core.api.Assertions.assertThat; import static org.assertj.core.api.Assertions.assertThatThrownBy; +import dev.caskeleton.application.fileserver.api.UploadId; import dev.caskeleton.application.fileserver.api.content.AppendResult; import dev.caskeleton.application.fileserver.api.content.PublishMode; import dev.caskeleton.application.fileserver.api.content.UploadHandle; @@ -25,6 +26,7 @@ import java.nio.channels.ReadableByteChannel; import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.nio.file.Path; +import java.util.UUID; import org.junit.jupiter.api.Test; import org.junit.jupiter.api.io.TempDir; @@ -70,7 +72,7 @@ class LocalAppendEngineTest { } @Test - void aReattachedHandleRehashesThePrefixInsteadOfGuessing() { + void aReattachedHandleStillProducesTheDigestOfTheWholeObject() { LocalBlockingContentStore store = store(root, PublishMode.ATOMIC_MOVE_PREFERRED); dev.caskeleton.application.fileserver.api.UploadId uploadId = dev.caskeleton.application.fileserver.api.UploadId.of(java.util.UUID.randomUUID()); @@ -83,6 +85,47 @@ class LocalAppendEngineTest { assertThat(result.sha256()).isEqualTo(sha256Hex("abcdef")); } + /** + * Every append arrives on a freshly reattached handle, so a handle-local accumulator alone made + * each append rehash the whole prefix — quadratic reads over a chunked upload. + */ + @Test + void aReattachedHandleResumesTheRunningDigestInsteadOfRereadingThePrefix() { + // given + LocalBlockingContentStore store = store(root, PublishMode.ATOMIC_MOVE_PREFERRED); + UploadId uploadId = UploadId.of(UUID.randomUUID()); + UploadHandle first = store.createUpload(createCommand(uploadId)); + store.append(first, 0, channel("abc"), 3); + + // when + UploadHandle reattached = store.reattach(createCommand(uploadId)); + + // then + assertThat(((LocalUploadHandle) reattached).digestAt(3)).isPresent(); + } + + /** The cached accumulator must not absorb bytes a failed append rolled back. */ + @Test + void aRolledBackAppendLeavesTheCachedDigestDescribingOnlyTheSurvivingPrefix() { + // given + LocalBlockingContentStore store = store(root, PublishMode.ATOMIC_MOVE_PREFERRED); + UploadId uploadId = UploadId.of(UUID.randomUUID()); + store.append(store.createUpload(createCommand(uploadId)), 0, channel("abc"), 3); + UploadHandle failing = store.reattach(createCommand(uploadId)); + try { + store.append(failing, 3, channel("toolong"), 2); + } catch (FileTooLargeException rolledBack) { + // The overlong body is truncated away; only "abc" survives on disk. + } + + // when + AppendResult result = + store.append(store.reattach(createCommand(uploadId)), 3, channel("de"), 2); + + // then + assertThat(result.sha256()).isEqualTo(sha256Hex("abcde")); + } + @Test void rejectsMoreBytesThanTheDeclaredContentLength() { LocalBlockingContentStore store = store(root, PublishMode.ATOMIC_MOVE_PREFERRED); diff --git a/src/adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/platform/local/LocalStorageGatewayContractTest.java b/src/adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/platform/local/LocalStorageGatewayContractTest.java index 08d2995f..43a75f20 100644 --- a/src/adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/platform/local/LocalStorageGatewayContractTest.java +++ b/src/adapter/outbound/fileserver/src/test/java/dev/caskeleton/adapter/outbound/fileserver/platform/local/LocalStorageGatewayContractTest.java @@ -24,6 +24,8 @@ import java.nio.channels.Channels; import java.nio.channels.ReadableByteChannel; import java.nio.charset.StandardCharsets; import java.nio.file.Path; +import java.time.Clock; +import java.time.Duration; import java.util.Optional; import java.util.UUID; import org.junit.jupiter.api.BeforeEach; @@ -54,7 +56,14 @@ class LocalStorageGatewayContractTest { store = LocalContentStoreFixture.store(root, PublishMode.ATOMIC_MOVE_PREFERRED); uploads = new LocalUploadStorageGateway(store); downloads = new LocalDownloadContentGateway(store); - cleanup = new LocalCleanupContentGateway(store); + cleanup = + new LocalCleanupContentGateway( + store, + new LocalOrphanScanAdapter( + key -> false, + LocalContentStoreFixture.properties(root, PublishMode.ATOMIC_MOVE_PREFERRED), + Duration.ZERO, + Clock.systemUTC())); copies = new LocalCopyContentGateway(store, LocalContentStoreFixture.MAX_FILE); zeroCopy = new LocalZeroCopyDownloadGateway(store); } diff --git a/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/api/error/HttpRetryBudgetExhaustedException.java b/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/api/error/HttpRetryBudgetExhaustedException.java new file mode 100644 index 00000000..53e82a86 --- /dev/null +++ b/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/api/error/HttpRetryBudgetExhaustedException.java @@ -0,0 +1,16 @@ +package dev.caskeleton.adapter.outbound.httpclient.api.error; + +/** + * The per-upstream retry budget refused a further attempt after a retryable failure. + * + *

Not a rate-limit rejection: no attempt was refused by the local rate limiter, the platform + * declined to spend more of the upstream's retry capacity on this call. + */ +public final class HttpRetryBudgetExhaustedException extends HttpClientException { + + private static final long serialVersionUID = 1L; + + public HttpRetryBudgetExhaustedException(String safeMessage, HttpFailureMetadata metadata) { + super(safeMessage, metadata); + } +} diff --git a/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/api/error/HttpRuntimeDrainingException.java b/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/api/error/HttpRuntimeDrainingException.java new file mode 100644 index 00000000..4773fbbd --- /dev/null +++ b/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/api/error/HttpRuntimeDrainingException.java @@ -0,0 +1,16 @@ +package dev.caskeleton.adapter.outbound.httpclient.api.error; + +/** + * The profile's runtime generation was retired during this call and refused a further attempt. + * + *

A generation drains after a certificate rotation; a new call runs on its replacement. Not a + * rate-limit rejection, which is what this used to be reported as. + */ +public final class HttpRuntimeDrainingException extends HttpClientException { + + private static final long serialVersionUID = 1L; + + public HttpRuntimeDrainingException(String safeMessage, HttpFailureMetadata metadata) { + super(safeMessage, metadata); + } +} diff --git a/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/api/error/HttpUnknownTransportException.java b/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/api/error/HttpUnknownTransportException.java new file mode 100644 index 00000000..e4fbfdc6 --- /dev/null +++ b/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/api/error/HttpUnknownTransportException.java @@ -0,0 +1,18 @@ +package dev.caskeleton.adapter.outbound.httpclient.api.error; + +/** + * The engine failed in a way no stable category describes. + * + *

Nothing about this type says the request was not sent; the evidence in {@link #metadata()} + * does. It used to surface as {@link HttpConnectException}, which promises exactly that, so a + * caller could resend a POST that had already executed. + */ +public final class HttpUnknownTransportException extends HttpClientException { + + private static final long serialVersionUID = 1L; + + public HttpUnknownTransportException( + String safeMessage, HttpFailureMetadata metadata, Throwable cause) { + super(safeMessage, metadata, cause); + } +} diff --git a/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/auth/OAuth2CredentialProvider.java b/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/auth/OAuth2CredentialProvider.java index d8764646..a809cc49 100644 --- a/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/auth/OAuth2CredentialProvider.java +++ b/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/auth/OAuth2CredentialProvider.java @@ -58,13 +58,15 @@ public final class OAuth2CredentialProvider implements RequestCredentialProvider if (request.forceRefresh()) { cache.remove(key); } - AccessToken token = - cache.compute( - key, - (ignored, existing) -> - existing == null || existing.expired(clock, EXPIRY_SKEW) - ? tokenLoader.load(key) - : existing); + // Never load inside cache.compute: that holds the lock of the key's hash bin for the whole + // token + // round trip, so every other key in the bin waited behind it. Concurrent loads of the same key + // are already collapsed by the single-flight loader. + AccessToken token = cache.get(key); + if (token == null || token.expired(clock, EXPIRY_SKEW)) { + token = tokenLoader.load(key); + cache.put(key, token); + } return RequestCredentials.header("Authorization", "Bearer " + token.value()); } diff --git a/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/auth/SingleFlightTokenLoader.java b/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/auth/SingleFlightTokenLoader.java index 7dfdc6e2..8068e209 100644 --- a/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/auth/SingleFlightTokenLoader.java +++ b/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/auth/SingleFlightTokenLoader.java @@ -4,6 +4,7 @@ import dev.caskeleton.adapter.outbound.httpclient.api.error.HttpAuthenticationEx import dev.caskeleton.adapter.outbound.httpclient.api.error.HttpFailureMetadata; import java.time.Duration; import java.util.Objects; +import java.util.concurrent.CancellationException; import java.util.concurrent.CompletableFuture; import java.util.concurrent.ConcurrentHashMap; import java.util.concurrent.ConcurrentMap; @@ -78,9 +79,10 @@ public final class SingleFlightTokenLoader implements AutoCloseable { try { return future.get(acquireTimeout.toMillis(), TimeUnit.MILLISECONDS); } catch (TimeoutException timedOut) { - // Cancelled rather than abandoned: leaving it running would let the next caller join a - // refresh that has already outlived its usefulness. - future.cancel(true); + // Not cancelled: other callers may have joined this refresh and are still inside their own + // wait, and cancelling handed each of them a CancellationException for a refresh that was + // about to succeed. The finally below drops it from inFlight, so the next caller starts a + // fresh refresh instead of joining this one. throw new HttpAuthenticationException( "oauth2 token refresh did not complete within " + acquireTimeout, HttpFailureMetadata.startup( @@ -99,15 +101,22 @@ public final class SingleFlightTokenLoader implements AutoCloseable { key.registrationId())), cause); } catch (InterruptedException interrupted) { - // The caller was cancelled; propagate the interrupt rather than swallowing it. + // This caller was cancelled, not the refresh others may be waiting on; propagate the + // interrupt rather than swallowing it. Thread.currentThread().interrupt(); - future.cancel(true); throw new HttpAuthenticationException( "oauth2 token refresh was interrupted", HttpFailureMetadata.startup( new dev.caskeleton.adapter.outbound.httpclient.api.ClientProfileName( key.registrationId())), interrupted); + } catch (CancellationException cancelled) { + throw new HttpAuthenticationException( + "oauth2 token refresh was cancelled", + HttpFailureMetadata.startup( + new dev.caskeleton.adapter.outbound.httpclient.api.ClientProfileName( + key.registrationId())), + cancelled); } finally { inFlight.remove(key, future); } diff --git a/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/restclient/DefaultGenericHttpGateway.java b/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/restclient/DefaultGenericHttpGateway.java index 17e78785..ccc99f24 100644 --- a/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/restclient/DefaultGenericHttpGateway.java +++ b/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/restclient/DefaultGenericHttpGateway.java @@ -4,7 +4,8 @@ import dev.caskeleton.adapter.outbound.httpclient.api.ClientProfileName; import dev.caskeleton.adapter.outbound.httpclient.api.error.HttpAmbiguousExecutionException; import dev.caskeleton.adapter.outbound.httpclient.api.error.HttpClientException; import dev.caskeleton.adapter.outbound.httpclient.api.error.HttpFailureMetadata; -import dev.caskeleton.adapter.outbound.httpclient.api.error.HttpRateLimitRejectedException; +import dev.caskeleton.adapter.outbound.httpclient.api.error.HttpRetryBudgetExhaustedException; +import dev.caskeleton.adapter.outbound.httpclient.api.error.HttpRuntimeDrainingException; import dev.caskeleton.adapter.outbound.httpclient.api.operation.ExecutionEvidence; import dev.caskeleton.adapter.outbound.httpclient.api.operation.HttpOperation; import dev.caskeleton.adapter.outbound.httpclient.api.result.HttpCallResult; @@ -179,7 +180,7 @@ public final class DefaultGenericHttpGateway implements GenericHttpGateway { @Override public AttemptOutcome attempt(int attemptNumber) { if (!runtime.acceptsNewAttempts() && attemptNumber > 1) { - throw new HttpRateLimitRejectedException( + throw new HttpRuntimeDrainingException( "runtime is draining and refuses new attempts", metadata); } // Checked before every attempt, not only before the first. The deadline used to be verified @@ -277,7 +278,7 @@ public final class DefaultGenericHttpGateway implements GenericHttpGateway { @Override public HttpClientException retryExhausted(int attemptNumber) { observation.recordRetryExhausted(); - return new HttpRateLimitRejectedException( + return new HttpRetryBudgetExhaustedException( "retry budget for this upstream is exhausted", metadata.withAttempt(attemptNumber)); } diff --git a/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/restclient/StableBlockingExceptionMapper.java b/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/restclient/StableBlockingExceptionMapper.java index e4305dce..9b1db6e4 100644 --- a/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/restclient/StableBlockingExceptionMapper.java +++ b/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/restclient/StableBlockingExceptionMapper.java @@ -10,6 +10,7 @@ import dev.caskeleton.adapter.outbound.httpclient.api.error.HttpRequestWriteExce import dev.caskeleton.adapter.outbound.httpclient.api.error.HttpResponseTimeoutException; import dev.caskeleton.adapter.outbound.httpclient.api.error.HttpResponseTruncatedException; import dev.caskeleton.adapter.outbound.httpclient.api.error.HttpTlsException; +import dev.caskeleton.adapter.outbound.httpclient.api.error.HttpUnknownTransportException; import dev.caskeleton.adapter.outbound.httpclient.transport.TransportFailure; /** @@ -34,7 +35,9 @@ public final class StableBlockingExceptionMapper { case REQUEST_WRITE -> new HttpRequestWriteException(message, metadata, cause); case RESPONSE_TIMEOUT -> new HttpResponseTimeoutException(message, metadata, cause); case RESPONSE_TRUNCATED -> new HttpResponseTruncatedException(message, metadata, cause); - default -> new HttpConnectException(message, metadata, cause); + // Not HttpConnectException: that type promises the request was never sent, and an + // unclassified failure promises nothing. The metadata's evidence says what happened. + default -> new HttpUnknownTransportException(message, metadata, cause); }; } } diff --git a/src/adapter/outbound/httpclient/src/main/resources/config/module-defaults/httpclient.yml b/src/adapter/outbound/httpclient/src/main/resources/config/module-defaults/httpclient.yml index 8a74080f..4bb98036 100644 --- a/src/adapter/outbound/httpclient/src/main/resources/config/module-defaults/httpclient.yml +++ b/src/adapter/outbound/httpclient/src/main/resources/config/module-defaults/httpclient.yml @@ -15,3 +15,11 @@ app: # client 별이 아니라 플랫폼 수준: 인증서 교체 뒤 은퇴한 runtime generation 이 pool 을 닫기 전까지 # in-flight 요청을 비우는 시간. rotation-drain-timeout: ${APP_HTTPCLIENT_ROTATION_DRAIN_TIMEOUT:30s} + +# /actuator/info 에 싣는 이 모듈의 상태(management.info.env). compose smoke 가 lane 이 실제로 켠 +# capability 를 이 값으로 확인한다. 위 스위치를 해석한 값이고, 기본값은 +# HttpClientPlatformAutoConfiguration 의 matchIfMissing 과 같다. +info: + capabilities: + httpclient: + enabled: ${app.httpclient.enabled:true} diff --git a/src/adapter/outbound/httpclient/src/test/java/dev/caskeleton/adapter/outbound/httpclient/auth/OAuth2CredentialProviderTest.java b/src/adapter/outbound/httpclient/src/test/java/dev/caskeleton/adapter/outbound/httpclient/auth/OAuth2CredentialProviderTest.java new file mode 100644 index 00000000..ed10f585 --- /dev/null +++ b/src/adapter/outbound/httpclient/src/test/java/dev/caskeleton/adapter/outbound/httpclient/auth/OAuth2CredentialProviderTest.java @@ -0,0 +1,141 @@ +package dev.caskeleton.adapter.outbound.httpclient.auth; + +import static org.assertj.core.api.Assertions.assertThat; + +import dev.caskeleton.adapter.outbound.httpclient.api.ClientProfileName; +import dev.caskeleton.adapter.outbound.httpclient.api.OperationName; +import dev.caskeleton.adapter.outbound.httpclient.profile.AuthenticationSettings; +import dev.caskeleton.adapter.outbound.httpclient.profile.AuthenticationType; +import java.net.URI; +import java.time.Clock; +import java.time.Instant; +import java.util.Optional; +import java.util.Set; +import java.util.concurrent.CountDownLatch; +import java.util.concurrent.ExecutorService; +import java.util.concurrent.Executors; +import java.util.concurrent.Future; +import java.util.concurrent.TimeUnit; +import java.util.stream.IntStream; +import org.junit.jupiter.api.Test; +import org.springframework.security.oauth2.client.OAuth2AuthorizedClient; +import org.springframework.security.oauth2.client.registration.ClientRegistration; +import org.springframework.security.oauth2.core.AuthorizationGrantType; +import org.springframework.security.oauth2.core.OAuth2AccessToken; + +class OAuth2CredentialProviderTest { + + private static final Set SCOPES = Set.of("read"); + + /** + * A slow token endpoint for one registration must not hold up another. + * + *

The provider refreshed inside {@code ConcurrentHashMap.compute}, which holds the lock of the + * key's hash bin for the whole network round trip. Any caller whose key landed in the same bin — + * a different registration, a different scope — waited on that lock until the slow refresh gave + * up, then started its own. The second registration here is chosen to share the bin with the + * first, which is what a real deployment gets by chance. + */ + @Test + void aSlowRefreshDoesNotHoldUpAnotherRegistrationThatSharesItsBin() throws Exception { + // given + String slow = "slow"; + String other = registrationSharingABinWith(slow); + CountDownLatch slowEntered = new CountDownLatch(1); + CountDownLatch releaseSlow = new CountDownLatch(1); + OAuth2CredentialProvider provider = + new OAuth2CredentialProvider( + request -> { + if (request.getClientRegistrationId().equals(slow)) { + slowEntered.countDown(); + awaitQuietly(releaseSlow); + } + return authorizedClient(request.getClientRegistrationId()); + }, + Clock.systemUTC()); + ExecutorService callers = Executors.newFixedThreadPool(2); + try { + Future slowCall = callers.submit(() -> provider.resolve(request(slow))); + assertThat(slowEntered.await(5, TimeUnit.SECONDS)).isTrue(); + assertThat(slowCall).isNotDone(); + + // when + Future otherCall = callers.submit(() -> provider.resolve(request(other))); + + // then + assertThat(otherCall.get(5, TimeUnit.SECONDS).headers()) + .containsEntry("Authorization", "Bearer token-" + other); + } finally { + releaseSlow.countDown(); + callers.shutdownNow(); + } + } + + /** + * A second registration whose cache key lands in the same bin as {@code registration}. + * + *

Mirrors the key the provider builds and {@code ConcurrentHashMap}'s bin index for its + * initial table of 16: the spread hash {@code h ^ (h >>> 16)} masked to the table size. + */ + private static String registrationSharingABinWith(String registration) { + int bin = bin(key(registration)); + return IntStream.range(0, 10_000) + .mapToObj(index -> "other-" + index) + .filter(candidate -> bin(key(candidate)) == bin) + .findFirst() + .orElseThrow(); + } + + private static int bin(OAuth2TokenCacheKey key) { + int hash = key.hashCode(); + return (hash ^ (hash >>> 16)) & 15; + } + + private static OAuth2TokenCacheKey key(String registration) { + return new OAuth2TokenCacheKey( + registration, "anonymous", SCOPES, Optional.empty(), Optional.empty(), Optional.empty()); + } + + private static CredentialRequest request(String registration) { + return new CredentialRequest( + new ClientProfileName(registration), + new OperationName("call"), + new AuthenticationSettings( + AuthenticationType.OAUTH2_CLIENT_CREDENTIALS, + Optional.of(registration), + SCOPES, + Optional.empty(), + Optional.empty(), + Optional.empty()), + URI.create("https://api.example"), + Optional.empty(), + Optional.empty(), + false); + } + + private static OAuth2AuthorizedClient authorizedClient(String registration) { + ClientRegistration clientRegistration = + ClientRegistration.withRegistrationId(registration) + .authorizationGrantType(AuthorizationGrantType.CLIENT_CREDENTIALS) + .clientId("client") + .tokenUri("https://auth.example/token") + .build(); + Instant now = Instant.now(); + return new OAuth2AuthorizedClient( + clientRegistration, + "anonymous", + new OAuth2AccessToken( + OAuth2AccessToken.TokenType.BEARER, + "token-" + registration, + now, + now.plusSeconds(300))); + } + + private static void awaitQuietly(CountDownLatch latch) { + try { + latch.await(30, TimeUnit.SECONDS); + } catch (InterruptedException interrupted) { + Thread.currentThread().interrupt(); + } + } +} diff --git a/src/adapter/outbound/httpclient/src/test/java/dev/caskeleton/adapter/outbound/httpclient/auth/SingleFlightTokenLoaderTest.java b/src/adapter/outbound/httpclient/src/test/java/dev/caskeleton/adapter/outbound/httpclient/auth/SingleFlightTokenLoaderTest.java index 19a410d8..909c3068 100644 --- a/src/adapter/outbound/httpclient/src/test/java/dev/caskeleton/adapter/outbound/httpclient/auth/SingleFlightTokenLoaderTest.java +++ b/src/adapter/outbound/httpclient/src/test/java/dev/caskeleton/adapter/outbound/httpclient/auth/SingleFlightTokenLoaderTest.java @@ -1,6 +1,7 @@ package dev.caskeleton.adapter.outbound.httpclient.auth; import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.catchThrowable; import java.time.Clock; import java.time.Duration; @@ -64,6 +65,63 @@ class SingleFlightTokenLoaderTest { } } + /** + * One caller giving up must not take the shared refresh away from the callers still waiting on + * it. + * + *

A caller that timed out cancelled the shared future, so every caller that had joined the + * same refresh received a raw {@code CancellationException} — not even the platform's + * authentication failure — although the refresh itself was still running and about to succeed. + */ + @Test + void aCallerThatJoinedLaterStillGetsTheTokenAfterAnEarlierCallerTimedOut() throws Exception { + // given + CountDownLatch release = new CountDownLatch(1); + ExecutorService callers = Executors.newFixedThreadPool(2); + try (SingleFlightTokenLoader loader = + new SingleFlightTokenLoader( + key -> { + try { + release.await(10, TimeUnit.SECONDS); + } catch (InterruptedException interrupted) { + Thread.currentThread().interrupt(); + } + return new AccessToken( + "token", Clock.systemUTC().instant().plus(Duration.ofMinutes(5))); + }, + 1, + Duration.ofSeconds(1))) { + Future first = callers.submit(() -> loader.load(KEY)); + awaitJoined(loader, 1); + // The later caller's own wait ends half a second after the first caller's. + Thread.sleep(500); + Future later = callers.submit(() -> loader.load(KEY)); + awaitJoined(loader, 2); + assertThat(catchThrowable(() -> first.get(5, TimeUnit.SECONDS))) + .hasCauseInstanceOf( + dev.caskeleton.adapter.outbound.httpclient.api.error.HttpAuthenticationException + .class); + release.countDown(); + + // when + AccessToken token = later.get(5, TimeUnit.SECONDS); + + // then + assertThat(token.value()).isEqualTo("token"); + } finally { + callers.shutdownNow(); + } + } + + private static void awaitJoined(SingleFlightTokenLoader loader, int callers) + throws InterruptedException { + long deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(5); + while (loader.joinedCallers() < callers && System.nanoTime() < deadline) { + Thread.sleep(5); + } + assertThat(loader.joinedCallers()).isGreaterThanOrEqualTo(callers); + } + @Test void tokenValueIsNeverRenderedInTextForm() { AccessToken token = diff --git a/src/adapter/outbound/httpclient/src/test/java/dev/caskeleton/adapter/outbound/httpclient/restclient/DefaultGenericHttpGatewayTest.java b/src/adapter/outbound/httpclient/src/test/java/dev/caskeleton/adapter/outbound/httpclient/restclient/DefaultGenericHttpGatewayTest.java index 3518a243..b1ed53be 100644 --- a/src/adapter/outbound/httpclient/src/test/java/dev/caskeleton/adapter/outbound/httpclient/restclient/DefaultGenericHttpGatewayTest.java +++ b/src/adapter/outbound/httpclient/src/test/java/dev/caskeleton/adapter/outbound/httpclient/restclient/DefaultGenericHttpGatewayTest.java @@ -2,22 +2,31 @@ package dev.caskeleton.adapter.outbound.httpclient.restclient; import static org.assertj.core.api.Assertions.assertThat; import static org.assertj.core.api.Assertions.assertThatThrownBy; +import static org.assertj.core.api.Assertions.catchThrowable; import dev.caskeleton.adapter.outbound.httpclient.api.ClientProfileName; import dev.caskeleton.adapter.outbound.httpclient.api.OperationName; import dev.caskeleton.adapter.outbound.httpclient.api.error.HttpProblemDetailException; import dev.caskeleton.adapter.outbound.httpclient.api.error.HttpRemoteErrorException; +import dev.caskeleton.adapter.outbound.httpclient.api.error.HttpRetryBudgetExhaustedException; +import dev.caskeleton.adapter.outbound.httpclient.api.error.HttpRuntimeDrainingException; import dev.caskeleton.adapter.outbound.httpclient.api.error.HttpTargetRejectedException; import dev.caskeleton.adapter.outbound.httpclient.api.operation.HttpOperation; import dev.caskeleton.adapter.outbound.httpclient.api.result.HttpCallResult; import dev.caskeleton.adapter.outbound.httpclient.api.result.ResponseType; import dev.caskeleton.adapter.outbound.httpclient.observation.HttpClientObservationNames; +import dev.caskeleton.adapter.outbound.httpclient.profile.ClientRuntime; +import dev.caskeleton.adapter.outbound.httpclient.profile.PoolSettings; +import dev.caskeleton.adapter.outbound.httpclient.resilience.RetryAllowed; +import dev.caskeleton.adapter.outbound.httpclient.resilience.RetryEligibilityEngine; import dev.caskeleton.adapter.outbound.httpclient.testkit.ClientProfiles; import dev.caskeleton.adapter.outbound.httpclient.testkit.MockHttpServer; +import dev.caskeleton.adapter.outbound.httpclient.testkit.ScriptedTransport; import dev.caskeleton.adapter.outbound.httpclient.testkit.TestGateways; import dev.caskeleton.adapter.outbound.httpclient.testkit.UserResponse; import java.time.Duration; import java.util.Map; +import java.util.concurrent.atomic.AtomicReference; import org.junit.jupiter.api.Test; import org.slf4j.MDC; @@ -265,4 +274,85 @@ class DefaultGenericHttpGatewayTest { } } } + + /** + * The budget is read when the retry is decided and spent just after; a concurrent call can spend + * the last token in between. That refusal was reported as a local rate-limit rejection. + */ + @Test + void anExhaustedRetryBudgetIsReportedAsItsOwnFailureNotARateLimit() { + // given + ScriptedTransport transport = new ScriptedTransport().json(503, "{}").json(503, "{}"); + var profile = ClientProfiles.builder("budgeted").pool(smallPool()).retryEnabled(5).build(); + RetryEligibilityEngine alwaysRetry = context -> RetryAllowed.of("UPSTREAM_UNAVAILABLE"); + + // when + Throwable thrown; + try (TestGateways.Harness harness = TestGateways.forProfile(profile, transport, alwaysRetry)) { + thrown = catchThrowable(() -> getUser(harness)); + } + + // then + assertThat(thrown) + .isInstanceOf(HttpRetryBudgetExhaustedException.class) + .hasMessage("retry budget for this upstream is exhausted"); + } + + /** + * A certificate rotation can retire the runtime after a retry was granted and before it starts. + * That refusal was reported as a local rate-limit rejection. + */ + @Test + void aRetryRefusedByADrainingRuntimeIsReportedAsItsOwnFailureNotARateLimit() { + // given + ScriptedTransport transport = new ScriptedTransport().json(503, "{}").json(200, USER); + var profile = ClientProfiles.builder("rotating").retryEnabled(2).build(); + AtomicReference runtime = new AtomicReference<>(); + RetryEligibilityEngine rotateThenRetry = + context -> { + runtime.get().beginDrain(Duration.ofSeconds(5)); + return RetryAllowed.of("UPSTREAM_UNAVAILABLE"); + }; + + // when + Throwable thrown; + try (TestGateways.Harness harness = + TestGateways.forProfile(profile, transport, rotateThenRetry)) { + runtime.set(harness.registry().current(profile.name())); + thrown = catchThrowable(() -> getUser(harness)); + } + + // then + assertThat(thrown) + .isInstanceOf(HttpRuntimeDrainingException.class) + .hasMessage("runtime is draining and refuses new attempts"); + } + + private static final String USER = "{\"id\":1,\"name\":\"a\"}"; + + private static void getUser(TestGateways.Harness harness) { + harness + .gateway() + .exchange( + harness.profile().name(), + HttpOperation.get(new OperationName("get-user"), "/users/1", Map.of()), + ResponseType.of(UserResponse.class)); + } + + private static PoolSettings smallPool() { + PoolSettings base = ClientProfiles.pool(); + // A pool of five connections gives the retry budget a capacity of one token. + return new PoolSettings( + 5, + 5, + base.maxPendingAcquires(), + base.pendingAcquireTimeout(), + base.maxIdleTime(), + base.maxLifeTime(), + base.validateAfterInactivity(), + base.evictionInterval(), + base.shutdownTimeout(), + false, + false); + } } diff --git a/src/adapter/outbound/httpclient/src/test/java/dev/caskeleton/adapter/outbound/httpclient/restclient/StableBlockingExceptionMapperTest.java b/src/adapter/outbound/httpclient/src/test/java/dev/caskeleton/adapter/outbound/httpclient/restclient/StableBlockingExceptionMapperTest.java new file mode 100644 index 00000000..408432ea --- /dev/null +++ b/src/adapter/outbound/httpclient/src/test/java/dev/caskeleton/adapter/outbound/httpclient/restclient/StableBlockingExceptionMapperTest.java @@ -0,0 +1,32 @@ +package dev.caskeleton.adapter.outbound.httpclient.restclient; + +import static org.assertj.core.api.Assertions.assertThat; + +import dev.caskeleton.adapter.outbound.httpclient.api.error.HttpClientException; +import dev.caskeleton.adapter.outbound.httpclient.api.error.HttpUnknownTransportException; +import dev.caskeleton.adapter.outbound.httpclient.api.operation.AttemptStage; +import dev.caskeleton.adapter.outbound.httpclient.api.operation.FailureCategory; +import dev.caskeleton.adapter.outbound.httpclient.testkit.CoreFixtures; +import dev.caskeleton.adapter.outbound.httpclient.transport.TransportFailure; +import org.junit.jupiter.api.Test; + +class StableBlockingExceptionMapperTest { + + @Test + void unknownTransportFailureIsNotReportedAsAConnectFailure() { + // given + TransportFailure failure = + TransportFailure.sentNoResponse( + AttemptStage.RESPONSE_HEADERS, FailureCategory.UNKNOWN, "unclassified"); + + // when + HttpClientException mapped = + new StableBlockingExceptionMapper() + .map(failure, CoreFixtures.notSentMetadata(), new IllegalStateException("engine")); + + // then + assertThat(mapped) + .isInstanceOf(HttpUnknownTransportException.class) + .hasMessage("outbound http attempt failed: unclassified"); + } +} diff --git a/src/adapter/outbound/httpclient/src/testFixtures/java/dev/caskeleton/adapter/outbound/httpclient/testkit/TestGateways.java b/src/adapter/outbound/httpclient/src/testFixtures/java/dev/caskeleton/adapter/outbound/httpclient/testkit/TestGateways.java index a9a9808a..e5a7a07a 100644 --- a/src/adapter/outbound/httpclient/src/testFixtures/java/dev/caskeleton/adapter/outbound/httpclient/testkit/TestGateways.java +++ b/src/adapter/outbound/httpclient/src/testFixtures/java/dev/caskeleton/adapter/outbound/httpclient/testkit/TestGateways.java @@ -9,6 +9,7 @@ import dev.caskeleton.adapter.outbound.httpclient.profile.ClientRuntimeRegistry; import dev.caskeleton.adapter.outbound.httpclient.profile.RuntimeGeneration; import dev.caskeleton.adapter.outbound.httpclient.profile.TransportType; import dev.caskeleton.adapter.outbound.httpclient.resilience.ResilienceRegistry; +import dev.caskeleton.adapter.outbound.httpclient.resilience.RetryEligibilityEngine; import dev.caskeleton.adapter.outbound.httpclient.restclient.BlockingAttemptExecutor; import dev.caskeleton.adapter.outbound.httpclient.restclient.BlockingExecutionSupport; import dev.caskeleton.adapter.outbound.httpclient.restclient.DefaultGenericHttpGateway; @@ -80,7 +81,25 @@ public final class TestGateways { ClientProfile profile, CredentialProviderRegistry credentialProviders, BlockingTransportProvider transport) { - return forProfile(profile, credentialProviders, Map.of(profile.transport(), transport)); + return forProfile( + profile, credentialProviders, Map.of(profile.transport(), transport), Optional.empty()); + } + + /** + * Serves the profile through the given transport and lets {@code eligibility} decide retries. + * + *

For paths that only a retry decision can reach — a budget or a runtime that changes between + * the decision and the next attempt. + */ + public static Harness forProfile( + ClientProfile profile, + BlockingTransportProvider transport, + RetryEligibilityEngine eligibility) { + return forProfile( + profile, + CredentialProviderRegistry.withNoAuth(), + Map.of(profile.transport(), transport), + Optional.of(eligibility)); } private static Harness forProfile( @@ -93,20 +112,23 @@ public final class TestGateways { new ApacheBlockingTransportProvider( Optional.empty(), ignored -> Optional.empty(), resolverFactory)); providers.put(TransportType.JDK, new JdkBlockingTransportProvider()); - return forProfile(profile, credentialProviders, providers); + return forProfile(profile, credentialProviders, providers, Optional.empty()); } private static Harness forProfile( ClientProfile profile, CredentialProviderRegistry credentialProviders, - Map providers) { + Map providers, + Optional eligibility) { MeterRegistry meterRegistry = new SimpleMeterRegistry(); + BlockingExecutionSupport standard = + BlockingExecutionSupport.standard(Clock.systemUTC(), meterRegistry); RestClientRuntimeFactory factory = new RestClientRuntimeFactory( providers, ResilienceRegistry.withDefaults(Clock.systemUTC()), credentialProviders, - BlockingExecutionSupport.standard(Clock.systemUTC(), meterRegistry), + eligibility.map(engine -> withEligibility(standard, engine)).orElse(standard), TransportLifecycleListener.noop(), RandomGenerator.getDefault()); @@ -118,4 +140,28 @@ public final class TestGateways { meterRegistry, profile); } + + private static BlockingExecutionSupport withEligibility( + BlockingExecutionSupport support, RetryEligibilityEngine eligibility) { + return new BlockingExecutionSupport( + support.clock(), + support.meterRegistry(), + support.tagPolicy(), + support.evidenceClassifier(), + support.protocolEvidenceReader(), + support.http2EvidenceMapper(), + eligibility, + support.bodyWriter(), + support.responseReader(), + support.responseMapper(), + support.exceptionMapper(), + support.redirectEvaluator(), + support.headerStripper(), + support.deadlineCalculator(), + support.attemptBudgetCalculator(), + support.unauthorizedRetryPolicy(), + support.minimumAttemptBudget(), + support.cleanupReserve(), + support.transientServerErrorStatuses()); + } } diff --git a/src/adapter/outbound/messaging-kafka/README.md b/src/adapter/outbound/messaging-kafka/README.md index 6aa49219..8e04d3a3 100644 --- a/src/adapter/outbound/messaging-kafka/README.md +++ b/src/adapter/outbound/messaging-kafka/README.md @@ -29,7 +29,8 @@ adapter:outbound:messaging-kafka - 설정: `config/module-defaults/messaging.yml`을 support의 `ModuleDefaultsEnvironmentPostProcessor`가 읽는다. 우선순위가 가장 낮아서 `application*.yml`, 환경 변수, 시스템 속성이 항상 이긴다. app-bootstrap은 이 파일을 모른다. - broker 주소 하나(`APP_MESSAGING_KAFKA_BROKERS`)가 legacy seam(`app.messaging.kafka.brokers`)과 - platform transport(`spring.kafka.bootstrap-servers`) 양쪽에 들어간다. + platform transport(`app.messaging.brokers.kafka.bootstrap-servers`) 양쪽에 들어간다. + `spring.kafka.bootstrap-servers`는 읽지 않는다. 논리 broker 이름은 `kafka` 하나다. ## 추가할 한 줄 diff --git a/src/adapter/outbound/messaging-kafka/src/main/java/dev/caskeleton/adapter/outbound/messaging/kafka/KafkaSenderAutoConfiguration.java b/src/adapter/outbound/messaging-kafka/src/main/java/dev/caskeleton/adapter/outbound/messaging/kafka/KafkaSenderAutoConfiguration.java index 5ed9f6b1..3b81ade8 100644 --- a/src/adapter/outbound/messaging-kafka/src/main/java/dev/caskeleton/adapter/outbound/messaging/kafka/KafkaSenderAutoConfiguration.java +++ b/src/adapter/outbound/messaging-kafka/src/main/java/dev/caskeleton/adapter/outbound/messaging/kafka/KafkaSenderAutoConfiguration.java @@ -97,7 +97,8 @@ public class KafkaSenderAutoConfiguration { public KafkaSender kafkaSender( @Qualifier("kafkaSeamProducer") Producer producer) { Duration ackTimeout = Duration.ofSeconds(30); - return message -> + return message -> { + try { producer .send( new ProducerRecord<>( @@ -108,5 +109,12 @@ public class KafkaSenderAutoConfiguration { message.key().isEmpty() ? null : message.key(), message.payload())) .get(ackTimeout.toMillis(), TimeUnit.MILLISECONDS); + } catch (InterruptedException interrupted) { + // Future.get cleared the flag when it threw, and the callers above catch Exception. Without + // restoring it, a relay being shut down kept waiting out every remaining row's timeout. + Thread.currentThread().interrupt(); + throw interrupted; + } + }; } } diff --git a/src/adapter/outbound/messaging-kafka/src/main/resources/config/module-defaults/messaging.yml b/src/adapter/outbound/messaging-kafka/src/main/resources/config/module-defaults/messaging.yml index 3dfa8d69..f095acce 100644 --- a/src/adapter/outbound/messaging-kafka/src/main/resources/config/module-defaults/messaging.yml +++ b/src/adapter/outbound/messaging-kafka/src/main/resources/config/module-defaults/messaging.yml @@ -12,12 +12,20 @@ app: # canonical IntegrationEventPublishPort bridge 의 producer id. 비어 있으면 bridge 가 없다. # host/pod/process 이름에서 추측하지 않는다. producer-id: ${APP_MESSAGING_PRODUCER_ID:} + # messaging platform 의 Kafka transport 가 연결하는 broker. 논리 이름은 kafka 하나다. + # 비어 있으면 기동이 실패한다(app.messaging.brokers.kafka.bootstrap-servers). + brokers: + kafka: + type: kafka + bootstrap-servers: ${APP_MESSAGING_KAFKA_BROKERS:} kafka: - # CSV host:port. legacy KafkaSender seam 이 쓴다. 켠 상태에서 비어 있으면 기동이 실패한다. + # CSV host:port. 같은 주소를 legacy KafkaSender seam 에도 준다. brokers: ${APP_MESSAGING_KAFKA_BROKERS:} -spring: - kafka: - # 같은 broker 주소를 messaging platform 의 Kafka transport 에도 준다. 키 하나로 두 경로가 같은 - # 클러스터를 본다. SPRING_KAFKA_BOOTSTRAP_SERVERS 를 직접 주면 그 값이 이긴다. - bootstrap-servers: ${APP_MESSAGING_KAFKA_BROKERS:} +# /actuator/info 에 싣는 이 모듈의 상태(management.info.env). compose smoke 가 lane 이 실제로 켠 +# capability 를 이 값으로 확인한다. 위 스위치를 해석한 값이고, 기본값은 messaging root +# auto-configuration 들의 matchIfMissing 과 같다. +info: + capabilities: + messaging: + enabled: ${app.messaging.enabled:true} diff --git a/src/adapter/outbound/messaging-kafka/src/test/java/dev/caskeleton/adapter/outbound/messaging/kafka/KafkaCapabilityActivationTest.java b/src/adapter/outbound/messaging-kafka/src/test/java/dev/caskeleton/adapter/outbound/messaging/kafka/KafkaCapabilityActivationTest.java index c5e30f2f..319225f7 100644 --- a/src/adapter/outbound/messaging-kafka/src/test/java/dev/caskeleton/adapter/outbound/messaging/kafka/KafkaCapabilityActivationTest.java +++ b/src/adapter/outbound/messaging-kafka/src/test/java/dev/caskeleton/adapter/outbound/messaging/kafka/KafkaCapabilityActivationTest.java @@ -49,7 +49,8 @@ class KafkaCapabilityActivationTest { assertThatThrownBy(() -> start().close()) .satisfiesAnyOf( failure -> - assertThat(failure).hasStackTraceContaining("spring.kafka.bootstrap-servers"), + assertThat(failure) + .hasStackTraceContaining("app.messaging.brokers.kafka.bootstrap-servers"), failure -> assertThat(failure).hasStackTraceContaining("app.messaging.kafka.brokers")); } diff --git a/src/adapter/outbound/messaging-kafka/src/test/java/dev/caskeleton/adapter/outbound/messaging/kafka/KafkaSenderInterruptionTest.java b/src/adapter/outbound/messaging-kafka/src/test/java/dev/caskeleton/adapter/outbound/messaging/kafka/KafkaSenderInterruptionTest.java new file mode 100644 index 00000000..16ec4b11 --- /dev/null +++ b/src/adapter/outbound/messaging-kafka/src/test/java/dev/caskeleton/adapter/outbound/messaging/kafka/KafkaSenderInterruptionTest.java @@ -0,0 +1,42 @@ +package dev.caskeleton.adapter.outbound.messaging.kafka; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.catchThrowable; + +import dev.caskeleton.adapter.outbound.messaging.core.OutboundMessage; +import org.apache.kafka.clients.producer.MockProducer; +import org.apache.kafka.common.serialization.StringSerializer; +import org.junit.jupiter.api.AfterEach; +import org.junit.jupiter.api.Test; + +class KafkaSenderInterruptionTest { + + @AfterEach + void clearInterrupt() { + Thread.interrupted(); + } + + /** + * An interrupted wait for the broker's acknowledgement leaves the thread interrupted. + * + *

{@code Future.get} clears the flag when it throws, and the callers above this seam catch + * {@code Exception}. So the interrupt that was meant to stop a relay during shutdown vanished, + * and the relay spent up to thirty seconds on every remaining row. + */ + @Test + void anInterruptedAcknowledgementWaitRethrowsWithTheInterruptFlagRestored() { + // given + KafkaSender sender = + new KafkaSenderAutoConfiguration() + .kafkaSender( + new MockProducer<>(false, null, new StringSerializer(), new StringSerializer())); + Thread.currentThread().interrupt(); + + // when + Throwable thrown = catchThrowable(() -> sender.send(new OutboundMessage("topic", "k", "v"))); + + // then + assertThat(new Object[] {thrown.getClass(), Thread.currentThread().isInterrupted()}) + .containsExactly(InterruptedException.class, true); + } +} diff --git a/src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/core/OutboundMessagePublisher.java b/src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/core/OutboundMessagePublisher.java index 0771078a..3f919e87 100644 --- a/src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/core/OutboundMessagePublisher.java +++ b/src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/core/OutboundMessagePublisher.java @@ -35,7 +35,11 @@ public class OutboundMessagePublisher implements MessagePublisher { sent = true; } catch (Exception ex) { // fail-open: observe with correlationId, delegate durability to outbox/retry, - // do NOT propagate — the core use case must still succeed. + // do NOT propagate — the core use case must still succeed. The failure is swallowed, the + // interrupt is not: a thread being stopped must still see it after this returns. + if (ex instanceof InterruptedException) { + Thread.currentThread().interrupt(); + } observeQuietly( () -> dependencyLogger.logFailure(broker.brokerId(), DEPENDENCY_TYPE, "publish", ex)); } diff --git a/src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/outbox/OutboxMessagePublishAdapter.java b/src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/outbox/OutboxMessagePublishAdapter.java index bb3265ea..d11eb983 100644 --- a/src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/outbox/OutboxMessagePublishAdapter.java +++ b/src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/outbox/OutboxMessagePublishAdapter.java @@ -94,7 +94,11 @@ public final class OutboxMessagePublishAdapter implements OutboxMessagePublishPo } catch (Exception unknownOutcome) { // The legacy MessageBroker seam exposes no transmission evidence. Once send() throws, this // adapter cannot prove that zero bytes reached the broker, so calling it a refusal risks - // losing an event that was accepted before the acknowledgement path failed. + // losing an event that was accepted before the acknowledgement path failed. An interrupt is + // kept, so a relay being shut down stops instead of moving on to the next row. + if (unknownOutcome instanceof InterruptedException) { + Thread.currentThread().interrupt(); + } return OutboxPublishOutcome.AMBIGUOUS; } } diff --git a/src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapter.java b/src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapter.java index a93d080c..eb366e81 100644 --- a/src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapter.java +++ b/src/adapter/outbound/messaging/src/main/java/dev/caskeleton/adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapter.java @@ -55,10 +55,14 @@ public final class PlatformIntegrationEventPublishAdapter implements Integration @Override public CompletionStage publish(ValidatedIntegrationEvent event) { + Objects.requireNonNull(event, "event must not be null"); final PreparedPublish prepared; try { - prepared = prepare(Objects.requireNonNull(event, "event must not be null")); - } catch (RuntimeException incompatibleCanonicalEvent) { + prepared = prepare(event); + } catch (IllegalArgumentException incompatibleCanonicalEvent) { + // Only a value the platform cannot represent is a definite refusal: the same payload is + // refused again, so the relay dead-letters it at once. Any other failure is not evidence of + // that and propagates, so the relay treats it as a retryable failure with its real cause. return CompletableFuture.completedFuture(OutboxPublishOutcome.REJECTED_BEFORE_SEND); } diff --git a/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/core/OutboundMessagePublisherTest.java b/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/core/OutboundMessagePublisherTest.java index ec53e46b..779557cd 100644 --- a/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/core/OutboundMessagePublisherTest.java +++ b/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/core/OutboundMessagePublisherTest.java @@ -91,6 +91,35 @@ class OutboundMessagePublisherTest { .doesNotThrowAnyException(); } + /** + * Fail-open swallows the failure, not the interrupt: a thread being stopped must still see that + * it is being stopped after the publish returns. + */ + @Test + void anInterruptedSendIsSwallowedWithTheInterruptFlagKept() { + // given + MessageBroker interruptedBroker = + new MessageBroker() { + @Override + public String brokerId() { + return "kafka"; + } + + @Override + public void send(OutboundMessage message) throws InterruptedException { + throw new InterruptedException("shutting down"); + } + }; + OutboundMessagePublisher publisher = + new OutboundMessagePublisher(interruptedBroker, dependencyLogger); + + // when + publisher.publish(new OutboundMessage("t", "k", "p")); + + // then + assertThat(Thread.interrupted()).isTrue(); + } + @Test void publishFailureLogCarriesCorrelationIdAndBrokerId() { MDC.put(OutboundCorrelation.MDC_KEY, "corr-msg-1"); diff --git a/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/outbox/OutboxCanonicalPublishRoutingTest.java b/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/outbox/OutboxCanonicalPublishRoutingTest.java index f488776d..eeac704c 100644 --- a/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/outbox/OutboxCanonicalPublishRoutingTest.java +++ b/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/outbox/OutboxCanonicalPublishRoutingTest.java @@ -113,6 +113,7 @@ class OutboxCanonicalPublishRoutingTest { private static ValidatedIntegrationEvent canonicalEvent() { String partition = "a".repeat(64); + byte[] envelope = "{\"wire\":\"exact\"}".getBytes(StandardCharsets.UTF_8); Sha256 zero = new Sha256(new byte[32]); return new ValidatedIntegrationEvent( new EventId("01994e11-4d88-7000-8000-000000000001"), @@ -127,10 +128,10 @@ class OutboxCanonicalPublishRoutingTest { Optional.empty(), partition, partition.getBytes(StandardCharsets.US_ASCII), - "{\"wire\":\"exact\"}".getBytes(StandardCharsets.UTF_8), + envelope, "application/json", zero, - zero, + Sha256.of(envelope), zero, zero, "catalog-r1", diff --git a/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/outbox/OutboxMessagePublishAdapterTest.java b/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/outbox/OutboxMessagePublishAdapterTest.java index 9ab82ff4..30ecccc9 100644 --- a/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/outbox/OutboxMessagePublishAdapterTest.java +++ b/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/outbox/OutboxMessagePublishAdapterTest.java @@ -170,6 +170,26 @@ class OutboxMessagePublishAdapterTest { .isInstanceOf(dev.caskeleton.application.outbox.OutboxPublishAmbiguousException.class); } + /** + * A relay stopped mid-send stays stopped. + * + *

The interrupt was consumed by the catch that turns a failed send into AMBIGUOUS, so a + * relay being shut down went on to the next row and waited out that row's acknowledgement + * timeout too. + */ + @Test + void anInterruptedSendKeepsTheRelayThreadInterrupted() { + // given + FakeBroker broker = new FakeBroker(new InterruptedException("shutting down")); + OutboxMessagePublishAdapter adapter = new OutboxMessagePublishAdapter(broker); + + // when + adapter.publishForOutcome(sampleEvent()); + + // then + assertThat(Thread.interrupted()).isTrue(); + } + @Test void adapterStateContainsOnlyTheTwoTransportReferencesAndCanonicalGate() { assertThat( diff --git a/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapterTest.java b/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapterTest.java index 2401d22a..046d7fb2 100644 --- a/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapterTest.java +++ b/src/adapter/outbound/messaging/src/test/java/dev/caskeleton/adapter/outbound/messaging/platformbridge/PlatformIntegrationEventPublishAdapterTest.java @@ -1,6 +1,7 @@ package dev.caskeleton.adapter.outbound.messaging.platformbridge; import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.catchThrowable; import dev.caskeleton.application.messaging.contract.ContractId; import dev.caskeleton.application.messaging.contract.LogicalDestinationId; @@ -112,6 +113,29 @@ class PlatformIntegrationEventPublishAdapterTest { assertThat(publisher.calls).isZero(); } + /** + * Only an event the platform cannot represent is a definite refusal. + * + *

Every runtime failure in {@code prepare} used to become REJECTED_BEFORE_SEND, which the + * relay dead-letters at once as "the same payload will be refused again" — so a programming error + * or a transient fault parked the event permanently, with the cause discarded. + */ + @Test + void aFailureOtherThanAnIncompatibleValueIsNotTurnedIntoARefusal() { + // given + PlatformIntegrationEventPublishAdapter bridge = + new PlatformIntegrationEventPublishAdapter( + new RecordingPublisher(confirmed()), "portfolio-service"); + + // when + Throwable thrown = catchThrowable(() -> bridge.publish(null)); + + // then + assertThat(thrown) + .isInstanceOf(NullPointerException.class) + .hasMessage("event must not be null"); + } + private static ValidatedIntegrationEvent event(String eventId, Optional causationId) { byte[] envelope = "{\"wire\":\"exact\"}".getBytes(StandardCharsets.UTF_8); Sha256 zero = new Sha256(new byte[32]); @@ -132,7 +156,7 @@ class PlatformIntegrationEventPublishAdapterTest { envelope, "application/json", zero, - zero, + Sha256.of(envelope), zero, zero, "catalog-r1", diff --git a/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/NotificationPlatformRegistriesConfig.java b/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/NotificationPlatformRegistriesConfig.java index f46387fb..522ff886 100644 --- a/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/NotificationPlatformRegistriesConfig.java +++ b/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/NotificationPlatformRegistriesConfig.java @@ -31,11 +31,22 @@ import org.springframework.context.annotation.Configuration; matchIfMissing = true) class NotificationPlatformRegistriesConfig { - /** Projector lookup by provider family. */ + /** + * Projector lookup by provider family. + * + *

Built from what assembly produced, which is where a family's projector comes from; a + * projector bean a deployment declares itself is added on top and wins for its family. Built from + * the bean list alone it was always empty, because nothing declared one. + */ @Bean public ProviderEventProjectorRegistry providerEventProjectorRegistry( + NotificationProviderAssembly.AssembledPlatform platform, List projectors) { Map byProvider = new HashMap<>(); + platform + .projectors() + .values() + .forEach(projector -> byProvider.put(projector.providerId(), projector)); projectors.forEach(projector -> byProvider.put(projector.providerId(), projector)); return new MapProviderEventProjectorRegistry(byProvider); } diff --git a/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/NotificationProviderAssembly.java b/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/NotificationProviderAssembly.java index 13cf2ade..725caa42 100644 --- a/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/NotificationProviderAssembly.java +++ b/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/NotificationProviderAssembly.java @@ -128,6 +128,11 @@ public final class NotificationProviderAssembly { settings.callbacks().enabled() && callbackAssembler != null ? callbackAssembler.assemble(profileId, profile) : null; + if (callback != null) { + // With the callback, in both modes: an INGEST_ONLY deployment still projects the events it + // accepts onto the deliveries an earlier serving deployment made. + projectors.put(id, callbackAssembler.projector()); + } // INGEST_ONLY is deliberately callback-capable without being dispatch-capable. Building a // runtime or a route here would make an ingest-only deployment able to send merely because a diff --git a/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/ProviderCallbackAssembler.java b/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/ProviderCallbackAssembler.java index f5f05f4b..00fba3ac 100644 --- a/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/ProviderCallbackAssembler.java +++ b/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/ProviderCallbackAssembler.java @@ -1,6 +1,7 @@ package dev.caskeleton.adapter.outbound.notification.platform.autoconfigure; import dev.caskeleton.adapter.outbound.notification.platform.callback.ProviderCallbackAdapter; +import dev.caskeleton.application.notification.platform.callback.ProviderEventProjector; /** * Builds the callback verifier for one configured provider profile. @@ -23,4 +24,15 @@ interface ProviderCallbackAssembler { * @return the profile-specific verifier */ ProviderCallbackAdapter assemble(String profileId, NotificationPlatformSettings.Provider profile); + + /** + * How this family's verified events move a delivery's projection. + * + *

Required of every callback-capable family. The SES callback was assembled with no projector + * anywhere, so every event it accepted was stored and then marked failed with {@code + * NO_PROJECTOR}: verified bounces and complaints that never reached a delivery. + * + * @return the family's projector + */ + ProviderEventProjector projector(); } diff --git a/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/SesProviderCallbackAssembler.java b/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/SesProviderCallbackAssembler.java index 25cb4acf..1aadd738 100644 --- a/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/SesProviderCallbackAssembler.java +++ b/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/SesProviderCallbackAssembler.java @@ -2,9 +2,11 @@ package dev.caskeleton.adapter.outbound.notification.platform.autoconfigure; import dev.caskeleton.adapter.outbound.notification.platform.callback.ProviderCallbackAdapter; import dev.caskeleton.adapter.outbound.notification.platform.provider.ses.SesCallbackAdapter; +import dev.caskeleton.adapter.outbound.notification.platform.provider.ses.SesDeliveryProjector; import dev.caskeleton.adapter.outbound.notification.platform.provider.ses.SesEventNormalizer; import dev.caskeleton.adapter.outbound.notification.platform.provider.ses.SnsCertificateProvider; import dev.caskeleton.adapter.outbound.notification.platform.provider.ses.SnsSignatureVerifier; +import dev.caskeleton.application.notification.platform.callback.ProviderEventProjector; import java.time.Duration; import java.util.Objects; import java.util.Set; @@ -27,6 +29,11 @@ final class SesProviderCallbackAssembler implements ProviderCallbackAssembler { return ProviderType.SES; } + @Override + public ProviderEventProjector projector() { + return new SesDeliveryProjector(); + } + @Override public ProviderCallbackAdapter assemble( String profileId, NotificationPlatformSettings.Provider profile) { diff --git a/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/SmtpProviderRuntimeAssembler.java b/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/SmtpProviderRuntimeAssembler.java index 263ab806..613f4bd9 100644 --- a/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/SmtpProviderRuntimeAssembler.java +++ b/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/SmtpProviderRuntimeAssembler.java @@ -105,15 +105,21 @@ public final class SmtpProviderRuntimeAssembler implements ProviderRuntimeAssemb ProviderRuntime runtime = new ProviderRuntime( - snapshot(profileId, profile), + snapshot(profileId, profile, adapter.capabilities()), adapter, new ProviderAttemptLimiter(profile.maxConcurrency(), profile.ratePerSecond(), clock)); return AssembledProvider.dispatchOnly(runtime, Channel.EMAIL); } + /** + * The snapshot the dispatch loop plans against. Its capabilities are the adapter's own, as the + * SES assembler does: a second copy here had drifted to a different payload limit. + */ private static ProviderProfileSnapshot snapshot( - String profileId, NotificationPlatformSettings.Provider profile) { + String profileId, + NotificationPlatformSettings.Provider profile, + ProviderCapabilities capabilities) { return new ProviderProfileSnapshot( new ProviderProfileId(profileId), new ProviderId(ProviderType.SMTP.name().toLowerCase(java.util.Locale.ROOT)), @@ -123,32 +129,7 @@ public final class SmtpProviderRuntimeAssembler implements ProviderRuntimeAssemb // rotation increments; starting anywhere but the first would make the first rotation look // like it had already occurred. 1L, - capabilities(), + capabilities, Map.of()); } - - /** - * What SMTP can actually do, stated rather than assumed. - * - *

No batch, no provider-side idempotency, no status callback, no status query, no delivery - * receipt, no native scheduling, cancel or collapse. SMTP is a protocol for handing a message to - * a relay; everything past that is the relay's business and invisible to the sender. A capability - * declared here that the protocol does not have is a promise the dispatch loop will act on. - */ - private static ProviderCapabilities capabilities() { - return new ProviderCapabilities( - false, - false, - false, - false, - false, - false, - false, - false, - 1, - 25L * 1024 * 1024, - // A relay that has not accepted the message within this is not going to; the platform's own - // queue-age bound is what decides how long a request keeps being retried. - java.time.Duration.ofHours(24)); - } } diff --git a/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/dispatch/ProviderRuntime.java b/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/dispatch/ProviderRuntime.java index 61e84aa2..a007aa24 100644 --- a/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/dispatch/ProviderRuntime.java +++ b/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/dispatch/ProviderRuntime.java @@ -123,12 +123,15 @@ public final class ProviderRuntime { return new LimiterPermit(profile.credentialGeneration(), limiter); } - /** Mark the credential as rejected by the provider. */ - public void markAuthenticationFailed(String reasonCode) { + /** + * Mark the credential as rejected by the provider. + * + * @return whether the runtime is now authentication-failed; an operator's DISABLED or DRAINING is + * kept + */ + public boolean markAuthenticationFailed(String reasonCode) { Objects.requireNonNull(reasonCode, "reasonCode"); - // One write, so the state and the reason it carries are never observed apart. - health.set( - new RuntimeHealth(ProviderRuntimeState.AUTHENTICATION_FAILED, Optional.of(reasonCode))); + return moveTo(ProviderRuntimeState.AUTHENTICATION_FAILED, Optional.of(reasonCode)); } /** @@ -203,42 +206,52 @@ public final class ProviderRuntime { * @return whether the runtime is now healthy */ public boolean resumeHealthy() { - return health - .updateAndGet( - current -> - current.state() == ProviderRuntimeState.AUTHENTICATION_FAILED - ? current - : new RuntimeHealth(ProviderRuntimeState.HEALTHY, Optional.empty())) - .state() - == ProviderRuntimeState.HEALTHY; + return moveTo(ProviderRuntimeState.HEALTHY, Optional.empty()); } /** * Stop admitting new attempts; in-flight attempts finish. * - * @return whether it is now draining + * @return whether it is now draining; an authentication failure is kept */ public boolean markDraining() { - return health - .updateAndGet( - current -> - new RuntimeHealth(ProviderRuntimeState.DRAINING, Optional.of("DRAINING"))) - .state() - == ProviderRuntimeState.DRAINING; + return moveTo(ProviderRuntimeState.DRAINING, Optional.of("DRAINING")); } /** * Operator disable. * - * @return whether it is now disabled + * @return whether it is now disabled; an authentication failure is kept */ public boolean markDisabled() { + return moveTo(ProviderRuntimeState.DISABLED, Optional.of("DISABLED")); + } + + /** + * The transition rule between an authentication failure and the operator states, in one place. + * + *

{@code AUTHENTICATION_FAILED} is left only by rotation, which replaces the whole runtime: an + * operator disable or drain on top of it used to overwrite it, and a later resume then declared + * the rejected credential healthy. An operator's {@code DISABLED} or {@code DRAINING} is a + * decision a late authentication failure from an in-flight attempt does not overwrite. + */ + private boolean moveTo(ProviderRuntimeState target, Optional reason) { return health .updateAndGet( - current -> - new RuntimeHealth(ProviderRuntimeState.DISABLED, Optional.of("DISABLED"))) + current -> { + ProviderRuntimeState from = current.state(); + boolean operatorState = + from == ProviderRuntimeState.DISABLED + || from == ProviderRuntimeState.DRAINING; + boolean kept = + target == ProviderRuntimeState.AUTHENTICATION_FAILED + ? operatorState + : from == ProviderRuntimeState.AUTHENTICATION_FAILED; + // One write, so the state and the reason it carries are never observed apart. + return kept ? current : new RuntimeHealth(target, reason); + }) .state() - == ProviderRuntimeState.DISABLED; + == target; } /** diff --git a/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/dispatch/RegistryProviderRuntimeControl.java b/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/dispatch/RegistryProviderRuntimeControl.java index b5ad665c..68275369 100644 --- a/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/dispatch/RegistryProviderRuntimeControl.java +++ b/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/dispatch/RegistryProviderRuntimeControl.java @@ -33,10 +33,7 @@ public final class RegistryProviderRuntimeControl implements ProviderRuntimeCont case HEALTHY -> runtime.resumeHealthy(); case DEGRADED -> runtime.markDegraded(reason); case THROTTLED -> runtime.markThrottled(); - case AUTHENTICATION_FAILED -> { - runtime.markAuthenticationFailed(reason); - yield true; - } + case AUTHENTICATION_FAILED -> runtime.markAuthenticationFailed(reason); // Unreachable while the enum is exhaustive; present so a state added later fails loudly here // rather than silently leaving the runtime in whatever state it was already in. default -> throw new IllegalStateException("unhandled provider runtime state"); diff --git a/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/provider/EmailRecipients.java b/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/provider/EmailRecipients.java new file mode 100644 index 00000000..f6404cb8 --- /dev/null +++ b/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/provider/EmailRecipients.java @@ -0,0 +1,59 @@ +package dev.caskeleton.adapter.outbound.notification.platform.provider; + +import dev.caskeleton.application.notification.platform.api.error.FailureCategory; +import dev.caskeleton.application.notification.platform.api.error.NotificationFailureCode; +import dev.caskeleton.application.notification.platform.contact.ContactPointValue; +import dev.caskeleton.application.notification.platform.contact.EmailAddress; +import dev.caskeleton.application.notification.platform.provider.ProviderCallNotStartedException; +import dev.caskeleton.application.notification.platform.provider.ProviderSubmission; +import dev.caskeleton.application.notification.platform.security.AccessContext; +import dev.caskeleton.application.notification.platform.security.ContactPointProtector; +import java.util.Objects; + +/** + * The email address a submission is for, shared by the email adapters. + * + *

A contact point that cannot be revealed, or that is not an email address, fails before the + * provider is contacted. Thrown as a plain exception it reached the dispatcher as "may already have + * been sent", and an ambiguous attempt is never retried or re-routed. + */ +public final class EmailRecipients { + + private EmailRecipients() {} + + /** + * Reveals the recipient address for dispatch. + * + * @param protector the contact point protector + * @param submission the submission + * @param provider the provider name, for the failure message + * @return the address + * @throws ProviderCallNotStartedException when there is no usable email address + */ + public static EmailAddress reveal( + ContactPointProtector protector, ProviderSubmission submission, String provider) { + Objects.requireNonNull(protector, "protector"); + Objects.requireNonNull(submission, "submission"); + ContactPointValue value; + try { + value = + protector.reveal( + submission.contactPoint(), + AccessContext.dispatch(submission.profile().profileId().value())); + } catch (RuntimeException unreadable) { + throw notStarted("the contact point could not be revealed for dispatch"); + } + if (!(value instanceof EmailAddress address)) { + throw notStarted(provider + " requires an email contact point"); + } + return address; + } + + private static ProviderCallNotStartedException notStarted(String message) { + return new ProviderCallNotStartedException( + NotificationFailureCode.CONTACT_POINT_INVALID, + FailureCategory.INVALID_RECIPIENT, + false, + message); + } +} diff --git a/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/provider/ses/SesNotificationProviderAdapter.java b/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/provider/ses/SesNotificationProviderAdapter.java index 0d252ca5..ed22fc17 100644 --- a/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/provider/ses/SesNotificationProviderAdapter.java +++ b/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/provider/ses/SesNotificationProviderAdapter.java @@ -1,6 +1,7 @@ package dev.caskeleton.adapter.outbound.notification.platform.provider.ses; import dev.caskeleton.adapter.outbound.notification.platform.provider.EmailAttachments; +import dev.caskeleton.adapter.outbound.notification.platform.provider.EmailRecipients; import dev.caskeleton.adapter.outbound.notification.platform.provider.ProviderResults; import dev.caskeleton.adapter.outbound.notification.platform.provider.http.NotificationHttpGateway; import dev.caskeleton.adapter.outbound.notification.platform.provider.http.NotificationHttpRequest; @@ -10,7 +11,6 @@ import dev.caskeleton.adapter.outbound.notification.platform.security.ProviderCr import dev.caskeleton.adapter.outbound.notification.platform.template.NotificationJsonMapper; import dev.caskeleton.application.notification.platform.api.ProviderId; import dev.caskeleton.application.notification.platform.api.routing.Channel; -import dev.caskeleton.application.notification.platform.contact.ContactPointValue; import dev.caskeleton.application.notification.platform.contact.EmailAddress; import dev.caskeleton.application.notification.platform.dispatch.AttachmentIntegrityGuard; import dev.caskeleton.application.notification.platform.provider.NotificationProviderAdapter; @@ -18,7 +18,6 @@ import dev.caskeleton.application.notification.platform.provider.ProviderCapabil import dev.caskeleton.application.notification.platform.provider.ProviderSubmission; import dev.caskeleton.application.notification.platform.provider.ProviderSubmissionResult; import dev.caskeleton.application.notification.platform.provider.ResolvedAttachment; -import dev.caskeleton.application.notification.platform.security.AccessContext; import dev.caskeleton.application.notification.platform.security.ContactPointProtector; import java.time.Clock; import java.time.Duration; @@ -109,13 +108,7 @@ public final class SesNotificationProviderAdapter implements NotificationProvide private ProviderSubmissionResult send(ProviderSubmission submission) { long startedNanos = System.nanoTime(); - ContactPointValue value = - protector.reveal( - submission.contactPoint(), - AccessContext.dispatch(submission.profile().profileId().value())); - if (!(value instanceof EmailAddress address)) { - throw new IllegalArgumentException("SES requires an email contact point"); - } + EmailAddress address = EmailRecipients.reveal(protector, submission, "SES"); // Resolved and verified before the request is shaped, and closed as soon as it is. An // attachment only reaches the wire through the raw MIME message the mapper builds from these diff --git a/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/provider/smtp/SmtpNotificationProviderAdapter.java b/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/provider/smtp/SmtpNotificationProviderAdapter.java index 9d057c52..88c3006c 100644 --- a/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/provider/smtp/SmtpNotificationProviderAdapter.java +++ b/src/adapter/outbound/notification/src/main/java/dev/caskeleton/adapter/outbound/notification/platform/provider/smtp/SmtpNotificationProviderAdapter.java @@ -1,9 +1,9 @@ package dev.caskeleton.adapter.outbound.notification.platform.provider.smtp; import dev.caskeleton.adapter.outbound.notification.platform.provider.EmailAttachments; +import dev.caskeleton.adapter.outbound.notification.platform.provider.EmailRecipients; import dev.caskeleton.application.notification.platform.api.ProviderId; import dev.caskeleton.application.notification.platform.api.routing.Channel; -import dev.caskeleton.application.notification.platform.contact.ContactPointValue; import dev.caskeleton.application.notification.platform.contact.EmailAddress; import dev.caskeleton.application.notification.platform.dispatch.AttachmentIntegrityGuard; import dev.caskeleton.application.notification.platform.provider.NotificationProviderAdapter; @@ -11,7 +11,6 @@ import dev.caskeleton.application.notification.platform.provider.ProviderCapabil import dev.caskeleton.application.notification.platform.provider.ProviderSubmission; import dev.caskeleton.application.notification.platform.provider.ProviderSubmissionResult; import dev.caskeleton.application.notification.platform.provider.ResolvedAttachment; -import dev.caskeleton.application.notification.platform.security.AccessContext; import dev.caskeleton.application.notification.platform.security.ContactPointProtector; import java.time.Duration; import java.util.List; @@ -84,13 +83,7 @@ public final class SmtpNotificationProviderAdapter implements NotificationProvid private ProviderSubmissionResult send(ProviderSubmission submission) { long startedNanos = System.nanoTime(); - ContactPointValue value = - protector.reveal( - submission.contactPoint(), - AccessContext.dispatch(submission.profile().profileId().value())); - if (!(value instanceof EmailAddress address)) { - throw new IllegalArgumentException("SMTP requires an email contact point"); - } + EmailAddress address = EmailRecipients.reveal(protector, submission, "SMTP"); // Resolved, verified and closed around the send. The factory was handed List.of() whatever the // content asked for, so an email with attachments went out without them — the caller was told diff --git a/src/adapter/outbound/notification/src/test/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/NotificationProviderAssemblyTest.java b/src/adapter/outbound/notification/src/test/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/NotificationProviderAssemblyTest.java index fd1dd3fa..222ada3f 100644 --- a/src/adapter/outbound/notification/src/test/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/NotificationProviderAssemblyTest.java +++ b/src/adapter/outbound/notification/src/test/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/NotificationProviderAssemblyTest.java @@ -9,10 +9,30 @@ import dev.caskeleton.adapter.outbound.notification.platform.callback.ProviderCa import dev.caskeleton.adapter.outbound.notification.platform.callback.VerifiedCallback; import dev.caskeleton.adapter.outbound.notification.platform.dispatch.ProviderAttemptLimiter; import dev.caskeleton.adapter.outbound.notification.platform.dispatch.ProviderRuntime; +import dev.caskeleton.application.notification.platform.api.ContactPointId; +import dev.caskeleton.application.notification.platform.api.DeliveryAttemptId; +import dev.caskeleton.application.notification.platform.api.NormalizedEventType; import dev.caskeleton.application.notification.platform.api.NormalizedProviderEvent; +import dev.caskeleton.application.notification.platform.api.NotificationId; import dev.caskeleton.application.notification.platform.api.ProviderId; import dev.caskeleton.application.notification.platform.api.ProviderProfileId; +import dev.caskeleton.application.notification.platform.api.RecipientDeliveryId; +import dev.caskeleton.application.notification.platform.api.TenantId; +import dev.caskeleton.application.notification.platform.api.delivery.AttemptConfirmation; +import dev.caskeleton.application.notification.platform.api.delivery.DeliveryOutcome; +import dev.caskeleton.application.notification.platform.api.delivery.EvidenceLevel; +import dev.caskeleton.application.notification.platform.api.delivery.SubmissionOutcome; import dev.caskeleton.application.notification.platform.api.routing.Channel; +import dev.caskeleton.application.notification.platform.callback.DeliveryAttemptSnapshot; +import dev.caskeleton.application.notification.platform.callback.DeliveryProjection; +import dev.caskeleton.application.notification.platform.callback.ProjectionResult; +import dev.caskeleton.application.notification.platform.callback.ProjectionStatus; +import dev.caskeleton.application.notification.platform.callback.ProviderEventProjector; +import dev.caskeleton.application.notification.platform.callback.ProviderEventProjectorRegistry; +import dev.caskeleton.application.notification.platform.callback.ProviderEventRecord; +import dev.caskeleton.application.notification.platform.callback.ProviderEventRecordId; +import dev.caskeleton.application.notification.platform.callback.ProviderEventSource; +import dev.caskeleton.application.notification.platform.callback.StandardDeliveryProjector; import dev.caskeleton.application.notification.platform.provider.NotificationProviderAdapter; import dev.caskeleton.application.notification.platform.provider.ProviderCapabilities; import dev.caskeleton.application.notification.platform.provider.ProviderProfileSnapshot; @@ -20,9 +40,12 @@ import dev.caskeleton.application.notification.platform.provider.ProviderSubmiss import dev.caskeleton.application.notification.platform.provider.ProviderSubmissionResult; import java.time.Clock; import java.time.Duration; +import java.time.Instant; import java.util.List; import java.util.Map; +import java.util.Optional; import java.util.Set; +import java.util.UUID; import java.util.concurrent.CompletionStage; import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; @@ -246,6 +269,87 @@ class NotificationProviderAssemblyTest { .isEqualTo(new ProviderId("ses")); } + @Test + @DisplayName("SES 콜백의 hard bounce는 SES projector를 찾아 배달 결과에 반영된다") + void anSesHardBounceIsProjectedRatherThanFailedForWantOfAProjector() { + // given + NotificationPlatformSettings settings = + new NotificationPlatformSettings( + true, + NotificationPlatformMode.INGEST_ONLY, + NotificationPlatformSettings.Dispatch.defaults(), + new NotificationPlatformSettings.Callbacks(true, 1_024, Duration.ofMinutes(5)), + Map.of("ses-events", profile("SES", true, false))); + NotificationProviderAssembly.AssembledPlatform platform = + new NotificationProviderAssembly( + List.of(), + List.of( + new SesProviderCallbackAssembler( + url -> { + throw new AssertionError("no certificate is fetched to project"); + }, + Duration.ofMinutes(5)))) + .assemble(settings, NotificationPlatformMode.INGEST_ONLY); + ProviderEventProjectorRegistry registry = + new NotificationPlatformRegistriesConfig() + .providerEventProjectorRegistry(platform, List.of()); + + // when + ProjectionResult result = + registry + .find(new ProviderId("ses")) + .orElseThrow() + .project(sesAttempt(), hardBounce(), DeliveryProjection.accepted()); + + // then + assertThat(result.projection().deliveryOutcome()).isEqualTo(DeliveryOutcome.BOUNCED); + } + + private static DeliveryAttemptSnapshot sesAttempt() { + return new DeliveryAttemptSnapshot( + new DeliveryAttemptId(UUID.fromString("00000000-0000-7000-8000-000000000081")), + new RecipientDeliveryId(UUID.fromString("00000000-0000-7000-8000-000000000082")), + new NotificationId(UUID.fromString("00000000-0000-7000-8000-000000000083")), + new TenantId("tenant-a"), + 1, + Channel.EMAIL, + new ProviderId("ses"), + new ProviderProfileId("ses-events"), + Optional.of("ses-message-1"), + new ContactPointId(UUID.fromString("00000000-0000-7000-8000-000000000084")), + AttemptConfirmation.CONFIRMED, + SubmissionOutcome.CONFIRMED_ACCEPTED, + DeliveryOutcome.UNKNOWN, + EvidenceLevel.PROVIDER_ACCEPTED, + 1L, + "a".repeat(64), + Instant.parse("2026-09-25T00:00:00Z"), + Optional.of(Instant.parse("2026-09-25T00:00:01Z")), + Optional.empty()); + } + + private static ProviderEventRecord hardBounce() { + return new ProviderEventRecord( + new ProviderEventRecordId(UUID.fromString("00000000-0000-7000-8000-000000000085")), + new ProviderProfileId("ses-events"), + new NormalizedProviderEvent( + NormalizedEventType.BOUNCED_HARD, + "Bounce", + Optional.empty(), + Optional.of("ses-message-1"), + Optional.of(Instant.parse("2026-09-25T00:00:02Z")), + Map.of()), + Optional.empty(), + Optional.empty(), + ProviderEventSource.CALLBACK, + true, + Instant.parse("2026-09-25T00:00:02Z"), + "a".repeat(64), + "b".repeat(64), + ProjectionStatus.PENDING, + Optional.empty()); + } + private static NotificationProviderAssembly.AssembledPlatform assemble( Map providers, ProviderRuntimeAssembler... assemblers) { @@ -371,6 +475,12 @@ class NotificationProviderAssemblyTest { } }; } + + @Override + public ProviderEventProjector projector() { + return new StandardDeliveryProjector( + new ProviderId(type.name().toLowerCase(java.util.Locale.ROOT))); + } }; } } diff --git a/src/adapter/outbound/notification/src/test/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/SmtpProviderRuntimeAssemblerTest.java b/src/adapter/outbound/notification/src/test/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/SmtpProviderRuntimeAssemblerTest.java index e452b248..aaf80775 100644 --- a/src/adapter/outbound/notification/src/test/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/SmtpProviderRuntimeAssemblerTest.java +++ b/src/adapter/outbound/notification/src/test/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/SmtpProviderRuntimeAssemblerTest.java @@ -64,6 +64,14 @@ class SmtpProviderRuntimeAssemblerTest { .isFalse(); } + @Test + void theAssembledProfileDeclaresTheAdaptersOwnCapabilities() { + AssembledProvider assembled = assembler().assemble("primary-email", profile()); + + assertThat(assembled.runtime().profile().capabilities()) + .isEqualTo(assembled.runtime().adapter().capabilities()); + } + @Test @DisplayName("the per-profile bounds come from the profile, not from the shared transport") void thePerProfileBoundsComeFromTheProfile() { diff --git a/src/adapter/outbound/notification/src/test/java/dev/caskeleton/adapter/outbound/notification/platform/dispatch/ProviderRuntimeStateTest.java b/src/adapter/outbound/notification/src/test/java/dev/caskeleton/adapter/outbound/notification/platform/dispatch/ProviderRuntimeStateTest.java index 44f27b33..671dd27b 100644 --- a/src/adapter/outbound/notification/src/test/java/dev/caskeleton/adapter/outbound/notification/platform/dispatch/ProviderRuntimeStateTest.java +++ b/src/adapter/outbound/notification/src/test/java/dev/caskeleton/adapter/outbound/notification/platform/dispatch/ProviderRuntimeStateTest.java @@ -18,6 +18,7 @@ import java.time.Duration; import java.time.Instant; import java.time.ZoneOffset; import java.util.Map; +import java.util.Optional; import java.util.Set; import java.util.concurrent.CompletableFuture; import java.util.concurrent.CompletionStage; @@ -27,6 +28,8 @@ import java.util.concurrent.Executors; import java.util.concurrent.TimeUnit; import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.EnumSource; /** * What a runtime's health means, and what closing a permit twice costs. @@ -139,6 +142,54 @@ class ProviderRuntimeStateTest { assertThat(failed.state()).isEqualTo(ProviderRuntimeState.AUTHENTICATION_FAILED); } + @ParameterizedTest + @EnumSource( + value = ProviderRuntimeState.class, + names = {"DISABLED", "DRAINING"}) + void anOperatorStateDoesNotLetResumeClearAnAuthenticationFailure( + ProviderRuntimeState operatorState) { + // given + ProviderRuntime runtime = runtime(1, 1); + runtime.markAuthenticationFailed("INVALID_CREDENTIAL"); + moveByOperator(runtime, operatorState); + + // when + runtime.resumeHealthy(); + + // then + assertThat(runtime.health()) + .isEqualTo( + new ProviderRuntime.RuntimeHealth( + ProviderRuntimeState.AUTHENTICATION_FAILED, Optional.of("INVALID_CREDENTIAL"))); + } + + @ParameterizedTest + @EnumSource( + value = ProviderRuntimeState.class, + names = {"DISABLED", "DRAINING"}) + void aLateAuthenticationFailureDoesNotOverwriteAnOperatorState( + ProviderRuntimeState operatorState) { + // given + ProviderRuntime runtime = runtime(1, 1); + moveByOperator(runtime, operatorState); + + // when + runtime.markAuthenticationFailed("INVALID_CREDENTIAL"); + + // then + assertThat(runtime.health()) + .isEqualTo( + new ProviderRuntime.RuntimeHealth(operatorState, Optional.of(operatorState.name()))); + } + + private static boolean moveByOperator(ProviderRuntime runtime, ProviderRuntimeState state) { + return switch (state) { + case DISABLED -> runtime.markDisabled(); + case DRAINING -> runtime.markDraining(); + default -> throw new IllegalArgumentException("not an operator state: " + state); + }; + } + @Test @DisplayName("degrading an already failed runtime is refused rather than silently ignored") void degradingAFailedRuntimeIsRefused() { diff --git a/src/adapter/outbound/notification/src/test/java/dev/caskeleton/adapter/outbound/notification/platform/provider/smtp/SmtpNotificationProviderAdapterTest.java b/src/adapter/outbound/notification/src/test/java/dev/caskeleton/adapter/outbound/notification/platform/provider/smtp/SmtpNotificationProviderAdapterTest.java index 9a3a66a3..899a37ff 100644 --- a/src/adapter/outbound/notification/src/test/java/dev/caskeleton/adapter/outbound/notification/platform/provider/smtp/SmtpNotificationProviderAdapterTest.java +++ b/src/adapter/outbound/notification/src/test/java/dev/caskeleton/adapter/outbound/notification/platform/provider/smtp/SmtpNotificationProviderAdapterTest.java @@ -1,6 +1,7 @@ package dev.caskeleton.adapter.outbound.notification.platform.provider.smtp; import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.catchThrowable; import dev.caskeleton.adapter.outbound.notification.platform.security.AesGcmContactPointProtector; import dev.caskeleton.adapter.outbound.notification.platform.security.SecurityFixtures; @@ -12,6 +13,8 @@ import dev.caskeleton.application.notification.platform.api.delivery.SubmissionO import dev.caskeleton.application.notification.platform.api.error.FailureCategory; import dev.caskeleton.application.notification.platform.api.routing.Channel; import dev.caskeleton.application.notification.platform.contact.EmailAddress; +import dev.caskeleton.application.notification.platform.contact.PhoneNumber; +import dev.caskeleton.application.notification.platform.provider.ProviderCallNotStartedException; import dev.caskeleton.application.notification.platform.provider.ProviderSubmission; import dev.caskeleton.application.notification.platform.security.ContactPointProtector; import jakarta.mail.Session; @@ -19,6 +22,7 @@ import java.time.Duration; import java.util.Optional; import java.util.Properties; import java.util.concurrent.Executors; +import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; class SmtpNotificationProviderAdapterTest { @@ -109,6 +113,31 @@ class SmtpNotificationProviderAdapterTest { assertThat(result.failure().orElseThrow().retryable()).isFalse(); } + @Test + @DisplayName("이메일이 아닌 연락처는 전송 전에 실패하고 '보냈을 수도 있음'으로 기록되지 않는다") + void aNonEmailContactPointFailsBeforeTheCallStarts() { + // given + ProviderSubmission phoneForEmail = + ProviderFixtures.submission( + ProviderFixtures.profile("smtp-primary", "smtp", Channel.EMAIL), + Channel.EMAIL, + ProviderFixtures.email(), + protector, + new PhoneNumber(ProviderFixtures.SECRET_PHONE), + Optional.empty()); + + // when + Throwable failure = + catchThrowable( + () -> adapter(message -> {}).submit(phoneForEmail).toCompletableFuture().join()); + + // then + assertThat(failure) + .cause() + .isInstanceOf(ProviderCallNotStartedException.class) + .hasMessageContaining("email contact point"); + } + private SmtpNotificationProviderAdapter adapter(SmtpDispatch dispatch) { var properties = new SmtpProviderProperties( diff --git a/src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/config/ObjectStorageCapabilityAssembler.java b/src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/config/ObjectStorageCapabilityAssembler.java index d8648f15..43520b62 100644 --- a/src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/config/ObjectStorageCapabilityAssembler.java +++ b/src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/config/ObjectStorageCapabilityAssembler.java @@ -49,29 +49,55 @@ public final class ObjectStorageCapabilityAssembler { constructed.add(factory); selected.put(provider.providerId(), factory); } - return new AssembledCapability(bindings, selected); + return new AssembledCapability(bindings, selected, constructed); } catch (RuntimeException exception) { - for (int index = constructed.size() - 1; index >= 0; index--) { - constructed.get(index).close(); + try { + closeInReverse(constructed); + } catch (RuntimeException closeFailure) { + exception.addSuppressed(closeFailure); } throw exception; } } + /** + * Closes the providers last-created first, every one of them even when some fail. The first + * failure is rethrown with the later ones suppressed on it. + */ + private static void closeInReverse(List providers) { + RuntimeException failure = null; + for (int index = providers.size() - 1; index >= 0; index--) { + try { + providers.get(index).close(); + } catch (RuntimeException closeFailure) { + if (failure == null) { + failure = closeFailure; + } else { + failure.addSuppressed(closeFailure); + } + } + } + if (failure != null) { + throw failure; + } + } + /** Immutable routing state plus owned provider lifecycle. */ public static final class AssembledCapability implements AutoCloseable { private final ObjectStorageBindingCompiler.CompiledBindings bindings; - private final Map providers; + // Creation order, which close() walks backwards. + private final List providers; private final Map byDestination; private final Map byRoute; private final AtomicBoolean closed = new AtomicBoolean(); private AssembledCapability( ObjectStorageBindingCompiler.CompiledBindings bindings, - Map providers) { + Map providers, + List creationOrder) { this.bindings = bindings; - this.providers = Map.copyOf(providers); + this.providers = List.copyOf(creationOrder); Map destinations = new LinkedHashMap<>(); Map routes = new LinkedHashMap<>(); for (CompiledObjectStorageDestination destination : bindings.destinations().values()) { @@ -110,10 +136,7 @@ public final class ObjectStorageCapabilityAssembler { @Override public void close() { if (closed.compareAndSet(false, true)) { - List reverse = new ArrayList<>(providers.values()); - for (int index = reverse.size() - 1; index >= 0; index--) { - reverse.get(index).close(); - } + closeInReverse(providers); } } } diff --git a/src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/config/RoutingObjectMutationAdapter.java b/src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/config/RoutingObjectMutationAdapter.java index 57723eb8..e00d44e7 100644 --- a/src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/config/RoutingObjectMutationAdapter.java +++ b/src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/config/RoutingObjectMutationAdapter.java @@ -29,6 +29,7 @@ import dev.caskeleton.application.objectstorage.model.ObjectMutationOutcome; import dev.caskeleton.application.objectstorage.model.ObjectMutationReceipt; import dev.caskeleton.application.objectstorage.model.ObjectOperationError; import dev.caskeleton.application.objectstorage.model.ObjectOperationResolution; +import dev.caskeleton.application.objectstorage.model.ObjectPublicationRequirement; import dev.caskeleton.application.objectstorage.model.ObjectPublicationState; import dev.caskeleton.application.objectstorage.model.ObjectPublishReceipt; import dev.caskeleton.application.objectstorage.port.ManagedObjectPublicationPort; @@ -434,6 +435,12 @@ public final class RoutingObjectMutationAdapter private static void requirePolicy( ObjectPublishRequest request, CompiledObjectStorageDestination destination) { + // Managed publish has no scan step: it would publish unscanned bytes as if they were clean. + if (destination.policySnapshot().publicationRequirement() + == ObjectPublicationRequirement.SCAN_CLEAN) { + throw new IllegalArgumentException( + "scan-gated destinations publish only through staged finalize"); + } if (request.publicationRequirement() != destination.policySnapshot().publicationRequirement() || request.retentionRequirement() != destination.policySnapshot().retentionRequirement() || request.encryptionRequirement() != destination.policySnapshot().encryptionRequirement() diff --git a/src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/config/RoutingObjectReadAdapter.java b/src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/config/RoutingObjectReadAdapter.java index 24ed0f52..5e92919c 100644 --- a/src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/config/RoutingObjectReadAdapter.java +++ b/src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/config/RoutingObjectReadAdapter.java @@ -13,6 +13,7 @@ import dev.caskeleton.application.objectstorage.identity.ObjectId; import dev.caskeleton.application.objectstorage.identity.ObjectReference; import dev.caskeleton.application.objectstorage.model.ObjectDescriptor; import dev.caskeleton.application.objectstorage.model.ObjectDigestVerification; +import dev.caskeleton.application.objectstorage.model.ObjectPublicationRequirement; import dev.caskeleton.application.objectstorage.model.ObjectPublicationState; import dev.caskeleton.application.objectstorage.model.ObjectReadReceipt; import dev.caskeleton.application.objectstorage.model.ObjectScanState; @@ -50,7 +51,11 @@ public final class RoutingObjectReadAdapter implements ObjectInspectionPort, Obj manifest.mediaType(), Optional.empty(), ObjectPublicationState.PUBLISHED, - ObjectScanState.NOT_REQUIRED, + // Finalize publishes a scan-gated destination only after an exact CLEAN verdict. + loaded.runtime().destination().policySnapshot().publicationRequirement() + == ObjectPublicationRequirement.SCAN_CLEAN + ? ObjectScanState.CLEAN + : ObjectScanState.NOT_REQUIRED, loaded.runtime().destination().policySnapshot().encryptionRequirement(), loaded.runtime().destination().policySnapshot().retentionRequirement(), manifest.updatedAt(), diff --git a/src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/config/RoutingObjectScanMaintenanceAdapter.java b/src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/config/RoutingObjectScanMaintenanceAdapter.java index 85aaa9a8..a76d50f5 100644 --- a/src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/config/RoutingObjectScanMaintenanceAdapter.java +++ b/src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/config/RoutingObjectScanMaintenanceAdapter.java @@ -89,18 +89,21 @@ public final class RoutingObjectScanMaintenanceAdapter implements ObjectScanMain .store() .compareAndSet( loaded.stageKey(), new ObjectControlMutation(loaded.stored().version(), verdict)); - ObjectOperationRecord operation = - loaded - .store() - .read( - ObjectControlKeyCodec.operation( - loaded.runtime().destination().route(), request.operationKey())) - .map(ObjectControlStore.StoredControlRecord::record) - .filter(ObjectOperationRecord.class::isInstance) - .map(ObjectOperationRecord.class::cast) - .orElseThrow(() -> new IllegalStateException("scan operation is absent")); + } + ObjectOperationRecord operation = + loaded + .store() + .read( + ObjectControlKeyCodec.operation( + loaded.runtime().destination().route(), request.operationKey())) + .map(ObjectControlStore.StoredControlRecord::record) + .filter(ObjectOperationRecord.class::isInstance) + .map(ObjectOperationRecord.class::cast) + .orElseThrow(() -> new IllegalStateException("scan operation is absent")); + // Also on a replayed verdict: a crash after the stage CAS left the operation SCAN_PENDING. + if (operation.stablePhase() == PublicationOperationState.SCAN_PENDING) { ObjectOperationKernel kernel = new ObjectOperationKernel(loaded.store()); - if (request.verdict() == ObjectScanState.CLEAN) { + if (verdict.scanState() == ObjectScanState.CLEAN) { kernel.advancePublication( operation, PublicationOperationState.SCAN_CLEAN, diff --git a/src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/control/ObjectPublicationHandoffRecord.java b/src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/control/ObjectPublicationHandoffRecord.java index 6b410d76..4ea6bd6a 100644 --- a/src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/control/ObjectPublicationHandoffRecord.java +++ b/src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/control/ObjectPublicationHandoffRecord.java @@ -116,7 +116,13 @@ public record ObjectPublicationHandoffRecord( now); } + /** + * Releases the claim; the same claimant/fence releasing again gets this record back unchanged. + */ public ObjectPublicationHandoffRecord release(long expectedFence, String claimant, Instant now) { + if (released && expectedFence == fence && claimantDigest.equals(digest(claimant))) { + return this; + } requireOwner(expectedFence, claimant, now); return new ObjectPublicationHandoffRecord( schemaVersion, @@ -133,7 +139,11 @@ public record ObjectPublicationHandoffRecord( now); } + /** Authorizes abort; authorizing the same fence again gets this record back unchanged. */ public ObjectPublicationHandoffRecord authorizeAbort(long expectedFence, Instant now) { + if (abortAuthorized && expectedFence == fence) { + return this; + } if (expectedFence != fence || (!released && leaseExpiresAt.isAfter(now))) { throw new IllegalStateException("active or stale handoff cannot authorize abort"); } diff --git a/src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/filesystem/LocalDevObjectControlStore.java b/src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/filesystem/LocalDevObjectControlStore.java index 4c293490..f7a931c9 100644 --- a/src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/filesystem/LocalDevObjectControlStore.java +++ b/src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/filesystem/LocalDevObjectControlStore.java @@ -47,20 +47,33 @@ public final class LocalDevObjectControlStore implements ObjectControlStore { } } + /** + * Writes the whole record to a private temporary file, forces it, and only then links it into + * place. A concurrent reader sees no file or the complete record, and a crash mid-write leaves an + * orphan under {@code .tmp} instead of a truncated record that decodes as corrupt forever. + */ @Override public StoredControlRecord create(String key, ObjectControlRecord record) { Path target = pathGuard.resolveControl(key, true); byte[] encoded = codec.encode(record); - try (FileChannel channel = - FileChannel.open(target, StandardOpenOption.CREATE_NEW, StandardOpenOption.WRITE)) { - writeFully(channel, encoded); - channel.force(true); + Path temporary = null; + try { + temporary = pathGuard.createTemporaryFile(); + try (FileChannel channel = + FileChannel.open( + temporary, StandardOpenOption.TRUNCATE_EXISTING, StandardOpenOption.WRITE)) { + writeFully(channel, encoded); + channel.force(true); + } + Files.createLink(target, temporary); LocalObjectPathGuard.applyFilePermissions(target, false); return new StoredControlRecord(ObjectControlVersion.of(codec.sha256Hex(encoded)), record); } catch (FileAlreadyExistsException exception) { throw new ObjectControlConflictException("local control record already exists"); } catch (IOException exception) { throw new IllegalStateException("local control create failed", exception); + } finally { + deleteTemporary(temporary); } } @@ -93,17 +106,22 @@ public final class LocalDevObjectControlStore implements ObjectControlStore { } catch (IOException exception) { throw new IllegalStateException("local control CAS failed", exception); } finally { - if (temporary != null) { - try { - Files.deleteIfExists(temporary); - } catch (IOException ignored) { - // Report-first local reconciliation owns any bounded .tmp orphan. - } - } + deleteTemporary(temporary); } } } + private static void deleteTemporary(Path temporary) { + if (temporary == null) { + return; + } + try { + Files.deleteIfExists(temporary); + } catch (IOException ignored) { + // Report-first local reconciliation owns any bounded .tmp orphan. + } + } + private static Object[] lockStripes() { Object[] stripes = new Object[LOCK_STRIPES]; java.util.Arrays.setAll(stripes, ignored -> new Object()); diff --git a/src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/kernel/ObjectPublicationHandoffService.java b/src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/kernel/ObjectPublicationHandoffService.java index 4165d8fd..925b2c7a 100644 --- a/src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/kernel/ObjectPublicationHandoffService.java +++ b/src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/kernel/ObjectPublicationHandoffService.java @@ -94,8 +94,7 @@ public final class ObjectPublicationHandoffService implements ObjectPublicationH ObjectControlStore.StoredControlRecord stored = loadHandoff(state); ObjectPublicationHandoffRecord released = handoff(stored).release(request.fence(), request.claimant(), clock.instant()); - state.store().compareAndSet(state.key(), new ObjectControlMutation(stored.version(), released)); - return mutation(request.operationKey(), ObjectMutationOutcome.APPLIED); + return mutation(request.operationKey(), writeUnlessReplayed(state, stored, released)); } @Override @@ -120,10 +119,21 @@ public final class ObjectPublicationHandoffService implements ObjectPublicationH ObjectControlStore.StoredControlRecord stored = loadHandoff(state); ObjectPublicationHandoffRecord authorized = handoff(stored).authorizeAbort(authorization.handoffFence(), clock.instant()); + return mutation(authorization.operationKey(), writeUnlessReplayed(state, stored, authorized)); + } + + /** An unchanged record is a replay of a transition already durable: nothing to write. */ + private static ObjectMutationOutcome writeUnlessReplayed( + RuntimeState state, + ObjectControlStore.StoredControlRecord stored, + ObjectPublicationHandoffRecord replacement) { + if (replacement.equals(stored.record())) { + return ObjectMutationOutcome.REPLAYED; + } state .store() - .compareAndSet(state.key(), new ObjectControlMutation(stored.version(), authorized)); - return mutation(authorization.operationKey(), ObjectMutationOutcome.APPLIED); + .compareAndSet(state.key(), new ObjectControlMutation(stored.version(), replacement)); + return ObjectMutationOutcome.APPLIED; } private RuntimeState state( diff --git a/src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/kernel/StagedObjectPublicationKernel.java b/src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/kernel/StagedObjectPublicationKernel.java index 1ae9e5b6..2c2a4250 100644 --- a/src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/kernel/StagedObjectPublicationKernel.java +++ b/src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/kernel/StagedObjectPublicationKernel.java @@ -6,6 +6,7 @@ import dev.caskeleton.adapter.outbound.objectstorage.codec.ObjectDataKeyCodec; import dev.caskeleton.adapter.outbound.objectstorage.codec.ObjectHandleCodec; import dev.caskeleton.adapter.outbound.objectstorage.codec.ObjectRequestFingerprintCodec; import dev.caskeleton.adapter.outbound.objectstorage.config.ObjectStorageCapabilityAssembler; +import dev.caskeleton.adapter.outbound.objectstorage.control.ObjectControlConflictException; import dev.caskeleton.adapter.outbound.objectstorage.control.ObjectControlMutation; import dev.caskeleton.adapter.outbound.objectstorage.control.ObjectControlStore; import dev.caskeleton.adapter.outbound.objectstorage.control.ObjectOperationRecord; @@ -75,12 +76,7 @@ public final class StagedObjectPublicationKernel { ObjectStagedObjectRecord existing = loadStage(objectId); if (existing != null) { requireExact(existing, request.contentIdentity()); - return new ObjectStageReceipt( - request.operationKey(), - existing.stageHandle(), - existing.exactVersion(), - existing.contentIdentity(), - ObjectMutationOutcome.REPLAYED); + return stageReceipt(request, existing, ObjectMutationOutcome.REPLAYED); } ObjectOperationRecord operation = reservation.record(); if (operation.stablePhase() == PublicationOperationState.RESERVED) { @@ -88,9 +84,56 @@ public final class StagedObjectPublicationKernel { operations.advancePublication( operation, PublicationOperationState.DATA_UPLOAD_IN_PROGRESS, null, clock.instant()); } - if (operation.stablePhase() != PublicationOperationState.DATA_UPLOAD_IN_PROGRESS) { + ObjectStorageProvider.StoredData stored; + if (operation.stablePhase() == PublicationOperationState.DATA_UPLOAD_IN_PROGRESS) { + stored = upload(request, producer, fingerprint, dataKey, operations, operation); + } else if (operation.stablePhase() == PublicationOperationState.DATA_UPLOADED) { + // The operation record is the source of truth: the upload is durable, only the stage record + // a crash cut off is missing. Rebuild it from the stored object instead of refusing. + stored = + runtime + .providerFactory() + .provider() + .inspect(dataKey) + .orElseThrow(() -> new IllegalStateException("uploaded stage data is absent")); + } else { throw new IllegalStateException("stage operation is not uploadable"); } + if (!stored.contentIdentity().equals(request.contentIdentity())) { + throw new IllegalStateException("staged content conflicts with declared identity"); + } + ObjectStagedObjectRecord staged = + ObjectStagedObjectRecord.staged( + request.operationKey(), + ObjectHandleCodec.stage(runtime.destination().route(), objectId), + objectId, + dataKey, + stored.exactVersion(), + stored.contentIdentity(), + request.declaredMediaType(), + request.publicationRequirement(), + clock.instant()); + try { + control().create(stageKey(staged.stageHandle()), staged); + } catch (ObjectControlConflictException concurrentRetry) { + ObjectStagedObjectRecord winner = loadStage(objectId); + if (winner == null) { + throw concurrentRetry; + } + requireExact(winner, request.contentIdentity()); + return stageReceipt(request, winner, ObjectMutationOutcome.REPLAYED); + } + return stageReceipt(request, staged, ObjectMutationOutcome.APPLIED); + } + + private ObjectStorageProvider.StoredData upload( + ObjectStageRequest request, + ObjectContentProducer producer, + String fingerprint, + String dataKey, + ObjectOperationKernel operations, + ObjectOperationRecord uploading) { + ObjectOperationRecord operation = uploading; ObjectStorageProviderOperation providerOperation = new ObjectStorageProviderOperation( request.operationKey(), @@ -125,24 +168,17 @@ public final class StagedObjectPublicationKernel { PublicationOperationState.DATA_UPLOADED, stored.contentIdentity(), clock.instant()); - ObjectStagedObjectRecord staged = - ObjectStagedObjectRecord.staged( - request.operationKey(), - ObjectHandleCodec.stage(runtime.destination().route(), objectId), - objectId, - dataKey, - stored.exactVersion(), - stored.contentIdentity(), - request.declaredMediaType(), - request.publicationRequirement(), - clock.instant()); - control().create(stageKey(staged.stageHandle()), staged); + return stored; + } + + private static ObjectStageReceipt stageReceipt( + ObjectStageRequest request, ObjectStagedObjectRecord staged, ObjectMutationOutcome outcome) { return new ObjectStageReceipt( request.operationKey(), staged.stageHandle(), staged.exactVersion(), staged.contentIdentity(), - ObjectMutationOutcome.APPLIED); + outcome); } public ObjectVerificationReceipt verifyIntegrity(ObjectVerifyRequest request) { @@ -153,31 +189,43 @@ public final class StagedObjectPublicationKernel { if (!stage.exactVersion().equals(request.exactVersion())) { throw new IllegalArgumentException("stage version conflicts"); } - if (stage.integrityVerified()) { - return verification(stage, ObjectMutationOutcome.REPLAYED); + ObjectStagedObjectRecord verified = stage; + ObjectMutationOutcome outcome = ObjectMutationOutcome.REPLAYED; + if (!stage.integrityVerified()) { + verified = integrity.verify(stage, runtime.providerFactory().provider(), clock.instant()); + control() + .compareAndSet( + stageKey(stage.stageHandle()), new ObjectControlMutation(stored.version(), verified)); + outcome = ObjectMutationOutcome.APPLIED; } - ObjectStagedObjectRecord verified = - integrity.verify(stage, runtime.providerFactory().provider(), clock.instant()); - control() - .compareAndSet( - stageKey(stage.stageHandle()), new ObjectControlMutation(stored.version(), verified)); - ObjectOperationRecord operation = loadOperation(request.operationKey()); + // Also on replay: a crash after the stage CAS left the operation behind the stage record. + advanceVerifiedOperation(request.operationKey(), verified); + return verification(verified, outcome); + } + + private void advanceVerifiedOperation( + dev.caskeleton.application.objectstorage.identity.ObjectOperationKey operationKey, + ObjectStagedObjectRecord verified) { + ObjectOperationRecord operation = loadOperation(operationKey); ObjectOperationKernel kernel = new ObjectOperationKernel(control()); - operation = - kernel.advancePublication( - operation, - PublicationOperationState.INTEGRITY_VERIFIED, - verified.contentIdentity(), - clock.instant()); - if (verified.publicationRequirement() - == dev.caskeleton.application.objectstorage.model.ObjectPublicationRequirement.SCAN_CLEAN) { + if (operation.stablePhase() == PublicationOperationState.DATA_UPLOADED) { + operation = + kernel.advancePublication( + operation, + PublicationOperationState.INTEGRITY_VERIFIED, + verified.contentIdentity(), + clock.instant()); + } + if (operation.stablePhase() == PublicationOperationState.INTEGRITY_VERIFIED + && verified.publicationRequirement() + == dev.caskeleton.application.objectstorage.model.ObjectPublicationRequirement + .SCAN_CLEAN) { kernel.advancePublication( operation, PublicationOperationState.SCAN_PENDING, verified.contentIdentity(), clock.instant()); } - return verification(verified, ObjectMutationOutcome.APPLIED); } public ObjectPublishReceipt finalizePublication(ObjectFinalizeRequest request) { @@ -210,16 +258,21 @@ public final class StagedObjectPublicationKernel { .SCAN_CLEAN ? PublicationOperationState.SCAN_CLEAN : PublicationOperationState.INTEGRITY_VERIFIED; - if (operation.stablePhase() != required) { + ObjectOperationKernel kernel = new ObjectOperationKernel(control()); + if (operation.stablePhase() == required) { + operation = + kernel.advancePublication( + operation, + PublicationOperationState.REFERENCE_PUBLISH_IN_PROGRESS, + stage.contentIdentity(), + clock.instant()); + } else if (operation.stablePhase() + != PublicationOperationState.REFERENCE_PUBLISH_IN_PROGRESS) { throw new IllegalStateException("staged operation is not finalizable"); } - ObjectOperationKernel kernel = new ObjectOperationKernel(control()); - operation = - kernel.advancePublication( - operation, - PublicationOperationState.REFERENCE_PUBLISH_IN_PROGRESS, - stage.contentIdentity(), - clock.instant()); + // REFERENCE_PUBLISH_IN_PROGRESS here is a retry after a crash mid-publication: the reference + // writes below are create-or-require-same with the stage's own timestamp, so re-running + // them converges instead of conflicting. reference = references.publish( runtime.destination().route(), @@ -260,25 +313,28 @@ public final class StagedObjectPublicationKernel { || !stage.exactVersion().equals(request.authorization().exactVersion())) { throw new IllegalStateException("abort authorization is stale or conflicts"); } + ObjectStorageProvider.RetireOperation retirement = + new ObjectStorageProvider.RetireOperation(stage.canonicalDataKey(), stage.exactVersion()); + if (operation.stablePhase() == PublicationOperationState.ABORTED) { + // A retry after ABORTED became durable: finish a retirement a crash may have cut short. An + // object already gone is the expected answer, not a failure. + runtime.providerFactory().provider().retire(retirement); + return abortReceipt(request, ObjectMutationOutcome.REPLAYED); + } // ABORTED is recorded by CAS before any byte is deleted: a finalize racing this abort can no // longer advance the operation, and a finalize that already advanced it makes this CAS fail. new ObjectOperationKernel(control()) .terminate(operation, PublicationOperationState.ABORTED, clock.instant()); - boolean retired = - runtime - .providerFactory() - .provider() - .retire( - new ObjectStorageProvider.RetireOperation( - stage.canonicalDataKey(), stage.exactVersion())); - if (!retired) { + if (!runtime.providerFactory().provider().retire(retirement)) { throw new IllegalStateException("staged provider object could not be retired"); } + return abortReceipt(request, ObjectMutationOutcome.APPLIED); + } + + private ObjectMutationReceipt abortReceipt( + ObjectAbortRequest request, ObjectMutationOutcome outcome) { return new ObjectMutationReceipt( - request.operationKey(), - ObjectMutationOutcome.APPLIED, - ObjectOperationError.NONE, - clock.instant()); + request.operationKey(), outcome, ObjectOperationError.NONE, clock.instant()); } private ObjectStorageProvider.StoredData resolveOrCreate( diff --git a/src/adapter/outbound/objectstorage/src/test/java/dev/caskeleton/adapter/outbound/objectstorage/config/ObjectStorageCapabilityAssemblerTest.java b/src/adapter/outbound/objectstorage/src/test/java/dev/caskeleton/adapter/outbound/objectstorage/config/ObjectStorageCapabilityAssemblerTest.java new file mode 100644 index 00000000..42f2f894 --- /dev/null +++ b/src/adapter/outbound/objectstorage/src/test/java/dev/caskeleton/adapter/outbound/objectstorage/config/ObjectStorageCapabilityAssemblerTest.java @@ -0,0 +1,99 @@ +package dev.caskeleton.adapter.outbound.objectstorage.config; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.catchThrowable; + +import dev.caskeleton.adapter.outbound.objectstorage.filesystem.FilesystemLocalDevProviderContribution; +import dev.caskeleton.adapter.outbound.objectstorage.provider.ObjectStorageProviderDescriptor; +import java.nio.file.Path; +import java.util.List; +import java.util.Map; +import java.util.Set; +import java.util.concurrent.CopyOnWriteArrayList; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; +import org.springframework.util.unit.DataSize; + +class ObjectStorageCapabilityAssemblerTest { + + @TempDir Path root; + + @Test + void closeReleasesProvidersInReverseCreationOrderAndKeepsEveryFailure() { + // given + List created = new CopyOnWriteArrayList<>(); + ObjectStorageProviderContribution contribution = new FailingCloseContribution(created); + ObjectStorageCapabilityAssembler.AssembledCapability capability = + new ObjectStorageCapabilityAssembler( + List.of(contribution), + new ObjectStorageBindingCompiler(List.of(contribution), Set.of("test"), false)) + .assemble(twoProviders(root)); + + // when + Throwable thrown = catchThrowable(capability::close); + + // then + assertThat(thrown) + .hasMessage("close failed: " + created.get(1)) + .satisfies( + failure -> + assertThat(failure.getSuppressed()) + .extracting(Throwable::getMessage) + .containsExactly("close failed: " + created.get(0))); + } + + private static ObjectStorageCapabilitySettings twoProviders(Path root) { + return new ObjectStorageCapabilitySettings( + true, + "one", + Map.of("a", provider(root.resolve("a")), "b", provider(root.resolve("b"))), + Map.of("one", destination("a", "0123456789ab"), "two", destination("b", "0123456789ac")), + null); + } + + private static ObjectStorageProviderSettings provider(Path root) { + return new ObjectStorageProviderSettings( + "filesystem-local-dev", + "jdk-21", + root.toString(), + DataSize.ofBytes(1024), + DataSize.ofBytes(64), + null); + } + + private static ObjectStorageDestinationSettings destination(String provider, String route) { + return new ObjectStorageDestinationSettings( + provider, route, "binding-v1", "policy-v1", null, null, null, null, null, null); + } + + /** Local provider whose close always fails, recording the order providers were created in. */ + private record FailingCloseContribution(List created) + implements ObjectStorageProviderContribution { + + private static final FilesystemLocalDevProviderContribution LOCAL = + new FilesystemLocalDevProviderContribution(); + + @Override + public String providerType() { + return LOCAL.providerType(); + } + + @Override + public ObjectStorageProviderDescriptor describe(ObjectStorageProviderSettings settings) { + return LOCAL.describe(settings); + } + + @Override + public SelectedObjectStorageProviderFactory create(CompiledObjectStorageProvider provider) { + SelectedObjectStorageProviderFactory real = LOCAL.create(provider); + created.add(provider.providerId()); + return new SelectedObjectStorageProviderFactory( + real.provider(), + real.controlStore(), + () -> { + real.close(); + throw new IllegalStateException("close failed: " + provider.providerId()); + }); + } + } +} diff --git a/src/adapter/outbound/objectstorage/src/test/java/dev/caskeleton/adapter/outbound/objectstorage/filesystem/LocalDevObjectStorageRecoveryTest.java b/src/adapter/outbound/objectstorage/src/test/java/dev/caskeleton/adapter/outbound/objectstorage/filesystem/LocalDevObjectStorageRecoveryTest.java index 91eb7028..7d2aad27 100644 --- a/src/adapter/outbound/objectstorage/src/test/java/dev/caskeleton/adapter/outbound/objectstorage/filesystem/LocalDevObjectStorageRecoveryTest.java +++ b/src/adapter/outbound/objectstorage/src/test/java/dev/caskeleton/adapter/outbound/objectstorage/filesystem/LocalDevObjectStorageRecoveryTest.java @@ -101,6 +101,60 @@ class LocalDevObjectStorageRecoveryTest { assertThat(physical).exists(); } + @Test + void aConcurrentReaderNeverSeesAPartiallyCreatedControlRecord() throws Exception { + // given + LocalDevObjectControlStore store = + new LocalDevObjectControlStore( + new LocalObjectPathGuard(root), new CanonicalJsonObjectControlRecordCodec()); + java.util.List readFailures = new java.util.concurrent.CopyOnWriteArrayList<>(); + java.util.concurrent.ExecutorService readers = + java.util.concurrent.Executors.newSingleThreadExecutor(); + + // when + try { + for (int index = 0; index < 300; index++) { + String key = "control/v1/references/0123456789ab/aa/reference-" + index; + java.util.concurrent.CountDownLatch started = new java.util.concurrent.CountDownLatch(1); + java.util.concurrent.Future reader = + readers.submit( + () -> { + started.countDown(); + while (true) { + try { + if (store.read(key).isPresent()) { + return; + } + } catch (RuntimeException failure) { + readFailures.add(failure); + return; + } + } + }); + started.await(); + store.create(key, referenceRecord()); + reader.get(1, java.util.concurrent.TimeUnit.MINUTES); + } + } finally { + readers.shutdownNow(); + } + + // then + assertThat(readFailures).isEmpty(); + } + + private static ObjectReferenceRecord referenceRecord() { + return new ObjectReferenceRecord( + 1, + "reference", + 1, + ObjectReference.parse("osr1.0123456789ab.0123456789abcdefghjkmnpqrs.d53d9429ac"), + ObjectId.parse("0123456789abcdefghjkmnpqrs"), + ObjectVersionToken.parse("osv1.0123456789ab.0123456789abcdefghjkmnpqrs.6678c6821f"), + PublishedReferenceState.PUBLISHED, + Instant.EPOCH); + } + @Test void exclusiveCreateRaceHasOneWinner() throws Exception { LocalDevObjectStorageProvider provider = diff --git a/src/adapter/outbound/objectstorage/src/test/java/dev/caskeleton/adapter/outbound/objectstorage/kernel/StagedObjectPublicationLifecycleTest.java b/src/adapter/outbound/objectstorage/src/test/java/dev/caskeleton/adapter/outbound/objectstorage/kernel/StagedObjectPublicationLifecycleTest.java index 7e1a5c07..9b5a277a 100644 --- a/src/adapter/outbound/objectstorage/src/test/java/dev/caskeleton/adapter/outbound/objectstorage/kernel/StagedObjectPublicationLifecycleTest.java +++ b/src/adapter/outbound/objectstorage/src/test/java/dev/caskeleton/adapter/outbound/objectstorage/kernel/StagedObjectPublicationLifecycleTest.java @@ -3,14 +3,26 @@ package dev.caskeleton.adapter.outbound.objectstorage.kernel; import static org.assertj.core.api.Assertions.assertThat; import static org.assertj.core.api.Assertions.catchThrowable; +import dev.caskeleton.adapter.outbound.objectstorage.codec.ObjectControlKeyCodec; +import dev.caskeleton.adapter.outbound.objectstorage.config.CompiledObjectStorageProvider; import dev.caskeleton.adapter.outbound.objectstorage.config.ObjectStorageBindingCompiler; import dev.caskeleton.adapter.outbound.objectstorage.config.ObjectStorageCapabilityAssembler; import dev.caskeleton.adapter.outbound.objectstorage.config.ObjectStorageCapabilitySettings; import dev.caskeleton.adapter.outbound.objectstorage.config.ObjectStorageDestinationSettings; +import dev.caskeleton.adapter.outbound.objectstorage.config.ObjectStorageProviderContribution; import dev.caskeleton.adapter.outbound.objectstorage.config.ObjectStorageProviderSettings; import dev.caskeleton.adapter.outbound.objectstorage.config.RoutingObjectMutationAdapter; import dev.caskeleton.adapter.outbound.objectstorage.config.RoutingObjectReadAdapter; +import dev.caskeleton.adapter.outbound.objectstorage.config.RoutingObjectScanMaintenanceAdapter; +import dev.caskeleton.adapter.outbound.objectstorage.config.SelectedObjectStorageProviderFactory; +import dev.caskeleton.adapter.outbound.objectstorage.control.ObjectControlMutation; +import dev.caskeleton.adapter.outbound.objectstorage.control.ObjectControlRecord; +import dev.caskeleton.adapter.outbound.objectstorage.control.ObjectControlStore; +import dev.caskeleton.adapter.outbound.objectstorage.control.ObjectManifestRecord; +import dev.caskeleton.adapter.outbound.objectstorage.control.ObjectOperationRecord; +import dev.caskeleton.adapter.outbound.objectstorage.control.ObjectStagedObjectRecord; import dev.caskeleton.adapter.outbound.objectstorage.filesystem.FilesystemLocalDevProviderContribution; +import dev.caskeleton.adapter.outbound.objectstorage.provider.ObjectStorageProviderDescriptor; import dev.caskeleton.application.objectstorage.content.CancellationView; import dev.caskeleton.application.objectstorage.identity.ObjectDestinationId; import dev.caskeleton.application.objectstorage.identity.ObjectOperationEpoch; @@ -19,22 +31,28 @@ import dev.caskeleton.application.objectstorage.identity.ObjectOperationKey; import dev.caskeleton.application.objectstorage.identity.ObjectReference; import dev.caskeleton.application.objectstorage.model.ObjectCapabilityRequirement; import dev.caskeleton.application.objectstorage.model.ObjectContentIdentity; +import dev.caskeleton.application.objectstorage.model.ObjectDescriptor; import dev.caskeleton.application.objectstorage.model.ObjectDigest; import dev.caskeleton.application.objectstorage.model.ObjectDigestVerification; import dev.caskeleton.application.objectstorage.model.ObjectEncryptionRequirement; import dev.caskeleton.application.objectstorage.model.ObjectHandoffReceipt; import dev.caskeleton.application.objectstorage.model.ObjectMediaType; +import dev.caskeleton.application.objectstorage.model.ObjectMutationOutcome; +import dev.caskeleton.application.objectstorage.model.ObjectMutationReceipt; import dev.caskeleton.application.objectstorage.model.ObjectPublicationRequirement; import dev.caskeleton.application.objectstorage.model.ObjectPublishReceipt; import dev.caskeleton.application.objectstorage.model.ObjectReadRange; import dev.caskeleton.application.objectstorage.model.ObjectRetentionRequirement; +import dev.caskeleton.application.objectstorage.model.ObjectScanState; import dev.caskeleton.application.objectstorage.model.ObjectStageReceipt; import dev.caskeleton.application.objectstorage.request.ObjectAbortAuthorization; import dev.caskeleton.application.objectstorage.request.ObjectAbortRequest; import dev.caskeleton.application.objectstorage.request.ObjectFinalizeRequest; import dev.caskeleton.application.objectstorage.request.ObjectHandoffClaimRequest; import dev.caskeleton.application.objectstorage.request.ObjectHandoffReleaseRequest; +import dev.caskeleton.application.objectstorage.request.ObjectPublishRequest; import dev.caskeleton.application.objectstorage.request.ObjectReadRequest; +import dev.caskeleton.application.objectstorage.request.ObjectScanVerdictRequest; import dev.caskeleton.application.objectstorage.request.ObjectStageRequest; import dev.caskeleton.application.objectstorage.request.ObjectVerifyRequest; import dev.caskeleton.application.outbound.CallBudget; @@ -50,37 +68,52 @@ import java.util.List; import java.util.Map; import java.util.Optional; import java.util.Set; +import java.util.function.Predicate; +import org.assertj.core.api.ThrowableAssert.ThrowingCallable; import org.junit.jupiter.api.AfterEach; import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Nested; import org.junit.jupiter.api.Test; import org.junit.jupiter.api.io.TempDir; import org.springframework.util.unit.DataSize; -/** Staged publication over the real local-dev provider: stage, verify, claim, finalize, abort. */ +/** + * Staged publication over the real local-dev provider: stage, verify, scan verdict, claim, + * finalize, abort. A crash between two control writes is modelled by failing the second write. + */ class StagedObjectPublicationLifecycleTest { private static final Instant START = Instant.parse("2026-09-25T00:00:00Z"); + private static final Instant EXPIRED = START.plusSeconds(31); private static final Duration LEASE = Duration.ofSeconds(30); private static final String CLAIMANT = "poster-worker-a"; - private static final ObjectDestinationId DESTINATION = ObjectDestinationId.of("poster"); - private static final ObjectOperationKey OPERATION = + private static final ObjectOperationKey POSTER = new ObjectOperationKey( - DESTINATION, ObjectOperationEpoch.of("epoch-a"), ObjectOperationId.of("upload-1")); + ObjectDestinationId.of("poster"), + ObjectOperationEpoch.of("epoch-a"), + ObjectOperationId.of("upload-1")); + private static final ObjectOperationKey SCANNED = + new ObjectOperationKey( + ObjectDestinationId.of("scanned"), + ObjectOperationEpoch.of("epoch-a"), + ObjectOperationId.of("upload-2")); private static final byte[] CONTENT = "staged-poster-bytes".getBytes(StandardCharsets.UTF_8); private static final ObjectContentIdentity IDENTITY = new ObjectContentIdentity(CONTENT.length, ObjectDigest.sha256(CONTENT)); @TempDir Path root; + private final CrashingControlStore control = new CrashingControlStore(); private ObjectStorageCapabilityAssembler.AssembledCapability capability; @BeforeEach void assembleLocalCapability() { - FilesystemLocalDevProviderContribution local = new FilesystemLocalDevProviderContribution(); + ObjectStorageProviderContribution local = + new CrashInjectingContribution(new FilesystemLocalDevProviderContribution(), control); capability = new ObjectStorageCapabilityAssembler( List.of(local), - new ObjectStorageBindingCompiler(List.of(local), Set.of("test"), false)) + new ObjectStorageBindingCompiler(List.of(local), Set.of("test"), true)) .assemble(settings(root)); } @@ -89,111 +122,315 @@ class StagedObjectPublicationLifecycleTest { capability.close(); } - @Test - void authorizeAbortIsRejectedOnceTheReferenceIsPublished() { - // given - ObjectStageReceipt stage = stagedAndVerified(); - ObjectHandoffReceipt claim = claim(stage, START); - finalizePublication(stage, claim, START); - handoffsAt(START).releaseClaim(release(stage, claim)); + @Nested + class Stage { - // when - Throwable thrown = - catchThrowable(() -> handoffsAt(START).authorizeAbort(abortAuth(stage, claim))); + @Test + void stageRetriedAfterACrashBeforeTheStageRecordStagesTheObject() { + // given + control.crashOnceBeforeWriting(ObjectStagedObjectRecord.class::isInstance); + crashed(() -> stage(POSTER)); - // then - assertThat(thrown) - .isInstanceOf(IllegalStateException.class) - .hasMessage("published operation cannot authorize abort"); + // when + ObjectStageReceipt retried = stage(POSTER); + + // then + assertThat(retried) + .extracting(ObjectStageReceipt::contentIdentity, ObjectStageReceipt::outcome) + .containsExactly(IDENTITY, ObjectMutationOutcome.APPLIED); + } } - @Test - void abortIsRejectedWhenTheOperationPublishedAfterAuthorization() { - // given - ObjectStageReceipt stage = stagedAndVerified(); - ObjectHandoffReceipt claim = claim(stage, START); - Instant expired = START.plus(LEASE).plusSeconds(1); - handoffsAt(expired).authorizeAbort(abortAuth(stage, claim)); - forcePublished(stage); + @Nested + class FinalizePublication { - // when - Throwable thrown = catchThrowable(() -> mutationsAt(expired).abort(abort(stage, claim))); + @Test + void finalizeAfterAbortWasAuthorizedIsRejected() { + // given + ObjectStageReceipt stage = stagedAndVerified(POSTER); + ObjectHandoffReceipt claim = claim(POSTER, stage, START); + handoffsAt(EXPIRED).authorizeAbort(abortAuth(POSTER, stage, claim)); - // then - assertThat(thrown) - .isInstanceOf(IllegalStateException.class) - .hasMessage("published operation cannot be aborted"); - } + // when + Throwable thrown = catchThrowable(() -> finalizePublication(POSTER, stage, claim, EXPIRED)); - @Test - void rejectedAbortAfterPublicationKeepsThePublishedBytesReadable() { - // given - ObjectStageReceipt stage = stagedAndVerified(); - ObjectHandoffReceipt claim = claim(stage, START); - Instant expired = START.plus(LEASE).plusSeconds(1); - handoffsAt(expired).authorizeAbort(abortAuth(stage, claim)); - ObjectReference reference = forcePublished(stage); - try { - mutationsAt(expired).abort(abort(stage, claim)); - } catch (IllegalStateException rejected) { - // abortIsRejectedWhenTheOperationPublishedAfterAuthorization owns the rejection itself. + // then + assertThat(thrown) + .isInstanceOf(IllegalStateException.class) + .hasMessage("finalize requires the active publication claim"); } - // when - byte[] readBack = read(reference); + @Test + void finalizeSucceedsWhenVerifyWasRetriedAfterACrashBeforeTheOperationAdvanced() { + // given + ObjectStageReceipt stage = stage(POSTER); + control.crashOnceBeforeWriting(phase(PublicationOperationState.INTEGRITY_VERIFIED)); + crashed(() -> verify(POSTER, stage)); + verify(POSTER, stage); + ObjectHandoffReceipt claim = claim(POSTER, stage, START); - // then - assertThat(readBack).containsExactly(CONTENT); + // when + ObjectPublishReceipt published = finalizePublication(POSTER, stage, claim, START); + + // then + assertThat(published.outcome()).isEqualTo(ObjectMutationOutcome.APPLIED); + } + + @Test + void finalizeRetriedAfterACrashInReferencePublicationPublishes() { + // given + ObjectStageReceipt stage = stagedAndVerified(POSTER); + ObjectHandoffReceipt claim = claim(POSTER, stage, START); + control.crashOnceBeforeWriting(ObjectManifestRecord.class::isInstance); + crashed(() -> finalizePublication(POSTER, stage, claim, START)); + + // when + ObjectPublishReceipt retried = finalizePublication(POSTER, stage, claim, START); + + // then + assertThat(retried.outcome()).isEqualTo(ObjectMutationOutcome.APPLIED); + } + + @Test + void finalizeSucceedsWhenTheCleanVerdictWasRetriedAfterACrash() { + // given + ObjectStageReceipt stage = stagedAndVerified(SCANNED); + control.crashOnceBeforeWriting(phase(PublicationOperationState.SCAN_CLEAN)); + crashed(() -> recordCleanVerdict(stage)); + recordCleanVerdict(stage); + ObjectHandoffReceipt claim = claim(SCANNED, stage, START); + + // when + ObjectPublishReceipt published = finalizePublication(SCANNED, stage, claim, START); + + // then + assertThat(published.outcome()).isEqualTo(ObjectMutationOutcome.APPLIED); + } } - @Test - void finalizeAfterAbortWasAuthorizedIsRejected() { - // given - ObjectStageReceipt stage = stagedAndVerified(); - ObjectHandoffReceipt claim = claim(stage, START); - Instant expired = START.plus(LEASE).plusSeconds(1); - handoffsAt(expired).authorizeAbort(abortAuth(stage, claim)); + @Nested + class ReleaseClaim { - // when - Throwable thrown = catchThrowable(() -> finalizePublication(stage, claim, expired)); + @Test + void repeatedReleaseByTheSameClaimantReplays() { + // given + ObjectStageReceipt stage = stagedAndVerified(POSTER); + ObjectHandoffReceipt claim = claim(POSTER, stage, START); + finalizePublication(POSTER, stage, claim, START); + handoffsAt(START).releaseClaim(release(POSTER, stage, claim)); - // then - assertThat(thrown) - .isInstanceOf(IllegalStateException.class) - .hasMessage("finalize requires the active publication claim"); + // when + ObjectMutationReceipt repeated = + handoffsAt(START).releaseClaim(release(POSTER, stage, claim)); + + // then + assertThat(repeated.outcome()).isEqualTo(ObjectMutationOutcome.REPLAYED); + } } - private ObjectStageReceipt stagedAndVerified() { - RoutingObjectMutationAdapter mutations = mutationsAt(START); - ObjectStageReceipt stage = - mutations.stage( + @Nested + class AuthorizeAbort { + + @Test + void authorizeAbortIsRejectedOnceTheReferenceIsPublished() { + // given + ObjectStageReceipt stage = stagedAndVerified(POSTER); + ObjectHandoffReceipt claim = claim(POSTER, stage, START); + finalizePublication(POSTER, stage, claim, START); + handoffsAt(START).releaseClaim(release(POSTER, stage, claim)); + + // when + Throwable thrown = + catchThrowable(() -> handoffsAt(START).authorizeAbort(abortAuth(POSTER, stage, claim))); + + // then + assertThat(thrown) + .isInstanceOf(IllegalStateException.class) + .hasMessage("published operation cannot authorize abort"); + } + + @Test + void repeatedAuthorizeAbortForTheSameFenceReplays() { + // given + ObjectStageReceipt stage = stagedAndVerified(POSTER); + ObjectHandoffReceipt claim = claim(POSTER, stage, START); + handoffsAt(START).releaseClaim(release(POSTER, stage, claim)); + handoffsAt(START).authorizeAbort(abortAuth(POSTER, stage, claim)); + + // when + ObjectMutationReceipt repeated = + handoffsAt(START).authorizeAbort(abortAuth(POSTER, stage, claim)); + + // then + assertThat(repeated.outcome()).isEqualTo(ObjectMutationOutcome.REPLAYED); + } + } + + @Nested + class Abort { + + @Test + void abortIsRejectedWhenTheOperationPublishedAfterAuthorization() { + // given + ObjectStageReceipt stage = stagedAndVerified(POSTER); + ObjectHandoffReceipt claim = claim(POSTER, stage, START); + handoffsAt(EXPIRED).authorizeAbort(abortAuth(POSTER, stage, claim)); + forcePublished(stage); + + // when + Throwable thrown = + catchThrowable(() -> mutationsAt(EXPIRED).abort(abort(POSTER, stage, claim))); + + // then + assertThat(thrown) + .isInstanceOf(IllegalStateException.class) + .hasMessage("published operation cannot be aborted"); + } + + @Test + void rejectedAbortAfterPublicationKeepsThePublishedBytesReadable() { + // given + ObjectStageReceipt stage = stagedAndVerified(POSTER); + ObjectHandoffReceipt claim = claim(POSTER, stage, START); + handoffsAt(EXPIRED).authorizeAbort(abortAuth(POSTER, stage, claim)); + ObjectReference reference = forcePublished(stage); + assertThat(catchThrowable(() -> mutationsAt(EXPIRED).abort(abort(POSTER, stage, claim)))) + .isInstanceOf(IllegalStateException.class); + + // when + byte[] readBack = read(reference); + + // then + assertThat(readBack).containsExactly(CONTENT); + } + + @Test + void repeatedAbortReplays() { + // given + ObjectStageReceipt stage = stagedAndVerified(POSTER); + ObjectHandoffReceipt claim = claim(POSTER, stage, START); + handoffsAt(START).releaseClaim(release(POSTER, stage, claim)); + handoffsAt(START).authorizeAbort(abortAuth(POSTER, stage, claim)); + mutationsAt(START).abort(abort(POSTER, stage, claim)); + + // when + ObjectMutationReceipt repeated = mutationsAt(START).abort(abort(POSTER, stage, claim)); + + // then + assertThat(repeated.outcome()).isEqualTo(ObjectMutationOutcome.REPLAYED); + } + } + + @Nested + class ManagedPublish { + + @Test + void managedPublishToAScanGatedDestinationIsRejected() { + // given + ObjectPublishRequest request = + new ObjectPublishRequest( + SCANNED, + ObjectMediaType.of("image/png"), + IDENTITY, + ObjectPublicationRequirement.SCAN_CLEAN, + ObjectRetentionRequirement.NONE, + ObjectEncryptionRequirement.PROVIDER_MANAGED, + EnumSet.of(ObjectCapabilityRequirement.IMMUTABLE_CREATE), + budget(), + CancellationView.never()); + + // when + Throwable thrown = + catchThrowable( + () -> + mutationsAt(START) + .publish(request, (context, sink) -> sink.write(CONTENT, 0, CONTENT.length))); + + // then + assertThat(thrown) + .isInstanceOf(IllegalArgumentException.class) + .hasMessage("scan-gated destinations publish only through staged finalize"); + } + } + + @Nested + class Inspect { + + @Test + void scanGatedReferenceReportsItsCleanVerdict() { + // given + ObjectStageReceipt stage = stagedAndVerified(SCANNED); + recordCleanVerdict(stage); + ObjectHandoffReceipt claim = claim(SCANNED, stage, START); + ObjectReference reference = finalizePublication(SCANNED, stage, claim, START).reference(); + + // when + Optional inspected = + new RoutingObjectReadAdapter(capability).inspect(reference); + + // then + assertThat(inspected).map(ObjectDescriptor::scanState).contains(ObjectScanState.CLEAN); + } + } + + /** The injected crash hit the write the scenario armed it for. */ + private static void crashed(ThrowingCallable call) { + assertThat(catchThrowable(call)).hasMessage("injected crash before a control write"); + } + + private ObjectStageReceipt stagedAndVerified(ObjectOperationKey operation) { + ObjectStageReceipt stage = stage(operation); + verify(operation, stage); + return stage; + } + + private ObjectStageReceipt stage(ObjectOperationKey operation) { + return mutationsAt(START) + .stage( new ObjectStageRequest( - OPERATION, + operation, ObjectMediaType.of("image/png"), IDENTITY, - ObjectPublicationRequirement.INTEGRITY_VERIFIED, + requirement(operation), ObjectRetentionRequirement.NONE, ObjectEncryptionRequirement.PROVIDER_MANAGED, EnumSet.of(ObjectCapabilityRequirement.IMMUTABLE_CREATE), budget(), CancellationView.never()), (context, sink) -> sink.write(CONTENT, 0, CONTENT.length)); - mutations.verifyIntegrity( - new ObjectVerifyRequest( - OPERATION, - stage.stageHandle(), - stage.exactVersion(), - IDENTITY, - budget(), - CancellationView.never())); - return stage; } - private ObjectHandoffReceipt claim(ObjectStageReceipt stage, Instant now) { + private void verify(ObjectOperationKey operation, ObjectStageReceipt stage) { + mutationsAt(START) + .verifyIntegrity( + new ObjectVerifyRequest( + operation, + stage.stageHandle(), + stage.exactVersion(), + IDENTITY, + budget(), + CancellationView.never())); + } + + private void recordCleanVerdict(ObjectStageReceipt stage) { + new RoutingObjectScanMaintenanceAdapter(capability, Clock.fixed(START, ZoneOffset.UTC)) + .recordScanVerdict( + new ObjectScanVerdictRequest( + SCANNED, + stage.stageHandle(), + stage.exactVersion(), + ObjectOperationId.of("scan-1"), + "scanner-policy-v1", + ObjectScanState.CLEAN, + START)); + } + + private ObjectHandoffReceipt claim( + ObjectOperationKey operation, ObjectStageReceipt stage, Instant now) { return handoffsAt(now) .claimForPublication( new ObjectHandoffClaimRequest( - OPERATION, + operation, stage.stageHandle(), stage.exactVersion(), CLAIMANT, @@ -203,14 +440,17 @@ class StagedObjectPublicationLifecycleTest { } private ObjectPublishReceipt finalizePublication( - ObjectStageReceipt stage, ObjectHandoffReceipt claim, Instant now) { + ObjectOperationKey operation, + ObjectStageReceipt stage, + ObjectHandoffReceipt claim, + Instant now) { return mutationsAt(now) .finalizePublication( new ObjectFinalizeRequest( - OPERATION, + operation, stage.stageHandle(), stage.exactVersion(), - ObjectPublicationRequirement.INTEGRITY_VERIFIED, + requirement(operation), claim.fence(), CLAIMANT, budget(), @@ -223,24 +463,20 @@ class StagedObjectPublicationLifecycleTest { */ private ObjectReference forcePublished(ObjectStageReceipt stage) { ObjectStorageCapabilityAssembler.DestinationRuntime runtime = - capability.destination(DESTINATION); - var control = runtime.providerFactory().controlStore(); - var stored = - control - .read( - dev.caskeleton.adapter.outbound.objectstorage.codec.ObjectControlKeyCodec - .stagedObject(runtime.destination().route(), stage.stageHandle())) - .orElseThrow(); - var staged = - (dev.caskeleton.adapter.outbound.objectstorage.control.ObjectStagedObjectRecord) - stored.record(); - ObjectOperationKernel kernel = new ObjectOperationKernel(control); - var operation = - (dev.caskeleton.adapter.outbound.objectstorage.control.ObjectOperationRecord) + capability.destination(POSTER.destination()); + ObjectStagedObjectRecord staged = + (ObjectStagedObjectRecord) control .read( - dev.caskeleton.adapter.outbound.objectstorage.codec.ObjectControlKeyCodec - .operation(runtime.destination().route(), OPERATION)) + ObjectControlKeyCodec.stagedObject( + runtime.destination().route(), stage.stageHandle())) + .orElseThrow() + .record(); + ObjectOperationKernel kernel = new ObjectOperationKernel(control); + ObjectOperationRecord operation = + (ObjectOperationRecord) + control + .read(ObjectControlKeyCodec.operation(runtime.destination().route(), POSTER)) .orElseThrow() .record(); operation = @@ -283,9 +519,9 @@ class StagedObjectPublicationLifecycleTest { } private static ObjectHandoffReleaseRequest release( - ObjectStageReceipt stage, ObjectHandoffReceipt claim) { + ObjectOperationKey operation, ObjectStageReceipt stage, ObjectHandoffReceipt claim) { return new ObjectHandoffReleaseRequest( - OPERATION, + operation, stage.stageHandle(), claim.fence(), CLAIMANT, @@ -294,20 +530,32 @@ class StagedObjectPublicationLifecycleTest { } private static ObjectAbortAuthorization abortAuth( - ObjectStageReceipt stage, ObjectHandoffReceipt claim) { + ObjectOperationKey operation, ObjectStageReceipt stage, ObjectHandoffReceipt claim) { return new ObjectAbortAuthorization( - OPERATION, stage.stageHandle(), stage.exactVersion(), claim.fence(), START); + operation, stage.stageHandle(), stage.exactVersion(), claim.fence(), START); } - private static ObjectAbortRequest abort(ObjectStageReceipt stage, ObjectHandoffReceipt claim) { + private static ObjectAbortRequest abort( + ObjectOperationKey operation, ObjectStageReceipt stage, ObjectHandoffReceipt claim) { return new ObjectAbortRequest( - OPERATION, + operation, stage.stageHandle(), - abortAuth(stage, claim), + abortAuth(operation, stage, claim), budget(), CancellationView.never()); } + private static ObjectPublicationRequirement requirement(ObjectOperationKey operation) { + return operation.equals(SCANNED) + ? ObjectPublicationRequirement.SCAN_CLEAN + : ObjectPublicationRequirement.INTEGRITY_VERIFIED; + } + + private static Predicate phase(PublicationOperationState phase) { + return record -> + record instanceof ObjectOperationRecord operation && operation.stablePhase() == phase; + } + private RoutingObjectMutationAdapter mutationsAt(Instant now) { return new RoutingObjectMutationAdapter(capability, Clock.fixed(now, ZoneOffset.UTC)); } @@ -335,17 +583,84 @@ class StagedObjectPublicationLifecycleTest { null)), Map.of( "poster", - new ObjectStorageDestinationSettings( - "local", - "0123456789ab", - "binding-v1", - "policy-v1", - null, - null, - null, - null, - null, - null)), + destination("0123456789ab", ObjectPublicationRequirement.INTEGRITY_VERIFIED), + "scanned", + destination("0123456789ac", ObjectPublicationRequirement.SCAN_CLEAN)), null); } + + private static ObjectStorageDestinationSettings destination( + String routeToken, ObjectPublicationRequirement requirement) { + return new ObjectStorageDestinationSettings( + "local", routeToken, "binding-v1", "policy-v1", requirement, null, null, null, null, null); + } + + /** Local provider whose control store is {@link CrashingControlStore}. */ + private record CrashInjectingContribution( + ObjectStorageProviderContribution delegate, CrashingControlStore control) + implements ObjectStorageProviderContribution { + + @Override + public String providerType() { + return delegate.providerType(); + } + + @Override + public Set providerTypes() { + return delegate.providerTypes(); + } + + @Override + public ObjectStorageProviderDescriptor describe(ObjectStorageProviderSettings settings) { + return delegate.describe(settings); + } + + @Override + public Object compileProviderBinding( + String providerId, ObjectStorageProviderSettings settings) { + return delegate.compileProviderBinding(providerId, settings); + } + + @Override + public SelectedObjectStorageProviderFactory create(CompiledObjectStorageProvider provider) { + SelectedObjectStorageProviderFactory real = delegate.create(provider); + control.delegate = real.controlStore(); + return new SelectedObjectStorageProviderFactory(real.provider(), control, real::close); + } + } + + /** Control store that fails the next matching write once, as a crash before it would. */ + private static final class CrashingControlStore implements ObjectControlStore { + + private ObjectControlStore delegate; + private Predicate crashBefore = record -> false; + + void crashOnceBeforeWriting(Predicate write) { + crashBefore = write; + } + + @Override + public Optional read(String key) { + return delegate.read(key); + } + + @Override + public StoredControlRecord create(String key, ObjectControlRecord record) { + crashIfArmed(record); + return delegate.create(key, record); + } + + @Override + public StoredControlRecord compareAndSet(String key, ObjectControlMutation mutation) { + crashIfArmed(mutation.replacement()); + return delegate.compareAndSet(key, mutation); + } + + private void crashIfArmed(ObjectControlRecord record) { + if (crashBefore.test(record)) { + crashBefore = ignored -> false; + throw new IllegalStateException("injected crash before a control write"); + } + } + } } diff --git a/src/adapter/outbound/objectstorage/src/test/java/dev/caskeleton/adapter/outbound/objectstorage/s3/S3AsyncResponseBodyBridgeTest.java b/src/adapter/outbound/objectstorage/src/test/java/dev/caskeleton/adapter/outbound/objectstorage/s3/S3AsyncResponseBodyBridgeTest.java index ae891add..44d69532 100644 --- a/src/adapter/outbound/objectstorage/src/test/java/dev/caskeleton/adapter/outbound/objectstorage/s3/S3AsyncResponseBodyBridgeTest.java +++ b/src/adapter/outbound/objectstorage/src/test/java/dev/caskeleton/adapter/outbound/objectstorage/s3/S3AsyncResponseBodyBridgeTest.java @@ -2,9 +2,11 @@ package dev.caskeleton.adapter.outbound.objectstorage.s3; import static org.assertj.core.api.Assertions.assertThat; import static org.assertj.core.api.Assertions.assertThatThrownBy; +import static org.assertj.core.api.Assertions.catchThrowable; import dev.caskeleton.adapter.outbound.objectstorage.contract.ObjectStorageProviderContract; import dev.caskeleton.adapter.outbound.objectstorage.provider.ObjectStorageProvider; +import dev.caskeleton.adapter.outbound.objectstorage.provider.ObjectStorageProviderException; import dev.caskeleton.application.objectstorage.content.CancellationView; import dev.caskeleton.application.objectstorage.model.ObjectReadRange; import dev.caskeleton.application.outbound.CallBudget; @@ -12,122 +14,137 @@ import java.io.ByteArrayOutputStream; import java.nio.ByteBuffer; import java.time.Duration; import java.util.List; +import java.util.concurrent.ExecutionException; +import java.util.concurrent.ExecutorService; import java.util.concurrent.Executors; import java.util.concurrent.TimeUnit; +import org.junit.jupiter.api.AfterEach; import org.junit.jupiter.api.Test; import software.amazon.awssdk.core.async.SdkPublisher; import software.amazon.awssdk.services.s3.model.GetObjectResponse; +/** + * The bridge checks its call budget on every 50 ms poll, so a budget that can run out while the + * test machine is busy turns load into a failure. Every read here gets a budget that cannot expire + * during a run; the {@code get} timeout only stops a genuine hang from blocking the build. + */ class S3AsyncResponseBodyBridgeTest { + private static final Duration NEVER_EXPIRES = Duration.ofDays(365); + private static final long HANG_GUARD_MINUTES = 1; + + private final ExecutorService worker = + Executors.newSingleThreadExecutor(runnable -> new Thread(runnable, "s3-response-worker")); + + @AfterEach + void stopWorker() { + worker.shutdownNow(); + } + @Test void deliversAnExactBoundedBodyOnTheWorkerAndInvalidatesTheSource() throws Exception { + // given byte[] content = new byte[129]; for (int index = 0; index < content.length; index++) { content[index] = (byte) (index * 7); } - var stored = - new ObjectStorageProvider.StoredData( - ObjectStorageProviderContract.operation(511, content, CancellationView.never()) - .canonicalDataKey(), - new dev.caskeleton.application.objectstorage.model.ObjectContentIdentity( - content.length, - dev.caskeleton.application.objectstorage.model.ObjectDigest.sha256(content)), - S3ObjectEvidenceMapper.versionForKey( - ObjectStorageProviderContract.operation(511, content, CancellationView.never()) - .canonicalDataKey())); - ObjectStorageProvider.ReadOperation operation = - new ObjectStorageProvider.ReadOperation( - stored.canonicalDataKey(), - stored.exactVersion(), - stored.contentIdentity(), - ObjectReadRange.of(0, content.length), - CallBudget.fromNow(Duration.ofSeconds(5)), - CancellationView.never(), - 64, - 1024); ByteArrayOutputStream delivered = new ByteArrayOutputStream(); var escaped = new java.util.concurrent.atomic.AtomicReference< dev.caskeleton.application.objectstorage.content.ObjectChunkSource>(); - var executor = - Executors.newSingleThreadExecutor(runnable -> new Thread(runnable, "s3-response-worker")); - try { - S3AsyncResponseBodyBridge bridge = - new S3AsyncResponseBodyBridge<>( - operation, - (context, source) -> { - assertThat(Thread.currentThread().getName()).startsWith("s3-response-worker"); - escaped.set(source); - byte[] buffer = new byte[31]; - for (int count = source.read(buffer, 0, buffer.length); - count != -1; - count = source.read(buffer, 0, buffer.length)) { - delivered.write(buffer, 0, count); - } - }, - executor, - response -> assertThat(response.contentLength()).isEqualTo((long) content.length)); - var result = bridge.prepare(); - bridge.onResponse(GetObjectResponse.builder().contentLength((long) content.length).build()); - bridge.onStream( - SdkPublisher.fromIterable( - List.of( - ByteBuffer.wrap(java.util.Arrays.copyOfRange(content, 0, 64)), - ByteBuffer.wrap(java.util.Arrays.copyOfRange(content, 64, 128)), - ByteBuffer.wrap(java.util.Arrays.copyOfRange(content, 128, 129))))); + S3AsyncResponseBodyBridge bridge = + new S3AsyncResponseBodyBridge<>( + read(511, content), + (context, source) -> { + assertThat(Thread.currentThread().getName()).startsWith("s3-response-worker"); + escaped.set(source); + byte[] buffer = new byte[31]; + for (int count = source.read(buffer, 0, buffer.length); + count != -1; + count = source.read(buffer, 0, buffer.length)) { + delivered.write(buffer, 0, count); + } + }, + worker, + response -> assertThat(response.contentLength()).isEqualTo((long) content.length)); + var result = bridge.prepare(); - assertThat(result.get(5, TimeUnit.SECONDS).contentLength()).isEqualTo(content.length); - assertThat(delivered.toByteArray()).containsExactly(content); - assertThat(bridge.maximumBufferedBytesObserved()).isLessThanOrEqualTo(64); - assertThatThrownBy(() -> escaped.get().read(new byte[1], 0, 1)) - .isInstanceOf(IllegalStateException.class); - } finally { - executor.shutdownNow(); - } + // when + bridge.onResponse(GetObjectResponse.builder().contentLength((long) content.length).build()); + bridge.onStream( + SdkPublisher.fromIterable( + List.of( + ByteBuffer.wrap(java.util.Arrays.copyOfRange(content, 0, 64)), + ByteBuffer.wrap(java.util.Arrays.copyOfRange(content, 64, 128)), + ByteBuffer.wrap(java.util.Arrays.copyOfRange(content, 128, 129))))); + + // then + assertThat(result.get(HANG_GUARD_MINUTES, TimeUnit.MINUTES).contentLength()) + .isEqualTo(content.length); + assertThat(delivered.toByteArray()).containsExactly(content); + assertThat(bridge.maximumBufferedBytesObserved()).isLessThanOrEqualTo(64); + assertThatThrownBy(() -> escaped.get().read(new byte[1], 0, 1)) + .isInstanceOf(IllegalStateException.class); } @Test - void truncatedAndOversizedSdkChunksFailClosed() throws Exception { - byte[] expected = new byte[65]; - var operation = - ObjectStorageProviderContract.operation(512, expected, CancellationView.never()); - ObjectStorageProvider.ReadOperation read = - new ObjectStorageProvider.ReadOperation( - operation.canonicalDataKey(), - S3ObjectEvidenceMapper.versionForKey(operation.canonicalDataKey()), - operation.expectedContentIdentity(), - ObjectReadRange.of(0, expected.length), - CallBudget.fromNow(Duration.ofSeconds(5)), - CancellationView.never(), - 64, - 1024); - var executor = Executors.newSingleThreadExecutor(); - try { - S3AsyncResponseBodyBridge truncated = - new S3AsyncResponseBodyBridge<>( - read, - (context, source) -> { - byte[] buffer = new byte[64]; - while (source.read(buffer, 0, buffer.length) != -1) {} - }, - executor, - ignored -> {}); - var truncatedResult = truncated.prepare(); - truncated.onResponse(GetObjectResponse.builder().contentLength(65L).build()); - truncated.onStream(SdkPublisher.fromIterable(List.of(ByteBuffer.wrap(new byte[64])))); - assertThatThrownBy(() -> truncatedResult.get(5, TimeUnit.SECONDS)) - .hasCauseInstanceOf(RuntimeException.class); + void truncatedSdkBodyFailsClosed() throws Exception { + // given + S3AsyncResponseBodyBridge truncated = + new S3AsyncResponseBodyBridge<>( + read(512, new byte[65]), + (context, source) -> { + byte[] buffer = new byte[64]; + while (source.read(buffer, 0, buffer.length) != -1) {} + }, + worker, + ignored -> {}); + var result = truncated.prepare(); + truncated.onResponse(GetObjectResponse.builder().contentLength(65L).build()); - S3AsyncResponseBodyBridge oversized = - new S3AsyncResponseBodyBridge<>(read, (context, source) -> {}, executor, ignored -> {}); - var oversizedResult = oversized.prepare(); - oversized.onResponse(GetObjectResponse.builder().contentLength(65L).build()); - oversized.onStream(SdkPublisher.fromIterable(List.of(ByteBuffer.wrap(new byte[65])))); - assertThatThrownBy(() -> oversizedResult.get(5, TimeUnit.SECONDS)) - .hasCauseInstanceOf(RuntimeException.class); - } finally { - executor.shutdownNow(); - } + // when + truncated.onStream(SdkPublisher.fromIterable(List.of(ByteBuffer.wrap(new byte[64])))); + + // then + Throwable thrown = catchThrowable(() -> result.get(HANG_GUARD_MINUTES, TimeUnit.MINUTES)); + assertThat(thrown) + .isInstanceOf(ExecutionException.class) + .hasCauseInstanceOf(RuntimeException.class); + } + + @Test + void oversizedSdkChunkFailsClosed() throws Exception { + // given + S3AsyncResponseBodyBridge oversized = + new S3AsyncResponseBodyBridge<>( + read(513, new byte[65]), (context, source) -> {}, worker, ignored -> {}); + var result = oversized.prepare(); + oversized.onResponse(GetObjectResponse.builder().contentLength(65L).build()); + + // when + oversized.onStream(SdkPublisher.fromIterable(List.of(ByteBuffer.wrap(new byte[65])))); + + // then + Throwable thrown = catchThrowable(() -> result.get(HANG_GUARD_MINUTES, TimeUnit.MINUTES)); + assertThat(thrown) + .isInstanceOf(ExecutionException.class) + .cause() + .isInstanceOf(ObjectStorageProviderException.class) + .hasMessage("S3 response chunk exceeds the bounded bridge size"); + } + + /** A fresh read with its own budget, so no bridge inherits time another bridge already used. */ + private static ObjectStorageProvider.ReadOperation read(int seed, byte[] content) { + var operation = + ObjectStorageProviderContract.operation(seed, content, CancellationView.never()); + return new ObjectStorageProvider.ReadOperation( + operation.canonicalDataKey(), + S3ObjectEvidenceMapper.versionForKey(operation.canonicalDataKey()), + operation.expectedContentIdentity(), + ObjectReadRange.of(0, content.length), + CallBudget.fromNow(NEVER_EXPIRES), + CancellationView.never(), + 64, + 1024); } } diff --git a/src/adapter/outbound/persistence-fileserver/src/main/java/dev/caskeleton/adapter/outbound/persistence/fileserver/JpaFileMetadataStore.java b/src/adapter/outbound/persistence-fileserver/src/main/java/dev/caskeleton/adapter/outbound/persistence/fileserver/JpaFileMetadataStore.java index c18cf639..ac126a19 100644 --- a/src/adapter/outbound/persistence-fileserver/src/main/java/dev/caskeleton/adapter/outbound/persistence/fileserver/JpaFileMetadataStore.java +++ b/src/adapter/outbound/persistence-fileserver/src/main/java/dev/caskeleton/adapter/outbound/persistence/fileserver/JpaFileMetadataStore.java @@ -19,6 +19,7 @@ import dev.caskeleton.application.fileserver.api.metadata.FileRecordMutation; import dev.caskeleton.application.fileserver.api.metadata.FileRecoveryQuery; import java.time.Clock; import java.time.Instant; +import java.util.Arrays; import java.util.List; import java.util.Optional; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; @@ -51,6 +52,9 @@ public class JpaFileMetadataStore implements FileMetadataStore { private final FileStateMachine stateMachine; private final Clock clock; + /** The states the transition table lets into DELETING, read from the table itself. */ + private final List deletableStates; + public JpaFileMetadataStore( JpaFileRepository files, FileTransitionRepository transitions, @@ -60,6 +64,11 @@ public class JpaFileMetadataStore implements FileMetadataStore { this.transitions = transitions; this.stateMachine = stateMachine; this.clock = clock; + this.deletableStates = + Arrays.stream(FileState.values()) + .filter(state -> stateMachine.canTransition(state, FileState.DELETING)) + .map(Enum::name) + .toList(); } @Override @@ -115,7 +124,8 @@ public class JpaFileMetadataStore implements FileMetadataStore { @Override public FileRecord markDeleting(FileId fileId, long expectedVersion) { - int updated = transitions.markDeleting(fileId.value(), expectedVersion, clock.instant()); + int updated = + transitions.markDeleting(fileId.value(), expectedVersion, deletableStates, clock.instant()); if (updated == 0) { throw conflict(fileId, expectedVersion, null, FileState.DELETING); } diff --git a/src/adapter/outbound/persistence-fileserver/src/main/java/dev/caskeleton/adapter/outbound/persistence/fileserver/repository/FileTransitionRepository.java b/src/adapter/outbound/persistence-fileserver/src/main/java/dev/caskeleton/adapter/outbound/persistence/fileserver/repository/FileTransitionRepository.java index 0b9c4de0..f0016312 100644 --- a/src/adapter/outbound/persistence-fileserver/src/main/java/dev/caskeleton/adapter/outbound/persistence/fileserver/repository/FileTransitionRepository.java +++ b/src/adapter/outbound/persistence-fileserver/src/main/java/dev/caskeleton/adapter/outbound/persistence/fileserver/repository/FileTransitionRepository.java @@ -2,6 +2,7 @@ package dev.caskeleton.adapter.outbound.persistence.fileserver.repository; import dev.caskeleton.adapter.outbound.persistence.fileserver.entity.FileEntity; import java.time.Instant; +import java.util.Collection; import java.util.UUID; import org.springframework.data.jpa.repository.Modifying; import org.springframework.data.jpa.repository.Query; @@ -51,7 +52,11 @@ public interface FileTransitionRepository extends Repository { @Param("updatedAt") Instant updatedAt); /** - * Moves a record into {@code DELETING} from any state the design permits. + * Moves a record into {@code DELETING} from any of {@code deletableStates}. + * + *

The caller derives the states from the transition table, so the table stays the one place + * that says which states may be deleted; a second list written into this statement could only + * drift from it. * *

Public read authorization is blocked the moment this succeeds, well before the physical * object is removed. @@ -65,12 +70,12 @@ public interface FileTransitionRepository extends Repository { f.updatedAt = :updatedAt where f.fileId = :fileId and f.version = :expectedVersion - and f.state in ('UPLOADING', 'UPLOADED', 'QUARANTINED', 'READY', 'REJECTED', - 'FAILED', 'EXPIRED') + and f.state in :deletableStates """) int markDeleting( @Param("fileId") UUID fileId, @Param("expectedVersion") long expectedVersion, + @Param("deletableStates") Collection deletableStates, @Param("updatedAt") Instant updatedAt); /** diff --git a/src/adapter/outbound/persistence-jpa/README.md b/src/adapter/outbound/persistence-jpa/README.md index 73fb7bba..ad349903 100644 --- a/src/adapter/outbound/persistence-jpa/README.md +++ b/src/adapter/outbound/persistence-jpa/README.md @@ -45,6 +45,11 @@ outbox **relay**(스케줄러)는 이 모듈이 아니라 합성 루트의 `Outb 만들고 구동하는 일은 driven adapter의 몫이 아니기 때문이다. 그 설정은 이 모듈이 주는 `OutboxStorePort`와 messaging이 주는 `OutboxMessagePublishPort`가 모두 있을 때만 켜진다. +durable operation HTTP 엔드포인트(`POST /operations`·`GET`·`DELETE /operations/{id}`)도 같은 +이유로 합성 루트의 `DurableOperationConfig`가 조립한다. 이 모듈이 주는 operation store와 outbox +append 포트(`APP_OUTBOX_ENABLED=true`)가 모두 있을 때만 켜진다. submit·cancel에는 +`operation-submit` 역할(`operation:submit`, `operation:cancel`)이 필요하다. + 애플리케이션이 제공해야 하는 bean: `Clock`, `DomainContextPropagator`(app-bootstrap과 sample-portfolio가 제공). @@ -250,6 +255,18 @@ PostgreSQL 구현은 native query 의 `FOR UPDATE SKIP LOCKED` 를 쓰고, 다 in-memory 필터링을 하지 않는다 — 리포지토리가 반환한 모든 row 를 IN_FLIGHT 로 전이시켜 호출자에 돌려준다. 전체 SQL gate 동작은 PG contract 테스트(Testcontainers)가 검증한다. +FIFO gate 의 "같은 aggregate"와 "앞선 row": +- canonical row 끼리는 `(tenant_scope, aggregate_type, aggregate_id)` 가 같아야 같은 aggregate + 이고, 순서는 `(aggregate_sequence, event_index)` 다. 그래서 `occurred_at` 이 같은 이벤트도 한 + 번에 하나씩 나가고, 다른 tenant·type 의 DEAD row 가 같은 `aggregate_id` 를 막지 않는다. + 인덱스는 `V18` 의 `ix_outbox_event_unpublished_aggregate_order`. +- legacy row 가 끼면 예전처럼 `aggregate_id` + `occurred_at <` 로 비교한다(같은 `occurred_at` 의 + legacy row 는 함께 claim된다 — `equalTimestampRowsAreClaimedTogetherLegacyFifoLimitationCharacterization`). + +읽을 수 없는 row(부분 canonical metadata, compatibility projection 불일치 등)는 claim 에서 DEAD 로 +옮기고 배치에서 뺀다. 예전에는 예외로 claim transaction 전체가 롤백되고 다음 claim 이 같은 row 를 +다시 먼저 골라 relay 가 영구히 멈췄다. legacy 로 낮춰 발행하지 않으므로 fail-closed 는 유지된다. + eligible row(I3/I4/I6): - `PENDING` — `next_attempt_at <= now`(insert 시 즉시 eligible) - `FAILED` — `next_attempt_at <= now`(backoff 경과) @@ -295,11 +312,17 @@ A가 FAILED로 바꾸면 다시 발행되고(중복 전달), A의 늦은 PUBLISH 재claim 가능. - `FAILED`: `now + backoff` → backoff window 경과 후에만 재시도. - `status` 는 `PENDING | IN_FLIGHT | PUBLISHED | FAILED | DEAD` 문자열이다. +- **`Persistable`(새 엔티티는 `isNew() == true`).** 식별자를 직접 넣고 `@Version` 이 없는 + 엔티티를 Spring Data 는 기존 row 로 보고 merge 한다. 그래서 같은 `event_id` 로 두 번 append 하면 + 이미 PUBLISHED 된 row 가 PENDING·attempt 0 으로 덮여 다시 발행됐다. 이제 append 는 항상 + insert 이고, 중복은 primary key 위반(`23505`)으로 드러난다. ### metric 쿼리 반환 형태 `OutboxEventJpaRepository.countGroupedByStatus()` 는 `[status(String), count(Long)]`, `findOldestUnpublishedOccurredAtByEventType()` 는 `[eventType(String), oldestOccurredAt(Instant)]` 2-요소 배열 리스트를 돌려준다(각각 outbox.pending.size, outbox.publisher.lag gauge 용). +두 쿼리 모두 PUBLISHED row 는 세지 않는다 — retention 기간 동안 테이블 대부분이 PUBLISHED 라, +매 poll 마다 테이블 전체를 세게 된다. `OutboxStoreAdapter.oldestUnpublishedAgeSecondsByEventType` 가 `HashMap` 을 쓰는 건 키가 enum 이 아니라 String(event-type 이름)이기 때문이다 — `countByStatus()` 는 키가 `OutboxEventStatus` enum 이라 `EnumMap` 을 쓴다(두 반환 타입이 의도적으로 다름). @@ -307,8 +330,10 @@ enum 이 아니라 String(event-type 이름)이기 때문이다 — `countByStat ### `OutboxReaper` PUBLISHED row 는 이미 전달된 terminal-success record 라 무한 보관할 필요가 없다. reaper 가 retention 보다 오래된 PUBLISHED row 를 주기적으로 비워 테이블 성장과 metric gauge 를 묶는다. -스케줄링은 컴포지션 루트의 `@EnableScheduling` 으로 켜지고, `@Transactional` bulk delete 가 purge -를 한 문장으로 유지한다. 고정 interval / clock-skew 미처리는 프로젝트 선택(부하 하 +스케줄링은 컴포지션 루트의 `@EnableScheduling` 으로 켜진다. 삭제는 `deletePublishedBatch` 로 +1,000 row 씩, 배치마다 별도 transaction 으로 돌리고 배치가 덜 차면 멈춘다 — relay 장애 뒤 쌓인 +PUBLISHED backlog 를 한 transaction 으로 지우면 그 사이 모든 row lock 을 쥔 긴 transaction 이 된다. +고정 interval / clock-skew 미처리는 프로젝트 선택(부하 하 cadence 측정 필요). retention 한 값은 reaper-local 이라 `@Value` 로 받지만, canonical 6-property 문서는 app-bootstrap `OutboxSettings` / `application.yml` 에 있다. diff --git a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/h2/H2OutboxClaimRepository.java b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/h2/H2OutboxClaimRepository.java index 3f43da6d..4d07f5ee 100644 --- a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/h2/H2OutboxClaimRepository.java +++ b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/h2/H2OutboxClaimRepository.java @@ -29,10 +29,18 @@ public final class H2OutboxClaimRepository implements OutboxClaimRepository { AND NOT EXISTS ( SELECT 1 FROM outbox_event p WHERE p.aggregate_id = o.aggregate_id - AND p.occurred_at < o.occurred_at AND p.status <> 'PUBLISHED' + AND CASE + WHEN o.contract_id IS NOT NULL AND p.contract_id IS NOT NULL THEN + p.tenant_scope = o.tenant_scope + AND p.aggregate_type = o.aggregate_type + AND (p.aggregate_sequence < o.aggregate_sequence + OR (p.aggregate_sequence = o.aggregate_sequence + AND p.event_index < o.event_index)) + ELSE p.occurred_at < o.occurred_at + END ) - ORDER BY o.occurred_at ASC + ORDER BY o.occurred_at ASC, o.aggregate_sequence ASC, o.event_index ASC LIMIT :limit FOR UPDATE SKIP LOCKED """; diff --git a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/notification/platform/inbox/InboxItemEntity.java b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/notification/platform/inbox/InboxItemEntity.java index cb43dd3a..07cab073 100644 --- a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/notification/platform/inbox/InboxItemEntity.java +++ b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/notification/platform/inbox/InboxItemEntity.java @@ -105,7 +105,7 @@ public class InboxItemEntity { * like the item went backwards. */ boolean markSeen(Instant at) { - if (seenAt != null || readAt != null) { + if (seenAt != null || readAt != null || leftTheInbox()) { return false; } seenAt = at; @@ -115,7 +115,7 @@ public class InboxItemEntity { /** Mark read; also fills in seen so the database check constraint stays satisfied. */ boolean markRead(Instant at) { - if (readAt != null) { + if (readAt != null || leftTheInbox()) { return false; } if (seenAt == null) { @@ -126,6 +126,18 @@ public class InboxItemEntity { return true; } + /** + * Whether the item is archived, expired or deleted. Seen and read would overwrite that state and + * put the item back in the inbox, so both leave it alone — the same states the unread count and + * the bulk mark-read exclude. + */ + private boolean leftTheInbox() { + return archivedAt != null + || "ARCHIVED".equals(state) + || "EXPIRED".equals(state) + || "DELETED".equals(state); + } + /** Archive; idempotent. */ boolean archive(Instant at) { if (archivedAt != null) { diff --git a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/notification/platform/inbox/InboxItemJpaRepository.java b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/notification/platform/inbox/InboxItemJpaRepository.java index 4c62e94d..8200e9f3 100644 --- a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/notification/platform/inbox/InboxItemJpaRepository.java +++ b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/notification/platform/inbox/InboxItemJpaRepository.java @@ -87,6 +87,9 @@ public interface InboxItemJpaRepository extends Repository{@code ON CONFLICT DO NOTHING} rather than an insert that may raise. A unique violation * leaves the PostgreSQL transaction aborted, and the caller still has to read the operation that * holds the scope in that same transaction. + * + * @return 1 when this call inserted the row, 0 when the scope was already held */ @Modifying(clearAutomatically = true, flushAutomatically = true) @Query( @@ -48,7 +50,7 @@ public interface DurableOperationJpaRepository ON CONFLICT (tenant, principal, operation_name, request_hash) DO NOTHING """, nativeQuery = true) - void submitIfAbsent( + int submitIfAbsent( @Param("operationId") String operationId, @Param("tenant") String tenant, @Param("principal") String principal, diff --git a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/operation/DurableOperationStoreAdapter.java b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/operation/DurableOperationStoreAdapter.java index aca86c3a..31669c76 100644 --- a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/operation/DurableOperationStoreAdapter.java +++ b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/operation/DurableOperationStoreAdapter.java @@ -7,6 +7,7 @@ import dev.caskeleton.application.operation.DurableOperationId; import dev.caskeleton.application.operation.DurableOperationState; import dev.caskeleton.application.operation.DurableOperationStorePort; import dev.caskeleton.application.operation.DurableOperationSubmission; +import dev.caskeleton.application.operation.DurableOperationSubmitResult; import dev.caskeleton.application.operation.OperationFailure; import dev.caskeleton.application.operation.OperationLease; import dev.caskeleton.application.operation.OperationProgressSnapshot; @@ -40,28 +41,31 @@ public class DurableOperationStoreAdapter implements DurableOperationStorePort { } @Override - public DurableOperation submit(DurableOperationSubmission submission) { + public DurableOperationSubmitResult submit(DurableOperationSubmission submission) { requireCallerTransaction("submit"); String tenant = submission.tenantId() == null ? "" : submission.tenantId(); // Insert-or-nothing on the scope, then read whichever row holds it. Catching the unique // violation instead does not work on PostgreSQL: the violation aborts the caller's transaction - // (25P02), and the read of the winning row is refused along with everything after it. - repository.submitIfAbsent( - submission.operationId().value(), - tenant, - submission.principal(), - submission.operationName(), - submission.fingerprint().hex(), - submission.payload(), - submission.submittedAt(), - submission.expiresAt()); + // (25P02), and the read of the winning row is refused along with everything after it. The + // inserted count is the only thing that tells a retry under the same operation id from a + // creation. + int inserted = + repository.submitIfAbsent( + submission.operationId().value(), + tenant, + submission.principal(), + submission.operationName(), + submission.fingerprint().hex(), + submission.payload(), + submission.submittedAt(), + submission.expiresAt()); return repository .findByTenantAndPrincipalAndOperationNameAndRequestHash( tenant, submission.principal(), submission.operationName(), submission.fingerprint().hex()) - .map(DurableOperationStoreAdapter::toDomain) + .map(operation -> new DurableOperationSubmitResult(toDomain(operation), inserted == 1)) .orElseThrow( () -> new IllegalStateException( diff --git a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/outbox/CanonicalOutboxAppendAdapter.java b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/outbox/CanonicalOutboxAppendAdapter.java index b7cfe173..61ad1ba5 100644 --- a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/outbox/CanonicalOutboxAppendAdapter.java +++ b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/outbox/CanonicalOutboxAppendAdapter.java @@ -12,6 +12,7 @@ import java.util.Arrays; import java.util.Objects; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; import org.springframework.stereotype.Repository; +import org.springframework.transaction.support.TransactionSynchronizationManager; /** * Canonical append path for the transport-only outbox cutover. @@ -35,6 +36,11 @@ final class CanonicalOutboxAppendAdapter implements OutboxAppendPort { @Override public void append(ValidatedIntegrationEvent event) { + // Outside a caller transaction the row commits on its own, apart from the business write it + // announces — the dual write the outbox exists to prevent. + if (!TransactionSynchronizationManager.isActualTransactionActive()) { + throw new IllegalStateException("outbox append requires an active caller transaction"); + } Objects.requireNonNull(event, "event must not be null"); byte[] envelopeBytes = event.envelopeBytes(); String compatibilityPayload = strictUtf8(envelopeBytes); diff --git a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/outbox/OutboxEventJpaRepository.java b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/outbox/OutboxEventJpaRepository.java index 4297828f..4b2637c2 100644 --- a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/outbox/OutboxEventJpaRepository.java +++ b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/outbox/OutboxEventJpaRepository.java @@ -7,20 +7,32 @@ import org.springframework.data.jpa.repository.JpaRepository; import org.springframework.data.jpa.repository.Modifying; import org.springframework.data.jpa.repository.Query; import org.springframework.data.repository.query.Param; +import org.springframework.transaction.annotation.Transactional; /** - * Spring Data repository for {@link OutboxEventEntity} — only the vendor-neutral JPQL operations. + * Spring Data repository for {@link OutboxEventEntity} — only vendor-neutral operations. * Vendor-specific row claiming lives in the {@link OutboxClaimRepository} SPI (see README * "outbox"). */ public interface OutboxEventJpaRepository extends JpaRepository { /** - * Deletes PUBLISHED rows whose {@code occurred_at} is before {@code cutoff}; returns the count. + * Deletes at most {@code limit} PUBLISHED rows whose {@code occurred_at} is before {@code + * cutoff}, in a transaction of its own unless the caller already has one; returns the count. + * + *

Bounded because a backlog of published rows is exactly what a relay outage leaves behind, + * and one unbounded {@code DELETE} over it is a long transaction holding every deleted row's + * lock. The key subquery is plain SQL that PostgreSQL and H2 both run. */ + @Transactional @Modifying - @Query("delete from OutboxEventEntity e where e.status = 'PUBLISHED' and e.occurredAt < :cutoff") - int deletePublishedBefore(@Param("cutoff") Instant cutoff); + @Query( + value = + "DELETE FROM outbox_event WHERE event_id IN (" + + "SELECT event_id FROM outbox_event " + + "WHERE status = 'PUBLISHED' AND occurred_at < :cutoff LIMIT :limit)", + nativeQuery = true) + int deletePublishedBatch(@Param("cutoff") Instant cutoff, @Param("limit") int limit); /** * Completes a claimed row only while the given lease still holds it: {@code IN_FLIGHT}, same @@ -51,8 +63,15 @@ public interface OutboxEventJpaRepository extends JpaRepositoryPUBLISHED rows are not counted. They are most of the table for the whole retention period, + * nothing waits on them, and counting them made every poll a scan of the table. + */ + @Query( + "select e.status, count(e) from OutboxEventEntity e " + + "where e.status <> 'PUBLISHED' group by e.status") List countGroupedByStatus(); /** diff --git a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/outbox/OutboxReaper.java b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/outbox/OutboxReaper.java index 1fcf92c7..71de2bdc 100644 --- a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/outbox/OutboxReaper.java +++ b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/outbox/OutboxReaper.java @@ -2,22 +2,29 @@ package dev.caskeleton.adapter.outbound.persistence.outbox; import java.time.Clock; import java.time.Duration; +import java.time.Instant; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.beans.factory.annotation.Value; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; import org.springframework.scheduling.annotation.Scheduled; import org.springframework.stereotype.Component; -import org.springframework.transaction.annotation.Transactional; /** * Periodically purges PUBLISHED outbox rows older than the configured retention period, bounding * table growth. See README "outbox" for retention/scheduling rationale. + * + *

Deletes in batches of {@link #BATCH_SIZE}, each committed on its own, until a batch comes back + * short. */ @Component @ConditionalOnProperty(prefix = "ca-skeleton.outbox", name = "enabled", havingValue = "true") public class OutboxReaper { + /** Rows per delete statement and transaction. */ + // ponytail: fixed batch size; make it a setting if a deployment's backlog needs another value. + static final int BATCH_SIZE = 1_000; + private static final Logger log = LoggerFactory.getLogger(OutboxReaper.class); private final OutboxEventJpaRepository repository; @@ -35,11 +42,21 @@ public class OutboxReaper { this.retention = retention; } - /** Deletes PUBLISHED rows older than {@code clock.instant() - retention}; returns the count. */ + /** + * Deletes PUBLISHED rows older than {@code clock.instant() - retention}; returns the count. + * + *

Not transactional itself: each batch is its own transaction (see {@link + * OutboxEventJpaRepository#deletePublishedBatch}). + */ @Scheduled(fixedDelayString = "${ca-skeleton.outbox.reaper-interval:PT10M}") - @Transactional public int reap() { - int purged = repository.deletePublishedBefore(clock.instant().minus(retention)); + Instant cutoff = clock.instant().minus(retention); + int purged = 0; + int deleted; + do { + deleted = repository.deletePublishedBatch(cutoff, BATCH_SIZE); + purged += deleted; + } while (deleted == BATCH_SIZE); if (purged > 0) { log.debug("outbox reaper purged {} published row(s)", purged); } diff --git a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/outbox/OutboxStoreAdapter.java b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/outbox/OutboxStoreAdapter.java index 337b0c1c..6807f1f4 100644 --- a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/outbox/OutboxStoreAdapter.java +++ b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/outbox/OutboxStoreAdapter.java @@ -23,12 +23,15 @@ import java.nio.charset.CodingErrorAction; import java.nio.charset.StandardCharsets; import java.time.Duration; import java.time.Instant; +import java.util.ArrayList; import java.util.EnumMap; import java.util.HashMap; import java.util.HexFormat; import java.util.List; import java.util.Map; import java.util.Optional; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; import org.springframework.stereotype.Repository; import org.springframework.transaction.support.TransactionSynchronizationManager; @@ -44,6 +47,8 @@ import org.springframework.transaction.support.TransactionSynchronizationManager @ConditionalOnProperty(prefix = "ca-skeleton.outbox", name = "enabled", havingValue = "true") public class OutboxStoreAdapter implements LegacyOutboxAppendPort, OutboxStorePort { + private static final Logger log = LoggerFactory.getLogger(OutboxStoreAdapter.class); + private final OutboxEventJpaRepository repository; private final OutboxClaimRepository claimRepository; @@ -74,23 +79,36 @@ public class OutboxStoreAdapter implements LegacyOutboxAppendPort, OutboxStorePo /** * The claim repository returns the rows locked ({@code FOR UPDATE SKIP LOCKED}) until this * transaction commits, so incrementing the token here cannot race another relay's claim. + * + *

A row that cannot be read as an event is moved to DEAD and left out of the batch. Throwing + * instead rolled the whole claim back, and the next claim selected the same row first again, so + * one bad row stopped the relay for good. DEAD is fail-closed: the row is never published or + * downgraded to a legacy claim, and it waits for the DEAD-row runbook like any other. */ @Override public List claimBatch( String owner, int batchSize, Instant now, Duration inFlightTimeout) { requireTransaction("claimBatch"); List eligible = claimRepository.claimEligible(now, batchSize); - return eligible.stream() - .map( - entity -> { - entity.setStatus(OutboxEventStatus.IN_FLIGHT.name()); - entity.setAttemptCount(entity.getAttemptCount() + 1); - entity.setNextAttemptAt(now.plus(inFlightTimeout)); - entity.setLeaseOwner(owner); - entity.setLeaseToken(entity.getLeaseToken() + 1); - return new OutboxLease(toClaimedOutboxEvent(entity), owner, entity.getLeaseToken()); - }) - .toList(); + List leases = new ArrayList<>(eligible.size()); + for (OutboxEventEntity entity : eligible) { + entity.setStatus(OutboxEventStatus.IN_FLIGHT.name()); + entity.setAttemptCount(entity.getAttemptCount() + 1); + entity.setNextAttemptAt(now.plus(inFlightTimeout)); + entity.setLeaseOwner(owner); + entity.setLeaseToken(entity.getLeaseToken() + 1); + ClaimedOutboxEvent event; + try { + event = toClaimedOutboxEvent(entity); + } catch (RuntimeException unreadable) { + entity.setStatus(OutboxEventStatus.DEAD.name()); + entity.setLeaseOwner(null); + log.warn("outbox claim moved a row it cannot read to DEAD", unreadable); + continue; + } + leases.add(new OutboxLease(event, owner, entity.getLeaseToken())); + } + return List.copyOf(leases); } /** diff --git a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/outbox/entity/OutboxEventEntity.java b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/outbox/entity/OutboxEventEntity.java index aa35cc98..d3a58a61 100644 --- a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/outbox/entity/OutboxEventEntity.java +++ b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/outbox/entity/OutboxEventEntity.java @@ -3,10 +3,14 @@ package dev.caskeleton.adapter.outbound.persistence.outbox.entity; import jakarta.persistence.Column; import jakarta.persistence.Entity; import jakarta.persistence.Id; +import jakarta.persistence.PostLoad; +import jakarta.persistence.PostPersist; import jakarta.persistence.Table; +import jakarta.persistence.Transient; import java.time.Instant; import org.hibernate.annotations.JdbcTypeCode; import org.hibernate.type.SqlTypes; +import org.springframework.data.domain.Persistable; /** * JPA row for the {@code outbox_event} table; schema owned by Flyway ({@code V3__outbox_event.sql} @@ -14,10 +18,18 @@ import org.hibernate.type.SqlTypes; * relay lease in {@code V17__outbox_event_lease_fencing.sql}). Does not extend {@code * AuditableEntity} (infra record, not a domain aggregate) and exposes mutating setters on purpose * (relay transitions state in-place). + * + *

{@link Persistable} so that {@code save} of a new row is always an insert. With an assigned + * identifier and no version, Spring Data treats every entity as existing and merges it, and a + * second append under an event id already present rewrote that row back to PENDING — republishing + * an event that had already gone out. As an insert, the duplicate fails on the primary key. */ @Entity @Table(name = "outbox_event") -public class OutboxEventEntity { +public class OutboxEventEntity implements Persistable { + + /** True until the row is written or read; not a column. */ + @Transient private boolean newRow = true; @Id @Column(name = "event_id", nullable = false, length = 96, updatable = false) @@ -119,6 +131,22 @@ public class OutboxEventEntity { /** JPA no-arg constructor. */ public OutboxEventEntity() {} + @Override + public String getId() { + return eventId; + } + + @Override + public boolean isNew() { + return newRow; + } + + @PostLoad + @PostPersist + void markStored() { + newRow = false; + } + public String getEventId() { return eventId; } diff --git a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/postgresql/PostgreSqlOutboxClaimRepository.java b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/postgresql/PostgreSqlOutboxClaimRepository.java index 7ccf5807..e84f6948 100644 --- a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/postgresql/PostgreSqlOutboxClaimRepository.java +++ b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/postgresql/PostgreSqlOutboxClaimRepository.java @@ -9,6 +9,13 @@ import java.util.List; /** * PostgreSQL {@link OutboxClaimRepository}: claims eligible outbox rows with {@code FOR UPDATE SKIP * LOCKED}. Design notes in the module README. + * + *

The FIFO gate: a row waits while an earlier row of its aggregate is unpublished. Two canonical + * rows are the same aggregate only with the same {@code (tenant_scope, aggregate_type, + * aggregate_id)}, and earlier means a lower {@code (aggregate_sequence, event_index)} — so events + * that share an {@code occurred_at} are still released one at a time, and a DEAD row of another + * tenant or type does not block this one. Any pair involving a legacy row keeps the {@code + * occurred_at} comparison it always had. */ public class PostgreSqlOutboxClaimRepository implements OutboxClaimRepository { @@ -20,10 +27,18 @@ public class PostgreSqlOutboxClaimRepository implements OutboxClaimRepository { AND NOT EXISTS ( SELECT 1 FROM outbox_event p WHERE p.aggregate_id = o.aggregate_id - AND p.occurred_at < o.occurred_at AND p.status <> 'PUBLISHED' + AND CASE + WHEN o.contract_id IS NOT NULL AND p.contract_id IS NOT NULL THEN + p.tenant_scope = o.tenant_scope + AND p.aggregate_type = o.aggregate_type + AND (p.aggregate_sequence < o.aggregate_sequence + OR (p.aggregate_sequence = o.aggregate_sequence + AND p.event_index < o.event_index)) + ELSE p.occurred_at < o.occurred_at + END ) - ORDER BY o.occurred_at ASC + ORDER BY o.occurred_at ASC, o.aggregate_sequence ASC, o.event_index ASC LIMIT :limit FOR UPDATE SKIP LOCKED """; diff --git a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/startup/JpaDangerousConfigurationGuard.java b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/startup/JpaDangerousConfigurationGuard.java index 5e130df5..7a06ffa7 100644 --- a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/startup/JpaDangerousConfigurationGuard.java +++ b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/startup/JpaDangerousConfigurationGuard.java @@ -2,32 +2,25 @@ package dev.caskeleton.adapter.outbound.persistence.startup; import dev.caskeleton.adapter.outbound.persistence.migration.FlywaySchemaPolicy; import dev.caskeleton.adapter.outbound.support.runtime.RuntimeProfileSnapshot; -import dev.caskeleton.adapter.outbound.support.startup.StartupFailures; import java.util.List; import java.util.Objects; import org.springframework.core.env.Environment; /** - * Fails startup on the two JPA settings that quietly break production (design §15.1, §31). + * Fails startup on a schema-mutating {@code ddl-auto} outside a local convenience profile (design + * §31). * - *

Open Session In View. It keeps the Hibernate session open through view rendering, so a - * lazy association touched by the serialiser issues a database query from the presentation layer. - * Nothing errors: the page renders, the transaction boundary is gone, and one endpoint issues a - * query per row of its response. It is on by default in Spring Boot, which is why this guard - * exists. + *

{@code update} never drops or narrows anything, so it produces a schema that is neither the + * old one nor the one the migrations describe — and it does so silently, on whichever instance + * starts first. This guard holds the whole non-local profile set to that rule, so a staging + * deployment is held to the same rule as production. * - *

Schema-mutating {@code ddl-auto}. {@code update} never drops or narrows anything, so it - * produces a schema that is neither the old one nor the one the migrations describe — and it does - * so silently, on whichever instance starts first. - * - *

This guard extends the per-setting validators in this package to the whole non-local profile - * set, so a staging deployment is held to the same rule as production. + *

Open Session In View is not checked here. {@link OpenInViewSafetyValidator} refuses it in + * every profile, local included; the local exception this guard used to carry could never be + * reached. */ final class JpaDangerousConfigurationGuard { - /** The property that enables Open Session In View. */ - public static final String OPEN_IN_VIEW_KEY = "spring.jpa.open-in-view"; - /** The property that decides whether Hibernate may change the schema. */ public static final String DDL_AUTO_KEY = "spring.jpa.hibernate.ddl-auto"; @@ -46,21 +39,8 @@ final class JpaDangerousConfigurationGuard { */ public void validate(Environment environment) { Objects.requireNonNull(environment, "environment"); - boolean localConvenience = isLocalConvenience(environment); - - if (Boolean.TRUE.equals(environment.getProperty(OPEN_IN_VIEW_KEY, Boolean.class)) - && !localConvenience) { - throw StartupFailures.profileMismatch( - OPEN_IN_VIEW_KEY - + " must be false outside a local convenience profile: it holds the persistence" - + " context open through view rendering, so a lazy association touched by the" - + " serialiser queries the database from the presentation layer. Approved profiles" - + " for this switch are " - + safety.localConvenienceProfiles()); - } - String ddlAuto = environment.getProperty(DDL_AUTO_KEY); - if (ddlAuto != null && !localConvenience) { + if (ddlAuto != null && !isLocalConvenience(environment)) { schemaPolicy.requirePermittedDdlAuto(ddlAuto); } } diff --git a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/startup/JpaPlatformReport.java b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/startup/JpaPlatformReport.java index 8819fc2f..fa5a8a5b 100644 --- a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/startup/JpaPlatformReport.java +++ b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/startup/JpaPlatformReport.java @@ -131,8 +131,7 @@ record JpaPlatformReport( } boolean openInViewDisabled = !Boolean.TRUE.equals( - environment.getProperty( - JpaDangerousConfigurationGuard.OPEN_IN_VIEW_KEY, Boolean.class)); + environment.getProperty(OpenInViewSafetyValidator.OPEN_IN_VIEW_KEY, Boolean.class)); return sanitized( product, majorVersion, diff --git a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/startup/JpaSafetySettings.java b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/startup/JpaSafetySettings.java index 3592cae8..63d578ac 100644 --- a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/startup/JpaSafetySettings.java +++ b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/startup/JpaSafetySettings.java @@ -14,9 +14,11 @@ import org.springframework.boot.context.properties.bind.DefaultValue; * switches turned off — the two answers disagreed precisely for the deployments that never thought * about it. * - *

{@code localConvenienceProfiles} names the profiles where Open Session In View may be left on - * — a developer running a template locally, and nothing else. It is a list rather than a boolean so - * that "on in local" cannot silently expand to another runtime environment when policy changes. + *

{@code localConvenienceProfiles} names the profiles where a schema-mutating {@code ddl-auto} + * may be used — a developer running a template locally, and nothing else. It is a list rather than + * a boolean so that "on in local" cannot silently expand to another runtime environment when policy + * changes. Open Session In View has no local exception: {@link OpenInViewSafetyValidator} refuses + * it in every profile. */ @ConfigurationProperties(prefix = "app.jpa-platform") record JpaSafetySettings( @@ -24,7 +26,7 @@ record JpaSafetySettings( Set localConvenienceProfiles, Set schemaMutatingProfiles) { - /** The profiles that may run with OSIV enabled, when nothing else is configured. */ + /** The local convenience profiles, when nothing else is configured. */ public static final Set DEFAULT_LOCAL_PROFILES = Set.of(RuntimeEnvironment.LOCAL.profileName(), RuntimeEnvironment.testProfileName()); @@ -42,7 +44,7 @@ record JpaSafetySettings( return new JpaSafetySettings(true, DEFAULT_LOCAL_PROFILES, Set.of()); } - /** Whether a profile may run with OSIV enabled. */ + /** Whether a profile is a local convenience profile. */ public boolean isLocalConvenience(String profile) { return localConvenienceProfiles.contains(profile); } diff --git a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/transaction/SpringTransactionPort.java b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/transaction/SpringTransactionPort.java index 4e54f6ec..2c89df5d 100644 --- a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/transaction/SpringTransactionPort.java +++ b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/transaction/SpringTransactionPort.java @@ -23,6 +23,9 @@ import org.springframework.transaction.support.TransactionTemplate; @Component public class SpringTransactionPort implements TransactionPort { + /** Upper bound on one {@link #inNew} transaction; the former compensation budget. */ + static final int REQUIRES_NEW_TIMEOUT_SECONDS = 30; + private final TransactionTemplate writeTemplate; private final TransactionTemplate readTemplate; private final TransactionTemplate requiresNewTemplate; @@ -54,6 +57,9 @@ public class SpringTransactionPort implements TransactionPort { TransactionMode.REQUIRES_NEW, TransactionDefinition.PROPAGATION_REQUIRES_NEW, false); + // inNew is for outbox, audit and compensation writes, which usually run while the caller's own + // transaction holds a second connection. An unbounded one could pin both for good. + this.requiresNewTemplate.setTimeout(REQUIRES_NEW_TIMEOUT_SECONDS); this.exceptionTranslator = exceptionTranslator; } diff --git a/src/adapter/outbound/persistence-jpa/src/main/resources/config/module-defaults/persistence-jpa.yml b/src/adapter/outbound/persistence-jpa/src/main/resources/config/module-defaults/persistence-jpa.yml index ab2fb8bf..c83c8304 100644 --- a/src/adapter/outbound/persistence-jpa/src/main/resources/config/module-defaults/persistence-jpa.yml +++ b/src/adapter/outbound/persistence-jpa/src/main/resources/config/module-defaults/persistence-jpa.yml @@ -201,3 +201,12 @@ ca-skeleton: # ISO-8601 duration — PUBLISHED row retention before reaper deletes them (I3) # read also by adapter-persistence OutboxReaper via ${ca-skeleton.outbox.published-retention:P7D} published-retention: P7D + +# /actuator/info 에 싣는 이 모듈의 상태(management.info.env). compose smoke 가 lane 이 실제로 켠 +# capability 와 DB 벤더를 이 값으로 확인한다. enabled 는 위 스위치를 해석한 값이고, 기본값은 +# PersistenceJpaAutoConfiguration 의 matchIfMissing 과 같다. +info: + capabilities: + persistence-jpa: + enabled: ${ca-skeleton.persistence-jpa.enabled:true} + vendor: ${ca-skeleton.persistence.vendor:postgresql} diff --git a/src/adapter/outbound/persistence-jpa/src/main/resources/db/migration/postgresql/V18__outbox_event_unpublished_aggregate_order.sql b/src/adapter/outbound/persistence-jpa/src/main/resources/db/migration/postgresql/V18__outbox_event_unpublished_aggregate_order.sql new file mode 100644 index 00000000..5fb418bf --- /dev/null +++ b/src/adapter/outbound/persistence-jpa/src/main/resources/db/migration/postgresql/V18__outbox_event_unpublished_aggregate_order.sql @@ -0,0 +1,8 @@ +-- The claim's per-aggregate FIFO gate looks up an aggregate's unpublished rows. Canonical rows are +-- ordered within (tenant_scope, aggregate_type, aggregate_id) by (aggregate_sequence, event_index); +-- legacy rows, which carry none of those columns, keep ordering by occurred_at. +-- +-- Partial on status: published rows stay for the retention period and never gate anything. +CREATE INDEX IF NOT EXISTS ix_outbox_event_unpublished_aggregate_order + ON outbox_event (aggregate_id, tenant_scope, aggregate_type, aggregate_sequence, event_index) + WHERE status <> 'PUBLISHED'; diff --git a/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/operation/DurableOperationSubmissionOutboxIntegrationTest.java b/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/operation/DurableOperationSubmissionOutboxIntegrationTest.java new file mode 100644 index 00000000..976a3e46 --- /dev/null +++ b/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/operation/DurableOperationSubmissionOutboxIntegrationTest.java @@ -0,0 +1,205 @@ +package dev.caskeleton.adapter.outbound.persistence.operation; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.catchThrowable; + +import dev.caskeleton.adapter.outbound.persistence.operation.entity.DurableOperationEntity; +import dev.caskeleton.adapter.outbound.persistence.outbox.OutboxEventJpaRepository; +import dev.caskeleton.adapter.outbound.persistence.outbox.OutboxStoreAdapter; +import dev.caskeleton.adapter.outbound.persistence.outbox.entity.OutboxEventEntity; +import dev.caskeleton.adapter.outbound.persistence.platform.JpaPlatformContractSupport; +import dev.caskeleton.adapter.outbound.persistence.transaction.SpringTransactionPort; +import dev.caskeleton.application.idempotency.RequestFingerprint; +import dev.caskeleton.application.operation.DurableOperationId; +import dev.caskeleton.application.operation.OperationAcceptance; +import dev.caskeleton.application.operation.OperationCommand; +import dev.caskeleton.application.operation.SubmitDurableOperationUseCase; +import dev.caskeleton.application.transaction.TransactionPort; +import dev.caskeleton.shared.error.PersistenceFailureException; +import jakarta.persistence.EntityManagerFactory; +import java.sql.Connection; +import java.sql.PreparedStatement; +import java.sql.ResultSet; +import java.sql.SQLException; +import java.sql.Statement; +import java.time.Clock; +import java.time.Duration; +import java.time.Instant; +import java.time.ZoneOffset; +import java.util.ArrayList; +import java.util.List; +import java.util.Map; +import javax.sql.DataSource; +import org.flywaydb.core.Flyway; +import org.junit.jupiter.api.AfterAll; +import org.junit.jupiter.api.BeforeAll; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Tag; +import org.junit.jupiter.api.Test; +import org.springframework.context.annotation.AnnotationConfigApplicationContext; +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; +import org.springframework.data.jpa.repository.config.EnableJpaRepositories; +import org.springframework.orm.jpa.JpaTransactionManager; +import org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean; +import org.springframework.orm.jpa.vendor.HibernateJpaVendorAdapter; +import org.springframework.transaction.PlatformTransactionManager; + +/** + * Submission through the shipped operation store and outbox store, in one Spring transaction, + * against real PostgreSQL. + * + *

The in-memory fakes cannot show what a repeated outbox append does to a row that already + * exists: that is Spring Data's {@code save} deciding between insert and merge, and PostgreSQL's + * primary key. + */ +@Tag("jpa-contract") +class DurableOperationSubmissionOutboxIntegrationTest { + + private static final Instant NOW = Instant.parse("2026-08-25T09:00:00Z"); + private static final DurableOperationId ID = new DurableOperationId("op-1"); + + private static JpaPlatformContractSupport support; + private static AnnotationConfigApplicationContext context; + + @BeforeAll + static void start() { + support = JpaPlatformContractSupport.start(); + Flyway.configure() + .dataSource(support.dataSource()) + .locations("classpath:db/migration/postgresql") + .load() + .migrate(); + context = new AnnotationConfigApplicationContext(); + context.getBeanFactory().registerSingleton("dataSource", support.dataSource()); + context.register(SubmissionConfiguration.class); + context.refresh(); + } + + @AfterAll + static void stop() { + if (context != null) { + context.close(); + } + if (support != null) { + support.close(); + } + } + + @BeforeEach + void empty() throws SQLException { + execute("TRUNCATE durable_operation, outbox_event"); + } + + @Test + void retryUnderTheSameOperationIdLeavesThePublishedOutboxRowAlone() throws SQLException { + // given + SubmitDurableOperationUseCase useCase = context.getBean(SubmitDurableOperationUseCase.class); + useCase.submit(command()); + execute("UPDATE outbox_event SET status = 'PUBLISHED'"); + + // when + OperationAcceptance retry = useCase.submit(command()); + + // then + assertThat(List.of(retry.alreadyAccepted(), outboxStatuses())) + .containsExactly(true, List.of("PUBLISHED")); + } + + @Test + void aSecondAppendOfTheSameEventIdIsRefusedByThePrimaryKeyInsteadOfOverwritingTheRow() + throws SQLException { + // given + SubmitDurableOperationUseCase useCase = context.getBean(SubmitDurableOperationUseCase.class); + useCase.submit(command()); + execute("UPDATE outbox_event SET status = 'PUBLISHED'"); + // With the operation row gone the next submission is a creation again, so it appends an outbox + // event under the event id that is already there. + execute("DELETE FROM durable_operation"); + + // when + Throwable thrown = catchThrowable(() -> useCase.submit(command())); + + // then + // SpringTransactionPort classifies the commit failure; 23505 is the primary key. + assertThat(thrown) + .isInstanceOf(PersistenceFailureException.class) + .hasMessageContaining("SQLState=23505"); + } + + private static OperationCommand command() { + return new OperationCommand( + ID, + "reports.generate", + "alice", + null, + new RequestFingerprint("a".repeat(64)), + "{\"range\":\"2026-08\"}", + OperationCommand.SUBMITTED_EVENT_TYPE, + Duration.ofDays(1)); + } + + private static List outboxStatuses() throws SQLException { + try (Connection connection = support.connection(); + PreparedStatement statement = + connection.prepareStatement("SELECT status FROM outbox_event ORDER BY event_id"); + ResultSet rows = statement.executeQuery()) { + List statuses = new ArrayList<>(); + while (rows.next()) { + statuses.add(rows.getString(1)); + } + return statuses; + } + } + + private static void execute(String sql) throws SQLException { + try (Connection connection = support.connection(); + Statement statement = connection.createStatement()) { + statement.execute(sql); + } + } + + @Configuration + @EnableJpaRepositories( + basePackageClasses = {DurableOperationJpaRepository.class, OutboxEventJpaRepository.class}) + static class SubmissionConfiguration { + + @Bean + LocalContainerEntityManagerFactoryBean entityManagerFactory(DataSource dataSource) { + LocalContainerEntityManagerFactoryBean factory = new LocalContainerEntityManagerFactoryBean(); + factory.setDataSource(dataSource); + factory.setPackagesToScan( + DurableOperationEntity.class.getPackageName(), OutboxEventEntity.class.getPackageName()); + factory.setJpaVendorAdapter(new HibernateJpaVendorAdapter()); + factory.setJpaPropertyMap( + Map.of( + "hibernate.hbm2ddl.auto", "validate", + "hibernate.dialect", "org.hibernate.dialect.PostgreSQLDialect", + "hibernate.jdbc.time_zone", "UTC")); + return factory; + } + + @Bean + PlatformTransactionManager transactionManager(EntityManagerFactory entityManagerFactory) { + return new JpaTransactionManager(entityManagerFactory); + } + + @Bean + TransactionPort transactionPort(PlatformTransactionManager transactionManager) { + return new SpringTransactionPort(transactionManager); + } + + @Bean + SubmitDurableOperationUseCase submitDurableOperationUseCase( + DurableOperationJpaRepository operations, + OutboxEventJpaRepository outbox, + TransactionPort transactions) { + return new SubmitDurableOperationUseCase( + new DurableOperationStoreAdapter(operations), + // The claim is never exercised here; submission only appends. + new OutboxStoreAdapter(outbox, (now, limit) -> List.of()), + transactions, + Clock.fixed(NOW, ZoneOffset.UTC)); + } + } +} diff --git a/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlFileserverMetadataStoreIntegrationTest.java b/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlFileserverMetadataStoreIntegrationTest.java index f0685699..e7957f45 100644 --- a/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlFileserverMetadataStoreIntegrationTest.java +++ b/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlFileserverMetadataStoreIntegrationTest.java @@ -2,6 +2,7 @@ package dev.caskeleton.adapter.outbound.persistence.readiness; import static org.assertj.core.api.Assertions.assertThat; import static org.assertj.core.api.Assertions.assertThatThrownBy; +import static org.assertj.core.api.Assertions.catchThrowable; import dev.caskeleton.adapter.outbound.persistence.fileserver.JpaFileMetadataStore; import dev.caskeleton.adapter.outbound.persistence.fileserver.JpaFileQuotaService; @@ -191,6 +192,25 @@ class PostgreSqlFileserverMetadataStoreIntegrationTest { .contains(new FileOwner("user-1", Optional.of("tenant-a"))); } + /** The deletable states come from the transition table, which has no VERIFYING -> DELETING. */ + @Test + void aRecordInAStateWithNoDeletingEdgeIsNotMarkedDeleting() { + // given + FileRecord verifying = insertVerifyingFile(); + + // when + Throwable failure = + catchThrowable( + () -> + transactions.execute( + ignored -> files.markDeleting(verifying.fileId(), verifying.version()))); + + // then + assertThat(failure) + .isInstanceOf(ConcurrentFileModificationException.class) + .hasMessageContaining("for target DELETING"); + } + @Test void logicalDeleteMovesTheRecordOutOfPublicReadability() { FileRecord ready = insertReadyFile(); diff --git a/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlInboxCutoffIntegrationTest.java b/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlInboxCutoffIntegrationTest.java index 67612fed..66b35d87 100644 --- a/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlInboxCutoffIntegrationTest.java +++ b/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlInboxCutoffIntegrationTest.java @@ -2,6 +2,8 @@ package dev.caskeleton.adapter.outbound.persistence.readiness; import static org.assertj.core.api.Assertions.assertThat; +import dev.caskeleton.adapter.outbound.persistence.notification.platform.inbox.InboxItemJpaRepository; +import java.sql.Types; import java.time.Instant; import java.util.List; import java.util.UUID; @@ -9,7 +11,10 @@ import org.flywaydb.core.Flyway; import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Tag; import org.junit.jupiter.api.Test; +import org.springframework.data.jpa.repository.Query; import org.springframework.jdbc.core.JdbcTemplate; +import org.springframework.jdbc.core.namedparam.MapSqlParameterSource; +import org.springframework.jdbc.core.namedparam.NamedParameterJdbcTemplate; /** * "Everything up to here" has to mean the ordering the reader actually scrolled through. @@ -83,25 +88,63 @@ class PostgreSqlInboxCutoffIntegrationTest { } } - private static int markAllRead(JdbcTemplate jdbc, Instant cutoffAt, UUID cutoffId) { - return jdbc.update( - """ - UPDATE notification_inbox_item SET read_at = now(), - seen_at = COALESCE(seen_at, now()), state = 'READ' - WHERE id IN ( - SELECT id FROM notification_inbox_item - WHERE tenant_id = 'tenant-a' AND owner_ref = 'user-1' AND read_at IS NULL - AND ( - CAST(? AS timestamptz) IS NULL - OR created_at < CAST(? AS timestamptz) - OR (created_at = CAST(? AS timestamptz) AND id <= CAST(? AS uuid)) - ) - ORDER BY created_at DESC, id DESC LIMIT 100) - """, - cutoffAt == null ? null : java.sql.Timestamp.from(cutoffAt), - cutoffAt == null ? null : java.sql.Timestamp.from(cutoffAt), - cutoffAt == null ? null : java.sql.Timestamp.from(cutoffAt), - cutoffId == null ? null : cutoffId.toString()); + @Test + void markAllReadLeavesAnUnreadArchivedItemArchived() throws Exception { + try (PostgreSqlReadinessSupport database = PostgreSqlReadinessSupport.start()) { + // given + migrate(database); + JdbcTemplate jdbc = new JdbcTemplate(database.dataSource()); + UUID unread = UUID.fromString("00000000-0000-0000-0000-0000000000a0"); + UUID archived = UUID.fromString("00000000-0000-0000-0000-0000000000b0"); + insert(jdbc, unread, SHARED); + jdbc.update( + """ + insert into notification_inbox_item ( + id, tenant_id, owner_ref, category, content_json, state, created_at, archived_at + ) values (?, 'tenant-a', 'user-1', 'transactional', '{}'::jsonb, 'ARCHIVED', ?, ?) + """, + archived, + java.sql.Timestamp.from(SHARED), + java.sql.Timestamp.from(SHARED)); + + // when + int marked = markAllRead(jdbc, null, null); + + // then + assertThat(List.of(marked, state(jdbc, archived))).containsExactly(1, "ARCHIVED"); + } + } + + /** + * Runs the repository's own statement, read off its {@code @Query}, so these cases exercise the + * SQL the application ships rather than a copy of it. + */ + private static int markAllRead(JdbcTemplate jdbc, Instant cutoffAt, UUID cutoffId) + throws NoSuchMethodException { + String sql = + InboxItemJpaRepository.class + .getMethod( + "markAllRead", + String.class, + String.class, + Instant.class, + UUID.class, + int.class, + Instant.class) + .getAnnotation(Query.class) + .value(); + MapSqlParameterSource parameters = + new MapSqlParameterSource() + .addValue("tenantId", "tenant-a") + .addValue("ownerRef", "user-1") + .addValue( + "cutoffCreatedAt", + cutoffAt == null ? null : java.sql.Timestamp.from(cutoffAt), + Types.TIMESTAMP) + .addValue("cutoffId", cutoffId == null ? null : cutoffId.toString(), Types.VARCHAR) + .addValue("maxItems", 100) + .addValue("at", java.sql.Timestamp.from(SHARED.plusSeconds(3600)), Types.TIMESTAMP); + return new NamedParameterJdbcTemplate(jdbc).update(sql, parameters); } private static Instant readState(JdbcTemplate jdbc, UUID id) { @@ -109,6 +152,11 @@ class PostgreSqlInboxCutoffIntegrationTest { "select read_at from notification_inbox_item where id = ?", Instant.class, id); } + private static String state(JdbcTemplate jdbc, UUID id) { + return jdbc.queryForObject( + "select state from notification_inbox_item where id = ?", String.class, id); + } + private static void insert(JdbcTemplate jdbc, UUID id, Instant createdAt) { jdbc.update( """ diff --git a/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlLegacyOutboxRowLifecycleIntegrationTest.java b/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlLegacyOutboxRowLifecycleIntegrationTest.java index c04b92f3..6b4b8ab2 100644 --- a/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlLegacyOutboxRowLifecycleIntegrationTest.java +++ b/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlLegacyOutboxRowLifecycleIntegrationTest.java @@ -5,6 +5,7 @@ import static org.assertj.core.api.Assertions.assertThat; import dev.caskeleton.adapter.outbound.persistence.outbox.OutboxEventJpaRepository; import dev.caskeleton.adapter.outbound.persistence.outbox.OutboxReaper; import dev.caskeleton.adapter.outbound.persistence.outbox.OutboxStoreAdapter; +import dev.caskeleton.adapter.outbound.persistence.outbox.entity.OutboxEventEntity; import dev.caskeleton.application.outbox.LegacyOutboxAppendPort; import dev.caskeleton.application.outbox.NewOutboxEvent; import dev.caskeleton.application.outbox.OutboxBackoffPolicy; @@ -76,7 +77,6 @@ class PostgreSqlLegacyOutboxRowLifecycleIntegrationTest { TransactionPort tx = ctx.getBean(TransactionPort.class); LegacyOutboxAppendPort append = ctx.getBean(LegacyOutboxAppendPort.class); - OutboxStoreAdapter store = ctx.getBean(OutboxStoreAdapter.class); String eventId = "lifecycle-happy-" + System.nanoTime(); tx.inWrite( @@ -97,11 +97,8 @@ class PostgreSqlLegacyOutboxRowLifecycleIntegrationTest { .count(); assertThat(published).as("event must be PUBLISHED in relay result").isEqualTo(1); - // Verify DB status - Map counts = store.countByStatus(); - assertThat(counts.getOrDefault(OutboxEventStatus.PUBLISHED, 0L)) - .as("PUBLISHED count must be >= 1") - .isGreaterThanOrEqualTo(1); + // Verify DB status (countByStatus leaves PUBLISHED rows uncounted, so read the row itself) + assertThat(statusOf(ctx, eventId)).as("row must be PUBLISHED").isEqualTo("PUBLISHED"); } } @@ -440,7 +437,6 @@ class PostgreSqlLegacyOutboxRowLifecycleIntegrationTest { TransactionPort tx = ctx.getBean(TransactionPort.class); LegacyOutboxAppendPort append = ctx.getBean(LegacyOutboxAppendPort.class); - OutboxStoreAdapter store = ctx.getBean(OutboxStoreAdapter.class); String aggId = "agg-fifo-unblock-" + System.nanoTime(); String headId = "fifo-unblock-head-" + System.nanoTime(); @@ -472,10 +468,7 @@ class PostgreSqlLegacyOutboxRowLifecycleIntegrationTest { .isZero(); // Verify DB: head is PUBLISHED. - Map afterCycle1 = store.countByStatus(); - assertThat(afterCycle1.getOrDefault(OutboxEventStatus.PUBLISHED, 0L)) - .as("at least one PUBLISHED row after cycle 1") - .isGreaterThanOrEqualTo(1L); + assertThat(statusOf(ctx, headId)).as("head row after cycle 1").isEqualTo("PUBLISHED"); // Cycle 2: head is now PUBLISHED → NOT EXISTS gate passes for tail. OutboxRelayResult cycle2 = relay.handle(PublishPendingOutboxEventsCommand.INSTANCE); @@ -659,21 +652,18 @@ class PostgreSqlLegacyOutboxRowLifecycleIntegrationTest { tx.inWrite(() -> store.markPublished(claimed.getFirst())); // Verify it's PUBLISHED - Map before = store.countByStatus(); - assertThat(before.getOrDefault(OutboxEventStatus.PUBLISHED, 0L)) + assertThat(statusOf(ctx, eventId)) .as("row must be PUBLISHED before reaper runs") - .isGreaterThanOrEqualTo(1); + .isEqualTo("PUBLISHED"); - // Run reaper with short retention (1s) and a clock well past the cutoff. - // OutboxReaper.reap() uses @Transactional which only works as a Spring proxy. - // When constructed manually, wrap the delete in a write transaction instead. + // Run reaper with short retention (1s) and a clock well past the cutoff. Each batch opens + // its own transaction on the Spring Data repository, so no caller transaction is needed. OutboxEventJpaRepository repo = ctx.getBean(OutboxEventJpaRepository.class); OutboxReaper reaper = new OutboxReaper( repo, clock, Duration.ofSeconds(1)); // retention = 1s; eventTime was 10s ago - // @Transactional is not active on a manually-constructed bean; run within tx. - int purged = tx.inWrite(() -> reaper.reap()); + int purged = reaper.reap(); assertThat(purged) .as("reaper must delete at least the PUBLISHED row inserted 10s ago") .isGreaterThanOrEqualTo(1); @@ -684,6 +674,13 @@ class PostgreSqlLegacyOutboxRowLifecycleIntegrationTest { // helpers // ========================================================================= + private static String statusOf(AnnotationConfigApplicationContext ctx, String eventId) { + return ctx.getBean(OutboxEventJpaRepository.class) + .findById(eventId) + .map(OutboxEventEntity::getStatus) + .orElseThrow(); + } + /** * Builds a relay use case that uses the given clock instant, but gets its store and transaction * port from the existing context. diff --git a/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlMigrationIntegrationTest.java b/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlMigrationIntegrationTest.java index f855a55a..8f7bf740 100644 --- a/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlMigrationIntegrationTest.java +++ b/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlMigrationIntegrationTest.java @@ -49,7 +49,7 @@ class PostgreSqlMigrationIntegrationTest { assertThat(appliedVersions(postgres, "flyway_schema_history")) .containsExactly( - "1", "3", "4", "5", "6", "9", "10", "11", "12", "13", "14", "15", "16", "17"); + "1", "3", "4", "5", "6", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18"); assertThat( singleValue( postgres, diff --git a/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlOutboxClaimAndMaintenanceIntegrationTest.java b/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlOutboxClaimAndMaintenanceIntegrationTest.java new file mode 100644 index 00000000..1528fafb --- /dev/null +++ b/src/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/readiness/PostgreSqlOutboxClaimAndMaintenanceIntegrationTest.java @@ -0,0 +1,268 @@ +package dev.caskeleton.adapter.outbound.persistence.readiness; + +import static org.assertj.core.api.Assertions.assertThat; + +import dev.caskeleton.adapter.outbound.persistence.outbox.OutboxEventJpaRepository; +import dev.caskeleton.adapter.outbound.persistence.outbox.OutboxReaper; +import dev.caskeleton.adapter.outbound.persistence.outbox.OutboxStoreAdapter; +import dev.caskeleton.application.outbox.OutboxEventStatus; +import dev.caskeleton.application.outbox.OutboxLease; +import dev.caskeleton.application.transaction.TransactionPort; +import java.nio.charset.StandardCharsets; +import java.security.MessageDigest; +import java.security.NoSuchAlgorithmException; +import java.sql.Timestamp; +import java.time.Clock; +import java.time.Duration; +import java.time.Instant; +import java.time.ZoneOffset; +import java.util.HexFormat; +import java.util.List; +import java.util.Map; +import javax.sql.DataSource; +import org.junit.jupiter.api.AfterAll; +import org.junit.jupiter.api.AfterEach; +import org.junit.jupiter.api.BeforeAll; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Tag; +import org.junit.jupiter.api.Test; +import org.springframework.context.annotation.AnnotationConfigApplicationContext; +import org.springframework.jdbc.core.JdbcTemplate; + +/** + * The claim gate, the claim's handling of unreadable rows, the status gauge query and the reaper, + * against real PostgreSQL through the shipped outbox store. + * + *

Canonical rows are written with SQL because the canonical append adapter is internal to its + * package; the columns are the ones that adapter writes. + */ +@Tag("jpa-contract") +class PostgreSqlOutboxClaimAndMaintenanceIntegrationTest { + + private static final Instant OCCURRED = Instant.parse("2026-09-01T00:00:00Z"); + private static final Instant NOW = OCCURRED.plusSeconds(60); + private static final String ENVELOPE = "{\"wire\":\"exact\"}"; + // The claim re-checks the stored hash against the bytes, so the fixture stores the real one. + private static final String ENVELOPE_SHA256 = sha256Hex(ENVELOPE); + + private static PostgreSqlReadinessSupport postgres; + private static DataSource dataSource; + + private AnnotationConfigApplicationContext context; + private JdbcTemplate jdbc; + + @BeforeAll + static void start() { + postgres = PostgreSqlReadinessSupport.start(); + dataSource = postgres.dataSource(); + LegacyOutboxIntegrationSupport.migrate(dataSource); + } + + @AfterAll + static void stop() { + if (postgres != null) { + postgres.close(); + } + } + + @BeforeEach + void openContext() { + jdbc = new JdbcTemplate(dataSource); + jdbc.execute("TRUNCATE outbox_event"); + context = + LegacyOutboxIntegrationSupport.buildContext( + dataSource, event -> {}, Clock.fixed(NOW, ZoneOffset.UTC)); + } + + @AfterEach + void closeContext() { + context.close(); + } + + @Test + void canonicalEventsSharingAnOccurredAtAreClaimedOneAtATimeInAggregateOrder() { + // given + insertCanonical("seq-1-idx-1", "tenant-a", "worklog", 1, 1, "PENDING"); + insertCanonical("seq-2-idx-0", "tenant-a", "worklog", 2, 0, "PENDING"); + insertCanonical("seq-1-idx-0", "tenant-a", "worklog", 1, 0, "PENDING"); + + // when + List claimed = claim(); + + // then + assertThat(claimed).containsExactly("seq-1-idx-0"); + } + + @Test + void aDeadCanonicalRowOfAnotherTenantOrTypeDoesNotBlockTheSameAggregateId() { + // given + // Earlier than the pending row, so an occurred_at gate keyed on aggregate_id alone blocks it. + Instant earlier = OCCURRED.minusSeconds(10); + insertCanonical("other-tenant-dead", "tenant-b", "worklog", 1, 0, "DEAD", earlier); + insertCanonical("other-type-dead", "tenant-a", "poster", 1, 0, "DEAD", earlier); + insertCanonical("tenant-a-worklog", "tenant-a", "worklog", 2, 0, "PENDING"); + + // when + List claimed = claim(); + + // then + assertThat(claimed).containsExactly("tenant-a-worklog"); + } + + @Test + void anUnreadableCanonicalRowDoesNotStopTheRestOfTheBatchFromBeingClaimed() { + // given + insertCanonical("unreadable", "tenant-a", "worklog", 1, 0, "PENDING"); + jdbc.update( + "UPDATE outbox_event SET payload = 'not the envelope' WHERE event_id = 'unreadable'"); + insertLegacy("readable", "PENDING", OCCURRED); + + // when + List claimed = claim(); + + // then + assertThat(claimed).containsExactly("readable"); + } + + @Test + void anUnreadableCanonicalRowIsMovedToDeadByTheClaim() { + // given + insertCanonical("unreadable", "tenant-a", "worklog", 1, 0, "PENDING"); + jdbc.update( + "UPDATE outbox_event SET payload = 'not the envelope' WHERE event_id = 'unreadable'"); + + // when + claim(); + + // then + assertThat(status("unreadable")).isEqualTo("DEAD"); + } + + @Test + void countByStatusLeavesPublishedRowsUncounted() { + // given + insertLegacy("published", "PUBLISHED", OCCURRED); + insertLegacy("pending", "PENDING", OCCURRED); + + // when + Map counts = context.getBean(OutboxStoreAdapter.class).countByStatus(); + + // then + assertThat(counts).containsExactly(Map.entry(OutboxEventStatus.PENDING, 1L)); + } + + @Test + void reaperDeletesOldPublishedRowsOutsideAnyCallerTransaction() { + // given + for (int index = 0; index < 5; index++) { + insertLegacy("published-" + index, "PUBLISHED", OCCURRED); + } + insertLegacy("pending", "PENDING", OCCURRED); + OutboxReaper reaper = + new OutboxReaper( + context.getBean(OutboxEventJpaRepository.class), + Clock.fixed(NOW, ZoneOffset.UTC), + Duration.ofSeconds(1)); + + // when + int purged = reaper.reap(); + + // then + assertThat(List.of(purged, rowCount())).containsExactly(5, 1); + } + + private List claim() { + OutboxStoreAdapter store = context.getBean(OutboxStoreAdapter.class); + List leases = + context + .getBean(TransactionPort.class) + .inWrite(() -> store.claimBatch("relay-1", 50, NOW, Duration.ofSeconds(30))); + return leases.stream().map(OutboxLease::eventId).toList(); + } + + private void insertCanonical( + String eventId, + String tenantScope, + String aggregateType, + long sequence, + int eventIndex, + String status) { + insertCanonical(eventId, tenantScope, aggregateType, sequence, eventIndex, status, OCCURRED); + } + + private void insertCanonical( + String eventId, + String tenantScope, + String aggregateType, + long sequence, + int eventIndex, + String status, + Instant occurredAt) { + jdbc.update( + """ + INSERT INTO outbox_event ( + event_id, aggregate_id, event_type, payload, occurred_at, status, attempt_count, + next_attempt_at, correlation_id, idempotency_key, + contract_id, envelope_version, payload_version, logical_destination, tenant_scope, + aggregate_type, aggregate_sequence, event_index, partition_key, envelope_bytes, + content_type, schema_set_hash, envelope_sha256, envelope_schema_hash, + payload_schema_hash, contract_catalog_revision, destination_binding_revision) + VALUES (?, 'worklog-42', 'portfolio.worklog.reserved', ?, ?, ?, 0, ?, 'corr-1', ?, + 'portfolio.worklog.reserved', 1, 3, 'portfolio-domain-events', ?, ?, ?, ?, ?, ?, + 'application/json', ?, ?, ?, ?, 'catalog-r1', 'binding-r1') + """, + eventId, + ENVELOPE, + Timestamp.from(occurredAt), + status, + Timestamp.from(occurredAt), + eventId, + tenantScope, + aggregateType, + sequence, + eventIndex, + "a".repeat(64), + ENVELOPE.getBytes(StandardCharsets.UTF_8), + "1".repeat(64), + ENVELOPE_SHA256, + "3".repeat(64), + "4".repeat(64)); + } + + private void insertLegacy(String eventId, String status, Instant occurredAt) { + jdbc.update( + """ + INSERT INTO outbox_event ( + event_id, aggregate_id, event_type, payload, occurred_at, status, attempt_count, + next_attempt_at, correlation_id, idempotency_key) + VALUES (?, ?, 'TestEvent', '{}', ?, ?, 0, ?, 'corr-1', ?) + """, + eventId, + "agg-" + eventId, + Timestamp.from(occurredAt), + status, + Timestamp.from(occurredAt), + eventId); + } + + private String status(String eventId) { + return jdbc.queryForObject( + "SELECT status FROM outbox_event WHERE event_id = ?", String.class, eventId); + } + + private int rowCount() { + Integer count = jdbc.queryForObject("SELECT count(*) FROM outbox_event", Integer.class); + return count == null ? 0 : count; + } + + private static String sha256Hex(String content) { + try { + return HexFormat.of() + .formatHex( + MessageDigest.getInstance("SHA-256") + .digest(content.getBytes(StandardCharsets.UTF_8))); + } catch (NoSuchAlgorithmException impossible) { + throw new IllegalStateException(impossible); + } + } +} diff --git a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/h2/H2ClaimSqlTest.java b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/h2/H2ClaimSqlTest.java index e2dcad91..5bd42c6b 100644 --- a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/h2/H2ClaimSqlTest.java +++ b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/h2/H2ClaimSqlTest.java @@ -2,6 +2,7 @@ package dev.caskeleton.adapter.outbound.persistence.h2; import static org.assertj.core.api.Assertions.assertThat; +import dev.caskeleton.adapter.outbound.persistence.outbox.OutboxEventJpaRepository; import dev.caskeleton.adapter.outbound.persistence.outbox.entity.OutboxEventEntity; import jakarta.persistence.EntityManager; import jakarta.persistence.EntityManagerFactory; @@ -13,6 +14,7 @@ import org.junit.jupiter.api.AfterAll; import org.junit.jupiter.api.BeforeAll; import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.Test; +import org.springframework.data.jpa.repository.Query; import org.springframework.jdbc.datasource.DriverManagerDataSource; import org.springframework.orm.jpa.EntityManagerFactoryUtils; import org.springframework.orm.jpa.JpaTransactionManager; @@ -111,6 +113,66 @@ class H2ClaimSqlTest { assertThat(claimEligible(now, 10)).isEmpty(); } + @Test + void claimsCanonicalEventsSharingAnOccurredAtOneAtATimeInAggregateOrder() { + // given + inTransaction( + entityManager -> { + entityManager.persist(canonical("seq-1-idx-1", 1, 1)); + entityManager.persist(canonical("seq-2-idx-0", 2, 0)); + entityManager.persist(canonical("seq-1-idx-0", 1, 0)); + return null; + }); + + // when + List claimed = claimEligible(now, 10); + + // then + assertThat(claimed).extracting(OutboxEventEntity::getEventId).containsExactly("seq-1-idx-0"); + } + + @Test + void theReaperBatchDeleteRunsOnH2AndStopsAtItsLimit() throws NoSuchMethodException { + // given + inTransaction( + entityManager -> { + for (int index = 0; index < 3; index++) { + OutboxEventEntity published = event("evt-" + index, "agg-" + index, now, now); + published.setStatus("PUBLISHED"); + entityManager.persist(published); + } + return null; + }); + String delete = + OutboxEventJpaRepository.class + .getMethod("deletePublishedBatch", Instant.class, int.class) + .getAnnotation(Query.class) + .value(); + + // when + Integer deleted = + inTransaction( + entityManager -> + entityManager + .createNativeQuery(delete) + .setParameter("cutoff", now.plusSeconds(1)) + .setParameter("limit", 2) + .executeUpdate()); + + // then + assertThat(deleted).isEqualTo(2); + } + + private OutboxEventEntity canonical(String eventId, long sequence, int eventIndex) { + OutboxEventEntity entity = event(eventId, "worklog-42", now.minusSeconds(60), now); + entity.setContractId("portfolio.worklog.reserved"); + entity.setTenantScope("tenant-a"); + entity.setAggregateType("worklog"); + entity.setAggregateSequence(sequence); + entity.setEventIndex(eventIndex); + return entity; + } + private List claimEligible(Instant asOf, int limit) { return inTransaction( entityManager -> new H2OutboxClaimRepository(entityManager).claimEligible(asOf, limit)); diff --git a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/notification/platform/inbox/InboxItemEntityTest.java b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/notification/platform/inbox/InboxItemEntityTest.java new file mode 100644 index 00000000..6f7dbe38 --- /dev/null +++ b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/notification/platform/inbox/InboxItemEntityTest.java @@ -0,0 +1,46 @@ +package dev.caskeleton.adapter.outbound.persistence.notification.platform.inbox; + +import static org.assertj.core.api.Assertions.assertThat; + +import java.time.Instant; +import java.util.List; +import java.util.UUID; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.ValueSource; + +class InboxItemEntityTest { + + private static final Instant CREATED = Instant.parse("2026-08-15T00:00:00Z"); + private static final Instant LATER = CREATED.plusSeconds(60); + + @ParameterizedTest + @ValueSource(strings = {"ARCHIVED", "EXPIRED", "DELETED"}) + void markReadLeavesAnItemThatLeftTheInboxWhereItIs(String state) { + // given + InboxItemEntity item = item(state); + + // when + boolean changed = item.markRead(LATER); + + // then + assertThat(List.of(changed, item.state())).containsExactly(false, state); + } + + @ParameterizedTest + @ValueSource(strings = {"ARCHIVED", "EXPIRED", "DELETED"}) + void markSeenLeavesAnItemThatLeftTheInboxWhereItIs(String state) { + // given + InboxItemEntity item = item(state); + + // when + boolean changed = item.markSeen(LATER); + + // then + assertThat(List.of(changed, item.state())).containsExactly(false, state); + } + + private static InboxItemEntity item(String state) { + return new InboxItemEntity( + UUID.randomUUID(), "tenant-a", "user-1", null, "transactional", "{}", state, CREATED, null); + } +} diff --git a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/outbox/CanonicalOutboxAppendAdapterTest.java b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/outbox/CanonicalOutboxAppendAdapterTest.java index d54b4a49..a07300a9 100644 --- a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/outbox/CanonicalOutboxAppendAdapterTest.java +++ b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/outbox/CanonicalOutboxAppendAdapterTest.java @@ -2,6 +2,7 @@ package dev.caskeleton.adapter.outbound.persistence.outbox; import static org.assertj.core.api.Assertions.assertThat; import static org.assertj.core.api.Assertions.assertThatThrownBy; +import static org.assertj.core.api.Assertions.catchThrowable; import static org.mockito.ArgumentCaptor.forClass; import static org.mockito.Mockito.mock; import static org.mockito.Mockito.verify; @@ -18,8 +19,11 @@ import dev.caskeleton.application.messaging.event.ValidatedIntegrationEvent; import java.nio.charset.StandardCharsets; import java.time.Instant; import java.util.Optional; +import org.junit.jupiter.api.AfterEach; +import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.Test; import org.mockito.ArgumentCaptor; +import org.springframework.transaction.support.TransactionSynchronizationManager; class CanonicalOutboxAppendAdapterTest { @@ -28,6 +32,31 @@ class CanonicalOutboxAppendAdapterTest { private final OutboxEventJpaRepository repository = mock(OutboxEventJpaRepository.class); private final CanonicalOutboxAppendAdapter adapter = new CanonicalOutboxAppendAdapter(repository); + @BeforeEach + void openCallerTransactionBoundary() { + TransactionSynchronizationManager.setActualTransactionActive(true); + } + + @AfterEach + void clearCallerTransactionBoundary() { + TransactionSynchronizationManager.clear(); + } + + @Test + void appendOutsideACallerTransactionIsRefusedBeforeAnyWrite() { + // given + TransactionSynchronizationManager.setActualTransactionActive(false); + ValidatedIntegrationEvent event = event("{}".getBytes(StandardCharsets.UTF_8)); + + // when + Throwable thrown = catchThrowable(() -> adapter.append(event)); + + // then + assertThat(thrown) + .isInstanceOf(IllegalStateException.class) + .hasMessage("outbox append requires an active caller transaction"); + } + @Test void appendPersistsExactCanonicalMetadataAndLegacyCompatibilityProjection() { byte[] exactEnvelope = @@ -63,7 +92,7 @@ class CanonicalOutboxAppendAdapterTest { assertThat(entity.getEnvelopeBytes()).containsExactly(exactEnvelope); assertThat(entity.getContentType()).isEqualTo("application/json"); assertThat(entity.getSchemaSetHash()).isEqualTo("1".repeat(64)); - assertThat(entity.getEnvelopeSha256()).isEqualTo("2".repeat(64)); + assertThat(entity.getEnvelopeSha256()).isEqualTo(Sha256.of(exactEnvelope).toString()); assertThat(entity.getEnvelopeSchemaHash()).isEqualTo("3".repeat(64)); assertThat(entity.getPayloadSchemaHash()).isEqualTo("4".repeat(64)); assertThat(entity.getContractCatalogRevision()).isEqualTo("catalog-r1"); @@ -101,7 +130,7 @@ class CanonicalOutboxAppendAdapterTest { envelopeBytes, "application/json", sha("1"), - sha("2"), + Sha256.of(envelopeBytes), sha("3"), sha("4"), "catalog-r1", diff --git a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/outbox/OutboxReaperTest.java b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/outbox/OutboxReaperTest.java index 7e27d412..471c1f5c 100644 --- a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/outbox/OutboxReaperTest.java +++ b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/outbox/OutboxReaperTest.java @@ -2,6 +2,8 @@ package dev.caskeleton.adapter.outbound.persistence.outbox; import static org.assertj.core.api.Assertions.assertThat; import static org.mockito.Mockito.mock; +import static org.mockito.Mockito.times; +import static org.mockito.Mockito.verify; import static org.mockito.Mockito.when; import java.time.Clock; @@ -11,35 +13,56 @@ import java.time.ZoneOffset; import org.junit.jupiter.api.Test; /** - * Unit tests for {@link OutboxReaper} — verifies that the bulk delete is driven by {@code - * clock.instant() - retention} and that the return value is propagated. + * Unit tests for {@link OutboxReaper}: the cutoff is {@code clock.instant() - retention}, and the + * delete runs in bounded batches until one comes back short. * - *

Real TTL / SQL behaviour is covered by the Task E PG contract tests. + *

The repository is a Spring Data boundary, so Mockito stands in for it. The SQL itself runs + * against PostgreSQL in {@code PostgreSqlOutboxClaimAndMaintenanceIntegrationTest}. */ class OutboxReaperTest { private static final Instant NOW = Instant.parse("2026-06-11T10:00:00Z"); private static final Duration RETENTION = Duration.ofDays(7); + private static final Instant CUTOFF = NOW.minus(RETENTION); + private static final int BATCH = OutboxReaper.BATCH_SIZE; + + private final OutboxEventJpaRepository repository = mock(OutboxEventJpaRepository.class); + private final OutboxReaper reaper = + new OutboxReaper(repository, Clock.fixed(NOW, ZoneOffset.UTC), RETENTION); @Test - void reapDeletesPublishedRowsOlderThanRetentionCutoff() { - OutboxEventJpaRepository repo = mock(OutboxEventJpaRepository.class); - Instant cutoff = NOW.minus(RETENTION); - when(repo.deletePublishedBefore(cutoff)).thenReturn(5); + void reapKeepsDeletingBatchesUntilOneComesBackShortAndReturnsTheTotal() { + // given + when(repository.deletePublishedBatch(CUTOFF, BATCH)).thenReturn(BATCH, BATCH, 1); - OutboxReaper reaper = new OutboxReaper(repo, Clock.fixed(NOW, ZoneOffset.UTC), RETENTION); + // when + int purged = reaper.reap(); - assertThat(reaper.reap()).isEqualTo(5); + // then + assertThat(purged).isEqualTo(2 * BATCH + 1); } @Test - void reapReturnsZeroWhenNothingToDelete() { - OutboxEventJpaRepository repo = mock(OutboxEventJpaRepository.class); - Instant cutoff = NOW.minus(RETENTION); - when(repo.deletePublishedBefore(cutoff)).thenReturn(0); + void eachBatchIsItsOwnDeleteStatement() { + // given + when(repository.deletePublishedBatch(CUTOFF, BATCH)).thenReturn(BATCH, BATCH, 1); - OutboxReaper reaper = new OutboxReaper(repo, Clock.fixed(NOW, ZoneOffset.UTC), RETENTION); + // when + var unused = reaper.reap(); - assertThat(reaper.reap()).isEqualTo(0); + // then + verify(repository, times(3)).deletePublishedBatch(CUTOFF, BATCH); + } + + @Test + void reapReturnsZeroWhenNothingIsOldEnough() { + // given + when(repository.deletePublishedBatch(CUTOFF, BATCH)).thenReturn(0); + + // when + int purged = reaper.reap(); + + // then + assertThat(purged).isZero(); } } diff --git a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/outbox/OutboxStoreAdapterTest.java b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/outbox/OutboxStoreAdapterTest.java index 1d9f544c..fd7f6de1 100644 --- a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/outbox/OutboxStoreAdapterTest.java +++ b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/outbox/OutboxStoreAdapterTest.java @@ -12,6 +12,7 @@ import static org.mockito.Mockito.verify; import static org.mockito.Mockito.when; import dev.caskeleton.adapter.outbound.persistence.outbox.entity.OutboxEventEntity; +import dev.caskeleton.application.messaging.contract.Sha256; import dev.caskeleton.application.outbox.CanonicalClaimedOutboxEvent; import dev.caskeleton.application.outbox.NewOutboxEvent; import dev.caskeleton.application.outbox.OutboxCompletion; @@ -120,7 +121,7 @@ class OutboxStoreAdapterTest { e.setEnvelopeBytes(envelope); e.setContentType("application/json"); e.setSchemaSetHash("1".repeat(64)); - e.setEnvelopeSha256("2".repeat(64)); + e.setEnvelopeSha256(Sha256.of(envelope).toString()); e.setEnvelopeSchemaHash("3".repeat(64)); e.setPayloadSchemaHash("4".repeat(64)); e.setContractCatalogRevision("catalog-r1"); @@ -241,16 +242,39 @@ class OutboxStoreAdapterTest { assertThat(result.attemptCount()).isEqualTo(1); } + /** + * Partial canonical metadata still fails closed — it is never downgraded to a legacy claim — but + * it fails that one row. Throwing out of the claim rolled the whole batch back, and the next + * claim selected the same row first, so one bad row stopped the relay for good. + */ @Test - void claimBatchRejectsPartialCanonicalMetadataInsteadOfDowngradingToLegacy() { - OutboxEventEntity entity = pendingEntity("partial-canonical"); - entity.setEnvelopeVersion(1); + void claimBatchMovesAnUnreadableRowToDeadAndClaimsTheRestOfTheBatch() { + // given + OutboxEventEntity partial = pendingEntity("partial-canonical"); + partial.setEnvelopeVersion(1); + when(claimRepo.claimEligible(eq(NOW), eq(2))) + .thenReturn(List.of(partial, pendingEntity("evt-readable"))); + + // when + List claimed = adapter.claimBatch(OWNER, 2, NOW, IN_FLIGHT_TIMEOUT); + + // then + assertThat(List.of(claimed.stream().map(OutboxLease::eventId).toList(), partial.getStatus())) + .containsExactly(List.of("evt-readable"), "DEAD"); + } + + @Test + void claimBatchMovesACanonicalRowWhoseStoredEnvelopeHashIsNotItsBytesHashToDead() { + // given + OutboxEventEntity entity = canonicalPendingEntity("01994e11-4d88-7000-8000-000000000001"); + entity.setEnvelopeSha256("2".repeat(64)); when(claimRepo.claimEligible(eq(NOW), eq(1))).thenReturn(List.of(entity)); - assertThatThrownBy(() -> adapter.claimBatch(OWNER, 1, NOW, IN_FLIGHT_TIMEOUT)) - .isInstanceOf(IllegalStateException.class) - .hasMessageContaining("partial canonical") - .hasMessageContaining("partial-canonical"); + // when + List claimed = adapter.claimBatch(OWNER, 1, NOW, IN_FLIGHT_TIMEOUT); + + // then + assertThat(List.of(claimed, entity.getStatus())).containsExactly(List.of(), "DEAD"); } @Test diff --git a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/startup/JpaDangerousConfigurationGuardTest.java b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/startup/JpaDangerousConfigurationGuardTest.java index f589e5cb..496c06d4 100644 --- a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/startup/JpaDangerousConfigurationGuardTest.java +++ b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/startup/JpaDangerousConfigurationGuardTest.java @@ -10,8 +10,8 @@ import org.junit.jupiter.api.Test; import org.springframework.mock.env.MockEnvironment; /** - * Plan Task 11 — the two JPA settings that quietly break production fail startup (design §15.1, - * §31). + * Plan Task 11 — a schema-mutating {@code ddl-auto} fails startup outside a local convenience + * profile (design §31). Open Session In View is {@link OpenInViewSafetyValidatorTest}'s. */ class JpaDangerousConfigurationGuardTest { @@ -20,16 +20,10 @@ class JpaDangerousConfigurationGuardTest { JpaSafetySettings.defaults(), FlywaySchemaPolicy.standard()); @Test - @DisplayName("production rejects open-session-in-view and a schema-mutating ddl-auto") - void productionRejectsOpenSessionInViewAndDdlUpdate() { - MockEnvironment openInView = environment("prod"); - openInView.setProperty(JpaDangerousConfigurationGuard.OPEN_IN_VIEW_KEY, "true"); - assertThatThrownBy(() -> guard.validate(openInView)) - .isInstanceOf(IllegalStateException.class) - .hasMessageContaining(JpaDangerousConfigurationGuard.OPEN_IN_VIEW_KEY); - + void productionRejectsASchemaMutatingDdlAuto() { MockEnvironment ddlUpdate = environment("prod"); ddlUpdate.setProperty(JpaDangerousConfigurationGuard.DDL_AUTO_KEY, "update"); + assertThatThrownBy(() -> guard.validate(ddlUpdate)) .isInstanceOf(IllegalStateException.class) .hasMessageContaining("Flyway owns schema change"); @@ -39,16 +33,14 @@ class JpaDangerousConfigurationGuardTest { @DisplayName("staging is held to the same rule as production") void stagingIsHeldToTheSameRule() { MockEnvironment staging = environment("staging"); - staging.setProperty(JpaDangerousConfigurationGuard.OPEN_IN_VIEW_KEY, "true"); + staging.setProperty(JpaDangerousConfigurationGuard.DDL_AUTO_KEY, "update"); assertThatThrownBy(() -> guard.validate(staging)).isInstanceOf(IllegalStateException.class); } @Test - @DisplayName("a local convenience profile may keep open-session-in-view on") - void localConvenienceProfileMayEnableOpenSessionInView() { + void localConvenienceProfileMayUseASchemaMutatingDdlAuto() { MockEnvironment local = environment("local"); - local.setProperty(JpaDangerousConfigurationGuard.OPEN_IN_VIEW_KEY, "true"); local.setProperty(JpaDangerousConfigurationGuard.DDL_AUTO_KEY, "update"); assertThatCode(() -> guard.validate(local)).doesNotThrowAnyException(); @@ -58,7 +50,7 @@ class JpaDangerousConfigurationGuardTest { @DisplayName("a profile set mixing local and production is not local convenience") void mixedProfileSetIsNotLocalConvenience() { MockEnvironment mixed = environment("local", "prod"); - mixed.setProperty(JpaDangerousConfigurationGuard.OPEN_IN_VIEW_KEY, "true"); + mixed.setProperty(JpaDangerousConfigurationGuard.DDL_AUTO_KEY, "update"); assertThatThrownBy(() -> guard.validate(mixed)).isInstanceOf(IllegalStateException.class); } @@ -67,7 +59,7 @@ class JpaDangerousConfigurationGuardTest { @DisplayName("no active profile is not local convenience either") void noActiveProfileIsNotLocalConvenience() { MockEnvironment none = new MockEnvironment(); - none.setProperty(JpaDangerousConfigurationGuard.OPEN_IN_VIEW_KEY, "true"); + none.setProperty(JpaDangerousConfigurationGuard.DDL_AUTO_KEY, "update"); assertThatThrownBy(() -> guard.validate(none)).isInstanceOf(IllegalStateException.class); } @@ -82,12 +74,6 @@ class JpaDangerousConfigurationGuardTest { } } - @Test - @DisplayName("an absent open-in-view property is left to the framework default") - void absentOpenInViewIsNotRejected() { - assertThatCode(() -> guard.validate(environment("prod"))).doesNotThrowAnyException(); - } - private static MockEnvironment environment(String... profiles) { MockEnvironment environment = new MockEnvironment(); environment.setActiveProfiles(profiles); diff --git a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/startup/OpenInViewSafetyValidatorTest.java b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/startup/OpenInViewSafetyValidatorTest.java index ef3ecdbd..51daadff 100644 --- a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/startup/OpenInViewSafetyValidatorTest.java +++ b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/startup/OpenInViewSafetyValidatorTest.java @@ -34,6 +34,17 @@ class OpenInViewSafetyValidatorTest { }); } + @Test + void openInViewTrueFailsStartupUnderALocalConvenienceProfileToo() { + runner + .withPropertyValues("spring.jpa.open-in-view=true", "spring.profiles.active=local") + .run( + context -> + assertThat(context.getStartupFailure()) + .isInstanceOf(StartupValidationException.class) + .hasStackTraceContaining("must be false")); + } + @Test void openInViewFalseStartsCleanly() { runner diff --git a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/transaction/SpringTransactionPortTest.java b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/transaction/SpringTransactionPortTest.java index f8626b2f..19a428ef 100644 --- a/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/transaction/SpringTransactionPortTest.java +++ b/src/adapter/outbound/persistence-jpa/src/test/java/dev/caskeleton/adapter/outbound/persistence/transaction/SpringTransactionPortTest.java @@ -159,6 +159,20 @@ class SpringTransactionPortTest { // ---- feature-transaction-concurrency-contract D3: vendor default isolation is forbidden ---- + /** Compensation and recovery writes must not hold a connection indefinitely. */ + @Test + void inNewBoundsItsTransactionToThirtySeconds() { + // given + RecordingTransactionManager tm = new RecordingTransactionManager(); + SpringTransactionPort port = new SpringTransactionPort(tm); + + // when + port.inNew(() -> "ok"); + + // then + assertThat(tm.definitions.get(0).getTimeout()).isEqualTo(30); + } + @Test void everyModePinsAnExplicitIsolationNeverTheVendorDefault() { RecordingTransactionManager tm = new RecordingTransactionManager(); diff --git a/src/adapter/outbound/persistence-jpa/src/test/resources/db/applied-migrations.sha256 b/src/adapter/outbound/persistence-jpa/src/test/resources/db/applied-migrations.sha256 index 6b605c49..0f881949 100644 --- a/src/adapter/outbound/persistence-jpa/src/test/resources/db/applied-migrations.sha256 +++ b/src/adapter/outbound/persistence-jpa/src/test/resources/db/applied-migrations.sha256 @@ -23,6 +23,7 @@ c5f9c638c6d5b7768e803a23b3f16e9e0a5e09918c0838ed9c81cb6d9524ec9c jpa/notificati 50e386675474ed09bd5317d160021c0e20cb61b2db52a90bc6d86bf703e7de7b postgresql/V15__live_event_stream_position.sql 1a5983c9212d6c155f0d7bea802bd9cd9c1055f3f0b055ba4168601146eeac0d postgresql/V16__outbox_canonical_hash_columns_varchar.sql b8f571e6cada72a8f2776f4462509ce4b535c964c75b1c3cfb34b9dc07446d59 postgresql/V17__outbox_event_lease_fencing.sql +44cacbde7d1381ca5290fb8ec28005e8127ff6b453ff84277ec8d1b3293d76c8 postgresql/V18__outbox_event_unpublished_aggregate_order.sql 8ab106731d4d04d3719da0692069947736dc490ca46aa5a3ea9bdf65a5d956dc postgresql/V1__idempotency_record.sql 6b62a01a4eeb792b81015b4810ecc6f3f021e0a17dea50c871493f7694d4f0b9 postgresql/V3__outbox_event.sql c57ab8a35a10079190ad8a563be58fae4147c9406c5bb752debb6998324ccdf6 postgresql/V4__int_lock.sql diff --git a/src/adapter/outbound/persistence-mongo/README.md b/src/adapter/outbound/persistence-mongo/README.md index c6d00e86..9520dd7c 100644 --- a/src/adapter/outbound/persistence-mongo/README.md +++ b/src/adapter/outbound/persistence-mongo/README.md @@ -45,7 +45,7 @@ registry를 같은 변경에서 함께 넓힌다. ```properties ca-skeleton.persistence-mongo.enabled=true -ca-skeleton.persistence-mongo.active-profile=standard-uri +ca-skeleton.persistence-mongo.platform.active-profile=standard-uri spring.mongodb.uri=${SPRING_MONGODB_URI} ``` @@ -59,7 +59,8 @@ connection string, TLS, Stable API, socket/server-selection/operation timeout, p `active-profile`은 장식용 설정이 아니다. `MongoProfileClientSettingsAutoConfiguration`이 실제 Boot `MongoClientSettings.Builder`에 선택된 profile 하나만 적용하며, 존재하지 않는 profile 이름은 -startup/client construction 과정에서 fail-closed 된다. profile map을 하나라도 선언한 배포는 다음 +startup/client construction 과정에서 fail-closed 된다. startup 검증과 readiness도 선택된 profile 하나만 +관측한 topology와 비교한다(고르지 않은 profile은 다른 서버를 설명한다). profile map을 하나라도 선언한 배포는 다음 composition-owned bean을 함께 준비해야 한다. - `MongoCredentialResolver` — 선택된 data-plane profile의 `secret://` URI를 한 번만 resolve. @@ -76,8 +77,8 @@ composition-owned bean을 함께 준비해야 한다. ca-skeleton: persistence-mongo: enabled: true - active-profile: primary platform: + active-profile: primary profiles: primary: uri-secret: secret://mongodb/primary @@ -133,7 +134,7 @@ Mongo auto-configuration 이름을 Boot 자신의 등록 파일에서 읽어 배 없으면 기동 거부, `MongoClientGenerationRegistry`(`MongoCredentialRotationPolicy` bean이 있을 때), `MongoPlatformHealthIndicator` + health contributor -설정 키는 `ca-skeleton.persistence-mongo.enabled`, `.active-profile`, `.platform.transactions`, +설정 키는 `ca-skeleton.persistence-mongo.enabled`, `.platform.active-profile`, `.platform.transactions`, `.platform.required-secondaries`, `.platform.profiles..*`(위 예시의 14개)뿐이다. ## 라이브러리 API — 서비스의 어댑터 leaf에서 `implementation`으로 받아 직접 호출 diff --git a/src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/MongoDefaultsEnvironmentPostProcessor.java b/src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/MongoDefaultsEnvironmentPostProcessor.java index 7d5194b2..ac81340e 100644 --- a/src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/MongoDefaultsEnvironmentPostProcessor.java +++ b/src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/MongoDefaultsEnvironmentPostProcessor.java @@ -44,7 +44,7 @@ public class MongoDefaultsEnvironmentPostProcessor implements EnvironmentPostPro static final String SWITCH = "ca-skeleton.persistence-mongo.enabled"; - static final String ACTIVE_PROFILE = "ca-skeleton.persistence-mongo.active-profile"; + static final String ACTIVE_PROFILE = "ca-skeleton.persistence-mongo.platform.active-profile"; private static final String EXCLUDE = "spring.autoconfigure.exclude"; diff --git a/src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/autoconfigure/MongoPlatformHealthIndicator.java b/src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/autoconfigure/MongoPlatformHealthIndicator.java index 5c700231..d7fd49d1 100644 --- a/src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/autoconfigure/MongoPlatformHealthIndicator.java +++ b/src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/autoconfigure/MongoPlatformHealthIndicator.java @@ -53,7 +53,7 @@ public final class MongoPlatformHealthIndicator { return !topologyMismatch(); } - /** True when the observed topology differs from what any profile declared. */ + /** True when the observed topology differs from what the active profile declared. */ public boolean topologyMismatch() { return topologyMismatch(probe.observation()); } @@ -80,12 +80,17 @@ public final class MongoPlatformHealthIndicator { details.put("availableSecondaries", observation.availableSecondaries()); details.put("requiredSecondaries", properties.requiredSecondaries()); details.put("profiles", properties.profiles().keySet()); + details.put("activeProfile", properties.activeProfile()); return Map.copyOf(details); } + // Only the active profile describes the server this instance talks to; comparing every declared + // profile kept readiness down for as long as a profile nobody selected named another topology. private boolean topologyMismatch(MongoTopologyProbe.Observation observation) { - return properties.profiles().values().stream() - .anyMatch(profile -> profile.topology() != observation.observedTopology()); + return properties + .active() + .map(profile -> profile.topology() != observation.observedTopology()) + .orElse(false); } private boolean degradedSecondaryAvailability(MongoTopologyProbe.Observation observation) { diff --git a/src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/autoconfigure/MongoPlatformSettings.java b/src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/autoconfigure/MongoPlatformSettings.java index 1d2ac008..631c45a4 100644 --- a/src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/autoconfigure/MongoPlatformSettings.java +++ b/src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/autoconfigure/MongoPlatformSettings.java @@ -4,6 +4,7 @@ import dev.caskeleton.adapter.outbound.mongo.api.DatabaseProfileName; import dev.caskeleton.adapter.outbound.mongo.api.error.MongoOperationRejectedException; import java.util.Map; import java.util.Objects; +import java.util.Optional; import org.springframework.boot.context.properties.ConfigurationProperties; /** @@ -20,9 +21,17 @@ import org.springframework.boot.context.properties.ConfigurationProperties; *

{@code transactions} is a subordinate switch, off until a deployment asks for it; when on, the * startup validator verifies the data-plane credential's real replica-set capability rather than * assuming it. + * + *

{@code activeProfile} names the one profile this deployment uses, bound here once so the + * client customizer, the startup validator and the health view all read the same name. It used to + * be read as a raw property by the customizer only, and the validator and health view compared + * every declared profile with the server — so a replica-set {@code primary} declared next to a + * standalone {@code local} failed startup, or kept readiness down, on account of a profile nobody + * selected. */ @ConfigurationProperties("ca-skeleton.persistence-mongo.platform") public record MongoPlatformSettings( + String activeProfile, Map profiles, boolean transactions, Integer requiredSecondaries) { @@ -38,6 +47,7 @@ public record MongoPlatformSettings( public static final int DEFAULT_REQUIRED_SECONDARIES = 2; public MongoPlatformSettings { + activeProfile = activeProfile == null ? "" : activeProfile.trim(); // Absent rather than empty is the normal case: a deployment that has opted the module in but // configured no platform profile yet must still start, so binding treats "no profiles" as an // empty map instead of a binding failure. @@ -57,15 +67,23 @@ public record MongoPlatformSettings( /** An empty configuration, for a deployment that has not opted the platform in. */ public static MongoPlatformSettings empty() { - return new MongoPlatformSettings(Map.of(), false, null); + return new MongoPlatformSettings("", Map.of(), false, null); + } + + /** The selected profile, empty when no configured profile has the active name. */ + public Optional active() { + return Optional.ofNullable(profiles.get(activeProfile)); } /** - * Validates every profile and its name. + * Validates every profile and its name, and that a declared profile set selects one of them. * * @throws MongoOperationRejectedException naming the offending profile */ public void validate() { + if (!profiles.isEmpty()) { + require(activeProfile); + } profiles.forEach( (name, profile) -> { try { diff --git a/src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/autoconfigure/MongoStartupValidator.java b/src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/autoconfigure/MongoStartupValidator.java index 1e17868e..e1f787fc 100644 --- a/src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/autoconfigure/MongoStartupValidator.java +++ b/src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/autoconfigure/MongoStartupValidator.java @@ -62,11 +62,13 @@ public final class MongoStartupValidator { requireSupportedSchemaRange(); } + /** The active profile only: the others describe servers this deployment is not connected to. */ private void requireDeclaredTopologyMatchesReality() { + String name = properties.activeProfile(); properties - .profiles() - .forEach( - (name, profile) -> { + .active() + .ifPresent( + profile -> { if (profile.production() && probe.observedTopology() == MongoTopology.STANDALONE) { throw MongoOperationRejectedException.of( "startup.topology", diff --git a/src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/client/MongoProfileClientSettingsAutoConfiguration.java b/src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/client/MongoProfileClientSettingsAutoConfiguration.java index f0411e7f..0471bc26 100644 --- a/src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/client/MongoProfileClientSettingsAutoConfiguration.java +++ b/src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/client/MongoProfileClientSettingsAutoConfiguration.java @@ -16,7 +16,6 @@ import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; import org.springframework.boot.mongodb.autoconfigure.MongoClientSettingsBuilderCustomizer; import org.springframework.context.annotation.Bean; import org.springframework.core.Ordered; -import org.springframework.core.env.Environment; /** Connects the typed Mongo profile to Spring Boot's actual driver builder. */ @AutoConfiguration( @@ -62,26 +61,19 @@ class MongoProfileClientSettingsAutoConfiguration { @Bean("mongoProfileClientSettingsCustomizer") @ConditionalOnMissingBean(name = "mongoProfileClientSettingsCustomizer") MongoClientSettingsBuilderCustomizer mongoProfileClientSettingsCustomizer( - MongoPlatformSettings settings, - ObjectProvider credentialResolvers, - Environment environment) { - String activeProfile = - environment.getProperty("ca-skeleton.persistence-mongo.active-profile", "").trim(); - return new OrderedProfileCustomizer(settings, activeProfile, credentialResolvers); + MongoPlatformSettings settings, ObjectProvider credentialResolvers) { + return new OrderedProfileCustomizer(settings, credentialResolvers); } private static final class OrderedProfileCustomizer implements MongoClientSettingsBuilderCustomizer, Ordered { private final MongoPlatformSettings settings; - private final String activeProfile; private final ObjectProvider credentialResolvers; private OrderedProfileCustomizer( MongoPlatformSettings settings, - String activeProfile, ObjectProvider credentialResolvers) { this.settings = Objects.requireNonNull(settings, "settings"); - this.activeProfile = Objects.requireNonNull(activeProfile, "activeProfile"); this.credentialResolvers = Objects.requireNonNull(credentialResolvers, "credentialResolvers"); } @@ -95,7 +87,8 @@ class MongoProfileClientSettingsAutoConfiguration { throw new IllegalStateException( "MongoDB typed profiles are configured but no MongoCredentialResolver bean is available"); } - new MongoClientSettingsFactory(settings, activeProfile, resolver).customize(builder); + new MongoClientSettingsFactory(settings, settings.activeProfile(), resolver) + .customize(builder); } @Override diff --git a/src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/imperative/bulk/MongoBulkExecutor.java b/src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/imperative/bulk/MongoBulkExecutor.java index f9a7eb1d..098c64f6 100644 --- a/src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/imperative/bulk/MongoBulkExecutor.java +++ b/src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/imperative/bulk/MongoBulkExecutor.java @@ -10,6 +10,7 @@ import com.mongodb.client.model.WriteModel; import dev.caskeleton.adapter.outbound.mongo.api.MongoOperationContext; import dev.caskeleton.adapter.outbound.mongo.api.MongoOperationType; import dev.caskeleton.adapter.outbound.mongo.api.error.MongoFailureCategory; +import dev.caskeleton.adapter.outbound.mongo.api.error.MongoOperationRejectedException; import dev.caskeleton.adapter.outbound.mongo.imperative.DefaultMongoImperativeExecutor; import dev.caskeleton.adapter.outbound.mongo.imperative.atomic.MongoAtomicPolicy; import dev.caskeleton.adapter.outbound.mongo.imperative.atomic.MongoAtomicPolicyRegistry; @@ -18,6 +19,13 @@ import java.util.List; import java.util.Objects; import java.util.concurrent.TimeUnit; import org.bson.Document; +import org.bson.RawBsonDocument; +import org.bson.codecs.Codec; +import org.bson.codecs.configuration.CodecRegistry; +import org.springframework.data.mongodb.core.convert.MongoConverter; +import org.springframework.data.mongodb.core.convert.QueryMapper; +import org.springframework.data.mongodb.core.convert.UpdateMapper; +import org.springframework.data.mongodb.core.mapping.MongoPersistentEntity; /** * Executes a bulk plan and preserves what actually happened to each item (design §19.2). @@ -51,9 +59,16 @@ public final class MongoBulkExecutor { this.policies = Objects.requireNonNull(policies, "policies"); } - /** Runs one bulk plan against the operation's collection. */ - public MongoBulkResult execute(MongoOperationContext context, MongoBulkWritePlan plan) { + /** + * Runs one bulk plan against the operation's collection. + * + * @param documentType the mapped document class, whose {@code @Field} names and conversions apply + * to every filter and update — the same mapping the atomic path applies to one document + */ + public MongoBulkResult execute( + MongoOperationContext context, Class documentType, MongoBulkWritePlan plan) { Objects.requireNonNull(context, "context"); + Objects.requireNonNull(documentType, "documentType"); Objects.requireNonNull(plan, "plan"); // Refused here, before anything is sent, and refused for a profile with no policy at all — @@ -70,20 +85,17 @@ public final class MongoBulkExecutor { context, MongoOperationType.BULK_WRITE, access -> { - List> writes = new ArrayList<>(plan.items().size()); - for (MongoBulkWritePlan.MongoBulkItem item : plan.items()) { - writes.add( - new UpdateOneModel<>( - item.filter().toQuery().getQueryObject(), - item.update().toUpdate().getUpdateObject(), - new UpdateOptions().upsert(item.upsert()))); - } - MongoCollection collection = access .rawOperations() .getCollection(access.collection()) .withTimeout(access.operationTimeout().toMillis(), TimeUnit.MILLISECONDS); + List> writes = + mappedWrites( + plan, + documentType, + access.rawOperations().getConverter(), + collection.getCodecRegistry()); try { var result = collection.bulkWrite( @@ -107,6 +119,51 @@ public final class MongoBulkExecutor { .orElseThrow(() -> new IllegalStateException("the bulk executor produced no result")); } + /** + * The plan as the driver will send it: mapped through the entity, and within the byte ceiling. + * + *

Mapped the way {@code MongoTemplate.updateFirst(query, update, type, collection)} maps a + * single update, so a {@code @Field} name and a registered converter mean the same thing in a + * batch as for one document. Measured on the mapped documents with the collection's own codecs, + * because only those have the BSON form the server will receive. + */ + static List> mappedWrites( + MongoBulkWritePlan plan, + Class documentType, + MongoConverter converter, + CodecRegistry codecs) { + QueryMapper queries = new QueryMapper(converter); + UpdateMapper updates = new UpdateMapper(converter); + MongoPersistentEntity entity = + converter.getMappingContext().getPersistentEntity(documentType); + Codec codec = codecs.get(Document.class); + + List> writes = new ArrayList<>(plan.items().size()); + long encoded = 0; + for (MongoBulkWritePlan.MongoBulkItem item : plan.items()) { + Document filter = queries.getMappedObject(item.filter().toQuery().getQueryObject(), entity); + Document update = updates.getMappedObject(item.update().toUpdate().getUpdateObject(), entity); + // Per-item command framing on top of the two documents: operation wrapper, flags, names. + encoded += encodedBytes(filter, codec) + encodedBytes(update, codec) + 64; + writes.add(new UpdateOneModel<>(filter, update, new UpdateOptions().upsert(item.upsert()))); + } + if (encoded > MongoBulkWritePlan.MAX_ENCODED_BYTES) { + throw MongoOperationRejectedException.of( + "bulk.plan", + "this plan encodes to about " + + encoded + + " bytes, above the ceiling of " + + MongoBulkWritePlan.MAX_ENCODED_BYTES + + "; split it into smaller plans, which preserves ordered semantics, rather than" + + " letting the server refuse the whole command"); + } + return writes; + } + + private static long encodedBytes(Document document, Codec codec) { + return new RawBsonDocument(document, codec).getByteBuffer().remaining(); + } + private static MongoBulkResult toPartialResult( MongoBulkWritePlan plan, MongoBulkWriteException failure) { List failures = new ArrayList<>(); diff --git a/src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/imperative/bulk/MongoBulkWritePlan.java b/src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/imperative/bulk/MongoBulkWritePlan.java index 3a870028..4bd7adb3 100644 --- a/src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/imperative/bulk/MongoBulkWritePlan.java +++ b/src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/imperative/bulk/MongoBulkWritePlan.java @@ -13,6 +13,11 @@ import java.util.Objects; *

The item ceiling is enforced when the plan is built rather than when it is sent. A batch * assembled in a loop grows with its input, and the first sign that the input got larger should not * be a 16 MiB command rejected by the server after the whole batch was serialized. + * + *

The byte ceiling is enforced by {@link MongoBulkExecutor}, on the mapped documents, before + * anything is sent. A plan holds domain values — a {@code DomainDocumentId}, a {@code BigInteger} — + * that only have a BSON form once the entity's mapping has converted them, so a plan cannot measure + * itself. */ public record MongoBulkWritePlan(MongoBulkMode mode, List items) { @@ -41,36 +46,6 @@ public record MongoBulkWritePlan(MongoBulkMode mode, List items) "bulk.plan", "a bulk plan of " + items.size() + " items is above the ceiling of " + MAX_ITEMS); } - long encoded = estimatedEncodedBytes(items); - if (encoded > MAX_ENCODED_BYTES) { - throw MongoOperationRejectedException.of( - "bulk.plan", - "this plan encodes to about " - + encoded - + " bytes, above the ceiling of " - + MAX_ENCODED_BYTES - + "; split it into smaller plans, which preserves ordered semantics, rather than" - + " letting the server refuse the whole command"); - } - } - - /** - * A conservative estimate of the encoded command size. - * - *

Estimated rather than measured because measuring means encoding, and encoding the batch to - * find out it is too large is the cost this avoids. The estimate is deliberately an - * over-estimate: refusing a plan that would have fit is a smaller failure than sending one that - * does not. - */ - public static long estimatedEncodedBytes(List items) { - long total = 0; - for (MongoBulkItem item : items) { - total += item.filter().toQuery().getQueryObject().toJson().length(); - total += item.update().toUpdate().getUpdateObject().toJson().length(); - // Per-item command framing: operation wrapper, flags, field names. - total += 64; - } - return total; } /** Starts a plan. */ diff --git a/src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/migration/MongoCollectionMigrationLock.java b/src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/migration/MongoCollectionMigrationLock.java index f9170f82..cca219af 100644 --- a/src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/migration/MongoCollectionMigrationLock.java +++ b/src/adapter/outbound/persistence-mongo/src/main/java/dev/caskeleton/adapter/outbound/mongo/migration/MongoCollectionMigrationLock.java @@ -1,5 +1,6 @@ package dev.caskeleton.adapter.outbound.mongo.migration; +import com.mongodb.ErrorCategory; import com.mongodb.MongoWriteException; import com.mongodb.client.MongoCollection; import com.mongodb.client.MongoDatabase; @@ -100,7 +101,9 @@ public final class MongoCollectionMigrationLock implements MongoMigrationLock { } // No document yet: the insert is the acquisition. A duplicate key means another runner won - // the race, which is the correct answer rather than an error to surface. + // the race, which is the correct answer rather than an error to surface. Any other write error + // (validation, authorization, disk) is not a race, and reporting it as "someone else holds the + // lease" would make every runner wait on a lease nobody holds. try { locks.insertOne( new Document("_id", LOCK_ID) @@ -109,8 +112,11 @@ public final class MongoCollectionMigrationLock implements MongoMigrationLock { .append("expiresAt", Date.from(now.plus(leaseDuration))) .append("fence", 1L)); return Optional.of(new MongoCollectionMigrationLock(locks, owner, clock, 1L)); - } catch (MongoWriteException lostTheRace) { - return Optional.empty(); + } catch (MongoWriteException writeFailure) { + if (writeFailure.getError().getCategory() == ErrorCategory.DUPLICATE_KEY) { + return Optional.empty(); + } + throw writeFailure; } } diff --git a/src/adapter/outbound/persistence-mongo/src/main/resources/config/mongo.yml b/src/adapter/outbound/persistence-mongo/src/main/resources/config/mongo.yml index 65272145..ffab45de 100644 --- a/src/adapter/outbound/persistence-mongo/src/main/resources/config/mongo.yml +++ b/src/adapter/outbound/persistence-mongo/src/main/resources/config/mongo.yml @@ -7,9 +7,11 @@ ca-skeleton: persistence-mongo: # true | false — 모듈이 있으면 켜진다. false 로 끄면 Spring Boot 의 Mongo 자동 설정도 함께 빠진다. enabled: ${APP_PERSISTENCE_MONGO_ENABLED:true} - # 켠 상태에서 비어 있으면 안 된다. profile 은 정확히 하나: client 하나와 pool 하나만 만들고, - # 고르지 않은 profile 의 secret 은 해석하지 않는다. - active-profile: ${APP_PERSISTENCE_MONGO_ACTIVE_PROFILE:} + platform: + # 켠 상태에서 비어 있으면 안 된다. profile 은 정확히 하나: client 하나와 pool 하나만 만들고, + # 고르지 않은 profile 의 secret 은 해석하지 않는다. 기동 검사와 readiness 도 이 profile 만 + # 관측한 topology 와 비교한다. + active-profile: ${APP_PERSISTENCE_MONGO_ACTIVE_PROFILE:} # 연결 source 도 명시해야 한다. 표준 배포는 SPRING_MONGODB_URI(Boot 4 -> spring.mongodb.uri)를 # 준다. typed-profile 배포는 대신 # ca-skeleton.persistence-mongo.platform.profiles..uri-secret 을 준다 @@ -34,3 +36,11 @@ ca-skeleton: # uuid-representation: STANDARD # tls-required: true # authentication-required: true + +# /actuator/info 에 싣는 이 모듈의 상태(management.info.env). compose smoke 가 lane 이 실제로 켠 +# capability 를 이 값으로 확인한다. 위 스위치를 해석한 값이고, 기본값은 MongoRootAutoConfiguration 의 +# matchIfMissing 과 같다. +info: + capabilities: + persistence-mongo: + enabled: ${ca-skeleton.persistence-mongo.enabled:true} diff --git a/src/adapter/outbound/persistence-mongo/src/mongoIntegrationTest/java/dev/caskeleton/adapter/outbound/mongo/migration/MongoMigrationLaneTest.java b/src/adapter/outbound/persistence-mongo/src/mongoIntegrationTest/java/dev/caskeleton/adapter/outbound/mongo/migration/MongoMigrationLaneTest.java index 8de780e5..abbcad9c 100644 --- a/src/adapter/outbound/persistence-mongo/src/mongoIntegrationTest/java/dev/caskeleton/adapter/outbound/mongo/migration/MongoMigrationLaneTest.java +++ b/src/adapter/outbound/persistence-mongo/src/mongoIntegrationTest/java/dev/caskeleton/adapter/outbound/mongo/migration/MongoMigrationLaneTest.java @@ -2,10 +2,15 @@ package dev.caskeleton.adapter.outbound.mongo.migration; import static org.assertj.core.api.Assertions.assertThat; import static org.assertj.core.api.Assertions.assertThatThrownBy; +import static org.assertj.core.api.Assertions.catchThrowable; +import com.mongodb.MongoWriteException; import com.mongodb.client.MongoClient; import com.mongodb.client.MongoClients; import com.mongodb.client.MongoDatabase; +import com.mongodb.client.model.CreateCollectionOptions; +import com.mongodb.client.model.Filters; +import com.mongodb.client.model.ValidationOptions; import dev.caskeleton.adapter.outbound.mongo.api.error.MongoOperationRejectedException; import dev.caskeleton.adapter.outbound.mongo.security.admin.MongoAdminAuthorization; import dev.caskeleton.adapter.outbound.mongo.security.admin.MongoAdminGateway; @@ -21,6 +26,7 @@ import java.util.List; import java.util.Optional; import java.util.Set; import java.util.concurrent.atomic.AtomicInteger; +import org.bson.BsonType; import org.bson.Document; import org.junit.jupiter.api.AfterAll; import org.junit.jupiter.api.BeforeAll; @@ -234,6 +240,28 @@ class MongoMigrationLaneTest { .isInstanceOf(RuntimeException.class); } + @Test + void aLeaseWriteThatFailsForAnotherReasonIsRaisedRatherThanReportedAsALostRace() { + // given + MongoDatabase database = freshDatabase(); + database.createCollection( + MongoCollectionMigrationLock.DEFAULT_COLLECTION, + new CreateCollectionOptions() + .validationOptions( + new ValidationOptions().validator(Filters.type("owner", BsonType.INT32)))); + + // when + Throwable thrown = + catchThrowable( + () -> MongoCollectionMigrationLock.tryAcquire(database, "first-runner", LEASE, FIXED)); + + // then + assertThat(thrown) + .as("only a duplicate key means another runner holds the lease") + .isInstanceOf(MongoWriteException.class) + .hasMessageContaining("Document failed validation"); + } + private static MongoDatabase freshDatabase() { return client.getDatabase("migration" + DATABASE_SEQUENCE.incrementAndGet()); } diff --git a/src/adapter/outbound/persistence-mongo/src/mongoIntegrationTest/java/dev/caskeleton/adapter/outbound/mongo/rs/MongoBulkMappingLaneTest.java b/src/adapter/outbound/persistence-mongo/src/mongoIntegrationTest/java/dev/caskeleton/adapter/outbound/mongo/rs/MongoBulkMappingLaneTest.java new file mode 100644 index 00000000..a21306c9 --- /dev/null +++ b/src/adapter/outbound/persistence-mongo/src/mongoIntegrationTest/java/dev/caskeleton/adapter/outbound/mongo/rs/MongoBulkMappingLaneTest.java @@ -0,0 +1,157 @@ +package dev.caskeleton.adapter.outbound.mongo.rs; + +import static org.assertj.core.api.Assertions.assertThat; + +import com.mongodb.client.MongoClient; +import com.mongodb.client.MongoClients; +import dev.caskeleton.adapter.outbound.mongo.api.CollectionProfileName; +import dev.caskeleton.adapter.outbound.mongo.api.MongoOperationContext; +import dev.caskeleton.adapter.outbound.mongo.api.consistency.MongoConsistencyProfile; +import dev.caskeleton.adapter.outbound.mongo.api.consistency.MongoConsistencyRegistry; +import dev.caskeleton.adapter.outbound.mongo.api.mapping.DomainDocumentId; +import dev.caskeleton.adapter.outbound.mongo.api.mapping.MongoTypeRepresentationManifest; +import dev.caskeleton.adapter.outbound.mongo.api.observation.MongoOperationObserver; +import dev.caskeleton.adapter.outbound.mongo.failure.DefaultMongoFailureClassifier; +import dev.caskeleton.adapter.outbound.mongo.failure.DefaultMongoFailureTranslator; +import dev.caskeleton.adapter.outbound.mongo.imperative.DefaultMongoImperativeExecutor; +import dev.caskeleton.adapter.outbound.mongo.imperative.MongoCollectionProfileRegistry; +import dev.caskeleton.adapter.outbound.mongo.imperative.MongoConsistencyBinder; +import dev.caskeleton.adapter.outbound.mongo.imperative.atomic.AtomicFilter; +import dev.caskeleton.adapter.outbound.mongo.imperative.atomic.AtomicUpdate; +import dev.caskeleton.adapter.outbound.mongo.imperative.atomic.MongoAtomicPolicy; +import dev.caskeleton.adapter.outbound.mongo.imperative.atomic.MongoAtomicPolicyRegistry; +import dev.caskeleton.adapter.outbound.mongo.imperative.atomic.MongoUpdateOperator; +import dev.caskeleton.adapter.outbound.mongo.imperative.bulk.MongoBulkExecutor; +import dev.caskeleton.adapter.outbound.mongo.imperative.bulk.MongoBulkMode; +import dev.caskeleton.adapter.outbound.mongo.imperative.bulk.MongoBulkWritePlan; +import dev.caskeleton.adapter.outbound.mongo.mapping.MongoCustomConversionsFactory; +import dev.caskeleton.adapter.outbound.mongo.testkit.rs.MongoSingleReplicaSetContainer; +import java.math.BigInteger; +import java.time.Duration; +import org.bson.Document; +import org.junit.jupiter.api.AfterAll; +import org.junit.jupiter.api.BeforeAll; +import org.junit.jupiter.api.Tag; +import org.junit.jupiter.api.Test; +import org.springframework.data.annotation.Id; +import org.springframework.data.mongodb.core.MongoTemplate; +import org.springframework.data.mongodb.core.SimpleMongoClientDatabaseFactory; +import org.springframework.data.mongodb.core.convert.MappingMongoConverter; +import org.springframework.data.mongodb.core.convert.MongoCustomConversions; +import org.springframework.data.mongodb.core.convert.NoOpDbRefResolver; +import org.springframework.data.mongodb.core.mapping.Field; +import org.springframework.data.mongodb.core.mapping.MongoMappingContext; + +/** + * The bulk path writes what the single-document path writes: {@code @Field} names and the + * registered conversions apply, because both go through Spring Data's mapping. + */ +@Tag("mongodb-replicaset") +class MongoBulkMappingLaneTest { + + private static final CollectionProfileName ORDERS = new CollectionProfileName("orders"); + + private static final MongoOperationContext CONTEXT = + MongoOperationContext.of( + "order.bulk", + "primary", + ORDERS.value(), + MongoConsistencyProfile.PRIMARY_MAJORITY, + Duration.ofSeconds(10)); + + private static MongoSingleReplicaSetContainer mongo; + + private static MongoClient client; + + private static MongoTemplate template; + + private static MongoBulkExecutor bulk; + + /** A document whose Java names differ from its stored names and whose values need converters. */ + record Order(@Id DomainDocumentId id, @Field("st") String status, BigInteger amount) {} + + @BeforeAll + static void start() { + mongo = MongoSingleReplicaSetContainer.mongoEight(); + mongo.start(); + client = MongoClients.create(mongo.connectionString()); + template = templateWithTheManifestConversions(client); + bulk = + new MongoBulkExecutor( + new DefaultMongoImperativeExecutor( + new MongoConsistencyBinder(template, MongoConsistencyRegistry.standard()), + MongoCollectionProfileRegistry.builder().register("orders", "orders").build(), + new DefaultMongoFailureTranslator(new DefaultMongoFailureClassifier()), + MongoOperationObserver.none()), + MongoAtomicPolicyRegistry.builder() + .register( + ORDERS, + MongoAtomicPolicy.builder() + .updatable("status", MongoUpdateOperator.SET) + .updatable("amount", MongoUpdateOperator.SET) + .build()) + .build()); + } + + @AfterAll + static void stop() { + if (client != null) { + client.close(); + } + if (mongo != null) { + mongo.close(); + } + } + + @Test + void aBulkUpdateWritesTheFieldUnderItsMappedName() { + // given + template.getCollection("orders").insertOne(new Document("_id", "o-1").append("st", "NEW")); + MongoBulkWritePlan plan = + MongoBulkWritePlan.builder(MongoBulkMode.ORDERED) + .update(AtomicFilter.id("o-1"), AtomicUpdate.set("status", "PAID")) + .build(); + + // when + bulk.execute(CONTEXT, Order.class, plan); + + // then + assertThat(template.getCollection("orders").find(new Document("_id", "o-1")).first()) + .isEqualTo(new Document("_id", "o-1").append("st", "PAID")); + } + + @Test + void aBulkUpdateCarriesValuesThatNeedAConverter() { + // given + template.getCollection("orders").insertOne(new Document("_id", "o-2").append("st", "NEW")); + BigInteger amount = new BigInteger("123456789012345678901234567890"); + + // when + bulk.execute( + CONTEXT, + Order.class, + MongoBulkWritePlan.builder(MongoBulkMode.ORDERED) + .update( + AtomicFilter.id(new DomainDocumentId("o-2")), AtomicUpdate.set("amount", amount)) + .build()); + + // then + assertThat(template.findById(new DomainDocumentId("o-2"), Order.class, "orders")) + .isEqualTo(new Order(new DomainDocumentId("o-2"), "NEW", amount)); + } + + private static MongoTemplate templateWithTheManifestConversions(MongoClient client) { + SimpleMongoClientDatabaseFactory factory = + new SimpleMongoClientDatabaseFactory(client, "bulkmapping"); + MongoCustomConversions conversions = + MongoCustomConversionsFactory.forManifest(MongoTypeRepresentationManifest.standard()); + MongoMappingContext mappingContext = new MongoMappingContext(); + mappingContext.setSimpleTypeHolder(conversions.getSimpleTypeHolder()); + mappingContext.afterPropertiesSet(); + MappingMongoConverter converter = + new MappingMongoConverter(NoOpDbRefResolver.INSTANCE, mappingContext); + converter.setCustomConversions(conversions); + converter.afterPropertiesSet(); + return new MongoTemplate(factory, converter); + } +} diff --git a/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/MongoConnectionSourceRuleTest.java b/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/MongoConnectionSourceRuleTest.java index 4fbbcd25..49606c91 100644 --- a/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/MongoConnectionSourceRuleTest.java +++ b/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/MongoConnectionSourceRuleTest.java @@ -18,14 +18,16 @@ class MongoConnectionSourceRuleTest { assertThat(failure) .isInstanceOf(IllegalStateException.class) - .hasMessageContaining("ca-skeleton.persistence-mongo.active-profile"); + .hasMessageContaining("ca-skeleton.persistence-mongo.platform.active-profile"); } @Test void anOnModuleWithoutAConnectionSourceIsRefusedNamingBothSources() { Throwable failure = catchThrowable( - () -> postProcess(Map.of("ca-skeleton.persistence-mongo.active-profile", "primary"))); + () -> + postProcess( + Map.of("ca-skeleton.persistence-mongo.platform.active-profile", "primary"))); assertThat(failure) .isInstanceOf(IllegalStateException.class) @@ -45,7 +47,7 @@ class MongoConnectionSourceRuleTest { () -> postProcess( Map.of( - "ca-skeleton.persistence-mongo.active-profile", + "ca-skeleton.persistence-mongo.platform.active-profile", "primary", source, "mongodb://db.example:27017/app"))); diff --git a/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/autoconfigure/MongoPlatformHealthMeasuresTheClusterTest.java b/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/autoconfigure/MongoPlatformHealthMeasuresTheClusterTest.java index f392cb3b..a0cb3e89 100644 --- a/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/autoconfigure/MongoPlatformHealthMeasuresTheClusterTest.java +++ b/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/autoconfigure/MongoPlatformHealthMeasuresTheClusterTest.java @@ -92,7 +92,7 @@ class MongoPlatformHealthMeasuresTheClusterTest { @Test @DisplayName("a negative requirement is refused rather than read as no requirement") void aNegativeRequirementIsRefused() { - assertThatThrownBy(() -> new MongoPlatformSettings(Map.of(), false, -1)) + assertThatThrownBy(() -> new MongoPlatformSettings("", Map.of(), false, -1)) .isInstanceOf(MongoOperationRejectedException.class) .hasMessageContaining("secondary"); } @@ -106,6 +106,7 @@ class MongoPlatformHealthMeasuresTheClusterTest { private static MongoPlatformSettings settings(int requiredSecondaries) { return new MongoPlatformSettings( + "default", Map.of("default", MongoProfileProperties.production("secret://mongodb/uri")), false, requiredSecondaries); diff --git a/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/autoconfigure/MongoPlatformPropertiesTest.java b/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/autoconfigure/MongoPlatformPropertiesTest.java index ae228099..56de08c2 100644 --- a/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/autoconfigure/MongoPlatformPropertiesTest.java +++ b/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/autoconfigure/MongoPlatformPropertiesTest.java @@ -3,6 +3,7 @@ package dev.caskeleton.adapter.outbound.mongo.autoconfigure; import static org.assertj.core.api.Assertions.assertThat; import static org.assertj.core.api.Assertions.assertThatCode; import static org.assertj.core.api.Assertions.assertThatThrownBy; +import static org.assertj.core.api.Assertions.catchThrowable; import dev.caskeleton.adapter.outbound.mongo.api.error.MongoOperationRejectedException; import dev.caskeleton.adapter.outbound.mongo.api.mapping.MongoUuidRepresentation; @@ -75,7 +76,10 @@ class MongoPlatformSettingsTest { void anInvalidProfileNameIsRejectedWithTheProfileNamed() { MongoPlatformSettings properties = new MongoPlatformSettings( - Map.of("Tenant_A", MongoProfileProperties.local("secret://mongodb/uri")), false, null); + "Tenant_A", + Map.of("Tenant_A", MongoProfileProperties.local("secret://mongodb/uri")), + false, + null); assertThatThrownBy(properties::validate) .isInstanceOf(MongoOperationRejectedException.class) @@ -84,10 +88,29 @@ class MongoPlatformSettingsTest { @Test void anAbsentProfileMapBindsToAnEmptyConfiguration() { - assertThat(new MongoPlatformSettings(null, false, null).profiles()).isEmpty(); + assertThat(new MongoPlatformSettings(null, null, false, null).profiles()).isEmpty(); assertThat(MongoPlatformSettings.empty().profiles()).isEmpty(); } + @Test + void aProfileSetWhoseActiveNameMatchesNoneOfItsProfilesIsRefused() { + // given + MongoPlatformSettings properties = + new MongoPlatformSettings( + "primry", + Map.of("primary", MongoProfileProperties.local("secret://mongodb/uri")), + false, + null); + + // when + Throwable thrown = catchThrowable(properties::validate); + + // then + assertThat(thrown) + .isInstanceOf(MongoOperationRejectedException.class) + .hasMessageContaining("'primry' is not configured"); + } + @Test void anUnconfiguredProfileIsRefusedRatherThanDefaulted() { assertThatThrownBy(() -> MongoPlatformSettings.empty().require("default")) diff --git a/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/autoconfigure/MongoStartupValidatorTest.java b/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/autoconfigure/MongoStartupValidatorTest.java index bb480f27..eff8ff4f 100644 --- a/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/autoconfigure/MongoStartupValidatorTest.java +++ b/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/autoconfigure/MongoStartupValidatorTest.java @@ -3,6 +3,7 @@ package dev.caskeleton.adapter.outbound.mongo.autoconfigure; import static org.assertj.core.api.Assertions.assertThat; import static org.assertj.core.api.Assertions.assertThatCode; import static org.assertj.core.api.Assertions.assertThatThrownBy; +import static org.assertj.core.api.Assertions.catchThrowable; import dev.caskeleton.adapter.outbound.mongo.api.capability.MongoCapability; import dev.caskeleton.adapter.outbound.mongo.api.error.MongoOperationRejectedException; @@ -106,6 +107,7 @@ class MongoStartupValidatorTest { new MongoPlatformHealthIndicator( new MongoTopologyProbe(MongoTopology.SHARDED, "8.0", 2), new MongoPlatformSettings( + "default", Map.of("default", MongoProfileProperties.production("secret://mongodb/uri")), false, 2)); @@ -121,6 +123,7 @@ class MongoStartupValidatorTest { new MongoPlatformHealthIndicator( new MongoTopologyProbe(MongoTopology.REPLICA_SET, "8.0", 1), new MongoPlatformSettings( + "default", Map.of("default", MongoProfileProperties.production("secret://mongodb/uri")), false, 2)); @@ -129,10 +132,72 @@ class MongoStartupValidatorTest { assertThat(health.degradedSecondaryAvailability()).isTrue(); } + @Test + void anInactiveProfileWithAnotherTopologyDoesNotFailStartup() { + // given + MongoStartupValidator validator = + new MongoStartupValidator( + primaryAndLocalStandalone(), + new MongoTopologyProbe(MongoTopology.REPLICA_SET, "8.0", 2), + MongoSecurityProfile.production(RUNTIME_CREDENTIAL, Set.of()), + ADMIN_CREDENTIAL, + false, + MongoSchemaVersionRange.of(1, 3)); + + // when + Throwable thrown = catchThrowable(validator::validate); + + // then + assertThat(thrown).isNull(); + } + + @Test + void anInactiveProfileWithAnotherTopologyDoesNotMakeTheInstanceUnready() { + // given + MongoPlatformHealthIndicator health = + new MongoPlatformHealthIndicator( + new MongoTopologyProbe(MongoTopology.REPLICA_SET, "8.0", 2), + primaryAndLocalStandalone()); + + // when + boolean ready = health.ready(); + + // then + assertThat(ready).isTrue(); + } + + /** {@code primary} is active and a replica set; {@code local} is a standalone nobody selected. */ + private static MongoPlatformSettings primaryAndLocalStandalone() { + MongoProfileProperties local = MongoProfileProperties.local("secret://mongodb/local"); + return new MongoPlatformSettings( + "primary", + Map.of( + "primary", + MongoProfileProperties.production("secret://mongodb/primary"), + "local", + new MongoProfileProperties( + local.uriSecret(), + MongoTopology.STANDALONE, + local.production(), + local.stableApiStrict(), + local.serverSelectionTimeout(), + local.connectTimeout(), + local.socketReadTimeout(), + local.operationTimeout(), + local.poolMinSize(), + local.poolMaxSize(), + local.poolMaxWaitTime(), + local.uuidRepresentation(), + local.tlsRequired(), + local.authenticationRequired())), + false, + null); + } + private static MongoStartupValidator validator( MongoProfileProperties profile, MongoTopologyProbe probe, boolean transactionsEnabled) { return new MongoStartupValidator( - new MongoPlatformSettings(Map.of("default", profile), false, null), + new MongoPlatformSettings("default", Map.of("default", profile), false, null), probe, MongoSecurityProfile.production(RUNTIME_CREDENTIAL, Set.of()), ADMIN_CREDENTIAL, diff --git a/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/client/MongoClientSettingsFactoryTest.java b/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/client/MongoClientSettingsFactoryTest.java index 4c329668..6d3b2d54 100644 --- a/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/client/MongoClientSettingsFactoryTest.java +++ b/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/client/MongoClientSettingsFactoryTest.java @@ -114,6 +114,7 @@ class MongoClientSettingsFactoryTest { java.util.List resolved = new java.util.ArrayList<>(); MongoPlatformSettings settings = new MongoPlatformSettings( + ACTIVE, Map.of(ACTIVE, profile(), "unused", profileWith("secret://mongodb/never-read")), false, null); @@ -155,7 +156,7 @@ class MongoClientSettingsFactoryTest { } private static MongoPlatformSettings settingsWith(MongoProfileProperties profile) { - return new MongoPlatformSettings(Map.of(ACTIVE, profile), false, null); + return new MongoPlatformSettings(ACTIVE, Map.of(ACTIVE, profile), false, null); } private static MongoProfileProperties profile() { diff --git a/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/client/MongoProfileClientSettingsAutoConfigurationTest.java b/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/client/MongoProfileClientSettingsAutoConfigurationTest.java index 926f3560..2d976a1e 100644 --- a/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/client/MongoProfileClientSettingsAutoConfigurationTest.java +++ b/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/client/MongoProfileClientSettingsAutoConfigurationTest.java @@ -35,11 +35,9 @@ class MongoProfileClientSettingsAutoConfigurationTest { .withUserConfiguration(MongoProfileClientSettingsAutoConfiguration.class) .withBean( MongoPlatformSettings.class, - () -> new MongoPlatformSettings(Map.of(ACTIVE, profile), false, null)) + () -> new MongoPlatformSettings(ACTIVE, Map.of(ACTIVE, profile), false, null)) .withBean(MongoCredentialResolver.class, () -> resolver(URI)) - .withPropertyValues( - "ca-skeleton.persistence-mongo.enabled=true", - "ca-skeleton.persistence-mongo.active-profile=" + ACTIVE) + .withPropertyValues("ca-skeleton.persistence-mongo.enabled=true") .run( context -> { assertThat(context).hasSingleBean(MongoClientSettingsBuilderCustomizer.class); @@ -71,11 +69,9 @@ class MongoProfileClientSettingsAutoConfigurationTest { .withUserConfiguration(MongoProfileClientSettingsAutoConfiguration.class) .withBean( MongoPlatformSettings.class, - () -> new MongoPlatformSettings(Map.of(ACTIVE, profile), false, null)) + () -> new MongoPlatformSettings("primry", Map.of(ACTIVE, profile), false, null)) .withBean(MongoCredentialResolver.class, () -> resolver(URI)) - .withPropertyValues( - "ca-skeleton.persistence-mongo.enabled=true", - "ca-skeleton.persistence-mongo.active-profile=primry") + .withPropertyValues("ca-skeleton.persistence-mongo.enabled=true") .run( context -> assertThatThrownBy( @@ -124,10 +120,10 @@ class MongoProfileClientSettingsAutoConfigurationTest { void standardUriPathDoesNotRequireACredentialResolverWhenNoTypedProfilesExist() { new ApplicationContextRunner() .withUserConfiguration(MongoProfileClientSettingsAutoConfiguration.class) - .withBean(MongoPlatformSettings.class, MongoPlatformSettings::empty) - .withPropertyValues( - "ca-skeleton.persistence-mongo.enabled=true", - "ca-skeleton.persistence-mongo.active-profile=standard-uri") + .withBean( + MongoPlatformSettings.class, + () -> new MongoPlatformSettings("standard-uri", Map.of(), false, null)) + .withPropertyValues("ca-skeleton.persistence-mongo.enabled=true") .run( context -> { MongoClientSettings.Builder builder = MongoClientSettings.builder(); @@ -144,10 +140,8 @@ class MongoProfileClientSettingsAutoConfigurationTest { .withUserConfiguration(MongoProfileClientSettingsAutoConfiguration.class) .withBean( MongoPlatformSettings.class, - () -> new MongoPlatformSettings(Map.of(ACTIVE, profile), false, null)) - .withPropertyValues( - "ca-skeleton.persistence-mongo.enabled=true", - "ca-skeleton.persistence-mongo.active-profile=" + ACTIVE) + () -> new MongoPlatformSettings(ACTIVE, Map.of(ACTIVE, profile), false, null)) + .withPropertyValues("ca-skeleton.persistence-mongo.enabled=true") .run( context -> assertThatThrownBy( @@ -174,11 +168,9 @@ class MongoProfileClientSettingsAutoConfigurationTest { .withUserConfiguration(MongoProfileClientSettingsAutoConfiguration.class) .withBean( MongoPlatformSettings.class, - () -> new MongoPlatformSettings(Map.of(ACTIVE, profile), false, null)) + () -> new MongoPlatformSettings(ACTIVE, Map.of(ACTIVE, profile), false, null)) .withBean(SecretSourcePort.class, () -> secrets) - .withPropertyValues( - "ca-skeleton.persistence-mongo.enabled=true", - "ca-skeleton.persistence-mongo.active-profile=" + ACTIVE) + .withPropertyValues("ca-skeleton.persistence-mongo.enabled=true") .run( context -> { // when diff --git a/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/imperative/bulk/BulkSharesTheAtomicPolicyTest.java b/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/imperative/bulk/BulkSharesTheAtomicPolicyTest.java index c92c28f8..b85e6d41 100644 --- a/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/imperative/bulk/BulkSharesTheAtomicPolicyTest.java +++ b/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/imperative/bulk/BulkSharesTheAtomicPolicyTest.java @@ -67,7 +67,8 @@ class BulkSharesTheAtomicPolicyTest { .update(AtomicFilter.id("o-2"), AtomicUpdate.set("auditedBy", "someone-else")) .build(); - assertThatThrownBy(() -> executorWith(registryAllowingStatusOnly()).execute(CONTEXT, plan)) + assertThatThrownBy( + () -> executorWith(registryAllowingStatusOnly()).execute(CONTEXT, Object.class, plan)) .isInstanceOf(MongoOperationRejectedException.class) .hasMessageContaining("auditedBy"); } @@ -80,7 +81,10 @@ class BulkSharesTheAtomicPolicyTest { .update(AtomicFilter.id("o-1"), AtomicUpdate.set("status", "PAID")) .build(); - assertThatThrownBy(() -> executorWith(MongoAtomicPolicyRegistry.empty()).execute(CONTEXT, plan)) + assertThatThrownBy( + () -> + executorWith(MongoAtomicPolicyRegistry.empty()) + .execute(CONTEXT, Object.class, plan)) .as("an empty registry used to mean 'validate nothing' on this path") .isInstanceOf(MongoOperationRejectedException.class) .hasMessageContaining("no registered atomic update policy"); diff --git a/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/imperative/bulk/MongoBulkOutcomeTest.java b/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/imperative/bulk/MongoBulkOutcomeTest.java index a70120dd..a1eeeecc 100644 --- a/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/imperative/bulk/MongoBulkOutcomeTest.java +++ b/src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/imperative/bulk/MongoBulkOutcomeTest.java @@ -1,9 +1,10 @@ package dev.caskeleton.adapter.outbound.mongo.imperative.bulk; import static org.assertj.core.api.Assertions.assertThat; -import static org.assertj.core.api.Assertions.assertThatThrownBy; +import static org.assertj.core.api.Assertions.catchThrowable; import com.mongodb.MongoBulkWriteException; +import com.mongodb.MongoClientSettings; import dev.caskeleton.adapter.outbound.mongo.api.error.MongoFailureCategory; import dev.caskeleton.adapter.outbound.mongo.api.error.MongoOperationRejectedException; import dev.caskeleton.adapter.outbound.mongo.imperative.atomic.AtomicFilter; @@ -12,6 +13,9 @@ import java.util.List; import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Tag; import org.junit.jupiter.api.Test; +import org.springframework.data.mongodb.core.convert.MappingMongoConverter; +import org.springframework.data.mongodb.core.convert.NoOpDbRefResolver; +import org.springframework.data.mongodb.core.mapping.MongoMappingContext; /** * What a bulk result says about each item. @@ -84,15 +88,28 @@ class MongoBulkOutcomeTest { } @Test - @DisplayName("a plan under the item cap but over the byte ceiling is refused before it is sent") + @DisplayName("아이템 수 한도 안이어도 매핑된 크기가 byte 한도를 넘으면 보내기 전에 거부된다") void aPlanOverTheByteCeilingIsRefused() { + // given String large = "x".repeat(200_000); MongoBulkWritePlan.Builder builder = MongoBulkWritePlan.builder(MongoBulkMode.ORDERED); for (int index = 0; index < 100; index++) { builder.update(AtomicFilter.id("o-" + index), AtomicUpdate.set("payload", large)); } + MongoBulkWritePlan plan = builder.build(); + MappingMongoConverter converter = + new MappingMongoConverter(NoOpDbRefResolver.INSTANCE, new MongoMappingContext()); + converter.afterPropertiesSet(); - assertThatThrownBy(builder::build) + // when + Throwable thrown = + catchThrowable( + () -> + MongoBulkExecutor.mappedWrites( + plan, Object.class, converter, MongoClientSettings.getDefaultCodecRegistry())); + + // then + assertThat(thrown) .as("an item count is not a size bound; the server refuses the command at 16 MiB") .isInstanceOf(MongoOperationRejectedException.class) .hasMessageContaining("encodes to about"); diff --git a/src/adapter/outbound/redis-runtime/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/config/RedisCorrectnessRoles.java b/src/adapter/outbound/redis-runtime/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/config/RedisCorrectnessRoles.java index 5c008151..7b6a8b5c 100644 --- a/src/adapter/outbound/redis-runtime/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/config/RedisCorrectnessRoles.java +++ b/src/adapter/outbound/redis-runtime/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/config/RedisCorrectnessRoles.java @@ -1,6 +1,7 @@ package dev.caskeleton.adapter.outbound.cache.redis.sdk.config; import java.util.Map; +import java.util.Set; import org.springframework.core.env.Environment; /** @@ -36,6 +37,16 @@ public final class RedisCorrectnessRoles { "ca-skeleton.capabilities.rate-limit.provider", "redis", "ca-skeleton.capabilities.lease.provider", "redis"); + /** + * The roles among {@link #SELECTORS} whose Redis programs run on the SCRIPT lane, which + * authenticates as the advanced account. Session is absent: it issues plain commands. + */ + private static final Set SCRIPT_SELECTORS = + Set.of( + "ca-skeleton.capabilities.idempotency.provider", + "ca-skeleton.capabilities.rate-limit.provider", + "ca-skeleton.capabilities.lease.provider"); + private RedisCorrectnessRoles() { throw new AssertionError("RedisCorrectnessRoles is a constant holder"); } @@ -51,6 +62,19 @@ public final class RedisCorrectnessRoles { .anyMatch(role -> role.getValue().equalsIgnoreCase(environment.getProperty(role.getKey()))); } + /** + * Reports whether a correctness role that runs registered scripts selected Redis. + * + * @param environment the environment to read selectors from + * @return {@code true} when the SCRIPT lane carries a correctness role + */ + public static boolean anyScriptRoleSelected(Environment environment) { + return SCRIPT_SELECTORS.stream() + .anyMatch( + selector -> + SELECTORS.get(selector).equalsIgnoreCase(environment.getProperty(selector))); + } + /** * Returns the selector properties and the values that select Redis, for diagnostics. * diff --git a/src/adapter/outbound/redis-runtime/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/config/RedisHealthContributor.java b/src/adapter/outbound/redis-runtime/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/config/RedisHealthContributor.java index 5e1ec779..86ccad79 100644 --- a/src/adapter/outbound/redis-runtime/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/config/RedisHealthContributor.java +++ b/src/adapter/outbound/redis-runtime/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/config/RedisHealthContributor.java @@ -1,12 +1,16 @@ package dev.caskeleton.adapter.outbound.cache.redis.sdk.config; +import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.error.RedisCommandRejectedException; import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisConnectionKind; import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisLease; import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner; +import java.nio.charset.StandardCharsets; import java.time.Duration; import java.util.LinkedHashMap; +import java.util.List; import java.util.Map; import java.util.Objects; +import java.util.Optional; import java.util.concurrent.TimeUnit; /** @@ -21,22 +25,51 @@ import java.util.concurrent.TimeUnit; *

This exists at all because the readiness group used to name a {@code redisRequired} * contributor that nothing created, with membership validation switched off so the missing name was * silently dropped — a probe that reported UP having checked nothing. + * + *

A lane at its connection limit is load, not an outage: the probe borrows from the same lanes + * as the traffic, and reporting "unreachable" there took a busy pod out of rotation while Redis was + * answering every command it was sent. The trade is that a hung Redis whose lanes stay full reads + * as saturated rather than down; the requests on those lanes still time out and fail closed, and + * the first probe that gets a connection reports the hang. */ public final class RedisHealthContributor { + // No command inside: this proves the SCRIPT lane's account authenticates and holds EVALSHA. The + // commands the semantic scripts call are the startup probe's question, not a readiness one. + private static final byte[] SCRIPT_PROBE = "return 1".getBytes(StandardCharsets.UTF_8); + private final RedisRuntimeOwner owner; private final Duration timeout; + private final Optional scriptProbeKey; + + /** + * Creates the contributor that probes the regular lane. + * + * @param owner the runtime owner to borrow a probe connection from + * @param timeout the ceiling on one probe + */ + public RedisHealthContributor(RedisRuntimeOwner owner, Duration timeout) { + this(owner, timeout, Optional.empty()); + } + /** * Creates the contributor. * * @param owner the runtime owner to borrow a probe connection from * @param timeout the ceiling on one probe + * @param scriptProbeKey when present, the SCRIPT lane is probed too by running a registered + * script on this key — the lane authenticates as the advanced account, which a PING on the + * regular lane says nothing about */ - public RedisHealthContributor(RedisRuntimeOwner owner, Duration timeout) { + public RedisHealthContributor( + RedisRuntimeOwner owner, Duration timeout, Optional scriptProbeKey) { this.owner = Objects.requireNonNull(owner, "runtime owner must be non-null"); this.timeout = Objects.requireNonNull(timeout, "timeout must be non-null"); + this.scriptProbeKey = + Objects.requireNonNull(scriptProbeKey, "script probe key must be non-null") + .map(byte[]::clone); } /** @@ -46,15 +79,37 @@ public final class RedisHealthContributor { */ public RedisHealth probe() { if (owner.state() != RedisRuntimeOwner.State.OPEN) { - return new RedisHealth(false, detail("shutting-down", owner.state().name())); + return shuttingDown(); } - try (RedisLease lease = owner.borrow(RedisConnectionKind.REGULAR)) { - // A round trip, not a flag. `isOpen()` on a driver connection reports what the client - // believes, which stays true for as long as it takes TCP to notice — the window in which a - // health check is most likely to be wrong is exactly the window it exists to catch. - Object reply = - lease.gateway().ping().toCompletableFuture().get(timeout.toNanos(), TimeUnit.NANOSECONDS); + try { + Object reply; + try (RedisLease lease = owner.borrow(RedisConnectionKind.REGULAR)) { + // A round trip, not a flag. `isOpen()` on a driver connection reports what the client + // believes, which stays true for as long as it takes TCP to notice — the window in which a + // health check is most likely to be wrong is exactly the window it exists to catch. + reply = lease.gateway().ping().toCompletableFuture().get(nanos(), TimeUnit.NANOSECONDS); + } + if (scriptProbeKey.isPresent()) { + try (RedisLease lease = owner.borrow(RedisConnectionKind.SCRIPT)) { + String digest = + lease + .gateway() + .loadScript(SCRIPT_PROBE) + .toCompletableFuture() + .get(nanos(), TimeUnit.NANOSECONDS); + lease + .gateway() + .evaluateRegisteredForLong(digest, scriptProbeKey.get(), List.of()) + .toCompletableFuture() + .get(nanos(), TimeUnit.NANOSECONDS); + } + } return new RedisHealth(true, detail("reachable", String.valueOf(reply))); + } catch (RedisCommandRejectedException refused) { + // A refusal is raised before any command exists: either shutdown began, or the lane is full. + return owner.state() != RedisRuntimeOwner.State.OPEN + ? shuttingDown() + : new RedisHealth(true, detail("saturated", "lane at its connection limit")); } catch (InterruptedException interrupted) { Thread.currentThread().interrupt(); return new RedisHealth(false, detail("interrupted", "probe interrupted")); @@ -65,6 +120,14 @@ public final class RedisHealthContributor { } } + private long nanos() { + return timeout.toNanos(); + } + + private RedisHealth shuttingDown() { + return new RedisHealth(false, detail("shutting-down", owner.state().name())); + } + private Map detail(String state, String reason) { Map detail = new LinkedHashMap<>(); detail.put("mode", owner.mode().name()); diff --git a/src/adapter/outbound/redis-runtime/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/config/RedisSdkAutoConfiguration.java b/src/adapter/outbound/redis-runtime/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/config/RedisSdkAutoConfiguration.java index 199cd05a..9e4bc9d7 100644 --- a/src/adapter/outbound/redis-runtime/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/config/RedisSdkAutoConfiguration.java +++ b/src/adapter/outbound/redis-runtime/src/main/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/config/RedisSdkAutoConfiguration.java @@ -1,10 +1,12 @@ package dev.caskeleton.adapter.outbound.cache.redis.sdk.config; +import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.key.RedisNamespace; import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisConnectionKind; import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisCredentialRole; import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeClient; import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner; import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisTopologyClientFactory; +import java.nio.charset.StandardCharsets; import java.util.EnumMap; import java.util.List; import java.util.Map; @@ -23,6 +25,7 @@ import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Condition; import org.springframework.context.annotation.ConditionContext; import org.springframework.context.annotation.Conditional; +import org.springframework.core.env.Environment; import org.springframework.core.io.Resource; import org.springframework.core.io.ResourceLoader; import org.springframework.core.type.AnnotatedTypeMetadata; @@ -276,15 +279,32 @@ public class RedisSdkAutoConfiguration { * cache has no correctness role to gate on, and a required contributor there would make a cache * outage an outage. * + *

When a role that runs registered scripts is selected, the SCRIPT lane is probed as well. It + * authenticates as the advanced account, so a broken advanced credential left the regular-lane + * PING answering while every idempotency, rate-limit and lease call failed. + * * @param owner the runtime owner * @param settings the validated settings + * @param environment the role selectors * @return the contributor */ @Bean(RedisCorrectnessRoles.REQUIRED_HEALTH_CONTRIBUTOR) @Conditional(RedisCorrectnessRoleBound.class) - public HealthIndicator redisRequired(RedisRuntimeOwner owner, RedisSdkSettings settings) { + public HealthIndicator redisRequired( + RedisRuntimeOwner owner, RedisSdkSettings settings, Environment environment) { + Optional scriptProbeKey = + RedisCorrectnessRoles.anyScriptRoleSelected(environment) + ? Optional.of( + (new RedisNamespace( + settings.getNamespace().getEnvironment(), + settings.getNamespace().getService(), + settings.getNamespace().getDomain()) + .prefix() + + ":probe:{health}:script") + .getBytes(StandardCharsets.UTF_8)) + : Optional.empty(); RedisHealthContributor contributor = - new RedisHealthContributor(owner, settings.getTimeout().getFast()); + new RedisHealthContributor(owner, settings.getTimeout().getFast(), scriptProbeKey); return () -> { RedisHealthContributor.RedisHealth health = contributor.probe(); return Health.status(health.reachable() ? Status.UP : Status.DOWN) diff --git a/src/adapter/outbound/redis-runtime/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/config/LiveRedisCompositionTest.java b/src/adapter/outbound/redis-runtime/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/config/LiveRedisCompositionTest.java index 47656d48..7588357f 100644 --- a/src/adapter/outbound/redis-runtime/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/config/LiveRedisCompositionTest.java +++ b/src/adapter/outbound/redis-runtime/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/config/LiveRedisCompositionTest.java @@ -32,6 +32,8 @@ import org.springframework.boot.test.context.runner.ApplicationContextRunner; @Tag("lane-cluster") class LiveRedisCompositionTest { + private static final String ADVANCED_PASSWORD_NAME = "APP_REDIS_ADVANCED_PASSWORD"; + private final RedisTopologyEndpoint endpoint = RedisTopologyEndpoint.fromSystemProperties(); private ApplicationContextRunner runner() { @@ -39,6 +41,10 @@ class LiveRedisCompositionTest { } private ApplicationContextRunner runner(String password) { + return runner(password, "fixture-advanced"); + } + + private ApplicationContextRunner runner(String password, String advancedPassword) { ApplicationContextRunner runner = new ApplicationContextRunner() .withConfiguration(AutoConfigurations.of(RedisSdkAutoConfiguration.class)) @@ -47,7 +53,10 @@ class LiveRedisCompositionTest { // The fixture account's real password. It used to be `nopass`, so this could have // been any string at all and the lane would still have connected — which is why // there was nothing to distinguish a working credential from a wrong one. - () -> name -> Optional.of(password)) + () -> + name -> + Optional.of( + ADVANCED_PASSWORD_NAME.equals(name) ? advancedPassword : password)) .withPropertyValues( "app.redis.enabled=true", "app.redis.mode=" + endpoint.mode().name().toLowerCase(java.util.Locale.ROOT), @@ -132,6 +141,45 @@ class LiveRedisCompositionTest { }); } + /** + * The composition with a script role selected and the advanced account configured. + * + * @param advancedPassword the password the advanced account's reference resolves to + */ + private ApplicationContextRunner scriptRole(String advancedPassword) { + return runner("fixture-application", advancedPassword) + .withPropertyValues( + "app.redis.authentication.advanced-credential-reference=secret://" + + "ca-skeleton-application-advanced@environment/" + + ADVANCED_PASSWORD_NAME, + "ca-skeleton.capabilities.idempotency.provider=redis"); + } + + @Test + @DisplayName("스크립트 role이 선택되면 advanced 계정이 동작할 때 redisRequired가 UP이다") + void aWorkingAdvancedAccountKeepsRequiredRedisUp() { + scriptRole("fixture-advanced") + .run( + context -> { + HealthIndicator required = (HealthIndicator) context.getBean("redisRequired"); + assertThat(required.health().getStatus()).isEqualTo(Status.UP); + }); + } + + @Test + @DisplayName("스크립트 role이 선택되면 advanced 계정 자격 증명이 깨졌을 때 redisRequired가 DOWN이다") + void aBrokenAdvancedAccountTakesRequiredRedisDown() { + // The REGULAR lane still answers PING on the application account. Probing only that lane is + // how a deployment whose script account could not authenticate stayed ready while every + // idempotency, rate-limit and lease call failed. + scriptRole("not-the-advanced-password") + .run( + context -> { + HealthIndicator required = (HealthIndicator) context.getBean("redisRequired"); + assertThat(required.health().getStatus()).isEqualTo(Status.DOWN); + }); + } + @Test @DisplayName("closing the context drains, closes connections, then shuts the client down") void closingTheContextTearsEverythingDown() { diff --git a/src/adapter/outbound/redis-runtime/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/config/RedisHealthContributorTest.java b/src/adapter/outbound/redis-runtime/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/config/RedisHealthContributorTest.java new file mode 100644 index 00000000..9d22deb4 --- /dev/null +++ b/src/adapter/outbound/redis-runtime/src/test/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/config/RedisHealthContributorTest.java @@ -0,0 +1,136 @@ +package dev.caskeleton.adapter.outbound.cache.redis.sdk.config; + +import static org.assertj.core.api.Assertions.assertThat; + +import dev.caskeleton.adapter.outbound.cache.redis.sdk.api.RedisDeploymentMode; +import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisConnectionKind; +import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeClient; +import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.connection.RedisRuntimeOwner; +import dev.caskeleton.adapter.outbound.cache.redis.sdk.lettuce.operations.RedisCommandGateway; +import java.lang.reflect.Proxy; +import java.nio.charset.StandardCharsets; +import java.time.Duration; +import java.util.EnumMap; +import java.util.Map; +import java.util.Optional; +import java.util.concurrent.CompletableFuture; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; + +class RedisHealthContributorTest { + + /** One connection per lane and almost no patience, so holding a lease saturates that lane. */ + private static RedisRuntimeOwner narrowOwner(RedisRuntimeClient client) { + Map limits = new EnumMap<>(RedisConnectionKind.class); + for (RedisConnectionKind kind : RedisConnectionKind.values()) { + limits.put(kind, 1); + } + return new RedisRuntimeOwner(client, limits, Duration.ofMillis(10), Duration.ofSeconds(1)); + } + + @Test + @DisplayName("업무 요청으로 lane이 가득 찬 것은 장애가 아니므로 reachable로 보고한다") + void aSaturatedLaneIsLoadNotAnOutage() { + // given + RedisRuntimeOwner owner = narrowOwner(client(answering())); + owner.borrow(RedisConnectionKind.REGULAR); + RedisHealthContributor contributor = new RedisHealthContributor(owner, Duration.ofSeconds(1)); + + // when + RedisHealthContributor.RedisHealth health = contributor.probe(); + + // then + assertThat(health) + .extracting(RedisHealthContributor.RedisHealth::reachable, h -> h.detail().get("state")) + .containsExactly(true, "saturated"); + } + + @Test + @DisplayName("스크립트 lane 계정이 스크립트를 못 돌리면 regular lane이 응답해도 unreachable이다") + void aScriptLaneItsAccountCannotRunIsUnreachable() { + // given + RedisRuntimeOwner owner = narrowOwner(client(answering(), refusingScripts())); + RedisHealthContributor contributor = + new RedisHealthContributor( + owner, + Duration.ofSeconds(1), + Optional.of("prod:svc:shared:probe:{health}:script".getBytes(StandardCharsets.UTF_8))); + + // when + RedisHealthContributor.RedisHealth health = contributor.probe(); + + // then + assertThat(health) + .extracting(RedisHealthContributor.RedisHealth::reachable, h -> h.detail().get("state")) + .containsExactly(false, "unreachable"); + } + + private static RedisRuntimeClient client(RedisCommandGateway gateway) { + return client(gateway, gateway); + } + + private static RedisRuntimeClient client( + RedisCommandGateway regular, RedisCommandGateway script) { + return new RedisRuntimeClient() { + @Override + public RedisDeploymentMode mode() { + return RedisDeploymentMode.STANDALONE; + } + + @Override + public RedisLaneConnection openLane(RedisConnectionKind kind, Optional routingKey) { + return new RedisLaneConnection() { + @Override + public RedisCommandGateway gateway() { + return kind == RedisConnectionKind.SCRIPT ? script : regular; + } + + @Override + public boolean open() { + return true; + } + + @Override + public void close() {} + }; + } + + @Override + public void close() {} + }; + } + + /** A gateway whose account is refused the script path, as Redis refuses it. */ + private static RedisCommandGateway refusingScripts() { + return (RedisCommandGateway) + Proxy.newProxyInstance( + RedisCommandGateway.class.getClassLoader(), + new Class[] {RedisCommandGateway.class}, + (proxy, method, arguments) -> + switch (method.getName()) { + case "loadScript" -> + CompletableFuture.failedFuture( + new RuntimeException("NOPERM this user has no permissions")); + case "toString" -> "RedisHealthContributorTestScriptGateway"; + default -> + throw new UnsupportedOperationException( + "unexpected gateway method: " + method.getName()); + }); + } + + /** A gateway that answers PING. */ + private static RedisCommandGateway answering() { + return (RedisCommandGateway) + Proxy.newProxyInstance( + RedisCommandGateway.class.getClassLoader(), + new Class[] {RedisCommandGateway.class}, + (proxy, method, arguments) -> + switch (method.getName()) { + case "ping" -> CompletableFuture.completedFuture("PONG"); + case "toString" -> "RedisHealthContributorTestGateway"; + default -> + throw new UnsupportedOperationException( + "unexpected gateway method: " + method.getName()); + }); + } +} diff --git a/src/adapter/outbound/redis-runtime/src/testFixtures/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/lettuce/operations/InMemoryRedisCommandGateway.java b/src/adapter/outbound/redis-runtime/src/testFixtures/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/lettuce/operations/InMemoryRedisCommandGateway.java index 0419bc8f..d6924a6f 100644 --- a/src/adapter/outbound/redis-runtime/src/testFixtures/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/lettuce/operations/InMemoryRedisCommandGateway.java +++ b/src/adapter/outbound/redis-runtime/src/testFixtures/java/dev/caskeleton/adapter/outbound/cache/redis/sdk/lettuce/operations/InMemoryRedisCommandGateway.java @@ -1721,13 +1721,15 @@ final class InMemoryRedisCommandGateway implements RedisCommandGateway { long nowMillis = now(); long windowStart = nowMillis - Math.floorMod(nowMillis, windowMillis); long resetAfter = (windowStart + windowMillis) - nowMillis; + // The script's layout: two fields, overwritten when the window turns. Map fields = hash(rendered); - String bucket = Long.toString(windowStart); - long current = fieldValue(fields, bucket); + boolean sameWindow = fields.containsKey("start") && fieldValue(fields, "start") == windowStart; + long current = sameWindow ? fieldValue(fields, "count") : 0; if (current + cost > limit) { return List.of(0L, limit - current, resetAfter); } - fields.put(bucket, new HashEntry(utf8(Long.toString(current + cost)), null)); + fields.put("start", new HashEntry(utf8(Long.toString(windowStart)), null)); + fields.put("count", new HashEntry(utf8(Long.toString(current + cost)), null)); return List.of(1L, limit - (current + cost), resetAfter); } @@ -1739,16 +1741,25 @@ final class InMemoryRedisCommandGateway implements RedisCommandGateway { long windowStart = nowMillis - Math.floorMod(nowMillis, windowMillis); long elapsed = nowMillis - windowStart; long resetAfter = windowMillis - elapsed; + // The script's layout: start/cur/prev, rotated when the window turns. Map fields = hash(rendered); - long current = fieldValue(fields, Long.toString(windowStart)); - long previous = fieldValue(fields, Long.toString(windowStart - windowMillis)); + long storedStart = fields.containsKey("start") ? fieldValue(fields, "start") : Long.MIN_VALUE; + long current = 0; + long previous = 0; + if (storedStart == windowStart) { + current = fieldValue(fields, "cur"); + previous = fieldValue(fields, "prev"); + } else if (storedStart == windowStart - windowMillis) { + previous = fieldValue(fields, "cur"); + } double weight = (double) (windowMillis - elapsed) / windowMillis; long estimated = current + (long) Math.floor(previous * weight); if (estimated + cost > limit) { return List.of(0L, Math.max(0, limit - estimated), resetAfter); } - fields.put( - Long.toString(windowStart), new HashEntry(utf8(Long.toString(current + cost)), null)); + fields.put("start", new HashEntry(utf8(Long.toString(windowStart)), null)); + fields.put("cur", new HashEntry(utf8(Long.toString(current + cost)), null)); + fields.put("prev", new HashEntry(utf8(Long.toString(previous)), null)); return List.of(1L, Math.max(0, limit - (estimated + cost)), resetAfter); } diff --git a/src/app-bootstrap/CLAUDE.md b/src/app-bootstrap/CLAUDE.md index b48d3d08..8a8e4b65 100644 --- a/src/app-bootstrap/CLAUDE.md +++ b/src/app-bootstrap/CLAUDE.md @@ -63,8 +63,10 @@ configurations, Redis as one 376-line class. covers `dev.caskeleton.bootstrap` only; web (`WebAdapterAutoConfiguration`) and support (`OutboundSupportConfig`) arrive through their own `AutoConfiguration.imports`. What stays in `autoconfigure//` is application composition over application-core ports that names no module type: `outbox` (the relay use case - and its scheduler, on only when the store and publisher ports exist), `idempotency` (the one - executor over whichever store is selected), `tracing`, `common`. + and its scheduler, on only when the store and publisher ports exist), `operation` (the durable + operation use cases and their `/operations` endpoints, on only when the operation store and the + outbox append port exist), `idempotency` (the one executor over whichever store is selected), + `tracing`, `common`. - **`Settings` lives beside its capability**, not in `settings/`. The `settings/` package holds only settings that belong to no capability — `BootstrapSettings`, `LoggingSettings`, `PrivacySettings`, `RuntimeSafetySettings`. diff --git a/src/app-bootstrap/README.md b/src/app-bootstrap/README.md index cb6bd1cd..f86cf9b0 100644 --- a/src/app-bootstrap/README.md +++ b/src/app-bootstrap/README.md @@ -346,9 +346,10 @@ README의 "startup" 절에 있다. 감싼다. 그런데 use case 가 `final` 클래스라 프록시 생성 자체가 실패하고, 설령 된다 해도 스케줄러 스레드에는 `Authentication`이 없어 매 릴레이 틱이 fail-closed 로 거부된다. 그래서 빈으로 올리지 않고, `outbox:relay` 권한 확인은 스케줄러 컨텍스트에서 관례로 둔다. -- **`outboxRelayScheduler` 빈은 `ca-skeleton.outbox.relay-enabled`로 게이팅한다(기본 true, - `matchIfMissing=true`).** 릴레이를 끄고 싶을 때 빈 자체가 만들어지지 않게 하기 위함. 키가 없으면 - 켜진 것으로 본다. +- **`outboxRelayScheduler` 빈은 `ca-skeleton.outbox.relay-enabled=true`일 때만 만든다(기본 + false).** 키가 없으면 꺼진 것으로 본다. 모듈 기본값(`persistence-jpa.yml`의 + `${APP_OUTBOX_RELAY_ENABLED:false}`), `@ConditionalOnProperty`, `OutboxSettings`의 null 기본값이 + 모두 false로 같다. - **store와 publisher가 있을 때만 켜진다.** 설정 전체는 `OutboxStorePort` 빈(persistence-jpa를 고르고 outbox를 켰을 때만 존재)을, 스케줄러는 추가로 `OutboxMessagePublishPort` 빈(messaging bridge가 제공)을 조건으로 건다. 두 auto-configuration 뒤에 오도록 `afterName`으로 순서를 명시한다. 발행할 @@ -538,11 +539,11 @@ README의 "startup" 절에 있다. 체인 범위에 든다. - **접근 정책.** `health`, `info`, `prometheus`는 permit-all 이다. 자격 증명 없이 Kubernetes 프로브와 Prometheus 스크레이프가 접근할 수 있어야 하고, 이 엔드포인트들은 민감 데이터를 노출하지 않기 - 때문이다(health 상세는 when-authorized). 나머지 액추에이터 엔드포인트는 모두 인증이 필요하다. -- **`loggers` 쓰기 차단.** 런타임 로그 레벨 변경은 `POST /actuator/loggers/{name}`이고, 레벨 리셋은 - `DELETE /actuator/loggers/{name}`이다. 둘 다 변형(mutation) 작업이므로 `denyAll()`로 모두에게 - (인증된 사용자 포함) 거부한다 — 인증만으로 쓰기 권한을 주지 않는다. `loggers` 읽기는 아래 - `authenticated()`로 흘러 인증을 요구한다. + 때문이다(health 상세는 `never`). 나머지(`/actuator` 링크 등)는 모두 인증이 필요하다. +- **`loggers`는 노출하지 않는다.** 이 체인에는 인증 수단(`httpBasic`·`oauth2ResourceServer`)이 없어 + `authenticated()`에 걸리는 엔드포인트는 어떤 자격 증명으로도 도달할 수 없다. 그래서 `loggers` + 노출과 `show-details: when-authorized`를 뺐다. 로그 레벨을 런타임에 보거나 바꿔야 하면 인증 + 수단을 이 체인에 먼저 붙이고 노출한다. - **인증 실패 시 기본값 403 대신 401(자격 증명 필요)을 반환한다(`HttpStatusEntryPoint(UNAUTHORIZED)`).** 대화형 로그인이나 basic-auth realm 은 제공하지 않는다 — 관리 포트는 네트워크 ACL 뒤에 있으므로 올바른 HTTP 의미(credentials required)만 신호하면 된다. @@ -735,8 +736,8 @@ app-bootstrap 은 합성 루트라 "왜 이 의존성이, 왜 이 scope 로" 결 활성화되고, deserialization-policy 경계 테스트가 `DeserializationFeature` enum 을 직접 읽는다. - **Testcontainers(`postgresql`/`junit-jupiter`)** — outbox contract 테스트용. 버전은 Spring Boot BOM 이 관리. -- **`spring-security-test`** — `@WithMockUser`로 actuator 보안 인가(permit-all 프로브 / authenticated - loggers / loggers 쓰기 거부)를 검증한다. +- **`spring-security-test`** — `@WithMockUser`로 actuator 보안 인가(permit-all 프로브 / 인증 필요한 + 링크 / 노출 안 한 loggers)를 검증한다. - **`snakeyaml`** — `config/messaging/*.yaml`의 first polling-producer tuple, closed maturity, wildcard-free compatibility, evidence task/scenario/runbook 선언을 `MessagingCapabilityRegistryContractTest`가 읽어 검증한다. 이 레지스트리는 런타임 설정이 아니며 diff --git a/src/app-bootstrap/build.gradle b/src/app-bootstrap/build.gradle index f0dd66bd..e249970c 100644 --- a/src/app-bootstrap/build.gradle +++ b/src/app-bootstrap/build.gradle @@ -41,6 +41,7 @@ strictTestLanes { requires 'dev.caskeleton.bootstrap.integration.fileserver.FileserverCompositionIntegrationTest' requires 'dev.caskeleton.bootstrap.integration.objectstorage.ObjectStorageCompositionIntegrationTest' requires 'dev.caskeleton.bootstrap.integration.idempotency.PostgreSqlIdempotencyProviderIntegrationTest' + requires 'dev.caskeleton.bootstrap.integration.operation.DurableOperationCompositionIntegrationTest' } lane('architectureTest') { architecture() diff --git a/src/app-bootstrap/src/integrationTest/java/dev/caskeleton/bootstrap/integration/operation/DurableOperationCompositionIntegrationTest.java b/src/app-bootstrap/src/integrationTest/java/dev/caskeleton/bootstrap/integration/operation/DurableOperationCompositionIntegrationTest.java new file mode 100644 index 00000000..ff3c3c59 --- /dev/null +++ b/src/app-bootstrap/src/integrationTest/java/dev/caskeleton/bootstrap/integration/operation/DurableOperationCompositionIntegrationTest.java @@ -0,0 +1,239 @@ +package dev.caskeleton.bootstrap.integration.operation; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.delete; +import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get; +import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post; + +import com.jayway.jsonpath.JsonPath; +import dev.caskeleton.adapter.inbound.web.auth.AuthenticatedPrincipal; +import dev.caskeleton.adapter.inbound.web.authz.AuthorizationAdapter; +import dev.caskeleton.adapter.inbound.web.authz.MethodSecurityConfig; +import dev.caskeleton.adapter.inbound.web.authz.RolePermissionPolicy; +import dev.caskeleton.adapter.inbound.web.authz.RolePermissionRegistry; +import dev.caskeleton.adapter.inbound.web.envelope.EnvelopeBodyAdvice; +import dev.caskeleton.bootstrap.concurrency.DomainContextConfig; +import dev.caskeleton.bootstrap.integration.PostgreSqlTestContainer; +import java.util.List; +import java.util.Set; +import org.flywaydb.core.Flyway; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.SpringBootConfiguration; +import org.springframework.boot.autoconfigure.EnableAutoConfiguration; +import org.springframework.boot.context.properties.EnableConfigurationProperties; +import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.boot.webmvc.test.autoconfigure.AutoConfigureMockMvc; +import org.springframework.context.annotation.Import; +import org.springframework.http.MediaType; +import org.springframework.jdbc.core.JdbcTemplate; +import org.springframework.security.authentication.TestingAuthenticationToken; +import org.springframework.security.core.context.SecurityContextHolder; +import org.springframework.test.context.DynamicPropertyRegistry; +import org.springframework.test.context.DynamicPropertySource; +import org.springframework.test.web.servlet.MockMvc; +import org.springframework.test.web.servlet.MvcResult; +import org.springframework.test.web.servlet.request.RequestPostProcessor; +import org.testcontainers.junit.jupiter.Container; +import org.testcontainers.junit.jupiter.Testcontainers; +import org.testcontainers.postgresql.PostgreSQLContainer; + +/** + * Durable operations as a service assembles them: HTTP in, the shipped composition, the JPA stores, + * real PostgreSQL. + * + *

The web contract is proven against fakes in {@code DurableOperationControllerTest}; what only + * this test can show is the assembly — that selecting the JPA module and the outbox turns the + * endpoints on, that the use cases are proxied so {@code @RequiresPermission} holds, and that the + * rows PostgreSQL ends up with are the ones the HTTP answers describe. + * + *

A focused context rather than a full boot, for the reasons {@code + * FileserverCompositionIntegrationTest} gives. The security filter chain is left out; the caller is + * placed in the security context directly, and the permission check still runs in the use case + * proxy. + */ +@Testcontainers +@SpringBootTest( + classes = DurableOperationCompositionIntegrationTest.OperationRuntime.class, + properties = { + "spring.config.name=durable-operation-round-trip", + "spring.main.banner-mode=off", + "spring.flyway.enabled=false", + "spring.jpa.open-in-view=false", + "spring.jpa.hibernate.ddl-auto=none", + "ca-skeleton.outbox.enabled=true", + "app.fileserver-platform.enabled=false", + "app.object-storage.enabled=false", + "ca-skeleton.authz.role-permissions.operation-submit=operation:submit,operation:cancel" + }) +@AutoConfigureMockMvc(addFilters = false) +class DurableOperationCompositionIntegrationTest { + + private static final String REPORT = + "{\"operationName\":\"reports.generate\",\"payload\":{\"range\":\"2026-08\"}}"; + + @Container static final PostgreSQLContainer PG = PostgreSqlTestContainer.create(); + + @Autowired private MockMvc mockMvc; + + @Autowired private JdbcTemplate jdbc; + + @DynamicPropertySource + static void runtimeProperties(DynamicPropertyRegistry registry) { + Flyway.configure() + .dataSource(PG.getJdbcUrl(), PG.getUsername(), PG.getPassword()) + .locations("classpath:db/migration/postgresql") + .load() + .migrate(); + registry.add("spring.datasource.url", PG::getJdbcUrl); + registry.add("spring.datasource.username", PG::getUsername); + registry.add("spring.datasource.password", PG::getPassword); + } + + @BeforeEach + void empty() { + SecurityContextHolder.clearContext(); + jdbc.execute("TRUNCATE durable_operation, outbox_event"); + } + + @Test + void aSubmissionWritesTheOperationRowAndOneOutboxEventToPostgreSql() throws Exception { + // when + String operationId = operationIdOf(submit(submitter("alice"))); + + // then + assertThat( + List.of( + jdbc.queryForObject( + "SELECT state FROM durable_operation WHERE operation_id = ?", + String.class, + operationId), + jdbc.queryForList("SELECT event_type FROM outbox_event", String.class))) + .containsExactly("PENDING", List.of("DurableOperationSubmitted")); + } + + @Test + void aResubmissionPointsAtTheFirstOperationAndAppendsNoSecondOutboxEvent() throws Exception { + // given + String first = operationIdOf(submit(submitter("alice"))); + + // when + MvcResult again = submit(submitter("alice")); + + // then + assertThat( + List.of( + operationIdOf(again), + JsonPath.read(again.getResponse().getContentAsString(), "$.data.alreadyAccepted"), + jdbc.queryForObject("SELECT count(*) FROM outbox_event", Integer.class))) + .containsExactly(first, true, 1); + } + + @Test + void theSubmitterReadsTheOperationBackFromPostgreSql() throws Exception { + // given + String operationId = operationIdOf(submit(submitter("alice"))); + + // when + MvcResult read = + mockMvc.perform(get("/operations/" + operationId).with(submitter("alice"))).andReturn(); + + // then + assertThat( + List.of( + read.getResponse().getStatus(), + JsonPath.read(read.getResponse().getContentAsString(), "$.data.state"))) + .containsExactly(200, "PENDING"); + } + + @Test + void theSubmitterCancelsThroughHttpAndPostgreSqlRecordsIt() throws Exception { + // given + String operationId = operationIdOf(submit(submitter("alice"))); + + // when + MvcResult cancel = + mockMvc.perform(delete("/operations/" + operationId).with(submitter("alice"))).andReturn(); + + // then + assertThat( + List.of( + cancel.getResponse().getStatus(), + jdbc.queryForObject( + "SELECT state FROM durable_operation WHERE operation_id = ?", + String.class, + operationId))) + .containsExactly(202, "CANCELED"); + } + + @Test + void aCallerWithoutTheSubmitRoleIsRefusedAndNothingIsWritten() throws Exception { + // when + MvcResult refused = + mockMvc + .perform( + post("/operations") + .contentType(MediaType.APPLICATION_JSON) + .content(REPORT) + .with(caller("mallory", Set.of()))) + .andReturn(); + + // then + assertThat( + List.of( + refused.getResponse().getStatus(), + jdbc.queryForObject("SELECT count(*) FROM durable_operation", Integer.class))) + .containsExactly(403, 0); + } + + private MvcResult submit(RequestPostProcessor caller) throws Exception { + return mockMvc + .perform( + post("/operations") + .contentType(MediaType.APPLICATION_JSON) + .content(REPORT) + .with(caller)) + .andReturn(); + } + + private static String operationIdOf(MvcResult result) throws Exception { + return JsonPath.read(result.getResponse().getContentAsString(), "$.data.operationId"); + } + + private static RequestPostProcessor submitter(String subject) { + return caller(subject, Set.of("operation-submit")); + } + + // With the filter chain off nothing copies a test authentication into the security context, so + // the caller is placed there directly; MockMvc dispatches on this thread. + private static RequestPostProcessor caller(String subject, Set roles) { + return request -> { + SecurityContextHolder.getContext() + .setAuthentication( + new TestingAuthenticationToken( + new AuthenticatedPrincipal(subject, subject + "@example.test", roles), + "n/a", + List.of())); + return request; + }; + } + + /** The shipped composition over a datasource, plus the web authorization pieces it relies on. */ + @SpringBootConfiguration + // The web adapter's root would add the JWT/session security chain, which needs an issuer; the + // permission check lives in the method-security advisor imported below. + @EnableAutoConfiguration( + excludeName = + "dev.caskeleton.adapter.inbound.web.mvc.autoconfigure.WebAdapterAutoConfiguration") + @EnableConfigurationProperties(RolePermissionPolicy.class) + @Import({ + // The JPA audit port reads the domain context; the running application gets it from here. + DomainContextConfig.class, + MethodSecurityConfig.class, + AuthorizationAdapter.class, + RolePermissionRegistry.class, + EnvelopeBodyAdvice.class + }) + static class OperationRuntime {} +} diff --git a/src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/operation/DurableOperationConfig.java b/src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/operation/DurableOperationConfig.java new file mode 100644 index 00000000..c498d5af --- /dev/null +++ b/src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/operation/DurableOperationConfig.java @@ -0,0 +1,65 @@ +package dev.caskeleton.bootstrap.autoconfigure.operation; + +import dev.caskeleton.adapter.inbound.web.operation.DurableOperationController; +import dev.caskeleton.application.operation.CancelDurableOperationUseCase; +import dev.caskeleton.application.operation.DurableOperationStorePort; +import dev.caskeleton.application.operation.GetDurableOperationUseCase; +import dev.caskeleton.application.operation.SubmitDurableOperationUseCase; +import dev.caskeleton.application.outbox.LegacyOutboxAppendPort; +import dev.caskeleton.application.transaction.TransactionPort; +import java.time.Clock; +import org.springframework.boot.autoconfigure.AutoConfiguration; +import org.springframework.boot.autoconfigure.condition.ConditionalOnBean; +import org.springframework.boot.autoconfigure.condition.ConditionalOnWebApplication; +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Import; + +/** + * Durable operations: the three use cases and their HTTP endpoints. + * + *

Application composition, like the outbox relay: it builds use cases from ports, which a driven + * adapter must not do. It names no module type, only ports, and turns itself on from what the + * selected modules provide — an operation store and an outbox to announce submissions through, both + * of which the JPA module contributes (the outbox with {@code ca-skeleton.outbox.enabled}). + * Removing that module's build line removes the endpoints with it. + * + *

The use cases are beans rather than objects built inside the controller so that the method + * security advisor proxies them: {@code @RequiresPermission} on submit and cancel is enforced by + * that proxy, and a use case constructed by hand would carry the annotation and skip the check. + */ +@AutoConfiguration( + afterName = + "dev.caskeleton.adapter.outbound.persistence.autoconfigure.PersistenceJpaAutoConfiguration") +@ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.SERVLET) +@ConditionalOnBean({ + DurableOperationStorePort.class, + LegacyOutboxAppendPort.class, + TransactionPort.class +}) +@Import(DurableOperationController.class) +public class DurableOperationConfig { + + /** Accepts work: the operation row and its outbox event in one transaction. */ + @Bean + public SubmitDurableOperationUseCase submitDurableOperationUseCase( + DurableOperationStorePort operations, + LegacyOutboxAppendPort outbox, + TransactionPort transactions, + Clock clock) { + return new SubmitDurableOperationUseCase(operations, outbox, transactions, clock); + } + + /** Reads one operation for the caller that submitted it. */ + @Bean + public GetDurableOperationUseCase getDurableOperationUseCase( + DurableOperationStorePort operations, TransactionPort transactions, Clock clock) { + return new GetDurableOperationUseCase(operations, transactions, clock); + } + + /** Cancels one operation for the caller that submitted it. */ + @Bean + public CancelDurableOperationUseCase cancelDurableOperationUseCase( + DurableOperationStorePort operations, TransactionPort transactions, Clock clock) { + return new CancelDurableOperationUseCase(operations, transactions, clock); + } +} diff --git a/src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/outbox/OutboxConfig.java b/src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/outbox/OutboxConfig.java index 3023c8ea..1da4038d 100644 --- a/src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/outbox/OutboxConfig.java +++ b/src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/outbox/OutboxConfig.java @@ -66,10 +66,7 @@ public class OutboxConfig { /** Relay use case is assembled manually here (not a bean) from {@link OutboxSettings} values. */ @Bean - @ConditionalOnProperty( - name = "ca-skeleton.outbox.relay-enabled", - havingValue = "true", - matchIfMissing = true) + @ConditionalOnProperty(name = "ca-skeleton.outbox.relay-enabled", havingValue = "true") @ConditionalOnBean(OutboxMessagePublishPort.class) public OutboxRelayScheduler outboxRelayScheduler( OutboxStorePort store, diff --git a/src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/outbox/OutboxMetrics.java b/src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/outbox/OutboxMetrics.java index 6b2c0f89..e81d07d6 100644 --- a/src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/outbox/OutboxMetrics.java +++ b/src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/outbox/OutboxMetrics.java @@ -89,6 +89,11 @@ public final class OutboxMetrics { Map counts = store.countByStatus(); List> rows = new ArrayList<>(OutboxEventStatus.values().length); for (OutboxEventStatus status : OutboxEventStatus.values()) { + if (status == OutboxEventStatus.PUBLISHED) { + // The store does not count published rows (OutboxStorePort#countByStatus); a series + // pinned at 0 would read as "nothing published". + continue; + } long count = counts.getOrDefault(status, 0L); rows.add(MultiGauge.Row.of(Tags.of("status", status.name()), count)); } diff --git a/src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/outbox/OutboxSettings.java b/src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/outbox/OutboxSettings.java index 13540da2..af5cc9cc 100644 --- a/src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/outbox/OutboxSettings.java +++ b/src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/autoconfigure/outbox/OutboxSettings.java @@ -9,7 +9,7 @@ import org.springframework.validation.annotation.Validated; * Outbox relay runtime knobs bound from {@code ca-skeleton.outbox.*} (literal defaults, no env * placeholders). See README for the design rationale. * - * @param relayEnabled whether the relay scheduler is enabled; default {@code true} + * @param relayEnabled whether the relay scheduler is enabled; default {@code false} * @param canonicalTransportEnabled whether canonical rows may use the platform transport; default * {@code false} * @param pollInterval how often the relay polls the outbox table; default {@code PT5S} @@ -32,7 +32,9 @@ public record OutboxSettings( public OutboxSettings { if (relayEnabled == null) { - relayEnabled = true; + // Off unless asked for, like the module default and the scheduler condition: three sources + // answering "is the relay on" differently is how a missing key started it. + relayEnabled = false; } if (canonicalTransportEnabled == null) { canonicalTransportEnabled = false; diff --git a/src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/management/security/ManagementSecurityConfig.java b/src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/management/security/ManagementSecurityConfig.java index a5ade0c1..56ef2d0b 100644 --- a/src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/management/security/ManagementSecurityConfig.java +++ b/src/app-bootstrap/src/main/java/dev/caskeleton/bootstrap/management/security/ManagementSecurityConfig.java @@ -4,7 +4,6 @@ import org.springframework.boot.security.autoconfigure.actuate.web.servlet.Endpo import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.core.annotation.Order; -import org.springframework.http.HttpMethod; import org.springframework.http.HttpStatus; import org.springframework.security.config.annotation.web.builders.HttpSecurity; import org.springframework.security.config.http.SessionCreationPolicy; @@ -34,10 +33,6 @@ public class ManagementSecurityConfig { // permit-all for probes and Prometheus scrape. .requestMatchers(EndpointRequest.to("health", "info", "prometheus")) .permitAll() - .requestMatchers(HttpMethod.POST, "/actuator/loggers/**") - .denyAll() - .requestMatchers(HttpMethod.DELETE, "/actuator/loggers/**") - .denyAll() .anyRequest() .authenticated()); return http.build(); diff --git a/src/app-bootstrap/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports b/src/app-bootstrap/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports index 1e3c2e8a..019304f3 100644 --- a/src/app-bootstrap/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports +++ b/src/app-bootstrap/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports @@ -1,4 +1,5 @@ dev.caskeleton.bootstrap.autoconfigure.common.BootstrapClockAutoConfiguration dev.caskeleton.bootstrap.autoconfigure.outbox.OutboxConfig +dev.caskeleton.bootstrap.autoconfigure.operation.DurableOperationConfig dev.caskeleton.bootstrap.autoconfigure.idempotency.IdempotencyProviderSelectionConfig dev.caskeleton.bootstrap.autoconfigure.tracing.TracingConfig diff --git a/src/app-bootstrap/src/main/resources/config/observability.yml b/src/app-bootstrap/src/main/resources/config/observability.yml index 520d3b9e..dff13705 100644 --- a/src/app-bootstrap/src/main/resources/config/observability.yml +++ b/src/app-bootstrap/src/main/resources/config/observability.yml @@ -29,16 +29,19 @@ management: port: ${MANAGEMENT_SERVER_PORT:9001} endpoints: web: - # D2: production allowlist — only safe, scrape-friendly endpoints are exposed. + # D2: production allowlist — only safe, scrape-friendly endpoints are exposed. The actuator + # chain has no authentication mechanism, so an endpoint that needs a caller to authenticate + # (loggers) would be reachable by nobody; it is not exposed. exposure: - include: health,prometheus,info,loggers + include: health,prometheus,info # D2/D4/D5: explicitly excluded dangerous endpoints (env leaks secrets, # heapdump/threaddump = memory forensics, shutdown = remote kill, configprops = secret leak). exclude: env,configprops,heapdump,threaddump,shutdown endpoint: health: - # D8: never expose health details to unauthenticated callers. - show-details: when-authorized + # D8: never expose health details. when-authorized named a caller the actuator chain cannot + # authenticate. + show-details: never # Membership is validated. With validation off, a group naming a contributor that does not # exist is silently dropped and readiness reports UP while proving nothing about the # dependency it claims to gate on — a false green that survives exactly as long as nobody @@ -87,6 +90,11 @@ management: build: # Build-info only (no env leak). enabled: true + # The `info.*` tree only, not the environment: each capability module ships an + # info.capabilities. entry beside its switch, and the Compose smoke lanes read it to check + # which capabilities the application actually turned on (compose-profile-contracts.json). + env: + enabled: true logging: level: @@ -148,7 +156,7 @@ ca-skeleton: # app-bootstrap/build.gradle. The exporter remains off while OTEL_EXPORTER_OTLP_ENDPOINT # is blank (url_or_empty default). A fork can supply the endpoint via env or override # SpanErrorRecorder with its own bean. - # D4 disabled-fallback: even when enabled=false, RequestLoggingFilter always + # D4 disabled-fallback: even when enabled=false, WebMvcRequestIdFilter always # generates a W3C traceparent so meta.traceId and log trace_id are never null. # D6 per-runtime defaults: prod=0.01 / dev·local=1.0 (RuntimeEnvironment SSOT). # APP_TRACING_SAMPLE_RATE overrides the per-profile default when set. diff --git a/src/app-bootstrap/src/main/resources/config/security.yml b/src/app-bootstrap/src/main/resources/config/security.yml index c18afa29..a2a4d21a 100644 --- a/src/app-bootstrap/src/main/resources/config/security.yml +++ b/src/app-bootstrap/src/main/resources/config/security.yml @@ -43,6 +43,10 @@ ca-skeleton: # both grants both roles. notification-submit: notification:submit notification-template-publish: notification-template:publish + # Durable operations (/operations, on with the JPA module and the outbox). One role for both: + # a caller that may start an operation may cancel its own, and reading one needs no + # permission beyond being the one who submitted it. + operation-submit: operation:submit,operation:cancel cors: # true | false enabled: ${APP_SECURITY_CORS_ENABLED:false} diff --git a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/autoconfigure/outbox/OutboxConfigTest.java b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/autoconfigure/outbox/OutboxConfigTest.java index 374762a5..b2f50ef9 100644 --- a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/autoconfigure/outbox/OutboxConfigTest.java +++ b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/autoconfigure/outbox/OutboxConfigTest.java @@ -62,6 +62,23 @@ class OutboxConfigTest { .run(context -> assertThat(context).hasSingleBean(OutboxRelayScheduler.class)); } + @Test + void withoutTheRelayKeyTheRelaySchedulerIsNotAssembled() { + new ApplicationContextRunner() + .withConfiguration(AutoConfigurations.of(OutboxConfig.class)) + .withBean(OutboxStorePort.class, OutboxConfigTest::unusedStore) + .withBean(OutboxRelayFailureReportPort.class, () -> report -> {}) + .withBean(TransactionPort.class, () -> mock(TransactionPort.class)) + .withBean(Clock.class, Clock::systemUTC) + .withBean(OutboxMessagePublishPort.class, () -> mock(OutboxMessagePublishPort.class)) + .withPropertyValues("ca-skeleton.outbox.enabled=true") + .run( + context -> + assertThat(context) + .as("the module default says false; a missing key must mean the same thing") + .doesNotHaveBean(OutboxRelayScheduler.class)); + } + @Test void withoutTheRelationalStoreTheOutboxAssemblesNothing() { new ApplicationContextRunner() diff --git a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/autoconfigure/outbox/OutboxSettingsTest.java b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/autoconfigure/outbox/OutboxSettingsTest.java index 5a008dba..ff033836 100644 --- a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/autoconfigure/outbox/OutboxSettingsTest.java +++ b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/autoconfigure/outbox/OutboxSettingsTest.java @@ -16,7 +16,7 @@ class OutboxSettingsTest { @Test void bindsAllSixDefaultsWhenFieldsAreNull() { OutboxSettings props = new OutboxSettings(null, null, null, null, null, null, null); - assertThat(props.relayEnabled()).isTrue(); + assertThat(props.relayEnabled()).isFalse(); assertThat(props.canonicalTransportEnabled()).isFalse(); assertThat(props.pollInterval()).isEqualTo(Duration.ofSeconds(5)); assertThat(props.batchSize()).isEqualTo(20); diff --git a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/ActuatorSecurityHttpTest.java b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/ActuatorSecurityHttpTest.java index 576ba3ce..7773fd22 100644 --- a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/ActuatorSecurityHttpTest.java +++ b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/ActuatorSecurityHttpTest.java @@ -1,9 +1,7 @@ package dev.caskeleton.bootstrap.contract; import static org.springframework.security.test.web.servlet.request.SecurityMockMvcRequestPostProcessors.user; -import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.delete; import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get; -import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post; import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status; import dev.caskeleton.adapter.inbound.web.mvc.autoconfigure.WebAdapterAutoConfiguration; @@ -19,7 +17,6 @@ import org.springframework.boot.jdbc.autoconfigure.DataSourceTransactionManagerA import org.springframework.boot.test.context.SpringBootTest; import org.springframework.boot.webmvc.test.autoconfigure.AutoConfigureMockMvc; import org.springframework.context.annotation.Import; -import org.springframework.http.MediaType; import org.springframework.test.web.servlet.MockMvc; /** @@ -49,10 +46,9 @@ import org.springframework.test.web.servlet.MockMvc; // The test classpath carries persistence-jpa, which is on while present; this slice excludes // the data layer, so it switches the module off too. "ca-skeleton.persistence-jpa.enabled=false", - "management.endpoints.web.exposure.include=health,prometheus,info,loggers", + "management.endpoints.web.exposure.include=health,prometheus,info", "management.endpoints.web.exposure.exclude=env,configprops,heapdump,threaddump,shutdown", - "management.endpoint.health.show-details=when-authorized", - "management.endpoint.loggers.enabled=true" + "management.endpoint.health.show-details=never" }) @AutoConfigureMockMvc // @SpringBootTest disables observability by default; re-enable metrics so the Prometheus @@ -80,11 +76,11 @@ class ActuatorSecurityHttpTest { } @Test - void loggersEndpointChallengesUnauthenticatedCallerWith401() throws Exception { - // D3: a protected actuator endpoint must answer 401 (unauthenticated), NOT the framework - // default 403. 401 is the correct "you must authenticate" semantics; 403 means + void actuatorLinksChallengeUnauthenticatedCallerWith401() throws Exception { + // D3: anything on the actuator chain beyond the probes must answer 401 (unauthenticated), NOT + // the framework default 403. 401 is the correct "you must authenticate" semantics; 403 means // "authenticated but forbidden". - mvc.perform(get("/actuator/loggers")).andExpect(status().isUnauthorized()); + mvc.perform(get("/actuator")).andExpect(status().isUnauthorized()); } @Test @@ -93,32 +89,11 @@ class ActuatorSecurityHttpTest { mvc.perform(get("/actuator/env")).andExpect(status().isNotFound()); } - // ---- F3: loggers is READ-ONLY (D2) — reads need auth, writes are denied for everyone ---- - @Test - void loggersReadIsAllowedForAuthenticatedCaller() throws Exception { - mvc.perform(get("/actuator/loggers").with(user("ops"))).andExpect(status().isOk()); - } - - @Test - void loggersWriteIsDeniedEvenForAuthenticatedCaller() throws Exception { - // D2 "loggers prod read-only": a runtime log-level change (POST) must be denied (403) - // even for an authenticated caller — authentication alone must not grant write. - mvc.perform( - post("/actuator/loggers/dev.caskeleton") - .with(user("ops")) - .contentType(MediaType.APPLICATION_JSON) - .content("{\"configuredLevel\":\"DEBUG\"}")) - .andExpect(status().isForbidden()); - } - - @Test - void loggersResetViaDeleteIsDenied() throws Exception { - // D2: A logger-level reset (DELETE /actuator/loggers/{name}) is also a write mutation - // that reverts a logger to its default level. It must be denied (403) for everyone — - // authentication alone must not grant write, just as for POST. - mvc.perform(delete("/actuator/loggers/dev.caskeleton").with(user("ops"))) - .andExpect(status().isForbidden()); + void loggersEndpointIsNotExposed() throws Exception { + // The actuator chain has no authentication mechanism, so an authenticated-only loggers read + // was reachable by nobody. It is not exposed rather than exposed and unreachable. + mvc.perform(get("/actuator/loggers").with(user("ops"))).andExpect(status().isNotFound()); } @EnableAutoConfiguration( diff --git a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/ConfigurationNamespaceContractTest.java b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/ConfigurationNamespaceContractTest.java index 76a7fb2c..a52cc4e7 100644 --- a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/ConfigurationNamespaceContractTest.java +++ b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/ConfigurationNamespaceContractTest.java @@ -57,7 +57,9 @@ class ConfigurationNamespaceContractTest { * The roots a shipped resource may declare. * *

{@code spring} and {@code management} / {@code server} / {@code logging} / {@code springdoc} - * are framework namespaces — this application does not own their shape, only their values. + * are framework namespaces — this application does not own their shape, only their values. So is + * {@code info}: Boot's {@code /actuator/info} publishes that tree as it is, and each capability + * module adds its own {@code info.capabilities.} entry for the Compose smoke lanes to read. */ private static final Set ALLOWED_ROOTS = Set.of( @@ -66,6 +68,7 @@ class ConfigurationNamespaceContractTest { "server", "logging", "springdoc", + "info", "ca-skeleton", "app", "backend"); diff --git a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/ManagementActuatorSecurityContractTest.java b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/ManagementActuatorSecurityContractTest.java index 8dd68d79..e9e73b4d 100644 --- a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/ManagementActuatorSecurityContractTest.java +++ b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/contract/ManagementActuatorSecurityContractTest.java @@ -38,8 +38,8 @@ import org.yaml.snakeyaml.Yaml; * server.port=8080. *

  • {@code actuator-contract:exposure-policy} — env/configprops/heapdump/threaddump/shutdown * NOT in include set. - *
  • {@code actuator-contract:show-details-when-authorized} — health show-details = - * when-authorized, not always. + *
  • {@code actuator-contract:show-details-never} — health show-details = never. The actuator + * chain has no authentication mechanism, so when-authorized could never show them to anyone. * * *

    The registry and linked runbook are checked-in contract resources. Missing resources are hard @@ -138,7 +138,7 @@ class ManagementActuatorSecurityContractTest { new ApplicationContextRunner() .withUserConfiguration(WebEndpointPropertiesConfig.class) .withPropertyValues( - "management.endpoints.web.exposure.include=health,prometheus,info,loggers", + "management.endpoints.web.exposure.include=health,prometheus,info", "management.endpoints.web.exposure.exclude=env,configprops,heapdump,threaddump,shutdown") .run( context -> { @@ -189,7 +189,7 @@ class ManagementActuatorSecurityContractTest { // Exactly the safe, scrape/probe-friendly endpoints — no more. assertThat(includeSet) .as("application.yml management.endpoints.web.exposure.include (D2 allowlist)") - .containsExactlyInAnyOrder("health", "prometheus", "info", "loggers"); + .containsExactlyInAnyOrder("health", "prometheus", "info"); // Dangerous endpoints must never appear in the include allowlist. assertThat(includeSet) .as("D2/D4/D5: dangerous endpoints must not be in application.yml include") @@ -221,12 +221,12 @@ class ManagementActuatorSecurityContractTest { } @Test - void applicationYmlPinsShowDetailsWhenAuthorizedAndShutdownDisabled() { + void applicationYmlPinsShowDetailsNeverAndShutdownDisabled() { Map mgmt = managementSubtree(); assertThat(String.valueOf(nested(mgmt, "endpoint", "health", "show-details"))) - .as("application.yml management.endpoint.health.show-details (D8) must be when-authorized") - .isEqualTo("when-authorized"); + .as("application.yml management.endpoint.health.show-details (D8) must be never") + .isEqualTo("never"); assertThat(nested(mgmt, "endpoint", "shutdown", "access")) .as("application.yml management.endpoint.shutdown.access (D4) must be none") .isEqualTo("none"); diff --git a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/runtime/OperationalContractRuntimeTest.java b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/runtime/OperationalContractRuntimeTest.java index aba03c71..7e173d7a 100644 --- a/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/runtime/OperationalContractRuntimeTest.java +++ b/src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/runtime/OperationalContractRuntimeTest.java @@ -21,6 +21,8 @@ import org.junit.jupiter.api.Test; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.autoconfigure.ImportAutoConfiguration; import org.springframework.boot.context.properties.EnableConfigurationProperties; +import org.springframework.boot.security.autoconfigure.web.servlet.SecurityFilterAutoConfiguration; +import org.springframework.boot.web.servlet.DelegatingFilterProxyRegistrationBean; import org.springframework.boot.web.servlet.FilterRegistrationBean; import org.springframework.boot.web.servlet.ServletContextInitializerBeans; import org.springframework.boot.webmvc.test.autoconfigure.AutoConfigureMockMvc; @@ -50,7 +52,14 @@ import org.springframework.web.bind.annotation.RestController; */ @WebMvcTest(CaSkeletonApplication.class) @AutoConfigureMockMvc(addFilters = false) -@ImportAutoConfiguration({WebAdapterAutoConfiguration.class, WebMvcPlatformAutoConfiguration.class}) +// SecurityFilterAutoConfiguration registers springSecurityFilterChain as a servlet filter, which +// the +// MVC slice leaves out; the order test compares the request-id filter against that registration. +@ImportAutoConfiguration({ + WebAdapterAutoConfiguration.class, + WebMvcPlatformAutoConfiguration.class, + SecurityFilterAutoConfiguration.class +}) // RequestLoggingFilter (a @Component filter the broad CaSkeletonApplication slice scan // instantiates) now requires a UserPrincipalPseudonymizerPort; PseudonymizationConfig supplies it // (and binds PrivacySettings from the test salt) so the slice context can be built. @@ -122,6 +131,25 @@ class OperationalContractRuntimeTest { .isLessThan(registrationOrders.get(RequestLoggingFilter.class)); } + @Test + void requestIdFilterIsRegisteredAheadOfSpringSecurity() { + // given: a 401/403 written inside the security chain reads its meta ids from MDC + Map orders = new java.util.HashMap<>(); + + // when + for (var initializer : new ServletContextInitializerBeans(ctx)) { + if (initializer instanceof FilterRegistrationBean registration + && registration.getFilter() instanceof WebMvcRequestIdFilter) { + orders.put("requestId", registration.getOrder()); + } else if (initializer instanceof DelegatingFilterProxyRegistrationBean springSecurity) { + orders.put("security", springSecurity.getOrder()); + } + } + + // then + assertThat(orders.get("requestId")).isLessThan(orders.get("security")); + } + @Test void envelopeAdviceWrapsRawControllerBody() throws Exception { mockMvc diff --git a/src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyExecutor.java b/src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyExecutor.java index 5800e070..f7f2ab9c 100644 --- a/src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyExecutor.java +++ b/src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyExecutor.java @@ -194,22 +194,27 @@ public final class IdempotencyExecutor { } catch (RuntimeException failure) { // The action threw without saying whether it had an effect, so the record must not say // "retryable": that would invite a second execution of something that may already have run. - preserveUnknown(owner, operationId); + recordFailure( + owner, IdempotencyFailureDisposition.EFFECT_UNKNOWN_ABANDONED, operationId, failure); throw failure; } return switch (outcome) { case IdempotentAction.Outcome.Success success -> complete(request, owner, success.result(), codec, false); case IdempotentAction.Outcome.RetryableNoEffect retryable -> { - store.markFailed( + recordFailure( owner, IdempotencyFailureDisposition.NO_EFFECT_RETRYABLE, - failureRetention, - operationId); + operationId, + retryable.failure()); throw retryable.failure(); } case IdempotentAction.Outcome.EffectUnknown unknown -> { - preserveUnknown(owner, operationId); + recordFailure( + owner, + IdempotencyFailureDisposition.EFFECT_UNKNOWN_ABANDONED, + operationId, + unknown.failure()); throw unknown.failure(); } }; @@ -265,12 +270,22 @@ public final class IdempotencyExecutor { }; } - private void preserveUnknown(IdempotencyOwner owner, OperationId operationId) { - store.markFailed( - owner, - IdempotencyFailureDisposition.EFFECT_UNKNOWN_ABANDONED, - failureRetention, - operationId); + /** + * Records the action's failure. The caller must still see that failure: a store that fails here + * is attached to it as suppressed instead of replacing it. + */ + private void recordFailure( + IdempotencyOwner owner, + IdempotencyFailureDisposition disposition, + OperationId operationId, + RuntimeException failure) { + try { + store.markFailed(owner, disposition, failureRetention, operationId); + } catch (RuntimeException storeFailure) { + if (storeFailure != failure) { + failure.addSuppressed(storeFailure); + } + } } private IdempotencyInspection inspect(IdempotencyClaimRequest request) { diff --git a/src/application-core/src/main/java/dev/caskeleton/application/messaging/contract/Sha256.java b/src/application-core/src/main/java/dev/caskeleton/application/messaging/contract/Sha256.java index 4a614789..dc1507d0 100644 --- a/src/application-core/src/main/java/dev/caskeleton/application/messaging/contract/Sha256.java +++ b/src/application-core/src/main/java/dev/caskeleton/application/messaging/contract/Sha256.java @@ -1,5 +1,7 @@ package dev.caskeleton.application.messaging.contract; +import java.security.MessageDigest; +import java.security.NoSuchAlgorithmException; import java.util.Arrays; import java.util.HexFormat; @@ -16,6 +18,16 @@ public record Sha256(byte[] bytes) { bytes = bytes.clone(); } + /** The SHA-256 digest of {@code content}. */ + public static Sha256 of(byte[] content) { + try { + return new Sha256(MessageDigest.getInstance("SHA-256").digest(content)); + } catch (NoSuchAlgorithmException e) { + // SHA-256 is mandated by every JDK — unreachable. + throw new IllegalStateException("SHA-256 algorithm unavailable", e); + } + } + @Override public byte[] bytes() { return bytes.clone(); diff --git a/src/application-core/src/main/java/dev/caskeleton/application/messaging/event/ValidatedIntegrationEvent.java b/src/application-core/src/main/java/dev/caskeleton/application/messaging/event/ValidatedIntegrationEvent.java index ea6016e7..27cd2dbc 100644 --- a/src/application-core/src/main/java/dev/caskeleton/application/messaging/event/ValidatedIntegrationEvent.java +++ b/src/application-core/src/main/java/dev/caskeleton/application/messaging/event/ValidatedIntegrationEvent.java @@ -33,7 +33,8 @@ public record ValidatedIntegrationEvent( String contractCatalogRevision, String destinationBindingRevision) { - private static final String CORRELATION_GRAMMAR = "[A-Za-z0-9][A-Za-z0-9._:-]*"; + // 128 characters: the width of the outbox correlation_id and causation_id columns. + private static final String CORRELATION_GRAMMAR = "[A-Za-z0-9][A-Za-z0-9._:-]{0,127}"; private static final String REVISION_GRAMMAR = "[a-z0-9][a-z0-9._:-]{0,95}"; private static final String CONTENT_TYPE_GRAMMAR = "[a-z0-9!#$&^_.+-]+/[a-z0-9!#$&^_.+-]+"; @@ -81,6 +82,11 @@ public record ValidatedIntegrationEvent( || payloadSchemaHash == null) { throw new IllegalArgumentException("validated schema and envelope hashes must not be null"); } + // A row restored from the outbox carries a stored hash; trusting it would publish bytes that + // were never the ones validated. + if (!envelopeSha256.equals(Sha256.of(envelopeBytes))) { + throw new IllegalArgumentException("envelopeSha256 must be the SHA-256 of envelopeBytes"); + } requireCanonicalIdentity("contractCatalogRevision", contractCatalogRevision, REVISION_GRAMMAR); requireCanonicalIdentity( "destinationBindingRevision", destinationBindingRevision, REVISION_GRAMMAR); diff --git a/src/application-core/src/main/java/dev/caskeleton/application/operation/DurableOperationStorePort.java b/src/application-core/src/main/java/dev/caskeleton/application/operation/DurableOperationStorePort.java index 2b4772b5..440d3fb2 100644 --- a/src/application-core/src/main/java/dev/caskeleton/application/operation/DurableOperationStorePort.java +++ b/src/application-core/src/main/java/dev/caskeleton/application/operation/DurableOperationStorePort.java @@ -24,9 +24,10 @@ public interface DurableOperationStorePort { * rather than a second one is what makes a resubmission safe while the first is still running. * * @param submission what was accepted - * @return the operation, whether newly created or already present + * @return the operation, and whether this call created it; a retry under the same operation id is + * not a creation */ - DurableOperation submit(DurableOperationSubmission submission); + DurableOperationSubmitResult submit(DurableOperationSubmission submission); /** * Reads an operation the caller is entitled to see. diff --git a/src/application-core/src/main/java/dev/caskeleton/application/operation/DurableOperationSubmitResult.java b/src/application-core/src/main/java/dev/caskeleton/application/operation/DurableOperationSubmitResult.java new file mode 100644 index 00000000..1d43820a --- /dev/null +++ b/src/application-core/src/main/java/dev/caskeleton/application/operation/DurableOperationSubmitResult.java @@ -0,0 +1,21 @@ +package dev.caskeleton.application.operation; + +import java.util.Objects; + +/** + * What a store did with a submission. + * + *

    {@code created} comes from the store's own write, not from comparing identifiers afterwards. A + * retry under the same operation id finds the operation it created itself, and an identifier + * comparison cannot tell that retry from the first call — which is how a retry appended its outbox + * event a second time. + * + * @param operation the operation holding the submission's scope + * @param created whether this call inserted it + */ +public record DurableOperationSubmitResult(DurableOperation operation, boolean created) { + + public DurableOperationSubmitResult { + Objects.requireNonNull(operation, "operation"); + } +} diff --git a/src/application-core/src/main/java/dev/caskeleton/application/operation/OperationCommand.java b/src/application-core/src/main/java/dev/caskeleton/application/operation/OperationCommand.java index 0a397786..3a5c6cce 100644 --- a/src/application-core/src/main/java/dev/caskeleton/application/operation/OperationCommand.java +++ b/src/application-core/src/main/java/dev/caskeleton/application/operation/OperationCommand.java @@ -31,6 +31,19 @@ public record OperationCommand( String eventType, Duration timeToLive) { + /** + * The outbox event type for an operation whose caller does not publish an event of its own, such + * as the HTTP operation endpoint. + * + *

    One type for all of them: the event only wakes a worker, and the worker reads what to run + * from the submission it claims. Letting such a caller choose the type would let it publish any + * event the broker carries. + */ + public static final String SUBMITTED_EVENT_TYPE = "DurableOperationSubmitted"; + + /** How long an operation submitted without a caller-specific lifetime stays pollable. */ + public static final Duration DEFAULT_TIME_TO_LIVE = Duration.ofDays(1); + public OperationCommand { Objects.requireNonNull(operationId, "operationId"); Objects.requireNonNull(operationName, "operationName"); diff --git a/src/application-core/src/main/java/dev/caskeleton/application/operation/SubmitDurableOperationUseCase.java b/src/application-core/src/main/java/dev/caskeleton/application/operation/SubmitDurableOperationUseCase.java index 8dbf3d47..52f143dc 100644 --- a/src/application-core/src/main/java/dev/caskeleton/application/operation/SubmitDurableOperationUseCase.java +++ b/src/application-core/src/main/java/dev/caskeleton/application/operation/SubmitDurableOperationUseCase.java @@ -96,8 +96,11 @@ public class SubmitDurableOperationUseCase { command.payload(), clock.instant(), command.timeToLive()); - DurableOperation operation = operations.submit(submission); - boolean alreadyAccepted = !operation.operationId().equals(command.operationId()); + DurableOperationSubmitResult submitted = operations.submit(submission); + DurableOperation operation = submitted.operation(); + // The store's answer, not an id comparison: a retry under the same operation id finds + // the operation it created itself, and the ids match. + boolean alreadyAccepted = !submitted.created(); if (!alreadyAccepted) { // Appended only for a genuinely new operation. A second outbox row for the same diff --git a/src/application-core/src/main/java/dev/caskeleton/application/outbox/OutboxStorePort.java b/src/application-core/src/main/java/dev/caskeleton/application/outbox/OutboxStorePort.java index df892933..2ce8bd00 100644 --- a/src/application-core/src/main/java/dev/caskeleton/application/outbox/OutboxStorePort.java +++ b/src/application-core/src/main/java/dev/caskeleton/application/outbox/OutboxStorePort.java @@ -61,10 +61,13 @@ public interface OutboxStorePort { OutboxCompletion markDead(OutboxLease lease); /** - * Returns a count of rows grouped by {@link OutboxEventStatus} — gauge source for the {@code - * outbox.pending.size} metric. Called outside a transaction (read-only). + * Returns a count of unpublished rows grouped by {@link OutboxEventStatus} — gauge source for the + * {@code outbox.pending.size} metric. Called outside a transaction (read-only). * - * @return map from status to row count; statuses with zero rows may be absent + *

    PUBLISHED is never counted: those rows wait on nothing, and counting them would scan the + * whole retention window on every poll. + * + * @return map from status to row count; PUBLISHED and statuses with zero rows are absent */ Map countByStatus(); diff --git a/src/application-core/src/test/java/dev/caskeleton/application/idempotency/IdempotencyExecutorTest.java b/src/application-core/src/test/java/dev/caskeleton/application/idempotency/IdempotencyExecutorTest.java index 3b712843..9975c742 100644 --- a/src/application-core/src/test/java/dev/caskeleton/application/idempotency/IdempotencyExecutorTest.java +++ b/src/application-core/src/test/java/dev/caskeleton/application/idempotency/IdempotencyExecutorTest.java @@ -2,14 +2,20 @@ package dev.caskeleton.application.idempotency; import static org.assertj.core.api.Assertions.assertThat; import static org.assertj.core.api.Assertions.assertThatThrownBy; +import static org.assertj.core.api.Assertions.catchThrowable; import dev.caskeleton.application.transaction.OperationId; import java.time.Duration; import java.time.Instant; import java.util.Optional; import java.util.concurrent.atomic.AtomicBoolean; +import java.util.function.Function; +import java.util.stream.Stream; import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.Arguments; +import org.junit.jupiter.params.provider.MethodSource; /** * The request-replay lifecycle, over the contract the stores implement. @@ -231,6 +237,44 @@ class IdempotencyExecutorTest { assertThat(store.lastDisposition).isEqualTo(IdempotencyFailureDisposition.NO_EFFECT_RETRYABLE); } + @ParameterizedTest(name = "{0}") + @MethodSource("failingActions") + void aStoreFailureWhileRecordingTheActionFailureIsSuppressedUnderIt( + String shape, Function> failingAction) { + // given + FakeStore store = startedStore(); + RuntimeException storeFailure = new IllegalStateException("store unavailable"); + store.markFailedFailure = storeFailure; + RuntimeException actionFailure = new IllegalArgumentException("provider response unknown"); + + // when + Throwable thrown = + catchThrowable( + () -> + executor(store) + .execute( + SCOPE, FINGERPRINT, ATTEMPT, failingAction.apply(actionFailure), codec())); + + // then + assertThat(thrown).isSameAs(actionFailure).hasSuppressedException(storeFailure); + } + + static Stream failingActions() { + Function> throwing = + failure -> + () -> { + throw failure; + }; + Function> effectUnknown = + failure -> () -> new IdempotentAction.Outcome.EffectUnknown<>(failure); + Function> retryable = + failure -> () -> new IdempotentAction.Outcome.RetryableNoEffect<>(failure); + return Stream.of( + Arguments.of("thrown", throwing), + Arguments.of("effect unknown", effectUnknown), + Arguments.of("retryable no effect", retryable)); + } + private static FakeStore startedStore() { FakeStore store = new FakeStore(); store.claim = new IdempotencyClaimOutcome.Acquired(owner(0), LEASE_UNTIL); @@ -271,6 +315,7 @@ class IdempotencyExecutorTest { private int failedCalls; private IdempotencyOwner completeOwner; private IdempotencyFailureDisposition lastDisposition; + private RuntimeException markFailedFailure; @Override public IdempotencyClaimAttempt newClaimAttempt(OperationId operationId) { @@ -320,6 +365,9 @@ class IdempotencyExecutorTest { OperationId operationId) { failedCalls++; lastDisposition = disposition; + if (markFailedFailure != null) { + throw markFailedFailure; + } return disposition == IdempotencyFailureDisposition.NO_EFFECT_RETRYABLE ? IdempotencyFailOutcome.MARKED_RETRYABLE : IdempotencyFailOutcome.MARKED_ABANDONED; diff --git a/src/application-core/src/test/java/dev/caskeleton/application/messaging/event/ValidatedIntegrationEventTest.java b/src/application-core/src/test/java/dev/caskeleton/application/messaging/event/ValidatedIntegrationEventTest.java index 4fca830a..bc2b3713 100644 --- a/src/application-core/src/test/java/dev/caskeleton/application/messaging/event/ValidatedIntegrationEventTest.java +++ b/src/application-core/src/test/java/dev/caskeleton/application/messaging/event/ValidatedIntegrationEventTest.java @@ -2,6 +2,7 @@ package dev.caskeleton.application.messaging.event; import static org.assertj.core.api.Assertions.assertThat; import static org.assertj.core.api.Assertions.assertThatThrownBy; +import static org.assertj.core.api.Assertions.catchThrowable; import dev.caskeleton.application.messaging.contract.ContractId; import dev.caskeleton.application.messaging.contract.LogicalDestinationId; @@ -15,6 +16,8 @@ import org.junit.jupiter.api.Test; class ValidatedIntegrationEventTest { + private static final Sha256 EMPTY_OBJECT_HASH = Sha256.of("{}".getBytes(StandardCharsets.UTF_8)); + @Test void validatedEventOwnsExactEncodedBytesThroughDefensiveCopies() { byte[] keyBytes = "a".repeat(64).getBytes(StandardCharsets.US_ASCII); @@ -106,7 +109,7 @@ class ValidatedIntegrationEventTest { .isEqualTo(new AggregateIdentity("tenant-a", "worklog", "worklog-42")); assertThat(event.order()).isEqualTo(new AggregateOrder(17, 0)); assertThat(event.contentType()).isEqualTo("application/json"); - assertThat(event.envelopeSha256()).isEqualTo(new Sha256(new byte[32])); + assertThat(event.envelopeSha256()).isEqualTo(EMPTY_OBJECT_HASH); assertThat(event.contractCatalogRevision()).isEqualTo("catalog-r1"); assertThat(event.destinationBindingRevision()).isEqualTo("binding-r1"); @@ -126,12 +129,92 @@ class ValidatedIntegrationEventTest { return event(keyBytes, envelopeBytes, "a".repeat(64), 1, 1); } + @Test + void envelopeHashThatIsNotTheSha256OfTheEnvelopeBytesIsRefused() { + // given + Sha256 storedHash = Sha256.of("{\"tampered\":true}".getBytes(StandardCharsets.UTF_8)); + + // when + Throwable thrown = catchThrowable(() -> withIdentities("corr-1", Optional.empty(), storedHash)); + + // then + assertThat(thrown) + .isInstanceOf(IllegalArgumentException.class) + .hasMessage("envelopeSha256 must be the SHA-256 of envelopeBytes"); + } + + @Test + void correlationIdOf128CharactersIsAccepted() { + String longest = "c".repeat(128); + + assertThat(withIdentities(longest, Optional.empty(), EMPTY_OBJECT_HASH).correlationId()) + .isEqualTo(longest); + } + + @Test + void correlationIdLongerThan128CharactersIsRefused() { + // when + Throwable thrown = + catchThrowable(() -> withIdentities("c".repeat(129), Optional.empty(), EMPTY_OBJECT_HASH)); + + // then + assertThat(thrown) + .isInstanceOf(IllegalArgumentException.class) + .hasMessage("correlationId must be a canonical bounded US-ASCII identity"); + } + + @Test + void causationIdLongerThan128CharactersIsRefused() { + // when + Throwable thrown = + catchThrowable( + () -> withIdentities("corr-1", Optional.of("c".repeat(129)), EMPTY_OBJECT_HASH)); + + // then + assertThat(thrown) + .isInstanceOf(IllegalArgumentException.class) + .hasMessage("causationId must be a canonical bounded US-ASCII identity"); + } + + private static ValidatedIntegrationEvent withIdentities( + String correlationId, Optional causationId, Sha256 envelopeSha256) { + return event( + "a".repeat(64).getBytes(StandardCharsets.US_ASCII), + "{}".getBytes(StandardCharsets.UTF_8), + "a".repeat(64), + 1, + 1, + correlationId, + causationId, + envelopeSha256); + } + private static ValidatedIntegrationEvent event( byte[] keyBytes, byte[] envelopeBytes, String keyText, int envelopeVersion, int payloadVersion) { + return event( + keyBytes, + envelopeBytes, + keyText, + envelopeVersion, + payloadVersion, + "corr-1", + Optional.of("cause-1"), + Sha256.of(envelopeBytes)); + } + + private static ValidatedIntegrationEvent event( + byte[] keyBytes, + byte[] envelopeBytes, + String keyText, + int envelopeVersion, + int payloadVersion, + String correlationId, + Optional causationId, + Sha256 envelopeSha256) { Sha256 hash = new Sha256(new byte[32]); return new ValidatedIntegrationEvent( new EventId("event-1"), @@ -142,14 +225,14 @@ class ValidatedIntegrationEventTest { new AggregateIdentity("tenant-a", "worklog", "worklog-42"), new AggregateOrder(17, 0), Instant.parse("2026-07-28T05:10:30.123Z"), - "corr-1", - Optional.of("cause-1"), + correlationId, + causationId, keyText, keyBytes, envelopeBytes, "application/json", hash, - hash, + envelopeSha256, hash, hash, "catalog-r1", diff --git a/src/application-core/src/test/java/dev/caskeleton/application/operation/GetDurableOperationUseCaseTest.java b/src/application-core/src/test/java/dev/caskeleton/application/operation/GetDurableOperationUseCaseTest.java index 85c7357b..292cce01 100644 --- a/src/application-core/src/test/java/dev/caskeleton/application/operation/GetDurableOperationUseCaseTest.java +++ b/src/application-core/src/test/java/dev/caskeleton/application/operation/GetDurableOperationUseCaseTest.java @@ -25,7 +25,7 @@ class GetDurableOperationUseCaseTest { @Test void submitterReadsTheirOperation() { // given - DurableOperation submitted = operations.submit(submission("t-1")); + DurableOperation submitted = operations.submit(submission("t-1")).operation(); // when Optional read = diff --git a/src/application-core/src/test/java/dev/caskeleton/application/operation/SubmitDurableOperationUseCaseTest.java b/src/application-core/src/test/java/dev/caskeleton/application/operation/SubmitDurableOperationUseCaseTest.java index 3b03ce3d..f333d717 100644 --- a/src/application-core/src/test/java/dev/caskeleton/application/operation/SubmitDurableOperationUseCaseTest.java +++ b/src/application-core/src/test/java/dev/caskeleton/application/operation/SubmitDurableOperationUseCaseTest.java @@ -104,6 +104,18 @@ class SubmitDurableOperationUseCaseTest { assertThat(outbox.appended).hasSize(1); } + @Test + void retryUnderTheSameOperationIdAppendsTheOutboxEventOnlyOnce() { + // given + useCase.submit(command(ID, "a".repeat(64))); + + // when + OperationAcceptance retry = useCase.submit(command(ID, "a".repeat(64))); + + // then + assertThat(List.of(retry.alreadyAccepted(), outbox.appended.size())).containsExactly(true, 1); + } + @Test @DisplayName("a different request under the same principal is a different operation") void differentRequestsAreDifferentOperations() { diff --git a/src/application-core/src/test/java/dev/caskeleton/application/outbox/ClaimedOutboxEventContractTest.java b/src/application-core/src/test/java/dev/caskeleton/application/outbox/ClaimedOutboxEventContractTest.java index 5efc9781..3e24fafa 100644 --- a/src/application-core/src/test/java/dev/caskeleton/application/outbox/ClaimedOutboxEventContractTest.java +++ b/src/application-core/src/test/java/dev/caskeleton/application/outbox/ClaimedOutboxEventContractTest.java @@ -52,6 +52,7 @@ class ClaimedOutboxEventContractTest { private static ValidatedIntegrationEvent canonicalEvent() { String partition = "a".repeat(64); + byte[] envelope = "{\"wire\":\"exact\"}".getBytes(StandardCharsets.UTF_8); Sha256 zero = new Sha256(new byte[32]); return new ValidatedIntegrationEvent( new EventId("01994e11-4d88-7000-8000-000000000001"), @@ -66,10 +67,10 @@ class ClaimedOutboxEventContractTest { Optional.empty(), partition, partition.getBytes(StandardCharsets.US_ASCII), - "{\"wire\":\"exact\"}".getBytes(StandardCharsets.UTF_8), + envelope, "application/json", zero, - zero, + Sha256.of(envelope), zero, zero, "catalog-r1", diff --git a/src/application-core/src/testFixtures/java/dev/caskeleton/application/operation/testkit/DurableOperationStoreContract.java b/src/application-core/src/testFixtures/java/dev/caskeleton/application/operation/testkit/DurableOperationStoreContract.java index 17d72dd1..4be958d2 100644 --- a/src/application-core/src/testFixtures/java/dev/caskeleton/application/operation/testkit/DurableOperationStoreContract.java +++ b/src/application-core/src/testFixtures/java/dev/caskeleton/application/operation/testkit/DurableOperationStoreContract.java @@ -8,6 +8,7 @@ import dev.caskeleton.application.operation.DurableOperationId; import dev.caskeleton.application.operation.DurableOperationState; import dev.caskeleton.application.operation.DurableOperationStorePort; import dev.caskeleton.application.operation.DurableOperationSubmission; +import dev.caskeleton.application.operation.DurableOperationSubmitResult; import dev.caskeleton.application.operation.OperationFailure; import dev.caskeleton.application.operation.OperationLease; import dev.caskeleton.application.operation.OperationProgressSnapshot; @@ -40,46 +41,60 @@ public abstract class DurableOperationStoreContract { protected abstract T inTransaction(Supplier work); @Test - void submitReturnsAPendingOperation() { + void firstSubmitCreatesAPendingOperation() { // when - DurableOperation submitted = submit(submission("op-1", null, HASH_A)); + DurableOperationSubmitResult submitted = submit(submission("op-1", null, HASH_A)); // then assertThat(submitted) .usingRecursiveComparison() .isEqualTo( - new DurableOperation( - id("op-1"), - "reports.generate", - "alice", - null, - DurableOperationState.PENDING, - NOW, - Optional.empty(), - Optional.empty(), - Optional.empty(), - Optional.empty(), - Optional.empty(), - Optional.empty(), - NOW.plus(TTL))); + new DurableOperationSubmitResult( + new DurableOperation( + id("op-1"), + "reports.generate", + "alice", + null, + DurableOperationState.PENDING, + NOW, + Optional.empty(), + Optional.empty(), + Optional.empty(), + Optional.empty(), + Optional.empty(), + Optional.empty(), + NOW.plus(TTL)), + true)); } @Test - void identicalResubmissionReturnsTheFirstOperation() { + void identicalResubmissionReturnsTheFirstOperationAsNotCreated() { // given - DurableOperation first = submit(submission("op-1", null, HASH_A)); + DurableOperationSubmitResult first = submit(submission("op-1", null, HASH_A)); // when - DurableOperation again = submit(submission("op-2", null, HASH_A)); + DurableOperationSubmitResult again = submit(submission("op-2", null, HASH_A)); // then - assertThat(again).isEqualTo(first); + assertThat(again).isEqualTo(new DurableOperationSubmitResult(first.operation(), false)); + } + + @Test + void retryUnderTheSameOperationIdReturnsTheOperationAsNotCreated() { + // given + DurableOperationSubmitResult first = submit(submission("op-1", null, HASH_A)); + + // when + DurableOperationSubmitResult retry = submit(submission("op-1", null, HASH_A)); + + // then + assertThat(retry).isEqualTo(new DurableOperationSubmitResult(first.operation(), false)); } @Test void identicalResubmissionInsideOneTransactionReturnsTheFirstOperation() { // when - DurableOperation again = + DurableOperationSubmitResult again = inTransaction( () -> { store().submit(submission("op-1", null, HASH_A)); @@ -87,7 +102,10 @@ public abstract class DurableOperationStoreContract { }); // then - assertThat(again.operationId()).isEqualTo(id("op-1")); + assertThat(again) + .extracting( + result -> result.operation().operationId(), DurableOperationSubmitResult::created) + .containsExactly(id("op-1"), false); } @Test @@ -96,10 +114,13 @@ public abstract class DurableOperationStoreContract { submit(submission("op-1", null, HASH_A)); // when - DurableOperation second = submit(submission("op-2", null, HASH_B)); + DurableOperationSubmitResult second = submit(submission("op-2", null, HASH_B)); // then - assertThat(second.operationId()).isEqualTo(id("op-2")); + assertThat(second) + .extracting( + result -> result.operation().operationId(), DurableOperationSubmitResult::created) + .containsExactly(id("op-2"), true); } @Test @@ -108,7 +129,7 @@ public abstract class DurableOperationStoreContract { submit(submission("op-1", null, HASH_A)); // when - DurableOperation tenantScoped = submit(submission("op-2", "t-1", HASH_A)); + DurableOperation tenantScoped = submit(submission("op-2", "t-1", HASH_A)).operation(); // then assertThat(tenantScoped) @@ -119,7 +140,7 @@ public abstract class DurableOperationStoreContract { @Test void findReturnsTheOperationToItsPrincipal() { // given - DurableOperation submitted = submit(submission("op-1", null, HASH_A)); + DurableOperation submitted = submit(submission("op-1", null, HASH_A)).operation(); // when Optional found = find("op-1", "alice", NOW); @@ -401,7 +422,7 @@ public abstract class DurableOperationStoreContract { assertThat(expired).containsExactly(id("op-2")); } - private DurableOperation submit(DurableOperationSubmission submission) { + private DurableOperationSubmitResult submit(DurableOperationSubmission submission) { return inTransaction(() -> store().submit(submission)); } diff --git a/src/application-core/src/testFixtures/java/dev/caskeleton/application/operation/testkit/InMemoryDurableOperationStore.java b/src/application-core/src/testFixtures/java/dev/caskeleton/application/operation/testkit/InMemoryDurableOperationStore.java index 33de76cc..077db829 100644 --- a/src/application-core/src/testFixtures/java/dev/caskeleton/application/operation/testkit/InMemoryDurableOperationStore.java +++ b/src/application-core/src/testFixtures/java/dev/caskeleton/application/operation/testkit/InMemoryDurableOperationStore.java @@ -5,6 +5,7 @@ import dev.caskeleton.application.operation.DurableOperationId; import dev.caskeleton.application.operation.DurableOperationState; import dev.caskeleton.application.operation.DurableOperationStorePort; import dev.caskeleton.application.operation.DurableOperationSubmission; +import dev.caskeleton.application.operation.DurableOperationSubmitResult; import dev.caskeleton.application.operation.OperationFailure; import dev.caskeleton.application.operation.OperationLease; import dev.caskeleton.application.operation.OperationProgressSnapshot; @@ -36,7 +37,7 @@ public final class InMemoryDurableOperationStore implements DurableOperationStor new ConcurrentHashMap<>(); @Override - public DurableOperation submit(DurableOperationSubmission submission) { + public DurableOperationSubmitResult submit(DurableOperationSubmission submission) { Scope scope = new Scope( submission.tenantId() == null ? "" : submission.tenantId(), @@ -45,7 +46,7 @@ public final class InMemoryDurableOperationStore implements DurableOperationStor submission.fingerprint().hex()); DurableOperationId existing = byScope.putIfAbsent(scope, submission.operationId()); if (existing != null) { - return byId.get(existing); + return new DurableOperationSubmitResult(byId.get(existing), false); } DurableOperation operation = new DurableOperation( @@ -64,7 +65,7 @@ public final class InMemoryDurableOperationStore implements DurableOperationStor submission.expiresAt()); byId.put(submission.operationId(), operation); submissions.put(submission.operationId(), submission); - return operation; + return new DurableOperationSubmitResult(operation, true); } @Override diff --git a/src/application-core/src/testFixtures/java/dev/caskeleton/application/outbox/testkit/InMemoryOutboxStore.java b/src/application-core/src/testFixtures/java/dev/caskeleton/application/outbox/testkit/InMemoryOutboxStore.java index fdf174ad..9ca43dac 100644 --- a/src/application-core/src/testFixtures/java/dev/caskeleton/application/outbox/testkit/InMemoryOutboxStore.java +++ b/src/application-core/src/testFixtures/java/dev/caskeleton/application/outbox/testkit/InMemoryOutboxStore.java @@ -141,7 +141,9 @@ public class InMemoryOutboxStore implements OutboxStorePort, LegacyOutboxAppendP @Override public Map countByStatus() { Map counts = new EnumMap<>(OutboxEventStatus.class); - rows.values().forEach(row -> counts.merge(row.status, 1L, Long::sum)); + rows.values().stream() + .filter(row -> row.status != OutboxEventStatus.PUBLISHED) + .forEach(row -> counts.merge(row.status, 1L, Long::sum)); return counts; } diff --git a/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/admin/DefaultFileserverAdminService.java b/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/admin/DefaultFileserverAdminService.java index 97beb79b..2da36561 100644 --- a/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/admin/DefaultFileserverAdminService.java +++ b/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/admin/DefaultFileserverAdminService.java @@ -18,7 +18,7 @@ import dev.caskeleton.application.fileserver.cleanup.CleanupBatchResult; import dev.caskeleton.application.fileserver.cleanup.CleanupQueue; import dev.caskeleton.application.fileserver.cleanup.CleanupRequest; import dev.caskeleton.application.fileserver.cleanup.CleanupService; -import dev.caskeleton.application.fileserver.cleanup.CleanupType; +import dev.caskeleton.application.fileserver.cleanup.FileRetirement; import dev.caskeleton.application.fileserver.observability.SafeFileFingerprint; import dev.caskeleton.application.fileserver.upload.FileView; import dev.caskeleton.application.transaction.TransactionPort; @@ -44,6 +44,7 @@ public final class DefaultFileserverAdminService implements FileserverAdminServi private final FileMetadataStore metadataStore; private final UploadSessionStore sessionStore; private final CleanupQueue cleanupQueue; + private final FileRetirement retirement; private final CleanupService cleanupService; private final FileAccessPolicy accessPolicy; private final AdminAuditPort auditPort; @@ -74,6 +75,7 @@ public final class DefaultFileserverAdminService implements FileserverAdminServi this.fingerprint = fingerprint; this.transactions = transactions; this.clock = clock; + this.retirement = new FileRetirement(metadataStore, cleanupQueue); } @Override @@ -162,17 +164,7 @@ public final class DefaultFileserverAdminService implements FileserverAdminServi FileRecord record = requireRecord(command.fileId()); // An operator force-delete must not be able to leave a file unreachable with nothing queued to // reclaim its bytes, so retiring the record and queueing the content commit together. - transactions.inWrite( - () -> { - FileRecord deleting = metadataStore.markDeleting(record.fileId(), record.version()); - deleting - .contentKey() - .ifPresent( - key -> - cleanupQueue.enqueue( - CleanupRequest.forContent( - CleanupType.DELETED_READY_CONTENT, deleting.fileId(), key))); - }); + transactions.inWrite(() -> retirement.retire(record, Optional.empty())); audit( "files:force-delete", command.reasonCode(), diff --git a/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/api/content/FinalizeContentCommand.java b/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/api/content/FinalizeContentCommand.java index f2cc070b..80707167 100644 --- a/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/api/content/FinalizeContentCommand.java +++ b/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/api/content/FinalizeContentCommand.java @@ -1,5 +1,6 @@ package dev.caskeleton.application.fileserver.api.content; +import dev.caskeleton.application.fileserver.api.ContentKey; import java.util.Objects; import java.util.Optional; import java.util.OptionalLong; @@ -9,16 +10,31 @@ import java.util.OptionalLong; * *

    {@code expectedSha256} is the digest the server computed while streaming, not a client * assertion. The store re-verifies length and digest before it exposes anything. + * + *

    {@code contentKey} is the key the caller already recorded for this publish. A publish that + * lands under a key the metadata has never named cannot be found again when its outcome is lost; + * one that lands under the recorded key can. Empty means the store picks a fresh key. */ public record FinalizeContentCommand( OptionalLong expectedLength, Optional expectedSha256, PublishMode publishMode, - boolean forceDurable) { + boolean forceDurable, + Optional contentKey) { public FinalizeContentCommand { Objects.requireNonNull(expectedLength, "expectedLength"); Objects.requireNonNull(expectedSha256, "expectedSha256"); Objects.requireNonNull(publishMode, "publishMode"); + Objects.requireNonNull(contentKey, "contentKey"); + } + + /** A publish under a key the store chooses. */ + public FinalizeContentCommand( + OptionalLong expectedLength, + Optional expectedSha256, + PublishMode publishMode, + boolean forceDurable) { + this(expectedLength, expectedSha256, publishMode, forceDurable, Optional.empty()); } } diff --git a/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/api/metadata/FileRecordMutation.java b/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/api/metadata/FileRecordMutation.java index 9a671c7a..03229fe1 100644 --- a/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/api/metadata/FileRecordMutation.java +++ b/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/api/metadata/FileRecordMutation.java @@ -50,6 +50,22 @@ public record FileRecordMutation( Optional.empty()); } + /** + * Names the key a publish is about to use, before the publish runs. + * + *

    Recorded ahead so a publish whose outcome is lost can be found by its key; the record only + * becomes readable when READY is committed with the same key. + */ + public static FileRecordMutation intendedContentKey(ContentKey contentKey) { + return new FileRecordMutation( + Optional.of(contentKey), + OptionalLong.empty(), + Optional.empty(), + Optional.empty(), + Optional.empty(), + Optional.empty()); + } + public static FileRecordMutation uploaded(long actualSize, String sha256) { return new FileRecordMutation( Optional.empty(), diff --git a/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/api/metadata/QuotaScope.java b/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/api/metadata/QuotaScope.java index bd0b1342..ad845dcf 100644 --- a/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/api/metadata/QuotaScope.java +++ b/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/api/metadata/QuotaScope.java @@ -5,8 +5,9 @@ import java.util.Objects; /** * Accounting boundary for reservations, commits, and concurrency permits. * - *

    A scope is a bounded label such as a tenant or a namespace. It is never a user identifier that - * would make a metric or a log line high-cardinality. + *

    A scope is a label such as a tenant or a namespace. A {@link #ofPrincipal principal} scope + * exists only for in-process transfer admission; it is never persisted as quota and never becomes a + * metric label or a log field, where a user identifier would be high-cardinality. */ public record QuotaScope(String type, String value) { @@ -26,6 +27,13 @@ public record QuotaScope(String type, String value) { return new QuotaScope("tenant", tenant); } + /** + * One caller's concurrent transfers, so a busy caller cannot starve everyone sharing a namespace. + */ + public static QuotaScope ofPrincipal(String principalId) { + return new QuotaScope("principal", principalId); + } + /** Stable key used for lock ordering and permit maps. */ public String canonicalKey() { return type + ':' + value; diff --git a/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/cleanup/CleanupContentGateway.java b/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/cleanup/CleanupContentGateway.java index 6a25438d..3790498e 100644 --- a/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/cleanup/CleanupContentGateway.java +++ b/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/cleanup/CleanupContentGateway.java @@ -16,4 +16,11 @@ public interface CleanupContentGateway { DeleteResult delete(ContentKey key, DeletePrecondition precondition); void discardStaging(UploadId uploadId); + + /** + * Reclaims an orphan the admin plane retired to quarantine, once nothing references it. + * + * @return whether an object was removed + */ + boolean purgeQuarantined(ContentKey key); } diff --git a/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/cleanup/DefaultCleanupService.java b/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/cleanup/DefaultCleanupService.java index 42c40553..cbbd14b1 100644 --- a/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/cleanup/DefaultCleanupService.java +++ b/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/cleanup/DefaultCleanupService.java @@ -118,9 +118,9 @@ public final class DefaultCleanupService implements CleanupService { *

    Nothing else ever did: an abandoned upload refused further appends once it expired, but its * record stayed UPLOADING and its staged bytes stayed on the volume for good. The session is made * terminal first, in the same transaction as the rest, so no writer can take a lease on bytes the - * cleanup is about to delete. Only a record the upload still owns — UPLOADING, or FAILED before - * it was ever published — becomes EXPIRED; any other state belongs to finalize, verification or - * delete, and only its session is closed. + * cleanup is about to delete. Only a record the upload still owns — CREATED, UPLOADING, or FAILED + * before it was ever published — becomes EXPIRED; any other state belongs to finalize, + * verification or delete, and only its session is closed. */ private void expireUploads(Instant now, int limit) { for (UploadSession session : sessionStore.findExpired(now, limit)) { @@ -138,22 +138,33 @@ public final class DefaultCleanupService implements CleanupService { if (!sessionStore.terminate(session.uploadId())) { return; } - metadataStore - .find(session.fileId()) - .filter( - record -> record.state() == FileState.UPLOADING || record.state() == FileState.FAILED) - .ifPresent( - record -> { - metadataStore.transition( - record.fileId(), - record.version(), - record.state(), - FileState.EXPIRED, - FileRecordMutation.failure("UPLOAD_EXPIRED")); - queue.enqueue( - CleanupRequest.forStaging( - CleanupType.EXPIRED_UPLOAD, record.fileId(), session.uploadId())); - }); + Optional found = metadataStore.find(session.fileId()); + if (found.isEmpty()) { + return; + } + FileRecord record = found.get(); + if (record.state() == FileState.CREATED) { + // A crash between the create commit and the staging confirmation. CREATED has no EXPIRED + // edge, so the record takes the one path the table permits, through UPLOADING. + record = + metadataStore.transition( + record.fileId(), + record.version(), + FileState.CREATED, + FileState.UPLOADING, + FileRecordMutation.none()); + } + if (record.state() != FileState.UPLOADING && record.state() != FileState.FAILED) { + return; + } + metadataStore.transition( + record.fileId(), + record.version(), + record.state(), + FileState.EXPIRED, + FileRecordMutation.failure("UPLOAD_EXPIRED")); + queue.enqueue( + CleanupRequest.forStaging(CleanupType.EXPIRED_UPLOAD, record.fileId(), session.uploadId())); } private Outcome process(CleanupItem item, Instant now) { @@ -196,7 +207,25 @@ public final class DefaultCleanupService implements CleanupService { return Outcome.of(OutcomeKind.SKIPPED_ACTIVE_LEASE, 0); } contentGateway.discardStaging(uploadId); - markDone(item); + transactions.inWrite( + () -> { + // A cancelled upload that never published anything has nothing else to wait for; left in + // DELETING it would read as a delete still in progress forever. + item.request() + .fileId() + .flatMap(metadataStore::find) + .filter(current -> current.state() == FileState.DELETING) + .filter(current -> current.contentKey().isEmpty()) + .ifPresent( + current -> + metadataStore.transition( + current.fileId(), + current.version(), + FileState.DELETING, + FileState.DELETED, + FileRecordMutation.none())); + queue.markDone(item); + }); return Outcome.of(OutcomeKind.DELETED, 0); } @@ -209,8 +238,11 @@ public final class DefaultCleanupService implements CleanupService { private Outcome cleanContent(CleanupItem item, ContentKey contentKey) { Optional fileId = item.request().fileId(); if (fileId.isEmpty()) { + // An orphan the admin plane retired to quarantine. Marking it done without the purge left + // every reconciled orphan's bytes in quarantine for good. + boolean purged = contentGateway.purgeQuarantined(contentKey); markDone(item); - return Outcome.of(OutcomeKind.SKIPPED_STATE_CHANGED, 0); + return Outcome.of(purged ? OutcomeKind.DELETED : OutcomeKind.SKIPPED_STATE_CHANGED, 0); } Optional found = metadataStore.find(fileId.get()); if (found.isEmpty()) { @@ -237,7 +269,12 @@ public final class DefaultCleanupService implements CleanupService { // longer exists. transactions.inWrite( () -> { - quotaGateway.reclaim(QuotaScope.ofNamespace(record.namespace().value()), size); + // Quota is committed only when a file is published. A key recorded ahead of a publish + // that never completed names no committed bytes, and reclaiming for it would push the + // ledger below the truth. + if (record.publishedAt().isPresent()) { + quotaGateway.reclaim(QuotaScope.ofNamespace(record.namespace().value()), size); + } if (record.state() == FileState.DELETING) { metadataStore.transition( record.fileId(), diff --git a/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/cleanup/FileRetirement.java b/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/cleanup/FileRetirement.java new file mode 100644 index 00000000..f72a637a --- /dev/null +++ b/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/cleanup/FileRetirement.java @@ -0,0 +1,64 @@ +package dev.caskeleton.application.fileserver.cleanup; + +import dev.caskeleton.application.fileserver.api.ContentKey; +import dev.caskeleton.application.fileserver.api.FileState; +import dev.caskeleton.application.fileserver.api.UploadId; +import dev.caskeleton.application.fileserver.api.metadata.FileMetadataStore; +import dev.caskeleton.application.fileserver.api.metadata.FileRecord; +import dev.caskeleton.application.fileserver.api.metadata.FileRecordMutation; +import java.util.Optional; + +/** + * Takes a record out of service: DELETING now, DELETED once nothing physical is left. + * + *

    Delete, cancel and the operator's force-delete each used to carry their own copy of this, and + * the copies disagreed. Cancel queued only the staging object, so a cancelled upload that had + * already been published kept its bytes and its quota for good; force-delete never moved a record + * without content past DELETING. One procedure, so every caller retires the same way. + * + *

    Runs inside the caller's write boundary: the record leaving service and the work that reclaims + * it commit together, or neither does. + */ +public final class FileRetirement { + + private final FileMetadataStore metadataStore; + private final CleanupQueue cleanupQueue; + + public FileRetirement(FileMetadataStore metadataStore, CleanupQueue cleanupQueue) { + this.metadataStore = metadataStore; + this.cleanupQueue = cleanupQueue; + } + + /** + * Retires {@code record}, also reclaiming the staging object of {@code upload} when given. + * + *

    A record with nothing to reclaim reaches DELETED at once. Otherwise it stays DELETING, and + * the cleanup item that reclaims its bytes moves it to DELETED. + * + * @return whether physical work was queued + */ + public boolean retire(FileRecord record, Optional upload) { + FileRecord deleting = metadataStore.markDeleting(record.fileId(), record.version()); + Optional contentKey = deleting.contentKey(); + contentKey.ifPresent( + key -> + cleanupQueue.enqueue( + CleanupRequest.forContent( + CleanupType.DELETED_READY_CONTENT, deleting.fileId(), key))); + upload.ifPresent( + uploadId -> + cleanupQueue.enqueue( + CleanupRequest.forStaging( + CleanupType.CANCELLED_STAGING, deleting.fileId(), uploadId))); + if (contentKey.isPresent() || upload.isPresent()) { + return true; + } + metadataStore.transition( + deleting.fileId(), + deleting.version(), + FileState.DELETING, + FileState.DELETED, + FileRecordMutation.none()); + return false; + } +} diff --git a/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/lifecycle/DefaultFileLifecycleService.java b/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/lifecycle/DefaultFileLifecycleService.java index 824738be..89b5c481 100644 --- a/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/lifecycle/DefaultFileLifecycleService.java +++ b/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/lifecycle/DefaultFileLifecycleService.java @@ -1,6 +1,5 @@ package dev.caskeleton.application.fileserver.lifecycle; -import dev.caskeleton.application.fileserver.api.ContentKey; import dev.caskeleton.application.fileserver.api.FileId; import dev.caskeleton.application.fileserver.api.FileState; import dev.caskeleton.application.fileserver.api.StorageNamespace; @@ -20,8 +19,7 @@ import dev.caskeleton.application.fileserver.api.security.OriginalFilenamePolicy import dev.caskeleton.application.fileserver.api.security.RequestContext; import dev.caskeleton.application.fileserver.api.security.SanitizedFilename; import dev.caskeleton.application.fileserver.cleanup.CleanupQueue; -import dev.caskeleton.application.fileserver.cleanup.CleanupRequest; -import dev.caskeleton.application.fileserver.cleanup.CleanupType; +import dev.caskeleton.application.fileserver.cleanup.FileRetirement; import dev.caskeleton.application.fileserver.upload.FileView; import dev.caskeleton.application.fileserver.upload.UploadIdentifierFactory; import dev.caskeleton.application.transaction.TransactionPort; @@ -43,10 +41,10 @@ public final class DefaultFileLifecycleService implements FileLifecycleService { private final CopyContentGateway copyGateway; private final FileAccessPolicy accessPolicy; private final OriginalFilenamePolicy filenamePolicy; - private final CleanupQueue cleanupQueue; private final UploadIdentifierFactory identifierFactory; private final TransactionPort transactions; private final Clock clock; + private final FileRetirement retirement; public DefaultFileLifecycleService( FileMetadataStore metadataStore, @@ -61,10 +59,10 @@ public final class DefaultFileLifecycleService implements FileLifecycleService { this.copyGateway = copyGateway; this.accessPolicy = accessPolicy; this.filenamePolicy = filenamePolicy; - this.cleanupQueue = cleanupQueue; this.identifierFactory = identifierFactory; this.transactions = transactions; this.clock = clock; + this.retirement = new FileRetirement(metadataStore, cleanupQueue); } @Override @@ -83,25 +81,7 @@ public final class DefaultFileLifecycleService implements FileLifecycleService { // One boundary for the whole decision: a record that reached DELETING without either its // terminal transition or a queued reclamation would be unreachable and never collected. return transactions.inWrite( - () -> { - FileRecord deleting = metadataStore.markDeleting(record.fileId(), record.version()); - Optional contentKey = deleting.contentKey(); - if (contentKey.isEmpty()) { - // Nothing was ever published, so there is no physical object to reclaim and the record - // can reach its terminal state immediately. - metadataStore.transition( - deleting.fileId(), - deleting.version(), - FileState.DELETING, - FileState.DELETED, - FileRecordMutation.none()); - return new DeleteOutcome(fileId, false); - } - cleanupQueue.enqueue( - CleanupRequest.forContent( - CleanupType.DELETED_READY_CONTENT, deleting.fileId(), contentKey.get())); - return new DeleteOutcome(fileId, true); - }); + () -> new DeleteOutcome(fileId, retirement.retire(record, Optional.empty()))); } @Override diff --git a/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/quota/DefaultTransferAdmissionController.java b/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/quota/DefaultTransferAdmissionController.java index 320ed582..ca6a178b 100644 --- a/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/quota/DefaultTransferAdmissionController.java +++ b/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/quota/DefaultTransferAdmissionController.java @@ -3,7 +3,6 @@ package dev.caskeleton.application.fileserver.quota; import dev.caskeleton.application.fileserver.api.error.FileTooLargeException; import dev.caskeleton.application.fileserver.api.error.FileserverErrorCode; import dev.caskeleton.application.fileserver.api.error.FileserverFailureContext; -import dev.caskeleton.application.fileserver.api.error.QuotaExceededException; import dev.caskeleton.application.fileserver.api.error.StorageFullException; import dev.caskeleton.application.fileserver.api.error.TransferAdmissionRejectedException; import dev.caskeleton.application.fileserver.api.metadata.QuotaScope; @@ -17,8 +16,9 @@ import java.util.concurrent.atomic.AtomicBoolean; * In-process admission control backed by bounded semaphores. * *

    The failure vocabulary is deliberately distinct so a client can tell a permanent policy denial - * from a transient one: an exhausted pool is {@code STORAGE_FULL}, a scope over its ceiling is - * {@code QUOTA_EXCEEDED}, and momentary permit exhaustion is a retryable admission rejection. + * from a transient one: an exhausted pool is {@code STORAGE_FULL}, and running out of concurrency + * permits — for the caller's scope or for the whole instance — is a retryable admission rejection. + * Stored bytes over a quota ({@code QUOTA_EXCEEDED}) are decided by the quota service, not here. */ public final class DefaultTransferAdmissionController implements TransferAdmissionController { @@ -49,11 +49,17 @@ public final class DefaultTransferAdmissionController implements TransferAdmissi public TransferPermit acquireUpload(QuotaScope scope, long requestedBytes) { requireWithinFileSizePolicy(requestedBytes); requireBelowHardHighWater(); - Semaphore scopePermits = scopePermits(scope); - if (!scopePermits.tryAcquire()) { - throw new QuotaExceededException( - "scope upload concurrency is exhausted", - FileserverFailureContext.of(FileserverErrorCode.QUOTA_EXCEEDED, true)); + Semaphore scopePermits; + // Looked up and acquired under one lock, so an idle semaphore can be forgotten without a caller + // acquiring the forgotten instance in between. + synchronized (scopeUploads) { + scopePermits = scopePermits(scope); + if (!scopePermits.tryAcquire()) { + // Momentary, like the instance limit below: the caller's own earlier uploads will finish. + throw new TransferAdmissionRejectedException( + "scope upload concurrency is exhausted", + FileserverFailureContext.of(FileserverErrorCode.TRANSFER_ADMISSION_REJECTED, true)); + } } if (!instanceUploads.tryAcquire()) { scopePermits.release(); @@ -101,22 +107,29 @@ public final class DefaultTransferAdmissionController implements TransferAdmissi } } + /** Called with the {@code scopeUploads} lock held. */ private Semaphore scopePermits(QuotaScope scope) { String key = scope.canonicalKey(); - synchronized (scopeUploads) { - Semaphore existing = scopeUploads.get(key); - if (existing != null) { - return existing; - } - if (scopeUploads.size() >= MAX_TRACKED_SCOPES) { - // Do not evict a live semaphore: it may still have held permits. New high-cardinality - // scopes share one conservative fallback instead of growing this map without a bound. - return overflowScopeUploads; - } - Semaphore created = new Semaphore(properties.scopeUploadPermits()); - scopeUploads.put(key, created); - return created; + Semaphore existing = scopeUploads.get(key); + if (existing != null) { + return existing; } + if (scopeUploads.size() >= MAX_TRACKED_SCOPES) { + // Scopes are per caller, so the table fills with callers who have long finished. A semaphore + // with every permit available holds nothing, and every acquire happens under this lock, so + // forgetting one cannot strand a permit. + scopeUploads + .values() + .removeIf(idle -> idle.availablePermits() == properties.scopeUploadPermits()); + } + if (scopeUploads.size() >= MAX_TRACKED_SCOPES) { + // Every tracked scope is mid-transfer. New scopes share one conservative fallback instead of + // growing this map without a bound. + return overflowScopeUploads; + } + Semaphore created = new Semaphore(properties.scopeUploadPermits()); + scopeUploads.put(key, created); + return created; } int trackedScopeCount() { diff --git a/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/upload/DefaultFinalizeUploadService.java b/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/upload/DefaultFinalizeUploadService.java index fb9ac4a0..1d866bd1 100644 --- a/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/upload/DefaultFinalizeUploadService.java +++ b/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/upload/DefaultFinalizeUploadService.java @@ -1,5 +1,6 @@ package dev.caskeleton.application.fileserver.upload; +import dev.caskeleton.application.fileserver.api.ContentKey; import dev.caskeleton.application.fileserver.api.FileState; import dev.caskeleton.application.fileserver.api.UploadId; import dev.caskeleton.application.fileserver.api.content.FinalizeContentCommand; @@ -120,7 +121,15 @@ public final class DefaultFinalizeUploadService implements FinalizeUploadService return applyNonAcceptVerdict(verifying, session, verdict); } - StoredContent published = publish(handle, session, serverDigest); + StoredContent published; + try { + published = publish(handle, session, serverDigest, verifying.contentKey()); + } catch (AmbiguousCompletionException ambiguous) { + // The object may be under the recorded key or may not; only the reconciler can tell, and it + // only looks at what the recovery queue names. + enqueueRecovery(verifying, "PUBLISH_UNCONFIRMED", ambiguous); + throw ambiguous; + } return commitReady(verifying, session, published, verdict, context); } @@ -194,13 +203,16 @@ public final class DefaultFinalizeUploadService implements FinalizeUploadService FileRecordMutation.uploaded(committedOffset, serverDigest)); } if (current.state() == FileState.UPLOADED) { + // Write-ahead: the key the publish will use is on the record before the publish runs, + // so a publish whose outcome is lost is still found by the reconciler under that key. current = metadataStore.transition( current.fileId(), current.version(), FileState.UPLOADED, FileState.VERIFYING, - FileRecordMutation.none()); + FileRecordMutation.intendedContentKey( + current.contentKey().orElseGet(contentGateway::newContentKey))); } if (current.state() != FileState.VERIFYING) { throw new IllegalStateException( @@ -215,7 +227,9 @@ public final class DefaultFinalizeUploadService implements FinalizeUploadService return new VerificationRequest( record.fileId(), Optional.of(session.uploadId()), - record.contentKey(), + // Nothing is published yet: the key on the record is where the publish will go, not where + // content is, so verification reads the staged bytes. + Optional.empty(), session.committedOffset(), serverDigest, record.claimedMediaType(), @@ -274,16 +288,30 @@ public final class DefaultFinalizeUploadService implements FinalizeUploadService return FileView.of(updated.toDescriptor()); } - private StoredContent publish(UploadHandle handle, UploadSession session, String serverDigest) { + private StoredContent publish( + UploadHandle handle, + UploadSession session, + String serverDigest, + Optional recordedKey) { FinalizeContentCommand command = new FinalizeContentCommand( OptionalLong.of(session.committedOffset()), Optional.of(serverDigest), publishMode, - true); + true, + recordedKey); return contentGateway.finalizeUpload(handle, command); } + /** In its own boundary, because whatever failed took the caller's transaction with it. */ + private void enqueueRecovery(FileRecord record, String reasonCode, RuntimeException failure) { + try { + transactions.inNew(() -> recoveryQueue.enqueue(record.fileId(), reasonCode)); + } catch (RuntimeException recoveryWriteFailure) { + failure.addSuppressed(recoveryWriteFailure); + } + } + /** * Commits READY and everything that must follow it. * @@ -328,13 +356,8 @@ public final class DefaultFinalizeUploadService implements FinalizeUploadService }); } catch (RuntimeException exception) { // The object is on the volume and the record does not say so — the definition of an ambiguous - // completion. Enqueued in its own boundary, because the one that failed took nothing with it. - try { - transactions.inNew( - () -> recoveryQueue.enqueue(verifying.fileId(), "READY_COMMIT_UNCONFIRMED")); - } catch (RuntimeException recoveryWriteFailure) { - exception.addSuppressed(recoveryWriteFailure); - } + // completion. + enqueueRecovery(verifying, "READY_COMMIT_UNCONFIRMED", exception); throw new AmbiguousCompletionException( "content was published but the READY commit could not be confirmed", exception, diff --git a/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/upload/DefaultUploadApplicationService.java b/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/upload/DefaultUploadApplicationService.java index d7a561e8..9e17ac7b 100644 --- a/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/upload/DefaultUploadApplicationService.java +++ b/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/upload/DefaultUploadApplicationService.java @@ -28,8 +28,7 @@ import dev.caskeleton.application.fileserver.api.security.OriginalFilenamePolicy import dev.caskeleton.application.fileserver.api.security.RequestContext; import dev.caskeleton.application.fileserver.api.security.SanitizedFilename; import dev.caskeleton.application.fileserver.cleanup.CleanupQueue; -import dev.caskeleton.application.fileserver.cleanup.CleanupRequest; -import dev.caskeleton.application.fileserver.cleanup.CleanupType; +import dev.caskeleton.application.fileserver.cleanup.FileRetirement; import dev.caskeleton.application.fileserver.concurrency.LeaseFence; import dev.caskeleton.application.fileserver.concurrency.WriterLeaseCoordinator; import dev.caskeleton.application.fileserver.observability.FileserverMetricsPort; @@ -68,7 +67,7 @@ public final class DefaultUploadApplicationService implements UploadApplicationS private final TransferAdmissionController admissionController; private final FileAccessPolicy accessPolicy; private final OriginalFilenamePolicy filenamePolicy; - private final CleanupQueue cleanupQueue; + private final FileRetirement retirement; private final UploadIdentifierFactory identifierFactory; private final UploadPolicy uploadPolicy; private final FileserverMetricsPort metrics; @@ -99,7 +98,7 @@ public final class DefaultUploadApplicationService implements UploadApplicationS this.admissionController = admissionController; this.accessPolicy = accessPolicy; this.filenamePolicy = filenamePolicy; - this.cleanupQueue = cleanupQueue; + this.retirement = new FileRetirement(metadataStore, cleanupQueue); this.identifierFactory = identifierFactory; this.uploadPolicy = uploadPolicy; this.metrics = metrics; @@ -115,7 +114,8 @@ public final class DefaultUploadApplicationService implements UploadApplicationS QuotaScope scope = QuotaScope.ofNamespace(request.namespace().value()); long reservationBytes = request.expectedLength().orElse(uploadPolicy.initialReservationBytes()); - try (TransferPermit permit = admissionController.acquireUpload(scope, reservationBytes)) { + try (TransferPermit permit = + admissionController.acquireUpload(admissionScope(context), reservationBytes)) { FileId fileId = identifierFactory.newFileId(); UploadId uploadId = identifierFactory.newUploadId(); @@ -194,9 +194,8 @@ public final class DefaultUploadApplicationService implements UploadApplicationS accessPolicy.authorize( FileOperation.APPEND, context.subject(), Optional.of(record.toDescriptor())); - QuotaScope scope = QuotaScope.ofNamespace(record.namespace().value()); try (TransferPermit permit = - admissionController.acquireUpload(scope, Math.max(contentLength, 0))) { + admissionController.acquireUpload(admissionScope(context), Math.max(contentLength, 0))) { // Three separate boundaries, not one: the byte transfer between them must not run inside a // transaction, so the lease, the offset commit, and the release each stand alone. WriterLease lease = leaseCoordinator.acquire(uploadId, context.instanceId()); @@ -242,7 +241,8 @@ public final class DefaultUploadApplicationService implements UploadApplicationS @Override public UploadSessionView status(UploadId uploadId, RequestContext context) { - UploadSession session = requireSession(uploadId); + // An ended upload answers gone, not with an offset a client would try to resume from. + UploadSession session = requireActiveSession(uploadId); FileRecord record = requireRecord(session.fileId()); accessPolicy.authorize( FileOperation.READ_METADATA, context.subject(), Optional.of(record.toDescriptor())); @@ -259,19 +259,27 @@ public final class DefaultUploadApplicationService implements UploadApplicationS transactions.inWrite( () -> { // Logical first: the record must stop being reachable before any physical work is - // scheduled. Both writes commit together, so no cancel can leave a file unreachable with - // nothing queued to reclaim it. - metadataStore.markDeleting(record.fileId(), record.version()); + // scheduled. The staged bytes and, for an upload that was already published, the + // published object are queued in the same commit, so no cancel can leave a file + // unreachable with nothing queued to reclaim it. + retirement.retire(record, Optional.of(session.uploadId())); // Terminal in the same transaction that queues the cleanup. Queuing alone left the // session ACTIVE, so a writer could still take a lease on the very bytes the cleanup was // about to delete and the two raced for the same object. sessionStore.terminate(session.uploadId()); - cleanupQueue.enqueue( - CleanupRequest.forStaging( - CleanupType.CANCELLED_STAGING, record.fileId(), session.uploadId())); }); } + /** + * Transfer concurrency is counted per caller. + * + *

    Counting it per namespace put every caller of a deployment — which uploads into one default + * namespace — behind the same handful of permits, so one busy client refused everyone else. + */ + private static QuotaScope admissionScope(RequestContext context) { + return QuotaScope.ofPrincipal(context.subject().principalId()); + } + /** * Cross-checks the resumable offset against the bytes actually on disk. * @@ -321,6 +329,14 @@ public final class DefaultUploadApplicationService implements UploadApplicationS private UploadSession requireActiveSession(UploadId uploadId) { UploadSession session = requireSession(uploadId); + if (session.terminal()) { + // Cancelled, rejected or swept. Refusing it as a lease conflict told the client to retry an + // upload that can never accept another byte. + throw new UploadExpiredException( + "upload resource is no longer open", + FileserverFailureContext.forUpload( + FileserverErrorCode.UPLOAD_EXPIRED, uploadId, false, false, false)); + } if (session.isExpiredAt(clock.instant())) { throw new UploadExpiredException( "upload resource has expired", diff --git a/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/upload/UploadContentGateway.java b/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/upload/UploadContentGateway.java index d146e5dd..2744c98e 100644 --- a/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/upload/UploadContentGateway.java +++ b/src/application-fileserver/src/main/java/dev/caskeleton/application/fileserver/upload/UploadContentGateway.java @@ -1,5 +1,6 @@ package dev.caskeleton.application.fileserver.upload; +import dev.caskeleton.application.fileserver.api.ContentKey; import dev.caskeleton.application.fileserver.api.content.FinalizeContentCommand; import dev.caskeleton.application.fileserver.api.content.StoredContent; import dev.caskeleton.application.fileserver.api.content.UploadHandle; @@ -24,6 +25,14 @@ public interface UploadContentGateway { */ String stagedDigest(UploadHandle handle, long committedOffset); + /** + * A fresh key for content that has not been published yet. + * + *

    Finalization records it on the file before publishing under it, so a publish whose outcome + * is lost can still be found by the reconciler. + */ + ContentKey newContentKey(); + StoredContent finalizeUpload(UploadHandle handle, FinalizeContentCommand command); /** Releases the writer lease this node holds for the session. */ diff --git a/src/application-fileserver/src/test/java/dev/caskeleton/application/fileserver/admin/FileserverAdminServiceTest.java b/src/application-fileserver/src/test/java/dev/caskeleton/application/fileserver/admin/FileserverAdminServiceTest.java index 5e4feb01..b56ea7c7 100644 --- a/src/application-fileserver/src/test/java/dev/caskeleton/application/fileserver/admin/FileserverAdminServiceTest.java +++ b/src/application-fileserver/src/test/java/dev/caskeleton/application/fileserver/admin/FileserverAdminServiceTest.java @@ -202,6 +202,22 @@ class FileserverAdminServiceTest { }); } + /** Nothing was published, so nothing is queued that could ever move it past DELETING. */ + @Test + void forceDeletingAFileThatWasNeverPublishedRetiresItCompletely() { + // given + FileRecord uploading = ReadyFileFixture.uploading(metadata, SIZE, DIGEST); + + // when + admin.forceDelete( + new ForceDeleteCommand(uploading.fileId(), "LEGAL_TAKEDOWN_2026_08"), + FileserverFixtures.context()); + + // then + assertThat(metadata.find(uploading.fileId()).orElseThrow().state()) + .isEqualTo(FileState.DELETED); + } + @Test void aForceDeleteWithoutTheSecondAuthorityNeverTouchesTheRecord() { FileRecord ready = ReadyFileFixture.ready(metadata, SIZE, DIGEST); diff --git a/src/application-fileserver/src/test/java/dev/caskeleton/application/fileserver/cleanup/CleanupServiceTest.java b/src/application-fileserver/src/test/java/dev/caskeleton/application/fileserver/cleanup/CleanupServiceTest.java index ac1246e9..cbd40e89 100644 --- a/src/application-fileserver/src/test/java/dev/caskeleton/application/fileserver/cleanup/CleanupServiceTest.java +++ b/src/application-fileserver/src/test/java/dev/caskeleton/application/fileserver/cleanup/CleanupServiceTest.java @@ -356,6 +356,61 @@ class CleanupServiceTest { assertThat(content.stagingExists(uploadId)).isFalse(); } + /** A crash between the create commit and the first append leaves the record in CREATED. */ + @Test + void anUploadThatExpiredBeforeItsFirstAppendIsExpiredToo() { + // given + FileRecord created = + metadata.insert(FileserverFixtures.draft(FileId.of(UUID.randomUUID()), SIZE)); + expiredSession(created.fileId()); + + // when + cleanup.runBatch(100, 1L << 30); + + // then + assertThat(metadata.find(created.fileId()).orElseThrow().state()).isEqualTo(FileState.EXPIRED); + } + + @Test + void aCancelledUploadReachesDeletedOnceItsStagingIsReclaimed() { + // given + FileRecord uploading = ReadyFileFixture.uploading(metadata, SIZE, DIGEST); + metadata.markDeleting(uploading.fileId(), uploading.version()); + UploadId uploadId = UploadId.of(UUID.randomUUID()); + sessions.create( + new UploadSessionDraft( + uploadId, + uploading.fileId(), + UploadMode.RESUMABLE, + OptionalLong.of(SIZE), + FileserverFixtures.NOW.plusSeconds(3600))); + sessions.terminate(uploadId); + content.storeStaging(uploadId); + queue.enqueue( + CleanupRequest.forStaging(CleanupType.CANCELLED_STAGING, uploading.fileId(), uploadId)); + + // when + cleanup.runBatch(100, 1L << 30); + + // then + assertThat(metadata.find(uploading.fileId()).orElseThrow().state()) + .isEqualTo(FileState.DELETED); + } + + @Test + void aRetiredOrphanIsPurgedFromQuarantine() { + // given + ContentKey orphan = ContentKey.of("aa/bb/orphan-object-0001"); + content.quarantine(orphan); + queue.enqueue(CleanupRequest.forOrphan(orphan)); + + // when + cleanup.runBatch(100, 1L << 30); + + // then + assertThat(content.quarantineHolds(orphan)).isFalse(); + } + private UploadId expiredSession(FileId fileId) { UploadId uploadId = UploadId.of(UUID.randomUUID()); sessions.create( diff --git a/src/application-fileserver/src/test/java/dev/caskeleton/application/fileserver/quota/TransferAdmissionControllerTest.java b/src/application-fileserver/src/test/java/dev/caskeleton/application/fileserver/quota/TransferAdmissionControllerTest.java index db23c33c..d9cd6627 100644 --- a/src/application-fileserver/src/test/java/dev/caskeleton/application/fileserver/quota/TransferAdmissionControllerTest.java +++ b/src/application-fileserver/src/test/java/dev/caskeleton/application/fileserver/quota/TransferAdmissionControllerTest.java @@ -2,9 +2,10 @@ package dev.caskeleton.application.fileserver.quota; import static org.assertj.core.api.Assertions.assertThat; import static org.assertj.core.api.Assertions.assertThatThrownBy; +import static org.assertj.core.api.Assertions.catchThrowable; import dev.caskeleton.application.fileserver.api.error.FileTooLargeException; -import dev.caskeleton.application.fileserver.api.error.QuotaExceededException; +import dev.caskeleton.application.fileserver.api.error.FileserverErrorCode; import dev.caskeleton.application.fileserver.api.error.StorageFullException; import dev.caskeleton.application.fileserver.api.error.TransferAdmissionRejectedException; import dev.caskeleton.application.fileserver.api.metadata.QuotaScope; @@ -22,19 +23,50 @@ class TransferAdmissionControllerTest { new DefaultTransferAdmissionController( TransferAdmissionProperties.standard(), StorageUsageProbe.unknown(), MAX_FILE); + /** Momentary concurrency is a retryable 429, not a permanent quota refusal. */ @Test - void rejectsWhenScopeConcurrencyIsExhausted() { + void anExhaustedScopeIsARetryableAdmissionRejection() { + // given TransferPermit first = controller.acquireUpload(scope("tenant-a"), 10); TransferPermit second = controller.acquireUpload(scope("tenant-a"), 10); TransferPermit third = controller.acquireUpload(scope("tenant-a"), 10); TransferPermit fourth = controller.acquireUpload(scope("tenant-a"), 10); - assertThatThrownBy(() -> controller.acquireUpload(scope("tenant-a"), 10)) - .isInstanceOf(QuotaExceededException.class); + // when + Throwable failure = catchThrowable(() -> controller.acquireUpload(scope("tenant-a"), 10)); + // then + assertThat(failure) + .isInstanceOf(TransferAdmissionRejectedException.class) + .extracting(rejected -> ((TransferAdmissionRejectedException) rejected).context().code()) + .isEqualTo(FileserverErrorCode.TRANSFER_ADMISSION_REJECTED); Stream.of(first, second, third, fourth).forEach(TransferPermit::close); } + /** + * Per-caller scopes are unbounded in number; an idle one must make room for the next caller + * instead of sending every later caller to the shared overflow pool. + */ + @Test + void newCallersStillGetTheirOwnScopeOnceTheTableHasFilledWithIdleOnes() { + // given + for (int index = 0; index < DefaultTransferAdmissionController.MAX_TRACKED_SCOPES; index++) { + controller.acquireUpload(scope("caller-" + index), 10).close(); + } + List held = new ArrayList<>(); + for (int index = 0; index < 4; index++) { + held.add(controller.acquireUpload(scope("late-" + index), 10)); + } + + // when + Throwable failure = + catchThrowable(() -> held.add(controller.acquireUpload(scope("late-4"), 10))); + + // then + assertThat(failure).isNull(); + held.forEach(TransferPermit::close); + } + @Test void aReleasedPermitReturnsCapacityToItsScope() { TransferPermit permit = controller.acquireUpload(scope("tenant-b"), 10); @@ -59,7 +91,7 @@ class TransferAdmissionControllerTest { permits.add(controller.acquireUpload(scope("tenant-c"), 10)); } assertThatThrownBy(() -> controller.acquireUpload(scope("tenant-c"), 10)) - .isInstanceOf(QuotaExceededException.class); + .isInstanceOf(TransferAdmissionRejectedException.class); permits.forEach(TransferPermit::close); } @@ -145,37 +177,18 @@ class TransferAdmissionControllerTest { } @Test - void scopeSemaphoreRegistryIsBoundedAndOverflowScopesShareConservativeCapacity() { - for (int index = 0; - index < DefaultTransferAdmissionController.MAX_TRACKED_SCOPES + 32; - index++) { - try (TransferPermit ignored = controller.acquireUpload(scope("tenant-" + index), 10)) { - assertThat(ignored.isHeld()).isTrue(); - } + void theScopeRegistryStaysBoundedAsCallersComeAndGo() { + // given + int callers = DefaultTransferAdmissionController.MAX_TRACKED_SCOPES + 32; + + // when + for (int index = 0; index < callers; index++) { + controller.acquireUpload(scope("tenant-" + index), 10).close(); } + // then assertThat(controller.trackedScopeCount()) - .isEqualTo(DefaultTransferAdmissionController.MAX_TRACKED_SCOPES); - - List overflow = new ArrayList<>(); - for (int index = 0; - index < TransferAdmissionProperties.standard().scopeUploadPermits(); - index++) { - overflow.add( - controller.acquireUpload( - scope("overflow-" + (DefaultTransferAdmissionController.MAX_TRACKED_SCOPES + index)), - 10)); - } - - assertThatThrownBy( - () -> - controller.acquireUpload( - scope( - "overflow-blocked-" - + DefaultTransferAdmissionController.MAX_TRACKED_SCOPES), - 10)) - .isInstanceOf(QuotaExceededException.class); - overflow.forEach(TransferPermit::close); + .isLessThanOrEqualTo(DefaultTransferAdmissionController.MAX_TRACKED_SCOPES); } @Test diff --git a/src/application-fileserver/src/test/java/dev/caskeleton/application/fileserver/testkit/FakeCleanupContentGateway.java b/src/application-fileserver/src/test/java/dev/caskeleton/application/fileserver/testkit/FakeCleanupContentGateway.java index acf1786f..39967a37 100644 --- a/src/application-fileserver/src/test/java/dev/caskeleton/application/fileserver/testkit/FakeCleanupContentGateway.java +++ b/src/application-fileserver/src/test/java/dev/caskeleton/application/fileserver/testkit/FakeCleanupContentGateway.java @@ -14,6 +14,7 @@ public final class FakeCleanupContentGateway implements CleanupContentGateway { private final Set objects = new LinkedHashSet<>(); private final Set stagingObjects = new LinkedHashSet<>(); + private final Set quarantined = new LinkedHashSet<>(); private final List preconditions = new java.util.ArrayList<>(); public void store(ContentKey key) { @@ -49,4 +50,17 @@ public final class FakeCleanupContentGateway implements CleanupContentGateway { public void discardStaging(UploadId uploadId) { stagingObjects.remove(uploadId); } + + public void quarantine(ContentKey key) { + quarantined.add(key); + } + + public boolean quarantineHolds(ContentKey key) { + return quarantined.contains(key); + } + + @Override + public boolean purgeQuarantined(ContentKey key) { + return quarantined.remove(key); + } } diff --git a/src/application-fileserver/src/test/java/dev/caskeleton/application/fileserver/testkit/FakeUploadContentGateway.java b/src/application-fileserver/src/test/java/dev/caskeleton/application/fileserver/testkit/FakeUploadContentGateway.java index 50b35237..5ba1be73 100644 --- a/src/application-fileserver/src/test/java/dev/caskeleton/application/fileserver/testkit/FakeUploadContentGateway.java +++ b/src/application-fileserver/src/test/java/dev/caskeleton/application/fileserver/testkit/FakeUploadContentGateway.java @@ -45,12 +45,17 @@ public final class FakeUploadContentGateway implements UploadContentGateway { return stagedDigest; } + @Override + public ContentKey newContentKey() { + return nextKey(); + } + @Override public StoredContent finalizeUpload(UploadHandle handle, FinalizeContentCommand command) { if (finalizeFailure != null) { throw finalizeFailure; } - ContentKey key = nextKey(); + ContentKey key = command.contentKey().orElseGet(this::nextKey); long size = command.expectedLength().orElse(0); published.put(key, size); return new StoredContent(key, size, command.expectedSha256().orElse(stagedDigest), true); diff --git a/src/application-fileserver/src/test/java/dev/caskeleton/application/fileserver/upload/FinalizeUploadServiceTest.java b/src/application-fileserver/src/test/java/dev/caskeleton/application/fileserver/upload/FinalizeUploadServiceTest.java index 5bed068d..63e83b48 100644 --- a/src/application-fileserver/src/test/java/dev/caskeleton/application/fileserver/upload/FinalizeUploadServiceTest.java +++ b/src/application-fileserver/src/test/java/dev/caskeleton/application/fileserver/upload/FinalizeUploadServiceTest.java @@ -9,6 +9,8 @@ import dev.caskeleton.application.fileserver.api.FileState; import dev.caskeleton.application.fileserver.api.content.PublishMode; import dev.caskeleton.application.fileserver.api.error.AmbiguousCompletionException; import dev.caskeleton.application.fileserver.api.error.FileAccessDeniedException; +import dev.caskeleton.application.fileserver.api.error.FileserverErrorCode; +import dev.caskeleton.application.fileserver.api.error.FileserverFailureContext; import dev.caskeleton.application.fileserver.api.error.IntegrityMismatchException; import dev.caskeleton.application.fileserver.api.error.MalwareDetectedException; import dev.caskeleton.application.fileserver.api.error.PartialWriteException; @@ -198,6 +200,52 @@ class FinalizeUploadServiceTest { .hasMessage("operation denied by policy"); } + /** A publish whose outcome is lost must still be findable, so its key is recorded first. */ + @Test + void theContentKeyIsRecordedBeforeThePublishIsAttempted() { + // given + content.failFinalizeWith(new IllegalStateException("volume went away")); + UploadSession session = uploadedSession(10); + + // when + Throwable failure = + catchThrowable( + () -> + service.finalizeUpload( + session, + FinalizeUploadRequest.synchronousWithoutDigest(), + FileserverFixtures.context())); + + // then + assertThat(metadata.find(session.fileId()).orElseThrow().contentKey()) + .as("finalize failed with %s", failure) + .isPresent(); + } + + @Test + void anAmbiguousPublishIsQueuedForRecovery() { + // given + content.failFinalizeWith( + new AmbiguousCompletionException( + "publish move result is unknown", + FileserverFailureContext.of(FileserverErrorCode.AMBIGUOUS_COMPLETION, false))); + UploadSession session = uploadedSession(10); + + // when + Throwable failure = + catchThrowable( + () -> + service.finalizeUpload( + session, + FinalizeUploadRequest.synchronousWithoutDigest(), + FileserverFixtures.context())); + + // then + assertThat(recovery.reasons()) + .as("finalize failed with %s", failure) + .containsEntry(session.fileId(), "PUBLISH_UNCONFIRMED"); + } + @Test void aRetryVerdictLeavesTheFileVerifyingWithoutPublishing() { verdict = VerificationResult.retry("SCANNER_TIMEOUT"); diff --git a/src/application-fileserver/src/test/java/dev/caskeleton/application/fileserver/upload/UploadApplicationServiceTest.java b/src/application-fileserver/src/test/java/dev/caskeleton/application/fileserver/upload/UploadApplicationServiceTest.java index 81e92cdf..f3b6b579 100644 --- a/src/application-fileserver/src/test/java/dev/caskeleton/application/fileserver/upload/UploadApplicationServiceTest.java +++ b/src/application-fileserver/src/test/java/dev/caskeleton/application/fileserver/upload/UploadApplicationServiceTest.java @@ -4,6 +4,8 @@ import static org.assertj.core.api.Assertions.assertThat; import static org.assertj.core.api.Assertions.assertThatThrownBy; import static org.assertj.core.api.Assertions.catchThrowable; +import dev.caskeleton.application.fileserver.api.ContentKey; +import dev.caskeleton.application.fileserver.api.FileId; import dev.caskeleton.application.fileserver.api.FileState; import dev.caskeleton.application.fileserver.api.UploadId; import dev.caskeleton.application.fileserver.api.error.ConcurrentFileModificationException; @@ -15,16 +17,22 @@ import dev.caskeleton.application.fileserver.api.error.StorageUnavailableExcepti import dev.caskeleton.application.fileserver.api.error.UploadExpiredException; import dev.caskeleton.application.fileserver.api.error.UploadOffsetMismatchException; import dev.caskeleton.application.fileserver.api.metadata.FileOwner; +import dev.caskeleton.application.fileserver.api.metadata.FileRecord; +import dev.caskeleton.application.fileserver.api.metadata.FileRecordMutation; +import dev.caskeleton.application.fileserver.api.metadata.QuotaScope; import dev.caskeleton.application.fileserver.api.security.FileAccessSubject; import dev.caskeleton.application.fileserver.api.security.FileOperation; import dev.caskeleton.application.fileserver.api.security.OriginalFilenamePolicy; import dev.caskeleton.application.fileserver.api.security.RequestContext; import dev.caskeleton.application.fileserver.api.transfer.UploadMode; +import dev.caskeleton.application.fileserver.cleanup.CleanupType; import dev.caskeleton.application.fileserver.concurrency.DefaultWriterLeaseCoordinator; import dev.caskeleton.application.fileserver.observability.FileserverMetricsPort; import dev.caskeleton.application.fileserver.quota.DefaultTransferAdmissionController; import dev.caskeleton.application.fileserver.quota.StorageUsageProbe; +import dev.caskeleton.application.fileserver.quota.TransferAdmissionController; import dev.caskeleton.application.fileserver.quota.TransferAdmissionProperties; +import dev.caskeleton.application.fileserver.quota.TransferPermit; import dev.caskeleton.application.fileserver.testkit.DirectTransactions; import dev.caskeleton.application.fileserver.testkit.FakeFileAccessPolicy; import dev.caskeleton.application.fileserver.testkit.FakeFileQuotaService; @@ -95,6 +103,78 @@ class UploadApplicationServiceTest { .contains(new FileOwner("user-9", Optional.of("tenant-a"))); } + /** Concurrency is counted per caller, so one caller's uploads cannot starve the namespace. */ + @Test + void admissionIsCountedPerCallerRatherThanPerNamespace() { + // given + DefaultTransferAdmissionController admission = + new DefaultTransferAdmissionController( + new TransferAdmissionProperties(16, 1, 64, 0.70, 0.85), + StorageUsageProbe.unknown(), + MAX_FILE); + UploadApplicationService narrow = service(FileserverFixtures.NOW, admission); + try (TransferPermit namespaceFull = + admission.acquireUpload(QuotaScope.ofNamespace(FileserverFixtures.NAMESPACE.value()), 1)) { + + // when + Throwable failure = + catchThrowable(() -> narrow.create(createRequest(), FileserverFixtures.context())); + + // then + assertThat(failure).as("namespace permit held: %s", namespaceFull.isHeld()).isNull(); + } + } + + @Test + void cancellingAPublishedUploadQueuesItsContentForReclamation() { + // given + UploadSessionView created = service.create(createRequest(), FileserverFixtures.context()); + publish(created.fileId()); + + // when + service.cancel(created.uploadId(), FileserverFixtures.context()); + + // then + assertThat(cleanup.queued()) + .extracting(item -> item.request().type()) + .contains(CleanupType.DELETED_READY_CONTENT); + } + + @Test + void anAppendToACancelledUploadIsRefusedAsGone() { + // given + UploadSessionView created = service.create(createRequest(), FileserverFixtures.context()); + service.cancel(created.uploadId(), FileserverFixtures.context()); + + // when + Throwable failure = + catchThrowable( + () -> + service.append( + created.uploadId(), 0, channel("abc"), 3, FileserverFixtures.context())); + + // then + assertThat(failure) + .isInstanceOf(UploadExpiredException.class) + .hasMessage("upload resource is no longer open"); + } + + @Test + void theStatusOfACancelledUploadIsGone() { + // given + UploadSessionView created = service.create(createRequest(), FileserverFixtures.context()); + service.cancel(created.uploadId(), FileserverFixtures.context()); + + // when + Throwable failure = + catchThrowable(() -> service.status(created.uploadId(), FileserverFixtures.context())); + + // then + assertThat(failure) + .isInstanceOf(UploadExpiredException.class) + .hasMessage("upload resource is no longer open"); + } + @Test void createAppendAndCancelMaintainStateAndOffset() { UploadSessionView created = service.create(createRequest(), FileserverFixtures.context()); @@ -345,6 +425,14 @@ class UploadApplicationServiceTest { } private UploadApplicationService serviceAt(java.time.Instant instant) { + return service( + instant, + new DefaultTransferAdmissionController( + TransferAdmissionProperties.standard(), StorageUsageProbe.unknown(), MAX_FILE)); + } + + private UploadApplicationService service( + java.time.Instant instant, TransferAdmissionController admission) { Clock clock = Clock.fixed(instant, ZoneOffset.UTC); return new DefaultUploadApplicationService( metadata, @@ -353,8 +441,7 @@ class UploadApplicationServiceTest { sessions, UploadPolicy.standard().leaseDuration(), new DirectTransactions(), clock), storage, quota, - new DefaultTransferAdmissionController( - TransferAdmissionProperties.standard(), StorageUsageProbe.unknown(), MAX_FILE), + admission, accessPolicy, OriginalFilenamePolicy.standard(), cleanup, @@ -371,6 +458,35 @@ class UploadApplicationServiceTest { java.util.Set.of(FileState.FAILED), FileserverFixtures.NOW.plusSeconds(1), 10); } + /** Walks a freshly created upload to READY through the legal edges. */ + private void publish(FileId fileId) { + FileRecord uploading = metadata.find(fileId).orElseThrow(); + FileRecord uploaded = + metadata.transition( + fileId, + uploading.version(), + FileState.UPLOADING, + FileState.UPLOADED, + FileRecordMutation.uploaded(3, FileserverFixtures.DIGEST)); + FileRecord verifying = + metadata.transition( + fileId, + uploaded.version(), + FileState.UPLOADED, + FileState.VERIFYING, + FileRecordMutation.none()); + metadata.transition( + fileId, + verifying.version(), + FileState.VERIFYING, + FileState.READY, + FileRecordMutation.publishAt( + ContentKey.of("ab/cd/published-object-0001"), + 3, + FileserverFixtures.DIGEST, + FileserverFixtures.NOW)); + } + private static CreateUploadRequest createRequest() { return createRequest(3); } diff --git a/src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/admin/AdminOperationExecutor.java b/src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/admin/AdminOperationExecutor.java index 668ef4d3..cf1349a2 100644 --- a/src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/admin/AdminOperationExecutor.java +++ b/src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/admin/AdminOperationExecutor.java @@ -1,7 +1,9 @@ package dev.caskeleton.application.notification.platform.admin; import dev.caskeleton.application.transaction.TransactionPort; +import java.util.List; import java.util.Objects; +import java.util.Optional; import java.util.function.Supplier; /** Serializes one destructive admin operation by its caller-supplied operation id. */ @@ -33,12 +35,63 @@ final class AdminOperationExecutor { () -> { AdminOperationClaim claim = operations.claim(operationId, commandFingerprint, actor, action); - return switch (claim.outcome()) { - case CLAIMED -> operation.get(); - case REPLAY -> claim.existing().orElseThrow(); - case IN_PROGRESS -> throw new AdminOperationInProgressException(operationId); - case CONFLICT -> throw new AdminOperationConflictException(operationId); - }; + return claim.mayProceed() ? operation.get() : withoutRunning(claim, operationId); }); } + + /** + * Claims the operation id in its own transaction and runs the operation with none open. + * + *

    For an operation that calls a provider over the network. Inside {@link #execute} the call + * held a write transaction — and a pooled connection — for as long as the provider took, once per + * attempt in the batch. The operation opens its own boundaries for what it writes, including + * saving its result, which completes the claim. + * + *

    The claim is committed before the operation starts, so a failure can no longer roll it back. + * The claim is completed with a {@code FAILED} result instead: left {@code CLAIMED}, every retry + * of the id would answer "in progress" forever. + */ + AdminOperationResult executeOutsideTransaction( + String operationId, + String commandFingerprint, + AdminActor actor, + String action, + Supplier operation) { + Objects.requireNonNull(operation, "operation"); + AdminOperationClaim claim = + transactions.inWrite( + () -> operations.claim(operationId, commandFingerprint, actor, action)); + if (!claim.mayProceed()) { + return withoutRunning(claim, operationId); + } + try { + return operation.get(); + } catch (RuntimeException failure) { + transactions.inWrite( + () -> + operations.save( + new AdminOperationResult( + operationId, + false, + 0, + Optional.empty(), + Optional.empty(), + Optional.empty(), + List.of("FAILED")), + actor, + action)); + throw failure; + } + } + + /** The answer to a claim this caller does not hold: the earlier result, or a refusal. */ + private static AdminOperationResult withoutRunning( + AdminOperationClaim claim, String operationId) { + return switch (claim.outcome()) { + case REPLAY -> claim.existing().orElseThrow(); + case IN_PROGRESS -> throw new AdminOperationInProgressException(operationId); + case CONFLICT -> throw new AdminOperationConflictException(operationId); + case CLAIMED -> throw new IllegalStateException("a held claim is run, not answered"); + }; + } } diff --git a/src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/admin/NotificationAdminApplicationService.java b/src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/admin/NotificationAdminApplicationService.java index ee121b6b..4f06e9b1 100644 --- a/src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/admin/NotificationAdminApplicationService.java +++ b/src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/admin/NotificationAdminApplicationService.java @@ -55,6 +55,7 @@ public final class NotificationAdminApplicationService implements NotificationAd private final AdminOperationStorePort operations; private final AdminOperationExecutor operationExecutor; private final AdminOperationCommandFingerprint commandFingerprints; + private final TransactionPort transactions; private final NotificationAuditPort audit; private final dev.caskeleton.application.notification.platform.dispatch .NotificationIdGeneratorPort @@ -83,9 +84,8 @@ public final class NotificationAdminApplicationService implements NotificationAd this.suppressions = Objects.requireNonNull(suppressions, "suppressions"); this.runtimes = Objects.requireNonNull(runtimes, "runtimes"); this.operations = Objects.requireNonNull(operations, "operations"); - this.operationExecutor = - new AdminOperationExecutor( - this.operations, Objects.requireNonNull(transactions, "transactions")); + this.transactions = Objects.requireNonNull(transactions, "transactions"); + this.operationExecutor = new AdminOperationExecutor(this.operations, this.transactions); this.commandFingerprints = new AdminOperationCommandFingerprint(Objects.requireNonNull(digests, "digests")); this.audit = Objects.requireNonNull(audit, "audit"); @@ -178,7 +178,9 @@ public final class NotificationAdminApplicationService implements NotificationAd List.of("DRY_RUN")); } - return operationExecutor.execute( + // Outside a transaction: each reconcile asks a provider over the network and opens its own + // boundaries for what it writes. + return operationExecutor.executeOutsideTransaction( command.operationId(), commandFingerprints.of(command), actor, @@ -201,15 +203,18 @@ public final class NotificationAdminApplicationService implements NotificationAd Optional.empty(), Optional.empty(), List.copyOf(reasons)); - audit.record( - new NotificationAuditEvent( - "ADMIN_RECONCILE", - actor.actorRef(), - Optional.of(command.reason()), - Optional.of(command.operationId()), - clock.instant(), - Map.of())); - return operations.save(result, actor, "ADMIN_RECONCILE"); + return transactions.inWrite( + () -> { + audit.record( + new NotificationAuditEvent( + "ADMIN_RECONCILE", + actor.actorRef(), + Optional.of(command.reason()), + Optional.of(command.operationId()), + clock.instant(), + Map.of())); + return operations.save(result, actor, "ADMIN_RECONCILE"); + }); }); } diff --git a/src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/DispatchGuardOutcome.java b/src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/DispatchGuardOutcome.java index 0cc8f1e6..b5354ff7 100644 --- a/src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/DispatchGuardOutcome.java +++ b/src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/DispatchGuardOutcome.java @@ -2,7 +2,9 @@ package dev.caskeleton.application.notification.platform.dispatch; import dev.caskeleton.application.notification.platform.api.delivery.RecipientDeliveryState; import dev.caskeleton.application.notification.platform.policy.RouteCandidate; +import java.time.Instant; import java.util.Objects; +import java.util.Optional; /** Result of the pre-provider guard chain. */ public sealed interface DispatchGuardOutcome { @@ -16,11 +18,22 @@ public sealed interface DispatchGuardOutcome { } } - /** A guard refused; the recipient job moves to the given state. */ - record Blocked(RecipientDeliveryState state, String reasonCode) implements DispatchGuardOutcome { + /** + * A guard refused; the recipient job moves to the given state. + * + * @param nextDispatchAt when the job becomes due again, for a refusal that only means "not yet" + */ + record Blocked(RecipientDeliveryState state, String reasonCode, Optional nextDispatchAt) + implements DispatchGuardOutcome { public Blocked { Objects.requireNonNull(state, "state"); Objects.requireNonNull(reasonCode, "reasonCode"); + Objects.requireNonNull(nextDispatchAt, "nextDispatchAt"); + } + + /** A refusal that is not waiting for a time. */ + public Blocked(RecipientDeliveryState state, String reasonCode) { + this(state, reasonCode, Optional.empty()); } } } diff --git a/src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/DispatchOutcomeRecorder.java b/src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/DispatchOutcomeRecorder.java index 1a1fca64..2b5f4927 100644 --- a/src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/DispatchOutcomeRecorder.java +++ b/src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/DispatchOutcomeRecorder.java @@ -52,14 +52,25 @@ public final class DispatchOutcomeRecorder { } } - /** Record the provider result on the attempt and roll it up into the recipient job. */ + /** + * Record the provider result on the attempt and roll it up into the recipient job. + * + * @param attempt the attempt the provider was called for + * @param recipient the job as the worker loaded it, before the provider call + * @param lease the lease the worker holds; the recipient write is fenced by it + * @param result what the provider said + * @param completedAt when the call finished + * @return the stored attempt + */ public DeliveryAttemptRecord record( DeliveryAttemptRecord attempt, RecipientDeliveryRecord recipient, + RecipientLease lease, ProviderSubmissionResult result, Instant completedAt) { Objects.requireNonNull(attempt, "attempt"); Objects.requireNonNull(recipient, "recipient"); + Objects.requireNonNull(lease, "lease"); Objects.requireNonNull(result, "result"); Objects.requireNonNull(completedAt, "completedAt"); @@ -105,34 +116,41 @@ public final class DispatchOutcomeRecorder { .bindUnmatched(attempt.providerProfileId(), requestId, stored.id()) .forEach(projection::project)); + // Read again: the projection above may just have rolled a delivered or bounced outcome onto + // this row, and the snapshot taken before the provider call would write it back over that. + // Only the fields an attempt result decides are this recorder's to change. + RecipientDeliveryRecord current = recipients.find(recipient.id()).orElse(recipient); boolean ambiguous = result.confirmation() == AttemptConfirmation.AMBIGUOUS; RecipientDeliveryRecord updated = new RecipientDeliveryRecord( - recipient.id(), - recipient.notificationId(), - recipient.tenantId(), - recipient.recipientRef(), - recipient.locale(), - recipient.timeZone(), - recipient.routingPlan(), - recipient.routeCursor(), + current.id(), + current.notificationId(), + current.tenantId(), + current.recipientRef(), + current.locale(), + current.timeZone(), + current.routingPlan(), + current.routeCursor(), ambiguous ? RecipientDeliveryState.RECONCILIATION_REQUIRED : RecipientDeliveryState.DISPATCHING, result.submissionOutcome(), - recipient.deliveryOutcome(), - recipient.evidenceLevel().strongerOf(result.evidenceLevel()), - recipient.ambiguousAttemptExists() || ambiguous, - recipient.duplicateRisk() || ambiguous, - recipient.nextDispatchAt(), - recipient.expiresAt(), - recipient.leaseOwner(), - recipient.leaseUntil(), - recipient.attemptCount() + 1, + current.deliveryOutcome(), + current.evidenceLevel().strongerOf(result.evidenceLevel()), + current.ambiguousAttemptExists() || ambiguous, + current.duplicateRisk() || ambiguous, + current.nextDispatchAt(), + current.expiresAt(), + current.leaseOwner(), + current.leaseUntil(), + current.attemptCount() + 1, result.failure().map(failure -> failure.category().name()), - recipient.createdAt(), + current.createdAt(), completedAt); - recipients.save(updated); + // Fenced like every write after the claim. An empty result means a new holder owns the row; + // the attempt row above still records what this worker's call did, and the fenced next-step + // write in the dispatch service will match nothing either. + recipients.saveHeldBy(updated, lease); metrics.increment( NotificationMetricName.DISPATCH, diff --git a/src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/DispatchPipeline.java b/src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/DispatchPipeline.java index 081d39bc..7bb77eaf 100644 --- a/src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/DispatchPipeline.java +++ b/src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/DispatchPipeline.java @@ -54,8 +54,10 @@ public final class DispatchPipeline { return new DispatchGuardOutcome.Blocked(RecipientDeliveryState.EXPIRED, "EXPIRED"); } if (request.notBefore().map(now::isBefore).orElse(false)) { + // Due again at notBefore. Without the time the job was left with no next dispatch, which the + // claim query never selects: redriven early, it was never sent at all. return new DispatchGuardOutcome.Blocked( - RecipientDeliveryState.READY_TO_DISPATCH, "NOT_BEFORE_NOT_REACHED"); + RecipientDeliveryState.READY_TO_DISPATCH, "NOT_BEFORE_NOT_REACHED", request.notBefore()); } Optional contact = contactPoints.find(tenantId, route.contactPointId()); diff --git a/src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/LeaseRecoveryService.java b/src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/LeaseRecoveryService.java index ee3a86f7..9f9b4a57 100644 --- a/src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/LeaseRecoveryService.java +++ b/src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/LeaseRecoveryService.java @@ -120,6 +120,17 @@ public final class LeaseRecoveryService { handled++; continue; } + if (attemptsOfDelivery.stream().allMatch(attempt -> attempt.completedAt().isPresent())) { + // Crash after the outcome was recorded and before the next step was applied. The loop + // below skips completed attempts, so the row stayed DISPATCHING and came back first on + // every pass, starving the rest of the batch. The recorder already wrote the outcome onto + // the delivery, and dispatch derives the next step from exactly those facts — an accepted + // submission stops as COMPLETED, an ambiguous one goes to reconciliation — so handing it + // back to dispatch cannot send a second copy of something the provider accepted. + requeue(recipientDeliveryId); + handled++; + continue; + } for (var attempt : attemptsOfDelivery) { if (attempt.completedAt().isEmpty()) { if (provablyNeverStarted(attempt)) { diff --git a/src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/NotificationDispatchService.java b/src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/NotificationDispatchService.java index 564b82cb..6b66c818 100644 --- a/src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/NotificationDispatchService.java +++ b/src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/NotificationDispatchService.java @@ -4,6 +4,7 @@ import dev.caskeleton.application.notification.platform.api.NotificationVariable import dev.caskeleton.application.notification.platform.api.delivery.RecipientDeliveryState; import dev.caskeleton.application.notification.platform.api.delivery.SubmissionOutcome; import dev.caskeleton.application.notification.platform.api.error.FailureCategory; +import dev.caskeleton.application.notification.platform.api.error.NotificationException; import dev.caskeleton.application.notification.platform.api.error.NotificationFailureCode; import dev.caskeleton.application.notification.platform.policy.NotificationRetryPolicy; import dev.caskeleton.application.notification.platform.policy.RetryBudget; @@ -136,15 +137,31 @@ public final class NotificationDispatchService { now); if (guard instanceof DispatchGuardOutcome.Blocked blocked) { transactions.inWrite( - () -> recipients.transition(work.recipient().id(), blocked.state(), Optional.empty())); + () -> + recipients.transition( + work.recipient().id(), blocked.state(), blocked.nextDispatchAt())); refreshStatus(work); releaseLease(lease); return; } ContactPointRecord contactPoint = ((DispatchGuardOutcome.Proceed) guard).contactPoint(); - RenderedNotificationContent content = render(work, route); - ProviderProfileSnapshot profile = gateway.profile(route.providerProfileId()); + RenderedNotificationContent content; + ProviderProfileSnapshot profile; + try { + content = render(work, route); + profile = gateway.profile(route.providerProfileId()); + } catch (NotificationException preDispatch) { + if (preDispatch.descriptor().retryable()) { + throw preDispatch; + } + // No attempt row exists yet, so a failure here used to escape with the lease still held: + // the lease expired, recovery found no attempt and requeued the job, and the same render + // failed again — forever. A template that cannot render will not render on the next pass. + failBeforeAttempt(work, lease, preDispatch.descriptor().category(), now); + releaseLease(lease); + return; + } DeliveryAttemptRecord attempt = transactions.inWrite( @@ -174,13 +191,47 @@ public final class NotificationDispatchService { DeliveryAttemptRecord recorded = transactions.inWrite( - () -> recorder.record(attempt, work.recipient(), result, clock.instant())); + () -> recorder.record(attempt, work.recipient(), lease, result, clock.instant())); RetryDecision next = retryPolicy.decide(retryContext(work, recorded, result, profile)); applyNextAction(work, recorded, next, clock.instant(), lease); releaseLease(lease); } + private void failBeforeAttempt( + Work work, RecipientLease lease, FailureCategory category, Instant now) { + RecipientDeliveryRecord recipient = work.recipient(); + RecipientDeliveryRecord failed = + new RecipientDeliveryRecord( + recipient.id(), + recipient.notificationId(), + recipient.tenantId(), + recipient.recipientRef(), + recipient.locale(), + recipient.timeZone(), + recipient.routingPlan(), + recipient.routeCursor(), + RecipientDeliveryState.FAILED, + recipient.submissionOutcome(), + recipient.deliveryOutcome(), + recipient.evidenceLevel(), + recipient.ambiguousAttemptExists(), + recipient.duplicateRisk(), + Optional.empty(), + recipient.expiresAt(), + recipient.leaseOwner(), + recipient.leaseUntil(), + recipient.attemptCount(), + Optional.of(category.name()), + recipient.createdAt(), + now); + transactions.inWrite( + () -> { + recipients.saveHeldBy(failed, lease); + refreshStatus(work); + }); + } + /** * Recomputes and stores the request status. * diff --git a/src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/ReconciliationService.java b/src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/ReconciliationService.java index fd871b54..ba131dcd 100644 --- a/src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/ReconciliationService.java +++ b/src/application-notification/src/main/java/dev/caskeleton/application/notification/platform/dispatch/ReconciliationService.java @@ -74,16 +74,12 @@ public final class ReconciliationService { } DeliveryAttemptSnapshot attempt = loaded.get(); - if (!gateway.supports(attempt.providerProfileId())) { - // Without a query capability the platform refuses to invent a final status; the attempt stays - // ambiguous and visible to operators. - metrics.increment( - NotificationMetricName.RECONCILIATION, - Map.of("provider", attempt.providerId().value(), "correction", "UNSUPPORTED")); - return new ReconciliationResult.Unsupported(); - } - - ReconciliationResult result = gateway.reconcile(attempt); + // Without a query capability the platform refuses to invent a final status; the attempt stays + // ambiguous and visible to operators. + ReconciliationResult result = + gateway.supports(attempt.providerProfileId()) + ? gateway.reconcile(attempt) + : new ReconciliationResult.Unsupported(); switch (result) { case ReconciliationResult.Confirmed confirmed -> { var appended = @@ -123,18 +119,46 @@ public final class ReconciliationService { attempt.recipientDeliveryId(), RecipientDeliveryState.RECONCILIATION_REQUIRED, Optional.of(unknown.nextCheckAt()))); - case ReconciliationResult.Unsupported ignored -> - metrics.increment( - NotificationMetricName.RECONCILIATION, - Map.of("provider", attempt.providerId().value(), "correction", "UNSUPPORTED")); - case ReconciliationResult.Failed failed -> - metrics.increment( - NotificationMetricName.RECONCILIATION, - Map.of("provider", attempt.providerId().value(), "correction", "FAILED")); + case ReconciliationResult.Unsupported ignored -> { + metrics.increment( + NotificationMetricName.RECONCILIATION, + Map.of("provider", attempt.providerId().value(), "correction", "UNSUPPORTED")); + parkForOperator(attempt); + } + case ReconciliationResult.Failed failed -> { + metrics.increment( + NotificationMetricName.RECONCILIATION, + Map.of("provider", attempt.providerId().value(), "correction", "FAILED")); + parkForOperator(attempt); + } } return result; } + /** + * Takes a still-in-flight delivery out of recovery when the provider cannot answer. + * + *

    Only the metric used to move. The delivery stayed {@code DISPATCHING}, lease recovery + * selected it again on every pass, asked again, and got the same non-answer — so one delivery + * with no status query held a slot of every batch forever. {@code RECONCILIATION_REQUIRED} with + * no next check is the state an operator reads; the ambiguous attempt itself is untouched, so a + * redrive still asks for duplicate-risk approval. A delivery that already finished keeps its + * state: an operator reconciling a completed one must not reopen it. + */ + private void parkForOperator(DeliveryAttemptSnapshot attempt) { + transactions.inWrite( + () -> + recipients + .find(attempt.recipientDeliveryId()) + .filter(recipient -> recipient.state() == RecipientDeliveryState.DISPATCHING) + .ifPresent( + recipient -> + recipients.transition( + recipient.id(), + RecipientDeliveryState.RECONCILIATION_REQUIRED, + Optional.empty()))); + } + private static String emptyDigest() { return "0".repeat(64); } diff --git a/src/application-notification/src/test/java/dev/caskeleton/application/notification/platform/admin/AdminOperationExecutorTest.java b/src/application-notification/src/test/java/dev/caskeleton/application/notification/platform/admin/AdminOperationExecutorTest.java index 62612cba..9dd1ee1d 100644 --- a/src/application-notification/src/test/java/dev/caskeleton/application/notification/platform/admin/AdminOperationExecutorTest.java +++ b/src/application-notification/src/test/java/dev/caskeleton/application/notification/platform/admin/AdminOperationExecutorTest.java @@ -2,12 +2,14 @@ package dev.caskeleton.application.notification.platform.admin; import static org.assertj.core.api.Assertions.assertThat; import static org.assertj.core.api.Assertions.assertThatThrownBy; +import static org.assertj.core.api.Assertions.catchThrowable; import dev.caskeleton.application.transaction.TransactionPort; import java.util.Optional; import java.util.Set; import java.util.concurrent.atomic.AtomicInteger; import java.util.function.Supplier; +import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; class AdminOperationExecutorTest { @@ -94,6 +96,35 @@ class AdminOperationExecutorTest { assertThat(sideEffects).hasValue(0); } + @Test + @DisplayName("트랜잭션 밖에서 실패한 operation은 claim을 FAILED 결과로 닫는다") + void anOperationThatFailsOutsideTheTransactionCompletesItsClaimAsFailed() { + // given + FakeStore store = new FakeStore(AdminOperationClaim.claimed()); + AdminOperationExecutor executor = + new AdminOperationExecutor(store, new RecordingTransactions()); + + // when + var unused = + catchThrowable( + () -> + executor.executeOutsideTransaction( + "op-1", + FINGERPRINT, + ACTOR, + "ADMIN_RECONCILE", + () -> { + throw new IllegalStateException("provider unreachable"); + })); + + // then + assertThat(store.saved) + .as( + "the claim committed before the operation ran; left CLAIMED, the id answers in-progress") + .extracting(AdminOperationResult::operationId, AdminOperationResult::reasonCodes) + .containsExactly("op-1", java.util.List.of("FAILED")); + } + private static Supplier sideEffect(AtomicInteger sideEffects) { return () -> { sideEffects.incrementAndGet(); @@ -115,6 +146,7 @@ class AdminOperationExecutorTest { private static final class FakeStore implements AdminOperationStorePort { private final AdminOperationClaim outcome; private int claims; + private AdminOperationResult saved; FakeStore(AdminOperationClaim outcome) { this.outcome = outcome; @@ -127,6 +159,7 @@ class AdminOperationExecutorTest { @Override public AdminOperationResult save(AdminOperationResult result, AdminActor actor, String action) { + saved = result; return result; } diff --git a/src/application-notification/src/test/java/dev/caskeleton/application/notification/platform/admin/NotificationAdminApplicationServiceTest.java b/src/application-notification/src/test/java/dev/caskeleton/application/notification/platform/admin/NotificationAdminApplicationServiceTest.java index 446aa7ea..ad385a5d 100644 --- a/src/application-notification/src/test/java/dev/caskeleton/application/notification/platform/admin/NotificationAdminApplicationServiceTest.java +++ b/src/application-notification/src/test/java/dev/caskeleton/application/notification/platform/admin/NotificationAdminApplicationServiceTest.java @@ -18,12 +18,15 @@ import dev.caskeleton.application.notification.platform.api.routing.Channel; import dev.caskeleton.application.notification.platform.callback.DeliveryAttemptSnapshot; import dev.caskeleton.application.notification.platform.dispatch.NotificationPlatformNoops; import dev.caskeleton.application.notification.platform.dispatch.PlatformFakes; +import dev.caskeleton.application.notification.platform.dispatch.ReconciliationGatewayPort; +import dev.caskeleton.application.notification.platform.dispatch.ReconciliationService; import dev.caskeleton.application.notification.platform.observation.NotificationAuditEvent; import dev.caskeleton.application.notification.platform.observation.NotificationAuditPort; import dev.caskeleton.application.notification.platform.policy.SuppressionEntry; import dev.caskeleton.application.notification.platform.policy.SuppressionId; import dev.caskeleton.application.notification.platform.policy.SuppressionStorePort; import dev.caskeleton.application.notification.platform.provider.ProviderRuntimeState; +import dev.caskeleton.application.notification.platform.provider.ReconciliationResult; import java.time.Clock; import java.time.Instant; import java.time.ZoneOffset; @@ -32,6 +35,7 @@ import java.util.List; import java.util.Optional; import java.util.Set; import java.util.UUID; +import java.util.concurrent.atomic.AtomicReference; import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; @@ -142,6 +146,44 @@ class NotificationAdminApplicationServiceTest { .isEqualTo(NotificationAdminAuthority.PROVIDER_CONTROL)); } + @Test + @DisplayName("운영자 reconcile은 DB 트랜잭션을 연 채로 provider에 묻지 않는다") + void reconcileAsksTheProviderWithNoTransactionOpen() { + // given + List transactionOpenDuringProviderCall = new ArrayList<>(); + AtomicReference holder = new AtomicReference<>(); + Fixture fixture = + new Fixture( + new ReconciliationGatewayPort() { + @Override + public boolean supports(ProviderProfileId profileId) { + return true; + } + + @Override + public ReconciliationResult reconcile(DeliveryAttemptSnapshot attempt) { + transactionOpenDuringProviderCall.add(holder.get().transactions.inTransaction()); + return new ReconciliationResult.Unsupported(); + } + }); + holder.set(fixture); + DeliveryAttemptSnapshot attempt = attemptOf(new TenantId("tenant-a")); + fixture.attempts.snapshots.put(attempt.attemptId(), attempt); + AdminActor operator = + new AdminActor( + "operator-1", Set.of(NotificationAdminAuthority.RECONCILE), Optional.empty()); + + // when + fixture.service.reconcile( + new ReconcileCommand("op-rc", List.of(attempt.attemptId()), "stuck attempt", false), + operator); + + // then + assertThat(transactionOpenDuringProviderCall) + .as("a slow provider held a write transaction, and its connection, for every attempt") + .containsExactly(false); + } + private static DeliveryAttemptSnapshot attemptOf(TenantId tenantId) { return new DeliveryAttemptSnapshot( new DeliveryAttemptId(UUID.fromString("00000000-0000-7000-8000-000000000011")), @@ -175,21 +217,36 @@ class NotificationAdminApplicationServiceTest { private final RecordingAudit audit = new RecordingAudit(); private final PlatformFakes.RecordingTransactions transactions = new PlatformFakes.RecordingTransactions(); - private final NotificationAdminApplicationService service = - new NotificationAdminApplicationService( - new AdminAuthorizationGuard(), - new DuplicateRiskGuard(), - attempts, - recipients, - NotificationPlatformNoops.reconciliation(attempts, recipients, CLOCK), - new UnusedSuppressionStore(), - runtime, - operations, - audit, - transactions, - new PlatformFakes.SequentialIds(), - NotificationAdminApplicationServiceTest::sha256, - CLOCK); + private final NotificationAdminApplicationService service; + + private Fixture() { + this(null); + } + + /** + * @param gateway the provider the reconciliation asks, or null for one that supports nothing + */ + private Fixture(ReconciliationGatewayPort gateway) { + ReconciliationService reconciliation = + gateway == null + ? NotificationPlatformNoops.reconciliation(attempts, recipients, CLOCK) + : NotificationPlatformNoops.reconciliation(attempts, recipients, gateway, CLOCK); + service = + new NotificationAdminApplicationService( + new AdminAuthorizationGuard(), + new DuplicateRiskGuard(), + attempts, + recipients, + reconciliation, + new UnusedSuppressionStore(), + runtime, + operations, + audit, + transactions, + new PlatformFakes.SequentialIds(), + NotificationAdminApplicationServiceTest::sha256, + CLOCK); + } } private static final class RecordingRuntime implements ProviderRuntimeControlPort { diff --git a/src/application-notification/src/test/java/dev/caskeleton/application/notification/platform/dispatch/AcceptNotificationApplicationUseCaseTest.java b/src/application-notification/src/test/java/dev/caskeleton/application/notification/platform/dispatch/AcceptNotificationApplicationUseCaseTest.java index dbbc0853..6fc2a5c2 100644 --- a/src/application-notification/src/test/java/dev/caskeleton/application/notification/platform/dispatch/AcceptNotificationApplicationUseCaseTest.java +++ b/src/application-notification/src/test/java/dev/caskeleton/application/notification/platform/dispatch/AcceptNotificationApplicationUseCaseTest.java @@ -1,6 +1,7 @@ package dev.caskeleton.application.notification.platform.dispatch; import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.catchThrowable; import dev.caskeleton.application.notification.platform.api.NotificationId; import dev.caskeleton.application.notification.platform.api.NotificationPlan; @@ -96,6 +97,28 @@ class AcceptNotificationApplicationUseCaseTest { .isEqualTo(submit.plans.get(0).idempotencyKey()); } + @Test + void anAcceptanceWithoutCategoryIsRefusedRatherThanDefaulted() { + // when: category decides marketing suppression, so no transport may pick one for the caller + Throwable thrown = + catchThrowable( + () -> + new AcceptNotificationCommand( + Optional.empty(), + "customer-42", + Channel.EMAIL, + "person@example.com", + "payment-receipt", + 1, + Locale.KOREAN, + Map.of(), + Optional.empty(), + null)); + + // then + assertThat(thrown).isInstanceOf(IllegalArgumentException.class).hasMessage("category"); + } + private static AcceptNotificationCommand command(Map variables) { return new AcceptNotificationCommand( Optional.empty(), diff --git a/src/application-notification/src/test/java/dev/caskeleton/application/notification/platform/dispatch/DispatchOutcomeRecorderTest.java b/src/application-notification/src/test/java/dev/caskeleton/application/notification/platform/dispatch/DispatchOutcomeRecorderTest.java index b72cc1db..bfdb14ad 100644 --- a/src/application-notification/src/test/java/dev/caskeleton/application/notification/platform/dispatch/DispatchOutcomeRecorderTest.java +++ b/src/application-notification/src/test/java/dev/caskeleton/application/notification/platform/dispatch/DispatchOutcomeRecorderTest.java @@ -4,6 +4,8 @@ import static org.assertj.core.api.Assertions.assertThat; import dev.caskeleton.application.notification.platform.api.ContactPointId; import dev.caskeleton.application.notification.platform.api.DeliveryAttemptId; +import dev.caskeleton.application.notification.platform.api.NormalizedEventType; +import dev.caskeleton.application.notification.platform.api.NormalizedProviderEvent; import dev.caskeleton.application.notification.platform.api.NotificationId; import dev.caskeleton.application.notification.platform.api.ProviderId; import dev.caskeleton.application.notification.platform.api.ProviderProfileId; @@ -24,10 +26,13 @@ import dev.caskeleton.application.notification.platform.callback.DeliveryProject import dev.caskeleton.application.notification.platform.callback.DeliveryProjectionStorePort; import dev.caskeleton.application.notification.platform.callback.NotificationSideEffectPort; import dev.caskeleton.application.notification.platform.callback.ProjectionResult; +import dev.caskeleton.application.notification.platform.callback.ProjectionStatus; import dev.caskeleton.application.notification.platform.callback.ProviderEventLedger; import dev.caskeleton.application.notification.platform.callback.ProviderEventProjectionService; +import dev.caskeleton.application.notification.platform.callback.ProviderEventProjector; import dev.caskeleton.application.notification.platform.callback.ProviderEventRecord; import dev.caskeleton.application.notification.platform.callback.ProviderEventRecordId; +import dev.caskeleton.application.notification.platform.callback.ProviderEventSource; import dev.caskeleton.application.notification.platform.callback.ProviderRequestIdHash; import dev.caskeleton.application.notification.platform.callback.VerifiedProviderEvent; import dev.caskeleton.application.notification.platform.observation.NotificationMetricName; @@ -39,6 +44,7 @@ import java.time.Instant; import java.util.List; import java.util.Optional; import java.util.UUID; +import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; class DispatchOutcomeRecorderTest { @@ -50,11 +56,13 @@ class DispatchOutcomeRecorderTest { private static final RecipientDeliveryId RECIPIENT_ID = new RecipientDeliveryId(UUID.fromString("00000000-0000-7000-8000-000000000032")); private static final ProviderProfileId PROFILE = new ProviderProfileId("ses-primary"); + private static final RecipientLease LEASE = + new RecipientLease(RECIPIENT_ID, "worker-a", 1L, STARTED.plusSeconds(30)); @Test void ambiguousSubmissionIsPersistedAndSchedulesReconciliation() { RecordingAttemptStore attempts = new RecordingAttemptStore(); - RecordingRecipientStore recipients = new RecordingRecipientStore(); + RecordingRecipientStore recipients = new RecordingRecipientStore(recipient()); RecordingReconciliationJobs jobs = new RecordingReconciliationJobs(); PlatformFakes.RecordingMetrics metrics = new PlatformFakes.RecordingMetrics(); DispatchOutcomeRecorder recorder = @@ -71,6 +79,7 @@ class DispatchOutcomeRecorderTest { recorder.record( attempt(), recipient(), + LEASE, ProviderSubmissionResult.ambiguous( ProviderFailure.of( NotificationFailureCode.PROVIDER_RESPONSE_LOST, @@ -92,6 +101,210 @@ class DispatchOutcomeRecorderTest { .contains(NotificationMetricName.DISPATCH, NotificationMetricName.AMBIGUOUS); } + @Test + @DisplayName("늦게 짝지어진 콜백이 수신자에 반영한 배달 결과를 recorder가 덮어쓰지 않는다") + void aLateMatchedCallbackProjectionIsNotOverwrittenByTheRecorder() { + // given + RecordingRecipientStore recipients = new RecordingRecipientStore(recipient()); + DispatchOutcomeRecorder recorder = + new DispatchOutcomeRecorder( + new RecordingAttemptStore(), + recipients, + new RecordingReconciliationJobs(), + new OneUnmatchedEventLedger(), + deliveringProjection(recipients), + new PlatformFakes.RecordingMetrics(), + Duration.ofSeconds(30)); + + // when + recorder.record( + attempt(), + recipient(), + LEASE, + ProviderSubmissionResult.accepted("ses-message-1", "Accepted", Duration.ofSeconds(1)), + COMPLETED); + + // then + assertThat(recipients.saved) + .extracting( + RecipientDeliveryRecord::deliveryOutcome, RecipientDeliveryRecord::evidenceLevel) + .containsExactly(DeliveryOutcome.DELIVERED, EvidenceLevel.DEVICE_DELIVERED); + } + + @Test + @DisplayName("lease를 잃은 worker의 recorder는 수신자 행에 아무것도 쓰지 않는다") + void aRecorderThatLostItsLeaseWritesNothingToTheRecipient() { + // given + RecordingRecipientStore recipients = new RecordingRecipientStore(recipient()); + recipients.superseded = true; + DispatchOutcomeRecorder recorder = + new DispatchOutcomeRecorder( + new RecordingAttemptStore(), + recipients, + new RecordingReconciliationJobs(), + new NoopLedger(), + noopProjection(), + new PlatformFakes.RecordingMetrics(), + Duration.ofSeconds(30)); + + // when + recorder.record( + attempt(), + recipient(), + LEASE, + ProviderSubmissionResult.accepted("ses-message-1", "Accepted", Duration.ofSeconds(1)), + COMPLETED); + + // then + assertThat(recipients.writes) + .as("a new holder owns the row; the stale snapshot must not land on it") + .isZero(); + } + + /** + * A projection whose store rolls the delivered outcome up onto the recipient row, as the JPA + * store does, for an event the ledger hands back once the provider request id is known. + */ + private static ProviderEventProjectionService deliveringProjection( + RecordingRecipientStore recipients) { + DeliveryAttemptSnapshot snapshot = + new DeliveryAttemptSnapshot( + ATTEMPT_ID, + RECIPIENT_ID, + new NotificationId(UUID.fromString("00000000-0000-7000-8000-000000000034")), + new TenantId("tenant-a"), + 1, + Channel.EMAIL, + new ProviderId("ses"), + PROFILE, + Optional.of("ses-message-1"), + new ContactPointId(UUID.fromString("00000000-0000-7000-8000-000000000033")), + AttemptConfirmation.CONFIRMED, + SubmissionOutcome.CONFIRMED_ACCEPTED, + DeliveryOutcome.UNKNOWN, + EvidenceLevel.PROVIDER_ACCEPTED, + 1L, + "a".repeat(64), + STARTED, + Optional.of(COMPLETED), + Optional.empty()); + DeliveryAttemptResolverPort resolver = + new DeliveryAttemptResolverPort() { + @Override + public Optional byAttemptId(DeliveryAttemptId attemptId) { + return Optional.of(snapshot); + } + + @Override + public Optional byProviderRequestId( + ProviderProfileId profileId, String providerRequestId) { + return Optional.of(snapshot); + } + + @Override + public Optional byProviderRequestIdHash( + ProviderProfileId profileId, ProviderRequestIdHash providerRequestIdHash) { + return Optional.of(snapshot); + } + }; + DeliveryProjectionStorePort projections = + new DeliveryProjectionStorePort() { + @Override + public DeliveryProjection load(DeliveryAttemptId attemptId) { + return DeliveryProjection.accepted(); + } + + @Override + public void save(DeliveryAttemptId attemptId, DeliveryProjection projection) { + RecipientDeliveryRecord current = recipients.saved; + recipients.saved = + new RecipientDeliveryRecord( + current.id(), + current.notificationId(), + current.tenantId(), + current.recipientRef(), + current.locale(), + current.timeZone(), + current.routingPlan(), + current.routeCursor(), + current.state(), + projection.submissionOutcome(), + projection.deliveryOutcome(), + current.evidenceLevel().strongerOf(projection.evidenceLevel()), + current.ambiguousAttemptExists(), + current.duplicateRisk(), + current.nextDispatchAt(), + current.expiresAt(), + current.leaseOwner(), + current.leaseUntil(), + current.attemptCount(), + current.lastFailureCategory(), + current.createdAt(), + COMPLETED); + } + + @Override + public boolean claimSuppressionSideEffect(DeliveryAttemptId attemptId) { + return false; + } + }; + ProviderEventProjector delivered = + new ProviderEventProjector() { + @Override + public ProviderId providerId() { + return new ProviderId("ses"); + } + + @Override + public ProjectionResult project( + DeliveryAttemptSnapshot attempt, + ProviderEventRecord event, + DeliveryProjection current) { + return ProjectionResult.applied( + current.withDelivery(DeliveryOutcome.DELIVERED, EvidenceLevel.DEVICE_DELIVERED), + "DELIVERED"); + } + }; + return new ProviderEventProjectionService( + new NoopLedger(), + providerId -> Optional.of(delivered), + resolver, + projections, + (attempt, facts) -> {}, + new PlatformFakes.RecordingTransactions(), + new PlatformFakes.RecordingMetrics()); + } + + /** A ledger holding one delivery event that arrived before the provider request id was known. */ + private static final class OneUnmatchedEventLedger extends NoopLedgerBase { + @Override + public List bindUnmatched( + ProviderProfileId providerProfileId, + String providerRequestId, + DeliveryAttemptId attemptId) { + return List.of( + new ProviderEventRecord( + new ProviderEventRecordId(UUID.fromString("00000000-0000-7000-8000-000000000036")), + PROFILE, + new NormalizedProviderEvent( + NormalizedEventType.DELIVERY_CONFIRMED, + "Delivery", + Optional.empty(), + Optional.of(providerRequestId), + Optional.of(STARTED), + java.util.Map.of()), + Optional.of(attemptId), + Optional.empty(), + ProviderEventSource.CALLBACK, + true, + STARTED, + "a".repeat(64), + "b".repeat(64), + ProjectionStatus.PENDING, + Optional.empty())); + } + } + private static DeliveryAttemptRecord attempt() { return new DeliveryAttemptRecord( ATTEMPT_ID, @@ -228,6 +441,12 @@ class DispatchOutcomeRecorderTest { private static final class RecordingRecipientStore implements RecipientDeliveryStorePort { private RecipientDeliveryRecord saved; + private boolean superseded; + private int writes; + + private RecordingRecipientStore(RecipientDeliveryRecord initial) { + this.saved = initial; + } @Override public Optional find(RecipientDeliveryId id) { @@ -236,6 +455,7 @@ class DispatchOutcomeRecorderTest { @Override public RecipientDeliveryRecord save(RecipientDeliveryRecord record) { + writes++; saved = record; return record; } @@ -249,7 +469,7 @@ class DispatchOutcomeRecorderTest { @Override public Optional saveHeldBy( RecipientDeliveryRecord record, RecipientLease lease) { - throw new UnsupportedOperationException(); + return superseded ? Optional.empty() : Optional.of(save(record)); } @Override @@ -294,7 +514,9 @@ class DispatchOutcomeRecorderTest { public void complete(ReconciliationJob job) {} } - private static final class NoopLedger implements ProviderEventLedger { + private static final class NoopLedger extends NoopLedgerBase {} + + private static class NoopLedgerBase implements ProviderEventLedger { @Override public AppendEventResult append(VerifiedProviderEvent event) { return new AppendEventResult(List.of(), List.of()); diff --git a/src/application-notification/src/test/java/dev/caskeleton/application/notification/platform/dispatch/LeaseRecoveryServiceTest.java b/src/application-notification/src/test/java/dev/caskeleton/application/notification/platform/dispatch/LeaseRecoveryServiceTest.java index 8031f084..566e0f4c 100644 --- a/src/application-notification/src/test/java/dev/caskeleton/application/notification/platform/dispatch/LeaseRecoveryServiceTest.java +++ b/src/application-notification/src/test/java/dev/caskeleton/application/notification/platform/dispatch/LeaseRecoveryServiceTest.java @@ -109,6 +109,32 @@ class LeaseRecoveryServiceTest { assertThat(deliveries.transitions).isEmpty(); } + @Test + @DisplayName("attempt가 모두 끝난 DISPATCHING 수신자는 다시 꺼낼 수 있게 되돌린다") + void aDispatchingDeliveryWhoseAttemptsAllCompletedIsRequeued() { + // given + RecipientDeliveryId id = new RecipientDeliveryId(UUID.randomUUID()); + leases.abandoned.add(id); + attempts.byDelivery.put( + id, + List.of( + completed( + attemptWith( + new DeliveryAttemptId(UUID.randomUUID()), + dev.caskeleton.application.notification.platform.provider + .ProviderExecutionEvidence.completed(true))))); + + // when + recovery.recoverOnce(); + + // then + assertThat(deliveries.transitions) + .as( + "the worker died after recording the outcome and before applying the next step; left" + + " DISPATCHING, the row is selected again on every pass and starves the rest") + .containsExactly(Map.entry(id, RecipientDeliveryState.READY_TO_DISPATCH)); + } + @Test @DisplayName("the decision depends on certainty, not on the value alone") void theDecisionDependsOnCertaintyNotValueAlone() { @@ -173,6 +199,34 @@ class LeaseRecoveryServiceTest { base.renderedContentDigest()); } + /** The same attempt with its outcome written, as the recorder leaves it. */ + private static DeliveryAttemptRecord completed(DeliveryAttemptRecord base) { + return new DeliveryAttemptRecord( + base.id(), + base.recipientDeliveryId(), + base.contactPointId(), + base.attemptNo(), + base.channel(), + base.providerId(), + base.providerProfileId(), + base.providerRequestId(), + base.executionEvidence(), + dev.caskeleton.application.notification.platform.api.delivery.SubmissionOutcome + .CONFIRMED_ACCEPTED, + base.deliveryOutcome(), + dev.caskeleton.application.notification.platform.api.delivery.AttemptConfirmation.CONFIRMED, + base.evidenceLevel(), + base.failureCategory(), + base.failureCode(), + base.nativeStatus(), + base.providerOccurredAt(), + base.startedAt(), + Optional.of(NOW), + Optional.of(Duration.ofSeconds(1)), + base.credentialGeneration(), + base.renderedContentDigest()); + } + /** An attempt row that exists with no completion: the provider may or may not have seen it. */ private static DeliveryAttemptRecord incompleteAttempt(DeliveryAttemptId id) { return new DeliveryAttemptRecord( diff --git a/src/application-notification/src/test/java/dev/caskeleton/application/notification/platform/dispatch/NotificationDispatchServiceTest.java b/src/application-notification/src/test/java/dev/caskeleton/application/notification/platform/dispatch/NotificationDispatchServiceTest.java index af53f0d9..e8b47370 100644 --- a/src/application-notification/src/test/java/dev/caskeleton/application/notification/platform/dispatch/NotificationDispatchServiceTest.java +++ b/src/application-notification/src/test/java/dev/caskeleton/application/notification/platform/dispatch/NotificationDispatchServiceTest.java @@ -3,6 +3,8 @@ package dev.caskeleton.application.notification.platform.dispatch; import static org.assertj.core.api.Assertions.assertThat; import dev.caskeleton.application.notification.platform.api.ContactPointId; +import dev.caskeleton.application.notification.platform.api.NotificationId; +import dev.caskeleton.application.notification.platform.api.NotificationPlan; import dev.caskeleton.application.notification.platform.api.ProviderId; import dev.caskeleton.application.notification.platform.api.ProviderProfileId; import dev.caskeleton.application.notification.platform.api.RecipientDeliveryId; @@ -10,8 +12,12 @@ import dev.caskeleton.application.notification.platform.api.TemplateSelection; import dev.caskeleton.application.notification.platform.api.TenantId; import dev.caskeleton.application.notification.platform.api.content.EmailContent; import dev.caskeleton.application.notification.platform.api.content.EmailOptions; +import dev.caskeleton.application.notification.platform.api.delivery.RecipientDeliveryState; import dev.caskeleton.application.notification.platform.api.delivery.SubmissionOutcome; +import dev.caskeleton.application.notification.platform.api.error.FailureCategory; import dev.caskeleton.application.notification.platform.api.error.NotificationFailureCode; +import dev.caskeleton.application.notification.platform.api.error.NotificationFailureDescriptor; +import dev.caskeleton.application.notification.platform.api.error.TemplateVariableValidationException; import dev.caskeleton.application.notification.platform.api.routing.Channel; import dev.caskeleton.application.notification.platform.contact.ContactPointStatus; import dev.caskeleton.application.notification.platform.contact.ContactPointType; @@ -36,6 +42,7 @@ import java.util.Locale; import java.util.Map; import java.util.Optional; import java.util.UUID; +import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; class NotificationDispatchServiceTest { @@ -150,6 +157,135 @@ class NotificationDispatchServiceTest { .isEqualTo(recipient); } + @Test + @DisplayName("렌더링할 수 없는 템플릿은 수신자를 FAILED로 닫고 lease를 놓는다") + void aTemplateThatCannotRenderFailsTheDeliveryInsteadOfLeavingItClaimed() { + // given + Scenario scenario = new Scenario(PlatformFakes.plan("render-failure", Map.of())); + RecordingLeases leases = new RecordingLeases(); + NotificationDispatchService service = + scenario.service( + leases, + channel -> + new NotificationTemplateRenderer() { + @Override + public Channel channel() { + return Channel.EMAIL; + } + + @Override + public RenderedNotificationContent render(RenderCommand command) { + throw new TemplateVariableValidationException( + NotificationFailureDescriptor.preDispatch( + NotificationFailureCode.TEMPLATE_VARIABLES_INVALID, + FailureCategory.TEMPLATE_FAILURE)); + } + }); + + // when + service.dispatch(scenario.lease()); + + // then + assertThat(scenario.stored()) + .extracting(RecipientDeliveryRecord::state, RecipientDeliveryRecord::lastFailureCategory) + .containsExactly(RecipientDeliveryState.FAILED, Optional.of("TEMPLATE_FAILURE")); + } + + @Test + @DisplayName("notBefore 전에 꺼낸 수신자는 notBefore 시각에 다시 꺼낼 수 있게 남는다") + void aDeliveryBlockedByNotBeforeStaysScheduledForThatTime() { + // given + Instant notBefore = NOW.plusSeconds(3600); + NotificationPlan base = PlatformFakes.plan("not-before", Map.of()); + Scenario scenario = + new Scenario( + new NotificationPlan( + base.tenantId(), + base.idempotencyKey(), + base.category(), + base.template(), + base.variables(), + base.recipients(), + base.deliveryStrategy(), + Optional.of(notBefore), + base.expiresAt(), + base.deduplication(), + base.collapse(), + base.correlationId(), + base.boundedMetadata())); + // An operator redrive makes the delivery due now, ahead of its notBefore. + scenario.recipients.transition( + scenario.recipient.id(), RecipientDeliveryState.READY_TO_DISPATCH, Optional.of(NOW)); + NotificationDispatchService service = + scenario.service(new RecordingLeases(), channel -> renderer()); + + // when + service.dispatch(scenario.lease()); + + // then + assertThat(scenario.stored().nextDispatchAt()).contains(notBefore); + } + + /** One accepted request and its recipient, dispatched against fakes. */ + private static final class Scenario { + private final PlatformFakes.RequestStore requests = new PlatformFakes.RequestStore(); + private final PlatformFakes.RecipientStore recipients = + new PlatformFakes.RecipientStore(requests); + private final PlatformFakes.AttemptStore attempts = new PlatformFakes.AttemptStore(); + private final NotificationId notificationId; + private final RecipientDeliveryRecord recipient; + + private Scenario(NotificationPlan plan) { + NotificationSubmissionService submissions = + new NotificationSubmissionService( + requests, + recipients, + attempts, + PlatformFakes.templates(true), + PlatformFakes.fingerprints(), + new CanonicalNotificationPlanWriter( + new PlatformFakes.SequentialIds(), PlatformFakes.routes(Channel.EMAIL)), + new PlatformFakes.RecordingTransactions(), + PlatformFakes.tenant("tenant-a"), + PlatformFakes.deduplication(Clock.fixed(NOW, ZoneOffset.UTC)), + new PlatformFakes.RecordingMetrics(), + Clock.fixed(NOW, ZoneOffset.UTC)); + notificationId = submissions.submit(plan).notificationId(); + recipient = stored(); + } + + private RecipientDeliveryRecord stored() { + return requests.recipientsOf(new TenantId("tenant-a"), notificationId).getFirst(); + } + + private RecipientLease lease() { + return new RecipientLease(recipient.id(), "worker-a", 1L, NOW.plusSeconds(30)); + } + + private NotificationDispatchService service( + RecipientLeaseStorePort leases, TemplateRendererRegistry renderers) { + return new NotificationDispatchService( + requests, + recipients, + attempts, + new DispatchPipeline( + new SingleContactStore(contactPoint()), + NotificationEligibilityPolicy.permitAll(), + new PlatformFakes.RecordingMetrics()), + new RoutingDecisionEngine(), + context -> new RetryDecision.Stop("unused"), + new DeliveryAttemptFactory(new PlatformFakes.SequentialIds()), + NotificationPlatformNoops.outcomeRecorder(attempts, recipients), + new ProfileOnlyGateway(), + renderers, + leases, + new PlatformFakes.RecordingTransactions(), + Clock.fixed(NOW, ZoneOffset.UTC), + 3, + Duration.ofSeconds(5)); + } + } + private static ContactPointRecord contactPoint() { return new ContactPointRecord( new ContactPointId(UUID.fromString("00000000-0000-7000-8000-000000000001")), diff --git a/src/application-notification/src/test/java/dev/caskeleton/application/notification/platform/dispatch/NotificationPlatformNoops.java b/src/application-notification/src/test/java/dev/caskeleton/application/notification/platform/dispatch/NotificationPlatformNoops.java index 15df35be..2416c62d 100644 --- a/src/application-notification/src/test/java/dev/caskeleton/application/notification/platform/dispatch/NotificationPlatformNoops.java +++ b/src/application-notification/src/test/java/dev/caskeleton/application/notification/platform/dispatch/NotificationPlatformNoops.java @@ -30,8 +30,7 @@ public final class NotificationPlatformNoops { public static ReconciliationService reconciliation( DeliveryAttemptStorePort attempts, RecipientDeliveryStorePort recipients, Clock clock) { - ProviderEventLedger ledger = new NoopLedger(); - return new ReconciliationService( + return reconciliation( attempts, recipients, new ReconciliationGatewayPort() { @@ -45,6 +44,20 @@ public final class NotificationPlatformNoops { return new ReconciliationResult.Unsupported(); } }, + clock); + } + + /** Reconciliation over a caller-supplied gateway, everything else a no-op. */ + public static ReconciliationService reconciliation( + DeliveryAttemptStorePort attempts, + RecipientDeliveryStorePort recipients, + ReconciliationGatewayPort gateway, + Clock clock) { + ProviderEventLedger ledger = new NoopLedger(); + return new ReconciliationService( + attempts, + recipients, + gateway, ledger, projection(ledger), audit(), diff --git a/src/application-notification/src/test/java/dev/caskeleton/application/notification/platform/dispatch/ReconciliationServiceTest.java b/src/application-notification/src/test/java/dev/caskeleton/application/notification/platform/dispatch/ReconciliationServiceTest.java index 380c94d6..d806b52d 100644 --- a/src/application-notification/src/test/java/dev/caskeleton/application/notification/platform/dispatch/ReconciliationServiceTest.java +++ b/src/application-notification/src/test/java/dev/caskeleton/application/notification/platform/dispatch/ReconciliationServiceTest.java @@ -12,6 +12,7 @@ import dev.caskeleton.application.notification.platform.api.TenantId; import dev.caskeleton.application.notification.platform.api.delivery.AttemptConfirmation; import dev.caskeleton.application.notification.platform.api.delivery.DeliveryOutcome; import dev.caskeleton.application.notification.platform.api.delivery.EvidenceLevel; +import dev.caskeleton.application.notification.platform.api.delivery.RecipientDeliveryState; import dev.caskeleton.application.notification.platform.api.delivery.SubmissionOutcome; import dev.caskeleton.application.notification.platform.api.routing.Channel; import dev.caskeleton.application.notification.platform.callback.DeliveryAttemptSnapshot; @@ -19,8 +20,10 @@ import dev.caskeleton.application.notification.platform.provider.ReconciliationR import java.time.Clock; import java.time.Instant; import java.time.ZoneOffset; +import java.util.List; import java.util.Optional; import java.util.UUID; +import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; class ReconciliationServiceTest { @@ -58,6 +61,119 @@ class ReconciliationServiceTest { assertThat(result).isInstanceOf(ReconciliationResult.Unsupported.class); } + @Test + @DisplayName("조회를 지원하지 않는 provider면 진행 중이던 수신자를 운영자 확인 상태로 옮긴다") + void anUnsupportedAnswerParksADispatchingDeliveryForAnOperator() { + // given + Stores stores = new Stores(RecipientDeliveryState.DISPATCHING); + ReconciliationService service = + NotificationPlatformNoops.reconciliation( + stores.attempts, stores.recipients, Clock.fixed(NOW, ZoneOffset.UTC)); + + // when + service.reconcile(stores.snapshot.attemptId()); + + // then + assertThat(stores.recipient()) + .extracting(RecipientDeliveryRecord::state, RecipientDeliveryRecord::nextDispatchAt) + .containsExactly(RecipientDeliveryState.RECONCILIATION_REQUIRED, Optional.empty()); + } + + @Test + @DisplayName("provider 조회가 실패하면 진행 중이던 수신자를 운영자 확인 상태로 옮긴다") + void aFailedAnswerParksADispatchingDeliveryForAnOperator() { + // given + Stores stores = new Stores(RecipientDeliveryState.DISPATCHING); + ReconciliationService service = + NotificationPlatformNoops.reconciliation( + stores.attempts, + stores.recipients, + answering(new ReconciliationResult.Failed("PROVIDER_TIMEOUT", true)), + Clock.fixed(NOW, ZoneOffset.UTC)); + + // when + service.reconcile(stores.snapshot.attemptId()); + + // then + assertThat(stores.recipient()) + .extracting(RecipientDeliveryRecord::state, RecipientDeliveryRecord::nextDispatchAt) + .containsExactly(RecipientDeliveryState.RECONCILIATION_REQUIRED, Optional.empty()); + } + + @Test + @DisplayName("이미 끝난 수신자는 조회 결과가 없어도 그대로 둔다") + void anUnsupportedAnswerLeavesAFinishedDeliveryAlone() { + // given + Stores stores = new Stores(RecipientDeliveryState.COMPLETED); + ReconciliationService service = + NotificationPlatformNoops.reconciliation( + stores.attempts, stores.recipients, Clock.fixed(NOW, ZoneOffset.UTC)); + + // when + service.reconcile(stores.snapshot.attemptId()); + + // then + assertThat(stores.recipient().state()).isEqualTo(RecipientDeliveryState.COMPLETED); + } + + private static ReconciliationGatewayPort answering(ReconciliationResult answer) { + return new ReconciliationGatewayPort() { + @Override + public boolean supports(ProviderProfileId profileId) { + return true; + } + + @Override + public ReconciliationResult reconcile(DeliveryAttemptSnapshot attempt) { + return answer; + } + }; + } + + /** One attempt and its recipient delivery in the given state. */ + private static final class Stores { + private final PlatformFakes.AttemptStore attempts = new PlatformFakes.AttemptStore(); + private final PlatformFakes.RequestStore requests = new PlatformFakes.RequestStore(); + private final PlatformFakes.RecipientStore recipients = + new PlatformFakes.RecipientStore(requests); + private final DeliveryAttemptSnapshot snapshot = snapshot(); + + private Stores(RecipientDeliveryState state) { + attempts.snapshots.put(snapshot.attemptId(), snapshot); + requests.recipients.put( + snapshot.notificationId(), + new java.util.ArrayList<>( + List.of( + new RecipientDeliveryRecord( + snapshot.recipientDeliveryId(), + snapshot.notificationId(), + snapshot.tenantId(), + "user-1", + Optional.empty(), + Optional.empty(), + List.of(), + 0, + state, + SubmissionOutcome.AMBIGUOUS, + DeliveryOutcome.UNKNOWN, + EvidenceLevel.PLATFORM_QUEUED, + false, + false, + Optional.of(NOW), + Optional.empty(), + Optional.of("worker-a"), + Optional.of(NOW), + 1, + Optional.empty(), + NOW, + NOW)))); + } + + private RecipientDeliveryRecord recipient() { + return recipients.find(snapshot.recipientDeliveryId()).orElseThrow(); + } + } + private static DeliveryAttemptSnapshot snapshot() { return new DeliveryAttemptSnapshot( new DeliveryAttemptId(UUID.fromString("00000000-0000-7000-8000-000000000051")), diff --git a/src/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/ArchitecturePlugin.java b/src/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/ArchitecturePlugin.java index 2b6ab50c..8027a8f6 100644 --- a/src/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/ArchitecturePlugin.java +++ b/src/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/ArchitecturePlugin.java @@ -4,6 +4,7 @@ import dev.caskeleton.buildlogic.ModuleRegistry; import java.io.File; import java.io.IOException; import java.io.UncheckedIOException; +import java.nio.file.Path; import java.util.ArrayList; import java.util.HashSet; import java.util.LinkedHashMap; @@ -17,6 +18,8 @@ import org.gradle.api.artifacts.Configuration; import org.gradle.api.artifacts.ProjectDependency; import org.gradle.api.artifacts.result.ResolvedComponentResult; import org.gradle.api.provider.Provider; +import org.gradle.api.tasks.SourceSet; +import org.gradle.api.tasks.SourceSetContainer; public final class ArchitecturePlugin implements Plugin { private static final List PRODUCTION_DECLARATIONS = @@ -190,18 +193,25 @@ public final class ArchitecturePlugin implements Plugin { } purity.configure(task -> task.dependsOn(purityTaskPaths)); + // Every source set of every project — testFixtures, integrationTest, systemTest and + // the sample included — because a file Git drops is lost whichever lane owns it. + // Directories under a build directory are generated and never committed. List sourceRoots = new ArrayList<>(); - root.getSubprojects().stream() - .filter(sub -> !sub.getPath().equals(":sample-portfolio")) - .forEach( - sub -> { - for (String relative : List.of("src/main/java", "src/test/java")) { - File sourceRoot = sub.file(relative); - if (sourceRoot.isDirectory()) { - sourceRoots.add(sourceRoot); - } - } - }); + for (Project sub : root.getSubprojects()) { + SourceSetContainer sourceSets = + sub.getExtensions().findByType(SourceSetContainer.class); + if (sourceSets == null) { + continue; + } + Path buildDirectory = sub.getLayout().getBuildDirectory().get().getAsFile().toPath(); + for (SourceSet sourceSet : sourceSets) { + for (File sourceRoot : sourceSet.getJava().getSrcDirs()) { + if (!sourceRoot.toPath().startsWith(buildDirectory)) { + sourceRoots.add(sourceRoot); + } + } + } + } ignoredSources.configure(task -> task.getSourceRoots().from(sourceRoots)); }); diff --git a/src/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/GitCommandResult.java b/src/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/GitCommandResult.java deleted file mode 100644 index 1a262e2a..00000000 --- a/src/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/GitCommandResult.java +++ /dev/null @@ -1,3 +0,0 @@ -package dev.caskeleton.buildlogic.architecture; - -record GitCommandResult(String output, int exitCode) {} diff --git a/src/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/VerifyNoIgnoredSourcePackagesTask.java b/src/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/VerifyNoIgnoredSourcePackagesTask.java index 32402ed3..ecbc1a4d 100644 --- a/src/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/VerifyNoIgnoredSourcePackagesTask.java +++ b/src/build-logic/src/main/java/dev/caskeleton/buildlogic/architecture/VerifyNoIgnoredSourcePackagesTask.java @@ -67,17 +67,12 @@ public abstract class VerifyNoIgnoredSourcePackagesTask extends DefaultTask { "verifyNoIgnoredSourcePackages: found no Java sources at all; the gate would pass vacuously."); } - GitCommandResult rootResult = runGit(List.of("git", "rev-parse", "--show-toplevel"), null); - String repositoryRoot = rootResult == null ? "" : rootResult.output().trim(); - if (repositoryRoot.isEmpty()) { + File repositoryRoot = checkoutRoot(getBuildRoot().get().getAsFile()); + if (repositoryRoot == null) { getLogger().lifecycle("verifyNoIgnoredSourcePackages: not a Git checkout; naming rule only."); } else { String stdin = sourceFiles.stream().map(File::getPath).collect(java.util.stream.Collectors.joining("\n")); - GitCommandResult ignored = - runGit( - List.of("git", "-C", repositoryRoot, "check-ignore", "--no-index", "-v", "--stdin"), - stdin); - String output = ignored == null ? "" : ignored.output(); + String output = checkIgnore(repositoryRoot, stdin); for (String line : output.lines().filter(value -> !value.isBlank()).toList()) { String[] parts = line.split("\\t", -1); String rule = parts.length > 1 ? parts[0] : "(unknown rule)"; @@ -99,24 +94,61 @@ public abstract class VerifyNoIgnoredSourcePackagesTask extends DefaultTask { sourceFiles.size()); } - private GitCommandResult runGit(List command, String stdin) { - try { - Process process = - new ProcessBuilder(command) - .directory(getBuildRoot().get().getAsFile()) - .redirectErrorStream(false) - .start(); - if (stdin != null) { - process.getOutputStream().write(stdin.getBytes(StandardCharsets.UTF_8)); + /** + * The nearest directory at or above {@code start} holding {@code .git} (a directory, or the file + * a worktree has), or {@code null} for an exported source tree. Decided on the file system rather + * than by asking Git, so that Git failing inside a checkout cannot read as "not a checkout". + */ + private static File checkoutRoot(File start) { + for (File directory = start.getAbsoluteFile(); directory != null; directory = directory.getParentFile()) { + if (new File(directory, ".git").exists()) { + return directory; } - process.getOutputStream().close(); - String output = new String(process.getInputStream().readAllBytes(), StandardCharsets.UTF_8); - process.getErrorStream().readAllBytes(); - int exitCode = process.waitFor(); - return new GitCommandResult(output, exitCode); + } + return null; + } + + /** + * Git's ignore verdicts for the paths on {@code stdin}. Fails closed: inside a checkout, a git that + * cannot run or exits with anything but 0 (some path ignored) or 1 (none ignored) is an error, not + * an empty answer — an empty answer is how the gate used to pass without asking. + */ + private String checkIgnore(File repositoryRoot, String stdin) { + List command = + List.of("git", "-C", repositoryRoot.getPath(), "check-ignore", "--no-index", "-v", "--stdin"); + Process process; + try { + process = new ProcessBuilder(command).start(); } catch (IOException unavailable) { - getLogger().info("verifyNoIgnoredSourcePackages: git unavailable ({})", unavailable.getMessage()); - return null; + throw new GradleException( + "verifyNoIgnoredSourcePackages: " + + repositoryRoot + + " is a Git checkout but git could not run: " + + unavailable.getMessage(), + unavailable); + } + try { + try (var input = process.getOutputStream()) { + input.write(stdin.getBytes(StandardCharsets.UTF_8)); + } catch (IOException exitedEarly) { + // git stopped reading, which it does when it fails; its exit code below says why. + } + String output = new String(process.getInputStream().readAllBytes(), StandardCharsets.UTF_8); + String error = new String(process.getErrorStream().readAllBytes(), StandardCharsets.UTF_8); + int exitCode = process.waitFor(); + if (exitCode != 0 && exitCode != 1) { + throw new GradleException( + "verifyNoIgnoredSourcePackages: `git check-ignore` exited " + + exitCode + + " inside the Git checkout at " + + repositoryRoot + + ": " + + error.strip()); + } + return output; + } catch (IOException unreadable) { + throw new GradleException( + "verifyNoIgnoredSourcePackages: could not read `git check-ignore` output", unreadable); } catch (InterruptedException interrupted) { Thread.currentThread().interrupt(); throw new GradleException("verifyNoIgnoredSourcePackages: git command interrupted", interrupted); diff --git a/src/build-logic/src/main/java/dev/caskeleton/buildlogic/quality/QualityConventionsPlugin.java b/src/build-logic/src/main/java/dev/caskeleton/buildlogic/quality/QualityConventionsPlugin.java index f01e3736..2c6cbaf8 100644 --- a/src/build-logic/src/main/java/dev/caskeleton/buildlogic/quality/QualityConventionsPlugin.java +++ b/src/build-logic/src/main/java/dev/caskeleton/buildlogic/quality/QualityConventionsPlugin.java @@ -72,6 +72,18 @@ public final class QualityConventionsPlugin implements Plugin { .configure( task -> { task.getAuxClassPaths().from(main.getRuntimeClasspath().minus(main.getOutput())); + // The SpotBugs Gradle plugin rewrites this file without truncating it. A classpath + // shorter than the previous run's (the version drops from `0.0.1+` to + // `0.0.1-SNAPSHOT` once the tree is dirty) keeps the old tail, the last entry reads + // `...-SNAPSHOT.jar.jar`, and SpotBugs reports its classes as missing. + File auxClasspathFile = + project + .getLayout() + .getBuildDirectory() + .file("spotbugs/auxclasspath/" + task.getName()) + .get() + .getAsFile(); + task.doFirst(ignored -> auxClasspathFile.delete()); SpotBugsReport xml = task.getReports().maybeCreate("xml"); xml.getRequired().set(true); task.doLast( diff --git a/src/build-logic/src/test/java/dev/caskeleton/buildlogic/architecture/VerifyNoIgnoredSourcePackagesFunctionalTest.java b/src/build-logic/src/test/java/dev/caskeleton/buildlogic/architecture/VerifyNoIgnoredSourcePackagesFunctionalTest.java new file mode 100644 index 00000000..c81c00bd --- /dev/null +++ b/src/build-logic/src/test/java/dev/caskeleton/buildlogic/architecture/VerifyNoIgnoredSourcePackagesFunctionalTest.java @@ -0,0 +1,122 @@ +package dev.caskeleton.buildlogic.architecture; + +import static java.nio.charset.StandardCharsets.UTF_8; +import static org.assertj.core.api.Assertions.assertThat; + +import java.io.IOException; +import java.nio.file.Files; +import java.nio.file.Path; +import org.gradle.testkit.runner.BuildResult; +import org.gradle.testkit.runner.GradleRunner; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; + +class VerifyNoIgnoredSourcePackagesFunctionalTest { + + @Test + void sourceInAnIgnoredPackageOfAnAuxiliarySourceSetFailsTheGate(@TempDir Path temporaryRoot) + throws IOException { + // given + Path project = fixture(temporaryRoot, "a"); + source(project, "a/src/main/java/example/Ok.java"); + source(project, "a/src/integrationTest/java/example/bin/Ignored.java"); + + // when + BuildResult result = runner(project).buildAndFail(); + + // then + assertThat(result.getOutput()) + .contains("Ignored.java: package segment 'bin' collides with a build output directory name"); + } + + @Test + void sourceInAnIgnoredPackageOfTheSamplePortfolioFailsTheGate(@TempDir Path temporaryRoot) + throws IOException { + // given + Path project = fixture(temporaryRoot, "sample-portfolio"); + source(project, "sample-portfolio/src/main/java/example/Ok.java"); + source(project, "sample-portfolio/src/main/java/example/build/Ignored.java"); + + // when + BuildResult result = runner(project).buildAndFail(); + + // then + assertThat(result.getOutput()) + .contains( + "Ignored.java: package segment 'build' collides with a build output directory name"); + } + + @Test + void gitFailingInsideACheckoutFailsTheGateInsteadOfPassing(@TempDir Path temporaryRoot) + throws IOException { + // given + Path project = fixture(temporaryRoot, "a"); + source(project, "a/src/main/java/example/Ok.java"); + Files.writeString( + project.getParent().resolve(".git"), + "gitdir: " + temporaryRoot.resolve("missing-git-dir") + "\n", + UTF_8); + + // when + BuildResult result = runner(project).buildAndFail(); + + // then + assertThat(result.getOutput()) + .contains("verifyNoIgnoredSourcePackages: `git check-ignore` exited 128"); + } + + /** One registered leaf with an extra {@code integrationTest} source set, under {@code src/}. */ + private static Path fixture(Path temporaryRoot, String leaf) throws IOException { + Path project = temporaryRoot.resolve("repository").resolve("src"); + Files.createDirectories(project.resolve("config/architecture")); + Files.createDirectories(project.resolve(leaf)); + Files.writeString( + project.resolve("settings.gradle"), + """ + rootProject.name = 'main' + include '%s' + """ + .formatted(leaf), + UTF_8); + Files.writeString( + project.resolve("build.gradle"), + """ + plugins { id 'ca.architecture' } + subprojects { + apply plugin: 'java-library' + sourceSets { integrationTest } + } + """, + UTF_8); + Files.writeString( + project.resolve("config/architecture/modules.json"), + """ + { + "modules": [ + { + "id": "%1$s", + "gradle_path": ":%1$s", + "source_path": "src/%1$s", + "allowed_dependencies": [] + } + ] + } + """ + .formatted(leaf), + UTF_8); + return project; + } + + private static void source(Path project, String relativePath) throws IOException { + Path file = project.resolve(relativePath); + Files.createDirectories(file.getParent()); + Files.writeString(file, "package example;\n", UTF_8); + } + + private static GradleRunner runner(Path project) { + return GradleRunner.create() + .withProjectDir(project.toFile()) + .withPluginClasspath() + .withArguments("--console=plain", "--stacktrace", "verifyNoIgnoredSourcePackages"); + } +} diff --git a/src/composition/fileserver-platform/README.md b/src/composition/fileserver-platform/README.md index 1374354b..8a11fba0 100644 --- a/src/composition/fileserver-platform/README.md +++ b/src/composition/fileserver-platform/README.md @@ -24,7 +24,8 @@ composition:fileserver-platform - 설정: `config/module-defaults/fileserver.yml`을 support의 `ModuleDefaultsEnvironmentPostProcessor`가 읽는다. 우선순위가 가장 낮아서 `application*.yml`, 환경 변수, 시스템 속성이 항상 이긴다. servlet multipart 상한(`spring.servlet.multipart.*`)도 같은 placeholder로 이 파일이 준다. app-bootstrap은 이 파일을 모른다. -- 저장소: 메타데이터 테이블은 JPA(`adapter:outbound:persistence-jpa`)가 있어야 한다. +- 저장소: 메타데이터 테이블은 관계형 DB에 있다. 이 모듈이 `adapter:outbound:persistence-jpa`를 + `runtimeOnly`로 함께 가져오므로 JPA 줄을 따로 추가하지 않아도 된다. DB 접속 env 키는 필요하다. ## 추가할 한 줄 diff --git a/src/composition/fileserver-platform/build.gradle b/src/composition/fileserver-platform/build.gradle index eedfe4f6..be1f23d8 100644 --- a/src/composition/fileserver-platform/build.gradle +++ b/src/composition/fileserver-platform/build.gradle @@ -30,6 +30,12 @@ dependencies { implementation project(':adapter:inbound:web') implementation project(':adapter:outbound:fileserver') implementation project(':adapter:outbound:persistence-fileserver') + // The relational platform the metadata tables live in: DataSource, Flyway core stream, + // capability schema registry and the TransactionPort every fileserver service needs. Without + // it, a service that picked this one line got Boot's relational auto-configuration with nothing + // behind it and failed to start with an unrelated-looking DataSource or missing-bean error. + // Runtime only: nothing here compiles against it. One line selects the whole capability. + runtimeOnly project(':adapter:outbound:persistence-jpa') implementation project(':adapter:outbound:support') implementation 'org.springframework.boot:spring-boot-autoconfigure' diff --git a/src/composition/fileserver-platform/gradle.lockfile b/src/composition/fileserver-platform/gradle.lockfile index e8b26147..a7482a79 100644 --- a/src/composition/fileserver-platform/gradle.lockfile +++ b/src/composition/fileserver-platform/gradle.lockfile @@ -35,6 +35,7 @@ com.google.guava:guava:33.6.0-jre=checkstyle com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=annotationProcessor,checkstyle,testAnnotationProcessor com.google.j2objc:j2objc-annotations:3.1=annotationProcessor,checkstyle,testAnnotationProcessor com.google.protobuf:protobuf-java:4.33.2=annotationProcessor,testAnnotationProcessor +com.h2database:h2:2.4.240=runtimeClasspath,testRuntimeClasspath com.h3xstream.findsecbugs:findsecbugs-plugin:1.14.0=spotbugsPlugins com.jayway.jsonpath:json-path:2.10.0=testCompileClasspath,testRuntimeClasspath com.nimbusds:nimbus-jose-jwt:10.4=runtimeClasspath,testRuntimeClasspath @@ -58,6 +59,7 @@ io.micrometer:micrometer-commons:1.16.7=compileClasspath,runtimeClasspath,testCo io.micrometer:micrometer-core:1.16.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath io.micrometer:micrometer-jakarta9:1.16.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath io.micrometer:micrometer-observation:1.16.7=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath +io.projectreactor:reactor-core:3.8.7=runtimeClasspath,testRuntimeClasspath io.swagger.core.v3:swagger-annotations-jakarta:2.2.38=runtimeClasspath,testRuntimeClasspath io.swagger.core.v3:swagger-core-jakarta:2.2.38=runtimeClasspath,testRuntimeClasspath io.swagger.core.v3:swagger-models-jakarta:2.2.38=runtimeClasspath,testRuntimeClasspath @@ -98,12 +100,15 @@ org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath org.aspectj:aspectjweaver:1.9.25.1=runtimeClasspath,testRuntimeClasspath org.assertj:assertj-core:3.27.7=testCompileClasspath,testRuntimeClasspath org.awaitility:awaitility:4.3.0=testCompileClasspath,testRuntimeClasspath +org.checkerframework:checker-qual:3.55.1=runtimeClasspath,testRuntimeClasspath org.codehaus.plexus:plexus-classworlds:2.6.0=checkstyle org.codehaus.plexus:plexus-component-annotations:2.1.0=checkstyle org.codehaus.plexus:plexus-container-default:2.1.0=checkstyle org.codehaus.plexus:plexus-utils:3.3.0=checkstyle org.dom4j:dom4j:2.2.0=spotbugs org.eclipse.angus:angus-activation:2.0.3=runtimeClasspath,testRuntimeClasspath +org.flywaydb:flyway-core:11.14.1=runtimeClasspath,testRuntimeClasspath +org.flywaydb:flyway-database-postgresql:11.14.1=runtimeClasspath,testRuntimeClasspath org.glassfish.jaxb:jaxb-core:4.0.9=runtimeClasspath,testRuntimeClasspath org.glassfish.jaxb:jaxb-runtime:4.0.9=runtimeClasspath,testRuntimeClasspath org.glassfish.jaxb:txw2:4.0.9=runtimeClasspath,testRuntimeClasspath @@ -141,6 +146,8 @@ org.ow2.asm:asm-util:9.10.1=spotbugs org.ow2.asm:asm:9.10.1=spotbugs org.ow2.asm:asm:9.7.1=testCompileClasspath,testRuntimeClasspath org.pcollections:pcollections:4.0.1=annotationProcessor,testAnnotationProcessor +org.postgresql:postgresql:42.7.13=runtimeClasspath,testRuntimeClasspath +org.reactivestreams:reactive-streams:1.0.4=runtimeClasspath,testRuntimeClasspath org.reflections:reflections:0.10.2=checkstyle org.skyscreamer:jsonassert:1.5.3=testCompileClasspath,testRuntimeClasspath org.slf4j:jul-to-slf4j:2.0.18=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath @@ -155,6 +162,7 @@ org.springframework.boot:spring-boot-autoconfigure:4.0.8=compileClasspath,runtim org.springframework.boot:spring-boot-configuration-processor:4.0.8=annotationProcessor org.springframework.boot:spring-boot-data-commons:4.0.8=runtimeClasspath,testRuntimeClasspath org.springframework.boot:spring-boot-data-jpa:4.0.8=runtimeClasspath,testRuntimeClasspath +org.springframework.boot:spring-boot-flyway:4.0.8=runtimeClasspath,testRuntimeClasspath org.springframework.boot:spring-boot-health:4.0.8=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath org.springframework.boot:spring-boot-hibernate:4.0.8=runtimeClasspath,testRuntimeClasspath org.springframework.boot:spring-boot-http-converter:4.0.8=runtimeClasspath,testCompileClasspath,testRuntimeClasspath @@ -171,6 +179,7 @@ org.springframework.boot:spring-boot-servlet:4.0.8=runtimeClasspath,testCompileC org.springframework.boot:spring-boot-sql:4.0.8=runtimeClasspath,testRuntimeClasspath org.springframework.boot:spring-boot-starter-actuator:4.0.8=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath org.springframework.boot:spring-boot-starter-data-jpa:4.0.8=runtimeClasspath,testRuntimeClasspath +org.springframework.boot:spring-boot-starter-flyway:4.0.8=runtimeClasspath,testRuntimeClasspath org.springframework.boot:spring-boot-starter-jackson-test:4.0.8=testCompileClasspath,testRuntimeClasspath org.springframework.boot:spring-boot-starter-jackson:4.0.8=runtimeClasspath,testCompileClasspath,testRuntimeClasspath org.springframework.boot:spring-boot-starter-jdbc:4.0.8=runtimeClasspath,testRuntimeClasspath @@ -197,6 +206,8 @@ org.springframework.boot:spring-boot-webmvc:4.0.8=runtimeClasspath,testCompileCl org.springframework.boot:spring-boot:4.0.8=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath org.springframework.data:spring-data-commons:4.0.7=runtimeClasspath,testRuntimeClasspath org.springframework.data:spring-data-jpa:4.0.7=runtimeClasspath,testRuntimeClasspath +org.springframework.integration:spring-integration-core:7.0.6=runtimeClasspath,testRuntimeClasspath +org.springframework.integration:spring-integration-jdbc:7.0.6=runtimeClasspath,testRuntimeClasspath org.springframework.security:spring-security-config:7.0.7=runtimeClasspath,testRuntimeClasspath org.springframework.security:spring-security-core:7.0.7=runtimeClasspath,testRuntimeClasspath org.springframework.security:spring-security-crypto:7.0.7=runtimeClasspath,testRuntimeClasspath @@ -212,6 +223,7 @@ org.springframework:spring-context:7.0.9=compileClasspath,runtimeClasspath,testC org.springframework:spring-core:7.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath org.springframework:spring-expression:7.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath org.springframework:spring-jdbc:7.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath +org.springframework:spring-messaging:7.0.9=runtimeClasspath,testRuntimeClasspath org.springframework:spring-orm:7.0.9=runtimeClasspath,testRuntimeClasspath org.springframework:spring-test:7.0.9=testCompileClasspath,testRuntimeClasspath org.springframework:spring-tx:7.0.9=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath diff --git a/src/composition/fileserver-platform/src/main/java/dev/caskeleton/composition/fileserver/FileserverCleanupConfiguration.java b/src/composition/fileserver-platform/src/main/java/dev/caskeleton/composition/fileserver/FileserverCleanupConfiguration.java index 84717fa6..cc150ef7 100644 --- a/src/composition/fileserver-platform/src/main/java/dev/caskeleton/composition/fileserver/FileserverCleanupConfiguration.java +++ b/src/composition/fileserver-platform/src/main/java/dev/caskeleton/composition/fileserver/FileserverCleanupConfiguration.java @@ -2,6 +2,7 @@ package dev.caskeleton.composition.fileserver; import dev.caskeleton.adapter.outbound.fileserver.platform.autoconfigure.FileserverPlatformSettings; import dev.caskeleton.application.fileserver.cleanup.CleanupService; +import dev.caskeleton.application.fileserver.recovery.FileReconciliationService; import java.time.Duration; import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; @@ -29,9 +30,14 @@ public class FileserverCleanupConfiguration { @Bean @ConditionalOnMissingBean FileserverCleanupWorker fileserverCleanupWorker( - CleanupService cleanupService, FileserverPlatformSettings settings) { + CleanupService cleanupService, + FileReconciliationService reconciliationService, + FileserverPlatformSettings settings) { return new FileserverCleanupWorker( - cleanupService, settings.cleanup().maxItems(), settings.cleanup().maxBytes().toBytes()); + cleanupService, + reconciliationService, + settings.cleanup().maxItems(), + settings.cleanup().maxBytes().toBytes()); } /** diff --git a/src/composition/fileserver-platform/src/main/java/dev/caskeleton/composition/fileserver/FileserverCleanupWorker.java b/src/composition/fileserver-platform/src/main/java/dev/caskeleton/composition/fileserver/FileserverCleanupWorker.java index 3a6eace5..60de461b 100644 --- a/src/composition/fileserver-platform/src/main/java/dev/caskeleton/composition/fileserver/FileserverCleanupWorker.java +++ b/src/composition/fileserver-platform/src/main/java/dev/caskeleton/composition/fileserver/FileserverCleanupWorker.java @@ -4,6 +4,9 @@ import static net.logstash.logback.argument.StructuredArguments.kv; import dev.caskeleton.application.fileserver.cleanup.CleanupBatchResult; import dev.caskeleton.application.fileserver.cleanup.CleanupService; +import dev.caskeleton.application.fileserver.recovery.FileReconciliationService; +import dev.caskeleton.application.fileserver.recovery.ReconciliationResult; +import java.util.List; import org.slf4j.Logger; import org.slf4j.LoggerFactory; @@ -31,19 +34,59 @@ public class FileserverCleanupWorker { private static final Logger LOG = LoggerFactory.getLogger(FileserverCleanupWorker.class); private final CleanupService cleanupService; + private final FileReconciliationService reconciliationService; private final int maxItems; private final long maxBytes; - public FileserverCleanupWorker(CleanupService cleanupService, int maxItems, long maxBytes) { + public FileserverCleanupWorker( + CleanupService cleanupService, + FileReconciliationService reconciliationService, + int maxItems, + long maxBytes) { if (maxItems < 1 || maxBytes < 1) { throw new IllegalArgumentException("cleanup batch bounds must be positive"); } this.cleanupService = cleanupService; + this.reconciliationService = reconciliationService; this.maxItems = maxItems; this.maxBytes = maxBytes; } + /** + * One unattended pass: reclaim what is queued, then settle what was left ambiguous. + * + *

    The reconciliation step is what makes an ambiguous publish or an unconfirmed READY commit + * resolve without an operator; nothing else ever called it. The two steps fail independently, so + * a broken queue does not also stop reconciliation. + */ public void runBatch() { + runCleanup(); + runReconciliation(); + } + + private void runReconciliation() { + try { + List results = reconciliationService.reconcileRecoverable(maxItems); + if (!results.isEmpty()) { + LOG.info( + "fileserver.reconcile examined={}", + results.size(), + kv("capability", "fileserver"), + kv("operation", "reconcile"), + kv("reconcile.examined", results.size())); + } + } catch (RuntimeException failure) { + LOG.warn( + "fileserver.reconcile pass failed; the next run looks again", + kv("capability", "fileserver"), + kv("operation", "reconcile"), + kv("warning.kind", "scheduled-task-failed"), + kv("retry.disposition", "next-run"), + failure); + } + } + + private void runCleanup() { try { CleanupBatchResult result = cleanupService.runBatch(maxItems, maxBytes); if (result.deleted() > 0 || result.failed() > 0) { diff --git a/src/composition/fileserver-platform/src/main/resources/config/module-defaults/fileserver.yml b/src/composition/fileserver-platform/src/main/resources/config/module-defaults/fileserver.yml index 58b796c4..ea3a8eeb 100644 --- a/src/composition/fileserver-platform/src/main/resources/config/module-defaults/fileserver.yml +++ b/src/composition/fileserver-platform/src/main/resources/config/module-defaults/fileserver.yml @@ -99,3 +99,11 @@ app: # Secret. Keyed HMAC over file identifiers; an unkeyed digest of an enumerable id is # reversible, so startup fails while metrics are on and this is blank. fingerprint-key: ${APP_FILESERVER_PLATFORM_OBSERVABILITY_FINGERPRINT_KEY:} + +# /actuator/info 에 싣는 이 모듈의 상태(management.info.env). compose smoke 가 lane 이 실제로 켠 +# capability 를 이 값으로 확인한다. 위 스위치를 해석한 값이고, 기본값은 +# FileserverPlatformAutoConfiguration 의 matchIfMissing 과 같다. +info: + capabilities: + fileserver: + enabled: ${app.fileserver-platform.enabled:true} diff --git a/src/composition/fileserver-platform/src/test/java/dev/caskeleton/composition/fileserver/FileserverCleanupWorkerTest.java b/src/composition/fileserver-platform/src/test/java/dev/caskeleton/composition/fileserver/FileserverCleanupWorkerTest.java new file mode 100644 index 00000000..bfa8c7b4 --- /dev/null +++ b/src/composition/fileserver-platform/src/test/java/dev/caskeleton/composition/fileserver/FileserverCleanupWorkerTest.java @@ -0,0 +1,64 @@ +package dev.caskeleton.composition.fileserver; + +import static org.assertj.core.api.Assertions.assertThat; + +import dev.caskeleton.application.fileserver.api.FileId; +import dev.caskeleton.application.fileserver.cleanup.CleanupBatchResult; +import dev.caskeleton.application.fileserver.recovery.FileReconciliationService; +import dev.caskeleton.application.fileserver.recovery.ReconciliationResult; +import java.util.ArrayList; +import java.util.List; +import org.junit.jupiter.api.Test; + +class FileserverCleanupWorkerTest { + + private final List reconciled = new ArrayList<>(); + + private final FileReconciliationService reconciliation = + new FileReconciliationService() { + @Override + public ReconciliationResult reconcile(FileId fileId) { + throw new UnsupportedOperationException("the worker reconciles in batches only"); + } + + @Override + public List reconcileRecoverable(int limit) { + reconciled.add(limit); + return List.of(); + } + }; + + /** Nothing else ever called the reconciler, so an ambiguous publish stayed ambiguous for good. */ + @Test + void aRunReconcilesTheFilesWhoseOutcomeWasLeftOpen() { + // given + FileserverCleanupWorker worker = + new FileserverCleanupWorker( + (maxItems, maxBytes) -> CleanupBatchResult.empty(), reconciliation, 25, 1024); + + // when + worker.runBatch(); + + // then + assertThat(reconciled).containsExactly(25); + } + + @Test + void aFailingCleanupBatchStillLetsReconciliationRun() { + // given + FileserverCleanupWorker worker = + new FileserverCleanupWorker( + (maxItems, maxBytes) -> { + throw new IllegalStateException("cleanup queue unavailable"); + }, + reconciliation, + 25, + 1024); + + // when + worker.runBatch(); + + // then + assertThat(reconciled).containsExactly(25); + } +} diff --git a/src/composition/fileserver-platform/src/test/java/dev/caskeleton/composition/fileserver/FileserverStructuredLoggingTest.java b/src/composition/fileserver-platform/src/test/java/dev/caskeleton/composition/fileserver/FileserverStructuredLoggingTest.java index e602d1a7..8fbee711 100644 --- a/src/composition/fileserver-platform/src/test/java/dev/caskeleton/composition/fileserver/FileserverStructuredLoggingTest.java +++ b/src/composition/fileserver-platform/src/test/java/dev/caskeleton/composition/fileserver/FileserverStructuredLoggingTest.java @@ -7,9 +7,13 @@ import ch.qos.logback.classic.Logger; import ch.qos.logback.classic.LoggerContext; import ch.qos.logback.classic.spi.ILoggingEvent; import ch.qos.logback.core.read.ListAppender; +import dev.caskeleton.application.fileserver.api.FileId; import dev.caskeleton.application.fileserver.cleanup.CleanupBatchResult; import dev.caskeleton.application.fileserver.cleanup.CleanupService; +import dev.caskeleton.application.fileserver.recovery.FileReconciliationService; +import dev.caskeleton.application.fileserver.recovery.ReconciliationResult; import java.util.Arrays; +import java.util.List; import java.util.stream.Collectors; import org.junit.jupiter.api.Test; import org.slf4j.LoggerFactory; @@ -24,12 +28,26 @@ import org.slf4j.LoggerFactory; */ class FileserverStructuredLoggingTest { + /** Reconciliation that finds nothing, so the only event is the cleanup batch's own. */ + private static final FileReconciliationService NOTHING_TO_RECONCILE = + new FileReconciliationService() { + @Override + public ReconciliationResult reconcile(FileId fileId) { + throw new UnsupportedOperationException("the worker reconciles in batches only"); + } + + @Override + public List reconcileRecoverable(int limit) { + return List.of(); + } + }; + @Test void fileserverCleanupSuccessCarriesBoundedOutcomeFields() { CleanupService cleanup = (maxItems, maxBytes) -> new CleanupBatchResult(1, 2, 3, 4, 5L); try (CapturedLogger captured = capture(FileserverCleanupWorker.class)) { - new FileserverCleanupWorker(cleanup, 10, 1_024L).runBatch(); + new FileserverCleanupWorker(cleanup, NOTHING_TO_RECONCILE, 10, 1_024L).runBatch(); ILoggingEvent event = captured.singleEvent(); assertThat(event.getLevel()).isEqualTo(Level.INFO); @@ -51,7 +69,7 @@ class FileserverStructuredLoggingTest { }; try (CapturedLogger captured = capture(FileserverCleanupWorker.class)) { - new FileserverCleanupWorker(cleanup, 10, 1_024L).runBatch(); + new FileserverCleanupWorker(cleanup, NOTHING_TO_RECONCILE, 10, 1_024L).runBatch(); ILoggingEvent event = captured.singleEvent(); assertThat(event.getLevel()).isEqualTo(Level.WARN); diff --git a/src/composition/notification-platform/src/main/resources/config/module-defaults/notification.yml b/src/composition/notification-platform/src/main/resources/config/module-defaults/notification.yml index 15b9310e..9fd05a9f 100644 --- a/src/composition/notification-platform/src/main/resources/config/module-defaults/notification.yml +++ b/src/composition/notification-platform/src/main/resources/config/module-defaults/notification.yml @@ -11,6 +11,15 @@ # docs/notification/configuration-reference.md. Off (APP_NOTIFICATION_PLATFORM_ENABLED=false) means # no provider runtime, schema activation check, scheduler thread, notification secret or Spring Boot # mail auto-configuration is required. + +# /actuator/info 에 싣는 이 모듈의 상태(management.info.env). compose smoke 가 lane 이 실제로 켠 +# capability 를 이 값으로 확인한다. 아래 스위치를 해석한 값이고, 기본값은 +# NotificationPlatformAutoConfiguration 의 matchIfMissing 과 같다. +info: + capabilities: + notification: + enabled: ${ca-skeleton.notification.platform.enabled:true} + ca-skeleton: notification: platform: diff --git a/src/config/architecture/modules.json b/src/config/architecture/modules.json index ae03e234..2d7929a8 100644 --- a/src/config/architecture/modules.json +++ b/src/config/architecture/modules.json @@ -269,6 +269,7 @@ "adapter-outbound-identifier", "adapter-outbound-support", "adapter-outbound-persistence-fileserver", + "adapter-outbound-persistence-jpa", "adapter-inbound-web-fileserver", "adapter-inbound-web" ] diff --git a/src/config/runtime/compose-profile-contracts.json b/src/config/runtime/compose-profile-contracts.json index 0500feb6..0e8afde8 100644 --- a/src/config/runtime/compose-profile-contracts.json +++ b/src/config/runtime/compose-profile-contracts.json @@ -40,7 +40,7 @@ "oneShotServices": [], "blocking": true, "activationEnv": {}, - "expectedSwitchesOn": [], + "expectedCapabilitiesOn": [], "expectedPersistenceVendor": "none" }, { @@ -60,7 +60,7 @@ "oneShotServices": [], "blocking": true, "activationEnv": {}, - "expectedSwitchesOn": [], + "expectedCapabilitiesOn": [], "expectedPersistenceVendor": "none" }, { @@ -80,7 +80,7 @@ "oneShotServices": [], "blocking": true, "activationEnv": {}, - "expectedSwitchesOn": [], + "expectedCapabilitiesOn": [], "expectedPersistenceVendor": "none" }, { @@ -109,8 +109,8 @@ "APP_DATASOURCE_DDL_AUTO": "validate", "APP_FLYWAY_ENABLED": "true" }, - "expectedSwitchesOn": [ - "ca-skeleton.persistence-jpa.enabled" + "expectedCapabilitiesOn": [ + "persistence-jpa" ], "expectedPersistenceVendor": "postgresql" }, @@ -142,8 +142,8 @@ "APP_PERSISTENCE_MONGO_ACTIVE_PROFILE": "primary", "SPRING_MONGODB_URI": "mongodb://mongo:27017/ca_skeleton?replicaSet=rs0" }, - "expectedSwitchesOn": [ - "ca-skeleton.persistence-mongo.enabled" + "expectedCapabilitiesOn": [ + "persistence-mongo" ], "expectedPersistenceVendor": "none" }, @@ -169,11 +169,10 @@ "activationEnv": { "APP_MESSAGING_ENABLED": "true", "APP_MESSAGING_BROKER": "kafka", - "SPRING_KAFKA_BOOTSTRAP_SERVERS": "kafka:9092", "APP_MESSAGING_KAFKA_BROKERS": "kafka:9092" }, - "expectedSwitchesOn": [ - "app.messaging.enabled" + "expectedCapabilitiesOn": [ + "messaging" ], "expectedPersistenceVendor": "none" }, @@ -201,7 +200,6 @@ "activationEnv": { "APP_MESSAGING_ENABLED": "true", "APP_MESSAGING_BROKER": "kafka", - "SPRING_KAFKA_BOOTSTRAP_SERVERS": "kafka:9092", "APP_PERSISTENCE_JPA_ENABLED": "true", "APP_OUTBOX_ENABLED": "true", "APP_OUTBOX_RELAY_ENABLED": "true", @@ -211,9 +209,9 @@ "APP_FLYWAY_ENABLED": "true", "APP_MESSAGING_KAFKA_BROKERS": "kafka:9092" }, - "expectedSwitchesOn": [ - "app.messaging.enabled", - "ca-skeleton.persistence-jpa.enabled" + "expectedCapabilitiesOn": [ + "messaging", + "persistence-jpa" ], "expectedPersistenceVendor": "postgresql" }, @@ -260,9 +258,9 @@ "APP_DATASOURCE_DDL_AUTO": "validate", "APP_FLYWAY_ENABLED": "true" }, - "expectedSwitchesOn": [ - "ca-skeleton.notification.platform.enabled", - "ca-skeleton.persistence-jpa.enabled" + "expectedCapabilitiesOn": [ + "notification", + "persistence-jpa" ], "expectedPersistenceVendor": "postgresql" }, @@ -318,9 +316,9 @@ "APP_NOTIFICATION_PLATFORM_SMTP_ENABLED": "true", "APP_NOTIFICATION_PLATFORM_SMTP_SENDER_IDENTITY": "no-reply@lane.test" }, - "expectedSwitchesOn": [ - "ca-skeleton.notification.platform.enabled", - "ca-skeleton.persistence-jpa.enabled" + "expectedCapabilitiesOn": [ + "notification", + "persistence-jpa" ], "expectedPersistenceVendor": "postgresql" }, @@ -384,9 +382,9 @@ "APP_NOTIFICATION_PLATFORM_SMTP_ENABLED": "true", "APP_NOTIFICATION_PLATFORM_SMTP_SENDER_IDENTITY": "no-reply@lane.test" }, - "expectedSwitchesOn": [ - "ca-skeleton.notification.platform.enabled", - "ca-skeleton.persistence-jpa.enabled" + "expectedCapabilitiesOn": [ + "notification", + "persistence-jpa" ], "expectedPersistenceVendor": "postgresql" }, @@ -418,8 +416,8 @@ "APP_GRAPHQL_ENABLED": "true", "APP_GRAPHQL_DEPLOYMENT_MODE": "LOCAL" }, - "expectedSwitchesOn": [ - "backend.graphql.enabled" + "expectedCapabilitiesOn": [ + "graphql" ], "expectedPersistenceVendor": "none" }, @@ -447,8 +445,8 @@ "APP_REDIS_NODES": "redis:6379", "APP_REDIS_AUTHENTICATION_ANONYMOUS_ACCESS_ACCEPTED": "true" }, - "expectedSwitchesOn": [ - "app.redis.enabled" + "expectedCapabilitiesOn": [ + "redis" ], "expectedPersistenceVendor": "none" }, @@ -474,8 +472,8 @@ "APP_FILESERVER_PLATFORM_SECURITY_ACCESS_POLICY": "role-based", "APP_FILESERVER_PLATFORM_OBSERVABILITY_FINGERPRINT_KEY": "compose-contract-fileserver-key-32" }, - "expectedSwitchesOn": [ - "app.fileserver-platform.enabled" + "expectedCapabilitiesOn": [ + "fileserver" ], "expectedPersistenceVendor": "none" }, @@ -505,8 +503,8 @@ "APP_HTTPCLIENT_CLIENTS_0_TLS_PROFILE_ID": "local-app", "APP_HTTPCLIENT_CLIENTS_0_TLS_ALLOW_PLAIN_HTTP": "true" }, - "expectedSwitchesOn": [ - "app.httpclient.enabled" + "expectedCapabilitiesOn": [ + "httpclient" ], "expectedPersistenceVendor": "none" }, @@ -547,8 +545,8 @@ "APP_DATASOURCE_DDL_AUTO": "validate", "APP_FLYWAY_ENABLED": "true" }, - "expectedSwitchesOn": [ - "ca-skeleton.persistence-jpa.enabled" + "expectedCapabilitiesOn": [ + "persistence-jpa" ], "expectedPersistenceVendor": "postgresql" }, @@ -589,8 +587,8 @@ "APP_DATASOURCE_DDL_AUTO": "validate", "APP_FLYWAY_ENABLED": "true" }, - "expectedSwitchesOn": [ - "ca-skeleton.persistence-jpa.enabled" + "expectedCapabilitiesOn": [ + "persistence-jpa" ], "expectedPersistenceVendor": "postgresql" }, @@ -632,8 +630,8 @@ "APP_DATASOURCE_DDL_AUTO": "validate", "APP_FLYWAY_ENABLED": "true" }, - "expectedSwitchesOn": [ - "ca-skeleton.persistence-jpa.enabled" + "expectedCapabilitiesOn": [ + "persistence-jpa" ], "expectedPersistenceVendor": "postgresql" }, @@ -692,7 +690,6 @@ "SPRING_MONGODB_URI": "mongodb://mongo:27017/ca_skeleton?replicaSet=rs0", "APP_MESSAGING_ENABLED": "true", "APP_MESSAGING_BROKER": "kafka", - "SPRING_KAFKA_BOOTSTRAP_SERVERS": "kafka:9092", "APP_NOTIFICATION_PLATFORM_ENABLED": "true", "APP_NOTIFICATION_PLATFORM_MODE": "SERVING", "APP_GRAPHQL_ENABLED": "true", @@ -725,20 +722,30 @@ "APP_HTTPCLIENT_CLIENTS_0_TLS_PROFILE_ID": "local-app", "APP_HTTPCLIENT_CLIENTS_0_TLS_ALLOW_PLAIN_HTTP": "true" }, - "expectedSwitchesOn": [ - "app.fileserver-platform.enabled", - "app.httpclient.enabled", - "app.messaging.enabled", - "app.redis.enabled", - "backend.graphql.enabled", - "ca-skeleton.notification.platform.enabled", - "ca-skeleton.persistence-jpa.enabled", - "ca-skeleton.persistence-mongo.enabled" + "expectedCapabilitiesOn": [ + "fileserver", + "graphql", + "httpclient", + "messaging", + "notification", + "persistence-jpa", + "persistence-mongo", + "redis" ], "expectedPersistenceVendor": "postgresql" } ], - "$activationComment": "activationEnv is what the lane injects; expectedSwitchesOn is what the application must then report. Both are needed: a lane named local-jpa that ran with JPA off would render the right services, start cleanly, and prove nothing at all. Redis, the HTTP Fileserver platform and the HTTP client platform are shipped in app-bootstrap and therefore have dedicated blocking lanes. Object storage, WebSocket and gRPC are build-time optional and are qualified by their dedicated workflows instead of being falsely reported as members of this bootJar.", - "$vendorComment": "expectedPersistenceVendor is the vendor the application must report, not the one the lane started. local-jpa passed for a while against H2 while a PostgreSQL container it never touched sat beside it, because application-local.yml pins an in-memory URL that outranks the lane's environment.", + "$activationComment": "activationEnv is what the lane injects; expectedCapabilitiesOn is what the application must then report on /actuator/info, as the names under info.capabilities whose enabled is true. Both are needed: a lane named local-jpa that ran with JPA off would render the right services, start cleanly, and prove nothing at all. Every lane boots the qualification image, which carries every capability module, and the wrapper switches them all off before the lane's activationEnv turns its own on. Each module named in `capabilities` ships its info entry beside its switch in its own settings file, so the application must report exactly those names: a missing one means the module or the info contributor is missing, which is what makes the all-off lanes a check rather than an empty list matching an empty list. Object storage, WebSocket and gRPC are switched off in every lane and report nothing.", + "capabilities": [ + "fileserver", + "graphql", + "httpclient", + "messaging", + "notification", + "persistence-jpa", + "persistence-mongo", + "redis" + ], + "$vendorComment": "expectedPersistenceVendor is the vendor the application must report, not the one the lane started: info.capabilities.persistence-jpa.vendor while JPA is on, none while it is off. A reported postgresql is the database the queries go to, because the JPA module refuses to start when the selected vendor is postgresql and the datasource it reaches is not PostgreSQL (JpaDataSourceProfileValidator). local-jpa passed for a while against H2 while a PostgreSQL container it never touched sat beside it, because application-local.yml pins an in-memory URL that outranks the lane's environment.", "$flywayComment": "SPRING_FLYWAY_LOCATIONS is deliberately absent. Seven lanes listed every capability stream there, and it could never have worked: the db/migration/jpa/* streams each declare a V1, so one Flyway instance over all of them fails with 'Found more than one migration with version 1'. Each stream is its own stream with its own history table by design. The setting was inert until Wave 2 stopped PostgreSqlPersistenceConfig from overriding spring.flyway.locations, and the lanes passed while their own configuration was being discarded. Applying a capability stream needs a Flyway execution per stream — the operator sequence PostgreSqlNotificationPersistenceUnitIntegrationTest and FileserverRoundTripContractTest both perform in their fixtures — and that is what the notification lanes still need." } diff --git a/src/grpc-advanced/grpc-advanced-compat/src/main/resources/envoy/envoy.yaml b/src/grpc-advanced/grpc-advanced-compat/src/main/resources/envoy/envoy.yaml index 0c5ec860..ae3cab3a 100644 --- a/src/grpc-advanced/grpc-advanced-compat/src/main/resources/envoy/envoy.yaml +++ b/src/grpc-advanced/grpc-advanced-compat/src/main/resources/envoy/envoy.yaml @@ -29,13 +29,18 @@ static_resources: - match: { prefix: "/" } route: cluster: grpc_backend - timeout: 30s + # No route timeout: it would cut every server stream at that age. The + # caller's grpc-timeout header bounds each call instead. + timeout: 0s + max_stream_duration: + grpc_timeout_header_max: 0s cors: allow_origin_string_match: - exact: "https://app.example.com" allow_methods: "POST,OPTIONS" - allow_headers: "content-type,x-grpc-web,x-correlation-id,authorization" - expose_headers: "grpc-status,grpc-message,error-code,error-category" + allow_headers: "content-type,x-grpc-web,x-user-agent,grpc-timeout,x-correlation-id,authorization" + # Every trailer the platform sends (GrpcErrorMapper, GrpcValidationInterceptor). + expose_headers: "grpc-status,grpc-message,grpc-status-details-bin,error-reason,error-execution-id,completion-outcome,validation-violations" max_age: "1728000" http_filters: - name: envoy.filters.http.grpc_web @@ -51,6 +56,11 @@ static_resources: name: envoy.transport_sockets.tls typed_config: "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext + # Placeholder paths: mount the proxy's certificate and key here. + common_tls_context: + tls_certificates: + - certificate_chain: { filename: /etc/envoy/tls/tls.crt } + private_key: { filename: /etc/envoy/tls/tls.key } clusters: - name: grpc_backend connect_timeout: 1s diff --git a/src/grpc-advanced/grpc-advanced-compat/src/test/java/dev/caskeleton/grpc/advanced/compat/GrpcWebCompatibilityTest.java b/src/grpc-advanced/grpc-advanced-compat/src/test/java/dev/caskeleton/grpc/advanced/compat/GrpcWebCompatibilityTest.java index 0a215f81..a34f687b 100644 --- a/src/grpc-advanced/grpc-advanced-compat/src/test/java/dev/caskeleton/grpc/advanced/compat/GrpcWebCompatibilityTest.java +++ b/src/grpc-advanced/grpc-advanced-compat/src/test/java/dev/caskeleton/grpc/advanced/compat/GrpcWebCompatibilityTest.java @@ -7,11 +7,15 @@ import dev.caskeleton.grpc.advanced.web.GrpcWebProfile; import dev.caskeleton.grpc.advanced.web.GrpcWebProxyContract; import dev.caskeleton.grpc.advanced.web.GrpcWebRpcSupport; import dev.caskeleton.grpc.core.RpcType; +import dev.caskeleton.grpc.error.GrpcErrorMapper; +import dev.caskeleton.grpc.validation.GrpcValidationInterceptor; import java.io.IOException; import java.io.InputStream; import java.io.UncheckedIOException; import java.nio.charset.StandardCharsets; import java.util.Set; +import java.util.regex.Matcher; +import java.util.regex.Pattern; import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; @@ -110,6 +114,58 @@ class GrpcWebCompatibilityTest { .contains("envoy.filters.http.grpc_web"); } + @Test + void theReferenceProxyExposesEveryTrailerThePlatformSends() { + // when + Set exposed = headerList(resource("envoy/envoy.yaml"), "expose_headers"); + + // then + assertThat(exposed) + .contains( + "grpc-status", + "grpc-message", + "grpc-status-details-bin", + GrpcErrorMapper.REASON_KEY.name(), + GrpcErrorMapper.EXECUTION_ID_KEY.name(), + GrpcErrorMapper.COMPLETION_OUTCOME_KEY.name(), + GrpcValidationInterceptor.VIOLATIONS_KEY.name()); + } + + @Test + void theReferenceProxyLetsTheBrowserSendItsDeadlineAndClientHeaders() { + // when + Set allowed = headerList(resource("envoy/envoy.yaml"), "allow_headers"); + + // then + assertThat(allowed).contains("grpc-timeout", "x-user-agent", "x-grpc-web", "content-type"); + } + + @Test + void theReferenceRouteLeavesStreamLengthToTheCallersDeadline() { + // when + String envoy = resource("envoy/envoy.yaml"); + + // then + assertThat(envoy).contains("timeout: 0s").contains("grpc_timeout_header_max: 0s"); + } + + @Test + void theReferenceProxyTerminatesTlsWithACertificate() { + // when + String envoy = resource("envoy/envoy.yaml"); + + // then + assertThat(envoy).contains("certificate_chain:").contains("private_key:"); + } + + private static Set headerList(String envoy, String field) { + Matcher matcher = Pattern.compile(field + ": \"([^\"]*)\"").matcher(envoy); + if (!matcher.find()) { + throw new IllegalStateException("the reference proxy has no " + field); + } + return Set.of(matcher.group(1).split(",")); + } + private static String resource(String path) { try (InputStream stream = GrpcWebCompatibilityTest.class.getClassLoader().getResourceAsStream(path)) { diff --git a/src/grpc/grpc-admin/src/main/java/dev/caskeleton/grpc/admin/GrpcServiceHealthRegistry.java b/src/grpc/grpc-admin/src/main/java/dev/caskeleton/grpc/admin/GrpcServiceHealthRegistry.java index ee4ad401..4be13bd0 100644 --- a/src/grpc/grpc-admin/src/main/java/dev/caskeleton/grpc/admin/GrpcServiceHealthRegistry.java +++ b/src/grpc/grpc-admin/src/main/java/dev/caskeleton/grpc/admin/GrpcServiceHealthRegistry.java @@ -22,7 +22,9 @@ public final class GrpcServiceHealthRegistry { private final ConcurrentMap states = new ConcurrentHashMap<>(); private final ConcurrentMap dependencyHealth = new ConcurrentHashMap<>(); private final GrpcHealthPolicy policy; - private volatile boolean draining; + // Every write holds this registry's lock, so a state change cannot land between the draining + // check and its write and undo a drain that started in between. + private boolean draining; /** Binds a registry to its health policy. */ public GrpcServiceHealthRegistry(GrpcHealthPolicy policy) { @@ -34,7 +36,7 @@ public final class GrpcServiceHealthRegistry { } /** Registers a service, unknown until something says otherwise. */ - public void register(String serviceName) { + public synchronized void register(String serviceName) { requireServiceName(serviceName); states.putIfAbsent(serviceName, GrpcHealthState.UNKNOWN); } @@ -45,7 +47,7 @@ public final class GrpcServiceHealthRegistry { *

    Ignored while draining: a service that reports itself healthy after the drain has started * would be routed traffic the instance has already promised not to take. */ - public void markServing(String serviceName) { + public synchronized void markServing(String serviceName) { requireServiceName(serviceName); if (draining) { return; @@ -55,7 +57,7 @@ public final class GrpcServiceHealthRegistry { } /** Records that a service is not serving. */ - public void markNotServing(String serviceName) { + public synchronized void markNotServing(String serviceName) { requireServiceName(serviceName); if (draining) { return; @@ -65,7 +67,7 @@ public final class GrpcServiceHealthRegistry { } /** Records a dependency's health, which only matters when the policy says it does. */ - public void recordDependencyHealth(String dependencyName, boolean healthy) { + public synchronized void recordDependencyHealth(String dependencyName, boolean healthy) { if (dependencyName == null || dependencyName.isBlank()) { throw new IllegalArgumentException("a dependency needs a name"); } @@ -81,7 +83,7 @@ public final class GrpcServiceHealthRegistry { *

    Called first in a shutdown, before admission stops, so that a load balancer has a chance to * stop sending before the server starts refusing. */ - public void beginDraining() { + public synchronized void beginDraining() { draining = true; states.replaceAll((service, state) -> GrpcHealthState.DRAINING); } diff --git a/src/grpc/grpc-admin/src/test/java/dev/caskeleton/grpc/admin/GrpcServiceHealthRegistryTest.java b/src/grpc/grpc-admin/src/test/java/dev/caskeleton/grpc/admin/GrpcServiceHealthRegistryTest.java index d85f7c3a..7454b5ae 100644 --- a/src/grpc/grpc-admin/src/test/java/dev/caskeleton/grpc/admin/GrpcServiceHealthRegistryTest.java +++ b/src/grpc/grpc-admin/src/test/java/dev/caskeleton/grpc/admin/GrpcServiceHealthRegistryTest.java @@ -4,6 +4,11 @@ import static org.assertj.core.api.Assertions.assertThat; import static org.assertj.core.api.Assertions.assertThatThrownBy; import java.util.Set; +import java.util.TreeSet; +import java.util.concurrent.CyclicBarrier; +import java.util.concurrent.ExecutorService; +import java.util.concurrent.Executors; +import java.util.concurrent.Future; import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; @@ -88,4 +93,47 @@ class GrpcServiceHealthRegistryTest { registry.markServing(DOCUMENTS); assertThat(registry.stateOf(DOCUMENTS)).isEqualTo(GrpcHealthState.DRAINING); } + + @Test + void aServiceMarkedServingWhileDrainBeginsNeverReturnsTheInstanceToServing() throws Exception { + // when + Set outcomes = outcomesOfServingRacingDrain(); + + // then + assertThat(outcomes).containsExactly("DRAINING/DRAINING"); + } + + /** Races markServing against beginDraining, round after round, recording service/global. */ + private static Set outcomesOfServingRacingDrain() throws Exception { + ExecutorService pool = Executors.newFixedThreadPool(2); + try { + Set outcomes = new TreeSet<>(); + for (int round = 0; round < 1000; round++) { + GrpcServiceHealthRegistry registry = + new GrpcServiceHealthRegistry(GrpcHealthPolicy.standalone()); + registry.register(DOCUMENTS); + CyclicBarrier start = new CyclicBarrier(2); + Future serving = + pool.submit( + () -> { + start.await(); + registry.markServing(DOCUMENTS); + return null; + }); + Future drain = + pool.submit( + () -> { + start.await(); + registry.beginDraining(); + return null; + }); + serving.get(); + drain.get(); + outcomes.add(registry.stateOf(DOCUMENTS) + "/" + registry.globalState()); + } + return outcomes; + } finally { + pool.shutdownNow(); + } + } } diff --git a/src/grpc/grpc-client/src/main/java/dev/caskeleton/grpc/client/GrpcChannelRuntimeRegistry.java b/src/grpc/grpc-client/src/main/java/dev/caskeleton/grpc/client/GrpcChannelRuntimeRegistry.java index b25dec2d..188ad5fd 100644 --- a/src/grpc/grpc-client/src/main/java/dev/caskeleton/grpc/client/GrpcChannelRuntimeRegistry.java +++ b/src/grpc/grpc-client/src/main/java/dev/caskeleton/grpc/client/GrpcChannelRuntimeRegistry.java @@ -3,7 +3,9 @@ package dev.caskeleton.grpc.client; import dev.caskeleton.grpc.core.GrpcChannelProfileName; import java.time.Instant; import java.util.ArrayList; +import java.util.HashMap; import java.util.List; +import java.util.Map; import java.util.Optional; import java.util.concurrent.ConcurrentHashMap; import java.util.concurrent.ConcurrentMap; @@ -24,8 +26,9 @@ public final class GrpcChannelRuntimeRegistry { private final ConcurrentMap> current = new ConcurrentHashMap<>(); - private final ConcurrentMap> draining = - new ConcurrentHashMap<>(); + // Guarded by this registry's lock, like every swap: rotations are rare, and one lock keeps the + // current pointer and the draining list from disagreeing. + private final Map> draining = new HashMap<>(); private final GrpcChannelDrainPolicy drainPolicy; /** Binds a registry to the drain policy its swaps use. */ @@ -37,7 +40,7 @@ public final class GrpcChannelRuntimeRegistry { } /** Installs the first generation for a profile. */ - public GrpcChannelRuntime install(GrpcChannelGeneration generation) { + public synchronized GrpcChannelRuntime install(GrpcChannelGeneration generation) { if (generation == null) { throw new IllegalArgumentException("a generation is required"); } @@ -80,7 +83,7 @@ public final class GrpcChannelRuntimeRegistry { * * @throws IllegalArgumentException when {@code next} does not supersede what is installed */ - public GrpcChannelRuntime rotate(GrpcChannelGeneration next, Instant now) { + public synchronized GrpcChannelRuntime rotate(GrpcChannelGeneration next, Instant now) { if (next == null || now == null) { throw new IllegalArgumentException("a rotation needs a generation and a moment"); } @@ -102,15 +105,12 @@ public final class GrpcChannelRuntimeRegistry { GrpcChannelRuntime replacement = new GrpcChannelRuntime(next); holder.set(replacement); previous.beginDrain(); - draining - .computeIfAbsent( - next.profileName(), key -> java.util.Collections.synchronizedList(new ArrayList<>())) - .add(previous); + draining.computeIfAbsent(next.profileName(), key -> new ArrayList<>()).add(previous); return replacement; } /** The generations still draining for a profile. */ - public List draining(GrpcChannelProfileName profileName) { + public synchronized List draining(GrpcChannelProfileName profileName) { return List.copyOf(draining.getOrDefault(profileName, List.of())); } @@ -119,7 +119,7 @@ public final class GrpcChannelRuntimeRegistry { * * @return how many were retired */ - public int retireQuiescent(GrpcChannelProfileName profileName) { + public synchronized int retireQuiescent(GrpcChannelProfileName profileName) { List runtimes = draining.get(profileName); if (runtimes == null) { return 0; diff --git a/src/grpc/grpc-client/src/test/java/dev/caskeleton/grpc/client/GrpcChannelRuntimeRegistryTest.java b/src/grpc/grpc-client/src/test/java/dev/caskeleton/grpc/client/GrpcChannelRuntimeRegistryTest.java index 796e4a1c..b1ceb3e3 100644 --- a/src/grpc/grpc-client/src/test/java/dev/caskeleton/grpc/client/GrpcChannelRuntimeRegistryTest.java +++ b/src/grpc/grpc-client/src/test/java/dev/caskeleton/grpc/client/GrpcChannelRuntimeRegistryTest.java @@ -6,6 +6,12 @@ import static org.assertj.core.api.Assertions.assertThatThrownBy; import dev.caskeleton.grpc.core.GrpcChannelProfileName; import java.time.Duration; import java.time.Instant; +import java.util.Set; +import java.util.TreeSet; +import java.util.concurrent.CyclicBarrier; +import java.util.concurrent.ExecutorService; +import java.util.concurrent.Executors; +import java.util.concurrent.Future; import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; @@ -125,4 +131,52 @@ class GrpcChannelRuntimeRegistryTest { .extracting(Class::getName) .noneMatch(name -> name.startsWith("io.grpc.")); } + + @Test + void racingRotationsDrainEveryReplacedRuntimeAndKeepTheNewestCurrent() throws Exception { + // when + Set outcomes = outcomesOfRacingRotations(); + + // then + assertThat(outcomes).isSubsetOf("3 draining [1]", "3 draining [1, 2]"); + } + + /** Races rotate(2) against rotate(3) on a profile at generation 1, round after round. */ + private static Set outcomesOfRacingRotations() throws Exception { + ExecutorService pool = Executors.newFixedThreadPool(2); + try { + Set outcomes = new TreeSet<>(); + for (int round = 0; round < 1000; round++) { + GrpcChannelRuntimeRegistry registry = + new GrpcChannelRuntimeRegistry(GrpcChannelDrainPolicy.stable()); + registry.install(generation(1)); + CyclicBarrier start = new CyclicBarrier(2); + Future a = pool.submit(() -> rotateIgnoringRefusal(registry, start, 2)); + Future b = pool.submit(() -> rotateIgnoringRefusal(registry, start, 3)); + a.get(); + b.get(); + outcomes.add( + registry.require(PROFILE).generation().generation() + + " draining " + + registry.draining(PROFILE).stream() + .map(runtime -> runtime.generation().generation()) + .sorted() + .toList()); + } + return outcomes; + } finally { + pool.shutdownNow(); + } + } + + private static Void rotateIgnoringRefusal( + GrpcChannelRuntimeRegistry registry, CyclicBarrier start, long next) throws Exception { + start.await(); + try { + registry.rotate(generation(next), NOW); + } catch (IllegalArgumentException refused) { + // the other rotator installed a newer generation first + } + return null; + } } diff --git a/src/grpc/grpc-client/src/test/java/dev/caskeleton/grpc/client/GrpcTypedStubFactoryTest.java b/src/grpc/grpc-client/src/test/java/dev/caskeleton/grpc/client/GrpcTypedStubFactoryTest.java index 8203a612..15cdf297 100644 --- a/src/grpc/grpc-client/src/test/java/dev/caskeleton/grpc/client/GrpcTypedStubFactoryTest.java +++ b/src/grpc/grpc-client/src/test/java/dev/caskeleton/grpc/client/GrpcTypedStubFactoryTest.java @@ -122,8 +122,10 @@ class GrpcTypedStubFactoryTest { GrpcStubPolicyApplier.CallPolicy generous = applier.applyTo(GET, Duration.ofSeconds(30)); GrpcStubPolicyApplier.CallPolicy tight = applier.applyTo(GET, Duration.ofMillis(300)); - assertThat(generous.deadline().remaining()).isEqualTo(Duration.ofMillis(1800)); - assertThat(tight.deadline().remaining()).isEqualTo(Duration.ofMillis(100)); + // The budget is live: a few milliseconds have passed since applyTo computed it. + assertThat(generous.deadline().remaining()) + .isBetween(Duration.ofMillis(1700), Duration.ofMillis(1800)); + assertThat(tight.deadline().remaining()).isBetween(Duration.ZERO, Duration.ofMillis(100)); assertThat(tight.waitForReady().queue()).isFalse(); } } diff --git a/src/grpc/grpc-core-api/src/main/java/dev/caskeleton/grpc/api/deadline/GrpcDeadlineBudget.java b/src/grpc/grpc-core-api/src/main/java/dev/caskeleton/grpc/api/deadline/GrpcDeadlineBudget.java index b41258a6..02a8cbb6 100644 --- a/src/grpc/grpc-core-api/src/main/java/dev/caskeleton/grpc/api/deadline/GrpcDeadlineBudget.java +++ b/src/grpc/grpc-core-api/src/main/java/dev/caskeleton/grpc/api/deadline/GrpcDeadlineBudget.java @@ -1,6 +1,7 @@ package dev.caskeleton.grpc.api.deadline; import java.time.Duration; +import java.util.function.LongSupplier; /** * How much time a call actually has, after the parent deadline and the method profile have both had @@ -9,17 +10,40 @@ import java.time.Duration; *

    The rule is "shorter of the two, minus the reserve", and it is here rather than at each call * site because the failure mode of getting it wrong is silent: a downstream timeout longer than the * inbound deadline never fires, and the caller sees a deadline the server has no idea it missed. + * + *

    The budget is an absolute deadline on a monotonic nanosecond clock, so {@link #remaining()} + * shrinks and {@link #expired()} turns true as time passes. A request context carries one budget + * for the whole call; a budget that remembered only the duration it started with would hand every + * later dependency call the full original time. */ -public record GrpcDeadlineBudget(Duration remaining, GrpcDeadlineProfile profile) { +public final class GrpcDeadlineBudget { - /** Rejects a budget with no time in it. */ - public GrpcDeadlineBudget { - if (remaining == null || profile == null) { - throw new IllegalArgumentException("a deadline budget needs a remaining time and a profile"); + private final long deadlineNanos; + private final GrpcDeadlineProfile profile; + private final LongSupplier nanoClock; + + /** A budget of {@code remaining} from now on the system's monotonic clock. */ + public GrpcDeadlineBudget(Duration remaining, GrpcDeadlineProfile profile) { + this(remaining, profile, System::nanoTime); + } + + /** + * A budget of {@code remaining} from now on {@code nanoClock}. + * + * @param nanoClock a monotonic nanosecond source, {@code System::nanoTime} outside tests + */ + public GrpcDeadlineBudget( + Duration remaining, GrpcDeadlineProfile profile, LongSupplier nanoClock) { + if (remaining == null || profile == null || nanoClock == null) { + throw new IllegalArgumentException( + "a deadline budget needs a remaining time, a profile and a clock"); } if (remaining.isNegative()) { throw new IllegalArgumentException("remaining time must not be negative; got " + remaining); } + this.deadlineNanos = nanoClock.getAsLong() + remaining.toNanos(); + this.profile = profile; + this.nanoClock = nanoClock; } /** @@ -31,6 +55,12 @@ public record GrpcDeadlineBudget(Duration remaining, GrpcDeadlineProfile profile */ public static GrpcDeadlineBudget forEntryPoint( Duration parentRemaining, GrpcDeadlineProfile profile) { + return forEntryPoint(parentRemaining, profile, System::nanoTime); + } + + /** {@link #forEntryPoint(Duration, GrpcDeadlineProfile)} on {@code nanoClock}. */ + public static GrpcDeadlineBudget forEntryPoint( + Duration parentRemaining, GrpcDeadlineProfile profile, LongSupplier nanoClock) { if (profile == null) { throw new IllegalArgumentException("a deadline budget needs a profile"); } @@ -42,17 +72,13 @@ public record GrpcDeadlineBudget(Duration remaining, GrpcDeadlineProfile profile throw new IllegalArgumentException( "a Stable unary call requires a positive deadline; got " + parentRemaining); } - Duration bounded = - parentRemaining.compareTo(profile.total()) <= 0 ? parentRemaining : profile.total(); - Duration afterReserve = bounded.minus(profile.safetyMargin()); - return new GrpcDeadlineBudget( - afterReserve.isNegative() ? Duration.ZERO : afterReserve, profile); + return new GrpcDeadlineBudget(afterReserve(parentRemaining, profile), profile, nanoClock); } /** * Derives the budget for a downstream dependency call under {@code downstream}. * - *

    Takes the shorter of what is left here and what the downstream profile allows, then + *

    Takes the shorter of what is left here now and what the downstream profile allows, then * subtracts the downstream reserve. A dependency can never be given more time than its caller * has. */ @@ -60,11 +86,18 @@ public record GrpcDeadlineBudget(Duration remaining, GrpcDeadlineProfile profile if (downstream == null) { throw new IllegalArgumentException("a downstream budget needs a profile"); } - Duration bounded = - remaining.compareTo(downstream.total()) <= 0 ? remaining : downstream.total(); - Duration afterReserve = bounded.minus(downstream.safetyMargin()); - return new GrpcDeadlineBudget( - afterReserve.isNegative() ? Duration.ZERO : afterReserve, downstream); + return new GrpcDeadlineBudget(afterReserve(remaining(), downstream), downstream, nanoClock); + } + + /** What is left now; zero once the deadline has passed. */ + public Duration remaining() { + long left = deadlineNanos - nanoClock.getAsLong(); + return left <= 0 ? Duration.ZERO : Duration.ofNanos(left); + } + + /** The profile this budget was cut from. */ + public GrpcDeadlineProfile profile() { + return profile; } /** @@ -75,11 +108,23 @@ public record GrpcDeadlineBudget(Duration remaining, GrpcDeadlineProfile profile * investigates the wrong system. */ public boolean canStartDependencyCall() { - return remaining.compareTo(profile.minimumAttemptBudget()) >= 0 && !remaining.isZero(); + Duration left = remaining(); + return !left.isZero() && left.compareTo(profile.minimumAttemptBudget()) >= 0; } /** Whether any time is left at all. */ public boolean expired() { - return remaining.isZero() || remaining.isNegative(); + return remaining().isZero(); + } + + @Override + public String toString() { + return "GrpcDeadlineBudget[remaining=" + remaining() + ", profile=" + profile + "]"; + } + + private static Duration afterReserve(Duration available, GrpcDeadlineProfile profile) { + Duration bounded = available.compareTo(profile.total()) <= 0 ? available : profile.total(); + Duration afterReserve = bounded.minus(profile.safetyMargin()); + return afterReserve.isNegative() ? Duration.ZERO : afterReserve; } } diff --git a/src/grpc/grpc-core-api/src/main/java/dev/caskeleton/grpc/api/ledger/GrpcOperationIdentity.java b/src/grpc/grpc-core-api/src/main/java/dev/caskeleton/grpc/api/ledger/GrpcOperationIdentity.java index b4dab916..bfd5bec2 100644 --- a/src/grpc/grpc-core-api/src/main/java/dev/caskeleton/grpc/api/ledger/GrpcOperationIdentity.java +++ b/src/grpc/grpc-core-api/src/main/java/dev/caskeleton/grpc/api/ledger/GrpcOperationIdentity.java @@ -16,6 +16,13 @@ import dev.caskeleton.grpc.core.GrpcMethodName; public record GrpcOperationIdentity( String callerFingerprint, GrpcMethodName method, String idempotencyKeyHash) { + // Column widths of grpc_operation_ledger (V001). An identity that does not fit is refused here, + // not by the database in the middle of a claim. + private static final int MAX_CALLER_FINGERPRINT = 256; + private static final int MAX_METHOD = 256; + private static final int MAX_KEY_HASH = 80; + private static final int MAX_STORAGE_KEY = 512; + /** Requires all three parts, with the key already hashed. */ public GrpcOperationIdentity { if (callerFingerprint == null || callerFingerprint.isBlank()) { @@ -30,6 +37,24 @@ public record GrpcOperationIdentity( throw new IllegalArgumentException( "the idempotency key is stored hashed; got '" + idempotencyKeyHash + "'"); } + requireAtMost("caller fingerprint", callerFingerprint, MAX_CALLER_FINGERPRINT); + requireAtMost("full method name", method.canonical(), MAX_METHOD); + requireAtMost("idempotency key hash", idempotencyKeyHash, MAX_KEY_HASH); + requireAtMost( + "storage key", + callerFingerprint + "|" + method.canonical() + "|" + idempotencyKeyHash, + MAX_STORAGE_KEY); + } + + private static void requireAtMost(String what, String value, int max) { + if (value.length() > max) { + throw new IllegalArgumentException( + what + + " must be at most " + + max + + " characters to fit the ledger; got " + + value.length()); + } } /** The stable storage key: the three parts joined, safe to index and safe to log. */ diff --git a/src/grpc/grpc-core-api/src/test/java/dev/caskeleton/grpc/api/deadline/GrpcDeadlineBudgetTest.java b/src/grpc/grpc-core-api/src/test/java/dev/caskeleton/grpc/api/deadline/GrpcDeadlineBudgetTest.java index 58fd57a9..a23bc99c 100644 --- a/src/grpc/grpc-core-api/src/test/java/dev/caskeleton/grpc/api/deadline/GrpcDeadlineBudgetTest.java +++ b/src/grpc/grpc-core-api/src/test/java/dev/caskeleton/grpc/api/deadline/GrpcDeadlineBudgetTest.java @@ -5,6 +5,7 @@ import static org.assertj.core.api.Assertions.assertThatThrownBy; import java.time.Duration; import java.time.Instant; +import java.util.concurrent.atomic.AtomicLong; import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; @@ -27,9 +28,11 @@ class GrpcDeadlineBudgetTest { @DisplayName("the budget takes the shorter of the parent remaining and the method default") void budgetTakesTheShorterOfParentAndMethodDefault() { GrpcDeadlineBudget fromShortParent = - GrpcDeadlineBudget.forEntryPoint(Duration.ofMillis(500), TWO_SECONDS); + GrpcDeadlineBudget.forEntryPoint( + Duration.ofMillis(500), TWO_SECONDS, GrpcDeadlineBudgetTest::frozenNanos); GrpcDeadlineBudget fromLongParent = - GrpcDeadlineBudget.forEntryPoint(Duration.ofSeconds(30), TWO_SECONDS); + GrpcDeadlineBudget.forEntryPoint( + Duration.ofSeconds(30), TWO_SECONDS, GrpcDeadlineBudgetTest::frozenNanos); assertThat(fromShortParent.remaining()) .isEqualTo(Duration.ofMillis(500).minus(TWO_SECONDS.safetyMargin())); @@ -44,7 +47,9 @@ class GrpcDeadlineBudgetTest { new GrpcDeadlineProfile( Duration.ofSeconds(10), Duration.ofSeconds(1), Duration.ofMillis(100)); - GrpcDeadlineBudget budget = GrpcDeadlineBudget.forEntryPoint(Duration.ofSeconds(10), profile); + GrpcDeadlineBudget budget = + GrpcDeadlineBudget.forEntryPoint( + Duration.ofSeconds(10), profile, GrpcDeadlineBudgetTest::frozenNanos); assertThat(budget.remaining()).isEqualTo(Duration.ofSeconds(9)); assertThat(profile.usable()).isEqualTo(Duration.ofSeconds(9)); @@ -54,7 +59,8 @@ class GrpcDeadlineBudgetTest { @DisplayName("a downstream call never gets more time than its caller has left") void downstreamNeverExceedsTheCaller() { GrpcDeadlineBudget caller = - GrpcDeadlineBudget.forEntryPoint(Duration.ofMillis(400), TWO_SECONDS); + GrpcDeadlineBudget.forEntryPoint( + Duration.ofMillis(400), TWO_SECONDS, GrpcDeadlineBudgetTest::frozenNanos); GrpcDeadlineProfile generousDownstream = new GrpcDeadlineProfile(Duration.ofSeconds(30), Duration.ZERO, Duration.ofMillis(10)); @@ -77,6 +83,39 @@ class GrpcDeadlineBudgetTest { assertThat(new GrpcDeadlineBudget(Duration.ZERO, profile).canStartDependencyCall()).isFalse(); } + @Test + void aBudgetRunsOutAsTimePassesAfterItWasCreated() { + // given + AtomicLong nanos = new AtomicLong(); + GrpcDeadlineBudget budget = + new GrpcDeadlineBudget(Duration.ofMillis(300), TWO_SECONDS, nanos::get); + + // when + nanos.addAndGet(Duration.ofMillis(300).toNanos()); + + // then + assertThat(budget) + .extracting(GrpcDeadlineBudget::remaining, GrpcDeadlineBudget::expired) + .containsExactly(Duration.ZERO, true); + } + + @Test + void aDownstreamDerivedLaterGetsOnlyWhatIsLeftThen() { + // given + AtomicLong nanos = new AtomicLong(); + GrpcDeadlineBudget caller = + new GrpcDeadlineBudget(Duration.ofSeconds(1), TWO_SECONDS, nanos::get); + nanos.addAndGet(Duration.ofMillis(700).toNanos()); + + // when + GrpcDeadlineBudget downstream = + caller.deriveDownstream( + new GrpcDeadlineProfile(Duration.ofSeconds(30), Duration.ZERO, Duration.ofMillis(10))); + + // then + assertThat(downstream.remaining()).isEqualTo(Duration.ofMillis(300)); + } + @Test @DisplayName("a profile whose reserve leaves no usable time is refused") void profileWithNoUsableTimeIsRefused() { @@ -121,4 +160,8 @@ class GrpcDeadlineBudgetTest { .hasMessageContaining("charge-card") .hasMessageContaining("deadline-exceeded"); } + + private static long frozenNanos() { + return 0L; + } } diff --git a/src/grpc/grpc-core-api/src/test/java/dev/caskeleton/grpc/api/ledger/GrpcOperationIdentityTest.java b/src/grpc/grpc-core-api/src/test/java/dev/caskeleton/grpc/api/ledger/GrpcOperationIdentityTest.java new file mode 100644 index 00000000..c210e211 --- /dev/null +++ b/src/grpc/grpc-core-api/src/test/java/dev/caskeleton/grpc/api/ledger/GrpcOperationIdentityTest.java @@ -0,0 +1,44 @@ +package dev.caskeleton.grpc.api.ledger; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.catchThrowable; + +import dev.caskeleton.grpc.core.GrpcMethodName; +import dev.caskeleton.grpc.core.GrpcServiceName; +import org.junit.jupiter.api.Test; + +class GrpcOperationIdentityTest { + + private static final GrpcMethodName CREATE = + GrpcMethodName.parse("hyeonworks.document.v1.DocumentService/CreateDocument"); + private static final String KEY_HASH = + "sha256:aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899"; + + @Test + void aCallerFingerprintWiderThanItsLedgerColumnIsRefused() { + // when + Throwable failure = + catchThrowable(() -> new GrpcOperationIdentity("c".repeat(257), CREATE, KEY_HASH)); + + // then + assertThat(failure) + .isInstanceOf(IllegalArgumentException.class) + .hasMessageContaining("caller fingerprint must be at most 256"); + } + + @Test + void anIdentityWhoseStorageKeyWouldNotFitTheLedgerIsRefused() { + // given + GrpcMethodName longMethod = + new GrpcMethodName(new GrpcServiceName("p.S" + "s".repeat(197)), "M" + "m".repeat(54)); + + // when + Throwable failure = + catchThrowable(() -> new GrpcOperationIdentity("c".repeat(256), longMethod, KEY_HASH)); + + // then + assertThat(failure) + .isInstanceOf(IllegalArgumentException.class) + .hasMessageContaining("storage key must be at most 512"); + } +} diff --git a/src/grpc/grpc-operation-ledger-jpa/src/main/java/dev/caskeleton/grpc/ledger/JpaGrpcOperationLedger.java b/src/grpc/grpc-operation-ledger-jpa/src/main/java/dev/caskeleton/grpc/ledger/JpaGrpcOperationLedger.java index 443847a7..7cd1afc2 100644 --- a/src/grpc/grpc-operation-ledger-jpa/src/main/java/dev/caskeleton/grpc/ledger/JpaGrpcOperationLedger.java +++ b/src/grpc/grpc-operation-ledger-jpa/src/main/java/dev/caskeleton/grpc/ledger/JpaGrpcOperationLedger.java @@ -50,7 +50,19 @@ public final class JpaGrpcOperationLedger implements GrpcOperationLedger { if (inserted != 0) { throw new IllegalStateException("claim insert affected an unexpected row count: " + inserted); } - return repository.findById(identity.storageKey()).map(entity -> entity.toRecord(identity)); + // Zero rows means another claim holds the key. An empty read now means that owner released it + // in between; treating that as "ours" would run the mutation without a claim row to guard it. + return Optional.of( + repository + .findById(identity.storageKey()) + .orElseThrow( + () -> + new IllegalStateException( + "claim for '" + + identity.storageKey() + + "' conflicted, but there was no row to read; the other owner released" + + " it in between. Retry the claim.")) + .toRecord(identity)); } @Override diff --git a/src/grpc/grpc-operation-ledger-jpa/src/test/java/dev/caskeleton/grpc/ledger/GrpcOperationLedgerRepositoryTest.java b/src/grpc/grpc-operation-ledger-jpa/src/test/java/dev/caskeleton/grpc/ledger/GrpcOperationLedgerRepositoryTest.java index e1457b52..84862d5d 100644 --- a/src/grpc/grpc-operation-ledger-jpa/src/test/java/dev/caskeleton/grpc/ledger/GrpcOperationLedgerRepositoryTest.java +++ b/src/grpc/grpc-operation-ledger-jpa/src/test/java/dev/caskeleton/grpc/ledger/GrpcOperationLedgerRepositoryTest.java @@ -2,6 +2,7 @@ package dev.caskeleton.grpc.ledger; import static org.assertj.core.api.Assertions.assertThat; import static org.assertj.core.api.Assertions.assertThatThrownBy; +import static org.assertj.core.api.Assertions.catchThrowable; import dev.caskeleton.grpc.api.ledger.GrpcOperationIdentity; import dev.caskeleton.grpc.api.ledger.GrpcOperationLedger; @@ -40,7 +41,7 @@ class GrpcOperationLedgerRepositoryTest { * putIfAbsent} and therefore tested the database constraint we wished save() would hit rather * than the merge behavior it actually uses. */ - private static final class InMemoryRepository implements GrpcOperationLedgerRepository { + private static class InMemoryRepository implements GrpcOperationLedgerRepository { private final ConcurrentMap rows = new ConcurrentHashMap<>(); @Override @@ -124,6 +125,34 @@ class GrpcOperationLedgerRepositoryTest { assertThat(second.get().sameRequestAs(FINGERPRINT)).isTrue(); } + @Test + void aConflictWhoseRowVanishedBeforeTheReadIsNotTakenAsOwnership() { + // given + InMemoryRepository conflictThenReleased = + new InMemoryRepository() { + @Override + public int tryInsertClaim( + String storageKey, + String callerFingerprint, + String fullMethodName, + String idempotencyKeyHash, + String requestFingerprint, + Instant claimedAt) { + return 0; // another owner held the key and released it before this read + } + }; + GrpcOperationLedger racing = new JpaGrpcOperationLedger(conflictThenReleased); + + // when + Throwable failure = + catchThrowable(() -> racing.claim(identity("tenant-1.actor-1"), FINGERPRINT, NOW)); + + // then + assertThat(failure) + .isInstanceOf(IllegalStateException.class) + .hasMessageContaining("no row to read"); + } + @Test @DisplayName("one caller's key does not collide with another's") void callersDoNotCollide() { diff --git a/src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/context/GrpcContextBinder.java b/src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/context/GrpcContextBinder.java index 5f0f67cc..5eef3bdd 100644 --- a/src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/context/GrpcContextBinder.java +++ b/src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/context/GrpcContextBinder.java @@ -87,15 +87,14 @@ public final class GrpcContextBinder { if (work == null) { throw new IllegalArgumentException("work must not be null"); } - GrpcContextSnapshot captured = SNAPSHOT.get(); - if (captured == null && policy.failClosedWithoutContext()) { + // The whole io.grpc Context, not just the snapshot value: it also carries the call's + // cancellation and deadline, which the other thread must see. + Context captured = Context.current(); + if (SNAPSHOT.get(captured) == null && policy.failClosedWithoutContext()) { throw new IllegalStateException( "refusing to hand work to another thread with no call context to carry"); } - if (captured == null) { - return work; - } - return () -> runWith(captured, work); + return captured.wrap(work); } /** An {@link Executor} that carries the submitting thread's context to every task. */ diff --git a/src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/resilience/GrpcRetryCoordinator.java b/src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/resilience/GrpcRetryCoordinator.java index b967e90a..5da90b5a 100644 --- a/src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/resilience/GrpcRetryCoordinator.java +++ b/src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/resilience/GrpcRetryCoordinator.java @@ -78,13 +78,15 @@ public final class GrpcRetryCoordinator { } Duration backoff = jittered(config.backoffBefore(completedAttempt + 1), config.jitterFactor()); - if (remaining.remaining().compareTo(backoff) <= 0) { + // Read once: the budget is live, and a second read could fall below the backoff. + Duration left = remaining.remaining(); + if (left.compareTo(backoff) <= 0) { return GrpcRetryDecision.refuse( GrpcRetryDecision.Verdict.TERMINAL, "the remaining deadline is shorter than the backoff, so a retry could not finish"); } GrpcDeadlineBudget afterBackoff = - new GrpcDeadlineBudget(remaining.remaining().minus(backoff), remaining.profile()); + new GrpcDeadlineBudget(left.minus(backoff), remaining.profile()); if (!afterBackoff.canStartDependencyCall()) { return GrpcRetryDecision.refuse( GrpcRetryDecision.Verdict.TERMINAL, diff --git a/src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/resilience/GrpcWaitForReadyValidator.java b/src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/resilience/GrpcWaitForReadyValidator.java index f41151da..6becd963 100644 --- a/src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/resilience/GrpcWaitForReadyValidator.java +++ b/src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/resilience/GrpcWaitForReadyValidator.java @@ -35,7 +35,9 @@ public final class GrpcWaitForReadyValidator { + policy.method().canonical() + "' must carry one"); } - if (remaining.expired()) { + // Read once: the budget is live and keeps shrinking between reads. + Duration left = remaining.remaining(); + if (left.isZero()) { return GrpcWaitForReadyDecision.failFast("no deadline remains to queue inside"); } if (policy.waitForReady() != profile.policy()) { @@ -47,9 +49,7 @@ public final class GrpcWaitForReadyValidator { + "; the stricter of the two wins"); } Duration allowance = - profile.maxQueueWait().compareTo(remaining.remaining()) <= 0 - ? profile.maxQueueWait() - : remaining.remaining(); + profile.maxQueueWait().compareTo(left) <= 0 ? profile.maxQueueWait() : left; return GrpcWaitForReadyDecision.queueFor( allowance, "queueing under " + profile.policy() + " within the queue budget"); } diff --git a/src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/security/GrpcCredentialRotationManager.java b/src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/security/GrpcCredentialRotationManager.java index bcf033f6..dc13a6c2 100644 --- a/src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/security/GrpcCredentialRotationManager.java +++ b/src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/security/GrpcCredentialRotationManager.java @@ -86,22 +86,29 @@ public final class GrpcCredentialRotationManager { if (next == null || now == null) { throw new IllegalArgumentException("a rotation needs a generation and a moment"); } - State observed = state.get(); - if (observed.current().generation() == next.generation()) { - // Idempotent: re-applying the generation that is already current is a no-op rather than a - // second drain, because a retried rotation must not cancel the calls the first one admitted. - return new RotationPlan(observed.current(), Optional.empty(), Optional.empty()); - } - if (!observed.current().supersededBy(next)) { - throw new IllegalArgumentException( - "credential generation " - + next.generation() - + " does not supersede the current generation " - + observed.current().generation()); - } Instant deadline = now.plus(drainWindow); - state.set(new State(next, observed.current(), deadline)); - return new RotationPlan(next, Optional.of(observed.current()), Optional.of(deadline)); + // Compare-and-set loop: a racing rotator or completeDrain re-runs the checks against the state + // it actually replaces, so a rotation never goes backwards and never loses a draining + // generation. + while (true) { + State observed = state.get(); + if (observed.current().generation() == next.generation()) { + // Idempotent: re-applying the generation that is already current is a no-op rather than a + // second drain, because a retried rotation must not cancel the calls the first one + // admitted. + return new RotationPlan(observed.current(), Optional.empty(), Optional.empty()); + } + if (!observed.current().supersededBy(next)) { + throw new IllegalArgumentException( + "credential generation " + + next.generation() + + " does not supersede the current generation " + + observed.current().generation()); + } + if (state.compareAndSet(observed, new State(next, observed.current(), deadline))) { + return new RotationPlan(next, Optional.of(observed.current()), Optional.of(deadline)); + } + } } /** @@ -116,7 +123,6 @@ public final class GrpcCredentialRotationManager { /** Forgets the draining generation once its work has finished or been cancelled. */ public void completeDrain() { - State observed = state.get(); - state.set(new State(observed.current(), null, null)); + state.updateAndGet(observed -> new State(observed.current(), null, null)); } } diff --git a/src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/streaming/GrpcSerializedStreamWriter.java b/src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/streaming/GrpcSerializedStreamWriter.java index 166638a3..c949d2f9 100644 --- a/src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/streaming/GrpcSerializedStreamWriter.java +++ b/src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/streaming/GrpcSerializedStreamWriter.java @@ -4,8 +4,9 @@ import java.util.ArrayDeque; import java.util.Deque; import java.util.List; import java.util.Optional; +import java.util.function.BooleanSupplier; import java.util.function.Consumer; -import java.util.function.LongSupplier; +import java.util.function.ToLongFunction; /** * The single writer every server stream goes through. @@ -27,7 +28,7 @@ public final class GrpcSerializedStreamWriter { private final GrpcStreamSequence sequence; private final GrpcFlowControlPolicy flowControl; private final Consumer> transport; - private final LongSupplier payloadSizer; + private final ToLongFunction payloadSizer; private final Deque> queue = new ArrayDeque<>(); private GrpcStreamWriterState state = GrpcStreamWriterState.OPEN; @@ -37,15 +38,15 @@ public final class GrpcSerializedStreamWriter { /** * @param transport the single consumer that actually calls the observer. Invoked only from {@link - * #flush}, which is synchronized, so the observer sees one thread. - * @param payloadSizer the serialized size of the next payload, for the byte bound + * #flush} and {@link #terminate}, which are synchronized, so the observer sees one thread. + * @param payloadSizer the serialized size of a payload, for the byte bound */ public GrpcSerializedStreamWriter( GrpcStreamId streamId, GrpcStreamSequence sequence, GrpcFlowControlPolicy flowControl, Consumer> transport, - LongSupplier payloadSizer) { + ToLongFunction payloadSizer) { if (streamId == null || sequence == null || flowControl == null @@ -70,7 +71,7 @@ public final class GrpcSerializedStreamWriter { if (!state.acceptsMessages()) { return GrpcStreamWriteResult.REJECTED_CLOSED; } - long nextBytes = payloadSizer.getAsLong(); + long nextBytes = payloadSizer.applyAsLong(payload); GrpcFlowControlDecision decision = flowControl.decide(queue.size(), queuedBytes, nextBytes, transportReady); return switch (decision.action()) { @@ -97,7 +98,11 @@ public final class GrpcSerializedStreamWriter { } } } - case PAUSE, PROCEED -> { + case PAUSE -> { + enqueue(kind, payload, snapshotVersion, resumeToken, nextBytes); + yield GrpcStreamWriteResult.ACCEPTED_PAUSE; + } + case PROCEED -> { enqueue(kind, payload, snapshotVersion, resumeToken, nextBytes); yield GrpcStreamWriteResult.ACCEPTED; } @@ -119,20 +124,22 @@ public final class GrpcSerializedStreamWriter { } /** - * Hands every queued message to the transport, in order, from this one thread. + * Hands queued messages to the transport, in order, from this one thread, while it is ready. * + * @param transportReady asked before each message ({@code ServerCallStreamObserver::isReady}); + * flushing stops at the first false and the rest stay queued for the next onReady * @return the sequence numbers flushed */ - public synchronized List flush() { + public synchronized List flush(BooleanSupplier transportReady) { java.util.List flushed = new java.util.ArrayList<>(); - while (!queue.isEmpty()) { - GrpcStreamEnvelope envelope = queue.pollFirst().envelope(); - transport.accept(envelope); - lastFlushedSequence = envelope.sequence(); - flushed.add(envelope.sequence()); + while (!queue.isEmpty() && transportReady.getAsBoolean()) { + QueuedEnvelope queued = queue.pollFirst(); + transport.accept(queued.envelope()); + queuedBytes = Math.max(0L, queuedBytes - queued.serializedBytes()); + lastFlushedSequence = queued.envelope().sequence(); + flushed.add(lastFlushedSequence); } - queuedBytes = 0L; - if (state == GrpcStreamWriterState.DRAINING) { + if (queue.isEmpty() && state == GrpcStreamWriterState.DRAINING) { state = GrpcStreamWriterState.TERMINATED; } return List.copyOf(flushed); diff --git a/src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/streaming/GrpcStreamAdmission.java b/src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/streaming/GrpcStreamAdmission.java index 2c58baf0..4bfb7e77 100644 --- a/src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/streaming/GrpcStreamAdmission.java +++ b/src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/streaming/GrpcStreamAdmission.java @@ -39,14 +39,15 @@ public final class GrpcStreamAdmission { if (callerFingerprint == null || callerFingerprint.isBlank()) { throw new IllegalArgumentException("stream admission needs a caller fingerprint"); } + // Global bound first: a caller refused here must not leave an empty per-caller entry behind. + if (openStreams.get() >= maxConcurrentStreams) { + return false; + } AtomicInteger callerCount = perCaller.computeIfAbsent(callerFingerprint, key -> new AtomicInteger()); if (callerCount.get() >= maxStreamsPerCaller) { return false; } - if (openStreams.get() >= maxConcurrentStreams) { - return false; - } callerCount.incrementAndGet(); openStreams.incrementAndGet(); return true; diff --git a/src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/streaming/GrpcStreamWriteResult.java b/src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/streaming/GrpcStreamWriteResult.java index 802acdbc..0063222b 100644 --- a/src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/streaming/GrpcStreamWriteResult.java +++ b/src/grpc/grpc-policy/src/main/java/dev/caskeleton/grpc/streaming/GrpcStreamWriteResult.java @@ -11,6 +11,12 @@ package dev.caskeleton.grpc.streaming; public enum GrpcStreamWriteResult { /** Queued for the single writer. Not a delivery guarantee. */ ACCEPTED, + /** + * Queued, and the producer should stop until the transport is ready again (the queue reached its + * high-water mark or the transport is not ready). Writing on regardless fills the queue to its + * bound and ends the stream. + */ + ACCEPTED_PAUSE, /** The bounded queue is full and the profile drops rather than terminates. */ DROPPED, /** The queue overflowed and the stream is being terminated. */ @@ -20,6 +26,6 @@ public enum GrpcStreamWriteResult { /** Whether the message entered the queue. */ public boolean queued() { - return this == ACCEPTED; + return this == ACCEPTED || this == ACCEPTED_PAUSE; } } diff --git a/src/grpc/grpc-policy/src/test/java/dev/caskeleton/grpc/context/GrpcContextBinderTest.java b/src/grpc/grpc-policy/src/test/java/dev/caskeleton/grpc/context/GrpcContextBinderTest.java index a97f73c8..f45ecf23 100644 --- a/src/grpc/grpc-policy/src/test/java/dev/caskeleton/grpc/context/GrpcContextBinderTest.java +++ b/src/grpc/grpc-policy/src/test/java/dev/caskeleton/grpc/context/GrpcContextBinderTest.java @@ -11,6 +11,7 @@ import dev.caskeleton.grpc.api.deadline.GrpcDeadlineBudget; import dev.caskeleton.grpc.api.deadline.GrpcDeadlineProfile; import dev.caskeleton.grpc.core.GrpcMethodName; import dev.caskeleton.grpc.core.RpcType; +import io.grpc.Context; import java.time.Duration; import java.time.Instant; import java.util.Map; @@ -19,6 +20,7 @@ import java.util.Set; import java.util.concurrent.ExecutorService; import java.util.concurrent.Executors; import java.util.concurrent.TimeUnit; +import java.util.concurrent.atomic.AtomicBoolean; import java.util.concurrent.atomic.AtomicReference; import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; @@ -156,4 +158,29 @@ class GrpcContextBinderTest { assertThat(actor).isEqualTo("actor-1"); assertThat(binder.current()).isEmpty(); } + + @Test + void wrappedWorkSeesTheSubmittingCallsCancellationOnAnotherThread() throws Exception { + // given + GrpcContextBinder binder = new GrpcContextBinder(GrpcContextPropagationPolicy.stable()); + Context.CancellableContext call = Context.current().withCancellation(); + AtomicBoolean cancelledInside = new AtomicBoolean(); + AtomicReference wrapped = new AtomicReference<>(); + call.run( + () -> + binder.runWith( + snapshot(null), + () -> + wrapped.set( + binder.wrap(() -> cancelledInside.set(Context.current().isCancelled()))))); + call.cancel(new IllegalStateException("the client went away")); + Thread worker = new Thread(wrapped.get()); + + // when + worker.start(); + worker.join(); + + // then + assertThat(cancelledInside).isTrue(); + } } diff --git a/src/grpc/grpc-policy/src/test/java/dev/caskeleton/grpc/resilience/GrpcWaitForReadyValidatorTest.java b/src/grpc/grpc-policy/src/test/java/dev/caskeleton/grpc/resilience/GrpcWaitForReadyValidatorTest.java index a5bec3b0..5bac289c 100644 --- a/src/grpc/grpc-policy/src/test/java/dev/caskeleton/grpc/resilience/GrpcWaitForReadyValidatorTest.java +++ b/src/grpc/grpc-policy/src/test/java/dev/caskeleton/grpc/resilience/GrpcWaitForReadyValidatorTest.java @@ -91,7 +91,7 @@ class GrpcWaitForReadyValidatorTest { GrpcWaitForReadyValidator.decide( policyWith(WaitForReadyPolicy.WORKER_OPT_IN), GrpcWaitForReadyProfile.worker(Duration.ofSeconds(30)), - new GrpcDeadlineBudget(Duration.ofSeconds(5), TEN_SECONDS)); + new GrpcDeadlineBudget(Duration.ofSeconds(5), TEN_SECONDS, () -> 0L)); GrpcWaitForReadyDecision tightBudget = GrpcWaitForReadyValidator.decide( policyWith(WaitForReadyPolicy.WORKER_OPT_IN), diff --git a/src/grpc/grpc-policy/src/test/java/dev/caskeleton/grpc/security/GrpcCredentialRotationManagerTest.java b/src/grpc/grpc-policy/src/test/java/dev/caskeleton/grpc/security/GrpcCredentialRotationManagerTest.java new file mode 100644 index 00000000..85c8cd0f --- /dev/null +++ b/src/grpc/grpc-policy/src/test/java/dev/caskeleton/grpc/security/GrpcCredentialRotationManagerTest.java @@ -0,0 +1,91 @@ +package dev.caskeleton.grpc.security; + +import static org.assertj.core.api.Assertions.assertThat; + +import java.time.Duration; +import java.time.Instant; +import java.util.concurrent.CyclicBarrier; +import java.util.concurrent.ExecutorService; +import java.util.concurrent.Executors; +import java.util.concurrent.Future; +import java.util.function.Consumer; +import org.junit.jupiter.api.Test; + +class GrpcCredentialRotationManagerTest { + + private static final Instant NOW = Instant.parse("2026-08-30T10:00:00Z"); + private static final int ROUNDS = 20_000; + + @Test + void racingRotationsNeverLeaveAnOlderGenerationCurrent() throws Exception { + // when + long lowest = + lowestCurrentAfterRacing( + manager -> rotateIgnoringRefusal(manager, 3L), manager -> manager.rotate(gen(4L), NOW)); + + // then + assertThat(lowest).isEqualTo(4L); + } + + @Test + void aDrainCompletedDuringARotationNeverRevertsTheNewGeneration() throws Exception { + // when + long lowest = + lowestCurrentAfterRacing( + manager -> manager.rotate(gen(3L), NOW), GrpcCredentialRotationManager::completeDrain); + + // then + assertThat(lowest).isEqualTo(3L); + } + + /** + * Starts each round at generation 2 (draining 1), runs {@code first} and {@code second} at the + * same moment, and returns the lowest generation left current over all rounds. + */ + private static long lowestCurrentAfterRacing( + Consumer first, Consumer second) + throws Exception { + ExecutorService pool = Executors.newFixedThreadPool(2); + try { + long lowest = Long.MAX_VALUE; + for (int round = 0; round < ROUNDS; round++) { + GrpcCredentialRotationManager manager = + new GrpcCredentialRotationManager(gen(1L), Duration.ofSeconds(30)); + manager.rotate(gen(2L), NOW); + CyclicBarrier start = new CyclicBarrier(2); + Future a = pool.submit(() -> run(start, first, manager)); + Future b = pool.submit(() -> run(start, second, manager)); + a.get(); + b.get(); + lowest = Math.min(lowest, manager.current().generation()); + } + return lowest; + } finally { + pool.shutdownNow(); + } + } + + private static Void run( + CyclicBarrier start, + Consumer action, + GrpcCredentialRotationManager manager) + throws Exception { + start.await(); + action.accept(manager); + return null; + } + + /** The losing rotator of a race is refused, which is the correct outcome, not a failure. */ + private static void rotateIgnoringRefusal(GrpcCredentialRotationManager manager, long next) { + try { + manager.rotate(gen(next), NOW); + } catch (IllegalArgumentException refused) { + // superseded by the other rotator + } + } + + private static GrpcCredentialGeneration gen(long generation) { + return new GrpcCredentialGeneration( + generation, "vault://v" + generation, NOW, NOW.plusSeconds(3600)); + } +} diff --git a/src/grpc/grpc-policy/src/test/java/dev/caskeleton/grpc/streaming/GrpcSerializedStreamWriterTest.java b/src/grpc/grpc-policy/src/test/java/dev/caskeleton/grpc/streaming/GrpcSerializedStreamWriterTest.java index 7976eea2..767142e1 100644 --- a/src/grpc/grpc-policy/src/test/java/dev/caskeleton/grpc/streaming/GrpcSerializedStreamWriterTest.java +++ b/src/grpc/grpc-policy/src/test/java/dev/caskeleton/grpc/streaming/GrpcSerializedStreamWriterTest.java @@ -9,6 +9,7 @@ import java.util.concurrent.CountDownLatch; import java.util.concurrent.ExecutorService; import java.util.concurrent.Executors; import java.util.concurrent.TimeUnit; +import java.util.concurrent.atomic.AtomicInteger; import java.util.concurrent.atomic.AtomicLong; import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; @@ -23,7 +24,7 @@ class GrpcSerializedStreamWriterTest { private GrpcSerializedStreamWriter writer( GrpcFlowControlPolicy policy, long messageSize) { return new GrpcSerializedStreamWriter<>( - STREAM, GrpcStreamSequence.forNewStream(STREAM), policy, sent::add, () -> messageSize); + STREAM, GrpcStreamSequence.forNewStream(STREAM), policy, sent::add, payload -> messageSize); } @Test @@ -38,7 +39,7 @@ class GrpcSerializedStreamWriterTest { assertThat(result.queued()).isTrue(); assertThat(sent).isEmpty(); - assertThat(writer.flush()).containsExactly(1L); + assertThat(writer.flush(() -> true)).containsExactly(1L); assertThat(sent).hasSize(1); } @@ -76,7 +77,7 @@ class GrpcSerializedStreamWriterTest { } assertThat(sent).isEmpty(); - List flushed = writer.flush(); + List flushed = writer.flush(() -> true); assertThat(flushed).hasSize(producers * perProducer); assertThat(flushed).isSorted(); assertThat(flushed).doesNotHaveDuplicates(); @@ -121,7 +122,7 @@ class GrpcSerializedStreamWriterTest { GrpcStreamSequence.forNewStream(STREAM), new GrpcFlowControlPolicy(10, 1000L, 9, GrpcSlowConsumerPolicy.DROP_OLDEST), sent::add, - nextSize::get); + payload -> nextSize.get()); nextSize.set(900L); assertThat(writer.write(GrpcStreamEnvelope.Kind.LIVE, "large", null, null, true)) @@ -149,7 +150,7 @@ class GrpcSerializedStreamWriterTest { GrpcStreamSequence.forNewStream(STREAM), new GrpcFlowControlPolicy(10, 700L, 9, GrpcSlowConsumerPolicy.DROP_OLDEST), sent::add, - nextSize::get); + payload -> nextSize.get()); writer.write(GrpcStreamEnvelope.Kind.LIVE, "first", null, null, true); writer.write(GrpcStreamEnvelope.Kind.LIVE, "second", null, null, true); @@ -179,7 +180,7 @@ class GrpcSerializedStreamWriterTest { void cancellingKeepsTheLastFlushedPositionAsEvidence() { GrpcSerializedStreamWriter writer = writer(GrpcFlowControlPolicy.stable(), 8L); writer.write(GrpcStreamEnvelope.Kind.LIVE, "first", null, null, true); - writer.flush(); + writer.flush(() -> true); writer.write(GrpcStreamEnvelope.Kind.LIVE, "second", null, null, true); long lastFlushed = writer.discardQueued(); @@ -189,4 +190,54 @@ class GrpcSerializedStreamWriterTest { assertThat(writer.queuedMessages()).isZero(); assertThat(sent).hasSize(1); } + + @Test + void theByteBoundCountsEachPayloadsOwnSize() { + // given + GrpcSerializedStreamWriter writer = + new GrpcSerializedStreamWriter<>( + STREAM, + GrpcStreamSequence.forNewStream(STREAM), + new GrpcFlowControlPolicy(10, 10L, 9, GrpcSlowConsumerPolicy.TERMINATE), + sent::add, + payload -> payload.length()); + writer.write(GrpcStreamEnvelope.Kind.LIVE, "eight-by", null, null, true); + + // when + GrpcStreamWriteResult result = + writer.write(GrpcStreamEnvelope.Kind.LIVE, "four", null, null, true); + + // then + assertThat(result).isEqualTo(GrpcStreamWriteResult.OVERFLOW_TERMINATING); + } + + @Test + void aWriteWhileTheTransportIsNotReadyTellsTheProducerToPause() { + // given + GrpcSerializedStreamWriter writer = writer(GrpcFlowControlPolicy.stable(), 8L); + + // when + GrpcStreamWriteResult result = + writer.write(GrpcStreamEnvelope.Kind.LIVE, "row", null, null, false); + + // then + assertThat(result) + .extracting(r -> r, GrpcStreamWriteResult::queued) + .containsExactly(GrpcStreamWriteResult.ACCEPTED_PAUSE, true); + } + + @Test + void flushStopsWhenTheTransportStopsBeingReady() { + // given + GrpcSerializedStreamWriter writer = writer(GrpcFlowControlPolicy.stable(), 8L); + writer.write(GrpcStreamEnvelope.Kind.LIVE, "first", null, null, true); + writer.write(GrpcStreamEnvelope.Kind.LIVE, "second", null, null, true); + AtomicInteger readyChecks = new AtomicInteger(); + + // when + List flushed = writer.flush(() -> readyChecks.getAndIncrement() == 0); + + // then + assertThat(flushed).containsExactly(1L); + } } diff --git a/src/grpc/grpc-policy/src/test/java/dev/caskeleton/grpc/streaming/GrpcStreamAdmissionConcurrencyTest.java b/src/grpc/grpc-policy/src/test/java/dev/caskeleton/grpc/streaming/GrpcStreamAdmissionConcurrencyTest.java index 8849c52e..f335220b 100644 --- a/src/grpc/grpc-policy/src/test/java/dev/caskeleton/grpc/streaming/GrpcStreamAdmissionConcurrencyTest.java +++ b/src/grpc/grpc-policy/src/test/java/dev/caskeleton/grpc/streaming/GrpcStreamAdmissionConcurrencyTest.java @@ -45,4 +45,17 @@ class GrpcStreamAdmissionConcurrencyTest { assertThat(admission.trackedCallers()).isZero(); } } + + @Test + void aCallerRefusedByTheGlobalBoundLeavesNoTrackedEntry() { + // given + GrpcStreamAdmission admission = new GrpcStreamAdmission(1, 1); + admission.tryAdmit("first"); + + // when + admission.tryAdmit("refused"); + + // then + assertThat(admission.trackedCallers()).isOne(); + } } diff --git a/src/grpc/grpc-server/src/main/java/dev/caskeleton/grpc/server/GrpcAdmissionController.java b/src/grpc/grpc-server/src/main/java/dev/caskeleton/grpc/server/GrpcAdmissionController.java index c25f67a2..a6b346c9 100644 --- a/src/grpc/grpc-server/src/main/java/dev/caskeleton/grpc/server/GrpcAdmissionController.java +++ b/src/grpc/grpc-server/src/main/java/dev/caskeleton/grpc/server/GrpcAdmissionController.java @@ -1,7 +1,5 @@ package dev.caskeleton.grpc.server; -import java.util.concurrent.atomic.AtomicInteger; - /** * Refuses work the server cannot do, before it spends anything on it. * @@ -14,9 +12,12 @@ public final class GrpcAdmissionController { private final int maxConcurrentCalls; private final int maxQueuedCalls; - private final AtomicInteger inFlight = new AtomicInteger(); - private final AtomicInteger queued = new AtomicInteger(); - private final AtomicInteger rejected = new AtomicInteger(); + + // One lock for both counters: every decision reads one and changes the other, and a check on an + // atomic followed by an increment lets racing callers all pass the same check. + private int inFlight; + private int queued; + private int rejected; /** Bounds concurrency and queueing separately. */ public GrpcAdmissionController(int maxConcurrentCalls, int maxQueuedCalls) { @@ -48,56 +49,54 @@ public final class GrpcAdmissionController { } /** Admits a call, queues it, or refuses it. */ - public Decision tryAdmit() { - int running = inFlight.get(); - if (running < maxConcurrentCalls) { - inFlight.incrementAndGet(); - return new Decision(true, inFlight.get(), queued.get(), "within the concurrency bound"); + public synchronized Decision tryAdmit() { + if (inFlight < maxConcurrentCalls) { + inFlight++; + return new Decision(true, inFlight, queued, "within the concurrency bound"); } - int waiting = queued.get(); - if (waiting < maxQueuedCalls) { - queued.incrementAndGet(); - return new Decision(true, running, queued.get(), "queued within the admission bound"); + if (queued < maxQueuedCalls) { + queued++; + return new Decision(true, inFlight, queued, "queued within the admission bound"); } - rejected.incrementAndGet(); + rejected++; return new Decision( false, - running, - waiting, + inFlight, + queued, "at capacity: " - + running + + inFlight + " in flight and " - + waiting + + queued + " queued. Refusing is better than accepting work whose caller will have given up."); } /** Moves a queued call into execution. */ - public void promoteFromQueue() { - if (queued.get() > 0) { - queued.decrementAndGet(); - inFlight.incrementAndGet(); + public synchronized void promoteFromQueue() { + if (queued > 0) { + queued--; + inFlight++; } } /** Releases a finished call. */ - public void release() { - if (inFlight.get() > 0) { - inFlight.decrementAndGet(); + public synchronized void release() { + if (inFlight > 0) { + inFlight--; } } /** How many calls are executing. */ - public int inFlight() { - return inFlight.get(); + public synchronized int inFlight() { + return inFlight; } /** How many calls are waiting. */ - public int queued() { - return queued.get(); + public synchronized int queued() { + return queued; } /** How many calls have been refused. */ - public int rejected() { - return rejected.get(); + public synchronized int rejected() { + return rejected; } } diff --git a/src/grpc/grpc-server/src/test/java/dev/caskeleton/grpc/server/GrpcAdmissionControllerTest.java b/src/grpc/grpc-server/src/test/java/dev/caskeleton/grpc/server/GrpcAdmissionControllerTest.java new file mode 100644 index 00000000..895fdf56 --- /dev/null +++ b/src/grpc/grpc-server/src/test/java/dev/caskeleton/grpc/server/GrpcAdmissionControllerTest.java @@ -0,0 +1,55 @@ +package dev.caskeleton.grpc.server; + +import static org.assertj.core.api.Assertions.assertThat; + +import java.util.ArrayList; +import java.util.List; +import java.util.concurrent.CyclicBarrier; +import java.util.concurrent.ExecutorService; +import java.util.concurrent.Executors; +import java.util.concurrent.Future; +import org.junit.jupiter.api.Test; + +class GrpcAdmissionControllerTest { + + private static final int CALLERS = 8; + private static final int ROUNDS = 500; + + @Test + void racingCallersNeverGetPastTheConcurrencyAndQueueBounds() throws Exception { + // when + int mostAdmitted = mostAdmittedOverRounds(); + + // then + assertThat(mostAdmitted).isEqualTo(2); + } + + /** Races {@link #CALLERS} callers at a 1-running, 1-queued controller, round after round. */ + private static int mostAdmittedOverRounds() throws Exception { + ExecutorService pool = Executors.newFixedThreadPool(CALLERS); + try { + int most = 0; + for (int round = 0; round < ROUNDS; round++) { + GrpcAdmissionController controller = new GrpcAdmissionController(1, 1); + CyclicBarrier start = new CyclicBarrier(CALLERS); + List> admitted = new ArrayList<>(); + for (int caller = 0; caller < CALLERS; caller++) { + admitted.add( + pool.submit( + () -> { + start.await(); + return controller.tryAdmit().admitted(); + })); + } + int count = 0; + for (Future result : admitted) { + count += result.get() ? 1 : 0; + } + most = Math.max(most, count); + } + return most; + } finally { + pool.shutdownNow(); + } + } +} diff --git a/src/messaging/messaging-inbox-jdbc-postgresql/src/integrationTest/java/dev/caskeleton/messaging/inbox/InboxPostgresIT.java b/src/messaging/messaging-inbox-jdbc-postgresql/src/integrationTest/java/dev/caskeleton/messaging/inbox/InboxPostgresIT.java index 367a6f5b..899707c0 100644 --- a/src/messaging/messaging-inbox-jdbc-postgresql/src/integrationTest/java/dev/caskeleton/messaging/inbox/InboxPostgresIT.java +++ b/src/messaging/messaging-inbox-jdbc-postgresql/src/integrationTest/java/dev/caskeleton/messaging/inbox/InboxPostgresIT.java @@ -151,7 +151,7 @@ class InboxPostgresIT { MessageId purged = MessageId.newId(); inTransaction(() -> repository.reserve(purged, "order-projection", NOW)); - assertThat(repository.purgeProcessedBefore(NOW.plusSeconds(1))).isEqualTo(1); + assertThat(repository.purgeProcessedBefore(NOW.plusSeconds(1), 100)).isEqualTo(1); } /** Reserves and writes inside one Spring transaction, exactly as an idempotent consumer must. */ diff --git a/src/messaging/messaging-inbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/inbox/InboxCleanupJob.java b/src/messaging/messaging-inbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/inbox/InboxCleanupJob.java index fbeda2e7..6baceae9 100644 --- a/src/messaging/messaging-inbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/inbox/InboxCleanupJob.java +++ b/src/messaging/messaging-inbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/inbox/InboxCleanupJob.java @@ -53,10 +53,10 @@ public final class InboxCleanupJob { int removed = 0; for (int batch = 0; batch < maxBatches; batch++) { - int deleted = inbox.purgeProcessedBefore(cutoff); + int deleted = inbox.purgeProcessedBefore(cutoff, DEFAULT_BATCH_SIZE); removed += deleted; // A short batch means the backlog is drained; continuing would just re-scan an empty range. - if (deleted == 0) { + if (deleted < DEFAULT_BATCH_SIZE) { break; } } diff --git a/src/messaging/messaging-inbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/inbox/JdbcInboxRepository.java b/src/messaging/messaging-inbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/inbox/JdbcInboxRepository.java index 1ac930c8..d941d739 100644 --- a/src/messaging/messaging-inbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/inbox/JdbcInboxRepository.java +++ b/src/messaging/messaging-inbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/inbox/JdbcInboxRepository.java @@ -167,18 +167,4 @@ public final class JdbcInboxRepository implements InboxRepository { "INBOX_PURGE_FAILED", "a bounded inbox purge failed", exception); } } - - @Override - public int purgeProcessedBefore(Instant processedBefore) { - Objects.requireNonNull(processedBefore, "processedBefore must not be null"); - try (Connection connection = dataSource.getConnection(); - PreparedStatement statement = - connection.prepareStatement("DELETE FROM messaging_inbox WHERE processed_at < ?")) { - statement.setTimestamp(1, Timestamp.from(processedBefore)); - return statement.executeUpdate(); - } catch (SQLException exception) { - throw new MessagingConfigurationException( - "INBOX_PURGE_FAILED", "could not purge the inbox", exception); - } - } } diff --git a/src/messaging/messaging-inbox-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/inbox/IdempotentConsumerTest.java b/src/messaging/messaging-inbox-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/inbox/IdempotentConsumerTest.java index 013fe846..b4331a66 100644 --- a/src/messaging/messaging-inbox-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/inbox/IdempotentConsumerTest.java +++ b/src/messaging/messaging-inbox-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/inbox/IdempotentConsumerTest.java @@ -82,7 +82,7 @@ class IdempotentConsumerTest { void retentionPruningRemovesOldRows() { consumer.runOnce(MessageId.newId(), "order-projection", NOW, () -> "done"); - assertThat(inbox.purgeProcessedBefore(NOW.plusSeconds(1))).isEqualTo(1); + assertThat(inbox.purgeProcessedBefore(NOW.plusSeconds(1), 100)).isEqualTo(1); assertThat(inbox.size()).isZero(); } } @@ -104,12 +104,7 @@ final class InMemoryInbox implements InboxRepository { @Override public int purgeProcessedBefore(Instant processedBefore, int limit) { - return Math.min(purgeProcessedBefore(processedBefore), limit); - } - - @Override - public int purgeProcessedBefore(Instant processedBefore) { - int removed = reserved.size(); + int removed = Math.min(reserved.size(), limit); reserved.clear(); return removed; } diff --git a/src/messaging/messaging-inbox-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/inbox/InboxOperationsTest.java b/src/messaging/messaging-inbox-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/inbox/InboxOperationsTest.java index 17409b1a..b8228346 100644 --- a/src/messaging/messaging-inbox-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/inbox/InboxOperationsTest.java +++ b/src/messaging/messaging-inbox-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/inbox/InboxOperationsTest.java @@ -42,15 +42,13 @@ class InboxOperationsTest { return reserved.contains(messageId.value() + "|" + consumerId); } - @Override - public int purgeProcessedBefore(Instant processedBefore, int limit) { - return Math.min(purgeProcessedBefore(processedBefore), limit); - } + private final List limits = new ArrayList<>(); @Override - public int purgeProcessedBefore(Instant processedBefore) { + public int purgeProcessedBefore(Instant processedBefore, int limit) { cutoffs.add(processedBefore); - return pass < deletions.size() ? deletions.get(pass++) : 0; + limits.add(limit); + return Math.min(pass < deletions.size() ? deletions.get(pass++) : 0, limit); } } @@ -91,14 +89,17 @@ class InboxOperationsTest { } @Test - void cleanupDeletesInBoundedBatches() { + void cleanupAsksForBoundedBatchesAndStopsAtTheFirstShortOne() { + // given InMemoryInbox inbox = new InMemoryInbox(List.of(1000, 500)); - int removed = - new InboxCleanupJob(inbox, policy(Duration.ofDays(7), Duration.ofDays(1)), 10).runOnce(NOW); + // when + new InboxCleanupJob(inbox, policy(Duration.ofDays(7), Duration.ofDays(1)), 10).runOnce(NOW); - assertThat(removed).isEqualTo(1500); - assertThat(inbox.cutoffs).hasSize(3); + // then + assertThat(inbox.limits) + .as("DEFAULT_BATCH_SIZE was declared and never passed to the repository") + .containsExactly(InboxCleanupJob.DEFAULT_BATCH_SIZE, InboxCleanupJob.DEFAULT_BATCH_SIZE); } @Test diff --git a/src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrar.java b/src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrar.java index c285b5c4..9bfec581 100644 --- a/src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrar.java +++ b/src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrar.java @@ -66,6 +66,35 @@ public final class KafkaConsumerRegistrar implements TransportConsumerRegistrati private final KafkaQuarantinePublisher quarantine; + private final java.time.InstantSource clock; + + /** The shortest wait before a failed delivery is read again, whatever the policy computes. */ + private static final Duration MIN_RETRY_DELAY = Duration.ofSeconds(1); + + private static final dev.caskeleton.messaging.policy.BackoffCalculator BACKOFF = + new dev.caskeleton.messaging.policy.BackoffCalculator(); + + /** A delivery that failed, by where it sits in the log. */ + private record FailedOffset(TopicPartition partition, long offset) {} + + /** + * How many times each offset has failed without being settled. + * + *

    Pause-and-seek re-reads the same record, so the envelope's own attempt header never moves; + * the count has to live here. Without it a poison message was retried with no delay and no limit, + * and its partition never advanced again. + */ + private final Map failures = new ConcurrentHashMap<>(); + + /** + * Partitions paused because a record could not be dispatched — the ceiling was reached, the + * runtime was draining, or the pool refused. Poll thread only. + * + *

    They were paused and never resumed: an ordered partition handed two records by one poll ran + * the first and then stopped reading for good. + */ + private final Set saturated = new java.util.HashSet<>(); + private final Map committed = new ConcurrentHashMap<>(); /** @@ -127,8 +156,38 @@ public final class KafkaConsumerRegistrar implements TransportConsumerRegistrati GracefulShutdownCoordinator shutdown, Duration pollTimeout, KafkaQuarantinePublisher quarantine) { + this( + spec, + consumer, + handlerPool, + shutdown, + pollTimeout, + quarantine, + java.time.InstantSource.system()); + } + + /** A consumer runtime with the clock retry delays are measured on, for tests. */ + KafkaConsumerRegistrar( + TransportConsumerSpec spec, + Consumer consumer, + Executor handlerPool, + GracefulShutdownCoordinator shutdown, + Duration pollTimeout, + KafkaQuarantinePublisher quarantine, + java.time.InstantSource clock) { + this.clock = Objects.requireNonNull(clock, "clock must not be null"); this.quarantine = Objects.requireNonNull(quarantine, "quarantine must not be null"); this.spec = Objects.requireNonNull(spec, "spec must not be null"); + if (spec.profile().production() && quarantine == KafkaQuarantinePublisher.unavailable()) { + // Without somewhere to park a message that keeps failing, its partition retries it forever + // and nothing behind it is ever read. + throw new dev.caskeleton.messaging.api.error.MessagingConfigurationException( + "KAFKA_QUARANTINE_REQUIRED", + "production destination " + + spec.profile().name().value() + + " needs a KafkaQuarantinePublisher; without one a message that exhausts its" + + " attempts stops its partition for good"); + } this.consumer = Objects.requireNonNull(consumer, "consumer must not be null"); this.handlerPool = Objects.requireNonNull(handlerPool, "handlerPool must not be null"); this.shutdown = Objects.requireNonNull(shutdown, "shutdown must not be null"); @@ -169,6 +228,8 @@ public final class KafkaConsumerRegistrar implements TransportConsumerRegistrati coordinator.forget(partition); retries.forget(partition); committed.remove(partition); + saturated.remove(partition); + failures.keySet().removeIf(failed -> failed.partition().equals(partition)); }); } @@ -199,6 +260,7 @@ public final class KafkaConsumerRegistrar implements TransportConsumerRegistrati syncEpochs(); applySettlements(); applyDueResumes(now); + resumeSaturated(); commitContiguous(); if (!shutdown.isAcceptingWork()) { @@ -251,6 +313,7 @@ public final class KafkaConsumerRegistrar implements TransportConsumerRegistrati // Only this partition pauses. Its earliest unsubmitted offset is where it resumes. consumer.pause(Set.of(partition)); consumer.seek(partition, seekBackTo); + saturated.add(partition); } } return dispatched; @@ -283,7 +346,7 @@ public final class KafkaConsumerRegistrar implements TransportConsumerRegistrati if (quarantine.quarantine(record, undecodable)) { settlement.acknowledgeAfterQuarantine(); } else { - settlement.requeueAfterFailure(); + settlement.requeueAfterFailure(record, undecodable); } coordinator.release(partition); shutdown.endWork(); @@ -308,37 +371,36 @@ public final class KafkaConsumerRegistrar implements TransportConsumerRegistrati handler = spec.sink().apply(delivery).toCompletableFuture(); handler.get(handlerTimeout.toMillis(), java.util.concurrent.TimeUnit.MILLISECONDS); } catch (java.util.concurrent.TimeoutException timedOut) { - // A timed-out handler may still be applying side effects. Cancel it before releasing - // the partition permit; otherwise the same offset can be dispatched again while the - // first handler is still running. + // A timed-out handler may still be applying side effects, and cancelling the + // CompletableFuture does not stop it — it only completes the stage this worker holds, + // which released the permit and let the same offset run again beside the first. So + // the slot stays taken until the handler really finishes, and only then is a delivery + // it left unsettled requeued. java.util.concurrent.CompletableFuture timedOutHandler = handler; - settlement.requeueAfterFailure(); - if (timedOutHandler != null - && !timedOutHandler.cancel(true) - && !timedOutHandler.isDone()) { - releaseImmediately = false; - java.util.concurrent.CompletableFuture releaseAfterCompletion = - timedOutHandler.whenComplete( - (ignored, failure) -> { - coordinator.release(partition); - shutdown.endWork(); - }); - // Keep the continuation strongly referenced through this worker frame. The - // completion action owns the delayed permit/work-count release; its own result is - // intentionally not joined here. - Objects.requireNonNull(releaseAfterCompletion); - } + releaseImmediately = false; + java.util.concurrent.CompletableFuture releaseAfterCompletion = + timedOutHandler.whenComplete( + (ignored, failure) -> { + settlement.requeueAfterFailure( + record, failure == null ? timedOut : failure); + coordinator.release(partition); + shutdown.endWork(); + }); + // Keep the continuation strongly referenced through this worker frame. The + // completion action owns the delayed permit/work-count release; its own result is + // intentionally not joined here. + Objects.requireNonNull(releaseAfterCompletion); } catch (InterruptedException interrupted) { Thread.currentThread().interrupt(); if (handler != null) { handler.cancel(true); } - settlement.requeueAfterFailure(); + settlement.requeueAfterFailure(record, interrupted); } catch (java.util.concurrent.ExecutionException | RuntimeException failure) { // A handler failure is retried, not parked. PARKED completed the offset without any // quarantine or dead-letter write, so a transient database outage silently discarded // every message it touched. - settlement.requeueAfterFailure(); + settlement.requeueAfterFailure(record, failure); } finally { if (releaseImmediately) { coordinator.release(partition); @@ -365,7 +427,10 @@ public final class KafkaConsumerRegistrar implements TransportConsumerRegistrati continue; } switch (command.kind()) { - case COMPLETE, PARKED -> offsets.completed(command.partition(), command.offset()); + case COMPLETE, PARKED -> { + offsets.completed(command.partition(), command.offset()); + failures.remove(new FailedOffset(command.partition(), command.offset())); + } case PAUSE_AND_SEEK -> { coordinator.pause(command.partition()); consumer.pause(Set.of(command.partition())); @@ -391,6 +456,22 @@ public final class KafkaConsumerRegistrar implements TransportConsumerRegistrati current.forEach( partition -> epochs.computeIfAbsent(partition, key -> epochSequence.incrementAndGet())); epochs.keySet().removeIf(partition -> !current.contains(partition)); + saturated.retainAll(current); + } + + /** Resumes a partition paused for lack of a slot once it has one and nothing else holds it. */ + private void resumeSaturated() { + int ceiling = spec.profile().consumer().maxInFlightPerOrderingUnit(); + saturated.removeIf( + partition -> { + if (coordinator.isPaused(partition) + || retries.isPaused(partition) + || coordinator.inFlight(partition) >= ceiling) { + return false; + } + consumer.resume(Set.of(partition)); + return true; + }); } private void applyDueResumes(Instant now) { @@ -603,16 +684,36 @@ public final class KafkaConsumerRegistrar implements TransportConsumerRegistrati } } - /** Used by the worker when the handler failed or timed out and never settled. */ - private void requeueAfterFailure() { + /** + * Used by the worker when the handler failed or timed out and never settled. + * + *

    Retried after the destination's backoff, never sooner than {@code MIN_RETRY_DELAY}; once + * the attempt budget is spent the record is written to quarantine and committed past. When + * there is no quarantine it keeps being retried — the offset may not advance past a message + * that exists nowhere else — which is why a production destination must have one. + */ + private void requeueAfterFailure(ConsumerRecord record, Throwable reason) { + if (terminal.get() != null) { + // The handler settled before it failed or before its late completion; that answer stands. + return; + } + FailedOffset key = new FailedOffset(partition, offset); + int attempt = failures.merge(key, 1, Integer::sum); + dev.caskeleton.messaging.policy.RetryPolicy retry = spec.profile().retry(); + if (attempt >= retry.maxAttempts() && quarantine.quarantine(record, reason)) { + failures.remove(key); + acknowledgeAfterQuarantine(); + return; + } if (terminal.compareAndSet(null, "requeue")) { - enqueueRequeue(Duration.ZERO); + Duration backoff = BACKOFF.delayFor(retry, attempt); + enqueueRequeue(backoff.compareTo(MIN_RETRY_DELAY) < 0 ? MIN_RETRY_DELAY : backoff); } } private dev.caskeleton.messaging.api.settlement.SettlementResult enqueueRequeue( Duration delay) { - retries.pauseUntil(partition, offset, delay, Instant.now()); + retries.pauseUntil(partition, offset, delay, clock.instant()); settlements.enqueue( new KafkaSettlementCommand( partition, offset, KafkaSettlementCommand.Kind.PAUSE_AND_SEEK, epoch)); diff --git a/src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaQuarantinePublisher.java b/src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaQuarantinePublisher.java index bdb43659..20489c95 100644 --- a/src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaQuarantinePublisher.java +++ b/src/messaging/messaging-kafka/src/main/java/dev/caskeleton/messaging/kafka/KafkaQuarantinePublisher.java @@ -24,8 +24,21 @@ public interface KafkaQuarantinePublisher { */ boolean quarantine(ConsumerRecord record, Throwable reason); - /** The default: nothing is configured, so nothing may be committed past. */ + /** + * The default: nothing is configured, so nothing may be committed past. + * + *

    One instance, so a consumer can tell it apart from a configured quarantine and refuse it on + * a production destination. + */ static KafkaQuarantinePublisher unavailable() { - return (record, reason) -> false; + return Unavailable.INSTANCE; + } + + /** Holds the single "not configured" quarantine. */ + final class Unavailable { + + private static final KafkaQuarantinePublisher INSTANCE = (record, reason) -> false; + + private Unavailable() {} } } diff --git a/src/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrarTest.java b/src/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrarTest.java index 941abf34..db4e105f 100644 --- a/src/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrarTest.java +++ b/src/messaging/messaging-kafka/src/test/java/dev/caskeleton/messaging/kafka/KafkaConsumerRegistrarTest.java @@ -4,6 +4,9 @@ import static org.assertj.core.api.Assertions.assertThat; import dev.caskeleton.messaging.api.MessageId; import dev.caskeleton.messaging.api.header.ReservedHeaders; +import dev.caskeleton.messaging.policy.OrderingImpact; +import dev.caskeleton.messaging.policy.RetryMode; +import dev.caskeleton.messaging.policy.RetryPolicy; import dev.caskeleton.messaging.transport.GracefulShutdownCoordinator; import dev.caskeleton.messaging.transport.TransportConsumerSpec; import dev.caskeleton.messaging.transport.TransportDelivery; @@ -154,51 +157,165 @@ class KafkaConsumerRegistrarTest { } @Test - void handlerTimeoutCancelsTheOutstandingHandlerBeforeThePartitionPermitIsReleased() { - CompletableFuture handler = new CompletableFuture<>(); - dev.caskeleton.messaging.policy.DestinationProfile base = KafkaContractHarness.profile(); - dev.caskeleton.messaging.policy.DestinationProfile fastTimeout = - new dev.caskeleton.messaging.policy.DestinationProfile( - base.name(), - base.broker(), - base.kind(), - base.physical(), - base.schema(), - base.deliveryGuarantee(), - base.orderingScope(), - base.externalSideEffectGuarantee(), - base.producer(), - new dev.caskeleton.messaging.policy.ConsumerPolicy( - base.consumer().group(), - base.consumer().concurrency(), - base.consumer().maxInFlightPerOrderingUnit(), - base.consumer().prefetch(), - Duration.ofMillis(5), - base.consumer().manualSettlement()), - base.retry(), - base.deadLetter(), - base.payload(), - base.tier(), - base.production(), - base.keyResolverConfigured(), - base.topologyAutoCreate()); - + void aTimedOutHandlerStillRunningIsNotDispatchedASecondTime() { + // given + Instant start = Instant.now(); + CompletableFuture stillRunning = new CompletableFuture<>(); KafkaConsumerRegistrar registrar = - new KafkaConsumerRegistrar( - new TransportConsumerSpec(fastTimeout, delivery -> handler), - consumer, - handlers, - new GracefulShutdownCoordinator(Duration.ofSeconds(30)), - Duration.ofMillis(1)); + registrar( + profile(Duration.ofMillis(5), RetryPolicy.none(), false), + delivery -> { + handled.add(delivery); + return stillRunning; + }, + KafkaQuarantinePublisher.unavailable(), + () -> start); + assign(); + addRecord(10); + registrar.pollOnce(start); + handlers.runAll(); + // What the broker serves again if the consumer seeks back to the timed-out offset. + addRecord(10); + // when + registrar.pollOnce(start.plusSeconds(60)); + handlers.runAll(); + + // then + assertThat(handled) + .as("cancelling a CompletableFuture does not stop the handler behind it") + .hasSize(1); + } + + @Test + void aTimedOutHandlerIsRedeliveredOnceItFinishesWithoutSettling() { + // given + CompletableFuture stillRunning = new CompletableFuture<>(); + KafkaConsumerRegistrar registrar = + registrar( + profile(Duration.ofMillis(5), RetryPolicy.none(), false), + delivery -> { + handled.add(delivery); + return stillRunning; + }, + KafkaQuarantinePublisher.unavailable(), + () -> NOW); + assign(); + addRecord(10); + registrar.pollOnce(NOW); + handlers.runAll(); + stillRunning.complete(null); + addRecord(10); + + // when + registrar.pollOnce(NOW.plusSeconds(60)); + handlers.runAll(); + + // then + assertThat(handled).hasSize(2); + } + + @Test + void aFailedHandlerWaitsOutItsBackoffBeforeThePartitionIsReadAgain() { + // given + Instant start = Instant.now(); + RetryPolicy threeAttempts = + new RetryPolicy( + RetryMode.PAUSE_PARTITION, + 3, + Duration.ofSeconds(1), + Duration.ofSeconds(10), + 2.0, + false, + OrderingImpact.PRESERVE, + java.util.Set.of(), + java.util.Set.of()); + KafkaConsumerRegistrar registrar = + registrar( + profile(Duration.ofSeconds(1), threeAttempts, false), + this::fail, + KafkaQuarantinePublisher.unavailable(), + () -> start); + assign(); + addRecord(10); + registrar.pollOnce(start); + handlers.runAll(); + + // when + registrar.pollOnce(start.plusMillis(500)); + + // then + assertThat(consumer.paused()) + .as("a failure retried with no delay re-reads the same record as fast as the loop polls") + .contains(PARTITION); + } + + @Test + void aHandlerThatSpendsItsAttemptBudgetIsQuarantinedAndCommittedPast() { + // given + List quarantined = new ArrayList<>(); + KafkaConsumerRegistrar registrar = + registrar( + KafkaContractHarness.profile(), + this::fail, + (record, reason) -> quarantined.add(record.offset()), + () -> NOW); assign(); addRecord(10); registrar.pollOnce(NOW); handlers.runAll(); - assertThat(handler) - .as("a timed-out handler must be cancelled before the same partition can be redelivered") - .isCancelled(); + // when + registrar.pollOnce(NOW); + + // then + assertThat(registrar.committedOffset(PARTITION)) + .as("a poison message retried forever stops its partition for good") + .hasValue(11L); + } + + @Test + void aProductionDestinationWithoutAQuarantineIsRefused() { + // given + dev.caskeleton.messaging.policy.DestinationProfile production = + profile(Duration.ofSeconds(30), RetryPolicy.none(), true); + + // when + Throwable thrown = + org.assertj.core.api.Assertions.catchThrowable( + () -> registrar(production, this::settleImmediately)); + + // then + assertThat(thrown) + .isInstanceOf(dev.caskeleton.messaging.api.error.MessagingConfigurationException.class) + .extracting( + failure -> + ((dev.caskeleton.messaging.api.error.MessagingConfigurationException) failure) + .failure() + .code()) + .isEqualTo("KAFKA_QUARANTINE_REQUIRED"); + } + + @Test + void aPartitionPausedAtItsCeilingResumesOnceItsDeliveryFinishes() { + // given + KafkaConsumerRegistrar registrar = registrar(this::settleImmediately); + assign(); + addRecord(10); + addRecord(11); + registrar.pollOnce(NOW); + handlers.runAll(); + // The second record was returned by the first poll and handed back with a seek. + addRecord(11); + + // when + registrar.pollOnce(NOW); + handlers.runAll(); + + // then + assertThat(handled) + .as("pausing a full partition is backpressure only if something resumes it") + .hasSize(2); } @Test @@ -495,6 +612,68 @@ class KafkaConsumerRegistrarTest { Duration.ofMillis(1)); } + private KafkaConsumerRegistrar registrar( + dev.caskeleton.messaging.policy.DestinationProfile profile, + java.util.function.Function> sink) { + return new KafkaConsumerRegistrar( + new TransportConsumerSpec(profile, sink), + consumer, + handlers, + new GracefulShutdownCoordinator(Duration.ofSeconds(30)), + Duration.ofMillis(1)); + } + + private KafkaConsumerRegistrar registrar( + dev.caskeleton.messaging.policy.DestinationProfile profile, + java.util.function.Function> sink, + KafkaQuarantinePublisher quarantine, + java.time.InstantSource clock) { + return new KafkaConsumerRegistrar( + new TransportConsumerSpec(profile, sink), + consumer, + handlers, + new GracefulShutdownCoordinator(Duration.ofSeconds(30)), + Duration.ofMillis(1), + quarantine, + clock); + } + + /** The harness profile with the three settings these tests vary. */ + private static dev.caskeleton.messaging.policy.DestinationProfile profile( + Duration handlerTimeout, RetryPolicy retry, boolean production) { + dev.caskeleton.messaging.policy.DestinationProfile base = KafkaContractHarness.profile(); + return new dev.caskeleton.messaging.policy.DestinationProfile( + base.name(), + base.broker(), + base.kind(), + base.physical(), + base.schema(), + base.deliveryGuarantee(), + base.orderingScope(), + base.externalSideEffectGuarantee(), + base.producer(), + new dev.caskeleton.messaging.policy.ConsumerPolicy( + base.consumer().group(), + base.consumer().concurrency(), + base.consumer().maxInFlightPerOrderingUnit(), + base.consumer().prefetch(), + handlerTimeout, + base.consumer().manualSettlement()), + retry, + base.deadLetter(), + base.payload(), + base.tier(), + production, + base.keyResolverConfigured(), + base.topologyAutoCreate()); + } + + /** A handler that fails every delivery it is given. */ + private CompletionStage fail(TransportDelivery delivery) { + handled.add(delivery); + throw new IllegalStateException("the downstream this handler writes to is down"); + } + /** Acknowledges inside the handler, as a successful M1 delivery does. */ private CompletionStage settleImmediately(TransportDelivery delivery) { handled.add(delivery); diff --git a/src/messaging/messaging-outbox-jdbc-postgresql/src/integrationTest/java/dev/caskeleton/messaging/outbox/OutboxPostgresIT.java b/src/messaging/messaging-outbox-jdbc-postgresql/src/integrationTest/java/dev/caskeleton/messaging/outbox/OutboxPostgresIT.java index 0e2d8705..66fba44e 100644 --- a/src/messaging/messaging-outbox-jdbc-postgresql/src/integrationTest/java/dev/caskeleton/messaging/outbox/OutboxPostgresIT.java +++ b/src/messaging/messaging-outbox-jdbc-postgresql/src/integrationTest/java/dev/caskeleton/messaging/outbox/OutboxPostgresIT.java @@ -205,7 +205,7 @@ class OutboxPostgresIT { appendInTransaction(pending); repository.markPublishedUnfenced(published.messageId(), NOW); - int removed = repository.purgePublishedBefore(NOW.plusSeconds(1)); + int removed = repository.purgePublishedBefore(NOW.plusSeconds(1), 100); assertThat(removed).isEqualTo(1); assertThat(repository.find(pending.messageId())).isPresent(); @@ -217,7 +217,35 @@ class OutboxPostgresIT { OutboxCanonicalMetadata.none().withRoutingKeys("acct-1", "acct-1")); } + @Test + void aNewerRowWaitsWhileAnOlderRowWithTheSameOrderingKeyIsUnfinished() { + // given + OutboxRecord older = record(ordered("customer-42"), NOW.minusSeconds(60)); + OutboxRecord newer = record(ordered("customer-42"), NOW.minusSeconds(30)); + OutboxRecord otherKey = record(ordered("customer-7"), NOW.minusSeconds(30)); + appendInTransaction(older); + appendInTransaction(newer); + appendInTransaction(otherKey); + + // when + List claimed = repository.claimBatch("relay-a", 10, Duration.ofSeconds(30), NOW); + + // then + assertThat(claimed) + .extracting(OutboxLease::messageId) + .as("a second relay, or a retry of the older row, would put the newer one first") + .containsExactlyInAnyOrder(older.messageId(), otherKey.messageId()); + } + + private static OutboxCanonicalMetadata ordered(String key) { + return OutboxCanonicalMetadata.none().withRoutingKeys(key, key); + } + private static OutboxRecord record(OutboxCanonicalMetadata metadata) { + return record(metadata, NOW.minusSeconds(60)); + } + + private static OutboxRecord record(OutboxCanonicalMetadata metadata, Instant createdAt) { return new OutboxRecord( MessageId.newId(), new DestinationName("order-events"), @@ -227,7 +255,7 @@ class OutboxPostgresIT { "{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8), Map.of(), metadata, - NOW.minusSeconds(60), + createdAt, OutboxStatus.PENDING, 0, Optional.empty(), @@ -361,8 +389,8 @@ class OutboxPostgresIT { @Test void twoRelaysClaimingConcurrentlyGetDisjointRowsAndDistinctTokens() { - OutboxRecord one = record(); - OutboxRecord two = record(); + OutboxRecord one = record(OutboxCanonicalMetadata.none().withRoutingKeys("acct-1", "acct-1")); + OutboxRecord two = record(OutboxCanonicalMetadata.none().withRoutingKeys("acct-2", "acct-2")); appendInTransaction(one); appendInTransaction(two); diff --git a/src/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/JdbcOutboxRepository.java b/src/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/JdbcOutboxRepository.java index 44a986ad..13b87a35 100644 --- a/src/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/JdbcOutboxRepository.java +++ b/src/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/JdbcOutboxRepository.java @@ -113,17 +113,29 @@ public final class JdbcOutboxRepository implements OutboxRepository { private static final String CLAIM = """ WITH claimable AS ( - SELECT message_id - FROM messaging_outbox - WHERE status IN ('PENDING', 'AMBIGUOUS', 'IN_FLIGHT') - AND (lease_expires_at IS NULL OR lease_expires_at <= ?) + SELECT m.message_id + FROM messaging_outbox m + WHERE m.status IN ('PENDING', 'AMBIGUOUS', 'IN_FLIGHT') + AND (m.lease_expires_at IS NULL OR m.lease_expires_at <= ?) -- The retry clock lives in the row, not in the relay's memory. Without these two -- predicates an AMBIGUOUS row became claimable again on the very next pass, so a -- broker outage meant the whole backlog was republished every poll interval and the -- configured attempt budget was a number nothing consulted. - AND (next_attempt_at IS NULL OR next_attempt_at <= ?) - AND attempts < ? - ORDER BY created_at + AND (m.next_attempt_at IS NULL OR m.next_attempt_at <= ?) + AND m.attempts < ? + -- A row with an ordering key waits while an older row with the same key is still + -- unfinished. SKIP LOCKED let a second relay take the newer row while the first still + -- held the older one, and an AMBIGUOUS older row was retried after newer ones had + -- already gone out. md5 matches the partial index, which cannot hold a key that long. + AND (m.ordering_key IS NULL OR NOT EXISTS ( + SELECT 1 + FROM messaging_outbox older + WHERE older.destination = m.destination + AND md5(older.ordering_key) = md5(m.ordering_key) + AND older.ordering_key = m.ordering_key + AND older.status IN ('PENDING', 'AMBIGUOUS', 'IN_FLIGHT') + AND (older.created_at, older.message_id) < (m.created_at, m.message_id))) + ORDER BY m.created_at, m.message_id LIMIT ? FOR UPDATE SKIP LOCKED ) @@ -514,20 +526,6 @@ public final class JdbcOutboxRepository implements OutboxRepository { }); } - @Override - public int purgePublishedBefore(Instant publishedBefore) { - Objects.requireNonNull(publishedBefore, "publishedBefore must not be null"); - return withConnection( - connection -> { - try (PreparedStatement statement = - connection.prepareStatement( - "DELETE FROM messaging_outbox WHERE status = 'PUBLISHED' AND published_at < ?")) { - statement.setTimestamp(1, Timestamp.from(publishedBefore)); - return statement.executeUpdate(); - } - }); - } - private void update(String sql, MessageId messageId, Instant now, String failureCode) { withConnection( connection -> { diff --git a/src/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/OutboxCleanupJob.java b/src/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/OutboxCleanupJob.java index 2bed4fcd..5d067bd0 100644 --- a/src/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/OutboxCleanupJob.java +++ b/src/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/OutboxCleanupJob.java @@ -15,6 +15,9 @@ import java.util.Objects; */ public final class OutboxCleanupJob { + /** How many rows one delete statement removes before yielding. */ + public static final int DEFAULT_BATCH_SIZE = 1_000; + private final OutboxRepository outbox; private final OutboxProperties properties; private final int maxBatches; @@ -47,9 +50,10 @@ public final class OutboxCleanupJob { int removed = 0; for (int batch = 0; batch < maxBatches; batch++) { - int deleted = outbox.purgePublishedBefore(cutoff); + int deleted = outbox.purgePublishedBefore(cutoff, DEFAULT_BATCH_SIZE); removed += deleted; - if (deleted == 0) { + // A short batch means the backlog is drained; asking again would re-scan an empty range. + if (deleted < DEFAULT_BATCH_SIZE) { break; } } diff --git a/src/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/OutboxRelay.java b/src/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/OutboxRelay.java index 64decb80..52350c57 100644 --- a/src/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/OutboxRelay.java +++ b/src/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/OutboxRelay.java @@ -1,9 +1,16 @@ package dev.caskeleton.messaging.outbox; +import dev.caskeleton.messaging.api.MessageEnvelope; import dev.caskeleton.messaging.api.destination.MessageDestination; +import dev.caskeleton.messaging.api.error.FailureCategory; +import dev.caskeleton.messaging.api.error.FailureDescriptor; +import dev.caskeleton.messaging.api.error.MessagingException; import dev.caskeleton.messaging.api.publish.MessagePublisher; +import dev.caskeleton.messaging.api.publish.PublishCompletion; +import dev.caskeleton.messaging.api.publish.PublishEvidence; import dev.caskeleton.messaging.api.publish.PublishOptions; import dev.caskeleton.messaging.api.publish.PublishResult; +import dev.caskeleton.messaging.api.publish.RoutingOutcome; import dev.caskeleton.messaging.reliability.OutboxLease; import dev.caskeleton.messaging.reliability.OutboxRecord; import dev.caskeleton.messaging.reliability.OutboxRepository; @@ -13,6 +20,7 @@ import java.time.Duration; import java.time.Instant; import java.util.List; import java.util.Objects; +import java.util.Optional; /** * Publishes outbox rows, treating an unknown outcome as retryable rather than final. @@ -165,7 +173,22 @@ public final class OutboxRelay { for (OutboxLease lease : batch) { OutboxRecord record = lease.record(); - PublishResult result = publish(record); + MessageEnvelope envelope; + try { + envelope = envelopeFactory.toEnvelope(record); + } catch (RuntimeException unpublishable) { + // A row that cannot become an envelope never will. Thrown out of the pass, it took the + // rest of the batch with it: those rows stayed IN_FLIGHT until their lease expired, and the + // same row was claimed and thrown again on the next pass, forever. + if (repository.markFailed(lease, failureCode(unpublishable), now) + == OutboxTransitionResult.APPLIED) { + failed++; + } else { + stale++; + } + continue; + } + PublishResult result = publish(record, envelope); switch (result.completion()) { case CONFIRMED -> { if (repository.markPublished(lease, now) == OutboxTransitionResult.APPLIED) { @@ -220,12 +243,35 @@ public final class OutboxRelay { return new OutboxRelayReport(batch.size(), published, ambiguous, failed, stale, exhausted); } - private PublishResult publish(OutboxRecord record) { + private PublishResult publish(OutboxRecord record, MessageEnvelope envelope) { MessageDestination destination = new MessageDestination<>(record.destination(), record.messageType(), EncodedMessage.class); - return publisher - .publish(destination, envelopeFactory.toEnvelope(record), PublishOptions.defaults()) - .toCompletableFuture() - .join(); + try { + return publisher + .publish(destination, envelope, PublishOptions.defaults()) + .toCompletableFuture() + .join(); + } catch (RuntimeException unknown) { + // An exception says nothing about whether the broker took the message, so the row is retried + // under the same id like any other unknown outcome — not failed, not left IN_FLIGHT. + return new PublishResult( + PublishCompletion.AMBIGUOUS, + PublishEvidence.ambiguous(), + RoutingOutcome.UNKNOWN, + Optional.empty(), + 1, + Duration.ZERO, + Optional.of( + FailureDescriptor.of( + FailureCategory.AMBIGUOUS, + "PUBLISH_OUTCOME_UNKNOWN", + "the publisher threw " + unknown.getClass().getSimpleName()))); + } + } + + private static String failureCode(RuntimeException failure) { + return failure instanceof MessagingException known + ? known.failure().code() + : "OUTBOX_ROW_UNPUBLISHABLE"; } } diff --git a/src/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/OutboxRelayWorker.java b/src/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/OutboxRelayWorker.java index 5a3ac4c0..5de58c6c 100644 --- a/src/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/OutboxRelayWorker.java +++ b/src/messaging/messaging-outbox-jdbc-postgresql/src/main/java/dev/caskeleton/messaging/outbox/OutboxRelayWorker.java @@ -34,6 +34,8 @@ public final class OutboxRelayWorker implements AutoCloseable { /** How long {@link #close()} waits for a running pass when no deadline is given. */ public static final Duration DEFAULT_DRAIN_DEADLINE = Duration.ofSeconds(30); + private static final System.Logger LOG = System.getLogger(OutboxRelayWorker.class.getName()); + private final OutboxRelay relay; private final OutboxRetryScheduler scheduler; @@ -184,9 +186,14 @@ public final class OutboxRelayWorker implements AutoCloseable { } catch (RuntimeException passFailed) { // A failed pass must not stop the loop: the scheduled task's own exception would cancel every // future pass, turning one broker error into a relay that never runs again. The failure is - // counted and the next pass backs off as if nothing was published, which is true. - failedPasses.incrementAndGet(); + // counted and the next pass backs off as if nothing was published, which is true. It is also + // logged: counted silently, a relay failing every pass looked exactly like an idle one. + long failures = failedPasses.incrementAndGet(); unproductive = unproductivePasses.incrementAndGet(); + LOG.log( + System.Logger.Level.WARNING, + "outbox relay pass failed (" + failures + " failed so far); retrying with backoff", + passFailed); } completedPasses.incrementAndGet(); schedule(scheduler.backoff(unproductive)); diff --git a/src/messaging/messaging-outbox-jdbc-postgresql/src/main/resources/db/migration/messaging/V1005__messaging_outbox_ordering_key_index.sql b/src/messaging/messaging-outbox-jdbc-postgresql/src/main/resources/db/migration/messaging/V1005__messaging_outbox_ordering_key_index.sql new file mode 100644 index 00000000..f62af018 --- /dev/null +++ b/src/messaging/messaging-outbox-jdbc-postgresql/src/main/resources/db/migration/messaging/V1005__messaging_outbox_ordering_key_index.sql @@ -0,0 +1,9 @@ +-- The claim now holds back a row while an older, unfinished row shares its destination and +-- ordering key. That check runs once per candidate row, so it needs an index or every claim scans +-- the backlog once per row it considers. +-- +-- md5 of the key rather than the key: ordering_key is VARCHAR(1024), and a long multi-byte key +-- would exceed the btree entry limit and fail the business transaction that appends the row. +CREATE INDEX ix_messaging_outbox_unfinished_ordering_key + ON messaging_outbox (destination, md5(ordering_key), created_at) + WHERE ordering_key IS NOT NULL AND status IN ('PENDING', 'AMBIGUOUS', 'IN_FLIGHT'); diff --git a/src/messaging/messaging-outbox-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/outbox/OutboxOperationsTest.java b/src/messaging/messaging-outbox-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/outbox/OutboxOperationsTest.java index f7df5cbf..7eb3f0ac 100644 --- a/src/messaging/messaging-outbox-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/outbox/OutboxOperationsTest.java +++ b/src/messaging/messaging-outbox-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/outbox/OutboxOperationsTest.java @@ -96,15 +96,13 @@ class OutboxOperationsTest { throw new UnsupportedOperationException(); } - @Override - public int purgePublishedBefore(Instant publishedBefore, int limit) { - return Math.min(purgePublishedBefore(publishedBefore), limit); - } + private final List limits = new ArrayList<>(); @Override - public int purgePublishedBefore(Instant publishedBefore) { + public int purgePublishedBefore(Instant publishedBefore, int limit) { cutoffs.add(publishedBefore); - return pass < deletions.size() ? deletions.get(pass++) : 0; + limits.add(limit); + return Math.min(pass < deletions.size() ? deletions.get(pass++) : 0, limit); } } @@ -130,13 +128,20 @@ class OutboxOperationsTest { } @Test - void cleanupDeletesInBoundedBatchesRatherThanOneLongStatement() { + void cleanupAsksForBoundedBatchesAndStopsAtTheFirstShortOne() { + // given RecordingRepository repository = new RecordingRepository(List.of(1000, 1000, 250)); - int removed = new OutboxCleanupJob(repository, OutboxProperties.defaults(), 10).runOnce(NOW); + // when + new OutboxCleanupJob(repository, OutboxProperties.defaults(), 10).runOnce(NOW); - assertThat(removed).isEqualTo(2250); - assertThat(repository.cutoffs).hasSize(4); + // then + assertThat(repository.limits) + .as("one DELETE over the whole backlog holds its locks for as long as the backlog is big") + .containsExactly( + OutboxCleanupJob.DEFAULT_BATCH_SIZE, + OutboxCleanupJob.DEFAULT_BATCH_SIZE, + OutboxCleanupJob.DEFAULT_BATCH_SIZE); } @Test diff --git a/src/messaging/messaging-outbox-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/outbox/OutboxRelayTest.java b/src/messaging/messaging-outbox-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/outbox/OutboxRelayTest.java index 3a8256ab..8749e0b6 100644 --- a/src/messaging/messaging-outbox-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/outbox/OutboxRelayTest.java +++ b/src/messaging/messaging-outbox-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/outbox/OutboxRelayTest.java @@ -86,6 +86,49 @@ class OutboxRelayTest { .isEqualTo(OutboxStatus.PUBLISHED); } + @Test + void aRowThatCannotBecomeAnEnvelopeFailsWhileTheRestOfItsBatchPublishes() { + // given + OutboxRecord poison = OutboxFixtures.withHeaders(Map.of("msg.id", "forged")); + OutboxRecord healthy = OutboxFixtures.pending(); + repository.append(poison); + repository.append(healthy); + + // when + relay(RecordingOutboxPublisher.confirming()).runOnce(NOW); + + // then + assertThat(List.of(poison, healthy)) + .extracting(row -> repository.find(row.messageId()).orElseThrow().status()) + .as("one bad row threw out of the pass and held the whole batch until its lease expired") + .containsExactly(OutboxStatus.FAILED, OutboxStatus.PUBLISHED); + } + + @Test + void aPublisherThatThrowsLeavesTheRowAmbiguousRatherThanStrandingTheBatch() { + // given + OutboxRecord first = OutboxFixtures.pending(); + repository.append(first); + MessagePublisher throwing = + new MessagePublisher() { + @Override + public CompletionStage publish( + MessageDestination destination, + MessageEnvelope message, + PublishOptions options) { + throw new IllegalStateException("the broker connection is gone"); + } + }; + + // when + relay(throwing).runOnce(NOW); + + // then + assertThat(repository.find(first.messageId()).orElseThrow().status()) + .as("an exception says nothing about whether the broker took the message") + .isEqualTo(OutboxStatus.AMBIGUOUS); + } + @Test void anAmbiguousPublishStaysRetryableRatherThanFailing() { OutboxRecord record = OutboxFixtures.pending(); @@ -263,6 +306,10 @@ final class OutboxFixtures { private OutboxFixtures() {} static OutboxRecord pending() { + return withHeaders(Map.of()); + } + + static OutboxRecord withHeaders(Map headers) { return new OutboxRecord( MessageId.newId(), new DestinationName("order-events"), @@ -270,7 +317,7 @@ final class OutboxFixtures { new SchemaVersion(1), ContentType.JSON, "{\"orderId\":\"o-1\"}".getBytes(StandardCharsets.UTF_8), - Map.of(), + headers, dev.caskeleton.messaging.reliability.OutboxCanonicalMetadata.none(), Instant.parse("2026-08-10T09:14:00Z"), OutboxStatus.PENDING, @@ -455,14 +502,9 @@ final class InMemoryOutboxRepository implements OutboxRepository { @Override public int purgePublishedBefore(Instant publishedBefore, int limit) { - return Math.min(purgePublishedBefore(publishedBefore), limit); - } - - @Override - public int purgePublishedBefore(Instant publishedBefore) { int before = rows.size(); rows.values().removeIf(record -> record.status() == OutboxStatus.PUBLISHED); - return before - rows.size(); + return Math.min(before - rows.size(), limit); } private void transition(MessageId messageId, OutboxStatus status, Optional failureCode) { diff --git a/src/messaging/messaging-outbox-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/outbox/OutboxRelayWorkerTest.java b/src/messaging/messaging-outbox-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/outbox/OutboxRelayWorkerTest.java index cadc6792..9f71564c 100644 --- a/src/messaging/messaging-outbox-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/outbox/OutboxRelayWorkerTest.java +++ b/src/messaging/messaging-outbox-jdbc-postgresql/src/test/java/dev/caskeleton/messaging/outbox/OutboxRelayWorkerTest.java @@ -79,8 +79,7 @@ class OutboxRelayWorkerTest { @Test @DisplayName("a pass that throws does not stop every pass after it") void aFailedPassDoesNotEndTheLoop() throws InterruptedException { - repository.append(OutboxFixtures.pending()); - OutboxRelayWorker worker = worker(new ThrowingPublisher()); + OutboxRelayWorker worker = worker(unreachableDatabase(), new ThrowingPublisher()); worker.start(); try { @@ -99,9 +98,25 @@ class OutboxRelayWorkerTest { } private OutboxRelayWorker worker(MessagePublisher publisher) { + return worker(repository, publisher); + } + + /** An outbox whose every call fails, as it does while its database is down. */ + private static dev.caskeleton.messaging.reliability.OutboxRepository unreachableDatabase() { + return (dev.caskeleton.messaging.reliability.OutboxRepository) + java.lang.reflect.Proxy.newProxyInstance( + OutboxRelayWorkerTest.class.getClassLoader(), + new Class[] {dev.caskeleton.messaging.reliability.OutboxRepository.class}, + (proxy, method, arguments) -> { + throw new IllegalStateException("the outbox database is unreachable"); + }); + } + + private static OutboxRelayWorker worker( + dev.caskeleton.messaging.reliability.OutboxRepository outbox, MessagePublisher publisher) { OutboxRelay relay = new OutboxRelay( - repository, + outbox, publisher, new OutboxEnvelopeFactory(new ProducerId("order-api")), 100, diff --git a/src/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/InFlightLimiter.java b/src/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/InFlightLimiter.java index 30ef288e..e15b7e64 100644 --- a/src/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/InFlightLimiter.java +++ b/src/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/InFlightLimiter.java @@ -50,7 +50,20 @@ public final class InFlightLimiter { * @throws InterruptedException when the waiting thread is interrupted */ public boolean tryAcquire() throws InterruptedException { - return permits.tryAcquire(maxWait.toNanos(), TimeUnit.NANOSECONDS); + return tryAcquire(maxWait); + } + + /** + * Tries to acquire one permit, waiting no longer than the configured bound or the given budget. + * + * @param budget what the caller has left to spend on the wait + * @return true when a permit was acquired + * @throws InterruptedException when the waiting thread is interrupted + */ + public boolean tryAcquire(Duration budget) throws InterruptedException { + Objects.requireNonNull(budget, "budget must not be null"); + long wait = Math.max(0, Math.min(maxWait.toNanos(), budget.toNanos())); + return permits.tryAcquire(wait, TimeUnit.NANOSECONDS); } /** Returns one permit to the pool. */ diff --git a/src/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/MessagingAdmissionController.java b/src/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/MessagingAdmissionController.java index 4b2cc984..118f9989 100644 --- a/src/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/MessagingAdmissionController.java +++ b/src/messaging/messaging-policy/src/main/java/dev/caskeleton/messaging/policy/MessagingAdmissionController.java @@ -73,7 +73,24 @@ public final class MessagingAdmissionController { * @throws MessageBackpressureException when shutting down or no permit became available */ public void admit(String destination, int payloadBytes) { + admit(destination, payloadBytes, java.time.Duration.ofNanos(Long.MAX_VALUE)); + } + + /** + * Admits one publish, waiting for a permit no longer than the caller has left. + * + *

    The limiter's own bound was the only one: a publish with a 100ms deadline could block its + * caller for the limiter's full wait before the deadline was even consulted. + * + * @param destination the logical destination name + * @param payloadBytes the encoded payload size + * @param budget the most this call may wait for a permit + * @throws MessageTooLargeException when the payload exceeds the destination limit + * @throws MessageBackpressureException when shutting down or no permit became available + */ + public void admit(String destination, int payloadBytes, java.time.Duration budget) { Objects.requireNonNull(destination, "destination must not be null"); + Objects.requireNonNull(budget, "budget must not be null"); payloadGuard.checkPayload(destination, payloadBytes); if (!acceptingNewWork) { @@ -91,7 +108,7 @@ public final class MessagingAdmissionController { boolean acquired; try { - acquired = limiter.tryAcquire(); + acquired = limiter.tryAcquire(budget); } catch (InterruptedException interrupted) { // The destination slot was taken a moment ago and no publish will use it, so it goes back // here: a slot leaked per interruption shrinks the destination's ceiling until it is zero. diff --git a/src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/InboxRepository.java b/src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/InboxRepository.java index a438805a..55846b4e 100644 --- a/src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/InboxRepository.java +++ b/src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/InboxRepository.java @@ -34,19 +34,11 @@ public interface InboxRepository { boolean isProcessed(MessageId messageId, String consumerId); /** - * Deletes records older than a cutoff. + * Deletes at most {@code limit} processed rows older than the cutoff. * *

    Retention must outlive the broker's maximum redelivery window, otherwise a late redelivery * arrives after its inbox row was pruned and is processed a second time. * - * @param processedBefore the retention cutoff - * @return how many rows were removed - */ - int purgeProcessedBefore(Instant processedBefore); - - /** - * Deletes at most {@code limit} processed rows older than the cutoff. - * * @return how many rows were deleted; fewer than {@code limit} means the sweep is finished */ int purgeProcessedBefore(Instant processedBefore, int limit); diff --git a/src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/OutboxRepository.java b/src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/OutboxRepository.java index 6552a3b1..8197a2c8 100644 --- a/src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/OutboxRepository.java +++ b/src/messaging/messaging-reliability-api/src/main/java/dev/caskeleton/messaging/reliability/OutboxRepository.java @@ -94,22 +94,12 @@ public interface OutboxRepository { */ Optional find(MessageId messageId); - /** - * Deletes records published before a cutoff. - * - * @param publishedBefore the retention cutoff - * @return how many rows were removed - */ - int purgePublishedBefore(Instant publishedBefore); - /** * Deletes at most {@code limit} published rows older than the cutoff. * - *

    The unbounded version deletes everything before the cutoff in one statement. On a table that - * has been accumulating published rows since the last sweep that is a single long transaction - * holding locks and generating WAL in proportion to the backlog, which shows up as the relay and - * the business writes stalling behind retention. The cleanup jobs describe themselves as bounded - * by batch size; this is the parameter that makes that true. + *

    There is no unbounded version. Deleting everything before the cutoff in one statement is a + * single long transaction holding locks and generating WAL in proportion to the backlog, which + * shows up as the relay and the business writes stalling behind retention. * * @return how many rows were deleted; fewer than {@code limit} means the sweep is finished */ diff --git a/src/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisher.java b/src/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisher.java index fe59a3ed..46c75462 100644 --- a/src/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisher.java +++ b/src/messaging/messaging-runtime-core/src/main/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisher.java @@ -224,7 +224,16 @@ public final class DefaultMessagePublisher implements MessagePublisher, EncodedM startedAt); } - admission.admit(destination.name().value(), encoded.payload().bytes().length); + // Refusals are results, not exceptions. They were thrown out of publish() on the caller's + // thread, so a CompletionStage caller — the outbox relay, the reactive facade — saw neither a + // REJECTED result nor a failed stage. The permit wait is bounded by what is left of the + // caller's deadline, not by the limiter's own bound. + try { + admission.admit(destination.name().value(), encoded.payload().bytes().length, remaining); + } catch (dev.caskeleton.messaging.api.error.MessageTooLargeException + | dev.caskeleton.messaging.api.error.MessageBackpressureException refused) { + return refused(refused.failure(), startedAt); + } MessagingRuntimeLease lease = null; try { lease = runtimes.acquire(profile.broker()); @@ -316,6 +325,12 @@ public final class DefaultMessagePublisher implements MessagePublisher, EncodedM } private CompletionStage rejected(String code, String reason, long startedAt) { + return refused( + new FailureDescriptor(FailureCategory.CONFIGURATION, code, false, reason, Optional.empty()), + startedAt); + } + + private CompletionStage refused(FailureDescriptor failure, long startedAt) { return CompletableFuture.completedFuture( new PublishResult( PublishCompletion.REJECTED, @@ -324,9 +339,7 @@ public final class DefaultMessagePublisher implements MessagePublisher, EncodedM Optional.empty(), 1, elapsedSince(startedAt), - Optional.of( - new FailureDescriptor( - FailureCategory.CONFIGURATION, code, false, reason, Optional.empty())))); + Optional.of(failure))); } private PublishResult ambiguousResult(String code, String reason, long startedAt) { diff --git a/src/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisherTest.java b/src/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisherTest.java index 5302ed6d..4ac4854b 100644 --- a/src/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisherTest.java +++ b/src/messaging/messaging-runtime-core/src/test/java/dev/caskeleton/messaging/runtime/DefaultMessagePublisherTest.java @@ -312,6 +312,89 @@ class DefaultMessagePublisherTest { assertThat(admission.inFlight()).isZero(); } + @Test + void anOversizedPayloadIsRejectedAsNotRetryableInsteadOfThrown() { + // given + DefaultMessagePublisher publisher = + new DefaultMessagePublisher( + registry(), + allowOrders(), + new SingleCodecRegistry(), + new MessagingAdmissionController( + new PayloadLimitGuard(new PayloadPolicy(4, 4)), + new InFlightLimiter(4, Duration.ofSeconds(1))), + new FixedRuntimeRegistry(transport), + transport); + + // when + CompletableFuture result = + CompletableFuture.supplyAsync( + () -> + publisher + .publish( + new MessageDestination<>( + ORDERS, new MessageType("order.created"), String.class), + envelope(), + PublishOptions.defaults()) + .toCompletableFuture() + .join()); + + // then + assertThat(result) + .succeedsWithin(Duration.ofSeconds(5)) + .extracting( + PublishResult::completion, outcome -> outcome.failure().orElseThrow().retryable()) + .containsExactly(PublishCompletion.REJECTED, false); + } + + @Test + void aSaturatedPermitPoolRejectsAsRetryableWithinTheCallersDeadline() { + // given + DestinationName audit = new DestinationName("audit-events"); + DefaultMessagePublisher publisher = + new DefaultMessagePublisher( + DestinationProfileRegistry.of( + Map.of( + ORDERS, + RuntimeFixtures.profile(ORDERS), + audit, + RuntimeFixtures.profile(audit))), + new DestinationAccessPolicy( + java.util.Set.of(ORDERS, audit), java.util.Set.of(), java.util.Set.of()), + new SingleCodecRegistry(), + new MessagingAdmissionController( + new PayloadLimitGuard(PayloadPolicy.defaults()), + new InFlightLimiter(1, Duration.ofMinutes(1))), + new FixedRuntimeRegistry(transport), + transport); + transport.stall(); + publisher.publish( + new MessageDestination<>(ORDERS, new MessageType("order.created"), String.class), + envelope(), + withTimeout(Duration.ofMinutes(1))); + + // when + CompletableFuture second = + CompletableFuture.supplyAsync( + () -> + publisher + .publish( + new MessageDestination<>( + audit, new MessageType("order.created"), String.class), + envelope(), + withTimeout(Duration.ofMillis(100))) + .toCompletableFuture() + .join()); + + // then + assertThat(second) + .as("the permit wait was the limiter's own minute, not what was left of 100ms") + .succeedsWithin(Duration.ofSeconds(5)) + .extracting( + PublishResult::completion, outcome -> outcome.failure().orElseThrow().retryable()) + .containsExactly(PublishCompletion.REJECTED, true); + } + @Test @DisplayName("an unavailable runtime releases the permit it took") void anUnavailableRuntimeReleasesThePermit() { diff --git a/src/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaMessagingAutoConfiguration.java b/src/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaMessagingAutoConfiguration.java index e4eea401..49a1ccb8 100644 --- a/src/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaMessagingAutoConfiguration.java +++ b/src/messaging/messaging-spring-boot-starter-kafka/src/main/java/dev/caskeleton/messaging/autoconfigure/KafkaMessagingAutoConfiguration.java @@ -121,15 +121,14 @@ public class KafkaMessagingAutoConfiguration { /** * The producer this transport publishes through (MSG-INT-003). * - *

    Built from Spring Boot's own {@code spring.kafka.bootstrap-servers} rather than from a - * second description on {@code app.messaging.*}. One broker described twice is the defect this - * repository has already paid for in {@code app.jpa-platform.datasource.*}, and the - * operator-facing property for "where is Kafka" is the one they already know. + *

    Built from the one {@code app.messaging.brokers.} entry of type {@code kafka}. It used + * to read {@code spring.kafka.bootstrap-servers} while the compiler required and validated the + * entry's own {@code bootstrap-servers}, so one broker was described twice and only one of the + * two descriptions reached the client. * *

    Byte-array serializers on purpose: the platform's codec registry decides the wire format, * and a serializer configured here would be a second encoder disagreeing with it. * - * @param environment the resolved environment * @param compiled the broker and security profiles compiled from {@code app.messaging} * @param declaredSecurity the security profiles the application declared as beans * @param securityConfigurer the Kafka security configurer, present only with a credential source @@ -138,45 +137,75 @@ public class KafkaMessagingAutoConfiguration { @Bean(destroyMethod = "close") @ConditionalOnMissingBean public org.apache.kafka.clients.producer.Producer messagingKafkaProducer( - org.springframework.core.env.Environment environment, CompiledMessagingConfiguration compiled, ObjectProvider declaredSecurity, ObjectProvider securityConfigurer) { return new org.apache.kafka.clients.producer.KafkaProducer<>( - producerConfig(environment, compiled, declaredSecurity, securityConfigurer)); + producerConfig(compiled, declaredSecurity, securityConfigurer)); } /** The producer's client configuration; package-visible so a test can read what it holds. */ static java.util.Map producerConfig( - org.springframework.core.env.Environment environment, CompiledMessagingConfiguration compiled, ObjectProvider declaredSecurity, ObjectProvider securityConfigurer) { - String bootstrapServers = environment.getProperty("spring.kafka.bootstrap-servers", "").trim(); - if (bootstrapServers.isEmpty()) { - throw new IllegalStateException( - "app.messaging.broker=kafka needs spring.kafka.bootstrap-servers; a producer with no " - + "broker address defaults to localhost:9092 and fails at the first publish rather " - + "than at startup"); - } + BrokerSettings broker = kafkaBroker(compiled); java.util.Map config = new java.util.HashMap<>(); config.put( org.apache.kafka.clients.producer.ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, - bootstrapServers); + String.join(",", broker.bootstrapServers())); config.put( org.apache.kafka.clients.producer.ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, org.apache.kafka.common.serialization.ByteArraySerializer.class); config.put( org.apache.kafka.clients.producer.ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, org.apache.kafka.common.serialization.ByteArraySerializer.class); - // Durability is not a default worth inheriting: acks=1 loses an accepted publish to a leader - // failover, which is exactly the outcome an outbox exists to prevent. - config.put(org.apache.kafka.clients.producer.ProducerConfig.ACKS_CONFIG, "all"); - config.put(org.apache.kafka.clients.producer.ProducerConfig.ENABLE_IDEMPOTENCE_CONFIG, true); + // The entry's delivery settings, which KafkaProfileValidator checks (a stable broker must keep + // acks=all and idempotence) and which used to be replaced here by hard-coded values. + config.put(org.apache.kafka.clients.producer.ProducerConfig.ACKS_CONFIG, broker.acks()); + config.put( + org.apache.kafka.clients.producer.ProducerConfig.ENABLE_IDEMPOTENCE_CONFIG, + broker.enableIdempotence()); + config.put( + org.apache.kafka.clients.producer.ProducerConfig.MAX_IN_FLIGHT_REQUESTS_PER_CONNECTION, + broker.maxInFlightRequestsPerConnection()); + // Kafka refuses delivery.timeout.ms below linger.ms + request.timeout.ms (5ms + 30s by + // default), which made the documented 30s a startup failure. The request timeout follows a + // short delivery deadline down, and records are not held back to fill a batch. + long delivery = broker.deliveryTimeout().toMillis(); + config.put(org.apache.kafka.clients.producer.ProducerConfig.LINGER_MS_CONFIG, 0); + config.put( + org.apache.kafka.clients.producer.ProducerConfig.REQUEST_TIMEOUT_MS_CONFIG, + Math.toIntExact(Math.min(30_000L, delivery))); + config.put( + org.apache.kafka.clients.producer.ProducerConfig.DELIVERY_TIMEOUT_MS_CONFIG, + Math.toIntExact(delivery)); + // send() blocks the caller while it waits for metadata or buffer space, for Kafka's default + // 60s — before the publish deadline is even applied. Bounded by the default deadline instead. + config.put( + org.apache.kafka.clients.producer.ProducerConfig.MAX_BLOCK_MS_CONFIG, + dev.caskeleton.messaging.api.publish.PublishOptions.defaults().timeout().toMillis()); config.putAll(producerSecurity(compiled, declaredSecurity, securityConfigurer)); return config; } + /** The one Kafka broker entry the producer connects to. */ + private static BrokerSettings kafkaBroker(CompiledMessagingConfiguration compiled) { + java.util.List kafka = + compiled.brokers().values().stream() + .filter(broker -> BrokerSettings.KAFKA.equalsIgnoreCase(broker.type())) + .toList(); + if (kafka.size() != 1) { + throw new IllegalStateException( + "app.messaging.broker=kafka needs exactly one app.messaging.brokers. entry with" + + " type kafka and its bootstrap-servers; found " + + kafka.size() + + ". A producer with no broker address defaults to localhost:9092 and fails at the" + + " first publish rather than at startup"); + } + return kafka.getFirst(); + } + /** * The producer's security properties, from the one security profile of the Kafka broker. * diff --git a/src/messaging/messaging-spring-boot-starter/src/integrationTest/java/dev/caskeleton/messaging/autoconfigure/MessagingLiveRoundTripQualificationTest.java b/src/messaging/messaging-spring-boot-starter/src/integrationTest/java/dev/caskeleton/messaging/autoconfigure/MessagingLiveRoundTripQualificationTest.java index 4edfe2bf..65c43408 100644 --- a/src/messaging/messaging-spring-boot-starter/src/integrationTest/java/dev/caskeleton/messaging/autoconfigure/MessagingLiveRoundTripQualificationTest.java +++ b/src/messaging/messaging-spring-boot-starter/src/integrationTest/java/dev/caskeleton/messaging/autoconfigure/MessagingLiveRoundTripQualificationTest.java @@ -77,7 +77,8 @@ class MessagingLiveRoundTripQualificationTest { .withPropertyValues( "app.messaging.enabled=true", "app.messaging.broker=kafka", - "spring.kafka.bootstrap-servers=" + KAFKA.getBootstrapServers()) + "app.messaging.brokers.kafka.type=kafka", + "app.messaging.brokers.kafka.bootstrap-servers[0]=" + KAFKA.getBootstrapServers()) // Both, because ValidatedDestinationRegistry refuses a profile whose dead-letter target is // not itself registered — a good invariant, and one a fixture declaring only the happy path // walks straight into. diff --git a/src/messaging/messaging-spring-boot-starter/src/integrationTest/java/dev/caskeleton/messaging/autoconfigure/MessagingSecuredBrokerQualificationTest.java b/src/messaging/messaging-spring-boot-starter/src/integrationTest/java/dev/caskeleton/messaging/autoconfigure/MessagingSecuredBrokerQualificationTest.java index 5d34659d..5e823a32 100644 --- a/src/messaging/messaging-spring-boot-starter/src/integrationTest/java/dev/caskeleton/messaging/autoconfigure/MessagingSecuredBrokerQualificationTest.java +++ b/src/messaging/messaging-spring-boot-starter/src/integrationTest/java/dev/caskeleton/messaging/autoconfigure/MessagingSecuredBrokerQualificationTest.java @@ -159,7 +159,6 @@ class MessagingSecuredBrokerQualificationTest { .withPropertyValues( "app.messaging.enabled=true", "app.messaging.broker=kafka", - "spring.kafka.bootstrap-servers=" + kafka.getBootstrapServers(), "app.messaging.brokers.kafka.type=kafka", "app.messaging.brokers.kafka.bootstrap-servers[0]=" + kafka.getBootstrapServers(), "app.messaging.brokers.kafka.tls-enabled=true", diff --git a/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/DefaultReactiveMessagePublisher.java b/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/DefaultReactiveMessagePublisher.java index a17c0e37..5c3a25be 100644 --- a/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/DefaultReactiveMessagePublisher.java +++ b/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/DefaultReactiveMessagePublisher.java @@ -34,6 +34,10 @@ public final class DefaultReactiveMessagePublisher implements ReactiveMessagePub Objects.requireNonNull(destination, "destination must not be null"); Objects.requireNonNull(message, "message must not be null"); Objects.requireNonNull(options, "options must not be null"); - return Mono.fromCompletionStage(() -> delegate.publish(destination, message, options)); + // publish() is not purely asynchronous: admission may wait for a permit and the Kafka producer + // may wait for metadata before the stage exists. Subscribing on a Netty event loop would pin + // that loop for the wait, so the call runs on the bounded elastic pool instead. + return Mono.fromCompletionStage(() -> delegate.publish(destination, message, options)) + .subscribeOn(reactor.core.scheduler.Schedulers.boundedElastic()); } } diff --git a/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingReliabilityAutoConfiguration.java b/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingReliabilityAutoConfiguration.java index 72350ccb..0fa0d2df 100644 --- a/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingReliabilityAutoConfiguration.java +++ b/src/messaging/messaging-spring-boot-starter/src/main/java/dev/caskeleton/messaging/autoconfigure/MessagingReliabilityAutoConfiguration.java @@ -109,6 +109,33 @@ public class MessagingReliabilityAutoConfiguration { return new OutboxRelayWorker(relay, scheduler); } + /** + * Publishes the relay's failed-pass count when a meter registry exists. + * + *

    {@code failedPasses()} was counted and read by nothing, so a relay failing every pass looked + * on every dashboard exactly like one with nothing to do. + * + * @param worker the relay worker + * @param registries the meter registry, when the application has one + * @return the registration, run once the context has the registry + */ + @Bean + @ConditionalOnBean(OutboxRelayWorker.class) + public org.springframework.beans.factory.InitializingBean outboxRelayMeters( + OutboxRelayWorker worker, + org.springframework.beans.factory.ObjectProvider + registries) { + return () -> + registries.ifAvailable( + registry -> + io.micrometer.core.instrument.FunctionCounter.builder( + "messaging.outbox.relay.failed.passes", + worker, + OutboxRelayWorker::failedPasses) + .description("Outbox relay passes that ended in an exception") + .register(registry)); + } + /** * Binds the relay worker to the context lifecycle. * diff --git a/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/BrokerAccessListTest.java b/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/BrokerAccessListTest.java index fef555dd..936c7108 100644 --- a/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/BrokerAccessListTest.java +++ b/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/BrokerAccessListTest.java @@ -38,7 +38,6 @@ class BrokerAccessListTest { .withPropertyValues( "app.messaging.enabled=true", "app.messaging.broker=kafka", - "spring.kafka.bootstrap-servers=localhost:9092", "app.messaging.brokers.kafka-primary.type=kafka", "app.messaging.brokers.kafka-primary.bootstrap-servers[0]=localhost:9092", "app.messaging.security.kafka-primary.producer.type=SASL_SCRAM", diff --git a/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaProducerConfigTest.java b/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaProducerConfigTest.java new file mode 100644 index 00000000..643a088a --- /dev/null +++ b/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaProducerConfigTest.java @@ -0,0 +1,96 @@ +package dev.caskeleton.messaging.autoconfigure; + +import static org.assertj.core.api.Assertions.assertThat; + +import dev.caskeleton.messaging.api.publish.PublishOptions; +import dev.caskeleton.messaging.kafka.KafkaSecurityConfigurer; +import dev.caskeleton.messaging.security.BrokerSecurityProfile; +import java.util.Map; +import org.junit.jupiter.api.Test; +import org.springframework.boot.autoconfigure.AutoConfigurations; +import org.springframework.boot.test.context.assertj.AssertableApplicationContext; +import org.springframework.boot.test.context.runner.ApplicationContextRunner; + +/** + * Where the producer connects and how it delivers come from the one broker entry. + * + *

    The producer read {@code spring.kafka.bootstrap-servers} while the compiler required and + * validated {@code app.messaging.brokers..bootstrap-servers}, so a broker was described twice + * and only one description was used. The entry's delivery settings were validated and then replaced + * by hard-coded values. + */ +class KafkaProducerConfigTest { + + private final ApplicationContextRunner runner = + new ApplicationContextRunner() + .withConfiguration(AutoConfigurations.of(MessagingPlatformRootAutoConfiguration.class)) + .withPropertyValues( + "app.messaging.enabled=true", + "app.messaging.broker=kafka", + "app.messaging.brokers.kafka-primary.type=kafka", + // Resolvable names: the client refuses an address it cannot look up at construction. + "app.messaging.brokers.kafka-primary.bootstrap-servers[0]=localhost:9093", + "app.messaging.brokers.kafka-primary.bootstrap-servers[1]=127.0.0.1:9094"); + + @Test + void theProducerConnectsToTheBrokerEntryAddressesNotToSpringKafka() { + runner + .withPropertyValues("spring.kafka.bootstrap-servers=elsewhere:9092") + .run( + context -> + assertThat(producerConfig(context).get("bootstrap.servers")) + .isEqualTo("localhost:9093,127.0.0.1:9094")); + } + + @Test + void theProducerAppliesTheBrokerEntryDeliverySettings() { + runner + .withPropertyValues( + "app.messaging.brokers.kafka-primary.enable-idempotence=false", + "app.messaging.brokers.kafka-primary.acks=1", + "app.messaging.brokers.kafka-primary.max-in-flight-requests-per-connection=3", + "app.messaging.brokers.kafka-primary.delivery-timeout=45s") + .run( + context -> + assertThat(producerConfig(context)) + .extractingByKeys( + "enable.idempotence", + "acks", + "max.in.flight.requests.per.connection", + "delivery.timeout.ms") + .containsExactly(false, "1", 3, 45_000)); + } + + @Test + void theProducerStopsWaitingForMetadataWithinTheDefaultPublishDeadline() { + runner.run( + context -> + assertThat(producerConfig(context).get("max.block.ms")) + .as("the caller's thread waited up to Kafka's own 60s before any deadline applied") + .isEqualTo(PublishOptions.defaults().timeout().toMillis())); + } + + @Test + void aBrokerWithoutAnEntryFailsStartupNamingTheKey() { + new ApplicationContextRunner() + .withConfiguration(AutoConfigurations.of(MessagingPlatformRootAutoConfiguration.class)) + .withPropertyValues( + "app.messaging.enabled=true", + "app.messaging.broker=kafka", + "spring.kafka.bootstrap-servers=localhost:9092") + .run( + context -> + assertThat(context) + .hasFailed() + .getFailure() + .rootCause() + .hasMessageContaining("app.messaging.brokers. entry with type kafka")); + } + + private static Map producerConfig(AssertableApplicationContext context) { + return KafkaMessagingAutoConfiguration.producerConfig( + context.getBean(CompiledMessagingConfiguration.class), + context.getBeanProvider(BrokerSecurityProfile.class), + context.getBeanProvider(KafkaSecurityConfigurer.class)); + } +} diff --git a/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaProducerSecurityTest.java b/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaProducerSecurityTest.java index 2efd948a..98c4bde3 100644 --- a/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaProducerSecurityTest.java +++ b/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/KafkaProducerSecurityTest.java @@ -39,7 +39,6 @@ class KafkaProducerSecurityTest { .withPropertyValues( "app.messaging.enabled=true", "app.messaging.broker=kafka", - "spring.kafka.bootstrap-servers=localhost:9092", "app.messaging.brokers.kafka-primary.type=kafka", "app.messaging.brokers.kafka-primary.bootstrap-servers[0]=localhost:9092"); @@ -228,7 +227,6 @@ class KafkaProducerSecurityTest { private static Map producerConfig(AssertableApplicationContext context) { return KafkaMessagingAutoConfiguration.producerConfig( - context.getEnvironment(), context.getBean(CompiledMessagingConfiguration.class), context.getBeanProvider(BrokerSecurityProfile.class), context.getBeanProvider(KafkaSecurityConfigurer.class)); diff --git a/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingAutoConfigurationTest.java b/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingAutoConfigurationTest.java index 6c829229..0d4708c6 100644 --- a/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingAutoConfigurationTest.java +++ b/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingAutoConfigurationTest.java @@ -314,7 +314,9 @@ class MessagingAutoConfigurationTest { org.springframework.boot.autoconfigure.AutoConfigurations.of( MessagingCoreAutoConfiguration.class, KafkaMessagingAutoConfiguration.class)) .withUserConfiguration(PublisherConfiguration.class, AutoCommittingKafkaProfile.class) - .withPropertyValues("spring.kafka.bootstrap-servers=localhost:9092") + .withPropertyValues( + "app.messaging.brokers.kafka.type=kafka", + "app.messaging.brokers.kafka.bootstrap-servers[0]=localhost:9092") .run( context -> org.assertj.core.api.Assertions.assertThat(context) diff --git a/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationBindingTest.java b/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationBindingTest.java index 73f8a08b..c3239aa2 100644 --- a/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationBindingTest.java +++ b/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingConfigurationBindingTest.java @@ -258,9 +258,7 @@ class MessagingConfigurationBindingTest { runner .withConfiguration(AutoConfigurations.of(KafkaMessagingAutoConfiguration.class)) .withPropertyValues(minimal()) - .withPropertyValues( - "spring.kafka.bootstrap-servers=localhost:9092", - "app.messaging.brokers.kafka-primary.production=true") + .withPropertyValues("app.messaging.brokers.kafka-primary.production=true") .run( context -> assertThat(context) diff --git a/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingOutboxRelayLifecycleTest.java b/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingOutboxRelayLifecycleTest.java index 6527539b..5c9e3b00 100644 --- a/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingOutboxRelayLifecycleTest.java +++ b/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingOutboxRelayLifecycleTest.java @@ -73,6 +73,55 @@ class MessagingOutboxRelayLifecycleTest { .isFalse(); } + @Test + void aRelayPassThatFailsIsCountedOnTheMeterRegistry() { + new ApplicationContextRunner() + .withConfiguration(AutoConfigurations.of(MessagingReliabilityAutoConfiguration.class)) + .withBean( + io.micrometer.core.instrument.MeterRegistry.class, + io.micrometer.core.instrument.simple.SimpleMeterRegistry::new) + .withBean( + OutboxRepository.class, + () -> + (OutboxRepository) + java.lang.reflect.Proxy.newProxyInstance( + getClass().getClassLoader(), + new Class[] {OutboxRepository.class}, + (proxy, method, arguments) -> { + throw new IllegalStateException("the outbox database is unreachable"); + })) + .withBean( + OutboxEnvelopeFactory.class, + () -> new OutboxEnvelopeFactory(new ProducerId("order-api"))) + .withBean(MessagePublisher.class, () -> new RelayDependencies().messagePublisher()) + .run( + context -> { + // given + io.micrometer.core.instrument.MeterRegistry registry = + context.getBean(io.micrometer.core.instrument.MeterRegistry.class); + + // when + double failed = awaitFailedPasses(registry); + + // then + assertThat(failed) + .as("a pass that failed was swallowed with no log and a counter nothing read") + .isPositive(); + }); + } + + /** Reads the failed-pass counter until the relay's first pass has had time to fail. */ + private static double awaitFailedPasses(io.micrometer.core.instrument.MeterRegistry registry) + throws InterruptedException { + long deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(5); + double failed = 0; + while (failed == 0 && System.nanoTime() < deadline) { + Thread.sleep(10); + failed = registry.get("messaging.outbox.relay.failed.passes").functionCounter().count(); + } + return failed; + } + /** The two beans only the application can supply, plus the publisher the platform needs. */ @Configuration(proxyBeanMethods = false) static class RelayDependencies { @@ -170,11 +219,6 @@ class MessagingOutboxRelayLifecycleTest { throw new UnsupportedOperationException("not used by this test"); } - @Override - public int purgePublishedBefore(Instant publishedBefore) { - throw new UnsupportedOperationException("not used by this test"); - } - @Override public int purgePublishedBefore(Instant publishedBefore, int limit) { throw new UnsupportedOperationException("not used by this test"); diff --git a/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingStarterOffContractTest.java b/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingStarterOffContractTest.java index 4da59b9e..e611c070 100644 --- a/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingStarterOffContractTest.java +++ b/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/MessagingStarterOffContractTest.java @@ -41,7 +41,9 @@ class MessagingStarterOffContractTest { void presentWithoutTheSwitchIsOn() { runner .withPropertyValues( - "app.messaging.broker=kafka", "spring.kafka.bootstrap-servers=localhost:9092") + "app.messaging.broker=kafka", + "app.messaging.brokers.kafka.type=kafka", + "app.messaging.brokers.kafka.bootstrap-servers[0]=localhost:9092") .run( context -> { assertThat(context).hasNotFailed(); @@ -123,7 +125,8 @@ class MessagingStarterOffContractTest { .withPropertyValues( "app.messaging.enabled=true", "app.messaging.broker=kafka", - "spring.kafka.bootstrap-servers=localhost:9092") + "app.messaging.brokers.kafka.type=kafka", + "app.messaging.brokers.kafka.bootstrap-servers[0]=localhost:9092") .run( context -> { assertThat(context).hasNotFailed(); @@ -138,7 +141,8 @@ class MessagingStarterOffContractTest { .withPropertyValues( "app.messaging.enabled=true", "app.messaging.broker=kafka", - "spring.kafka.bootstrap-servers=localhost:9092") + "app.messaging.brokers.kafka.type=kafka", + "app.messaging.brokers.kafka.bootstrap-servers[0]=localhost:9092") .run( context -> { assertThat(context) @@ -165,7 +169,8 @@ class MessagingStarterOffContractTest { .withPropertyValues( "app.messaging.enabled=true", "app.messaging.broker=kafka", - "spring.kafka.bootstrap-servers=localhost:9092") + "app.messaging.brokers.kafka.type=kafka", + "app.messaging.brokers.kafka.bootstrap-servers[0]=localhost:9092") .run( context -> { assertThat(context) @@ -203,7 +208,7 @@ class MessagingStarterOffContractTest { .hasFailed() .getFailure() .rootCause() - .hasMessageContaining("spring.kafka.bootstrap-servers")); + .hasMessageContaining("app.messaging.brokers.")); } /** diff --git a/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/ReactiveFacadeTest.java b/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/ReactiveFacadeTest.java index 21931ea8..91e82fe9 100644 --- a/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/ReactiveFacadeTest.java +++ b/src/messaging/messaging-spring-boot-starter/src/test/java/dev/caskeleton/messaging/autoconfigure/ReactiveFacadeTest.java @@ -91,6 +91,34 @@ class ReactiveFacadeTest { .verify(); } + @Test + void theBlockingPublishRunsOffTheSubscribingThread() { + // given + java.util.concurrent.atomic.AtomicReference publishedOn = + new java.util.concurrent.atomic.AtomicReference<>(); + MessagePublisher recording = + new MessagePublisher() { + @Override + public CompletionStage publish( + MessageDestination destination, + MessageEnvelope message, + PublishOptions options) { + publishedOn.set(Thread.currentThread()); + return CompletableFuture.completedFuture(confirmed()); + } + }; + + // when + new DefaultReactiveMessagePublisher(recording) + .publish(ORDERS, envelope(), PublishOptions.defaults()) + .block(); + + // then + assertThat(publishedOn.get()) + .as("admission and the producer's metadata wait block; an event loop must not pay for it") + .isNotSameAs(Thread.currentThread()); + } + private MessagePublisher counting() { return new MessagePublisher() { @Override diff --git a/src/optional-platforms/build.gradle b/src/optional-platforms/build.gradle index 001bb2dc..e91af3c5 100644 --- a/src/optional-platforms/build.gradle +++ b/src/optional-platforms/build.gradle @@ -35,7 +35,9 @@ tasks.register('ci') { description = 'Runs the optional gRPC platform verification surface.' dependsOn tasks.named('checkAll') dependsOn tasks.named('qualityCheck') - dependsOn tasks.named('verifyCleanArchitectureDependencies') + // architectureCheck, not only the direction gate: it also runs verifyNoIgnoredSourcePackages, so + // a gRPC source Git would drop fails this build's ci the way it fails the main build's. + dependsOn tasks.named('architectureCheck') } // A strict integration lane that no workflow invokes is not coverage; it is a file that looks like diff --git a/src/sample-portfolio/README.md b/src/sample-portfolio/README.md index 59bac9a9..1ecb7c35 100644 --- a/src/sample-portfolio/README.md +++ b/src/sample-portfolio/README.md @@ -255,8 +255,10 @@ curl -X POST localhost:8080/work-logs -H 'Content-Type: application/json' -d '{ - **GET /worklogs/{id}**: `ETag` 를 내보내고, `If-None-Match` 가 맞으면 본문 없이 304 를 답니다. - **PATCH /worklogs/{id}**: `If-Match` 가 오면 현재 ETag 와 같아야 하고, 다르면 412(낙관적 동시성). `If-Match` 가 없으면 검사를 건너뜁니다 — 스켈레톤은 권장 패턴을 보여주되 강제하지는 않습니다. - `ETag`/`If-Match` 는 HTTP 전송 관심사(RFC 7232)라, 읽고-비교하는 로직을 일부러 웹 어댑터에만 - 두고 application/domain 은 ETag 를 전혀 보지 않게 합니다. + 헤더 해석(`W/""` → 숫자)은 웹 어댑터가 하고, 비교는 `UpdateWorkLogCommand.expectedVersion` + 으로 받은 update 유스케이스가 쓰기 트랜잭션 안에서 합니다. 컨트롤러가 트랜잭션 밖에서 읽고 비교하면 + 그 사이에 다른 수정이 끼어들 수 있기 때문입니다. application 은 ETag 문자열을 보지 않습니다. + 이 리소스는 validator 하나만 내보내므로 목록·비숫자 `If-Match` 는 읽지 않고 412 입니다. - **POST /worklogs**: 이 예제는 멱등성을 약속하지 않습니다. 지원하지 않는 `Idempotency-Key`를 시그니처에 받아 놓고 무시하지 않으며, 멱등성 예시는 poster image publication 유스케이스에서 application `IdempotencyExecutor`로 제공합니다. diff --git a/src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/SamplePortfolioApplication.java b/src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/SamplePortfolioApplication.java index 066e0bde..0dff8cfe 100644 --- a/src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/SamplePortfolioApplication.java +++ b/src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/SamplePortfolioApplication.java @@ -3,6 +3,7 @@ package dev.caskeleton.sample.portfolio; import dev.caskeleton.adapter.inbound.web.auth.SecurityConfig; import dev.caskeleton.adapter.inbound.web.authz.MethodSecurityConfig; import dev.caskeleton.adapter.inbound.web.mvc.autoconfigure.WebAdapterAutoConfiguration; +import dev.caskeleton.adapter.inbound.web.operation.DurableOperationController; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.EnableAutoConfiguration; import org.springframework.boot.context.properties.ConfigurationPropertiesScan; @@ -40,13 +41,16 @@ import org.springframework.context.annotation.FilterType; }, excludeFilters = { // The standalone sample is a public demo app: URL access should not require a configured - // IdP or method-security principal. Production modules keep these guards. + // IdP or method-security principal. Production modules keep these guards. The durable + // operation endpoint is imported by its own auto-configuration only when the JPA store and + // outbox are there; the sample wires neither, so a scan must not register it. @ComponentScan.Filter( type = FilterType.ASSIGNABLE_TYPE, classes = { SecurityConfig.class, MethodSecurityConfig.class, - WebAdapterAutoConfiguration.class + WebAdapterAutoConfiguration.class, + DurableOperationController.class }) }) @ConfigurationPropertiesScan( diff --git a/src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/adapter/inbound/web/controller/WorkLogController.java b/src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/adapter/inbound/web/controller/WorkLogController.java index 34c079d0..de74a237 100644 --- a/src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/adapter/inbound/web/controller/WorkLogController.java +++ b/src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/adapter/inbound/web/controller/WorkLogController.java @@ -38,6 +38,7 @@ import jakarta.validation.Valid; import jakarta.validation.constraints.Size; import java.util.List; import java.util.Locale; +import java.util.OptionalLong; import java.util.UUID; import org.springframework.http.HttpStatus; import org.springframework.http.ResponseEntity; @@ -158,9 +159,8 @@ public class WorkLogController { @PathVariable String id, @RequestHeader(value = ApiHeaders.IF_MATCH, required = false) String ifMatch, @Valid @RequestBody UpdateWorkLogRequest body) { - WorkLogId workLogId = toId(id); - requireIfMatch(ifMatch, workLogId); - WorkLog updated = update.handle(WorkLogWebMapper.toUpdateCommand(workLogId, body)); + WorkLog updated = + update.handle(WorkLogWebMapper.toUpdateCommand(toId(id), body, expectedVersion(ifMatch))); return ResponseEntity.ok().eTag(etagOf(updated)).body(WorkLogWebMapper.toResponse(updated)); } @@ -202,16 +202,26 @@ public class WorkLogController { } /** - * Optimistic-concurrency precondition. {@code ETag}/{@code If-Match} is an HTTP transport - * concern, so the read-then-compare stays in the web adapter; an absent/blank {@code If-Match} - * skips the check. See README. + * The version an {@code If-Match} names. Reading the header is transport; comparing it is the + * update use case's, inside its write transaction — a read here and a write there would let + * another update land in between. Absent, blank or {@code *} sets no precondition. This resource + * emits one validator, {@code W/""}, so a list or a non-numeric tag cannot name a + * version it holds and is refused (412) without a read. See README. */ - private void requireIfMatch(String ifMatch, WorkLogId id) { - if (ifMatch == null || ifMatch.isBlank()) { - return; + private static OptionalLong expectedVersion(String ifMatch) { + if (ifMatch == null || ifMatch.isBlank() || "*".equals(ifMatch.trim())) { + return OptionalLong.empty(); } - WorkLog current = get.handle(new GetWorkLogQuery(id)); - if (!ETags.matches(ifMatch, etagOf(current))) { + String tag = ifMatch.trim(); + if (tag.startsWith("W/")) { + tag = tag.substring(2); + } + if (tag.length() > 2 && tag.startsWith("\"") && tag.endsWith("\"")) { + tag = tag.substring(1, tag.length() - 1); + } + try { + return OptionalLong.of(Long.parseLong(tag)); + } catch (NumberFormatException notOneVersion) { throw new PreconditionFailedException("If-Match does not match the current resource version"); } } diff --git a/src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/adapter/inbound/web/error/DomainExceptionHandler.java b/src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/adapter/inbound/web/error/DomainExceptionHandler.java index 8d2ba0ff..b6af9674 100644 --- a/src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/adapter/inbound/web/error/DomainExceptionHandler.java +++ b/src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/adapter/inbound/web/error/DomainExceptionHandler.java @@ -4,8 +4,10 @@ import dev.caskeleton.adapter.inbound.web.error.ErrorResponseFactory; import dev.caskeleton.sample.portfolio.application.exception.PosterNotFoundException; import dev.caskeleton.sample.portfolio.application.exception.PosterTitleAlreadyExistsException; import dev.caskeleton.sample.portfolio.application.exception.WorkLogNotFoundException; +import dev.caskeleton.sample.portfolio.application.exception.WorkLogVersionMismatchException; import dev.caskeleton.sample.portfolio.domain.poster.PosterInvariantException; import dev.caskeleton.sample.portfolio.domain.worklog.WorkLogInvariantException; +import dev.caskeleton.shared.error.OperationalError; import dev.caskeleton.shared.response.Envelope; import org.springframework.core.Ordered; import org.springframework.core.annotation.Order; @@ -31,6 +33,14 @@ public class DomainExceptionHandler { null); } + /** A stale {@code If-Match}, found by the update use case inside its transaction → 412. */ + @ExceptionHandler(WorkLogVersionMismatchException.class) + public ResponseEntity> handleWorkLogVersionMismatch( + WorkLogVersionMismatchException ex) { + return ErrorResponseFactory.envelope( + OperationalError.PRECONDITION_FAILED, "Resource state changed; refresh and retry", null); + } + @ExceptionHandler(WorkLogInvariantException.class) public ResponseEntity> handleWorkLogInvariant(WorkLogInvariantException ex) { return ErrorResponseFactory.envelope( diff --git a/src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/adapter/inbound/web/mapper/WorkLogWebMapper.java b/src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/adapter/inbound/web/mapper/WorkLogWebMapper.java index f9083db9..294d4ff9 100644 --- a/src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/adapter/inbound/web/mapper/WorkLogWebMapper.java +++ b/src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/adapter/inbound/web/mapper/WorkLogWebMapper.java @@ -14,6 +14,7 @@ import dev.caskeleton.shared.error.MappingException; import java.net.URI; import java.net.URISyntaxException; import java.util.List; +import java.util.OptionalLong; public final class WorkLogWebMapper { @@ -43,14 +44,16 @@ public final class WorkLogWebMapper { // PATCH goes through the mapper too (not built inline in the controller) so the web // adapter owns all request DTO -> command translation. The WorkLogId is parsed at the // web edge and passed in. See README. - public static UpdateWorkLogCommand toUpdateCommand(WorkLogId id, UpdateWorkLogRequest body) { + public static UpdateWorkLogCommand toUpdateCommand( + WorkLogId id, UpdateWorkLogRequest body, OptionalLong expectedVersion) { return new UpdateWorkLogCommand( id, body.titlePatch(), body.summaryPatch(), body.contentPatch(), body.categoryPatch(), - body.statusPatch()); + body.statusPatch(), + expectedVersion); } public static WorkLogResponse toResponse(WorkLog w) { diff --git a/src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/application/command/UpdateWorkLogCommand.java b/src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/application/command/UpdateWorkLogCommand.java index 570a5d86..084d030e 100644 --- a/src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/application/command/UpdateWorkLogCommand.java +++ b/src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/application/command/UpdateWorkLogCommand.java @@ -6,14 +6,23 @@ import dev.caskeleton.sample.portfolio.domain.worklog.WorkLogId; import dev.caskeleton.sample.portfolio.domain.worklog.WorkLogStatus; import dev.caskeleton.shared.request.Patch; import java.util.Objects; +import java.util.OptionalLong; +/** + * A partial update. + * + * @param expectedVersion the version the caller last read; empty sets no precondition. Compared by + * the use case inside its write transaction, so no other write can land between the check and + * the update. + */ public record UpdateWorkLogCommand( WorkLogId id, Patch title, Patch summary, Patch content, Patch category, - Patch status) + Patch status, + OptionalLong expectedVersion) implements Command { // Self-validating input model: a null id or null patch is a programming error — fail @@ -25,5 +34,6 @@ public record UpdateWorkLogCommand( Objects.requireNonNull(content, "content"); Objects.requireNonNull(category, "category"); Objects.requireNonNull(status, "status"); + Objects.requireNonNull(expectedVersion, "expectedVersion"); } } diff --git a/src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/application/exception/WorkLogVersionMismatchException.java b/src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/application/exception/WorkLogVersionMismatchException.java new file mode 100644 index 00000000..881eda52 --- /dev/null +++ b/src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/application/exception/WorkLogVersionMismatchException.java @@ -0,0 +1,13 @@ +package dev.caskeleton.sample.portfolio.application.exception; + +import dev.caskeleton.sample.portfolio.domain.worklog.WorkLogId; + +/** The caller edited a version that is no longer the stored one. */ +public class WorkLogVersionMismatchException extends RuntimeException { + + private static final long serialVersionUID = 1L; + + public WorkLogVersionMismatchException(WorkLogId id) { + super("WorkLog version changed: " + id.value()); + } +} diff --git a/src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/application/worklog/UpdateWorkLogUseCase.java b/src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/application/worklog/UpdateWorkLogUseCase.java index 58d134c4..257543a5 100644 --- a/src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/application/worklog/UpdateWorkLogUseCase.java +++ b/src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/application/worklog/UpdateWorkLogUseCase.java @@ -9,6 +9,7 @@ import dev.caskeleton.application.transaction.TransactionPort; import dev.caskeleton.application.usecase.CommandUseCase; import dev.caskeleton.sample.portfolio.application.command.UpdateWorkLogCommand; import dev.caskeleton.sample.portfolio.application.exception.WorkLogNotFoundException; +import dev.caskeleton.sample.portfolio.application.exception.WorkLogVersionMismatchException; import dev.caskeleton.sample.portfolio.domain.worklog.WorkLog; import dev.caskeleton.sample.portfolio.domain.worklog.WorkLogInvariantException; import dev.caskeleton.sample.portfolio.domain.worklog.WorkLogRepository; @@ -37,6 +38,10 @@ public class UpdateWorkLogUseCase implements CommandUseCase new WorkLogNotFoundException(cmd.id())); + long current = w.version() == null ? 0L : w.version(); + if (cmd.expectedVersion().isPresent() && cmd.expectedVersion().getAsLong() != current) { + throw new WorkLogVersionMismatchException(cmd.id()); + } if (cmd.title().hasValue()) { w.rename(cmd.title().value()); } diff --git a/src/sample-portfolio/src/main/resources/application.yml b/src/sample-portfolio/src/main/resources/application.yml index d31037fd..9374dbac 100644 --- a/src/sample-portfolio/src/main/resources/application.yml +++ b/src/sample-portfolio/src/main/resources/application.yml @@ -42,7 +42,7 @@ spring: initialization-fail-timeout: 1 flyway: baseline-on-migrate: false - out-of-order: true + out-of-order: false clean-disabled: true # The primary Flyway owns the production persistence timeline only. The sample schema # is migrated separately by SamplePostgreSqlPersistenceConfig.sampleMigrationStrategy using @@ -50,7 +50,7 @@ spring: locations: classpath:db/migration/postgresql jpa: hibernate: - ddl-auto: ${APP_DATASOURCE_DDL_AUTO:update} + ddl-auto: ${APP_DATASOURCE_DDL_AUTO:validate} show-sql: ${APP_DATASOURCE_SHOW_SQL:false} open-in-view: ${APP_DATASOURCE_OPEN_IN_VIEW:false} properties: diff --git a/src/sample-portfolio/src/test/java/dev/caskeleton/sample/portfolio/adapter/inbound/web/controller/WorkLogControllerWireTest.java b/src/sample-portfolio/src/test/java/dev/caskeleton/sample/portfolio/adapter/inbound/web/controller/WorkLogControllerWireTest.java index d689cfa1..bd5e0388 100644 --- a/src/sample-portfolio/src/test/java/dev/caskeleton/sample/portfolio/adapter/inbound/web/controller/WorkLogControllerWireTest.java +++ b/src/sample-portfolio/src/test/java/dev/caskeleton/sample/portfolio/adapter/inbound/web/controller/WorkLogControllerWireTest.java @@ -23,6 +23,7 @@ import dev.caskeleton.sample.portfolio.adapter.inbound.web.json.WorkLogIdSeriali import dev.caskeleton.sample.portfolio.application.command.CreateWorkLogCommand; import dev.caskeleton.sample.portfolio.application.command.UpdateWorkLogCommand; import dev.caskeleton.sample.portfolio.application.exception.WorkLogNotFoundException; +import dev.caskeleton.sample.portfolio.application.exception.WorkLogVersionMismatchException; import dev.caskeleton.sample.portfolio.application.query.GetWorkLogQuery; import dev.caskeleton.sample.portfolio.application.query.ListWorkLogsQuery; import dev.caskeleton.sample.portfolio.application.worklog.BatchCreateWorkLogsUseCase; @@ -43,6 +44,7 @@ import dev.caskeleton.shared.request.Patch; import java.time.LocalDate; import java.util.List; import java.util.Locale; +import java.util.OptionalLong; import java.util.Set; import java.util.stream.Collectors; import java.util.stream.IntStream; @@ -123,7 +125,13 @@ class WorkLogControllerWireTest { private static UpdateWorkLogCommand patchOf(Patch title, Patch summary) { return new UpdateWorkLogCommand( - WorkLogId.of(ID), title, summary, Patch.absent(), Patch.absent(), Patch.absent()); + WorkLogId.of(ID), + title, + summary, + Patch.absent(), + Patch.absent(), + Patch.absent(), + OptionalLong.empty()); } /** D7/D18/D20/D21. */ @@ -419,8 +427,9 @@ class WorkLogControllerWireTest { @Test void patchWithStaleIfMatchReturns412() throws Exception { - // given - when(getUseCase.handle(any())).thenReturn(sample("current")); + // given: the update use case finds version 0 stored where 99 was expected + when(updateUseCase.handle(any())) + .thenThrow(new WorkLogVersionMismatchException(WorkLogId.of(ID))); // when ResultActions result = @@ -436,10 +445,59 @@ class WorkLogControllerWireTest { .andExpect(jsonPath("$.error.code").value("PRECONDITION_FAILED")); } + @Test + void patchWithIfMatchDoesNotReadTheWorkLogOutsideTheUpdate() throws Exception { + // given + when(updateUseCase.handle(any())).thenReturn(sample("new title")); + + // when + mvc.perform( + patch("/worklogs/" + ID) + .header("If-Match", "W/\"0\"") + .contentType(MediaType.APPLICATION_JSON) + .content("{\"title\":\"new title\"}")); + + // then + verifyNoInteractions(getUseCase); + } + + @Test + void patchHandsTheIfMatchVersionToTheUpdateUseCase() throws Exception { + // given + ArgumentCaptor command = + ArgumentCaptor.forClass(UpdateWorkLogCommand.class); + when(updateUseCase.handle(command.capture())).thenReturn(sample("new title")); + + // when + mvc.perform( + patch("/worklogs/" + ID) + .header("If-Match", "W/\"7\"") + .contentType(MediaType.APPLICATION_JSON) + .content("{\"title\":\"new title\"}")); + + // then + assertThat(command.getValue().expectedVersion()).isEqualTo(OptionalLong.of(7)); + } + + @Test + void patchWithAListIfMatchIsRefusedAs412() throws Exception { + // when + ResultActions result = + mvc.perform( + patch("/worklogs/" + ID) + .header("If-Match", "W/\"1\", W/\"2\"") + .contentType(MediaType.APPLICATION_JSON) + .content("{\"title\":\"x\"}")); + + // then + result + .andExpect(status().isPreconditionFailed()) + .andExpect(jsonPath("$.error.code").value("PRECONDITION_FAILED")); + } + @Test void patchWithMatchingIfMatchAppliesUpdate() throws Exception { // given - when(getUseCase.handle(any())).thenReturn(sample("current")); when(updateUseCase.handle(any())).thenReturn(sample("new title")); // when diff --git a/src/sample-portfolio/src/test/java/dev/caskeleton/sample/portfolio/application/command/CommandSelfValidationTest.java b/src/sample-portfolio/src/test/java/dev/caskeleton/sample/portfolio/application/command/CommandSelfValidationTest.java index e2d25a99..14906af5 100644 --- a/src/sample-portfolio/src/test/java/dev/caskeleton/sample/portfolio/application/command/CommandSelfValidationTest.java +++ b/src/sample-portfolio/src/test/java/dev/caskeleton/sample/portfolio/application/command/CommandSelfValidationTest.java @@ -11,6 +11,7 @@ import dev.caskeleton.sample.portfolio.domain.worklog.WorkLogId; import dev.caskeleton.shared.request.Patch; import java.time.LocalDate; import java.util.List; +import java.util.OptionalLong; import java.util.stream.Stream; import org.assertj.core.api.ThrowableAssert.ThrowingCallable; import org.junit.jupiter.api.Test; @@ -78,6 +79,12 @@ class CommandSelfValidationTest { private static UpdateWorkLogCommand update(WorkLogId id, Patch title) { return new UpdateWorkLogCommand( - id, title, Patch.absent(), Patch.absent(), Patch.absent(), Patch.absent()); + id, + title, + Patch.absent(), + Patch.absent(), + Patch.absent(), + Patch.absent(), + OptionalLong.empty()); } } diff --git a/src/sample-portfolio/src/test/java/dev/caskeleton/sample/portfolio/application/worklog/WorkLogUseCasesTest.java b/src/sample-portfolio/src/test/java/dev/caskeleton/sample/portfolio/application/worklog/WorkLogUseCasesTest.java index 15ed1c46..97aaed3b 100644 --- a/src/sample-portfolio/src/test/java/dev/caskeleton/sample/portfolio/application/worklog/WorkLogUseCasesTest.java +++ b/src/sample-portfolio/src/test/java/dev/caskeleton/sample/portfolio/application/worklog/WorkLogUseCasesTest.java @@ -16,6 +16,7 @@ import dev.caskeleton.sample.portfolio.application.command.CreateWorkLogCommand; import dev.caskeleton.sample.portfolio.application.command.DeleteWorkLogCommand; import dev.caskeleton.sample.portfolio.application.command.UpdateWorkLogCommand; import dev.caskeleton.sample.portfolio.application.exception.WorkLogNotFoundException; +import dev.caskeleton.sample.portfolio.application.exception.WorkLogVersionMismatchException; import dev.caskeleton.sample.portfolio.application.query.GetWorkLogQuery; import dev.caskeleton.sample.portfolio.application.query.ListWorkLogsQuery; import dev.caskeleton.sample.portfolio.domain.worklog.WorkCategory; @@ -32,6 +33,7 @@ import java.time.Clock; import java.time.LocalDate; import java.util.List; import java.util.Optional; +import java.util.OptionalLong; import org.junit.jupiter.api.Nested; import org.junit.jupiter.api.Test; @@ -119,7 +121,8 @@ class WorkLogUseCasesTest { Patch.absent(), Patch.of("new content"), Patch.absent(), - Patch.absent())); + Patch.absent(), + OptionalLong.empty())); // then assertThat(updated) @@ -127,6 +130,33 @@ class WorkLogUseCasesTest { .containsExactly("new title", "s", "new content"); } + @Test + void staleExpectedVersionIsRefusedInsideTheUpdate() { + // given: created at version 0, then edited to version 1 + WorkLogId id = aCreatedWorkLog("old").id(); + update.handle(renameExpecting(id, 0)); + + // when + Throwable thrown = catchThrowable(() -> update.handle(renameExpecting(id, 0))); + + // then + assertThat(thrown) + .isInstanceOf(WorkLogVersionMismatchException.class) + .hasMessage("WorkLog version changed: " + id.value()); + } + + @Test + void currentExpectedVersionAppliesTheUpdate() { + // given + WorkLogId id = aCreatedWorkLog("old").id(); + + // when + WorkLog updated = update.handle(renameExpecting(id, 0)); + + // then + assertThat(updated.title()).isEqualTo("renamed"); + } + @Test void clearsTheSummaryOnAnExplicitNull() { // given @@ -141,7 +171,8 @@ class WorkLogUseCasesTest { Patch.ofNull(), Patch.absent(), Patch.absent(), - Patch.absent())); + Patch.absent(), + OptionalLong.empty())); // then assertThat(updated.summary()).isEmpty(); @@ -178,7 +209,8 @@ class WorkLogUseCasesTest { Patch.absent(), Patch.absent(), Patch.absent(), - Patch.absent()))); + Patch.absent(), + OptionalLong.empty()))); // then assertThat(thrown) @@ -305,6 +337,23 @@ class WorkLogUseCasesTest { private static UpdateWorkLogCommand statusChange(WorkLogId id, WorkLogStatus status) { return new UpdateWorkLogCommand( - id, Patch.absent(), Patch.absent(), Patch.absent(), Patch.absent(), Patch.of(status)); + id, + Patch.absent(), + Patch.absent(), + Patch.absent(), + Patch.absent(), + Patch.of(status), + OptionalLong.empty()); + } + + private static UpdateWorkLogCommand renameExpecting(WorkLogId id, long expectedVersion) { + return new UpdateWorkLogCommand( + id, + Patch.of("renamed"), + Patch.absent(), + Patch.absent(), + Patch.absent(), + Patch.absent(), + OptionalLong.of(expectedVersion)); } } diff --git a/src/sample-portfolio/src/test/java/dev/caskeleton/sample/portfolio/bootstrap/persistence/SampleSchemaOwnershipDefaultsTest.java b/src/sample-portfolio/src/test/java/dev/caskeleton/sample/portfolio/bootstrap/persistence/SampleSchemaOwnershipDefaultsTest.java new file mode 100644 index 00000000..1cb8c96c --- /dev/null +++ b/src/sample-portfolio/src/test/java/dev/caskeleton/sample/portfolio/bootstrap/persistence/SampleSchemaOwnershipDefaultsTest.java @@ -0,0 +1,36 @@ +package dev.caskeleton.sample.portfolio.bootstrap.persistence; + +import static org.assertj.core.api.Assertions.assertThat; + +import java.io.IOException; +import java.util.List; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.CsvSource; +import org.springframework.boot.env.YamlPropertySourceLoader; +import org.springframework.core.env.PropertySource; +import org.springframework.core.io.ClassPathResource; + +/** + * Flyway owns the sample schema. Out-of-order migration is what production refuses, and a Hibernate + * {@code update} rewrites the schema under Flyway and hides a mapping that no migration matches. + */ +class SampleSchemaOwnershipDefaultsTest { + + @ParameterizedTest + @CsvSource({ + "spring.flyway.out-of-order, false", + "spring.jpa.hibernate.ddl-auto, '${APP_DATASOURCE_DDL_AUTO:validate}'" + }) + void sampleDefaultsLeaveTheSchemaToFlyway(String key, String expected) throws IOException { + // given + List> documents = + new YamlPropertySourceLoader() + .load("application", new ClassPathResource("application.yml")); + + // when + Object value = documents.get(0).getProperty(key); + + // then + assertThat(value).hasToString(expected); + } +}