# delivery.capnp — Delivery Service RPC interface.
#
# The Delivery Service is a simple store-and-forward relay. It does not parse
# MLS messages — all payloads are opaque byte strings routed by recipient key.
#
# Callers are responsible for:
#   - Routing Welcome messages to the correct new member after add_members().
#   - Routing Commit messages to any existing group members (other than self).
#   - Routing Application messages to the intended recipient(s).
#
# The DS indexes queues by the recipient's raw Ed25519 public key (32 bytes),
# matching the indexing scheme used by the Authentication Service.
#
# ID generated with: capnp id
@0xc5d9e2b4f1a83076;

interface DeliveryService {
  # Enqueue an opaque payload for delivery to a recipient.
  #
  # recipientKey : Ed25519 public key of the intended recipient (exactly 32 bytes).
  # payload      : Opaque byte string — a TLS-encoded MlsMessageOut blob or any
  #                other framed data the application layer wants to deliver.
  # channelId    : Optional channel identifier (empty for legacy). A 16-byte UUID
  #                is recommended for 1:1 channels.
  # version      : Schema/wire version. Must be 0 (legacy) or 1 (this spec).
  #
  # The payload is appended to the recipient's FIFO queue. Returns immediately;
  # the recipient retrieves it via `fetch`.
  enqueue @0 (recipientKey :Data, payload :Data, channelId :Data, version :UInt16) -> ();

  # Fetch and atomically drain all queued payloads for a given recipient.
  #
  # recipientKey : Ed25519 public key of the caller (exactly 32 bytes).
  # channelId    : Optional channel identifier (empty for legacy).
  # version      : Schema/wire version. Must be 0 (legacy) or 1 (this spec).
  #
  # Returns the complete queue in FIFO order and clears it. Returns an empty
  # list if there are no pending messages.
  fetch @1 (recipientKey :Data, channelId :Data, version :UInt16) -> (payloads :List(Data));
}