review-followup Wave 3 라운드 3(P28·P29): fileserver use case·file:* 권한, 보안 파일 primitive 공용화, jvm-test-suite

- 결정 32: fileserver transport 연산 21개를 `port.in` use case로, 쓰기·읽기에 `file:*` 권한(소유자·tenant 정책은 유지),
  inbound 서비스 이름 `*UseCase`, port 구현 이름 `<Tech><Port>` 규칙(S2-#13b, 24개)
- 디렉터리 descriptor 파일 primitive를 `adapter:outbound:support`로(S4-lead-2 일부 — fileserver는 번역만),
  persistence-fileserver를 scan·클래스별 조건 대신 명시적 `@Bean` 설정으로(S2-#8a 일부), `FileVerifier`를 adapter로
- 호출자 0인 `poster.image-attached` 이벤트 삭제, SES SDK client를 레지스트리 종료 때 close, fileserver migration V1–V5 고정
- P29: auxiliary 레인 → Gradle `jvm-test-suite`(BUILD-O3-5, build-logic 16,768 → 5,851줄), redis-sdk가 runtime을 api로(P22-new-3)
- 통합: JPA API surface 기준선 재승인(이름 규칙 변경), migration lane에 V19 반영, messaging 통합 테스트가 jar 안 migration 목록 조회(ORCH-new-5)
- P28·P29 에이전트가 세션 재시작으로 중단 — 커밋된 것만 합치고 결과 파일은 오케스트레이터가 확정, S6-#10a는 P30으로

검증: ./gradlew ci verifyDependencyLocks --warning-mode=fail(714 task) · mainCheck architectureCheck verifyPublicPathSnapshot
:app-bootstrap:verifyEnvKeys configContractCheck · :app-bootstrap:integrationTest :sample-portfolio:integrationTest
:sample-portfolio:systemTest integrationCheck · -p build-logic test · -p optional-platforms ci · releaseCheck qualificationBootJar 통과

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
donghyeon-ka
2026-09-29 14:54:06 +09:00
co-authored by Claude Opus 5.5
parent 09e2dd63d6
commit 0579935746
275 changed files with 5838 additions and 3312 deletions
+38 -22
View File
@@ -3,7 +3,6 @@ plugins {
id 'ca.spring-config'
id 'org.springframework.boot'
id 'ca.config-contract'
id 'ca.auxiliary-source-set'
id 'ca.bootrun-dotenv'
}
@@ -15,21 +14,40 @@ plugins {
// feedback loop starts a database is a leaf nobody runs the fast loop on. This is the same shape
// persistence-jpa, web, websocket and objectstorage already use, declared through the repository's
// own strictTestLanes DSL rather than by hand.
auxiliarySourceSets {
sourceSet('integrationTest') {
compilesAgainst 'main'
inherits 'implementation', 'compileOnly', 'runtimeOnly', 'annotationProcessor'
// The suites see main (and two of them the test classes) as class directories rather than through
// `implementation project()`: this is a Spring Boot application project, and its lanes have always
// run on main's output, not on the plain jar.
testing {
suites {
integrationTest(JvmTestSuite)
architectureTest(JvmTestSuite)
// No test runtime and no inherited test dependencies: the full-boot lane runs on the
// composition bootJar packages (see the configurations block below).
systemTest(JvmTestSuite)
}
sourceSet('architectureTest') {
compilesAgainst 'main', 'test'
inherits 'implementation', 'compileOnly', 'runtimeOnly', 'annotationProcessor'
runtimeFrom 'test'
}
configurations {
integrationTestImplementation.extendsFrom testImplementation
integrationTestCompileOnly.extendsFrom testCompileOnly
integrationTestRuntimeOnly.extendsFrom testRuntimeOnly
integrationTestAnnotationProcessor.extendsFrom testAnnotationProcessor
architectureTestImplementation.extendsFrom testImplementation
architectureTestCompileOnly.extendsFrom testCompileOnly
architectureTestRuntimeOnly.extendsFrom testRuntimeOnly
architectureTestAnnotationProcessor.extendsFrom testAnnotationProcessor
systemTestAnnotationProcessor.extendsFrom testAnnotationProcessor
}
sourceSets {
integrationTest {
compileClasspath += main.output
runtimeClasspath += main.output
}
// No `runtimeFrom 'test'` and no inherited test dependencies: the full-boot lane runs on the
// composition bootJar packages (see the configurations block below).
sourceSet('systemTest') {
compilesAgainst 'main', 'test'
inherits 'annotationProcessor'
architectureTest {
compileClasspath += main.output + test.output
}
systemTest {
compileClasspath += main.output + test.output
runtimeClasspath += main.output + test.output
}
}
@@ -73,10 +91,12 @@ tasks.named('check') {
dependsOn tasks.named('systemTestLaneCheck')
}
// architectureTest runs on the `test` runtime (runtimeFrom above) plus its own configuration, so
// the capability leaves declared `architectureTestRuntimeOnly` reach the whole-repository ArchUnit
// import without reaching the default composition that `test` and `systemTest` boot.
sourceSets.architectureTest.runtimeClasspath += configurations.architectureTestRuntimeClasspath
// architectureTest runs on the `test` runtime plus its own configuration, so the capability leaves
// declared `architectureTestRuntimeOnly` reach the whole-repository ArchUnit import without reaching
// the default composition that `test` and `systemTest` boot. Its compile classpath (test fixtures,
// testCompileOnly analysis dependencies) is deliberately not its runtime.
sourceSets.architectureTest.runtimeClasspath = sourceSets.architectureTest.output +
sourceSets.test.runtimeClasspath + configurations.architectureTestRuntimeClasspath
// The full-boot lane boots the composition bootJar packages. It compiles against everything the
// test lane sees, but it runs on the main runtime graph plus the test frameworks — not on the test
@@ -95,10 +115,6 @@ dependencies {
systemTestRuntimeOnly 'org.junit.platform:junit-platform-launcher'
}
// architectureTest compiles against test fixtures but intentionally mirrors the ordinary test
// runtime rather than its compile classpath. `runtimeFrom 'test'` above keeps testCompileOnly
// analysis dependencies out of that lane.
sourceSets {
conditionalTransportBuildContractTest {
java.srcDir 'src/conditionalTransportBuildContractTest/java'
@@ -691,7 +691,12 @@ class ApplicationBoundaryArchitectureTest {
// The template's IntegrationEventEncoderPort: a deterministic in-memory rendering of the
// application's own envelope, no IO — the same shape as the identifier codecs. Only this
// package; the rest of support stays covered.
|| packageName.contains(".adapter.outbound.support.messaging");
|| packageName.contains(".adapter.outbound.support.messaging")
// The Fileserver's access policies: a role-and-owner decision over values already in hand,
// no IO. Every Fileserver use case asks it before acting, so without this every one of them
// would have to claim an external outbound call it never makes. Only this package; the
// storage, verification and audit adapters beside it stay covered.
|| packageName.contains(".adapter.outbound.fileserver.platform.security");
}
@ArchTest
@@ -38,8 +38,8 @@ import org.springframework.stereotype.Component;
* selects that implementation but does not implement the port.
*
* <p>The rule has no exceptions any more. Its one allowlisted class, the metering decorator {@code
* MeteredDistributedLockPort}, moved to {@code adapter:outbound:persistence-jpa} with the JDBC lock
* it decorates.
* MeteredDistributedLock}, moved to {@code adapter:outbound:persistence-jpa} with the JDBC lock it
* decorates.
*/
@AnalyzeClasses(
packages = "dev.caskeleton.bootstrap",
@@ -12,23 +12,24 @@ import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
/**
* Freezes the Fileserver's exemption from the inbound use-case contract.
* Freezes what is left of the Fileserver's exemption from the inbound use-case contract.
*
* <p>{@code application-core/CLAUDE.md} requires every inbound port implementation to extend {@code
* CommandUseCase} or {@code QueryUseCase} and to declare {@code @UseCaseCapability}. The ArchUnit
* rules that enforce it — {@code INBOUND_PORT_IMPLEMENTATIONS_END_WITH_USE_CASE} and {@code
* INBOUND_PORT_IMPLEMENTATIONS_DECLARE_CAPABILITY} — only match types that implement {@link
* UseCase}. A service that never does is not caught; it is invisible to them.
* rules that enforce it only match types that implement {@link UseCase}; a service that never does
* is invisible to them.
*
* <p>That is why the Fileserver's multi-method services pass the build today while declaring none
* of the transaction mode, idempotency or repository access every other checked use case declares.
* Resolving it properly means roughly thirty command/query use cases and a decision about where the
* shared status vocabulary lives — an ADR, recorded as open in {@code
* docs/fileserver/design-deviations.md} §5.
* <p>Every operation the transport reaches is now a use case (owner decision 32): one port per
* operation under {@code application.fileserver.port.in}, each implementation declaring its
* capability and, for the writes, a {@code file:*} permission. What remains here is what no
* transport calls. The cleanup and reconciliation services are driven by background workers that
* have no caller identity; a mutating use case must declare a permission
* (MUTATING_USE_CASES_DECLARE_REQUIRED_PERMISSION), and a permission a scheduler cannot hold would
* refuse every run. The writer-lease coordinator is a collaborator the append use case holds, not
* an entrypoint.
*
* <p>Until then the exemption is frozen rather than open-ended. A new Fileserver application
* service fails this test, so the deviation cannot quietly grow while the decision is pending, and
* removing an entry as it is converted is a one-line change that records the progress.
* <p>A new Fileserver application service still fails this test, so the exemption cannot quietly
* grow back.
*/
class FileserverUseCaseContractDeviationTest {
@@ -39,16 +40,7 @@ class FileserverUseCaseContractDeviationTest {
* a pattern would silently absorb the next service, which is the behaviour being prevented.
*/
private static final Set<String> KNOWN_DEVIATIONS =
Set.of(
"DefaultUploadApplicationService",
"DefaultDownloadApplicationService",
"DefaultFinalizeUploadService",
"DefaultSingleShotUploadService",
"DefaultFileLifecycleService",
"DefaultFileserverAdminService",
"DefaultCleanupService",
"DefaultFileReconciliationService",
"WriterLeaseCoordinator");
Set.of("DefaultCleanupService", "DefaultFileReconciliationService", "WriterLeaseCoordinator");
@Test
@DisplayName("no new Fileserver application service may bypass the use-case contract")
@@ -76,9 +68,8 @@ class FileserverUseCaseContractDeviationTest {
.as(
"a Fileserver application service that is not a use case declares none of the "
+ "transaction mode, idempotency or repository access the contract requires, and "
+ "the ArchUnit rules cannot see it. Convert it, or — if the ADR in "
+ "docs/fileserver/design-deviations.md §5 is still open — add it here and say why "
+ "in the pull request.")
+ "the ArchUnit rules cannot see it. Make it a use case behind a port.in "
+ "interface (docs/fileserver/design-deviations.md §5).")
.allSatisfy(name -> assertThat(KNOWN_DEVIATIONS).contains(name));
}
@@ -14,7 +14,7 @@ import org.springframework.boot.context.properties.ConfigurationProperties;
* <p>The naming/idiom SSOT is {@code code-conventions.md}. This test enforces only the rules that
* ArchUnit can decide reliably (N6, I5). {@code [판단]} naming rules (N2/N7/N8/...) and rules with
* intentional project exceptions (N3/N4 — e.g. the {@code IdFactory} domain port, the {@code
* SpringTransactionPort} canonical impl) stay in {@code ca-quality-reviewer} (doc+review), per the
* SpringTransaction} canonical impl) stay in {@code ca-quality-reviewer} (doc+review), per the
* code-conventions enforcement matrix.
*/
@AnalyzeClasses(packages = "dev.caskeleton", importOptions = ProductionClassImportOption.class)
@@ -4,8 +4,14 @@ import static org.assertj.core.api.Assertions.assertThat;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
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.error.GlobalExceptionHandler;
import dev.caskeleton.adapter.inbound.web.fileserver.mapper.RawUploadRequestMapper;
import dev.caskeleton.adapter.outbound.persistence.transaction.SpringTransactionPort;
import dev.caskeleton.adapter.outbound.persistence.transaction.SpringTransaction;
import dev.caskeleton.application.transaction.TransactionPort;
import dev.caskeleton.bootstrap.async.AsyncContextTaskDecorator;
import dev.caskeleton.bootstrap.integration.PostgreSqlTestContainer;
@@ -28,13 +34,17 @@ import java.time.Clock;
import java.util.Comparator;
import java.util.HexFormat;
import java.util.List;
import java.util.Set;
import java.util.stream.Stream;
import org.flywaydb.core.Flyway;
import org.junit.jupiter.api.AfterAll;
import org.junit.jupiter.api.AfterEach;
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.Bean;
@@ -43,7 +53,8 @@ import org.springframework.context.annotation.Import;
import org.springframework.core.task.TaskDecorator;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.security.test.context.support.WithMockUser;
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;
@@ -103,6 +114,9 @@ import tools.jackson.databind.ObjectMapper;
"app.object-storage.enabled=false",
"app.fileserver-platform.instance-id=round-trip-node",
"app.fileserver-platform.security.access-policy=role-based",
// A second write tier that no permission mapping names: the fileserver's own policy admits
// it, so a refusal can only come from the permission gate in front of the use case.
"app.fileserver-platform.security.write-roles=ROLE_FILE_WRITE,ROLE_UNMAPPED_WRITER",
// Metrics are a separate concern with their own tests; leaving them off keeps a MeterRegistry
// out of a context that would otherwise need one only to satisfy a bean signature.
"app.fileserver-platform.observability.metrics-enabled=false",
@@ -111,10 +125,14 @@ import tools.jackson.databind.ObjectMapper;
// real filesystem, so a developer machine with a 90%-full disk would otherwise fail this
// test for a reason that has nothing to do with the seams under test.
"app.fileserver-platform.quota.soft-high-water=0.99",
"app.fileserver-platform.quota.hard-high-water=1.0"
"app.fileserver-platform.quota.hard-high-water=1.0",
// The fileserver's tiers grant their permissions, as security.yml ships them. This
// environment loads no configuration file, so the mapping is restated rather than read.
"ca-skeleton.authz.role-permissions[ROLE_FILE_READ]=file:read",
"ca-skeleton.authz.role-permissions[ROLE_FILE_WRITE]=file:upload,file:delete,file:copy,"
+ "file:move"
})
@AutoConfigureMockMvc(addFilters = false)
@WithMockUser(authorities = {"ROLE_FILE_READ", "ROLE_FILE_WRITE"})
class FileserverCompositionIntegrationTest {
private static final String CORE_CAPABILITY = "jpa-flyway-migration";
@@ -137,6 +155,24 @@ class FileserverCompositionIntegrationTest {
@Autowired private ObjectMapper objectMapper;
/**
* The caller every test acts as unless it says otherwise: a reader and writer.
*
* <p>An {@link AuthenticatedPrincipal}, not a mock user. Method security resolves permissions
* from the principal's roles, and any other principal type is refused outright — which is exactly
* what a {@code @WithMockUser} caller would have been once the upload became a permissioned use
* case. With the filter chain off, nothing else would put a caller in the security context.
*/
@BeforeEach
void actAsReaderAndWriter() {
actAs(Set.of("ROLE_FILE_READ", "ROLE_FILE_WRITE"));
}
@AfterEach
void forgetTheCaller() {
SecurityContextHolder.clearContext();
}
/**
* Applies the operator-owned schema streams and points the runtime at the container.
*
@@ -229,18 +265,58 @@ class FileserverCompositionIntegrationTest {
* actually reaches it: the same request that succeeds above fails here on the roles alone.
*/
@Test
@WithMockUser(authorities = "ROLE_UNRELATED")
void downloadWithoutTheReadRoleIsRefused() throws Exception {
MvcResult refused =
mockMvc.perform(get("/v1/files/{fileId}/content", knownFileId())).andReturn();
String fileId = knownFileId();
actAs(Set.of("ROLE_UNRELATED"));
MvcResult refused = mockMvc.perform(get("/v1/files/{fileId}/content", fileId)).andReturn();
assertThat(refused.getResponse().getStatus()).isEqualTo(403);
}
/**
* The fileserver's tier is not the whole of a write's authority.
*
* <p>{@code ROLE_UNMAPPED_WRITER} is a write tier the fileserver's policy admits, but no role
* mapping grants it {@code file:upload}. The upload is refused by the permission gate on the use
* case's proxy — the one this composition gets from the web adapter's method security — before
* the fileserver's own policy or any storage is reached, so nothing is staged.
*/
@Test
void anUploadByATierWithoutTheUploadPermissionIsRefusedBeforeAnythingIsStaged() throws Exception {
// given
actAs(Set.of("ROLE_FILE_READ", "ROLE_UNMAPPED_WRITER"));
// when
MvcResult refused =
mockMvc
.perform(
post("/v1/files:raw")
.header(RawUploadRequestMapper.FILENAME_HEADER, "refused.txt")
.contentType(MediaType.TEXT_PLAIN)
.content(CONTENT))
.andReturn();
// then
assertThat(List.<Object>of(refused.getResponse().getStatus(), stagingObjects()))
.containsExactly(403, List.of());
}
// =========================================================================
// helpers
// =========================================================================
// 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 void actAs(Set<String> roles) {
SecurityContextHolder.getContext()
.setAuthentication(
new TestingAuthenticationToken(
new AuthenticatedPrincipal("uploader", "uploader@example.test", roles),
"n/a",
List.of()));
}
/** Uploads one file over the raw streaming endpoint and returns the parsed answer. */
private JsonNode upload(byte[] content, String filename) throws Exception {
MvcResult result =
@@ -425,7 +501,17 @@ class FileserverCompositionIntegrationTest {
// declarations over overlapping packages produced a duplicate uploadLeaseRepository definition —
// and, more to the point, a test that declared its own scan would keep passing if the shipped one
// were ever registered nowhere, which is exactly the failure this arrangement exists to catch.
@Import({FileserverPlatformAutoConfiguration.class, DomainContextConfig.class})
@EnableConfigurationProperties(RolePermissionPolicy.class)
@Import({
FileserverPlatformAutoConfiguration.class,
DomainContextConfig.class,
// The permission gate the running application puts in front of every fileserver write, and
// the handler that answers its refusal. Without them a @RequiresPermission is only a marker.
MethodSecurityConfig.class,
AuthorizationAdapter.class,
RolePermissionRegistry.class,
GlobalExceptionHandler.class
})
static class FileserverRuntime {
@Bean
@@ -436,14 +522,14 @@ class FileserverCompositionIntegrationTest {
/**
* The production transaction port, named rather than scanned.
*
* <p>{@code SpringTransactionPort} is a {@code @Component} the running application picks up
* from {@code dev.caskeleton.adapter.outbound.persistence}. Constructing it here keeps the scan
* <p>{@code SpringTransaction} is a {@code @Component} the running application picks up from
* {@code dev.caskeleton.adapter.outbound.persistence}. Constructing it here keeps the scan
* narrow without substituting a different implementation — the boundaries under test are the
* real ones, over the real transaction manager.
*/
@Bean
TransactionPort transactions(PlatformTransactionManager transactionManager) {
return new SpringTransactionPort(transactionManager);
return new SpringTransaction(transactionManager);
}
/**
@@ -47,6 +47,16 @@ ca-skeleton:
# 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
# Fileserver (/v1/files, /v1/uploads, /internal/fileserver; on with the fileserver module).
# Keyed by the fileserver's own default tier roles (app.fileserver-platform.security.*-roles),
# so one role grants both halves of a fileserver write: the permission here, checked on the
# use case, and the tier FileAccessPolicyPort checks inside it along with ownership. The
# brackets keep the underscores, which unbracketed map keys lose in binding. A deployment that
# renames those roles maps its own names here too. The tiers do not inherit, and neither do
# these: a writer that also reads holds both roles.
"[ROLE_FILE_READ]": file:read
"[ROLE_FILE_WRITE]": file:upload,file:delete,file:copy,file:move
"[ROLE_FILE_ADMIN]": file:admin
cors:
# true | false
enabled: ${APP_SECURITY_CORS_ENABLED:false}