Package org.keycloak.events.outbox

Interface OutboxDeliveryHandler

public interface OutboxDeliveryHandler
Per-kind plug-in that knows how to actually deliver an OutboxEntryEntity's payload to its destination. The drainer is generic — for each due row it calls deliver(KeycloakSession, OutboxEntryEntity) and transitions the row based on the returned OutboxDeliveryResult.

One handler per registered entryKind; the drainer locates a handler by the row's entryKind value. Implementations are free to interpret the payload and metadata columns however they like — the store treats both as opaque text.

Synchronous by design — the handler returns when delivery has either succeeded, failed retryably, or failed terminally. Long-poll or fire-and-forget delivery semantics should be modelled by returning OutboxDeliveryResult.delivered() as soon as the payload has been handed off (e.g. enqueued in an external broker).

  • Method Details

    • entryKind

      String entryKind()
      The entryKind this handler is responsible for. Must match the entry_kind column of every row this handler will be invoked for; the drainer uses this to map locked rows back to a handler.

    • deliver

      OutboxDeliveryResult deliver(KeycloakSession session, OutboxEntryEntity row)
      Attempts delivery for one outbox row. The drainer holds a pessimistic write lock on the row for the duration of the call; implementations should keep the call bounded (no indefinite blocking) and avoid touching unrelated database rows so the lock window stays tight.

      Implementations may throw RuntimeException; the drainer treats an uncaught exception as OutboxDeliveryOutcome.RETRY and records the exception class + message in last_error.

      The returned OutboxDeliveryResult's errorMessage (if any) is persisted into the row's last_error column. Handlers should pack as much diagnostic detail (HTTP status, response body excerpt, exception class) into that single string as fits the column (VARCHAR(2048)).