Add Support for Differentiating Cached and Regular Responses in Idempotency Handling for Accurate Metrics

[fernando-mendonca1]

Is your feature request related to a problem? Please describe.

In the Account Security team at Booking, we rely on the Java Powertools library's idempotency support to manage both idempotent and non-idempotent downstream API calls. This functionality is crucial for ensuring that our security remediations are executed without unintended duplication or unnecessary load on our systems.

However, there is currently no mechanism to distinguish between a regular response and one that has been cached and returned by the Powertools library. While this behavior is technically correct and functions as intended, it presents a challenge when it comes to accurately tracking business metrics. Specifically, if we are unable to differentiate between regular and cached responses, our count of successful executions becomes inaccurate. This discrepancy impacts our projects on a business level, as we depend on these metrics to monitor key goals and milestones effectively.

Describe the solution you'd like

We propose two potential solutions, in decreasing order of preference:

1. Callback Method for Response Manipulation: Introduce support for manipulating responses through a callback method during idempotency configuration. This would allow us to modify the response object to include additional information indicating whether it was served from cache.

Idempotency.config().withPersistenceStore(
  DynamoDBPersistenceStore.builder()
    .withTableName(System.getenv("TABLE_NAME"))
    .withEventHandler(subscriptionResult -> {
      return new SubscriptionResult(subscriptionResult.getPaymentId(), "noop", 200);
    })
    .build()
).configure();

2. Key-Value Pair in Cached Responses: Allow the specification of a key-value pair that would be appended to cached responses. This would provide a straightforward way to identify cached responses in our metrics.

Idempotency.config().withPersistenceStore(
  DynamoDBPersistenceStore.builder()
    .withTableName(System.getenv("TABLE_NAME"))
    .withCachedResponseKey("x-idempotent-key")
    .withCachedResponseValue("true")
    .build()
).configure();

Implementing either of these solutions would bring the Java implementation in line with the capabilities already available in the Python version of Powertools, which supports response manipulation as documented here: Powertools Python Documentation.

Describe alternatives you've considered

• Moving the @Idempotent Annotation: Shifting the annotation to a secondary method rather than the handler method was deemed unviable, as idempotency execution is independent of the method itself.

• Custom Idempotency Annotation: Creating a custom annotation that inherits from Powertools was rejected due to the increased complexity in maintenance and the need to track upstream changes continuously.

• Implementing Functionality In-House: Developing similar functionality within our project using DynamoDB would lead to duplication of existing features and an increased maintenance burden, which we aim to avoid.

[phipag]

Hey @fernando-mendonca1, thank you for your detailed feature request and for describing your use-case in so much detail. This is awesome! 🚀

We have recently published our roadmap for 2025 and feature parity between the Java library and Powertools libraries in other languages is something we are planning to work on. I believe that your feature request fits well in this context.

There was already some work done regarding a new major version release and I can image that the feature you described could become part of this (see v2 branch). In v2, the idempotency module was already refactored into multiple submodules where the DynamoDB persistency layer is no longer coupled to the core idempotency logic: #1467.

Regarding your proposed options (1 and 2), I believe both the response hook solution as well as your withCachedResponse proposal should be independent of the persistence layer. Instead of being part of the DynamoDBPersistenceStore.build()... they should be part of the IdempotencyConfig. To sketch roughly how a response hook could look like (Option 1 in your proposal):

Idempotency.config()
        .withPersistenceStore(
                DynamoDBPersistenceStore.builder()
                        .withTableName(System.getenv("TABLE_NAME"))
                        .build())
        // Make it part of IdempotencyConfig rather than persistence store
        .withConfig(
                IdempotencyConfig.builder()
                        .withEventKeyJMESPath("messageId")
                        // Logic to manipulate original response can be added here
                        .withResponseHook((response, idempotentData) -> {
                            return new SubscriptionResult(response.getPaymentId(), "noop", 200);
                        })
                        .build())
        .configure();

I will triage your request further with the Powertools team.

In the meantime, some questions:

• Would a response hook similar to Powertools in Python help solve your use-case?
• Would you be interested in working on this feature and contributing it to Powertools in Java?

[phipag]

Hey @fernando-mendonca1, we will pick this up for version 2.0.0 of Powertools.

I prefer the response hook option since it is similar to the Python and TypeScript implementation. @hjgraca I assume you will go for the response hook option in .NET as well?

@fernando-mendonca1, let me know what you think.