FINERACT-1420: Improve idempotency fallback using deterministic key generation

[elnafateh]

Description

This PR improves the existing idempotency mechanism by enhancing the fallback behavior when no idempotency key is provided by the client.

Currently, when a request is sent without an idempotency key, the system generates a random key, which breaks retry safety in real-world scenarios (e.g. network failures). Retried requests are treated as new operations, leading to potential duplicate processing.

This change introduces deterministic idempotency key generation based on a canonical representation of the request payload combined with a time window.

Key Points

• Does NOT replace the existing idempotency mechanism
• Retains DB-level uniqueness constraint as final safeguard
• Ensures consistent retry behavior without requiring client-provided keys
• Maintains backward compatibility (no migration required)

Trade-offs

Semantically identical requests within the same time window may be deduplicated unintentionally. This is a design trade-off to ensure retry safety.

Scope

This change aligns with FINERACT-1420 by improving API fault tolerance and preventing duplicate request execution.

This contribution is part of my preparation for Google Summer of Code and aims to improve reliability in Fineract's command processing pipeline.

Checklist

Please make sure these boxes are checked before submitting your pull request - thanks!

• [x ] Write the commit message as per our guidelines
• [ x] Acknowledge that we will not review PRs that are not passing the build ("green") - it is your responsibility to get a proposed PR to pass the build, not primarily the project's maintainers.
• Create/update unit or integration tests for verifying the changes made.
• [ x] Follow our coding conventions.
• Add required Swagger annotation and update API documentation at fineract-provider/src/main/resources/static/legacy-docs/apiLive.htm with details of any API changes
• [ x] This PR must not be a "code dump". Large changes can be made in a branch, with assistance. Ask for help on the developer mailing list.

Your assigned reviewer(s) will follow our guidelines for code reviews.

[vidakovic]

Also: 2 commits... please squash into 1 according to rules. No reference to a ticket in the PR title... please follow the rules (there are not many).

[vidakovic]

I see nothing related to the "DB-level uniqueness constraint"... there is nothing mentioning the existing idempotency solution, possible side effects with this implementation, how we should migrate from one to the other, do we have to migrate at all? Looks incomplete.

[elnafateh]

Also: 2 commits... please squash into 1 according to rules. No reference to a ticket in the PR title... please follow the rules (there are not many).

I’ve made required update and then quash the commits into a single one and I’ve also added the ticket number.

[elnafateh]

I see nothing related to the "DB-level uniqueness constraint"... there is nothing mentioning the existing idempotency solution, possible side effects with this implementation, how we should migrate from one to the other, do we have to migrate at all? Looks incomplete.

Fair point — the PR description needs to be clearer.

This change does not replace the existing idempotency mechanism but enhances it by providing a fallback when no idempotency key is supplied.

• The DB-level uniqueness constraint remains unchanged and continues to act as the final safeguard.
• No migration is required since this is backward compatible.
• One trade-off is that semantically identical requests within the time window may be deduplicated unintentionally, which is a design consideration.

I will update the PR description to reflect these aspects clearly.