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:
@@ -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
|
||||
|
||||
|
||||
@@ -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).
|
||||
|
||||
|
||||
+69
@@ -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;
|
||||
}
|
||||
}
|
||||
+19
@@ -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");
|
||||
}
|
||||
}
|
||||
}
|
||||
+18
@@ -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
|
||||
}
|
||||
+1
@@ -0,0 +1 @@
|
||||
7264efd4e2531e6fd00010bb3deca96af2f1d0408d0021d014feaf90190f2eac
|
||||
+181
@@ -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();
|
||||
}
|
||||
}
|
||||
+1
@@ -0,0 +1 @@
|
||||
{"workLogId":"worklog-42","unexpected":"rejected"}
|
||||
+1
@@ -0,0 +1 @@
|
||||
{"workLogId":"worklog-42"}
|
||||
Reference in New Issue
Block a user