Hammerwork

https://docs.rs/hammerwork/1.15.5/hammerwork/
Admin
Hammerwork is a high-performance, database-driven job queue for Rust with comprehensive features...
Tokens:256,481
Snippets:1,869
Trust Score:9.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### Configure EventFilter Examples

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/events/struct.EventFilter.html

Examples demonstrating how to instantiate and configure an EventFilter for different use cases.

```rust
use hammerwork::events::{EventFilter, JobLifecycleEventType};
use hammerwork::priority::JobPriority;

// Filter for high-priority completed jobs in specific queues
let filter = EventFilter::new()
    .with_event_types(vec![JobLifecycleEventType::Completed])
    .with_queue_names(vec!["critical".to_string(), "urgent".to_string()])
    .with_priorities(vec![JobPriority::High, JobPriority::Critical])
    .with_processing_time_range(Some(5000), None) // > 5 seconds
    .with_metadata_filter("tenant_id".to_string(), "premium".to_string())
    .include_payload();
```

```rust
use hammerwork::events::{EventFilter, JobLifecycleEventType};

// Filter for any failure events
let failure_filter = EventFilter::new()
    .with_event_types(vec![
        JobLifecycleEventType::Failed,
        JobLifecycleEventType::Dead,
        JobLifecycleEventType::TimedOut,
    ]);
```

--------------------------------

### EventFilter Examples

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/events/struct.EventFilter.html

Illustrative examples of how to create and configure EventFilter instances.

```APIDOC
## Examples

### Example 1: Filtering for high-priority completed jobs in specific queues
```rust
use hammerwork::events::{EventFilter, JobLifecycleEventType};
use hammerwork::priority::JobPriority;

let filter = EventFilter::new()
    .with_event_types(vec![JobLifecycleEventType::Completed])
    .with_queue_names(vec!["critical".to_string(), "urgent".to_string()])
    .with_priorities(vec![JobPriority::High, JobPriority::Critical])
    .with_processing_time_range(Some(5000), None) // > 5 seconds
    .with_metadata_filter("tenant_id".to_string(), "premium".to_string())
    .include_payload();
```

### Example 2: Filtering for any failure events
```rust
use hammerwork::events::{EventFilter, JobLifecycleEventType};

let failure_filter = EventFilter::new()
    .with_event_types(vec![
        JobLifecycleEventType::Failed,
        JobLifecycleEventType::Dead,
        JobLifecycleEventType::TimedOut,
    ]);
```
```

--------------------------------

### Example: Basic File Processing Spawner

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/spawn/trait.SpawnHandler.html

An example implementation of SpawnHandler to process a list of files specified in the parent job's payload.

```APIDOC
## Example: Basic File Processing Spawner

This example demonstrates how to implement `SpawnHandler` to spawn jobs for processing individual files.

### Code Example
```rust
use async_trait::async_trait;
use serde_json::json;
use hammerwork::{Job, spawn::{SpawnHandler, SpawnContext}};

struct FileProcessingSpawner;

#[async_trait]
impl<DB: sqlx::Database + Send + Sync> SpawnHandler<DB> for FileProcessingSpawner {
    async fn spawn_jobs(&self, context: SpawnContext<DB>) -> hammerwork::Result<Vec<Job>> {
        let files = context.parent_job.payload["files"].as_array()
            .ok_or_else(|| hammerwork::error::HammerworkError::InvalidJobPayload {
                message: "Missing files array in payload".to_string()
            })?;

        let mut child_jobs = Vec::new();
        for file in files {
            let child_job = Job::new(
                "process_file".to_string(),
                json!({
                    "file_path": file,
                    "parent_job_id": context.parent_job.id
                })
            );
            child_jobs.push(child_job);
        }

        Ok(child_jobs)
    }
}
```

### Explanation
- The `FileProcessingSpawner` struct implements the `SpawnHandler` trait.
- The `spawn_jobs` method extracts a list of files from the parent job's payload.
- For each file, it creates a new `Job` named `"process_file"` with the file path and parent job ID in its payload.
- It returns a vector containing all the newly created child jobs.
```

--------------------------------

### Example: Data Chunking Spawner with Validation

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/spawn/trait.SpawnHandler.html

An example implementation of SpawnHandler for splitting large data processing tasks into smaller, manageable chunks.

```APIDOC
## Example: Data Chunking Spawner with Validation

This example shows how to split large datasets into smaller processing chunks using `SpawnHandler`.

### Code Example
```rust
use async_trait::async_trait;
use serde_json::json;
use hammerwork::{Job, spawn::{SpawnHandler, SpawnContext, SpawnConfig}};

struct DataChunkingSpawner;

#[async_trait]
impl<DB: sqlx::Database + Send + Sync> SpawnHandler<DB> for DataChunkingSpawner {
    async fn spawn_jobs(&self, context: SpawnContext<DB>) -> hammerwork::Result<Vec<Job>> {
        // Break large data processing into manageable chunks
        let total_records = context.parent_job.payload["total_records"].as_u64().unwrap_or(0) as usize;
        let chunk_size = context.parent_job.payload["chunk_size"].as_u64().unwrap_or(1000) as usize;

        let mut child_jobs = Vec::new();
        let mut offset = 0;

        while offset < total_records {
            let limit = std::cmp::min(chunk_size, total_records - offset);
             
            let child_job = Job::new(
                "process_chunk".to_string(),
                json!({
                    "offset": offset,
                    "limit": limit,
                    "parent_job_id": context.parent_job.id
                })
            );
            child_jobs.push(child_job);
            offset += chunk_size;
        }
         
        Ok(child_jobs)
    }
}
```

### Explanation
- The `DataChunkingSpawner` implements `SpawnHandler` to manage large data processing tasks.
- It reads `total_records` and `chunk_size` from the parent job's payload.
- It then iteratively creates child jobs (`"process_chunk"`) for each data chunk, specifying the `offset` and `limit` for each chunk.
- This approach ensures that large datasets are processed in smaller, more manageable segments.
```

