Struct ConnectOptions 

pub struct ConnectOptions {
    pub accept_version: Option<String>,
    pub client_id: Option<String>,
    pub host: Option<String>,
    pub headers: Vec<(String, String)>,
    pub heartbeat_tx: Option<Sender<()>>,
}

Options for customizing the STOMP CONNECT frame.

Use this struct with Connection::connect_with_options() to set custom headers, specify supported STOMP versions, or configure broker-specific options like client-id for durable subscriptions.

Validation

This struct performs minimal validation. Values are passed to the broker as-is, and invalid configurations will be rejected by the broker at connection time. Empty strings are technically accepted but may cause broker-specific errors.

Custom Headers

Custom headers added via header() cannot override critical STOMP headers (accept-version, host, login, passcode, heart-beat, client-id). Such headers are silently ignored. Use the dedicated builder methods to set these values.

Example

use iridium_stomp::{Connection, ConnectOptions};

let options = ConnectOptions::default()
    .client_id("my-durable-client")
    .host("my-vhost")
    .header("custom-header", "value");

let conn = Connection::connect_with_options(
    "localhost:61613",
    "guest",
    "guest",
    "10000,10000",
    options,
).await?;

Fields

accept_version: Option<String>

STOMP version(s) to accept (e.g., “1.2” or “1.0,1.1,1.2”). Defaults to “1.2” if not set.

client_id: Option<String>

Client ID for durable subscriptions (required by ActiveMQ, etc.).

host: Option<String>

Virtual host header value. Defaults to “/” if not set.

headers: Vec<(String, String)>

Additional custom headers to include in the CONNECT frame. Note: Headers that would override critical STOMP headers are ignored.

heartbeat_tx: Option<Sender<()>>

Optional channel to receive heartbeat notifications. When set, the connection will send a () on this channel each time a heartbeat is received from the server.

Implementations

impl ConnectOptions

pub fn new() -> Self

Create a new ConnectOptions with default values.

pub fn accept_version(self, version: impl Into<String>) -> Self

Set the STOMP version(s) to accept (builder style).

Examples: “1.2”, “1.1,1.2”, “1.0,1.1,1.2”

pub fn client_id(self, id: impl Into<String>) -> Self

Set the client ID for durable subscriptions (builder style).

Required by some brokers (e.g., ActiveMQ) for durable topic subscriptions.

pub fn host(self, host: impl Into<String>) -> Self

Set the virtual host (builder style).

Defaults to “/” if not set.

pub fn header(self, key: impl Into<String>, value: impl Into<String>) -> Self

Add a custom header to the CONNECT frame (builder style).

pub fn with_heartbeat_notify(self, tx: Sender<()>) -> Self

Set a channel to receive heartbeat notifications (builder style).

When set, the connection will send a () on this channel each time a heartbeat is received from the server. This is useful for CLI tools or monitoring applications that want to display heartbeat status.

Note

Notifications are sent using try_send() to avoid blocking the connection’s background task. If the channel buffer is full, notifications will be silently dropped. Use a sufficiently sized channel buffer (e.g., 16) to avoid missing notifications.

Example

use tokio::sync::mpsc;
use iridium_stomp::ConnectOptions;

let (tx, mut rx) = mpsc::channel(16);
let options = ConnectOptions::default()
    .with_heartbeat_notify(tx);

// In another task:
while rx.recv().await.is_some() {
    println!("Heartbeat received!");
}

Trait Implementations

impl Clone for ConnectOptions

fn clone(&self) -> ConnectOptions

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ConnectOptions

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ConnectOptions

fn default() -> ConnectOptions

Returns the “default value” for a type.