Interface DurableQueue

All Superinterfaces:
AutoCloseable
public interface DurableQueue extends AutoCloseable
Local durable queue contract for Phase 6.3 messaging primitives.

Implementations are expected to be thread-safe and may block on local durable-log append, fsync, recovery, and visibility-timeout maintenance. The contract provides local durable enqueue, lease, acknowledge, negative acknowledge, and redacted status operations. It also defines the queue side of the durable outbox/inbox pattern used by higher-level services.

This API does not define a broker protocol, cluster membership, consensus, distributed consumer balancing, transaction coordinator, or generic exactly-once delivery. Callers must provide explicit idempotency and duplicate-detection metadata when their domain requires effectively-once patterns. Implementations map overload, stale leases, invalid arguments, recovery failure, and durable storage failure to stable middleware error codes and must redact message payload bytes from status and exception details.

  • Method Details

    • enqueue

      EnqueueResult enqueue(QueueName queue, QueueMessage message, EnqueueOptions options)
      Enqueues a message durably before it can be leased.

      The append must be durable before the message is visible to consumers. Duplicate idempotency or dedupe keys return the previous durable decision according to the implementation's duplicate policy.

      Parameters:
      queue - queue name to receive the message
      message - message payload and safe metadata; payload is not exposed in status
      options - enqueue options; defaults when null
      Returns:
      assigned durable message identity and duplicate status

    • lease

      LeaseBatch lease(QueueName queue, ConsumerId consumer, LeaseOptions options)
      Leases available messages for a consumer and makes them invisible until their visibility timeout expires.

      Lease acquisition is local and durable enough to reject stale acknowledgements. It is not distributed consumer-group balancing.

      Parameters:
      queue - queue name
      consumer - consumer identity
      options - lease options; defaults when null
      Returns:
      leased message batch, possibly empty

    • ack

      AckResult ack(QueueName queue, MessageId messageId, AckOptions options)
      Acknowledges a currently leased message.

      The acknowledgement must validate the current lease id. Stale, missing, or mismatched leases fail with a stable fencing/lease error.

      Parameters:
      queue - queue name
      messageId - message identity
      options - acknowledge options containing the current lease id
      Returns:
      acknowledge result

    • nack

      NackResult nack(QueueName queue, MessageId messageId, NackOptions options)
      Negatively acknowledges a currently leased message and either requeues it for retry or moves it to the dead-letter set.

      Retry timing uses the configured deterministic clock. Dead-letter status is visible through redacted queue metrics without exposing payload bytes. The negative acknowledgement must validate the current lease id; stale, missing, or mismatched leases fail with a stable fencing/lease error.

      Parameters:
      queue - queue name
      messageId - message identity
      options - negative acknowledge options
      Returns:
      negative acknowledge result

    • status

      QueueStatus status(QueueName queue)
      Returns redacted queue status and metrics.
      Parameters:
      queue - queue name
      Returns:
      immutable queue status with counters, partition summaries, and last safe error

    • close

      void close()
      Closes owned resources. Further operations fail with a stable middleware error.

      Close should be idempotent. Implementations must finish or reject in-flight local operations without leaking filesystem paths, payloads, or credentials in error details.

      Specified by:
      close in interface AutoCloseable