--------------------------------

### SpawnConfig Examples

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/spawn/struct.SpawnConfig.html

Illustrates different ways to initialize and use the SpawnConfig struct, from default settings to custom configurations.

```APIDOC
## Examples

### Basic Configuration
```rust
use hammerwork::spawn::SpawnConfig;

// Use default configuration
let config = SpawnConfig::default();
assert_eq!(config.max_spawn_count, Some(100));
assert!(config.inherit_priority);
assert!(config.inherit_retry_strategy);
assert!(!config.inherit_timeout);
assert!(config.inherit_trace_context);
```

### Custom Configuration for File Processing
```rust
use hammerwork::spawn::SpawnConfig;

let config = SpawnConfig {
    max_spawn_count: Some(50),        // Limit to 50 files
    inherit_priority: true,           // Inherit parent priority
    inherit_retry_strategy: true,     // Inherit retry settings
    inherit_timeout: false,           // Each file has own timeout
    inherit_trace_context: true,      // Maintain tracing
    operation_id: Some("file_batch_001".to_string()),
};
```

### Configuration for Large Data Processing
```rust
use hammerwork::spawn::SpawnConfig;

let config = SpawnConfig {
    max_spawn_count: Some(1000),      // Allow many chunks
    inherit_priority: false,          // Let chunks be normal priority
    inherit_retry_strategy: true,     // Inherit retry logic
    inherit_timeout: true,            // Inherit timeout settings
    inherit_trace_context: true,      // Maintain trace correlation
    operation_id: Some("data_processing_2024_01".to_string()),
};
```
```

--------------------------------

### Configure SpawnConfig Examples

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/spawn/struct.SpawnConfig.html

Various ways to initialize and customize SpawnConfig for different operational requirements.

```rust
use hammerwork::spawn::SpawnConfig;

// Use default configuration
let config = SpawnConfig::default();
assert_eq!(config.max_spawn_count, Some(100));
assert!(config.inherit_priority);
assert!(config.inherit_retry_strategy);
assert!(!config.inherit_timeout);
assert!(config.inherit_trace_context);
```

```rust
use hammerwork::spawn::SpawnConfig;

let config = SpawnConfig {
    max_spawn_count: Some(50),        // Limit to 50 files
    inherit_priority: true,           // Inherit parent priority
    inherit_retry_strategy: true,     // Inherit retry settings
    inherit_timeout: false,           // Each file has own timeout
    inherit_trace_context: true,      // Maintain tracing
    operation_id: Some("file_batch_001".to_string()),
};
```

```rust
use hammerwork::spawn::SpawnConfig;

let config = SpawnConfig {
    max_spawn_count: Some(1000),      // Allow many chunks
    inherit_priority: false,          // Let chunks be normal priority
    inherit_retry_strategy: true,     // Inherit retry logic
    inherit_timeout: true,            // Inherit timeout settings
    inherit_trace_context: true,      // Maintain trace correlation
    operation_id: Some("data_processing_2024_01".to_string()),
};
```

--------------------------------

### Handling File Metadata Operations with Result

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/type.Result.html

Shows how to use `and_then` to chain fallible file system operations, such as getting metadata. This example checks for successful metadata retrieval and handles potential errors like 'NotFound'.

```rust
use std::{io::ErrorKind, path::Path};

// Note: on Windows "/" maps to "C:\"
let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());
assert!(root_modified_time.is_ok());

let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());
assert!(should_fail.is_err());
assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);
```

--------------------------------

### Initialize Retry Strategies

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/retry/enum.RetryStrategy.html

Examples of initializing different retry strategy variants.

```rust
use hammerwork::retry::RetryStrategy;
use std::time::Duration;

// Simple fixed delay
let fixed = RetryStrategy::Fixed(Duration::from_secs(30));

// Linear backoff: 10s, 20s, 30s, 40s...
let linear = RetryStrategy::Linear {
    base: Duration::from_secs(10),
    increment: Duration::from_secs(10),
    max_delay: Some(Duration::from_secs(5 * 60)),
};

// Exponential backoff: 1s, 2s, 4s, 8s, 16s...
let exponential = RetryStrategy::Exponential {
    base: Duration::from_secs(1),
    multiplier: 2.0,
    max_delay: Some(Duration::from_secs(10 * 60)),
    jitter: None,
};
```

--------------------------------

### Initialize JobArchiver

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/archive/struct.JobArchiver.html

Examples for creating a new JobArchiver instance, including sharing pools with a JobQueue.

```rust
use hammerwork::archive::JobArchiver;
use sqlx::PgPool;

let pool = PgPool::connect("postgresql://localhost/hammerwork").await?;
let archiver = JobArchiver::new(pool);
```

```rust
use hammerwork::{JobQueue, archive::JobArchiver};
use std::sync::Arc;

let queue = Arc::new(JobQueue::new(pool.clone()));

// Access the public pool field to create an archiver
let archiver = JobArchiver::new(queue.pool.clone());

// Both the queue and archiver share the same database connection pool
```

```rust
use hammerwork::{JobQueue, archive::JobArchiver};
use std::sync::Arc;

let queue = Arc::new(JobQueue::new(pool.clone()));

// Create multiple archivers sharing the same pool
let archiver1 = JobArchiver::new(queue.pool.clone());
let archiver2 = JobArchiver::new(queue.pool.clone());

// All components share the same connection pool for efficiency
```

--------------------------------

### Fixed Strategy Usage

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/retry/enum.RetryStrategy.html

Example demonstrating a fixed delay strategy.

