LavinMQ Documentation

Use the following comparison to decide if a Stream is appropriate for your use case:

Note on Restrictions: Streams do not support x-dead-letter-exchange, x-dead-letter-routing-key, x-expires, x-delivery-limit, x-overflow, x-single-active-consumer, or x-max-priority.

The x-delivery-limit argument (or delivery-limit policy) defines the maximum number of times a message can be redelivered.

How it works:

1. Each time a message is requeued (via reject or nack with requeue=true), an internal delivery counter is incremented.
2. When the limit is reached, the message is dead-lettered instead of being requeued.
3. On redelivery, the server adds an x-delivery-count header to the message indicating how many prior delivery attempts occurred (this header is omitted on the very first delivery).

Deduplication in LavinMQ is a best-effort mechanism with the following constraints:

• Volatility: The deduplication cache is stored in memory only. It is lost during server restarts or during leadership transfers in a cluster.
• No Replication: The cache is not replicated across cluster nodes.
• Post-Failover Behavior: Because the cache is lost on restart or failover, messages that were previously identified as duplicates may be accepted again once the server is back online.

Bindings are the mechanism that connects exchanges to queues (or other exchanges) to define routing rules. When a message is published to an exchange, the exchange uses its bindings to determine which queues should receive the message based on routing keys and optional arguments.

Routing behavior depends on the exchange type:

• Direct: Requires an exact match between the message routing key and the binding routing key.
• Fanout: The routing key is ignored; all messages are broadcast to all bound queues.
• Topic: Uses pattern matching with wildcards: * (matches one word) and # (matches zero or more words).
• Headers: The routing key is ignored; matching is performed using binding arguments.
• Consistent Hash: The routing key is treated as a weight (integer) used for hash distribution.

Routing Behavior

Dead-lettered messages are routed directly to matching queues on the dead-letter exchange. This process:

• Bypasses exchange-level features like delayed delivery and consistent hashing.
• Strips the x-dead-letter-exchange and x-dead-letter-routing-key headers from the message before routing.
• If x-dead-letter-routing-key is set, CC and BCC headers are ignored for routing (though they are maintained on the message).

Interaction with Overflow

• drop-head overflow: Dropped messages are dead-lettered with the reason maxlen or maxlenbytes.
• reject-publish overflow: New messages are rejected (nacked to the publisher) rather than being dead-lettered.

LavinMQ uses a leader-based replication model coordinated by an external etcd service.

• Leader: The single node that accepts all client connections and writes. It is responsible for replicating data to followers.
• Followers: Nodes that receive replicated data from the leader. They maintain a synchronized copy of the data and can be promoted to leader during a failover.
• etcd: An external coordination service used for leader election, tracking In-Sync Replicas (ISR), and managing shared state.

In this model, only the leader handles active client traffic, while followers act as hot standbys.

LavinMQ derives permissions and tags from JWT scopes. It collects scopes from these sources in order:

1. resource_access.<resource_server_id>.roles (if resource_server_id is set).
2. The standard scope claim (space-separated list).
3. Additional claims specified in additional_scopes_keys.

Scope Filtering

To isolate LavinMQ-specific scopes, you can use scope_prefix:

• If scope_prefix is set, only scopes starting with that prefix are kept (the prefix is then stripped).
• If scope_prefix is unset but resource_server_id is set, the prefix defaults to <resource_server_id>..
• If neither is set, all scopes are used as-is.

The queue type is selected at the time of declaration and cannot be changed later. Use the x-queue-type argument to specify the type:

• Standard (default): A FIFO queue with optional durability.
• Priority: Delivers messages based on priority levels (requires x-max-priority).
• Stream: An append-only log designed for multiple consumers.
• MQTT Session (mqtt): An internal type used by MQTT sessions.

// Example of declaring a priority queue via arguments
{
  "arguments": {
    "x-queue-type": "priority",
    "x-max-priority": 10
  }
}

Operator policies are a restricted subset of policies designed for infrastructure operators. Unlike regular policies, operator policies are merged with regular policies rather than being replaced by them.

Behavior

• Layering: They are evaluated independently and can layer on top of regular policies.
• Conflict Resolution: If an operator policy and a regular policy set the same key, the lower (more restrictive) value applies.
• Allowed Keys: Operator policies are limited to the following keys:
  • max-length
  • max-length-bytes
  • message-ttl
  • expires