hammerwork 0.2.2

A high-performance, database-driven job queue for Rust with PostgreSQL and MySQL support, featuring job timeouts, dead job management, and comprehensive statistics collection
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.2.2] - 2025-06-26

### Added
- **Comprehensive Job Timeout Functionality**
  - `TimedOut` job status for jobs that exceed their timeout duration
  - Per-job timeout configuration with `Job::with_timeout()` builder method
  - Worker-level default timeouts with `Worker::with_default_timeout()`
  - Timeout detection using `tokio::time::timeout` for efficient async timeout handling
  - `timeout` and `timed_out_at` fields added to `Job` struct for complete timeout tracking
  - Automatic timeout event recording in statistics with `JobEventType::TimedOut`

- **Enhanced Database Support for Timeouts**
  - `timeout_seconds` and `timed_out_at` columns added to database schema
  - `mark_job_timed_out()` method added to `DatabaseQueue` trait
  - Complete timeout support in both PostgreSQL and MySQL implementations
  - Database queries updated to handle timeout fields in job lifecycle operations
  - Timeout counts integrated into queue statistics with `timed_out_count` field

- **Timeout Statistics and Monitoring**
  - `timed_out` field added to `JobStatistics` for timeout event tracking
  - Timeout events included in error rate calculations for comprehensive metrics
  - `timed_out_count` added to `QueueStats` for per-queue timeout monitoring
  - Enhanced statistics display in examples showing timeout metrics
  - Timeout event processing in `InMemoryStatsCollector`

- **Comprehensive Testing**
  - 14 new comprehensive tests covering timeout functionality
  - Job timeout detection logic testing with edge cases
  - Worker timeout configuration and precedence testing
  - Timeout statistics integration testing
  - Database operation interface testing for timeout methods
  - Job lifecycle testing with timeout scenarios

- **Enhanced Examples**
  - Updated PostgreSQL example with timeout configuration demonstrations
  - Updated MySQL example with various timeout scenarios (10s, 60s, 600s)
  - Job timeout precedence examples (job-specific vs worker defaults)
  - Priority-based timeout configuration examples (VIP vs standard jobs)
  - Comprehensive timeout statistics display in both examples

### Technical Implementation
- Timeout precedence: job-specific timeout takes priority over worker default timeout
- Graceful timeout handling: jobs are marked as `TimedOut` without affecting other jobs
- Async timeout detection: uses `tokio::time::timeout` for efficient resource management
- Database consistency: timeout information persisted and retrievable across job lifecycle
- Statistics integration: timeout events fully integrated into existing statistics framework

## [0.2.1] - 2025-06-25

### Removed
- Removed the `full` feature flag that enabled both PostgreSQL and MySQL simultaneously
  - Users typically choose one database backend per application
  - Simplifies the feature set and reduces unnecessary dependencies
  - Available features are now: `postgres`, `mysql`

## [0.2.0] - 2025-06-25

### Added
- **Comprehensive Statistics Tracking**
  - `JobStatistics` struct with detailed metrics (throughput, processing times, error rates)
  - `StatisticsCollector` trait for pluggable statistics backends
  - `InMemoryStatsCollector` with time-windowed data collection and configurable cleanup
  - `QueueStats` for queue-specific insights
  - `DeadJobSummary` for dead job analysis with error patterns
  - `JobEvent` system for tracking job processing lifecycle events
  - Integration with `Worker` and `WorkerPool` for automatic statistics collection

- **Dead Job Management**
  - Enhanced `Job` struct with `failed_at` field and `Dead` status
  - Dead job utility methods: `is_dead()`, `has_exhausted_retries()`, `age()`, `processing_duration()`
  - Database operations for dead job management:
    - `mark_job_dead()` - Mark jobs as permanently failed
    - `get_dead_jobs()` - Retrieve dead jobs with pagination
    - `get_dead_jobs_by_queue()` - Queue-specific dead job retrieval
    - `retry_dead_job()` - Reset dead jobs for retry
    - `purge_dead_jobs()` - Clean up old dead jobs
    - `get_dead_job_summary()` - Summary statistics with error patterns

- **Database Enhancements**
  - Extended `DatabaseQueue` trait with 15 new methods for statistics and dead job management
  - Enhanced database schemas with `failed_at` column and performance indexes
  - Complete feature parity between PostgreSQL and MySQL implementations
  - Optimized queries with proper indexing for performance

- **Testing & Examples**
  - 32 comprehensive unit tests with full coverage of new features
  - Updated examples demonstrating statistics collection and dead job management
  - Enhanced integration tests with 4 new test scenarios:
    - Dead job management lifecycle
    - Statistics collection functionality
    - Database queue statistics
    - Error frequency analysis

### Changed
- Updated package description to highlight new statistics and dead job management features
- Enhanced API with backward-compatible design

## [0.1.0] - 2025-06-25

### Added
- **Core Job Queue Infrastructure**
  - `Job` struct with UUID, payload, status, retry logic, and scheduling
  - Job statuses: `Pending`, `Running`, `Completed`, `Failed`, `Retrying`
  - Support for delayed job execution with configurable retry attempts
  - `JobQueue<DB>` generic struct with database connection pooling

- **Worker System**
  - `Worker<DB>` for processing jobs from specific queues
  - Configurable polling intervals, retry delays, and maximum retries
  - `WorkerPool<DB>` for managing multiple workers with graceful shutdown
  - Async channels for coordinated shutdown signaling

- **Database Support**
  - `DatabaseQueue` trait defining interface for database operations
  - Full PostgreSQL implementation with `FOR UPDATE SKIP LOCKED` for efficient job polling
  - Full MySQL implementation with transaction-based locking
  - Database-agnostic design using SQLx for compile-time query verification

- **Error Handling & Observability**
  - `HammerworkError` enum with structured error handling using `thiserror`
  - Comprehensive error wrapping for SQLx, serialization, and custom errors
  - Integrated tracing support for observability

- **Database Schema**
  - Optimized `hammerwork_jobs` table design for both PostgreSQL and MySQL
  - Proper indexing for efficient queue polling and job management
  - JSON/JSONB payload support with metadata tracking

- **Testing & Integration**
  - Comprehensive Docker-based integration testing infrastructure
  - Support for both PostgreSQL and MySQL in CI/CD pipelines
  - Shared test scenarios for database-agnostic testing
  - Complete test coverage with realistic job processing scenarios

- **Configuration & Features**
  - Feature flags: `postgres`, `mysql` for selective database support
  - Workspace configuration for consistent dependency management
  - Production-ready configuration with performance optimizations

### Technical Details
- Built on Tokio with async/await throughout the codebase
- Uses database transactions for atomic job state changes
- Type-safe job handling with `Result<()>` error propagation
- SQLx for compile-time query checking and database abstraction
- Generic over database types using `sqlx::Database` trait

---

## Release Links
- [0.2.2](https://github.com/CodingAnarchy/hammerwork/releases/tag/v0.2.2)
- [0.2.1](https://github.com/CodingAnarchy/hammerwork/releases/tag/v0.2.1)
- [0.2.0](https://github.com/CodingAnarchy/hammerwork/releases/tag/v0.2.0)
- [0.1.0](https://github.com/CodingAnarchy/hammerwork/releases/tag/v0.1.0)

## Contributing
Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.

## License
This project is licensed under the MIT License - see the [LICENSE-MIT](LICENSE-MIT) file for details.