```rust
use hammerwork::retry::RetryStrategy;
use std::time::Duration;

let strategy = RetryStrategy::Fixed(Duration::from_secs(30));

// All attempts wait 30 seconds: 30s, 30s, 30s...
assert_eq!(strategy.calculate_delay(1), Duration::from_secs(30));
assert_eq!(strategy.calculate_delay(5), Duration::from_secs(30));
```

--------------------------------

### Basic Webhook Setup

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/webhooks/index.html

Sets up a basic webhook to send POST requests for job completion events. Requires EventManager and WebhookManager initialization.

```rust
use hammerwork::webhooks::{WebhookManager, WebhookConfig, HttpMethod, WebhookManagerConfig};
use hammerwork::events::{EventManager, EventFilter, JobLifecycleEventType};
use std::sync::Arc;
use std::collections::HashMap;

let event_manager = Arc::new(EventManager::new_default());
let webhook_manager = WebhookManager::new(
    event_manager.clone(),
    WebhookManagerConfig::default()
);

let webhook = WebhookConfig::new(
    "job_completion_hook".to_string(),
    "https://api.example.com/webhooks/jobs".to_string(),
)
.with_method(HttpMethod::Post)
.with_header("Content-Type".to_string(), "application/json".to_string())
.with_filter(
    EventFilter::new()
        .with_event_types(vec![JobLifecycleEventType::Completed])
);

webhook_manager.add_webhook(webhook).await?;
```

--------------------------------

### Set Job Start Handler

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/worker/struct.Worker.html

Convenience method to register a single callback for job start events.

```rust

let worker = Worker::new(queue, "queue".to_string(), handler)
    .on_job_start(|event| {
        println!("Starting job: {}", event.job.id);
    });
```

--------------------------------

### Exponential Strategy Usage

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/retry/enum.RetryStrategy.html

Example demonstrating an exponential backoff strategy with jitter.

```rust
use hammerwork::retry::{RetryStrategy, JitterType};
use std::time::Duration;

let strategy = RetryStrategy::Exponential {
    base: Duration::from_secs(1),
    multiplier: 2.0,
    max_delay: Some(Duration::from_secs(10 * 60)),
    jitter: Some(JitterType::Multiplicative(0.1)), // ±10% jitter
};

// Base delays: 1s, 2s, 4s, 8s, 16s, 32s, 64s, 128s, 256s, 512s (capped at 600s)
// With jitter: each delay is randomly adjusted by ±10%
```

--------------------------------

### Arc::new_in Example

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/worker/type.JobHandler.html

Demonstrates constructing a new Arc with a custom allocator. This is an experimental API.

```rust
use std::sync::Arc;
use std::alloc::System;

let arc = Arc::new_in(5, System);
assert_eq!(*arc, 5);
```

--------------------------------

### Linear Strategy Usage

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/retry/enum.RetryStrategy.html

Example demonstrating a linear backoff strategy with a maximum delay cap.

```rust
use hammerwork::retry::RetryStrategy;
use std::time::Duration;

let strategy = RetryStrategy::Linear {
    base: Duration::from_secs(5),
    increment: Duration::from_secs(10),
    max_delay: Some(Duration::from_secs(2 * 60)),
};

// Delays: 5s, 15s, 25s, 35s, 45s, 55s, 65s, 75s, 85s, 95s, 120s (capped)...
assert_eq!(strategy.calculate_delay(1), Duration::from_secs(15));
assert_eq!(strategy.calculate_delay(10), Duration::from_secs(105));
```

--------------------------------

### Create a New JobGroup

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/workflow/struct.JobGroup.html

Shows how to instantiate a new JobGroup with a given name. This is the starting point for defining a workflow.

```rust
use hammerwork::workflow::JobGroup;

let workflow = JobGroup::new("data_processing_pipeline");
assert_eq!(workflow.name, "data_processing_pipeline");
```

--------------------------------

### GET /workflow/ready-jobs

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/workflow/struct.JobGroup.html

Retrieves a list of jobs that are currently ready to execute.

```APIDOC
## GET /workflow/ready-jobs

### Description
Returns jobs that are ready to execute (have no unsatisfied dependencies).

### Response
#### Success Response (200)
- **jobs** (Vec<Job>) - List of jobs ready for execution
```

--------------------------------

### Verify HMAC Signature Usage Example

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/webhooks/fn.verify_hmac_signature.html

Demonstrates generating and verifying a signature for a webhook payload.

```rust
use hammerwork::webhooks::{generate_hmac_signature, verify_hmac_signature};

let secret = "my-webhook-secret";
let payload = b"{'event': 'job.completed', 'job_id': '123'}";

// Generate signature (sender side)
let signature = generate_hmac_signature(secret, payload);

// Verify signature (receiver side)
let is_valid = verify_hmac_signature(secret, payload, &signature);
assert!(is_valid);

// Invalid signature
let is_invalid = verify_hmac_signature(secret, payload, "invalid-signature");
assert!(!is_invalid);
```

--------------------------------

### Initialize JitterType Variants

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/retry/enum.JitterType.html

Examples of creating additive and multiplicative jitter instances.

```rust
use hammerwork::retry::JitterType;
use std::time::Duration;

// Add ±2 seconds of randomness
let additive = JitterType::Additive(Duration::from_secs(2));

// Add ±20% randomness to the delay
let multiplicative = JitterType::Multiplicative(0.2);
```

--------------------------------

### Initialize and run a Hammerwork worker

Source: https://docs.rs/hammerwork

Demonstrates setting up a database connection, defining a job handler, and starting a worker pool to process jobs.

