Courier Android Library

Courier provides several features for robust mobile connectivity:

• Adaptive Keep Alive: Optimizes connection maintenance.
• Automatic Reconnect & Resubscribe: Handles connection drops gracefully.
• Subscription Store & Database Persistence: Ensures subscriptions and state are maintained.
• Backpressure handling: Manages data flow to prevent overwhelming the client.
• Reliable Pinging: Uses Alarm, Timer, and WorkManager to send pings.
• Extensibility: Supports Message & Stream Adapters and MQTT Chuck.

In Courier, an Authenticator is an interface used to manage MQTT connection credentials. When an MQTT client attempts to connect to a broker, it sends a username and password within the CONNECT packet. If the broker rejects these credentials (returning reason code 5), the Courier library uses the Authenticator to refresh the connection options (username and password) to enable a successful reconnection.

You can either provide your own custom implementation of the Authenticator interface or use the library's built-in HttpAuthenticator.

MQTT connections can be terminated by TCP binding timeouts if they remain idle for too long. To prevent this, the client must send PINGREQ packets at a specific Keepalive Interval. The broker responds with a PINGRESP packet to confirm the connection is alive.

In the Courier Android library, a Ping Sender is an abstraction that encapsulates the mechanism used to send these ping requests. Different implementations are available depending on whether you need to maintain the connection while the app is in the background or foreground.

You can extract specific parts of a placeholder value using a delimiter and a 0-based index with the syntax (<placeholder>,<delimiter>,<index>).

Example: If the client id (%c) is region:tenant:device:

• Topic: user/(%c,:,2)/send
• Logic: Splits region:tenant:device by : into [region, tenant, device] and picks index 2.
• Resolved Topic: user/device/send.

Warning: An index that is out of range will result in an IllegalArgumentException.

@Send(topic = "user/(%c,:,2)/send", qos = QoS.ONE)
fun send(@Data message: Message)

Courier supports connection placeholders that are automatically resolved from the established MQTT connection. These can be used in @Send, @Subscribe, @SubscribeMultiple, and @Unsubscribe annotations.

Supported Placeholders:

• %u: The connection's username.
• %c: The connection's client id.

Important Limitation: Placeholders are not resolved for @Receive topics. For @Receive, the topic string is used as-is. If you need placeholder-based receiving, use @Subscribe with a stream instead.

interface MessageService {
	@Send(topic = "user/%u/send", qos = QoS.ONE)
	fun send(@Data message: Message)

	@Subscribe(topic = "client/%c/receive", qos = QoS.ONE)
	fun subscribe(): Observable<Message>
}

Courier utilizes MQTT's built-in QoS levels to manage reliable message delivery. You can choose from three levels depending on your requirements for delivery guarantees:

• QoS 0 (At most once): Fire and forget. The message is sent once without acknowledgment from the client or broker.
• QoS 1 (At least once): Acknowledged delivery. The sender retries the message until an acknowledgment is received.
• QoS 2 (Exactly once): Assured delivery. Uses a two-level handshake between sender and receiver to ensure exactly one copy of the message is delivered.

Quality of Service (QoS) defines the delivery guarantee for a message between a sender and a receiver. In MQTT, there are three standard levels:

1. At most once (0): The message is sent without an acknowledgment. It may arrive once or not at all.
2. At least once (1): The message is acknowledged with PUBACK. The receiver is guaranteed to receive the message, but it might receive it more than once if the acknowledgment is lost.
3. Exactly once (2): The highest level of guarantee, ensuring the message is delivered exactly one time through a four-step handshake.

When configuring QoS, consider both directions of delivery:

• From the publishing client to the broker.
• From the broker to the subscribing client.