Review message-schema evolution

Review exercise · TypeScript

Review brief

Nightmare60 min

An at-least-once message pipeline is evolving OrderPaid from a cents-only v1 payload to a structured v2 amount. Old consumers remain during rollout, payload extensions must survive forwarding, and processing can fail transiently or encounter a future schema.

Behavioral contract

Envelope messageId equals the immutable payment event id on every retry. Producers emit v1 until capabilities.allConsumersSupportV2 is true, then may emit v2.
v1 totalCents is an integer USD minor-unit amount. Upcast it to v2 amount { currency: USD, minorUnits: totalCents } without division or rounding.
v2 consumers accept both versions. Preserve unrecognized payload fields under extensions when upcasting or forwarding so another consumer can use them.
Acknowledge only after successful business processing. Transient processing failures nack for retry without quarantine.
An unknown future schema is retried up to five deliveries, then its exact raw envelope is quarantined before acknowledgement; quarantine failure leaves it unacknowledged.

Review instructions

1Trace mixed-version rollout, redelivery, v1 upcast, transient failure, and an unknown future envelope.
2Anchor each finding to the narrowest useful changed line and explain the compatibility or data impact.
3Recommend a direction rather than writing replacement code.
4Prioritize no more than six findings.

Learning objectives

• Coordinate producer rollout with consumer capabilities
• Upcast monetary data without changing its unit
• Preserve raw messages and retryability through processing

src/order-paid-types.tsTypeScript

@@ -0,0 +1,43 @@

1+export interface PaymentEvent {

2+ eventId: string;

3+ orderId: string;

4+ totalCents: number;

5+ note?: string;

6+}

7+

8+export interface ConsumerCapabilities {

9+ allConsumersSupportV2(): Promise<boolean>;

10+}

11+

12+export interface MessageIds {

13+ next(): string;

14+}

15+

16+export interface MessagePublisher {

17+ publish(rawEnvelope: string): Promise<void>;

18+}

19+

20+export interface QueuedEnvelope {

21+ raw: string;

22+ deliveryCount: number;

23+}

24+

25+export interface MessageQueue {

26+ ack(message: QueuedEnvelope): Promise<void>;

27+ nack(message: QueuedEnvelope): Promise<void>;

28+}

29+

30+export interface Quarantine {

31+ save(input: { messageId: string; rawEnvelope: string }): Promise<void>;

32+}

33+

34+export interface OrderPaidV2 {

35+ orderId: string;

36+ amount: { currency: "USD"; minorUnits: number };

37+ note?: string;

38+ extensions: Readonly<Record<string, unknown>>;

39+}

40+

41+export interface OrderPaidProcessor {

42+ process(messageId: string, payload: OrderPaidV2): Promise<void>;

43+}

Reference solution

The findings below are ordered by priority.

Findings

1. The producer emits v2 before the fleet capability allows it

Location: src/order-paid-producer.ts:13-28

Every event uses schemaVersion 2 and the capability dependency is ignored. During rolling deployment, remaining v1-only consumers receive a payload they cannot decode and can lose or poison payment processing.

Await the capability and emit the documented v1 shape until all consumers support v2.

2. Redelivery receives a new message identity

Location: src/order-paid-producer.ts:14-16

ids.next() creates a different message id on every publish attempt. Downstream idempotency keyed by message id cannot recognize a retry and may apply the same payment event repeatedly.

Use the immutable event.eventId as messageId on every attempt.

3. The v1 upcaster divides a cents value by 100

Location: src/order-paid-consumer.ts:17-30

totalCents already contains minor units, but the upcaster divides and rounds it. A value of 1,099 cents becomes 11 cents rather than preserving 1,099, silently corrupting monetary data.

Validate the integer and copy it directly to amount.minorUnits with USD currency.

4. Decoding strips extension data from both versions

Location: src/order-paid-consumer.ts:17-30 and src/order-paid-consumer.ts:36-45

Both branches construct extensions: {} and discard every unrecognized payload field. Forward-compatible producers or other consumers can no longer recover their data after this service upcasts and forwards the event.

Separate recognized fields and preserve the remaining raw payload properties under extensions.

5. Messages are acknowledged before decoding or processing

Location: src/order-paid-consumer.ts:48-57

The queue removes the delivery before JSON parsing and business processing. A crash, transient processor error, or quarantine failure cannot trigger redelivery, so at-least-once delivery degrades to at-most-once loss.

Acknowledge only after successful processing or after the specified durable terminal quarantine.

6. Every error is immediately and incorrectly quarantined

Location: src/order-paid-consumer.ts:55-61

Transient processor failures and first encounters with a future schema take the same catch path. It ignores deliveryCount, stores the error string rather than the exact raw envelope, and invents message id unknown. A quarantine failure does reject, but only after the premature acknowledgement has already made redelivery impossible.

Nack transient failures; for an unsupported future version, retry through five deliveries, then store its exact raw envelope and real parsed message id before acknowledging.

Reasonable non-findings

JSON is a permissible envelope encoding for this exercise.
A v2 producer using integer minor units and explicit USD is correct once rollout gating and identity are fixed.
A v2 consumer accepting v1 through a pure upcaster is the intended rolling-compatibility design.
Business processing may use stable message id for its own idempotency.