```rust
use hammerwork::{Job, Worker, WorkerPool, JobQueue, Result, worker::JobHandler, queue::DatabaseQueue};
use serde_json::json;
use std::sync::Arc;

#[tokio::main]
async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    // Setup database connection (requires PostgreSQL or MySQL)
    let pool = sqlx::PgPool::connect("postgresql://localhost/hammerwork").await?;
     
    let queue = Arc::new(JobQueue::new(pool));
     
    // Note: Run database migrations first using `cargo hammerwork migrate`
    // or use the migration manager programmatically

    // Create job handler
    let handler: JobHandler = Arc::new(|job: Job| {
        Box::pin(async move {
            println!("Processing job: {:?}", job.payload);
            // Your job processing logic here
            Ok(())
        })
    });

    // Create and start worker
    let worker = Worker::new(queue.clone(), "default".to_string(), handler);
    let mut pool = WorkerPool::new();
    pool.add_worker(worker);

    // Enqueue a job
    {
        use hammerwork::queue::DatabaseQueue;
        let job = Job::new("default".to_string(), json!({"task": "send_email"}));
        queue.enqueue(job).await?;
    }

    // Start processing jobs
    Ok(pool.start().await?)
}
```

--------------------------------

### Arc Unwrap Example (Unique Reference)

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/worker/type.JobHandler.html

Demonstrates unwrapping an Arc when it holds the unique reference, avoiding a clone.

```rust
use std::sync::Arc;
use std::ptr;

let inner = String::from("test");
let ptr = inner.as_ptr();

let arc = Arc::new(inner);
let inner = Arc::unwrap_or_clone(arc);
// The inner value was not cloned
assert!(ptr::eq(ptr, inner.as_ptr()));
```

--------------------------------

### Constructing ArchiveEvent Instances

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/archive/enum.ArchiveEvent.html

Examples of how to instantiate specific ArchiveEvent variants for job archival and bulk operations.

```rust
use hammerwork::archive::{ArchiveEvent, ArchivalReason, ArchivalStats};
use uuid::Uuid;
use chrono::Utc;

// Job archived event
let job_archived = ArchiveEvent::JobArchived {
    job_id: Uuid::new_v4(),
    queue: "email_queue".to_string(),
    reason: ArchivalReason::Automatic,
};

// Bulk operation started
let operation_id = "bulk_op_123".to_string();
let bulk_started = ArchiveEvent::BulkArchiveStarted {
    operation_id: operation_id.clone(),
    estimated_jobs: 1000,
};
```

--------------------------------

### Example JobLifecycleEvent Creation

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/events/struct.JobLifecycleEvent.html

Demonstrates how to create a JobLifecycleEvent instance with various fields populated, including a completed event with payload and metadata. Ensure all necessary imports are included.

```rust
use hammerwork::events::{JobLifecycleEvent, JobLifecycleEventType};
use hammerwork::priority::JobPriority;
use uuid::Uuid;
use chrono::Utc;
use std::collections::HashMap;

let event = JobLifecycleEvent {
    event_id: Uuid::new_v4(),
    job_id: Uuid::new_v4(),
    queue_name: "email_queue".to_string(),
    event_type: JobLifecycleEventType::Completed,
    priority: JobPriority::Normal,
    timestamp: Utc::now(),
    processing_time_ms: Some(1500),
    error: None,
    payload: Some(serde_json::json!({"recipient": "user@example.com"})),
    metadata: {
        let mut meta = HashMap::new();
        meta.insert("tenant_id".to_string(), "acme_corp".to_string());
        meta
    },
};
```

--------------------------------

### Arc Unwrap Example (Non-Unique Reference)

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/worker/type.JobHandler.html

Demonstrates unwrapping an Arc when it does not hold the unique reference, resulting in a clone.

```rust
use std::sync::Arc;
use std::ptr;

let inner = String::from("test");
let ptr = inner.as_ptr();

let arc = Arc::new(inner);
let arc2 = arc.clone();
let inner = Arc::unwrap_or_clone(arc);
// Because there were 2 references, we had to clone the inner value.
assert!(!ptr::eq(ptr, inner.as_ptr()));
// `arc2` is the last reference, so when we unwrap it we get back
// the original `String`.
let inner = Arc::unwrap_or_clone(arc2);
assert!(ptr::eq(ptr, inner.as_ptr()));
```

--------------------------------

### Get Job Processing Duration

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/job/struct.Job.html

Calculates the time a job spent processing, from start to finish or current running time. Returns None if the job has not yet started.

```rust
use hammerwork::Job;
use serde_json::json;
use chrono::Utc;

let mut job = Job::new("test".to_string(), json!({"data": "test"}));

// Job hasn't started, so no processing duration
assert!(job.processing_duration().is_none());

// Simulate job that started and completed
let start_time = Utc::now() - chrono::Duration::seconds(10);
let end_time = start_time + chrono::Duration::seconds(5);
job.started_at = Some(start_time);
job.completed_at = Some(end_time);

let duration = job.processing_duration().unwrap();
assert_eq!(duration.num_seconds(), 5);
```

--------------------------------

### Integrate Hammerwork with Application Database

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/migrations/index.html

Example of connecting to a migrated database and enqueuing a job using the JobQueue.

```rust
use hammerwork::{Job, JobQueue, queue::DatabaseQueue};
use serde_json::json;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Database schema is already set up by cargo hammerwork migrate
    let pool = sqlx::PgPool::connect("postgresql://localhost/hammerwork").await?;
    let queue = Arc::new(JobQueue::new(pool));
     
    // Start using immediately
    let job = Job::new("queue".to_string(), json!({"task": "work"}));
    queue.enqueue(job).await?;
    Ok(())
}
```

--------------------------------

### Configure ArchivalPolicy

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/archive/struct.ArchivalPolicy.html

Example of setting multiple archival retention periods using the builder pattern.

