Implement Reservation Timeout With Auto-Cancellation

Hey guys! Today, let's dive deep into how we can automatically cancel pending reservations after a 10-minute timeout. This is crucial for managing resources effectively, especially in systems like booking services where holding a reservation indefinitely can lead to lost opportunities. So, let’s get started and explore the ins and outs of this implementation.

Goal

Our main goal here is to ensure that if a user reserves a slot but doesn't complete the payment within 10 minutes, the reservation should be automatically canceled. This frees up the slot for other users, thereby optimizing resource utilization. Essentially, we're looking to recover inventory in a timely manner, preventing it from being held up unnecessarily. This approach helps maintain a smooth and efficient reservation system, ensuring that resources are available to those who are ready to use them.

Acceptance Criteria (AC)

To make sure we’re on the right track, here are the criteria we need to meet:

• [ ] Automatically process to CANCELLED status if 10 minutes have passed in PENDING status.
• [ ] Periodically check with a Scheduled Job (every 1 minute).
• [ ] Automatically restore inventory upon cancellation (CANCELLED is excluded from inventory calculation).
• [ ] Maintain history using Soft Delete method.
• [ ] Log timeout time.
• [ ] Write integration tests.

Each of these points is vital for the successful implementation of our timeout mechanism. Let's break down why. First, automatically transitioning to a CANCELLED status after 10 minutes ensures timely inventory recovery. Next, a Scheduled Job running every minute allows for frequent checks, minimizing the window of opportunity for conflicts. Restoring inventory upon cancellation is crucial for accurate resource management. Using a Soft Delete method for history maintenance provides an audit trail without permanently deleting records. Logging the timeout time helps in debugging and monitoring system behavior. Finally, writing integration tests ensures that the entire system works harmoniously, validating the functionality and reliability of our solution.

Implementation Plan

Option A: Add expiresAt Field (Recommended)

The best way to handle this, in my opinion, is to add an expiresAt field. Check out this Java snippet:

// ReservationPricing Domain
private LocalDateTime expiresAt; // Only used when PENDING

public boolean isExpired() {
    return status == PENDING 
        && LocalDateTime.now().isAfter(expiresAt);
}

// Automatically set upon creation
expiresAt = calculatedAt.plusMinutes(10);

This approach introduces an expiresAt field within the ReservationPricing domain, which is only relevant when the reservation status is PENDING. The isExpired() method checks whether the current time has exceeded the expiresAt time. This makes it super straightforward to determine if a reservation has timed out. When a reservation is created, the expiresAt field is automatically set to 10 minutes after the reservation's calculated time (calculatedAt). This ensures that every pending reservation has a built-in expiration timestamp, making the timeout process both efficient and reliable. By encapsulating this logic within the domain, we keep our code clean and maintainable, and the expiration check becomes a natural part of the reservation object's behavior.

Scheduled Job

Now, let's set up a Scheduled Job to periodically check for expired reservations:

@Scheduled(fixedDelay = 60000) // Every 1 minute
public void cancelExpiredReservations() {
    List<ReservationPricing> expired = 
        repository.findExpiredPendingReservations();
    
    expired.forEach(reservation -> {
        reservation.cancel(); // CANCELLED → Automatic inventory recovery
        repository.save(reservation);
        logger.info("Expired reservation cancelled: {}", 
            reservation.getReservationId());
    });
}

Here, we use Spring's @Scheduled annotation to create a job that runs every minute (fixedDelay = 60000). This job fetches all expired pending reservations from the repository and then cancels each one. The reservation.cancel() method not only updates the reservation status to CANCELLED but also triggers the automatic inventory recovery process. After canceling the reservation, we save the updated state back to the repository. The logger.info() statement provides a clear audit trail, logging the cancellation of each expired reservation along with its ID. This scheduled task ensures that our system regularly checks for and handles expired reservations, maintaining the efficiency of our reservation system.

Repository Method

We’ll need a way to query for these expired reservations. Add this to your repository:

List<ReservationPricing> findExpiredPendingReservations();
// WHERE status = 'PENDING' AND expiresAt < NOW()

This repository method, findExpiredPendingReservations(), is crucial for fetching all pending reservations that have exceeded their expiration time. The underlying SQL query (WHERE status = 'PENDING' AND expiresAt < NOW()) ensures that we only retrieve reservations that are both in the PENDING state and have an expiresAt timestamp earlier than the current time. This targeted query optimizes performance by minimizing the data processed, and it's a key part of the data access layer. By abstracting this query into the repository, we keep our service layer clean and focused on business logic. This method allows our scheduled job to efficiently identify and process expired reservations, ensuring timely inventory recovery.

Technical Considerations

Before we roll this out, let’s think about a few technical bits:

• @EnableScheduling configuration
• Transaction handling
• Concurrency issue considerations (review optimistic locking)
• Cancellation history tracking with logging
• Optionally clean up old CANCELLED reservations with a batch job later

These considerations are crucial for ensuring the robustness and reliability of our implementation. First, @EnableScheduling is necessary to activate Spring's scheduling capabilities, allowing our scheduled job to run. Transaction handling ensures that database operations are performed atomically, preventing partial updates and maintaining data integrity. Concurrency issues need careful attention, especially if multiple threads or processes might access the same reservations simultaneously; optimistic locking can help prevent conflicts. Logging cancellation history provides an audit trail, making it easier to track and debug issues. Finally, while not immediately necessary, a batch job to clean up old CANCELLED reservations can help maintain database performance over time. By addressing these technical aspects, we can build a scalable and maintainable system for handling reservation timeouts.

Implementation Order

Here’s how we’ll roll this out:

1. Domain: Add expiresAt field and isExpired() method
2. Repository: Add query to find expired reservations
3. Service: Implement Scheduled Job
4. Config: Activate @EnableScheduling
5. Test: Write timeout scenario tests

This step-by-step approach ensures a systematic and organized implementation process. First, we enhance the ReservationPricing domain by adding the expiresAt field and the isExpired() method. This lays the foundation for tracking reservation expirations. Next, we add a query to the repository to efficiently retrieve expired reservations, optimizing database interactions. Then, we implement the Scheduled Job in the service layer, which orchestrates the process of finding and canceling expired reservations. After that, we activate @EnableScheduling in our configuration to enable the scheduled task. Finally, we write comprehensive tests to validate the timeout scenario, ensuring the correctness and reliability of our solution. By following this order, we can incrementally build and test our feature, reducing the risk of integration issues and ensuring a smooth deployment.

Related Issues

This is related to #4 and #87. Always good to keep track of related issues to ensure everything's connected!

So there you have it, folks! Implementing a timeout for pending reservations is a smart move for any reservation-based system. It keeps things running smoothly and ensures resources are used efficiently. Keep coding, and stay awesome!