feat: jpa, messaging, notification, mongo, graphql 어댑터터 리펙토링

This commit is contained in:
DongHyeonka
2026-08-18 10:59:56 +09:00
parent 2f5d2fc219
commit e98b56eb03
372 changed files with 25131 additions and 20357 deletions
@@ -0,0 +1,89 @@
package dev.caskeleton.shared.activation;
import java.util.EnumMap;
import java.util.List;
import java.util.Map;
/**
* The five adapters 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");
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());
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);
}
}
@@ -0,0 +1,54 @@
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 {}
}
@@ -0,0 +1,51 @@
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);
}
}
@@ -0,0 +1,81 @@
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("each switch carries its canonical env name")
void environmentNamesAreCanonical() {
assertThat(MasterSwitch.PERSISTENCE_JPA.environmentVariable())
.isEqualTo("APP_PERSISTENCE_JPA_ENABLED");
assertThat(MasterSwitch.PERSISTENCE_MONGO.environmentVariable())
.isEqualTo("APP_PERSISTENCE_MONGO_ENABLED");
assertThat(MasterSwitch.MESSAGING.environmentVariable()).isEqualTo("APP_MESSAGING_ENABLED");
assertThat(MasterSwitch.NOTIFICATION_PLATFORM.environmentVariable())
.isEqualTo("APP_NOTIFICATION_PLATFORM_ENABLED");
assertThat(MasterSwitch.GRAPHQL.environmentVariable()).isEqualTo("APP_GRAPHQL_ENABLED");
}
}