```rust
use hammerwork::archive::ArchivalPolicy;
use chrono::Duration;

// Archive completed jobs after 7 days, failed jobs after 30 days
let policy = ArchivalPolicy::new()
    .archive_completed_after(Duration::days(7))
    .archive_failed_after(Duration::days(30))
    .purge_archived_after(Duration::days(365));
```

--------------------------------

### Example Usage of ArchivedJob

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/archive/struct.ArchivedJob.html

Demonstrates how to create an instance of ArchivedJob and perform assertions on its fields. Requires hammerwork, chrono, and uuid crates.

```rust
use hammerwork::archive::{ArchivedJob, ArchivalReason};
use hammerwork::{JobId, JobStatus};
use chrono::Utc;
use uuid::Uuid;

let job_id = Uuid::new_v4();
let now = Utc::now();

let archived_job = ArchivedJob {
    id: job_id,
    queue_name: "email_queue".to_string(),
    status: JobStatus::Completed,
    created_at: now,
    archived_at: now,
    archival_reason: ArchivalReason::Automatic,
    original_payload_size: Some(1024),
    payload_compressed: true,
    archived_by: Some("scheduler".to_string()),
};

assert_eq!(archived_job.queue_name, "email_queue");
assert_eq!(archived_job.status, JobStatus::Completed);
assert_eq!(archived_job.archival_reason, ArchivalReason::Automatic);
assert!(archived_job.payload_compressed);
```

--------------------------------

### Create and Configure Basic Webhook

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/webhooks/struct.WebhookConfig.html

Demonstrates how to create a basic webhook configuration using `WebhookConfig::new` and set HTTP method and headers using builder methods.

```rust
use hammerwork::webhooks::{WebhookConfig, WebhookAuth, HttpMethod, RetryPolicy};
use hammerwork::events::{EventFilter, JobLifecycleEventType};
use hammerwork::priority::JobPriority;
use std::collections::HashMap;

// Basic webhook configuration
let webhook = WebhookConfig::new(
    "payment_webhook".to_string(),
    "https://api.example.com/webhooks/payments".to_string(),
)
.with_method(HttpMethod::Post)
.with_header("Content-Type".to_string(), "application/json".to_string())
.with_header("X-API-Version".to_string(), "v1".to_string());
```

--------------------------------

### Job Creation and Basic Usage

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/job/struct.Job.html

Demonstrates how to create a new Job instance and perform basic checks.

```APIDOC
## Job Creation and Basic Usage

### Description
This example shows how to instantiate a `Job` with a name and an empty JSON payload, and then check if it should clean up encrypted data.

### Method
N/A (Example usage)

### Endpoint
N/A (Library code)

### Request Example
```rust
use hammerwork::Job;
use serde_json::json;

let job = Job::new("test".to_string(), json!({}));
assert!(!job.should_cleanup_encrypted_data());
```

### Response
N/A (Example usage)
```

--------------------------------

### Create a started event

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/events/trait.JobLifecycleEventBuilder.html

Use this method to create a job lifecycle event indicating that a job has begun processing.

```rust
fn started(
        job_id: Uuid,
        queue_name: String,
        priority: JobPriority,
    ) -> JobLifecycleEvent;
```

--------------------------------

### Initialize Archival Policy and Configuration

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/archive/index.html

Demonstrates setting up archival policies and storage configurations for use with the job queue archival methods.

```rust
use hammerwork::archive::{ArchivalPolicy, ArchivalConfig, ArchivalReason};
use chrono::Duration;

// Create an archival policy
let policy = ArchivalPolicy::new()
    .archive_completed_after(Duration::days(7))
    .archive_failed_after(Duration::days(30))
    .purge_archived_after(Duration::days(365))
    .compress_archived_payloads(true);

let config = ArchivalConfig::new().with_compression_level(9);
let reason = ArchivalReason::Automatic;

// These can be used with queue.archive_jobs() method
assert!(policy.enabled);
assert_eq!(config.compression_level, 9);
```

--------------------------------

### Start Prometheus Exposition Server

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/metrics/struct.PrometheusMetricsCollector.html

Starts the HTTP server for exposing Prometheus metrics. This method is asynchronous.

```rust
pub async fn start_exposition_server(&mut self) -> Result<()>
```

--------------------------------

### Create Started Event

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/events/struct.JobLifecycleEvent.html

Use this builder function to create a JobLifecycleEvent representing a job that has started processing.

```rust
fn started( job_id: Uuid, queue_name: String, priority: JobPriority, ) -> JobLifecycleEvent
```

--------------------------------

### Basic Event Publishing and Subscription

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/events/index.html

Demonstrates initializing an EventManager, creating a subscription with a filter, and publishing a completion event.

```rust
use hammerwork::events::{EventManager, EventFilter, JobLifecycleEvent, JobLifecycleEventType, JobLifecycleEventBuilder};
use hammerwork::priority::JobPriority;
use uuid::Uuid;

// Create an event manager
let event_manager = EventManager::new_default();

// Subscribe to completion events
let filter = EventFilter::new()
    .with_event_types(vec![JobLifecycleEventType::Completed]);
let mut subscription = event_manager.subscribe(filter).await?;

// Create and publish an event
let event = JobLifecycleEvent::completed(
    Uuid::new_v4(),
    "email_queue".to_string(),
    JobPriority::Normal,
    1500, // processing time in ms
);
event_manager.publish_event(event).await?;

// The subscription is ready to receive events
// In a real application, you would receive events in a loop:
// let received_event = subscription.receiver.recv().await?;
assert_eq!(subscription.filter.event_types.len(), 1);
```

--------------------------------

### Check if Job Should Timeout

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/job/struct.Job.html

Determines if a job has exceeded its configured timeout duration based on its start time. Ensure the job has a timeout set and has started to accurately assess this.

