merge: integrate messaging R2 polling producer

# Conflicts:
#	docs/superpowers/specs/2026-07-28-messaging-production-capability-design.md
#	src/app-bootstrap/gradle.lockfile
#	src/app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/ArchitectureViolationFixtureTest.java
#	src/build.gradle
This commit is contained in:
donghyeon-ka
2026-08-01 00:04:02 +09:00
92 changed files with 10591 additions and 54 deletions
+5
View File
@@ -22,6 +22,9 @@ Package root: `dev.caskeleton.sample.portfolio`.
`RepoStatsAclMapper`), `adapter/identifier` (`UuidWorkLogIdFactory`).
- Contract-test fixtures the app-bootstrap verification suite analyses
(`DomainExceptionHandler`, `PortfolioErrorCode`, wire/contract tests).
- Disposable messaging contract fixture: the exact `WorkLogReservedPayload` record, its static
application-core contract contribution, sample-owned schema/digest and golden vectors. It is not
runtime-discovered, and validator compatibility remains unproven until messaging Task 6.
- Sample application collaborators consume invocation context through application-core ports and
must not import SLF4J/MDC.
@@ -39,6 +42,8 @@ Package root: `dev.caskeleton.sample.portfolio`.
- Production-required behaviour living here: deleting this module must not break the
production build or runtime (the base `GlobalExceptionHandler`, envelope, and
error-code contract live in `adapter:inbound:web` / `shared-contract`).
- Treating a sample schema/contribution as an automatically discovered production registry entry,
or placing JSON mapper, physical topic, Kafka or bootstrap-server concerns in the contribution.
## Test
+17
View File
@@ -223,6 +223,23 @@ curl -X POST localhost:8080/work-logs -H 'Content-Type: application/json' -d '{
이벤트의 클래스 단순명을 쓰는 대안도 있지만, 클래스 이름을 바꾸면 토픽이 조용히 바뀌어 컨슈머가
깨질 수 있어, 안정적인 문자열 리터럴을 택했습니다(토픽 마이그레이션 계획 없이는 바꾸지 말 것).
### WorkLogReservedPayload / …ContractContribution — canonical contract fixture
- `WorkLogReservedPayload`는 새 closed contract SPI에 제공하는 exact final record다. v1은
`workLogId` 하나만 소유하며, schema와 같은 canonical bounded identifier 규칙을 생성자에서 지킨다.
- `contracts/messaging/portfolio.worklog.reserved/v1.schema.json`과 golden vector는
**sample fixture contract**다. 공통 envelope는 WorkLog 필드를 알지 못하며 이 모듈을 삭제해도
production module build/runtime은 깨지지 않아야 한다.
- contribution은 contract ID, exact payload type/component order, classpath resource ID, checked-in
digest와 provider-neutral descriptor만 제공한다. JSON mapper, physical topic, Kafka 설정을 소유하지
않으며 매 호출 filesystem I/O도 하지 않는다.
- 기존 3-field `WorkLogReservedIntegrationEvent`/hand-rolled mapper는 현재 legacy outbox
characterization 경로에 남아 있다. 새 1-field canonical payload는 그 타입을 조용히 대체하지 않으며,
closed catalog와 encoder가 조립되기 전까지 양쪽은 서로 호출하거나 직렬화하지 않는다.
- 현재는 classpath scanning이나 runtime discovery가 없다. Task 5의 closed catalog 조립 전에는
자동 등록되지 않고, Task 6 validator qualification 전에는 Draft 2020-12 validator compatibility를
주장하지 않는다.
### RepoStatsPort
- 외부 저장소 통계를 가져오는 아웃바운드 포트(구현은 adapter-outbound).
@@ -0,0 +1,69 @@
package dev.caskeleton.sample.portfolio.application.event;
import dev.caskeleton.application.messaging.contract.ContractDescriptor;
import dev.caskeleton.application.messaging.contract.ContractId;
import dev.caskeleton.application.messaging.contract.IntegrationEventContractContribution;
import dev.caskeleton.application.messaging.contract.LogicalDestinationId;
import dev.caskeleton.application.messaging.contract.SchemaResourceId;
import dev.caskeleton.application.messaging.contract.Sha256;
import java.time.Duration;
import java.util.HexFormat;
import java.util.List;
/** Static sample contribution for the {@code portfolio.worklog.reserved} v1 contract. */
public final class WorkLogReservedContractContribution
implements IntegrationEventContractContribution<WorkLogReservedPayload> {
private static final ContractId CONTRACT_ID = new ContractId("portfolio.worklog.reserved");
private static final SchemaResourceId SCHEMA_RESOURCE =
new SchemaResourceId("contracts/messaging/portfolio.worklog.reserved/v1.schema.json");
private static final Sha256 SCHEMA_HASH =
new Sha256(
HexFormat.of()
.parseHex("7264efd4e2531e6fd00010bb3deca96a" + "f2f1d0408d0021d014feaf90190f2eac"));
private static final ContractDescriptor DESCRIPTOR =
new ContractDescriptor(
"sample-portfolio",
new LogicalDestinationId("portfolio-domain-events"),
"json-schema-envelope-v1",
true,
64 * 1024,
128 * 1024,
ContractDescriptor.SensitivityClassification.INTERNAL,
Duration.ofDays(7));
@Override
public ContractId contractId() {
return CONTRACT_ID;
}
@Override
public int payloadVersion() {
return 1;
}
@Override
public Class<WorkLogReservedPayload> exactPayloadRecordType() {
return WorkLogReservedPayload.class;
}
@Override
public List<String> canonicalRecordComponentOrder() {
return List.of("workLogId");
}
@Override
public SchemaResourceId payloadSchemaResource() {
return SCHEMA_RESOURCE;
}
@Override
public Sha256 payloadSchemaHash() {
return SCHEMA_HASH;
}
@Override
public ContractDescriptor descriptor() {
return DESCRIPTOR;
}
}
@@ -0,0 +1,19 @@
package dev.caskeleton.sample.portfolio.application.event;
import dev.caskeleton.application.messaging.contract.IntegrationPayload;
/** Immutable sample payload for the {@code portfolio.worklog.reserved} v1 contract. */
public record WorkLogReservedPayload(String workLogId) implements IntegrationPayload {
private static final int MAXIMUM_WORK_LOG_ID_LENGTH = 160;
private static final String WORK_LOG_ID_GRAMMAR = "[A-Za-z0-9][A-Za-z0-9._:-]*";
public WorkLogReservedPayload {
if (workLogId == null
|| workLogId.length() > MAXIMUM_WORK_LOG_ID_LENGTH
|| !workLogId.matches(WORK_LOG_ID_GRAMMAR)) {
throw new IllegalArgumentException(
"workLogId must be a 1-160 character canonical US-ASCII identifier");
}
}
}
@@ -0,0 +1,18 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "urn:dev-caskeleton:contracts:messaging:portfolio.worklog.reserved:v1",
"title": "WorkLogReserved payload v1",
"type": "object",
"required": [
"workLogId"
],
"properties": {
"workLogId": {
"type": "string",
"minLength": 1,
"maxLength": 160,
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
}
},
"unevaluatedProperties": false
}
@@ -0,0 +1 @@
7264efd4e2531e6fd00010bb3deca96af2f1d0408d0021d014feaf90190f2eac
@@ -0,0 +1,181 @@
package dev.caskeleton.sample.portfolio.application.event;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import dev.caskeleton.application.messaging.contract.ContractDescriptor;
import dev.caskeleton.application.messaging.contract.ContractId;
import dev.caskeleton.application.messaging.contract.IntegrationPayload;
import dev.caskeleton.application.messaging.contract.LogicalDestinationId;
import dev.caskeleton.application.messaging.contract.SchemaResourceId;
import java.io.IOException;
import java.io.InputStream;
import java.lang.reflect.Modifier;
import java.net.URI;
import java.nio.ByteBuffer;
import java.nio.charset.CharacterCodingException;
import java.nio.charset.CodingErrorAction;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.time.Duration;
import java.util.HexFormat;
import java.util.Locale;
import org.junit.jupiter.api.Test;
class WorkLogReservedContractContributionTest {
private static final String SCHEMA_RESOURCE =
"contracts/messaging/portfolio.worklog.reserved/v1.schema.json";
private static final String DIGEST_RESOURCE =
"contracts/messaging/portfolio.worklog.reserved/v1.schema.sha256";
private static final String VALID_RESOURCE =
"contracts/messaging/portfolio.worklog.reserved/v1.valid.json";
private static final String INVALID_UNKNOWN_FIELD_RESOURCE =
"contracts/messaging/portfolio.worklog.reserved/v1.invalid-unknown-field.json";
private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper();
@Test
void payloadIsTheExactImmutableValidatedIntegrationPayloadRecord() {
WorkLogReservedPayload payload = new WorkLogReservedPayload("worklog-42");
assertThat(payload.workLogId()).isEqualTo("worklog-42");
assertThat(WorkLogReservedPayload.class.isRecord()).isTrue();
assertThat(Modifier.isFinal(WorkLogReservedPayload.class.getModifiers())).isTrue();
assertThat(IntegrationPayload.class).isAssignableFrom(WorkLogReservedPayload.class);
assertThatThrownBy(() -> new WorkLogReservedPayload(null))
.isInstanceOf(IllegalArgumentException.class);
assertThatThrownBy(() -> new WorkLogReservedPayload(""))
.isInstanceOf(IllegalArgumentException.class);
assertThatThrownBy(() -> new WorkLogReservedPayload("worklog 42"))
.isInstanceOf(IllegalArgumentException.class);
assertThatThrownBy(() -> new WorkLogReservedPayload("x".repeat(161)))
.isInstanceOf(IllegalArgumentException.class);
}
@Test
void contributionPublishesOnlyTheClosedProviderNeutralContractDescription() {
WorkLogReservedContractContribution contribution = new WorkLogReservedContractContribution();
assertThat(contribution.contractId()).isEqualTo(new ContractId("portfolio.worklog.reserved"));
assertThat(contribution.payloadVersion()).isEqualTo(1);
assertThat(contribution.exactPayloadRecordType()).isEqualTo(WorkLogReservedPayload.class);
assertThat(contribution.canonicalRecordComponentOrder()).containsExactly("workLogId");
assertThat(contribution.payloadSchemaResource())
.isEqualTo(
new SchemaResourceId("contracts/messaging/portfolio.worklog.reserved/v1.schema.json"));
assertThat(contribution.payloadSchemaHash()).isSameAs(contribution.payloadSchemaHash());
ContractDescriptor descriptor = contribution.descriptor();
assertThat(descriptor.ownerModule()).isEqualTo("sample-portfolio");
assertThat(descriptor.logicalDestination())
.isEqualTo(new LogicalDestinationId("portfolio-domain-events"));
assertThat(descriptor.serializerId()).isEqualTo("json-schema-envelope-v1");
assertThat(descriptor.orderingRequired()).isTrue();
assertThat(descriptor.maximumPayloadBytes()).isEqualTo(64 * 1024);
assertThat(descriptor.maximumEnvelopeBytes()).isEqualTo(128 * 1024);
assertThat(descriptor.sensitivityClassification())
.isEqualTo(ContractDescriptor.SensitivityClassification.INTERNAL);
assertThat(descriptor.sameEventRequeueHorizon()).isEqualTo(Duration.ofDays(7));
assertThat(WorkLogReservedContractContribution.class.getDeclaredMethods())
.allSatisfy(
method -> {
String name = method.getName().toLowerCase(Locale.ROOT);
assertThat(name)
.doesNotContain(
"json", "mapper", "tree", "parser", "topic", "kafka", "bootstrap");
});
}
@Test
void checkedInPayloadSchemaIsClosedBoundedAndMatchesItsExactByteDigest() throws Exception {
byte[] schemaBytes = readResource(SCHEMA_RESOURCE);
String schemaText = strictUtf8(schemaBytes);
JsonNode schema = OBJECT_MAPPER.readTree(schemaText);
assertThat(schema.path("$schema").textValue())
.isEqualTo("https://json-schema.org/draft/2020-12/schema");
String schemaId = schema.path("$id").textValue();
assertThat(schemaId)
.isEqualTo("urn:dev-caskeleton:contracts:messaging:portfolio.worklog.reserved:v1");
assertThat(URI.create(schemaId).isAbsolute()).isTrue();
assertThat(schema.path("type").textValue()).isEqualTo("object");
assertThat(schema.path("required")).containsExactly(OBJECT_MAPPER.valueToTree("workLogId"));
assertThat(schema.path("properties").size()).isEqualTo(1);
assertThat(schema.path("properties").has("workLogId")).isTrue();
JsonNode workLogId = schema.path("properties").path("workLogId");
assertThat(workLogId.path("type").textValue()).isEqualTo("string");
assertThat(workLogId.path("minLength").intValue()).isEqualTo(1);
assertThat(workLogId.path("maxLength").intValue()).isEqualTo(160);
assertThat(workLogId.path("pattern").textValue()).isEqualTo("^[A-Za-z0-9][A-Za-z0-9._:-]*$");
assertThat(schema.path("unevaluatedProperties").booleanValue()).isFalse();
assertThat(schemaText).doesNotContainPattern("\"type\"\\s*:\\s*\\[[^]]*\"null\"");
assertThat(schemaText).doesNotContain("\"$ref\"");
byte[] manifestBytes = readResource(DIGEST_RESOURCE);
String manifest = strictUtf8(manifestBytes);
assertThat(manifestBytes).endsWith((byte) '\n');
assertThat(manifest).matches("[0-9a-f]{64}\\n");
String exactDigest =
HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(schemaBytes));
assertThat(manifest).isEqualTo(exactDigest + "\n");
WorkLogReservedContractContribution contribution = new WorkLogReservedContractContribution();
assertThat(contribution.payloadSchemaHash().toString()).isEqualTo(exactDigest);
}
@Test
void goldenVectorsFreezeRequiredUnknownAndNullPolicyWithoutClaimingValidatorCompatibility()
throws Exception {
JsonNode valid = OBJECT_MAPPER.readTree(strictUtf8(readResource(VALID_RESOURCE)));
JsonNode invalidUnknown =
OBJECT_MAPPER.readTree(strictUtf8(readResource(INVALID_UNKNOWN_FIELD_RESOURCE)));
JsonNode missing = OBJECT_MAPPER.readTree("{}");
JsonNode explicitNull = OBJECT_MAPPER.readTree("{\"workLogId\":null}");
assertThat(valid).isEqualTo(OBJECT_MAPPER.readTree("{\"workLogId\":\"worklog-42\"}"));
assertThat(invalidUnknown.path("workLogId").textValue()).isEqualTo("worklog-42");
assertThat(invalidUnknown.has("unexpected")).isTrue();
assertThat(matchesStructuralV1Policy(valid)).isTrue();
assertThat(matchesStructuralV1Policy(invalidUnknown)).isFalse();
assertThat(matchesStructuralV1Policy(missing)).isFalse();
assertThat(matchesStructuralV1Policy(explicitNull)).isFalse();
}
private static boolean matchesStructuralV1Policy(JsonNode candidate) {
if (!candidate.isObject() || candidate.size() != 1 || !candidate.has("workLogId")) {
return false;
}
JsonNode workLogId = candidate.path("workLogId");
if (!workLogId.isTextual()) {
return false;
}
String value = workLogId.textValue();
return value.length() <= 160 && value.matches("[A-Za-z0-9][A-Za-z0-9._:-]*");
}
private static byte[] readResource(String resource) throws IOException {
try (InputStream input =
WorkLogReservedContractContributionTest.class
.getClassLoader()
.getResourceAsStream(resource)) {
if (input == null) {
throw new IOException("Missing classpath resource: " + resource);
}
return input.readAllBytes();
}
}
private static String strictUtf8(byte[] bytes) throws CharacterCodingException {
return StandardCharsets.UTF_8
.newDecoder()
.onMalformedInput(CodingErrorAction.REPORT)
.onUnmappableCharacter(CodingErrorAction.REPORT)
.decode(ByteBuffer.wrap(bytes))
.toString();
}
}
@@ -0,0 +1 @@
{"workLogId":"worklog-42","unexpected":"rejected"}
@@ -0,0 +1 @@
{"workLogId":"worklog-42"}