Namastack Outbox v0.2.0

🎉 Major Architectural Improvements

Version 0.2.0 introduces a complete architectural overhaul that transforms how the Outbox pattern scales across multiple instances. We've replaced distributed locking with hash-based partitioning, delivering significant performance improvements and true horizontal scalability.

🚀 Key Features

Hash-based Partitioning

• 🎯 Consistent Hashing: Each aggregate maps to the same partition using MurmurHash3
• ⚡ Lock-Free Design: Eliminates distributed lock overhead and deadlock risks
• 📈 Linear Scaling: Performance scales directly with instance count
• 🔄 Automatic Rebalancing: Partitions redistribute automatically when instances join/leave
• 🛡️ Ordering Guarantee: Maintains strict event ordering per aggregate
• 256 Fixed Partitions: Provides fine-grained load distribution

Instance Coordination

• 💓 Heartbeat System: Automatic detection of healthy/failed instances
• 🔍 Dynamic Discovery: New instances automatically join the cluster
• ⚖️ Load Balancing: Even distribution of partitions across all instances
• 🛑 Graceful Shutdown: Clean partition handover during instance shutdown

Multi-Database Support

• 🗄️ Programmatic Transactions: Replaced @Transactional with TransactionTemplate
• 🔧 Multi-Persistence Units: Support for multiple database configurations
• ⚙️ Configurable Transaction Managers: Custom transaction template support

🔧 Technical Improvements

Performance Enhancements

• ⚡ Eliminated Lock Contention: No more distributed lock overhead
• 🚀 Optimized Queries: New database indexes for partition-based queries
• 📊 Batch Processing: Efficient partition-aware record processing
• 🎯 Reduced Latency: Direct partition assignment without lock acquisition

🔄 Migration from v0.1.0

Simple Migration (Recommended)

-- Stop all instances, then drop and recreate tables
DROP TABLE IF EXISTS outbox_record;
DROP TABLE IF EXISTS outbox_lock;  -- If exists from v0.1.0

-- Tables will be recreated automatically with new schema

Custom Migration

For production environments requiring data preservation, contact the maintainer for migration assistance.

⚠️ Breaking Changes

Removed Features

• Distributed Locking: Completely replaced with hash-based partitioning
• Lock Tables: outbox_lock table no longer needed
• Lock Configuration: All lock-related configuration options removed

Changed Behavior

• Record Structure: OutboxRecord now includes partition information
• Processing Logic: Events processed based on partition assignment
• Scaling Model: Horizontal scaling through partitions instead of locks
• Transaction Management: Switched from declarative to programmatic transactions

Updated Dependencies

• Spring Boot: 3.0+ required
• Java: 21+ required
• Kotlin: 2.2+ required

📈 Performance Improvements

Real-world Impact

• Multiple Instances: Seamless scaling from 1 to N instances
• Load Distribution: Even workload distribution across instances
• Failure Recovery: Sub-second partition reassignment on instance failure
• Resource Usage: Reduced CPU and memory overhead

🙏 Acknowledgments

Special thanks to the community for feedback and testing that made this release possible. The architectural improvements in v0.2.0 lay the foundation for even better performance and scalability in future releases.

@AZapata27 @icepuma @wimdeblauwe

📚 Resources

• 📖 Documentation: outbox.namastack.io
• 🔧 Migration Guide: See README.md for detailed migration instructions
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

---

Download: GitHub Releases
Maven Central: io.namastack:namastack-outbox-starter-jpa:0.2.0

v0.1.0

Namastack Outbox for Spring Boot 0.1.0 - Initial Release 🎉

We're excited to announce the first release of Namastack Outbox for Spring Boot, a robust Spring Boot library that implements the Outbox Pattern for reliable message publishing in distributed systems.

🌟 What is Namastack Outbox for Spring Boot?

Namastack Outbox for Spring Boot ensures that domain events are published reliably, even in the face of system failures, by using transactional guarantees and distributed locking. This library solves the common problem of ensuring consistency between database operations and message publishing in microservices architectures.

✨ Key Features

🔄 Transactional Outbox Pattern

• Ensures events are never lost by storing them in the same database transaction as your business data
• Guarantees eventual consistency between database state and published events

🔒 Distributed Locking

• Prevents concurrent processing of the same aggregate across multiple application instances
• Uses optimistic locking to handle race conditions safely

🔁 Automatic Retry Mechanism

• Multiple configurable retry policies with exponential backoff
• Jitter support to prevent thundering herd problems
• Automatic retry scheduling for failed events

📊 Event Ordering Guarantees

• Ensures event processing order per aggregate
• Maintains consistency in event sequence for domain aggregates

⚡ High Performance & Scalability

• Optimized for high-throughput scenarios
• Supports multiple application instances running concurrently
• Efficient database queries with proper indexing

🛡️ Production Ready

• Zero message loss guarantee through database-backed reliability
• Race condition safe implementation
• Comprehensive error handling and logging

📦 Available Modules

Core Modules

• namastack-outbox-core - Core outbox pattern implementation
• namastack-outbox-jpa - JPA/Hibernate integration for database operations

Integration Modules

• namastack-outbox-starter-jpa - Spring Boot starter for easy setup
• namastack-outbox-actuator - Spring Boot Actuator endpoints for monitoring
• namastack-outbox-metrics - Metrics and observability support

🚀 Quick Start

Get started with Namastack Outbox for Spring Boot in minutes! Follow our comprehensive Quick Start Guide for step-by-step setup instructions.

📋 Requirements

• Java: 21 or higher
• Spring Boot: 3.x
• Database: Any JPA-supported database (PostgreSQL, MySQL, H2, etc.)

🗄️ Database Schema

The library automatically creates two essential tables:

• outbox_record - Stores events to be processed
• outbox_lock - Manages distributed locking per aggregate

📊 Monitoring & Observability

• Spring Boot Actuator endpoints for health checks and metrics
• Built-in metrics for processed events, failures, and retry attempts
• Comprehensive logging for debugging and monitoring

🎯 Use Cases

Perfect for:

• Microservices architectures requiring reliable event publishing
• Event-driven systems needing guaranteed event delivery
• Domain Driven Design implementations with domain events
• CQRS patterns where commands need to publish events reliably
• Saga patterns requiring reliable event coordination

📚 Documentation & Examples

• 📖 Documentation: outbox.namastack.io
• 💻 Example Project: Check out namastack-outbox-examples/namastack-outbox-basic-example
• 🔧 Configuration Reference: Complete configuration options in the docs

🤝 Community & Support

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Contact: Namastack

⚖️ License

Apache License 2.0 - see LICENSE file for details.

---

Ready to get started? Check out our Quick Start guide and join the community!

Maven Central: All artifacts are available on Maven Central under the io.namastack group.