```rust
use hammerwork::Job;
use serde_json::json;
use std::time::Duration;
use chrono::Utc;

let mut job = Job::new("test".to_string(), json!({"data": "test"}))
    .with_timeout(Duration::from_secs(30));

// Job hasn't started yet, so it shouldn't timeout
assert!(!job.should_timeout());

// Simulate job starting 45 seconds ago
job.started_at = Some(Utc::now() - chrono::Duration::seconds(45));

// Job should timeout since 45s > 30s timeout
assert!(job.should_timeout());
```

--------------------------------

### Initialize a new Job

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/job/struct.Job.html

Demonstrates how to create a new Job instance using the Job::new constructor and verify its cleanup configuration.

```rust
use hammerwork::Job;
use serde_json::json;

let job = Job::new("test".to_string(), json!({}));
assert!(!job.should_cleanup_encrypted_data());
```

--------------------------------

### WebhookManager Initialization

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/webhooks/struct.WebhookManager.html

Demonstrates how to create and configure a new WebhookManager instance.

```APIDOC
## WebhookManager Initialization

### Description
Initializes a new `WebhookManager` with a given `EventManager` and configuration.

### Method
`WebhookManager::new`

### Parameters
- **event_manager** (`Arc<EventManager>`) - Required - An asynchronous runtime event manager.
- **config** (`WebhookManagerConfig`) - Required - Configuration for the webhook manager.

### Request Example
```rust
use hammerwork::webhooks::{WebhookManager, WebhookManagerConfig};
use hammerwork::events::EventManager;
use std::sync::Arc;

let event_manager = Arc::new(EventManager::new_default());
let config = WebhookManagerConfig {
    max_concurrent_deliveries: 20,
    max_response_body_size: 64 * 1024,
    log_deliveries: true,
    default_timeout_secs: 30,
    user_agent: "MyApp/1.0".to_string(),
};
let webhook_manager = WebhookManager::new(event_manager, config);
```

### Response
- **WebhookManager** - The newly created webhook manager instance.
```

```APIDOC
## WebhookManager Initialization (Default Configuration)

### Description
Initializes a new `WebhookManager` with a given `EventManager` and default configuration.

### Method
`WebhookManager::new_default`

### Parameters
- **event_manager** (`Arc<EventManager>`) - Required - An asynchronous runtime event manager.

### Request Example
```rust
use hammerwork::webhooks::WebhookManager;
use hammerwork::events::EventManager;
use std::sync::Arc;

let event_manager = Arc::new(EventManager::new_default());
let webhook_manager = WebhookManager::new_default(event_manager);
```

### Response
- **WebhookManager** - The newly created webhook manager instance with default settings.
```

--------------------------------

### Get Mutable Reference to Arc Data

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/worker/type.JobHookHandler.html

Safely get a mutable reference to the data inside an Arc if it's the unique owner. Returns None if other Arc or Weak pointers exist.

```rust
use std::sync::Arc;

let mut x = Arc::new(3);
*Arc::get_mut(&mut x).unwrap() = 4;
assert_eq!(*x, 4);

let _y = Arc::clone(&x);
assert!(Arc::get_mut(&mut x).is_none());
```

--------------------------------

### GET /throttle-configs

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/queue/trait.DatabaseQueue.html

Retrieves all current throttle configurations.

```APIDOC
## GET /throttle-configs

### Description
Retrieves a map of all throttle configurations currently defined in the system.

### Method
GET

### Response
#### Success Response (200)
- **configs** (HashMap<String, ThrottleConfig>) - A map of throttle names to their respective configurations.
```

--------------------------------

### Initialize and Configure WebhookManager

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/webhooks/struct.WebhookManager.html

Demonstrates creating a WebhookManager instance, configuring it with custom settings, adding a filtered webhook, and retrieving delivery statistics.

```rust
use hammerwork::webhooks::{WebhookManager, WebhookConfig, WebhookManagerConfig, HttpMethod};
use hammerwork::events::{EventManager, EventFilter, JobLifecycleEventType};
use std::sync::Arc;

// Create webhook manager
let event_manager = Arc::new(EventManager::new_default());
let config = WebhookManagerConfig {
    max_concurrent_deliveries: 20,
    max_response_body_size: 64 * 1024,
    log_deliveries: true,
    default_timeout_secs: 30,
    user_agent: "MyApp/1.0".to_string(),
};
let webhook_manager = WebhookManager::new(event_manager, config);

// Add a webhook
let webhook = WebhookConfig::new(
    "completion_notifier".to_string(),
    "https://api.example.com/job-completed".to_string(),
)
.with_filter(
    EventFilter::new()
        .with_event_types(vec![JobLifecycleEventType::Completed])
);

webhook_manager.add_webhook(webhook).await?;

// Get delivery statistics
let stats = webhook_manager.get_stats().await;
println!("Active webhooks: {}", stats.active_webhooks);
```

--------------------------------

### Arc::weak_count

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/worker/type.JobHandlerWithResult.html

Gets the number of Weak pointers to this allocation.

```APIDOC
## GET /weak_count

### Description
Gets the number of `Weak` pointers to this allocation.

### Method
GET

### Endpoint
`Arc::weak_count(this: &Arc<T, A>) -> usize`

### Safety
This method by itself is safe, but using it correctly requires extra care. Another thread can change the weak count at any time, including potentially between calling this method and acting on the result.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

### Request Body
None

### Request Example
```rust
use std::sync::Arc;

let five = Arc::new(5);
let _weak_five = Arc::downgrade(&five);

// This assertion is deterministic because we haven't shared
// the `Arc` or `Weak` between threads.
assert_eq!(1, Arc::weak_count(&five));
```

### Response
#### Success Response (200)
- **usize** - The number of weak pointers.

#### Response Example
(See Request Example for usage)
```

--------------------------------

