shared-infrastructure/com.vertyll.veds.sharedinfrastructure.kafka.contract/OutboxMessage

OutboxMessage

Persistence-agnostic contract for a Kafka outbox message.

The contract is immutable from the caller's perspective: all properties are val and every state transition is expressed as a domain method that returns the new message instance (e.g. markProcessing, markCompleted, markRetryScheduled, markDeadLettered). Concrete adapters decide whether to mutate the underlying row in place (JPA dirty-tracking with var private-set fields) or return a freshly copied document (MongoDB, Cassandra). The outbox processor never observes the difference — it always works with the returned reference.

Inheritors

BaseOutbox

Properties

createdAt

abstract val createdAt: Instant

Instant the row was first written by the producing transaction.

errorMessage

abstract val errorMessage: String?

Latest publishing error message, or null if the message has never failed.

eventId

abstract val eventId: String

Stable business identifier propagated as the eventId Kafka header (idempotency key on the consumer side).

abstract val id: Long?

Storage-assigned surrogate id; null until the row is first persisted.

key

abstract val key: String

Kafka record key used for partitioning (typically the aggregate id or saga id).

lastRetryAt

abstract val lastRetryAt: Instant?

Instant of the most recent retry; used together with veds.outbox.retry-cooldown to throttle redelivery.

payload

abstract val payload: ByteArray

Serialized record value; encoding (Avro, JSON, …) is the caller's responsibility.

processedAt

abstract val processedAt: Instant?

Instant of the most recent dispatch attempt (success or failure).

retryCount

abstract val retryCount: Int

Number of publishing attempts already made. Compared against veds.outbox.max-retries.

sagaId

abstract val sagaId: String?

Optional saga correlation id (Saga.id) so saga-related outbox rows can be located quickly.

status

abstract val status: OutboxStatus

Current lifecycle OutboxStatus. See the enum's KDoc for the state machine.

topic

abstract val topic: String

Target Kafka topic name.

version

abstract val version: Long?

JPA optimistic-locking version, or null for storage backends that do not provide one.

Functions

markCompleted

abstract fun markCompleted(): OutboxMessage

Marks the message as successfully published to the broker. Sets status to OutboxStatus.COMPLETED and stamps processedAt with the current instant.

markDeadLettered

abstract fun markDeadLettered(error: String): OutboxMessage

Transitions the message to OutboxStatus.DEAD_LETTERED. Terminal — the message will never be retried automatically.

markProcessing

abstract fun markProcessing(): OutboxMessage

Marks the message as being currently processed. Sets status to OutboxStatus.PROCESSING and stamps processedAt with the current instant.

markRetryScheduled

abstract fun markRetryScheduled(error: String): OutboxMessage

Reverts the message to OutboxStatus.PENDING after a failed publishing attempt, incrementing retryCount and stamping lastRetryAt. The message will be picked up again by the next poller cycle after the configured retry cooldown elapses.