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<()>>,
    pub disconnect_timeout: Option<Duration>,
    pub connect_timeout: Option<Duration>,
    pub max_frame_size: Option<usize>,
}

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",
    Connection::DEFAULT_HEARTBEAT,
    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.

disconnect_timeout: Option<Duration>

How long Connection::close waits for the broker’s RECEIPT after it sends DISCONNECT. Defaults to Connection::DEFAULT_DISCONNECT_TIMEOUT if not set.

connect_timeout: Option<Duration>

Upper bound on the initial connect-and-handshake before Connection::connect_with_options gives up. When None (the default), an unreachable broker is retried indefinitely with backoff. When set, the whole operation is bounded and, on expiry, the last error encountered is returned.

max_frame_size: Option<usize>

Largest inbound frame to accept, in bytes. When None, the default is crate::parser::DEFAULT_MAX_FRAME_SIZE (16 MiB). A frame larger than this — whether via an oversized content-length or a body that never terminates — is rejected as a ConnError::Io, so a malicious or buggy broker cannot exhaust client memory or panic the decoder.

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 disconnect_timeout(self, timeout: Duration) -> Self

Set how long Connection::close waits for the broker to confirm the DISCONNECT (builder style).

Defaults to Connection::DEFAULT_DISCONNECT_TIMEOUT. The socket is torn down when the timeout expires regardless, so this bounds how long a clean shutdown may take against an unresponsive broker; it does not decide whether the connection closes.

Example

let options = ConnectOptions::default()
    .disconnect_timeout(Duration::from_secs(2));

pub fn connect_timeout(self, timeout: Duration) -> Self

Bound the initial connect and STOMP handshake (builder style).

By default Connection::connect_with_options retries an unreachable broker indefinitely with exponential backoff, which is the right choice for a long-lived service that should wait for its broker to come up. It is the wrong choice for a CLI tool or one-shot script pointed at a misconfigured address: without a bound it hangs forever. Set this to cap the whole operation.

When the timeout expires, connect_with_options returns the last error it encountered — a ConnError::Io, or a ConnError::Protocol such as a broker that closed the socket mid-handshake — or a synthesized std::io::ErrorKind::TimedOut if no attempt had produced one yet. A ConnError::ServerRejected still fails immediately, before the bound is consulted, because retrying bad credentials is pointless.

Example

let options = ConnectOptions::default()
    .connect_timeout(Duration::from_secs(60));

pub fn max_frame_size(self, max_frame_size: usize) -> Self

Set the largest inbound frame to accept, in bytes (builder style).

Defaults to crate::parser::DEFAULT_MAX_FRAME_SIZE (16 MiB). A frame exceeding this — an oversized content-length, or a body that never terminates — is rejected rather than buffered or allocated, so a malicious or buggy broker cannot exhaust client memory. Raise it if you legitimately exchange larger messages.

Example

let options = ConnectOptions::default()
    .max_frame_size(64 * 1024 * 1024);

pub fn 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()
    .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.