### Basic Job Creation

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/job/struct.Job.html

Demonstrates how to create a new `Job` instance with a queue name and a JSON payload.

```APIDOC
### Basic Job Creation

```rust
use hammerwork::Job;
use serde_json::json;

let job = Job::new("email_queue".to_string(), json!({
    "to": "user@example.com",
    "subject": "Welcome!",
    "body": "Thanks for signing up"
}));

assert_eq!(job.queue_name, "email_queue");
assert_eq!(job.max_attempts, 3); // Default retry attempts
```
```

--------------------------------

### GET /get_workflow_status

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/queue/trait.DatabaseQueue.html

Retrieve the status and statistics for a specific workflow.

```APIDOC
## GET /get_workflow_status

### Description
Get workflow status and statistics.

### Method
GET

### Parameters
#### Query Parameters
- **workflow_id** (WorkflowId) - Required - The unique identifier of the workflow.

### Response
#### Success Response (200)
- **status** (Option<JobGroup>) - The status and statistics of the workflow if found.
```

--------------------------------

### Initialize ResultStorage Options

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/job/enum.ResultStorage.html

Demonstrates how to instantiate the different ResultStorage variants. Use Database for persistent storage, Memory for faster but non-persistent results, and None to disable storage.

```rust
use hammerwork::job::ResultStorage;

// Store results in the database
let db_storage = ResultStorage::Database;

// Store results in memory (faster but not persistent)
let memory_storage = ResultStorage::Memory;

// Don't store results (default behavior)
let no_storage = ResultStorage::None;
```

--------------------------------

### GET capacity

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/archive/type.ArchivalPolicyId.html

Returns the current capacity of the String in bytes.

```APIDOC
## GET capacity

### Description
Returns this String's capacity, in bytes.

### Method
GET

### Endpoint
/capacity

### Response
#### Success Response (200)
- **capacity** (usize) - The number of bytes the string can hold without reallocating.
```

--------------------------------

### Basic Usage of SpawnManager

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/spawn/struct.SpawnManager.html

Demonstrates implementing a SpawnHandler, registering it with the SpawnManager, and verifying handler registration.

```rust
use hammerwork::spawn::SpawnManager;
use async_trait::async_trait;
use serde_json::json;
use hammerwork::{Job, spawn::{SpawnHandler, SpawnContext}};
use std::sync::Arc;

struct SimpleSpawner;

#[async_trait]
impl<DB: sqlx::Database + Send + Sync> SpawnHandler<DB> for SimpleSpawner {
    async fn spawn_jobs(&self, context: SpawnContext<DB>) -> hammerwork::Result<Vec<Job>> {
        let count = context.parent_job.payload["count"].as_u64().unwrap_or(1) as usize;
        let mut jobs = Vec::new();
        for i in 0..count {
            jobs.push(Job::new("child_task".to_string(), json!({"index": i, "parent": context.parent_job.id})));
        }
        Ok(jobs)
    }
}

// Create and configure spawn manager
let mut spawn_manager: SpawnManager<sqlx::Postgres> = SpawnManager::new();
spawn_manager.register_handler("parent_task", SimpleSpawner);

// Check if handler is registered
assert!(spawn_manager.has_handler("parent_task"));
assert!(!spawn_manager.has_handler("other_task"));

// Get registered types
let types = spawn_manager.registered_types();
assert!(types.contains(&"parent_task".to_string()));
```

--------------------------------

### Create a Job with Dependencies

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/job/struct.Job.html

Demonstrates creating jobs and establishing dependencies between them using their IDs.

```rust
use hammerwork::Job;
use serde_json::json;

let job1 = Job::new("step1".to_string(), json!({}));
let job2 = Job::new("step2".to_string(), json!({}));
let final_job = Job::new("final".to_string(), json!({}))
    .depends_on_jobs(&[job1.id, job2.id]);
assert_eq!(final_job.depends_on.len(), 2);
```

--------------------------------

### Get Correlation ID

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/job/struct.Job.html

Retrieves the correlation ID if it has been set.

```rust
use hammerwork::Job;
use serde_json::json;

let job = Job::new("test".to_string(), json!({}))
    .with_correlation_id("corr-456");

assert_eq!(job.get_correlation_id(), Some("corr-456"));
```

--------------------------------

### Get Trace ID

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/job/struct.Job.html

Retrieves the trace ID if it has been set.

```rust
use hammerwork::Job;
use serde_json::json;

let job = Job::new("test".to_string(), json!({}))
    .with_trace_id("trace-123");

assert_eq!(job.get_trace_id(), Some("trace-123"));
```

--------------------------------

### WorkerPool Construction and Configuration

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/worker/struct.WorkerPool.html

Demonstrates how to create and configure a WorkerPool, including setting up autoscaling and worker templates.

```APIDOC
## WorkerPool Construction and Configuration

### Description
This section covers the creation and configuration of the `WorkerPool` struct.

### Methods

#### `new()`
- **Description**: Creates a new `WorkerPool` instance.
- **Returns**: `Self` (a new `WorkerPool` instance).

#### `with_stats_collector(stats_collector: Arc<dyn StatisticsCollector>)`
- **Description**: Configures the `WorkerPool` to use a statistics collector.
- **Parameters**:
  - `stats_collector` (Arc<dyn StatisticsCollector>) - The statistics collector to use.
- **Returns**: `Self` (the modified `WorkerPool` instance).

#### `with_autoscaling(config: AutoscaleConfig)`
- **Description**: Configures autoscaling for the worker pool.
- **Parameters**:
  - `config` (AutoscaleConfig) - The configuration for autoscaling.
- **Returns**: `Self` (the modified `WorkerPool` instance).

#### `without_autoscaling()`
- **Description**: Disables autoscaling for the worker pool.
- **Returns**: `Self` (the modified `WorkerPool` instance).

#### `with_worker_template(worker: Worker<DB>)`
- **Description**: Sets a worker template for autoscaling. This worker will be cloned when creating new workers.
- **Parameters**:
  - `worker` (Worker<DB>) - The worker template to use.
- **Returns**: `Self` (the modified `WorkerPool` instance).

#### `add_worker(worker: Worker<DB>)`
- **Description**: Adds a worker to the pool.
- **Parameters**:
  - `worker` (Worker<DB>) - The worker to add.

### Request Example
```rust
let pool = WorkerPool::<MyDatabase>::new()
    .with_autoscaling(AutoscaleConfig { /* ... */ })
    .with_worker_template(Worker::<MyDatabase>::new());
