refactor: 각 어댑터터별 리펙토링 진행

This commit is contained in:
DongHyeonka
2026-08-24 18:26:40 +09:00
parent 16e33ce986
commit a261df2a2b
100 changed files with 7072 additions and 902 deletions
@@ -3,15 +3,22 @@ package dev.caskeleton.messaging.api;
/**
* Workflow-scoped correlation value shared by every message of one business flow.
*
* @param value the correlation value, 1 to 160 characters
* <p>This value is copied onto every message of a flow and onto the header set of every broker the
* flow touches, so it is bounded in {@link WireSafeText UTF-8 bytes} rather than in Java
* characters: the previous 160-character bound admitted a 640-byte value, which a broker with a
* byte-counted header budget rejects at publish time, mid-flow, on a message the caller cannot
* resend under a different identity.
*
* @param value the correlation value, 1 to 160 UTF-8 bytes and free of control characters
*/
public record CorrelationId(String value) {
private static final int MAX_LENGTH = 160;
private static final int MAX_BYTES = 160;
public CorrelationId {
if (value == null || value.isBlank() || value.length() > MAX_LENGTH) {
throw new IllegalArgumentException("correlationId must contain 1 to 160 characters");
if (value == null || value.isBlank()) {
throw new IllegalArgumentException("correlationId must not be blank");
}
WireSafeText.require(value, "a correlation id", MAX_BYTES);
}
}
@@ -62,8 +62,18 @@ public record MessageEnvelope<T>(
Objects.requireNonNull(traceContext, "traceContext must not be null");
Objects.requireNonNull(headers, "headers must not be null");
Objects.requireNonNull(payload, "payload must not be null");
// Both keys are routing input the caller chooses, and both used to be unbounded strings. A
// partition key is hashed by the broker, so an unbounded one is a cost rather than a
// correctness problem; an ordering key is carried on the wire by several bindings, so a
// control character in it is the same injection primitive as in a header. The bound is the
// smallest one every targeted broker accepts.
partitionKey.ifPresent(key -> WireSafeText.require(key, "a partition key", MAX_KEY_BYTES));
orderingKey.ifPresent(key -> WireSafeText.require(key, "an ordering key", MAX_KEY_BYTES));
}
/** The routing-key bound every targeted broker accepts. */
private static final int MAX_KEY_BYTES = 1024;
/**
* Returns a copy of this envelope carrying a different payload representation.
*
@@ -119,6 +129,31 @@ public record MessageEnvelope<T>(
payload);
}
/**
* Returns a copy of this envelope bound to a tenant.
*
* @param tenant the tenant this message belongs to
* @return an envelope with identical identity and payload
*/
public MessageEnvelope<T> withTenant(TenantContext tenant) {
return new MessageEnvelope<>(
messageId,
messageType,
schemaVersion,
producedAt,
occurredAt,
producer,
correlationId,
causationId,
contentType,
partitionKey,
orderingKey,
Optional.of(Objects.requireNonNull(tenant, "tenant must not be null")),
traceContext,
headers,
payload);
}
/**
* Returns a copy of this envelope carrying replacement headers.
*
@@ -6,39 +6,16 @@ package dev.caskeleton.messaging.api;
* <p>Java class names are deliberately not usable as a message type: renaming or repackaging a
* class must never change the wire contract.
*
* @param value the catalog name, 1 to 240 characters
* @param value the catalog name, 1 to 240 UTF-8 bytes and free of control characters
*/
public record MessageType(String value) {
private static final int MAX_LENGTH = 240;
private static final int MAX_BYTES = 240;
public MessageType {
if (value == null || value.isBlank() || value.length() > MAX_LENGTH) {
throw new IllegalArgumentException("messageType must contain 1 to 240 characters");
}
requireWireSafe(value, "a message type", MAX_LENGTH);
}
/**
* Characters that must never reach a broker.
*
* <p>Length in Java {@code char}s bounded nothing useful: a 240-character string can be 960 UTF-8
* bytes, and a control character passes a length check untouched. CR and LF split records on
* line-oriented protocols, NUL truncates them in C string handling, and both survive right up to
* the broker that mishandles them.
*/
private static void requireWireSafe(String value, String what, int maxBytes) {
for (int index = 0; index < value.length(); index++) {
char character = value.charAt(index);
if (character < 0x20 || character == 0x7F) {
throw new IllegalArgumentException(
what
+ " must not contain control characters (found U+%04X)".formatted((int) character));
}
}
int bytes = value.getBytes(java.nio.charset.StandardCharsets.UTF_8).length;
if (bytes > maxBytes) {
throw new IllegalArgumentException(what + " exceeds " + maxBytes + " UTF-8 bytes: " + bytes);
if (value == null || value.isBlank()) {
throw new IllegalArgumentException("messageType must not be blank");
}
WireSafeText.require(value, "a message type", MAX_BYTES);
}
}
@@ -6,39 +6,16 @@ package dev.caskeleton.messaging.api;
* <p>This is a deployment-independent service name, not a host, pod, or connection identity, so
* that it stays a bounded value safe for metric tags.
*
* @param value the service name, 1 to 120 characters
* @param value the service name, 1 to 120 UTF-8 bytes and free of control characters
*/
public record ProducerId(String value) {
private static final int MAX_LENGTH = 120;
private static final int MAX_BYTES = 120;
public ProducerId {
if (value == null || value.isBlank() || value.length() > MAX_LENGTH) {
throw new IllegalArgumentException("producerId must contain 1 to 120 characters");
}
requireWireSafe(value, "a producer id", MAX_LENGTH);
}
/**
* Characters that must never reach a broker.
*
* <p>Length in Java {@code char}s bounded nothing useful: a 240-character string can be 960 UTF-8
* bytes, and a control character passes a length check untouched. CR and LF split records on
* line-oriented protocols, NUL truncates them in C string handling, and both survive right up to
* the broker that mishandles them.
*/
private static void requireWireSafe(String value, String what, int maxBytes) {
for (int index = 0; index < value.length(); index++) {
char character = value.charAt(index);
if (character < 0x20 || character == 0x7F) {
throw new IllegalArgumentException(
what
+ " must not contain control characters (found U+%04X)".formatted((int) character));
}
}
int bytes = value.getBytes(java.nio.charset.StandardCharsets.UTF_8).length;
if (bytes > maxBytes) {
throw new IllegalArgumentException(what + " exceeds " + maxBytes + " UTF-8 bytes: " + bytes);
if (value == null || value.isBlank()) {
throw new IllegalArgumentException("producerId must not be blank");
}
WireSafeText.require(value, "a producer id", MAX_BYTES);
}
}
@@ -1,7 +1,9 @@
package dev.caskeleton.messaging.api;
import java.nio.charset.StandardCharsets;
import java.util.Objects;
import java.util.Optional;
import java.util.regex.Pattern;
/**
* W3C trace propagation values carried with a message.
@@ -10,6 +12,13 @@ import java.util.Optional;
* envelope rather than only in headers means a trace survives an Outbox round trip through the
* database, where broker headers do not exist yet.
*
* <p>The three values used to be checked for non-nullness and nothing more, which made this record
* a general-purpose string carrier wearing the name of a standard. Anything accepted here is
* written to the {@code traceparent}, {@code tracestate} and {@code baggage} headers of every
* broker the message touches, so an unvalidated value is both a header-injection vector and a
* silent trace break: a collector that cannot parse {@code traceparent} drops the span rather than
* reporting a bad value, and the trace disappears at exactly the hop being investigated.
*
* @param traceparent the {@code traceparent} value when a trace is active
* @param tracestate the {@code tracestate} value when present
* @param baggage the {@code baggage} value when present
@@ -17,10 +26,112 @@ import java.util.Optional;
public record TraceContext(
Optional<String> traceparent, Optional<String> tracestate, Optional<String> baggage) {
/**
* {@code version-traceid-spanid-flags}, all lowercase hex, per the W3C Trace Context grammar.
*
* <p>Uppercase hex is refused rather than folded: the standard defines the field as lowercase,
* and a receiver comparing trace IDs as strings — which collectors do — would treat the two cases
* as two different traces.
*/
private static final Pattern TRACEPARENT =
Pattern.compile("[0-9a-f]{2}-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}");
private static final String ALL_ZERO_TRACE_ID = "0".repeat(32);
private static final String ALL_ZERO_SPAN_ID = "0".repeat(16);
/** {@code key=value} or {@code tenant@vendor=value}, per the standard's list-member grammar. */
private static final Pattern TRACESTATE_MEMBER =
Pattern.compile(
"[a-z0-9][_\\-*/a-z0-9]{0,255}(@[a-z0-9][_\\-*/a-z0-9]{0,13})?=[\\x20-\\x7E&&[^,=]]{0,255}");
/**
* The standard's bounds: at most 32 list members, and a field a receiver is allowed to truncate.
*/
private static final int MAX_TRACESTATE_MEMBERS = 32;
private static final int MAX_TRACESTATE_BYTES = 512;
/** W3C Baggage bounds: 8192 bytes total across at most 64 members. */
private static final int MAX_BAGGAGE_BYTES = 8192;
private static final int MAX_BAGGAGE_MEMBERS = 64;
public TraceContext {
Objects.requireNonNull(traceparent, "traceparent must not be null");
Objects.requireNonNull(tracestate, "tracestate must not be null");
Objects.requireNonNull(baggage, "baggage must not be null");
traceparent.ifPresent(TraceContext::requireValidTraceparent);
tracestate.ifPresent(TraceContext::requireValidTracestate);
baggage.ifPresent(TraceContext::requireValidBaggage);
if (tracestate.isPresent() && traceparent.isEmpty()) {
// A tracestate without a traceparent is vendor state belonging to no trace. Propagating it
// hands the next hop a key it will attribute to whatever trace that hop starts.
throw new IllegalArgumentException("tracestate must not be present without a traceparent");
}
}
private static void requireValidTraceparent(String value) {
if (!TRACEPARENT.matcher(value).matches()) {
throw new IllegalArgumentException(
"traceparent must be version-traceid-spanid-flags in lowercase hex: '" + value + '\'');
}
String version = value.substring(0, 2);
if ("ff".equals(version)) {
// The standard reserves ff and requires a receiver to reject it, rather than treat it as a
// future version to be forwarded.
throw new IllegalArgumentException("traceparent version ff is invalid");
}
String traceId = value.substring(3, 35);
if (ALL_ZERO_TRACE_ID.equals(traceId)) {
throw new IllegalArgumentException("traceparent carries an all-zero trace id");
}
String spanId = value.substring(36, 52);
if (ALL_ZERO_SPAN_ID.equals(spanId)) {
throw new IllegalArgumentException("traceparent carries an all-zero parent span id");
}
}
private static void requireValidTracestate(String value) {
int bytes = value.getBytes(StandardCharsets.UTF_8).length;
if (bytes > MAX_TRACESTATE_BYTES) {
throw new IllegalArgumentException("tracestate exceeds 512 bytes: " + bytes);
}
String[] members = value.split(",", -1);
if (members.length > MAX_TRACESTATE_MEMBERS) {
throw new IllegalArgumentException(
"tracestate carries more than 32 list members: " + members.length);
}
for (String member : members) {
String trimmed = member.strip();
if (trimmed.isEmpty()) {
// The grammar permits empty members for forward compatibility; nothing is propagated for
// them, so they are dropped by the receiver rather than being an error here.
continue;
}
if (!TRACESTATE_MEMBER.matcher(trimmed).matches()) {
throw new IllegalArgumentException("tracestate member is not valid: '" + trimmed + '\'');
}
}
}
private static void requireValidBaggage(String value) {
int bytes = value.getBytes(StandardCharsets.UTF_8).length;
if (bytes > MAX_BAGGAGE_BYTES) {
throw new IllegalArgumentException("baggage exceeds 8192 bytes: " + bytes);
}
WireSafeText.requireNoControls(value, "baggage");
String[] members = value.split(",", -1);
if (members.length > MAX_BAGGAGE_MEMBERS) {
throw new IllegalArgumentException("baggage carries more than 64 members: " + members.length);
}
for (String member : members) {
String trimmed = member.strip();
int equals = trimmed.indexOf('=');
if (equals <= 0 || equals == trimmed.length() - 1) {
throw new IllegalArgumentException("baggage member must be key=value: '" + trimmed + '\'');
}
}
}
/**
@@ -0,0 +1,65 @@
package dev.caskeleton.messaging.api;
import java.nio.charset.StandardCharsets;
/**
* The one place that decides which text may reach a broker.
*
* <p>Every wire-facing value used to bound itself in Java {@code char}s and check nothing else. A
* {@code char} count bounds nothing on a wire: a 240-character string is up to 960 UTF-8 bytes, so
* a "240 character" limit is a 960-byte limit against a broker that counts bytes. And a control
* character passes a length check untouched — CR and LF split records on line-oriented protocols,
* NUL truncates them in C string handling inside a broker, and DEL is stripped by some
* intermediaries and preserved by others. A value that survives one broker and corrupts the next is
* worse than a rejected one.
*
* <p>The rule is refused rather than sanitised on purpose. Silently stripping a CR turns a caller's
* two-line value into a one-line value that no longer means what they wrote, and the caller never
* learns; the broker downstream cannot tell the difference between that and a legitimate value.
*
* <p>Each copy of this check that lived in its own record was one more place for the rule to drift.
*/
public final class WireSafeText {
private WireSafeText() {}
/**
* Refuses text that no broker should be asked to carry.
*
* <p>Horizontal tab is refused along with the rest of the C0 range. It is legal in an HTTP field
* value, and that is exactly the problem: a header carried over a line-folding binding and the
* same header carried over a length-prefixed one disagree about whether a tab ends the value.
* Nothing in this platform needs a tab in an identifier or a header.
*
* @param value the text to check
* @param what a noun phrase naming the value, used in the failure message
* @param maxBytes the inclusive UTF-8 byte bound
* @throws IllegalArgumentException when the text carries a control character or exceeds the bound
*/
public static void require(String value, String what, int maxBytes) {
requireNoControls(value, what);
int bytes = value.getBytes(StandardCharsets.UTF_8).length;
if (bytes > maxBytes) {
throw new IllegalArgumentException(
what + " exceeds " + maxBytes + " UTF-8 bytes: " + bytes + " bytes");
}
}
/**
* Refuses control characters without applying a size bound.
*
* @param value the text to check
* @param what a noun phrase naming the value, used in the failure message
* @throws IllegalArgumentException when the text carries a control character
*/
public static void requireNoControls(String value, String what) {
for (int index = 0; index < value.length(); index++) {
char character = value.charAt(index);
if (character < 0x20 || character == 0x7F) {
throw new IllegalArgumentException(
"%s must not contain control characters (found U+%04X at index %d)"
.formatted(what, (int) character, index));
}
}
}
}
@@ -0,0 +1,79 @@
package dev.caskeleton.messaging.api.header;
import java.util.Locale;
import java.util.Set;
/**
* Splits the reserved namespace into the part an envelope field already owns and the part that only
* a header can carry.
*
* <p>{@link ReservedHeaders} answers one question — does the platform own this name — and every
* adapter that asked it treated the whole namespace as forgeable content. That is right for {@code
* msg.id} and wrong for {@code msg.retry-attempt}: the first restates a value the envelope already
* holds, so a header claiming it can only overwrite the canonical one, while the second has no
* envelope field at all and exists precisely to survive a hop through a broker. Refusing both is
* how a retry re-publish becomes an error, and dropping both on the way back is how an attempt
* counter silently restarts at one and a retry budget stops capping anything.
*
* <p>The split is derived from the envelope's own shape rather than listed by hand per adapter, so
* Kafka and RabbitMQ cannot disagree about which headers are identity and which are bookkeeping — a
* disagreement that would make the same message mean different things on two brokers.
*/
public final class CanonicalEnvelopeHeaders {
/**
* Reserved names that restate a value the envelope already carries in a field.
*
* <p>Every one of these is written by the adapter from an envelope field on the way out and read
* back into that field on the way in. A copy of it inside the header map is therefore never the
* source of truth, only a way to disagree with it.
*/
private static final Set<String> ENVELOPE_FIELDS =
Set.of(
ReservedHeaders.MESSAGE_ID,
ReservedHeaders.MESSAGE_TYPE,
ReservedHeaders.SCHEMA_VERSION,
ReservedHeaders.PRODUCER,
ReservedHeaders.PRODUCED_AT,
ReservedHeaders.OCCURRED_AT,
ReservedHeaders.CORRELATION_ID,
ReservedHeaders.CAUSATION_ID,
ReservedHeaders.CONTENT_TYPE,
ReservedHeaders.PARTITION_KEY,
ReservedHeaders.ORDERING_KEY,
ReservedHeaders.TENANT,
ReservedHeaders.TRACEPARENT,
ReservedHeaders.TRACESTATE,
ReservedHeaders.BAGGAGE);
private CanonicalEnvelopeHeaders() {}
/**
* Reports whether a header name restates an envelope field.
*
* @param name the header name in any case
* @return true when the envelope already carries this value in a field of its own
*/
public static boolean restatesEnvelopeField(String name) {
return name != null && ENVELOPE_FIELDS.contains(name.toLowerCase(Locale.ROOT));
}
/**
* Reports whether a header name is platform bookkeeping that must travel in the header map.
*
* @param name the header name in any case
* @return true for a reserved name with no envelope field behind it
*/
public static boolean isPlatformBookkeeping(String name) {
return ReservedHeaders.isReserved(name) && !restatesEnvelopeField(name);
}
/**
* Returns the reserved names an envelope field owns.
*
* @return an immutable set of lowercase names
*/
public static Set<String> envelopeFieldNames() {
return ENVELOPE_FIELDS;
}
}
@@ -1,11 +1,17 @@
package dev.caskeleton.messaging.api.header;
import java.nio.charset.StandardCharsets;
import dev.caskeleton.messaging.api.WireSafeText;
/**
* Value of a single message header.
*
* @param value the header value, at most 4096 UTF-8 bytes
* <p>The bound used to be the only rule, so a value containing CR, LF or NUL reached the broker
* intact. On a line-oriented binding a CRLF inside a value ends the header and starts a new one the
* caller wrote — the same header-injection primitive as in HTTP, with the broker's own control
* headers as the target. A NUL truncates the value inside a broker that hands it to C string
* handling, so a subscriber receives a prefix of what was published and cannot tell.
*
* @param value the header value, at most 4096 UTF-8 bytes and free of control characters
*/
public record HeaderValue(String value) {
@@ -15,9 +21,6 @@ public record HeaderValue(String value) {
if (value == null) {
throw new IllegalArgumentException("header value must not be null");
}
int bytes = value.getBytes(StandardCharsets.UTF_8).length;
if (bytes > MAX_BYTES) {
throw new IllegalArgumentException("header value exceeds 4096 bytes: " + bytes);
}
WireSafeText.require(value, "a header value", MAX_BYTES);
}
}
@@ -34,6 +34,31 @@ public final class MessageHeaders {
"password",
"client_secret");
/**
* Words that make a header name a credential regardless of what surrounds them.
*
* <p>Exact-name matching only refuses the spellings someone thought of. {@code x-api-key}, {@code
* auth-token} and {@code db_password} are the same credential leak as {@code authorization} and
* none of them was on the list. Matching whole segments rather than substrings is what keeps
* {@code tokenizer-version} or {@code secretariat-id} from being refused for containing the
* letters of a secret.
*/
private static final Set<String> SECRET_SEGMENTS =
Set.of(
"password",
"passwd",
"secret",
"token",
"credential",
"credentials",
"apikey",
"authorization",
"cookie",
"signature");
private static final java.util.regex.Pattern SEGMENT_SEPARATOR =
java.util.regex.Pattern.compile("[._\\-]+");
private static final MessageHeaders EMPTY = new MessageHeaders(Map.of());
private final Map<HeaderName, HeaderValue> values;
@@ -96,7 +121,9 @@ public final class MessageHeaders {
if (!reservedAllowed && ReservedHeaders.isReserved(normalized)) {
throw new IllegalArgumentException("message header is not allowed: " + normalized);
}
if (SECRET_NAMES.contains(normalized)) {
if (carriesACredential(normalized)) {
// The name is reported and the value never is: an error message is written to a log that
// is exactly as readable as the broker storage this check exists to keep the value out of.
throw new IllegalArgumentException("message header is not allowed: " + normalized);
}
if (!seen.add(normalized)) {
@@ -112,6 +139,26 @@ public final class MessageHeaders {
return new MessageHeaders(Collections.unmodifiableMap(copy));
}
private static boolean carriesACredential(String normalized) {
if (SECRET_NAMES.contains(normalized)) {
return true;
}
String[] segments = SEGMENT_SEPARATOR.split(normalized, -1);
for (int index = 0; index < segments.length; index++) {
if (SECRET_SEGMENTS.contains(segments[index])) {
return true;
}
// Adjacent segments are also tested joined, because the same word is written both ways:
// `api_key` is one segment to a reader and two to a splitter, and `x-api-key` is two of
// three. Joining only neighbouring pairs is what keeps `routing-key` accepted.
if (index + 1 < segments.length
&& SECRET_SEGMENTS.contains(segments[index] + segments[index + 1])) {
return true;
}
}
return false;
}
/**
* Returns the headers as an immutable map.
*
@@ -45,6 +45,16 @@ public final class ReservedHeaders {
/** Ordering key. */
public static final String ORDERING_KEY = "msg.ordering-key";
/**
* Bounded tenant identity.
*
* <p>The envelope carried a tenant and no header name existed for it, so the write side had
* nothing to write and the read side rebuilt every consumed message with an empty tenant. A
* message published by one tenant and consumed as belonging to none is not a lost label: it is
* the field every downstream authorization and data-partitioning decision reads.
*/
public static final String TENANT = "msg.tenant";
/** Identity of the redrive operation that replayed this message. */
public static final String REDRIVE_ID = "msg.redrive-id";
@@ -91,6 +101,7 @@ public final class ReservedHeaders {
CONTENT_TYPE,
PARTITION_KEY,
ORDERING_KEY,
TENANT,
REDRIVE_ID,
REDRIVE_COUNT,
RETRY_ATTEMPT,
@@ -105,6 +116,16 @@ public final class ReservedHeaders {
private ReservedHeaders() {}
/**
* The namespace the platform owns, whether or not a name in it exists yet.
*
* <p>The check used to be exact membership of {@link #NAMES}, so {@code msg.anything} that this
* release has not defined was an ordinary application header — until a later release defined it,
* at which point every application already writing it silently started overwriting envelope
* metadata. Owning the prefix means a new platform header is a compatible change.
*/
private static final String PLATFORM_PREFIX = "msg.";
/**
* Reports whether a header name belongs to the platform.
*
@@ -112,7 +133,11 @@ public final class ReservedHeaders {
* @return true when the platform owns the name
*/
public static boolean isReserved(String name) {
return name != null && NAMES.contains(name.toLowerCase(Locale.ROOT));
if (name == null) {
return false;
}
String normalized = name.toLowerCase(Locale.ROOT);
return NAMES.contains(normalized) || normalized.startsWith(PLATFORM_PREFIX);
}
/**
@@ -2,27 +2,25 @@ package dev.caskeleton.messaging.api.publish;
import dev.caskeleton.messaging.api.destination.ConfirmationRequirement;
import java.time.Duration;
import java.util.Map;
import java.util.Objects;
import java.util.Optional;
/**
* Per-call publish options.
*
* <p>{@code brokerHints} must be empty for M1 callers. Only an M3 native capability may populate
* it, because a hint map on the general API becomes an escape hatch that quietly bypasses
* destination policy.
* <p>There is no free-form hint map. One existed for a native surface that does not read it, so the
* only thing a caller could do with it was pass adapter settings that the publish path refused at
* runtime — an escape hatch around destination policy that never opened. A broker-specific option
* belongs in that broker's own typed API, where the adapter that honours it can be seen to.
*
* @param timeout the publish operation deadline
* @param confirmation the confirmation this call requires
* @param deduplication optional broker-side duplicate suppression
* @param brokerHints M3-only adapter hints
*/
public record PublishOptions(
Duration timeout,
ConfirmationRequirement confirmation,
Optional<PublishDeduplication> deduplication,
Map<String, String> brokerHints) {
Optional<PublishDeduplication> deduplication) {
private static final Duration DEFAULT_TIMEOUT = Duration.ofSeconds(5);
@@ -30,32 +28,18 @@ public record PublishOptions(
Objects.requireNonNull(timeout, "timeout must not be null");
Objects.requireNonNull(confirmation, "confirmation must not be null");
Objects.requireNonNull(deduplication, "deduplication must not be null");
Objects.requireNonNull(brokerHints, "brokerHints must not be null");
if (timeout.isNegative() || timeout.isZero()) {
throw new IllegalArgumentException("publish timeout must be positive");
}
brokerHints = Map.copyOf(brokerHints);
}
/**
* Returns the M1 default: five second timeout, replication evidence, no hints.
* Returns the M1 default: five second timeout, replication evidence.
*
* @return the default options
*/
public static PublishOptions defaults() {
return new PublishOptions(
DEFAULT_TIMEOUT,
ConfirmationRequirement.REPLICATION_OR_PERSISTENCE_ACK,
Optional.empty(),
Map.of());
}
/**
* Reports whether these options stay inside the M1 surface.
*
* @return true when no broker hints are present
*/
public boolean isM1Compatible() {
return brokerHints.isEmpty();
DEFAULT_TIMEOUT, ConfirmationRequirement.REPLICATION_OR_PERSISTENCE_ACK, Optional.empty());
}
}
@@ -8,10 +8,16 @@ import java.util.Optional;
/**
* The outcome of one publish call, with the evidence that justifies it.
*
* <p>The constructor refuses combinations that would let a caller read a stronger guarantee than
* was actually obtained. An adapter that cannot decide must report {@link
* PublishCompletion#AMBIGUOUS} with no confirmation level, which is the conservative answer, rather
* than picking a completion that happens to make the call site simpler.
* <p>The constructor refuses every combination that would let a caller read a stronger guarantee
* than was actually obtained, and every one that contradicts itself: a rejection the broker
* acknowledged, a confirmation that does not know whether it routed, an ambiguous outcome the
* broker routed, a broker coordinate for bytes that never left. An adapter that cannot decide must
* report {@link PublishCompletion#AMBIGUOUS} with no confirmation level, which is the conservative
* answer, rather than picking a completion that happens to make the call site simpler.
*
* <p>Validating here rather than trusting call sites is deliberate: the record is public, every
* adapter builds one, and a contradiction assembled in an adapter is only ever read much later, by
* an operator deciding whether to re-publish.
*
* @param completion how the attempt ended
* @param evidence the observable facts behind that outcome
@@ -72,6 +78,26 @@ public record PublishResult(
if (completion == PublishCompletion.CONFIRMED && failure.isPresent()) {
throw new IllegalArgumentException("confirmed publish must not carry a failure descriptor");
}
if (completion == PublishCompletion.REJECTED && evidence.brokerAccepted()) {
// A broker that acknowledged the message did not reject it. Left representable, this is the
// combination that turns a delivered message into one the caller re-publishes as if it had
// never been sent.
throw new IllegalArgumentException("rejected publish cannot claim broker acceptance");
}
if (completion == PublishCompletion.CONFIRMED && routingOutcome == RoutingOutcome.UNKNOWN) {
// The confirmation came from the broker, and the same response says whether it routed. A
// confirmed publish that does not know is an adapter reporting half of what it was told.
throw new IllegalArgumentException("confirmed publish knows whether it routed");
}
if (completion == PublishCompletion.AMBIGUOUS && routingOutcome == RoutingOutcome.ROUTED) {
// Routing is something only the broker can report, and a broker that reported it answered.
throw new IllegalArgumentException("a routed publish is not ambiguous");
}
if (position.isPresent() && evidence.transmission() == TransmissionEvidence.NOT_TRANSMITTED) {
// A partition and offset for a message that never left the process: whatever coordinate this
// is, it belongs to some other message, and an operator would chase it.
throw new IllegalArgumentException("an untransmitted publish has no broker position");
}
}
/**
@@ -0,0 +1,208 @@
package dev.caskeleton.messaging.api;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatCode;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import dev.caskeleton.messaging.api.header.HeaderName;
import dev.caskeleton.messaging.api.header.HeaderValue;
import dev.caskeleton.messaging.api.header.MessageHeaders;
import dev.caskeleton.messaging.api.header.ReservedHeaders;
import java.util.Map;
import java.util.Optional;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.ValueSource;
/**
* The rest of the wire boundary: values, correlation, trace propagation and the two denylists.
*
* <p>{@link WireSafeValueObjectTest} covers the name side. This covers what was still unbounded
* after it: a header <em>value</em> carrying CRLF straight to the broker, a correlation id bounded
* in Java characters rather than bytes, a {@code traceparent} that was any string at all, and two
* denylists that matched exact spellings only.
*/
class WireBoundaryRejectionTest {
/** The C0 and DEL code points a broker disagrees with itself about. */
@ParameterizedTest
@ValueSource(ints = {0x00, 0x09, 0x0A, 0x0D, 0x1B, 0x7F})
@DisplayName("a header value carrying a control character is refused")
void aHeaderValueWithAControlCharacterIsRefused(int codePoint) {
// NUL truncates the value inside a broker that hands it to C string handling; LF and CR end
// the header on a line-oriented binding and start one the caller wrote; ESC and DEL are
// stripped by some intermediaries and preserved by others. Tab is refused with them because a
// line-folding binding and a length-prefixed one disagree about whether it ends the value.
String value = "order-" + (char) codePoint + "-created";
assertThatThrownBy(() -> new HeaderValue(value))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("control characters");
}
@Test
@DisplayName("an ordinary header value, including non-ASCII text, is still accepted")
void anOrdinaryHeaderValueIsAccepted() {
assertThatCode(() -> new HeaderValue("주문 생성됨 / order created")).doesNotThrowAnyException();
}
@Test
@DisplayName("a header value is bounded in bytes, not in characters")
void aHeaderValueIsBoundedInBytes() {
// 4096 characters of three bytes each: inside any character bound, three times the byte one.
assertThatThrownBy(() -> new HeaderValue("가".repeat(4096)))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("UTF-8 bytes");
}
@Test
@DisplayName("a correlation id is bounded in bytes and refuses control characters")
void aCorrelationIdIsBoundedInBytes() {
assertThatThrownBy(() -> new CorrelationId("가".repeat(160)))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("UTF-8 bytes");
assertThatThrownBy(() -> new CorrelationId("flow-1\r\nmsg.id: forged"))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("control characters");
assertThatCode(() -> new CorrelationId("flow-0198e2b1")).doesNotThrowAnyException();
}
@ParameterizedTest
@ValueSource(
strings = {
"not-a-traceparent",
"00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331",
"00-0AF7651916CD43DD8448EB211C80319C-b7ad6b7169203331-01",
"ff-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
"00-00000000000000000000000000000000-b7ad6b7169203331-01",
"00-0af7651916cd43dd8448eb211c80319c-0000000000000000-01",
"00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01\r\nx: y"
})
@DisplayName("an invalid traceparent is refused rather than propagated")
void anInvalidTraceparentIsRefused(String traceparent) {
// In order: not the grammar at all; no flags field; uppercase hex, which a collector comparing
// trace ids as strings reads as a different trace; the reserved ff version; an all-zero trace
// id and an all-zero parent span id, both of which the standard declares invalid; and a value
// with a CRLF, which is a header injection once it is written to the traceparent header.
assertThatThrownBy(() -> TraceContext.of(traceparent))
.isInstanceOf(IllegalArgumentException.class);
}
@Test
@DisplayName("the W3C example traceparent is accepted")
void theStandardExampleIsAccepted() {
assertThatCode(() -> TraceContext.of("00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01"))
.doesNotThrowAnyException();
}
@Test
@DisplayName("tracestate is bounded by the standard's member count and size")
void tracestateIsBounded() {
String parent = "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01";
assertThatCode(
() ->
new TraceContext(
Optional.of(parent),
Optional.of("congo=t61rcWkgMzE,rojo=00f067aa0ba902b7"),
Optional.empty()))
.doesNotThrowAnyException();
String tooManyMembers =
java.util.stream.IntStream.range(0, 33)
.mapToObj(index -> "k" + index + "=v")
.collect(java.util.stream.Collectors.joining(","));
assertThatThrownBy(
() ->
new TraceContext(
Optional.of(parent), Optional.of(tooManyMembers), Optional.empty()))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("32 list members");
assertThatThrownBy(
() ->
new TraceContext(
Optional.of(parent), Optional.of("congo=a\r\nx=y"), Optional.empty()))
.isInstanceOf(IllegalArgumentException.class);
}
@Test
@DisplayName("tracestate without a traceparent is vendor state belonging to no trace")
void tracestateWithoutATraceparentIsRefused() {
assertThatThrownBy(
() ->
new TraceContext(
Optional.empty(), Optional.of("congo=t61rcWkgMzE"), Optional.empty()))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("without a traceparent");
}
@Test
@DisplayName("baggage is bounded in total bytes and in member count")
void baggageIsBounded() {
assertThatCode(
() ->
new TraceContext(
Optional.empty(), Optional.empty(), Optional.of("tenant=acme,region=eu")))
.doesNotThrowAnyException();
String oversize = "k=" + "v".repeat(8200);
assertThatThrownBy(
() -> new TraceContext(Optional.empty(), Optional.empty(), Optional.of(oversize)))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("8192 bytes");
String tooManyMembers =
java.util.stream.IntStream.range(0, 65)
.mapToObj(index -> "k" + index + "=v")
.collect(java.util.stream.Collectors.joining(","));
assertThatThrownBy(
() -> new TraceContext(Optional.empty(), Optional.empty(), Optional.of(tooManyMembers)))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("64 members");
}
@ParameterizedTest
@ValueSource(strings = {"x-api-key", "auth-token", "db_password", "request.signature", "Cookie"})
@DisplayName("a credential-shaped header name is refused however it is spelled")
void aCredentialShapedNameIsRefused(String name) {
assertThatThrownBy(
() ->
MessageHeaders.application(Map.of(new HeaderName(name), new HeaderValue("opaque"))))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("not allowed");
}
@Test
@DisplayName("a name that merely contains the letters of a secret is still accepted")
void aNameThatMerelyContainsTheLettersIsAccepted() {
assertThatCode(
() ->
MessageHeaders.application(
Map.of(
new HeaderName("tokenizer-version"), new HeaderValue("3"),
new HeaderName("secretariat-id"), new HeaderValue("s-9"))))
.as("segment matching, not substring matching")
.doesNotThrowAnyException();
}
@Test
@DisplayName("the platform namespace is reserved whether or not the name exists yet")
void thePlatformNamespaceIsReserved() {
assertThat(ReservedHeaders.isReserved("msg.not-defined-in-this-release")).isTrue();
assertThatThrownBy(
() ->
MessageHeaders.application(
Map.of(new HeaderName("msg.not-defined-yet"), new HeaderValue("mine"))))
.isInstanceOf(IllegalArgumentException.class)
.hasMessageContaining("not allowed");
// The platform factory still writes its own namespace; that is the whole distinction.
assertThatCode(
() ->
MessageHeaders.platform(
Map.of(new HeaderName(ReservedHeaders.MESSAGE_ID), new HeaderValue("m-1"))))
.doesNotThrowAnyException();
}
}
@@ -11,9 +11,90 @@ import org.junit.jupiter.api.Test;
class PublishResultTest {
/** A coordinate no adapter would have produced for a message that never left. */
private static final BrokerPosition POSITION =
new BrokerPosition() {
@Override
public String broker() {
return "kafka";
}
@Override
public java.util.Map<String, String> diagnosticAttributes() {
return java.util.Map.of("topic", "order-events", "partition", "0", "offset", "17");
}
};
private static final FailureDescriptor AMBIGUOUS_FAILURE =
FailureDescriptor.of(FailureCategory.AMBIGUOUS, "CONFIRM_TIMEOUT", "confirm timed out");
@Test
void aRejectionCannotClaimTheBrokerAcceptedIt() {
PublishEvidence accepted =
PublishEvidence.confirmed(ConfirmationLevel.REPLICATION_OR_PERSISTENCE_ACK);
assertThatThrownBy(
() ->
new PublishResult(
PublishCompletion.REJECTED,
accepted,
RoutingOutcome.ROUTED,
Optional.empty(),
1,
Duration.ofMillis(10),
Optional.of(AMBIGUOUS_FAILURE)))
.as("re-publishing a message the broker acknowledged is how one order becomes two")
.isInstanceOf(IllegalArgumentException.class);
}
@Test
void aConfirmationCannotBeUnsureWhetherItRouted() {
assertThatThrownBy(
() ->
new PublishResult(
PublishCompletion.CONFIRMED,
PublishEvidence.confirmed(ConfirmationLevel.BROKER_ACK),
RoutingOutcome.UNKNOWN,
Optional.empty(),
1,
Duration.ofMillis(10),
Optional.empty()))
.as("the response that confirmed the publish is the one that says whether it routed")
.isInstanceOf(IllegalArgumentException.class);
}
@Test
void aRoutedPublishIsNotAmbiguous() {
assertThatThrownBy(
() ->
new PublishResult(
PublishCompletion.AMBIGUOUS,
PublishEvidence.ambiguous(),
RoutingOutcome.ROUTED,
Optional.empty(),
1,
Duration.ofMillis(10),
Optional.of(AMBIGUOUS_FAILURE)))
.as("only the broker can report routing, and a broker that reported it answered")
.isInstanceOf(IllegalArgumentException.class);
}
@Test
void anUntransmittedPublishHasNoBrokerPosition() {
assertThatThrownBy(
() ->
new PublishResult(
PublishCompletion.REJECTED,
PublishEvidence.notTransmitted(),
RoutingOutcome.NOT_APPLICABLE,
Optional.of(POSITION),
1,
Duration.ofMillis(10),
Optional.of(AMBIGUOUS_FAILURE)))
.as("a coordinate for bytes that never left belongs to some other message")
.isInstanceOf(IllegalArgumentException.class);
}
@Test
void confirmedResultRequiresBrokerAcceptance() {
PublishEvidence evidence =
@@ -158,9 +239,4 @@ class PublishResultTest {
Optional.empty()))
.isInstanceOf(IllegalArgumentException.class);
}
@Test
void m1OptionsCarryNoBrokerHints() {
assertThat(PublishOptions.defaults().isM1Compatible()).isTrue();
}
}