refactor: 부가 기능을 capability 모듈로 포장하고 기본 조립을 web-only로 전환
설계: docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md
계획/진행 기록: docs/superpowers/plans/2026-09-25-capability-module-packaging.md
- Wave 0: 규칙 고정(AGENTS.md capability 완료 기준·테스트 규칙) + 차단 결함 7건
(compose overlay 검사, redis-sdk CI job, 적용된 V9/V13 원복 + V16, @EnableScheduling,
messaging bridge 순서, prod 에러 상세 validator, sample loggers read-only)
- Wave 1: 데이터·보안 Critical 10건 (durable operation 25P02, operation 유스케이스 이동,
outbox 재인코딩, Kafka TLS/SASL, 알림 트랜잭션, SNS 서명, tus checksum, GraphQL fragment,
Redis lane, gRPC FAILED_TERMINAL)
- Wave 2: 리팩터링 잔재·실험용 자리 삭제, outbox v1 fencing(V17), 멱등성 V2 정본화
- Wave 3: 라이브러리형 코드 정리(동작하지 않는 설정·인터페이스·gate 제거, web-advanced 분리)
- Wave 4: capability 11개를 "있으면 켜짐" 모듈로 포장, 끄는 장치 제거, 기본 조립 web-only,
qualificationBootJar 분리
- Wave 5: 빌드 로직 축소(17.2k -> 10.8k줄), sample 테스트 컨벤션 적용
삭제한 코드는 docs/capability-status.md "제거된 코드" 표에 복구 커밋(208077fd)과 함께 기록.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
208077fddf
commit
6d27356e2b
@@ -1,6 +1,5 @@
|
||||
plugins {
|
||||
id 'ca.java-library'
|
||||
id 'ca.strict-qualification'
|
||||
}
|
||||
|
||||
// Skeleton-wide operational contracts only. No business/domain concepts.
|
||||
@@ -8,18 +7,12 @@ plugins {
|
||||
dependencies {
|
||||
}
|
||||
|
||||
def messagingSharedSchemaQualification = extensions.getByName('strictQualification').register(
|
||||
'messagingSharedSchemaQualificationTest',
|
||||
sourceSets.test,
|
||||
[
|
||||
'dev.caskeleton.shared.contract.messaging.MessagingEnvelopeSchemaResourceTest'
|
||||
],
|
||||
rootProject.layout.buildDirectory.dir(
|
||||
'test-results/messaging-evidence/shared'),
|
||||
rootProject.layout.buildDirectory.dir(
|
||||
'test-results/messaging-evidence-binary/shared'),
|
||||
'Runs exact Messaging shared schema qualification tests.'
|
||||
)
|
||||
messagingSharedSchemaQualification.configure {
|
||||
dependsOn ':prepareMessagingContractEvidence'
|
||||
// Half of the root `verifyMessagingContracts`: the shared envelope schema, run by name, no skips.
|
||||
strictTestLanes {
|
||||
lane('messagingSharedSchemaQualificationTest') {
|
||||
description = 'Runs exact Messaging shared schema qualification tests.'
|
||||
requires 'dev.caskeleton.shared.contract.messaging.MessagingEnvelopeSchemaResourceTest'
|
||||
rejectSkipped = true
|
||||
jvmArgs '-Duser.timezone=UTC'
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,102 +0,0 @@
|
||||
package dev.caskeleton.shared.activation;
|
||||
|
||||
import java.util.EnumMap;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
|
||||
/**
|
||||
* The runtime capabilities this skeleton ships behind an explicit switch, and the names that
|
||||
* address them.
|
||||
*
|
||||
* <p>One place knows the names. Spread across conditions as string literals, a rename becomes a
|
||||
* silent activation change: the condition stops matching, the adapter stops assembling, and nothing
|
||||
* reports it.
|
||||
*
|
||||
* <p>The superseded names sit in a static map rather than in an instance field, because Error
|
||||
* Prone's {@code ImmutableEnumChecker} rejects a collection-typed field on an enum and this
|
||||
* repository compiles with {@code -Werror}. The two scalar names stay as fields, since a String is
|
||||
* already immutable.
|
||||
*/
|
||||
public enum MasterSwitch {
|
||||
/** Relational persistence: entity scan, repositories, pool, migration. */
|
||||
PERSISTENCE_JPA("ca-skeleton.persistence-jpa.enabled", "APP_PERSISTENCE_JPA_ENABLED"),
|
||||
/** MongoDB persistence. */
|
||||
PERSISTENCE_MONGO("ca-skeleton.persistence-mongo.enabled", "APP_PERSISTENCE_MONGO_ENABLED"),
|
||||
/** Broker publication and consumption. */
|
||||
MESSAGING("app.messaging.enabled", "APP_MESSAGING_ENABLED"),
|
||||
/** The notification delivery platform. */
|
||||
NOTIFICATION_PLATFORM(
|
||||
"ca-skeleton.notification.platform.enabled", "APP_NOTIFICATION_PLATFORM_ENABLED"),
|
||||
/** The GraphQL transport boundary. */
|
||||
GRAPHQL("backend.graphql.enabled", "APP_GRAPHQL_ENABLED"),
|
||||
/** The shared Redis runtime substrate. */
|
||||
REDIS("app.redis.enabled", "APP_REDIS_ENABLED"),
|
||||
/** The explicit Fileserver R2 publication capability. */
|
||||
FILESERVER("app.fileserver.enabled", "APP_FILESERVER_ENABLED"),
|
||||
/** The HTTP upload/download Fileserver platform. */
|
||||
FILESERVER_PLATFORM("app.fileserver-platform.enabled", "APP_FILESERVER_PLATFORM_ENABLED"),
|
||||
/** The outbound HTTP client platform. */
|
||||
HTTPCLIENT("app.httpclient.enabled", "APP_HTTPCLIENT_ENABLED");
|
||||
|
||||
private static final Map<MasterSwitch, List<String>> SUPERSEDED = supersededProperties();
|
||||
|
||||
private final String property;
|
||||
private final String environmentVariable;
|
||||
|
||||
MasterSwitch(String property, String environmentVariable) {
|
||||
this.property = property;
|
||||
this.environmentVariable = environmentVariable;
|
||||
}
|
||||
|
||||
private static Map<MasterSwitch, List<String>> supersededProperties() {
|
||||
Map<MasterSwitch, List<String>> superseded = new EnumMap<>(MasterSwitch.class);
|
||||
// Gated only add-on beans while reading as a whole-adapter switch, and defaulted to on.
|
||||
superseded.put(PERSISTENCE_JPA, List.of("app.jpa-platform.enabled"));
|
||||
superseded.put(PERSISTENCE_MONGO, List.of());
|
||||
superseded.put(MESSAGING, List.of());
|
||||
// Deliberately empty. The notification provider selectors and the two GraphQL safety flags are
|
||||
// often described as "legacy activation", and they are not alternative spellings of these
|
||||
// switches — they are subordinate settings that stay meaningful while the adapter is on.
|
||||
// Listing
|
||||
// them here made every shipped configuration ambiguous, because a provider selector is present
|
||||
// in the default configuration and would collide with a master switch that is legitimately set.
|
||||
// Their own migrations are keyed to the settings that replace them: the provider selectors to
|
||||
// the
|
||||
// delivery-platform runtime, and backend.graphql.production / .environment to
|
||||
// backend.graphql.deployment-mode.
|
||||
superseded.put(NOTIFICATION_PLATFORM, List.of());
|
||||
superseded.put(GRAPHQL, List.of());
|
||||
superseded.put(REDIS, List.of());
|
||||
superseded.put(FILESERVER, List.of());
|
||||
superseded.put(FILESERVER_PLATFORM, List.of());
|
||||
superseded.put(HTTPCLIENT, List.of());
|
||||
return Map.copyOf(superseded);
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the canonical Spring property name.
|
||||
*
|
||||
* @return the property this switch is read from
|
||||
*/
|
||||
public String property() {
|
||||
return property;
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the canonical environment variable name.
|
||||
*
|
||||
* @return the operator-facing environment variable
|
||||
*/
|
||||
public String environmentVariable() {
|
||||
return environmentVariable;
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns property names this switch supersedes, which are now migration errors.
|
||||
*
|
||||
* @return superseded property names, possibly empty
|
||||
*/
|
||||
public List<String> legacyProperties() {
|
||||
return SUPERSEDED.get(this);
|
||||
}
|
||||
}
|
||||
-54
@@ -1,54 +0,0 @@
|
||||
package dev.caskeleton.shared.activation;
|
||||
|
||||
/**
|
||||
* The outcome of reading one master switch. Only {@link Off} and {@link On} may start a context.
|
||||
*/
|
||||
public sealed interface MasterSwitchParseResult {
|
||||
|
||||
/**
|
||||
* The switch this result describes.
|
||||
*
|
||||
* @return the owning switch
|
||||
*/
|
||||
MasterSwitch owner();
|
||||
|
||||
/**
|
||||
* The switch is off, either explicitly or because nobody set it.
|
||||
*
|
||||
* @param owner the switch that is off
|
||||
*/
|
||||
record Off(MasterSwitch owner) implements MasterSwitchParseResult {}
|
||||
|
||||
/**
|
||||
* The switch is on.
|
||||
*
|
||||
* @param owner the switch that is on
|
||||
*/
|
||||
record On(MasterSwitch owner) implements MasterSwitchParseResult {}
|
||||
|
||||
/**
|
||||
* The value is neither {@code true} nor {@code false}.
|
||||
*
|
||||
* @param owner the switch that was misconfigured
|
||||
* @param raw the rejected raw value
|
||||
*/
|
||||
record Invalid(MasterSwitch owner, String raw) implements MasterSwitchParseResult {}
|
||||
|
||||
/**
|
||||
* Canonical and legacy keys are both set.
|
||||
*
|
||||
* @param owner the switch addressed by both keys
|
||||
* @param legacyProperty the superseded key that is also present
|
||||
*/
|
||||
record Ambiguous(MasterSwitch owner, String legacyProperty) implements MasterSwitchParseResult {}
|
||||
|
||||
/**
|
||||
* Only a superseded key is set.
|
||||
*
|
||||
* @param owner the switch the legacy key used to address
|
||||
* @param legacyProperty the superseded key that is present
|
||||
* @param replacementProperty the canonical key to use instead
|
||||
*/
|
||||
record LegacyOnly(MasterSwitch owner, String legacyProperty, String replacementProperty)
|
||||
implements MasterSwitchParseResult {}
|
||||
}
|
||||
-51
@@ -1,51 +0,0 @@
|
||||
package dev.caskeleton.shared.activation;
|
||||
|
||||
import java.util.Locale;
|
||||
import java.util.Map;
|
||||
|
||||
/**
|
||||
* Reads one master switch, strictly.
|
||||
*
|
||||
* <p>No Spring types, so the rule is testable without a context — and usable by the environment
|
||||
* post-processor, which has to run before there is one.
|
||||
*
|
||||
* <p>The strictness is the design. {@code yes} read as true turns something on by accident; {@code
|
||||
* yes} read as false is a deployment that believes it turned something on and did not. Rejecting
|
||||
* the value is the only answer that cannot be wrong in a way nobody notices.
|
||||
*/
|
||||
public final class MasterSwitchParser {
|
||||
|
||||
private MasterSwitchParser() {}
|
||||
|
||||
/**
|
||||
* Parses a switch from its canonical raw value and whatever legacy keys are present.
|
||||
*
|
||||
* @param owner the switch being read
|
||||
* @param canonicalRaw the raw canonical value, or null when unset
|
||||
* @param legacyRaw legacy property names to their raw values; only present keys belong here
|
||||
* @return the parse outcome
|
||||
*/
|
||||
public static MasterSwitchParseResult parse(
|
||||
MasterSwitch owner, String canonicalRaw, Map<String, String> legacyRaw) {
|
||||
String legacyPresent =
|
||||
owner.legacyProperties().stream().filter(legacyRaw::containsKey).findFirst().orElse(null);
|
||||
|
||||
if (canonicalRaw != null && legacyPresent != null) {
|
||||
return new MasterSwitchParseResult.Ambiguous(owner, legacyPresent);
|
||||
}
|
||||
if (canonicalRaw == null && legacyPresent != null) {
|
||||
return new MasterSwitchParseResult.LegacyOnly(owner, legacyPresent, owner.property());
|
||||
}
|
||||
if (canonicalRaw == null) {
|
||||
return new MasterSwitchParseResult.Off(owner);
|
||||
}
|
||||
String normalized = canonicalRaw.toLowerCase(Locale.ROOT);
|
||||
if ("true".equals(normalized)) {
|
||||
return new MasterSwitchParseResult.On(owner);
|
||||
}
|
||||
if ("false".equals(normalized)) {
|
||||
return new MasterSwitchParseResult.Off(owner);
|
||||
}
|
||||
return new MasterSwitchParseResult.Invalid(owner, canonicalRaw);
|
||||
}
|
||||
}
|
||||
-86
@@ -1,86 +0,0 @@
|
||||
package dev.caskeleton.shared.activation;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
|
||||
import java.util.Map;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
/**
|
||||
* A master switch is the one value an operator must be able to trust absolutely.
|
||||
*
|
||||
* <p>Every rule here exists because the permissive alternative fails silently. {@code yes} parsed
|
||||
* as true is a deployment that turned something on by accident; {@code yes} parsed as false is a
|
||||
* deployment that thought it turned something on and did not. Rejecting it is the only answer that
|
||||
* cannot be wrong in a way nobody notices.
|
||||
*/
|
||||
class MasterSwitchParserTest {
|
||||
|
||||
@Test
|
||||
@DisplayName("an unset switch is off")
|
||||
void unsetIsOff() {
|
||||
assertThat(MasterSwitchParser.parse(MasterSwitch.GRAPHQL, null, Map.of()))
|
||||
.isInstanceOf(MasterSwitchParseResult.Off.class);
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("true and false parse case-insensitively")
|
||||
void booleansParse() {
|
||||
assertThat(MasterSwitchParser.parse(MasterSwitch.GRAPHQL, "TRUE", Map.of()))
|
||||
.isInstanceOf(MasterSwitchParseResult.On.class);
|
||||
assertThat(MasterSwitchParser.parse(MasterSwitch.GRAPHQL, "False", Map.of()))
|
||||
.isInstanceOf(MasterSwitchParseResult.Off.class);
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("yes, 1, on, blank, and whitespace are configuration errors rather than off")
|
||||
void truthyLookalikesAreRejected() {
|
||||
for (String raw : new String[] {"yes", "1", "on", "", " ", "true ", " false", "ture"}) {
|
||||
assertThat(MasterSwitchParser.parse(MasterSwitch.MESSAGING, raw, Map.of()))
|
||||
.as("%s must be rejected; a silent off here is a deployment that thinks it is on", raw)
|
||||
.isInstanceOf(MasterSwitchParseResult.Invalid.class);
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("canonical and legacy together are ambiguous even when they agree")
|
||||
void agreeingDuplicatesAreStillAmbiguous() {
|
||||
MasterSwitchParseResult result =
|
||||
MasterSwitchParser.parse(
|
||||
MasterSwitch.PERSISTENCE_JPA, "true", Map.of("app.jpa-platform.enabled", "true"));
|
||||
assertThat(result)
|
||||
.as(
|
||||
"two keys that agree today diverge the first time somebody edits one of them; the "
|
||||
+ "ambiguity is the defect, not the disagreement")
|
||||
.isInstanceOf(MasterSwitchParseResult.Ambiguous.class);
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a legacy key alone names its replacement")
|
||||
void legacyAloneNamesTheReplacement() {
|
||||
MasterSwitchParseResult result =
|
||||
MasterSwitchParser.parse(
|
||||
MasterSwitch.PERSISTENCE_JPA, null, Map.of("app.jpa-platform.enabled", "true"));
|
||||
assertThat(result).isInstanceOf(MasterSwitchParseResult.LegacyOnly.class);
|
||||
assertThat(((MasterSwitchParseResult.LegacyOnly) result).replacementProperty())
|
||||
.isEqualTo("ca-skeleton.persistence-jpa.enabled");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("every switch has one unique operator-facing APP_* environment name")
|
||||
void environmentNamesAreCanonical() {
|
||||
var names =
|
||||
java.util.Arrays.stream(MasterSwitch.values())
|
||||
.map(MasterSwitch::environmentVariable)
|
||||
.toList();
|
||||
|
||||
assertThat(names)
|
||||
.allSatisfy(
|
||||
name -> {
|
||||
assertThat(name).startsWith("APP_").endsWith("_ENABLED");
|
||||
assertThat(name).doesNotContain(".");
|
||||
})
|
||||
.doesNotHaveDuplicates();
|
||||
assertThat(MasterSwitch.GRAPHQL.environmentVariable()).isEqualTo("APP_GRAPHQL_ENABLED");
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user