```
```

--------------------------------

### WorkerPool Lifecycle and Management

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/worker/struct.WorkerPool.html

Details on starting, managing, and shutting down the WorkerPool.

```APIDOC
## WorkerPool Lifecycle and Management

### Description
This section covers the operational methods for the `WorkerPool`.

### Methods

#### `start()`
- **Description**: Starts the worker pool and begins processing jobs.
- **Returns**: `Result<()>` - Ok(()) on success, or an error.
- **Async**: Yes

#### `get_autoscale_metrics()`
- **Description**: Retrieves the current autoscaling metrics for the worker pool.
- **Returns**: `AutoscaleMetrics` - The current autoscaling metrics.

#### `shutdown()`
- **Description**: Shuts down the worker pool gracefully.
- **Returns**: `Result<()>` - Ok(()) on success, or an error.
- **Async**: Yes

#### `stats_collector()`
- **Description**: Gets the statistics collector for the worker pool.
- **Returns**: `Option<Arc<dyn StatisticsCollector>>` - The statistics collector if configured, otherwise None.

### Request Example
```rust
let mut pool = WorkerPool::<MyDatabase>::new();
pool.add_worker(Worker::<MyDatabase>::new());
pool.start().await?; // Start the pool

// Later, to shut down:
pool.shutdown().await?; // Shut down the pool
```

### Response Example (Success)
```rust
// For start() and shutdown(), success is indicated by Ok(())
// For get_autoscale_metrics(), returns an AutoscaleMetrics struct
// For stats_collector(), returns Option<Arc<dyn StatisticsCollector>>
```
```

--------------------------------

### Arc::strong_count

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/worker/type.JobHandlerWithResult.html

Gets the number of strong (Arc) pointers to this allocation.

```APIDOC
## GET /strong_count

### Description
Gets the number of strong (`Arc`) pointers to this allocation.

### Method
GET

### Endpoint
`Arc::strong_count(this: &Arc<T, A>) -> usize`

### Safety
This method by itself is safe, but using it correctly requires extra care. Another thread can change the strong count at any time, including potentially between calling this method and acting on the result.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

### Request Body
None

### Request Example
```rust
use std::sync::Arc;

let five = Arc::new(5);
let _also_five = Arc::clone(&five);

// This assertion is deterministic because we haven't shared
// the `Arc` between threads.
assert_eq!(2, Arc::strong_count(&five));
```

### Response
#### Success Response (200)
- **usize** - The number of strong pointers.

#### Response Example
(See Request Example for usage)
```

--------------------------------

### Create and Enqueue Job with JobQueue

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/queue/struct.JobQueue.html

Demonstrates creating a JobQueue with a PostgreSQL pool and enqueuing a new job.

```rust
use hammerwork::{JobQueue, Job, queue::DatabaseQueue};
use serde_json::json;

// Create a PostgreSQL-backed queue
let pool = sqlx::PgPool::connect("postgresql://localhost/hammerwork").await?;
let queue = JobQueue::new(pool);

// Create and enqueue a job
let job = Job::new("email_queue".to_string(), json!({"to": "user@example.com"}));
let job_id = queue.enqueue(job).await?;
```

--------------------------------

### Initialize and use EventManager

Source: https://docs.rs/hammerwork/1.15.5/hammerwork/events/struct.EventManager.html

Demonstrates creating a configured manager, subscribing with a filter, and publishing events asynchronously.

```rust
use hammerwork::events::{EventManager, EventConfig, EventFilter, JobLifecycleEvent, JobLifecycleEventType, JobLifecycleEventBuilder};
use hammerwork::priority::JobPriority;
use uuid::Uuid;
use std::sync::Arc;

// Create a manager with custom configuration
let config = EventConfig {
    max_buffer_size: 5000,
    include_payload_default: true,
    max_payload_size_bytes: 128 * 1024, // 128KB
    log_events: true,
};
let manager = Arc::new(EventManager::new(config));

// Subscribe to events
let filter = EventFilter::new()
    .with_event_types(vec![JobLifecycleEventType::Failed])
    .with_priorities(vec![JobPriority::Low]);
let mut subscription = manager.subscribe(filter).await?;

// Publish an event from another task
let manager_clone = Arc::clone(&manager);
tokio::spawn(async move {
    let event = JobLifecycleEvent::failed(
        Uuid::new_v4(),
        "background_queue".to_string(),
        JobPriority::Low,
        hammerwork::events::JobError {
            message: "Service unavailable".to_string(),
            error_type: Some("ServiceError".to_string()),
            details: None,
            retry_attempt: Some(1),
        },
    );
    let _ = manager_clone.publish_event(event).await;
});

// The subscription is ready to receive events
// In a real application, you would receive events in a loop:
// while let Ok(event) = subscription.receiver.recv().await {
//     if subscription.filter.matches(&event) {
//         println!("Job {} failed: {}", event.job_id,
//                  event.error.as_ref().unwrap().message);
//         break;
//     }
// }
assert!(subscription.filter.priorities.contains(&JobPriority::Low));
```
Tokens:
Raw