Platform kit

The problem it removes

An event published after the commit is lost on the next crash.

What it does

Decisions and trade-offs

1. 01

   We chose

   A transactional outbox: EventPublisher.publish writes a row of your outbox in your transaction; a relay claims rows with FOR UPDATE SKIP LOCKED and publishes them, with a messageId chosen at write time.

   We refused

   Publishing to the broker from the service method, and a distributed transaction (XA) across database and broker.

   Because

   The event commits or rolls back with the change. A relay that crashes republishes the same messageId, and the consumer's dedup makes it a no-op.

   What it costs you

   An outbox table per context (you implement OutboxStore over your schema) and a polling delay between commit and publish.

2. 02

   We chose

   The envelope in AMQP headers (kz-type, kz-version, kz-producer, kz-correlation-id, kz-occurred-at), the body the bare event, and a JSON Schema per event in the producer's -api module.

   We refused

   A shared jar of event DTOs, and a JSON wrapper around every body.

   Because

   A shared DTO jar ties every service's release to every other's. A schema checked by tests on both sides (EventContractTest) gives the contract without the coupling, and the body stays readable by any language.

   What it costs you

   Each consumer keeps its own tolerant copy of the event and one contract test.

3. 03

   We chose

   Quorum queues declared in one line (KrizakaQueues.consumer), a stateless retry with back-off — 5 attempts from 500 ms — then the queue’s .dlq twin with the original headers and the exception.

   We refused

   Spring's default requeue on failure.

   Because

   A requeued poison message loops forever; in the DLQ it is visible, with the reason, and can be replayed by hand.

   What it costs you

   A queue already declared as classic must be drained and redeclared once.

4. 04

   We chose

   RFC 9457 Problem Details for every error: a DomainException becomes its 4xx with a stable code and the requestId; bean validation a 422 with errors[]; anything unexpected a 500 that never carries its message.

   We refused

   Free-form error bodies per service, and stack traces or exception messages in 500 responses.

   Because

   A client handles one shape, and the requestId in the response is the one in the log line — a support ticket points at the failure.

   What it costs you

   Your exceptions extend DomainException (NotFoundException, ConflictException…) to choose their status.

5. 05

   We chose

   Starters that are POMs only, over modules usable alone; defaults applied at the lowest priority.

   We refused

   Renaming the modules into starters, and defaults that override application.yml.

   Because

   A product declares capabilities, not the Spring list behind them; a Spring Boot upgrade changes the starters, not your POM — and your application.yml always wins.

   What it costs you

   Java 21 and Spring Boot 4.0 only.

In code

@Transactional
public User register(NewUser input) {
  User user = users.save(input);
  // A row of YOUR outbox, in THIS transaction: no event for a rollback, no lost event on a crash.
  events.publish("evt.user.registered", 1, new UserRegistered(user.id(), user.email()));
  return user;
}

@Bean // the quorum queue, its <queue>.dlq, the bindings
Declarables userEvents(MessagingExchanges exchanges) {
  return KrizakaQueues.consumer(exchanges, "krizaka.notifications.user-events", "evt.user.registered");
}

@RabbitListener(queues = "krizaka.notifications.user-events") // 5 retries with back-off, then the DLQ
void onRegistered(UserRegistered event, @Header(AmqpHeaders.MESSAGE_ID) String messageId) {
  if (!dedup.claim("notifications.user-events", messageId)) return; // a redelivery: already done
  try { welcome(event); }
  catch (RuntimeException e) { dedup.release("notifications.user-events", messageId); throw e; }
}

Adopt it

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.krizaka</groupId>
      <artifactId>krizaka-bom</artifactId>
      <version>0.2.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency><groupId>com.krizaka</groupId><artifactId>krizaka-spring-boot-starter-web</artifactId></dependency>
  <dependency><groupId>com.krizaka</groupId><artifactId>krizaka-spring-boot-starter-security</artifactId></dependency>
  <dependency><groupId>com.krizaka</groupId><artifactId>krizaka-spring-boot-starter-rabbitmq</artifactId></dependency>
  <dependency><groupId>com.krizaka</groupId><artifactId>krizaka-spring-boot-starter-observability</artifactId></dependency>
</dependencies>