> ## Documentation Index
> Fetch the complete documentation index at: https://densumesh-broccoli-27.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Messages

> API reference for BrokerMessage and related types

## BrokerMessage

A wrapper for messages that includes metadata for processing.

```rust theme={null}
use broccoli_queue::brokers::broker::BrokerMessage;
```

### Structure

```rust theme={null}
pub struct BrokerMessage<T: Clone> {
    /// Unique identifier for the message
    pub task_id: uuid::Uuid,
    
    /// The actual message content
    pub payload: T,
    
    /// Number of processing attempts made
    pub attempts: u8,
    
    /// Disambiguator for message fairness
    pub disambiguator: Option<String>,
}
```

### Fields

| Field           | Type             | Description                                          |
| --------------- | ---------------- | ---------------------------------------------------- |
| `task_id`       | `Uuid`           | Unique message identifier, auto-generated on publish |
| `payload`       | `T`              | Your custom message data                             |
| `attempts`      | `u8`             | Number of times this message has been processed      |
| `disambiguator` | `Option<String>` | Optional identifier for fairness queue routing       |

### Creating messages

Messages are automatically created when publishing:

```rust theme={null}
let job = JobPayload { id: "1".into(), task: "process".into() };

// publish() creates and returns the BrokerMessage
let message = queue.publish("jobs", None, &job, None).await?;
println!("Task ID: {}", message.task_id);
```

### Accessing message data

```rust theme={null}
queue.process_messages("jobs", Some(1), None, |msg: BrokerMessage<JobPayload>| async move {
    // Access metadata
    println!("ID: {}", msg.task_id);
    println!("Attempts: {}", msg.attempts);
    println!("Disambiguator: {:?}", msg.disambiguator);
    
    // Access payload
    let job = &msg.payload;
    println!("Job: {} - {}", job.id, job.task);
    
    Ok(())
}).await?;
```

***

## Payload requirements

Your message payload type must implement:

* `Clone`
* `serde::Serialize`
* `serde::Deserialize`

### Example payload

```rust theme={null}
use serde::{Serialize, Deserialize};

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct JobPayload {
    pub id: String,
    pub task_name: String,
    pub parameters: serde_json::Value,
    pub created_at: chrono::DateTime<chrono::Utc>,
}
```

### Complex payload

```rust theme={null}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EmailJob {
    pub recipient: String,
    pub subject: String,
    pub body: String,
    pub attachments: Vec<Attachment>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Attachment {
    pub filename: String,
    pub content_type: String,
    #[serde(with = "base64_serde")]
    pub data: Vec<u8>,
}
```

***

## InternalBrokerMessage

Internal message representation used by broker implementations. You typically don't interact with this directly.

```rust theme={null}
pub struct InternalBrokerMessage {
    pub task_id: String,
    pub payload: String,  // JSON serialized
    pub attempts: u8,
    pub disambiguator: Option<String>,
}
```

***

## BrokerConfig

Configuration options for broker behavior.

```rust theme={null}
pub struct BrokerConfig {
    /// Maximum retry attempts (default: 3)
    pub retry_attempts: Option<u8>,
    
    /// Whether to retry failed messages (default: true)
    pub retry_failed: Option<bool>,
    
    /// Connection pool size (default: 10)
    pub pool_connections: Option<u8>,
    
    /// Enable message scheduling (default: false)
    pub enable_scheduling: Option<bool>,
}
```

### Default values

```rust theme={null}
impl Default for BrokerConfig {
    fn default() -> Self {
        Self {
            retry_attempts: Some(3),
            retry_failed: Some(true),
            pool_connections: Some(10),
            enable_scheduling: Some(false),
        }
    }
}
```

***

## BrokerType

Enum representing supported broker types.

```rust theme={null}
pub enum BrokerType {
    #[cfg(feature = "redis")]
    Redis,
    
    #[cfg(feature = "rabbitmq")]
    RabbitMQ,
    
    #[cfg(feature = "surrealdb")]
    SurrealDB,
}
```

***

## Broker trait

The `Broker` trait defines the interface that all broker implementations must satisfy. This is internal to Broccoli but useful for understanding the abstraction.

```rust theme={null}
#[async_trait]
pub trait Broker: Send + Sync {
    async fn connect(&mut self, broker_url: &str) -> Result<(), BroccoliError>;
    
    async fn publish(
        &self,
        queue_name: &str,
        disambiguator: Option<String>,
        message: &[InternalBrokerMessage],
        options: Option<PublishOptions>,
    ) -> Result<Vec<InternalBrokerMessage>, BroccoliError>;
    
    async fn consume(
        &self,
        queue_name: &str,
        options: Option<ConsumeOptions>,
    ) -> Result<InternalBrokerMessage, BroccoliError>;
    
    async fn try_consume(
        &self,
        queue_name: &str,
        options: Option<ConsumeOptions>,
    ) -> Result<Option<InternalBrokerMessage>, BroccoliError>;
    
    async fn acknowledge(
        &self,
        queue_name: &str,
        message: InternalBrokerMessage,
    ) -> Result<(), BroccoliError>;
    
    async fn reject(
        &self,
        queue_name: &str,
        message: InternalBrokerMessage,
    ) -> Result<(), BroccoliError>;
    
    async fn cancel(
        &self,
        queue_name: &str,
        message_id: String,
    ) -> Result<(), BroccoliError>;
    
    async fn size(
        &self,
        queue_name: &str,
    ) -> Result<HashMap<String, u64>, BroccoliError>;
}
```